SLiCAPmath.py

SLiCAP module with extended matrix class and SLiCAP math functions.

Imported by the module SLiCAPprotos.py.

assumePosParams(expr, params='all')

Returns the sympy expression ‘expr’ in which variables, except the Laplace variable, have been redefined as real.

Parameters:
  • expr (sympy.Expr, sympy.Symbol) – Sympy expression
  • params (list, str) – List with variable names (str), or ‘all’ or a variable name (str).
Returns:

Expression with redefined variables.
Return type:

sympy.Expr, sympy.Symbol
assumeRealParams(expr, params='all')

Returns the sympy expression ‘expr’ in which variables, except the Laplace variable, have been redefined as real.

Parameters:
  • expr (sympy.Expr, sympy.Symbol) – Sympy expression
  • params (list, str) – List with variable names (str), or ‘all’ or a variable name (str).
Returns:

Expression with redefined variables.
Return type:

sympy.Expr, sympy.Symbol
cancelPZ(poles, zeros)

Cancels poles and zeros that coincide within the displayed accuracy.

Note:

The display accuracy (number of digits) is defined by ini.disp.

Parameters:
  • poles (list) – List with poles (float) of a Laplace rational function.
  • zeros (list) – List with zeros (float) of a Laplace rational function.
Returns:

Tuple with a list with poles (float) and a list with zeros (float).
checkNumber(var)

Returns a number with its value represented by var, or None if var does not represent a number.

Parameters:var (str, sympy object, int, float) – Variable that may represent a number.
Returns:Numeric value (int, float) or None
Return type:int, float, bool
clearAssumptions(expr, params='all')

Returns the sympy expression ‘expr’ in which the assumtions ‘Real’ and ‘Positive’ have been deleted.

Parameters:
  • expr (sympy.Expr, sympy.Symbol) – Sympy expression
  • params (list, str) – List with variable names (str), or ‘all’ or a variable name (str).
Returns:

Expression with redefined variables.
Return type:

sympy.Expr, sympy.Symbol
coeffsTransfer(LaplaceRational)

Returns a nested list with the coefficients of the Laplace variable of the numerator and of the denominator of ‘LaplaceRational’.

The coefficients are in ascending order.

Parameters:LaplaceRational (sympy.Expr) – Rational function of the Laplace variable.
Returns:Tuple with gain and two lists: [gain, numerCoeffs, denomCoeffs]
  1. gain (sympy.Expr): ratio of the nonzero coefficient of the lowest order of the numerator and the coefficient of the nonzero coefficient of the lowest order of the denominator.
  2. numerCoeffs (list): List with all coeffcients of the numerator in ascending order.
  3. denomCoeffs (list): List with all coeffcients of the denominator in ascending order.
Return type:tuple
dBmagFunc_f(LaplaceExpr, f)

Calculates the dB magnitude at the real frequency f (Fourier) from the univariate function ‘LaplaceExpr’ of the Laplace variable.

If ini.Hz == true, the Laplace variable will be replaced with 2*sp.pi*sp.I*ini.frequency.

If ini.Hz == False, the Laplace variable will be replaced with sp.I*ini.frequency.

Parameters:
  • LaplaceExpr (sympy.Expr) – Univariate function of the Laplace variable.
  • f – Frequency value (float), or a numpy array with frequency values (float).
Returns:

dB Magnitude at the specified frequency, or list with dB magnitudes at the specified frequencies.
Return type:

float, numpy.array
delayFunc_f(LaplaceExpr, f, delta=0.0001)

Calculates the group delay at the real frequency f (Fourier) from the univariate function ‘LaplaceExpr’ of the Laplace variable.

If ini.Hz == true, the Laplace variable will be replaced with 2*sp.pi*sp.I*ini.frequency.

If ini.Hz == False, the Laplace variable will be replaced with sp.I*ini.frequency.

Parameters:
  • LaplaceExpr (sympy.Expr) – Univariate function of the Laplace variable.
  • f – Frequency value (float), or a numpy array with frequency values (float).
Returns:

Group delay at the specified frequency, or list with group delays at the specified frequencies.
Return type:

float, numpy.array
findServoBandwidth(loopgainRational)

Determines the intersection points of the asymptotes of the magnitude of the loopgain with unity.

Parameters:loopgainRational – Rational function of the Laplace variable, that represents the loop gain of a circuit.
Returns:Dictionary with key-value pairs:
  • hpf: frequency of high-pass intersection
  • hpo: order at high-pass intersection
  • lpf: frequency of low-pass intersection
  • lpo: order at low-pass intersection
  • mbv: mid-band value of the loopgain (highest value at order = zero)
  • mbf: lowest freqency of mbv
Return type:dict
fullSubs(valExpr, parDefs)

Returns ‘valExpr’ after all parameters of ‘parDefs’ have been substituted into it recursively until no changes occur or until the maximum number of substitutions is achieved.

The maximum number opf recursive substitutions is set by ini.maxRexSubst.

Parameters:
  • valExpr (sympy.Expr, sympy.Symbol, int, float) – Eympy expression in which the parameters should be substituted.
  • parDefs –

    Dictionary with key-value pairs:

    • key (sympy.Symbol): parameter name
    • value (sympy object, int, float): value of the parameter
Returns:

Expression or value obtained from recursive substitutions of parameter definitions into ‘valExpr’.
Return type:

sympy object, int, float
invLaplace(numer, denom)

Calculates the Inverse Laplace Transform of a numerical rational expression of which the sympy polynomials of the numerator and the denominator are passed as arguments, respecively.

ToDo: This function is not used because of observed problems with residues at dominant pole-zero pairs. Instead maxILT() is used, which also supports the symbolic inverse Laplace Transform.

Parameters:
  • numer (sympy.Expr) – Univariate function of the Laplace variable.
  • denom (sympy.Expr) – Univariate function of the Laplace variable.
Returns:

Inverse Laplace transform of numer/denom.
Return type:

sympy.Expr
magFunc_f(LaplaceExpr, f)

Calculates the magnitude at the real frequency f (Fourier) from the univariate function ‘LaplaceExpr’ of the Laplace variable.

If ini.Hz == true, the Laplace variable will be replaced with 2*sp.pi*sp.I*ini.frequency.

If ini.Hz == False, the Laplace variable will be replaced with sp.I*ini.frequency.

Parameters:
  • LaplaceExpr (sympy.Expr) – Univariate function of the Laplace variable.
  • f – Frequency value (float), or a numpy array with frequency values (float).
Returns:

Magnitude at the specified frequency, or list with magnitudes at the specified frequencies.
Return type:

float, numpy.array
mag_f(LaplaceExpr)

Returns the magnitude as a function of the real frequency f (Fourier) from the Laplace function ‘LaplaceExpr’.

If ini.Hz == true, the Laplace variable will be replaced with 2*sp.pi*sp.I*ini.frequency.

If ini.Hz == False, the Laplace variable will be replaced with sp.I*ini.frequency.

Parameters:
  • LaplaceExpr (sympy.Expr) – Univariate function of the Laplace variable.
  • f – Frequency value (float), or a numpy array with frequency values (float).
Returns:

Sympy expression representing the magnitude of the Fourier Transform.
Return type:

sympy.Expr
makeLaplaceRational(gain, zeros, poles)

Creates a Laplace rational from a gain factor, a list of zeros and a list of poles:

\[F(s) = gain \frac{ \prod_j(s-z_j)} {\prod_i(s-p_i)}\]

Terms with complex conjugated poles or zeros will be combined into quadratic terms.

The gain factor should be taken as

This function is used for evaluation of the inverse Laplace transform of rational functions in the Laplace variable ‘s’ with Maxima CAS.

Parameters:
  • gain (int, float, sympy.Symbol, sympy.Expr) – The ratio of the coefficients of the highest order of the Laplace variable of the numerator and the denominator; this is not the DC gain!
  • zeros – List with solutions of the Laplace variable of the numerator of \(F(s)\).
  • poles – List with solutions of the Laplace variable of the denominator of \(F(s)\).
Returns:

\(F(s)\)
Return type:

sympy.Expr
class matrix(M)

SLiCAP matrix class for symbolic calculations.

This class is an extension to the sympy Matrix class. It calculates determinants using minor expansion. This is slow for large matrices.

SLiCAP uses Maxima CAS for calculation of determinants.

Return types for matrices are <class ‘sympy.matrices.matrices.Matrix’>.

Adapted from: from “Bill McNeill <billmcn@speakeasy.net>”

Added

  • Test for matrix element == zero, speeds up calculation of sparse matrices.

Removed

  • Checks for square matrices: the matrix generated by SLiCAP is square.

Modified

  • Updated to the latest version of sympy.
Cramer(colVector, colNumber)

Returns matrix with colVector substituted in column colNumber

adjugate()

Returns the adjugate (transposed cofactor matrix) matrix of M.

coFactor(i, j)

Returns cofactor C(i,j).

coFactorMatrix()

Returns the cofactor matrix of M.

determinant()

Returns determinant of a 2 x 2 matrix.

dot(M2)

Returns the dot product of two matrices M1 and M2

dotV(Vr, Vc)

Returns the dot product of row vector Vr and column vector Vc.

expandByMinorsCols()

Calculates (sub)determinant by expansion of minors.

expandByMinorsRows()

Calculates (sub)determinant by expansion of minors.

inverse()

Returns inverse matrix of M

minor(i, j)

Returns determinant of M after deleting row i and column j.

normalizeLaplaceRational(LaplaceRational)

Normalizes a Laplace rational to:

\[F(s) = gain\,s^{\ell} \frac{1+b_1s + ... + b_ms^m}{1+a_1s + ... + a_ns^n}\]
Parameters:LaplaceRational (sympy.Expr) – Rational function of the Laplace variable.
Returns:Normalized rational function of the Laplace variable.
Return type:sympy.Expr
numRoots(expr, var)

Returns the roots of the polynomial ‘expr’ with indeterminate ‘var’.

This function uses numpy for calculation of numeric roots.

Note:

See: https://docs.scipy.org/doc/numpy/reference/generated/numpy.polynomial.polynomial.polyroots.html

Parameters:
  • expr (sympy.Expr) – Univariate function.
  • var (sympy.Symbol) – Indeterminate of ‘expr’.
phaseFunc_f(LaplaceExpr, f)

Calculates the phase angle at the real frequency f (Fourier) from the univariate function ‘LaplaceExpr’ of the Laplace variable.

If ini.Hz == true, the Laplace variable will be replaced with 2*sp.pi*sp.I*ini.frequency.

If ini.Hz == False, the Laplace variable will be replaced with sp.I*ini.frequency.

Parameters:
  • LaplaceExpr (sympy.Expr) – Univariate function of the Laplace variable.
  • f – Frequency value (float), or a numpy array with frequency values (float).
Returns:

Angle at the specified frequency, or list with angles at the specified frequencies.
Return type:

float, numpy.array
phaseMargin(LaplaceExpr)

Calculates the phase margin assuming a loop gain definition according to the asymptotic gain model.

This function uses scipy.newton() for determination of the the unity-gain frequency. It uses the function SLiCAPmath.findServoBandwidth() for the initial guess, and ini.disp for the relative accuracy.

if ini.Hz == True, the units will be degrees and Hz, else radians and radians per seconds.

Parameters:LaplaceExpr (sympy.Expr, list) – Univariate function (sympy.Expr*) or list with univariate functions (sympy.Expr*) of the Laplace variable.
Returns:Tuple with phase margin (float) and unity-gain frequency (float), or Tuple with lists with phase margins (float) and unity-gain frequencies (float).
Return type:tuple
phase_f(LaplaceExpr)

Calculates the magnitude as a function of the real frequency f (Fourier) from the Laplace function ‘LaplaceExpr’.

If ini.Hz == true, the Laplace variable will be replaced with 2*sp.pi*sp.I*ini.frequency.

If ini.Hz == False, the Laplace variable will be replaced with sp.I*ini.frequency.

Parameters:
  • LaplaceExpr (sympy.Expr) – Univariate function of the Laplace variable.
  • f – Frequency value (float), or a numpy array with frequency values (float).
Returns:

Sympy expression representing the phase of the Fourier Transform.
Return type:

sympy.Expr
polyCoeffs(expr, var)

Returns a list with coefficients of ‘var’ in descending order.

Parameters:
  • expr (sympy.Expr) – Sympy expression
  • var (sympy.Symbol) – Indeterminate of the polynomial.
Returns:

List with coefficients (sympy.Expr) in descending order.
Return type:

list
simplify(expr, method='fraction')

Simplifies an expression. Simplification methods can be:

  1. fraction: The expression will be rewritten as a normal fraction, (also common fraction or simple fraction)
  2. normalize: The expression will be rewritten as a normal fraction, (also common fraction or simple fraction) in which the coefficient of the lowest order of ini.frequency or ini.laplace of the numerator and the denominatior are normalized to unity, while this rational is multiplied with the ratio of these coefficients.
  3. factor: The expression is rewritten as a product of factors.
  4. expand: The expression is expanded into a sum of normal fractions.
Param:expr: sympy expression
Returns:simplified expression
Return type:sympy.Expr