Lcapy: symbolic linear circuit analysis with Python

Expressions

Lcapy has a number of pre-defined variables associated with different domains: f for the Fourier (frequency) domain, F for the normalized Fourier domain, s for the Laplace (s) domain, t for the time domain, omega for the angular Fourier domain, and Omega for the normalized angular Fourier domain. These variables can be utilised to create expressions or to specify the result domain for transformations, for example¹:

>>> from lcapy import s, t, exp

>>> H = s * (s + 2)/ (s + 3) * exp(-2 * s)

>>> H(t)

$3e^{6-3t}u\left(t-2\right)-\delta \left(t-2\right)+{\delta }^{\left(1\right)}\left(t-2\right)\mathrm{f}\mathrm{o}\mathrm{r}t\ge 0.$

Here δ(t) is the Dirac delta and δ⁽¹⁾(t) is the first derivative of the Dirac delta. As a consequence of the unilateral Laplace transform, the result is only known for t ≥ 0. However, if the result is known to be zero for t < 0, this can be specified by asserting the causal argument, for example:

>>> from lcapy import s, t, exp

>>> H = s * (s + 2) / (s + 3) * exp(-2 * s)

>>> H(t, causal = True)

$3e^{6-3t}u\left(t-2\right)-\delta \left(t-2\right)+{\delta }^{\left(1\right)}\left(t-2\right).$

Lcapy can display expressions in a number of forms. In each case the expressions are factored into a rational function and an optional exponential function (the latter is used to support Laplace-domain delays):

(1) $$H(s)={\displaystyle \frac{N(s)}{D(s)}\exp (-sT).}$$

Rational functions can be represented in many forms. Table 1 shows the representations that Lcapy supports.

Some of the other methods that can be applied to Laplace-domain expressions include: initial_value(), final_value(), differentiate(), integrate(), delay(), zeros(), poles(), residues(), transient_response(), frequency_response(), and step_response(). For example:

>>> from lcapy import s

>>> V = s**3 / ((s + 3) * (s + 4))

>>> V.poles()

$\left\{-3:1,-4:1\right\}.$

This dictionary indicates a pair of real poles, each with a single occurrence.

Discrete-time expressions

Lcapy also has a number of pre-defined variables associated with discrete-time signals: k for the discrete-frequency sample index, n for the discrete-time sample index, and z for the z-transform domain. These can be used to compose discrete-time signals, for example:

>>> from lcapy import delta, n

>>> x = delta(n) + 2 * delta(n - 2)

>>> x.seq()

$\left[1,0,2\right]$and

>>> from lcapy import delta, n, z

>>> x = delta(n) + 2 * delta(n - 2)

>>> x(z)

$$1+{\displaystyle \frac{2}{z^2}.}$$

Sequences

Discrete-time, discrete-Fourier, and Z-domain expressions can be converted to and from sequences. These can be convolved, shifted, transformed, etc. For example,

>>> from lcapy import symbols, delta, n

>>> a, b = symbols(’a b’)

>>> x = a * delta(n - 1) + b * delta(n - 2)

>>> x.seq()

$\left\{\underset{\_}{0},a,b\right\},$

where the underscore marks the origin. Similarly, sequences can be converted to expressions:

>>> seq((1, 2, 3, ’a’)).expr

$$a\delta \left[n-3\right]+\delta \left[n\right]+3\delta \left[n-2\right]+2\delta \left[n-1\right].$$

One-port networks

Networks can be constructed by connecting one-port (two-terminal) and two-port components. Basic one-port components include: Vdc (DC voltage source), Idc (DC current source), Vac (AC voltage source), Iac (AC current source), R, G, C, and L. These are augmented by V (generic voltage source), I (generic current source), Y (generic admittance), and Z (generic impedance). More esoteric components include gyrators and constant phase elements.

Here is an example that combines an 8 V source in series with a parallel combination of 6 ohm and 3 ohm resistors:

>>> from lcapy import V, R

>>> net = V(8) + (R(6) | R(3))

>>> net

$V(8)+(R(6)|R(3)).$

Note, Lcapy overloads the Python | operator to denote a parallel operation. Also note that when the net object is printed, the underlying components forming the network are shown. This is achieved using an abstract syntax tree to represent the component connections.

A network can be simplified:

>>> net.simplify()

$V(8)+R(2)$and transformed into its Norton or Thévenin equivalent:

>>> net.norton()

$$G(1/2)|I(4).$$

Attributes of one-port networks include: Isc—short-circuit current; Voc—open-circuit voltage; Y—generalized admittance; and Z—generalized impedance.

Two-port networks

Two-port networks can be created from one-port components using ladder descriptions (Khanshan (2007)), primitive two-ports (Shunt, Series, LSection, TSection, TwinTSection, BridgedTSection, PiSection, Ladder, GeneralTxLine, LosslessTxLine, TxLine), or by combinations of two-ports using series(), parallel(), and chain() methods. Furthermore, they can be generated from a netlist. For example, the filter shown in Figure 1 can be represented as a two-port using:

>>> from lcapy import TSection, L, C, R

>>> a = TSection(C(’C’), L(’L’), R(’R’))

The same network can be constructed by chaining series and shunt elements:

>>> from lcapy import Series, Shunt, L, C, R

>>> a = Series(C(’C’)).chain(Shunt(L(’L’))).chain(Series(R(’R’)))

A two-port object has methods for generating A (chain) parameters, B (inverse chain) parameters, G (inverse hybrid) parameters, H (hybrid) parameters, S (scattering) parameters, T (transmission) parameters, Y (admittance) parameters, and Z (impedance) parameters (Hayt, Kemmerly & Durbin, 2006). For the above example, the Z parameters can be found using:

>>> a.Zparams

$$\left[\begin{array}{cc}-Ls\left(-1-{\displaystyle \frac{1}{CL{s}^2}}\right)& Ls\\ Ls& -Ls\left(-1-{\displaystyle \frac{R}{Ls}}\right)\end{array}\right].$$

A unique feature of Lcapy is polyphase two-port networks. These use block-matrix forms for the parameter matrices and are useful for modelling power systems. They have methods for converting to symmetrical sequence components.

Netlists

More complex circuit topologies are best described using netlists. The Lcapy netlist syntax is similar to that of SPICE. Usually nodes are numbered, but they can have symbolic names. The netlist can be loaded from a file or generated incrementally using the add method of the Circuit class. For example, Listing 1 describes the circuit shown in Fig. 2.

A Circuit object is collection of components and nodes. The nodes are accessed using Python’s array-indexing notation, for example,

>>> cct[2] - cct[’a7’]

Nodes have a number of attributes including: V—the voltage between the node and ground; dpY—the driving-point generalized admittance between the node and ground; dpZ—the driving-point generalized impedance between the node and ground. Thus the potential of node 2 with respect to ground can be found using:

>>> cct[2].V

Components are dynamically added as attributes of the Circuit class. Thus components can be accessed using the Python’s attribute notation. For example:

>>> cct.C1

Each component has several attributes as shown in Table 2. For example, the current through the inductor L1 in the netlist described by Listing 1 is found using:

>>> from lcapy import Circuit

>>> cct = Circuit(’VRL1.sch’)

>>> cct.L1.I

$\left\{\mathrm{d}\mathrm{c}:{\displaystyle \frac{V_o}{R},\mathrm{s}:{\displaystyle \frac{{\displaystyle \frac{1}{L}{V}_s}}{s^2+{\displaystyle \frac{Rs}{L}}}}}\right\}.$

The output is a dictionary showing the superposition of a DC component and a transient-component described in the Laplace domain.

The time-domain response can be found using Python’s call notation:

>>> cct.L1.I(t)

This transforms each component of the superposition into the time domain and sums the result to give:

$V_s\left({\displaystyle \frac{1}{R}-{\displaystyle \frac{e^{-{\displaystyle \frac{Rt}{L}}}}{R}}}\right)u\left(t\right)+{\displaystyle \frac{V_o}{R}.}$

Similarly, the total Laplace-domain response can be found using:

>>> cct.L1.I(s)

$${\displaystyle \frac{{\displaystyle \frac{1}{L}{V}_s}}{s^2+{\displaystyle \frac{Rs}{L}}}+{\displaystyle \frac{V_o}{Rs}.}}$$

A common circuit analysis problem is to find the transfer function between two pairs of nodes. There are several ways this can be achieved with Lcapy. For example, consider the filter network shown in Fig. 3. First, the independent sources need to be killed and an arbitrary Laplace-domain voltage source connected across the input nodes. The transfer function is then found from the ratio of the voltage measured across the output nodes to the input voltage. An alternative approach is to use the transfer() method which implicitly kills any independent sources. For example:

>>> H = cct.transfer(1, 0, 2, 0)

>>> H.canonical()

${\displaystyle \frac{s^2}{s^2+{\displaystyle \frac{1}{CL}}}.}$

A more general approach is to generate a two-port model. For example, the Z-parameters can be found using:

>>> tp = cct.twoport(1, 0, 2, 0)

>>> tp.Zparams

$$\left[\begin{array}{cc}Ls+{\displaystyle \frac{1}{Cs}}& Ls\\ Ls& Ls+R\end{array}\right].$$

The common two-port models are supported, including the A, B, G, H, S, T, Y, and Z-parameter models (Hayt, Kemmerly & Durbin, 2006). They can be converted interchangeably provided the matrices are not singular.

Other methods of the Circuit class are shown in Table 3. These are augmented with methods for manipulating a netlist as listed in Table 4.

Nodal analysis

Lcapy can output the nodal equations by applying Kirchhoff’s current law at each node in a circuit. For example:

>>> from lcapy import Circuit

>>> cct = Circuit(’example1.sch’)

>>> na = cct.nodal_analysis()

>>> na.nodal_equations()

$\{1:v_1(t)=v(t),$

$2:{\displaystyle \frac{-v_1(t)+v_2(t)}{R_1}+{\displaystyle \frac{\underset{-\mathrm{\infty }}{\overset{t}{\int }}\left(v_2(\tau )-v_3(\tau )\right)d\tau }{L}=0,}}$

$3:C{\displaystyle \frac{d}{dt}{v}_3(t)+{\displaystyle \frac{v_3(t)}{R_2}+{\displaystyle \frac{\underset{-\mathrm{\infty }}{\overset{t}{\int }}\left(-v_2(\tau )+v_3(\tau )\right)d\tau }{L}=0\}}}}$This is a dictionary keyed by the circuit node names.

The nodal equations can be formulated in the Laplace-domain using the laplace() method to convert the circuit. For example:

>>> na = cct.laplace().nodal_analysis()

>>> na.nodal_equations()

$\{1:V_1(s)=V(s),$

$2:{\displaystyle \frac{-V_1(s)+V_2(s)}{R_1}+{\displaystyle \frac{V_2(s)-V_3(s)}{Ls}=0,}}$

$3:Cs{V}_3(s)+{\displaystyle \frac{V_3(s)}{R_2}+{\displaystyle \frac{-V_2(s)+V_3(s)}{Ls}=0\}.}}$

The matrix formulation can also be generated for the Laplace-domain, DC, and phasors. For example:

>>> na = cct.laplace().nodal_analysis()

>>> na.matrix_equations()

$$\left[\begin{array}{c}{V}_1(s)\\ V_2(s)\\ V_3(s)\end{array}\right]={\left(\left[\begin{array}{ccc}1& 0& 0\\ -{\displaystyle \frac{1}{R_1}}& {\displaystyle \frac{1}{R_1}+{\displaystyle \frac{1}{L{l}_{\mathrm{a}\mathrm{p}\mathrm{l}\mathrm{a}\mathrm{c}\mathrm{e}}}}}& -{\displaystyle \frac{1}{L{l}_{\mathrm{a}\mathrm{p}\mathrm{l}\mathrm{a}\mathrm{c}\mathrm{e}}}}\\ 0& -{\displaystyle \frac{1}{L{l}_{\mathrm{a}\mathrm{p}\mathrm{l}\mathrm{a}\mathrm{c}\mathrm{e}}}}& C{l}_{\mathrm{a}\mathrm{p}\mathrm{l}\mathrm{a}\mathrm{c}\mathrm{e}}+{\displaystyle \frac{1}{R_2}+{\displaystyle \frac{1}{L{l}_{\mathrm{a}\mathrm{p}\mathrm{l}\mathrm{a}\mathrm{c}\mathrm{e}}}}}\end{array}\right]\right)}^{-1}\left[\begin{array}{c}V(s)\\ 0\\ 0\end{array}\right].$$

Mesh analysis

Lcapy can output the mesh equations by applying Kirchhoff’s voltage law around each mesh loop in a circuit. For example:

>>> from lcapy import Circuit

>>> cct = Circuit(‘example1.sch’)

>>> la = cct.loop_analysis()

>>> la.mesh_equations()

$\{i_1(t):L{\displaystyle \frac{d}{dt}\left(-i_1(t)\right)-R_1{i}_1(t)+R_2\left(-i_1(t)+i_2(t)\right)+v(t)=0,}$

$i_2(t):R_2\left(-i_1(t)+i_2(t)\right)+{\displaystyle \frac{\underset{-\mathrm{\infty }}{\overset{t}{\int }}\left(-i_1(\tau )+i_2(\tau )\right)d\tau }{C}=0}\}$This is a dictionary indexed by the mesh current.

State-space analysis

State-space analysis is performed by assigning capacitor voltages and inductor currents as state variables. The state equations are found using:

>>> from lcapy import Circuit

>>> cct = Circuit(’example1.sch’).

>>> ss = cct.state_space()

>>> ss.state_equations()

$\left[\begin{array}{c}{\displaystyle \frac{d}{dt}{i}_L(t)}\\ {\displaystyle \frac{d}{dt}{v}_C(t)}\end{array}\right]=\left[\begin{array}{c}{\displaystyle \frac{1}{L}}\\ 0\end{array}\right]\left[\begin{array}{c}v(t)\end{array}\right]+\left[\begin{array}{cc}-{\displaystyle \frac{R_1}{L}}& -{\displaystyle \frac{1}{L}}\\ {\displaystyle \frac{1}{C}}& -{\displaystyle \frac{1}{C{R}_2}}\end{array}\right]\left[\begin{array}{c}{i}_L(t)\\ v_C(t)\end{array}\right].$

Similarly, the output equations are found using:

>>> ss.output_equations()

$$\left[\begin{array}{c}{v}_1(t)\\ v_2(t)\\ v_3(t)\end{array}\right]=\left[\begin{array}{c}1\\ 1\\ 0\end{array}\right]\left[\begin{array}{c}v(t)\end{array}\right]+\left[\begin{array}{cc}0& 0\\ -R_1& 0\\ 0& 1\end{array}\right]\left[\begin{array}{c}{i}_L(t)\\ v_C(t)\end{array}\right].$$

The state-space analyser can generate state-transition matrices, system transfer functions, system impulse responses, and the characteristic polynomial. For example, the characteristic polynomial for the circuit in Fig. 4 is generated by:

>>> ss.P

$${\displaystyle \frac{R_2+\left(Ls+R_1\right)\left(C{R}_{2}s+1\right)}{CL{R}_2}.}$$

Initial value problems

If any capacitor or inductor in a netlist has an initial value, the transient response is calculated as an initial value problem using Laplace transforms. The result is only valid for t ≥ 0.

Simulation

Lcapy can numerically simulate a circuit using time-stepping numerical integration. Both the trapezoidal and backward-Euler integrators are provided. Here is an example of use:

>>> from lcapy import Circuit

>>> from numpy import linspace

>>> cct = Circuit(" " "

… V 1 0 {10 * u(t)}; down

… R 1 2 5; right

… C 2 3 0.1; right

… L 3 0_3 0.5; down

… W 0 0_3; right" " ")

>>> tv = linspace(0, 1, 100)

>>> results = cct.sim(tv)

>>> ax = cct.R.v.plot(tv, label = ’analytic’)

>>> ax.plot(tv, results.R.v, ’C1–’, label=’simulated’)

>>> ax.legend()

In this example, the sim() method takes a NumPy array of time values to numerically evaluate the circuit at. The variable results is a SimulationResults object. This can be indexed by node name. It also has an attribute for each circuit component; for example, results.R1.v is a NumPy array for the time-varying voltage across R1. The plotted result is shown in Fig. 5.

Network synthesis

Networks can be created using network synthesis techniques given an impedance or admittance expression. For example:

>>> from lcapy import s, Impedance

>>> Z = Impedance((4 * s**2 + 3 * s + ’1 / 6’) / (s**2 + 2 * s / 3))

>>> Z.network()

$((C(1)+R(2))|C(3))+R(4).$Note, in this example the ratio 1/6 is placed in quotes to prevent Python converting the result to a floating point number before Lcapy converts it to a rational number. This overcomes an unfortunate side-effect of the Python parser.

Lcapy provides many network synthesis methods, including recognising the common parallel/serial combinations of resistors, inductors, and capacitors plus more generic methods such as Foster I, II and Cauer I, II (Bakshi & Bakshi, 2005).

Random networks

Networks with a random topology can generated with the random_network() function. This is useful for automated exam question generation. For example:

>>> from lcapy import random_network

>>> net = random_network(num_resistors = 4, num_voltage_sources = 1, kind = ’dc’)

This example generates a DC network with four resistors and one voltage source. The kind argument can be ac, dc, or transient. The number of parallel connections can be specified with the num_parallel argument.

Parameterization

Lcapy can parameterize a number of first-order, second-order, and third-order Laplace-domain expressions. For example:

>>> from lcapy import s

>>> H2 = 3 / (s**2 + 2 * s + 4)

>>> H2p, defs = H2.parameterize()

>>> H2p

${\displaystyle \frac{K}{{\omega }_0^2+2{\omega }_{0}s\zeta +s^2},}$where defs is a dictionary of the parameter definitions. In this case the parameter definitions are:

$\left\{\mathrm{K}:3,\mathrm{o}\mathrm{m}\mathrm{e}\mathrm{g}\mathrm{a}\mathrm{\_}0:2,\mathrm{z}\mathrm{e}\mathrm{t}\mathrm{a}:{\displaystyle \frac{1}{2}}\right\}.$

Using the dictionary of definitions, the original expression can be obtained by substituting the parameter definitions into the parameterized expression.

Systems higher than first-order can be parameterized in different ways. For example:

>>> from lcapy import s

>>> H2 = 3 / (s**2 + 2 * s + 4)

>>> H2p, defs = H2.parameterize(zeta = False)

>>> H2p

$${\displaystyle \frac{K}{{\omega }_1^2+s^2+2s{\sigma }_1+{\sigma }_1^2}.}$$

Polyphase systems

The polyphase module provides classes for handling polyphase signals. This handles conversions between line voltages and currents to phase voltages and currents. In addition, it can decompose line and phase signals into symmetrical components and vice-versa. In each case, the polyphase signals are stored as vectors. An arbitrary number of phases can be supported, although there are many attributes specifically for three-phase systems, such as Vab that returns the phase-phase voltage between the a and b phases.

Here is an example that determines the symmetrical sequence components for three-phase phase-voltages:

>>> from lcapy.polyphase import PhaseVoltageVector

>>> V = PhaseVoltageVector((’Va’, ’Vb’, ’Vc’))

>>> V.sequence()

$\left[\begin{array}{c}{\displaystyle \frac{V_a}{3}+{\displaystyle \frac{V_b}{3}+{\displaystyle \frac{V_c}{3}}}}\\ {\displaystyle \frac{V_a}{3}+{\displaystyle \frac{V_b\alpha }{3}+{\displaystyle \frac{V_c{\alpha }^2}{3}}}}\\ {\displaystyle \frac{V_a}{3}+{\displaystyle \frac{V_b{\alpha }^2}{3}+{\displaystyle \frac{V_c\alpha }{3}}}}\end{array}\right],$where α = exp(−j2π/3) for a three-phase system.

Printing

Expressions have printing methods similar to Sympy. These are summarised in Table 5². There are other methods for automatic formatting of the expression for a Jupyter notebook (Kluyver et al., 2016) or an IPython interpreter (Pérez & Granger, 2007). These include the use of MathJax (Cervone (2012)) for mathematics formatting in web browsers.

Evaluation

Expressions have an evaluate() method which accepts a NumPy array of values at which to evaluate the expression. Internally, Lcapy uses Sympy’s lambdify() function to convert the expression to executable Python code that can be efficiently evaluated.

Plotting

Expressions have a plot() method. For Laplace-domain expressions, this is a pole-zero plot. For time-domain expressions, this shows the waveform. In addition, there are specific methods for Bode and Nyquist plots. The plot() methods provide automatic labelling and use the Matplotlib library for high-quality output in a number of formats (Hunter (2007)).

Schematics

Lcapy can draw circuits specified as networks or netlists. Networks are drawn automatically using a number of layout forms, including as a ladder network. Netlists require drawing hints to describe the component orientation, size, color, etc. These hints are used to automatically position the components. LaTeX CircuiTikz (https://www.ctan.org/pkg/circuitikz) macros are output producing text-book quality schematics. Lcapy provides a script, schtex, that can convert a netlist into an image, with a number of formats such as pdf or png. This script can also manipulate the netlist, such as renumbering the nodes.

Customisation

Lcapy has a config module that can be used for customisation. For example, the printing of $\sqrt{-1}$ as i or j, aliases for functions such as the Dirac delta or Heaviside unit step, an extensible list of words used for formatting in a Roman font in LaTeX expressions, and which method Sympy uses for matrix inversion.

Expressions

Expressions are represented using one of the 170 dynamic expression classes⁴. Each of these inherit from a quantity class (voltage, current, impedance, etc.) and from a domain class (time, Laplace, Fourier, phasor, discrete-time, etc.). Attributes specify the quantity (is_voltage, is_current, etc.) and the domain (is_time_domain, is_laplace_domain, etc.).

Lcapy expressions are created from factory functions, including: expr() for general expressions, voltage(), current(), impedance(), admittance(), and transfer() (for transfer functions). For example, the expr() factory function chooses one of the expression classes listed in Table 6. Similarly, the voltage() factory function chooses one of the voltage classes, subclassed from a corresponding expression class.

There are two special superposition classes: SuperpositionCurrent and SuperpositionVoltage. These represent signals as a superposition of DC, phasor, transient, and noise signals. They collate the results from the different circuit analysis methods before conversion to the time domain, Laplace domain, etc.

All Lcapy expression classes sub-class the Expr class. This facade class provides a common interface to the myriad of Sympy expression classes. Note, Sympy represents an expression using an abstract syntax tree of expression classes (Meurer et al., 2017). For example, it includes simple singleton classes to represent common constants such as 0 or 1, the Mul class to represent the product of two sub-expressions, the Add class to represent the sum of two sub-expressions, etc.

The Expr class also tracks the units of an expression using the Sympy units sub-system with an Lcapy extension that simplifies products of units into canonical forms. Units can be printed after expressions in both standard and abbreviated forms.

Lcapy has a Matrix class to extend the Sympy Matrix class. It also has classes to extend list, tuple, and dict. These provide a unified set of methods for printing of expressions.

Numbers

Lcapy converts floating point numbers to rational numbers of arbitrary precision. This improves detection of equality between expressions and reduces the order of some rational functions.

Noise signals

Lcapy assumes noise signals are zero-mean, wide-sense stationary, Gaussian random processes. Correlations are specified by a one-sided amplitude spectral density. Each noise source is assigned a noise identifier (nid) attribute. Noise expressions with different nids are assumed to be independent and thus represent different noise realisations.

Lcapy analyses the circuit for each noise realisation independently and stores the result for each realisation separately, using a SuperpositionVoltage or SuperpositionCurrent object. For example:

>>> from lcapy import Circuit

>>> cct = Circuit(" " "

… Vn1 1 0 noise 3

… Vn2 2 1 noise 4" " ")

>>> cct[2].V

$\left\{\mathrm{n}1:3,\mathrm{n}2:4\right\}.$

In this example Vn1 defines a white Gaussian noise source with an amplitude spectral density (ASD) of 3 V $/\sqrt{\mathrm{H}\mathrm{z}}$. It has a noise identifier n1. Similarly, Vn2 defines an independent white Gaussian noise source with an ASD of 4 V $/\sqrt{\mathrm{H}\mathrm{z}}$. It has a noise identifier n2. The voltage at node 2 can be seen to be a superposition of the two noise signals. The total noise ASD at node 2 is found using the n attribute. This sums the noise components in quadrature, i.e., $\sqrt{3^2+4^2}$, since the noise components have different nids and are thus considered independent.

>>> cct[2].V.n

$$5.$$

Netlists

Netlists have a Spice-like syntax and are parsed with a custom parser. A parser based on lex-yacc (Johnson, 1975) was tried but found to give poor messages for syntax errors. Each netlist component has an optional orientation hint and drawing attributes. These are used to semi-automatically draw a schematic, using a graph-based approach to define the component positions.

Netlists are stored as ordered dictionaries. This simplifies the lookup of components by name and preserves the component order whenever a netlist is converted into another form.

Modified nodal analysis

Circuit analysis is performed using modified nodal analysis (MNA) (Ho, Ruehli & Brennan, 1975). Essentially, this analyses the circuit by solving a set of simultaneous linear equations,

(2) $$\mathbf{x}={\mathbf{A}}^{-1}\mathbf{b},$$where $\overrightarrow{x}$ is a vector of unknown nodal voltages and unknown currents through dependent voltage sources, $\overrightarrow{b}$ is a vector of the known voltage and current sources, and A is the system matrix. For example, the system of equations for the circuit shown in Fig. 2 and described by the netlist shown in Listing 1 is:

(3) $$\left[\begin{array}{c}{V}_1\\ V_2\\ I_{V_s}\\ \end{array}\right]={\left[\begin{array}{ccc}{\displaystyle \frac{1}{R}}& -{\displaystyle \frac{1}{R}}& 1\\ -{\displaystyle \frac{1}{R}}& {\displaystyle \frac{Ls+R}{LRs}}& 0\\ 1& 0& 0\end{array}\right]}^{-1}\left[\begin{array}{c}0\\ 0\\ {\displaystyle \frac{V_s}{s}}\end{array}\right].$$Here V₁ and V₂ are the unknown nodal voltages and I_Vs is the unknown current through the independent voltage source V_s. Note, since the voltage source is DC, its Laplace-domain voltage is $V_s/s$.

Lcapy uses a custom implementation of modified nodal analysis and supports controlled sources (VCCS, CCVS, etc.), opamps, gyrators, mutual inductances, transformers, and two-ports. Each component has a stamp() method that fills in the system matrices.

Transforms

Lcapy supports the Laplace and the Fourier transform, the discrete-time equivalents (the Z-transform and the discrete-time Fourier transform (DTFT)), plus the discrete Fourier transform (DFT). The inverse transforms are also supported. Where possible, Lcapy breaks an expression into terms and evaluates each term. All results are cached.

One-port components

The one-port components are sub-classed from the OnePort class. Parallel and series combinations are represented by the Par and Ser classes. Both of these combinations are also OnePort objects.

Two-port components

Two-port components are based on the TwoPortModel class. This class contains a 2 × 2 matrix of expressions for the two-port parameters. This is augmented with a vector of two voltages, two currents, or a voltage/current pair to describe the effects of independent sources within the circuit. For example, the equations describing a B-parameter two-port model are:

(9) $$\left[\begin{array}{c}{V}_2\\ -I_2\end{array}\right]=\left[\begin{array}{cc}{B}_{11}& B_{12}\\ B_{21}& B_{22}\end{array}\right]\left[\begin{array}{c}{V}_1\\ I_1\end{array}\right]+\left[\begin{array}{c}{V}_{2b}\\ I_{2b}\end{array}\right].$$Here V_2b and I_2b model the independent sources within the circuit. Similarly, the equations used to describe a Z-parameter two-port model are:

(10) $$\left[\begin{array}{c}{V}_1\\ V_2\end{array}\right]=\left[\begin{array}{cc}{Z}_{11}& Z_{12}\\ Z_{21}& Z_{22}\end{array}\right]\left[\begin{array}{c}{I}_1\\ I_2\end{array}\right]+\left[\begin{array}{c}{V}_{1z}\\ V_{2z}\end{array}\right].$$In this case, a pair of voltages (one for each port) are required to model the independent sources within the circuit, see Figs. 6 and 7.

Nodal and mesh analysis

Nodal and mesh analysis use the CircuitGraph class to convert a netlist into a graph. The Python package Networkx (Hagberg, Swart & Chult, 2008) is employed to determine the loops in the graph. Unfortunately, Networkx cannot find loops when there are parallel edges in a graph, and so Lcapy adds dummy nodes and dummy wires to avoid parallel edges (see Fig. 8).

Documentation

Documentation is stored as Restructured Text and converted to HTML/PDF using Sphinx (http://sphinx-doc.org/sphinx.pdf). On-line documentation can be found at https://lcapy.readthedocs.io. Included in the documentation are tutorials; some using Jupyter notebooks.