Struct NodalAnalysis 

pub struct NodalAnalysis { /* private fields */ }

Implementation of the nodal analysis algorithm for a nonlinear Network.

This struct holds components (mainly conversion matrices and buffers) needed to perform a modified nodal analysis of a Network. The aforementioned conversion matrices are derived within the NetworkAnalysis::new method. They are then used within the NetworkAnalysis::solve method to try and solve the problem defined by the network, its excitation and resistances. An in-depth description of the solving process is given in lib module docstring.

To get an general overview over nodal analysis, please have a look at the corresponding [Wikipedia entry]((https://en.wikipedia.org/wiki/Nodal_analysis). Some advanced features such as e.g. voltage sources or using custom Jacobians require an in-depth understanding of the method. It is therefore recommended to consult specialist literature such as [1], [2].

In comparison to the closely related mesh analysis method, which is available via the [MeshAnalysis] struct, nodal analysis is especially well suited for networks with a low number of nodes in comparison to the number of edges and few voltage sources since the number of equations which need to be solved is equal to the number of nodes minus one (see NodalAnalysis::node_count()) plus the number of voltage sources.

Examples

The docstring of NetworkAnalysis::solve as well as the lib module docstring show some examples on how to perform nodal analysis. Furthermore, a variety of examples is provided in the examples directory of the repository.

Literature

1. Schmidt, Lorenz-Peter; Schaller, Gerd; Martius, Siegfried: Grundlagen der Elektrotechnik 3 - Netzwerke. 1st edition (2006). Pearson, Munich
2. Modified nodal analysis: https://lpsa.swarthmore.edu/Systems/Electrical/mna/MNA3.html

Implementations

impl NodalAnalysis

pub fn edge_to_node(&self) -> &DMatrix<f64>

Returns a matrix describing the coupling between the edges and the equation system.

The nodal analysis method derives m system equations from the input matrix, where m is the number of nodes minus one (one of the nodes is defined as potential 0, see NodalAnalysis::zero_potential_node, hence its equation can be omitted). Together with the n edges of the underlying Network, this results in a matrix m x n which directly describes the coupling between nodes and edges:

• -1: Node is the source of the edge.
• 0: Edge is not using the node.
• 1: Node is the target of the edge.

Therefore, this matrix together with NodalAnalysis::edge_types describes the entire equation system of the nodal analysis.

pub fn edge_to_node_resistance(&self) -> &DMatrix<Vec<f64>>

Returns a conversion matrix for calculating the node resistance matrix from the edge resistances.

This conversion matrix allows calculating the system matrix (the A in A * x = b). Each element of the conversion matrix is a vector whose length is equal to that of the edge resistance vector otherwise. Pairwise multiplication of this vector with the edge resistance vector and summing the resulting vector up returns the value of the corresponding system matrix element.

Examples

use network_analysis::*;
use nalgebra::Matrix5;

/*
This creates the following network with a current source at 0
 ┌─[1]─┬─[2]─┐
[0]   [6]   [3]
 └─[5]─┴─[4]─┘
 */
let mut edges: Vec<EdgeListEdge> = Vec::new();
edges.push(EdgeListEdge::new(vec![5], vec![1], Type::Current));
edges.push(EdgeListEdge::new(vec![0], vec![2, 6], Type::Resistance));
edges.push(EdgeListEdge::new(vec![1, 6], vec![3], Type::Resistance));
edges.push(EdgeListEdge::new(vec![2], vec![4], Type::Resistance));
edges.push(EdgeListEdge::new(vec![3], vec![5, 6], Type::Resistance));
edges.push(EdgeListEdge::new(vec![4, 6], vec![0], Type::Resistance));
edges.push(EdgeListEdge::new(vec![1, 2], vec![4, 5], Type::Resistance));
let network = Network::from_edge_list_edges(&edges).expect("valid network");

/*
This network has 6 nodes -> The conversion matrix is 5x5 and each element
is a vector of length 7 (since the matrix has seven edges)
 */
let nodal_analysis = NodalAnalysis::new(&network);
let conv = nodal_analysis.edge_to_node_resistance();
assert_eq!(conv.nrows(), 5);
assert_eq!(conv.ncols(), 5);
for elem in conv.iter() {
    assert_eq!(elem.len(), 7);
}

// Use the conversion matrix to calculate the system matrix
let edge_resistances = [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0];
let mut system_matrix = Matrix5::from_element(0.0);
for (sys_elem, conv_vec) in system_matrix.iter_mut().zip(conv.iter()) {
    *sys_elem = conv_vec.iter().zip(edge_resistances.into_iter()).map(|(factor, edge_resistance)| factor / edge_resistance).sum();
}

let mut expected = Matrix5::from_element(0.0);

// Diagonals
expected[(0, 0)] = 1.0;
expected[(1, 1)] = 1.0;
expected[(2, 2)] = 2.0;
expected[(3, 3)] = 2.0;
expected[(4, 4)] = 3.0;

// Off-diagonals
expected[(0, 4)] = -1.0;
expected[(4, 0)] = expected[(0, 4)];
expected[(2, 3)] = -1.0;
expected[(3, 2)] = expected[(2, 3)];
expected[(3, 4)] = -1.0;
expected[(4, 3)] = expected[(3, 4)];
assert_eq!(system_matrix, expected);

Literature

1. Schmidt, Lorenz-Peter; Schaller, Gerd; Martius, Siegfried: Grundlagen der Elektrotechnik 3 - Netzwerke. 1st edition (2006). Pearson, Munich

pub fn unknowns_to_edge_voltage(&self) -> &DMatrix<f64>

Returns a conversion matrix from node to edge voltages. This function is mainly meant to be used in custom Jacobian implementations.

As explained in the docstring of [JacobianFunctionSignature], a custom Jacobian function receives the node voltages as an input argument. The matrix provided by this function can then be used to calculate the edge currents via matrix multiplication:

C * n = e, where C is this matrix, n is the node voltage vector and e is the edge voltage vector.

pub fn node_count(&self) -> usize

Returns the number of nodes in the network.

The equation system size is equal to this number minus one.

Examples

use network_analysis::*;

/*
This creates the following network with a voltage source at 0
 ┌─[1]─┬─[2]─┐
[0]   [6]   [3]
 └─[5]─┴─[4]─┘
 */
let mut edges: Vec<EdgeListEdge> = Vec::new();
edges.push(EdgeListEdge::new(vec![5], vec![1], Type::Voltage));
edges.push(EdgeListEdge::new(vec![0], vec![2, 6], Type::Resistance));
edges.push(EdgeListEdge::new(vec![1, 6], vec![3], Type::Resistance));
edges.push(EdgeListEdge::new(vec![2], vec![4], Type::Resistance));
edges.push(EdgeListEdge::new(vec![3], vec![5, 6], Type::Resistance));
edges.push(EdgeListEdge::new(vec![4, 6], vec![0], Type::Resistance));
edges.push(EdgeListEdge::new(vec![1, 2], vec![4, 5], Type::Resistance));
let network = Network::from_edge_list_edges(&edges).expect("valid network");

let nodal_analysis = NodalAnalysis::new(&network);
assert_eq!(nodal_analysis.node_count(), 6);

pub fn edge_count(&self) -> usize

Returns the number of edges of the underlying network.

Examples

use network_analysis::*;

/*
This creates the following network with a voltage source at 0
 ┌─[1]─┬─[2]─┐
[0]   [6]   [3]
 └─[5]─┴─[4]─┘
 */
let mut edges: Vec<EdgeListEdge> = Vec::new();
edges.push(EdgeListEdge::new(vec![5], vec![1], Type::Voltage));
edges.push(EdgeListEdge::new(vec![0], vec![2, 6], Type::Resistance));
edges.push(EdgeListEdge::new(vec![1, 6], vec![3], Type::Resistance));
edges.push(EdgeListEdge::new(vec![2], vec![4], Type::Resistance));
edges.push(EdgeListEdge::new(vec![3], vec![5, 6], Type::Resistance));
edges.push(EdgeListEdge::new(vec![4, 6], vec![0], Type::Resistance));
edges.push(EdgeListEdge::new(vec![1, 2], vec![4, 5], Type::Resistance));
let network = Network::from_edge_list_edges(&edges).expect("valid network");

let nodal_analysis = NodalAnalysis::new(&network);
assert_eq!(nodal_analysis.edge_count(), 7);

pub fn zero_potential_node(&self) -> usize

Returns the index of the node which was chosen as the “zero potential” node. This node is always the one with the most edges using it, as this results in the most zeros in the system matrix of nodal analysis, hence reducing calculation load.

Trait Implementations

impl Clone for NodalAnalysis

fn clone(&self) -> NodalAnalysis

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NodalAnalysis

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl NetworkAnalysis for NodalAnalysis

fn new(network: &Network) -> Self

Create a new MeshAnalysis or NodalAnalysis instance from the given network. Since the network has already been checked during its creation, this operation is infallible.

fn solve<'a>( &'a mut self, resistances: Resistances<'_>, current_exc: CurrentSources<'_>, voltage_src: VoltageSources<'_>, initial_edge_resistances: Option<&[f64]>, initial_edge_currents: Option<&[f64]>, jacobian: Option<&mut (dyn for<'b> FnMut(JacobianData<'b>) + 'a)>, config: &SolverConfig, ) -> Result<Solution<'a>, SolveError>

Try to solve the network for the given excitations and resistances.

fn edge_types(&self) -> &[Type]

Returns the edge types.