SLiCAPmath.py

SLiCAP module with math functions.

DIN_A(f_0=1000)

Returns DIN_A frequency weighting function (audio), normalized at f=f_0

See WiKi R_A(f): https://en.wikipedia.org/wiki/A-weighting

Parameters:

f_0 (float, int, sympy.Symbol) – Normalization frequency (frequency at which the weight = 1), defaults to 1kHz

Returns:

R_A(f): Weighting function, argument = ini.frequency

Return type:

sympy.Expr

ENG(number, scaleFactors=False)

Converts a number into a tuple with a number and exponent as power of 3 or as scale factor.

Parameters:

  • number – Anything representing a number

  • scaleFactors (Bool) – if ‘True’, scale factors ‘y’, ‘z’, ‘a’, ‘f’, ‘p’, ‘n’, ‘u’, ‘m’, ‘k’, ‘M’, ‘G’, ‘T’, and ‘P’ will be returned instead of exponents -24, -21, -18, -15, -12, -9, -6, -3, 3, 6, 9, 12, and 15, respectively.

Returns:

number, exp

Return type:

tuple:

  • number: int, float, or input type if conversion failed

  • exp: int, str (in case of scaleFactors == True), or None, if conversion failed

Example:

>>> import SLiCAP as sl
>>> import sympy as sp

>>> sl.ini.disp # number of significant digits to be diplayed
    4

>>> sl.ENG(sp.sqrt(sp.pi))
    (1.772, 0)

>>> sl.ENG(1234567890)
    (1.234, 9)

>>> sl.ENG(1234567890, scaleFactors=True)
    (1.234, 'G')

>>> sl.ENG(1.234567890E-4)
    (123.4, -6)

>>> sl.ENG(1.234567890E-4, scaleFactors=True)
    (123.4, 'u')
PdBm2V(p, r)

Returns the RMS value of the voltage that generates p dBm power in a resistor with resistance r.

Parameters:

  • p (sympy.Symbol, sympy.Expression, int, or float) – Power in dBm

  • r (sympy.Symbol, sympy.Expression, int, or float) – Resistance

Returns:

voltage

Return type:

sympy.Expression

RMS(y, x=None)

RMS value of y.

  • With x: sqrt(trapezoid(y², x) / (x[-1] - x[0])) — proper time- or frequency-domain average.

  • Without x: sqrt(mean(y²)) — RMS over the available samples.

The operation is applied along axis=-1 so 2D stepped results (shape n_steps × n_sweep) return a 1D array of length n_steps.

Parameters:

  • y (list, numpy.ndarray) – Data values.

  • x (list, numpy.ndarray, NoneType) – X-axis values (same length as last axis of y). Defaults to None.

Returns:

RMS value(s).

Return type:

float, numpy.ndarray

SUM(y, x=None)

Sum or integral of y.

  • With x: trapezoid integration along axis=-1.

  • Without x: plain numpy.sum along axis=-1.

Parameters:

  • y (list, numpy.ndarray) – Data values.

  • x (list, numpy.ndarray, NoneType) – X-axis values. Defaults to None.

Returns:

Sum or integral.

Return type:

float, numpy.ndarray

class WeightingFilter(f_type, char=None, f_c=None, B=None, order=None, ripple=None, expr=None)

Single noise weighting filter for use with noiseWeighting().

Supported filter types (f_type):

  • “lp” : low-pass, requires char, f_c, order

  • “hp” : high-pass, requires char, f_c, order

  • “ap” : all-pass, requires char, f_c, order

  • “bp” : band-pass, requires char, f_c, B, order

  • “bs” : band-stop, requires char, f_c, B, order

  • “custom” : arbitrary, requires expr (sympy expression in ini.laplace)

Supported filter characteristics (char):

  • “butterworth”

  • “bessel”

  • “chebyshev1”

Parameters:

  • f_type (str) – Filter type string (see above).

  • char (str, NoneType) – Filter characteristic (butterworth / bessel / chebyshev1).

  • f_c (float, int, NoneType) – Corner frequency [Hz].

  • B (float, int, NoneType) – Bandwidth [Hz] (band-pass / band-stop only).

  • order (int, NoneType) – Filter order.

  • ripple (float, NoneType) – Pass-band ripple [dB] (chebyshev1 only).

  • expr (sympy.Expr, str, NoneType) – Custom sympy expression in ini.laplace (custom type only).

create_expr()

Build self.expr as a Laplace-domain transfer function.

Returns:

True if successful, False on error.

Return type:

bool

XatNthY(x, y, y0, n=1)

Find the n-th x value where y crosses y0 (linear interpolation at the crossing point).

Parameters:

  • x (list, numpy.ndarray) – X-axis values (1D).

  • y (list, numpy.ndarray) – Data values (1D, same length as x).

  • y0 (float, int) – Target y value (crossing level).

  • n (int) – Which crossing to return (1 = first, 2 = second, …). Defaults to 1.

Returns:

Interpolated x at the n-th crossing, or None if fewer than n crossings are found.

Return type:

float, NoneType

YatX(y, x, x0)

Interpolate y at x = x0.

For 2D arrays (stepped results, shape n_steps × n_sweep) the interpolation is applied row-wise along the last axis and a 1D array of length n_steps is returned.

Parameters:

  • y (list, numpy.ndarray) – Data array (1D or 2D).

  • x (list, numpy.ndarray) – X-axis values (1D, same length as the last axis of y).

  • x0 (float, int) – X value at which to interpolate.

Returns:

Interpolated value(s).

Return type:

float, numpy.ndarray

apply_goal(goal_fn, x, Y)

Applies a goal function to each row of a 2-D array (pure math — the back-end trace converters only supply their data in this shape).

Parameters:

  • goal_fn (callable) – Goal function f(x, y) -> float.

  • x (numpy.ndarray) – Sweep values, shape (n_sweep,).

  • Y (numpy.ndarray) – Row-per-step data, shape (n_steps, n_sweep).

Returns:

Goal value per row, shape (n_steps,).

Return type:

numpy.ndarray

assumePosParams(expr, params='all')

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

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

besselPoly(n)

Returns a normalized Bessel polynomial of the n-th order of the Laplace variable.

Zero-frequency value = 1, -3dB frequency (magnitude = 2) is 1 rad/s.

Parameters:

n (int) – order

Returns:

Bessel polynomial of the n-th order of the Laplace variable

Return type:

sympy.Expression

butterworthPoly(n)

Returns a narmalized Butterworth polynomial of the n-th order of the Laplace variable.

Zero-frequency value = 1, -3dB frequency (magnitude = 2) is 1 rad/s.

Parameters:

n (int) – order

Returns:

Butterworth polynomial of the n-th order of the Laplace variable

Return type:

sympy.Expression

chebyshev1Poly(n, ripple)

Returns a normalized Chebyshev polynomial of the n-th order of the Laplace variable, with a ripple of <ripple> dB

Zero-frequency value = 1, -3dB frequency (magnitude = 2) is 1 rad/s.

Parameters:

n (int) – order

Returns:

Chebyshev polynomial of the n-th order of the Laplace variable

Return type:

sympy.Expression

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(rational, var=s, method='lowest')

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

The coefficients are in ascending order.

Parameters:

  • rational (sympy.Expr) – Rational function of the variable.

  • variable (sympy.Symbol) – Variable of the rational function

  • method (str) –

    Normalization method:

    • ”highest”: the coefficients of the highest order of <variable> of the denominator will be noramalized to unity.

    • ”lowest”: the coefficients of the lowest order of <variable> of the denominator will be noramalized to unity.

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

dB(data, f=None, power=False)

Decibel value of data.

  • numpy array:

    • power = False (default): 20·log₁₀|data|. Use for complex amplitudes (AC voltages/currents) and noise amplitude spectral densities (V/√Hz, A/√Hz).

    • power = True: 10·log₁₀|data|. Use for noise power spectral densities (V²/Hz, A²/Hz).

    Note: dB(np.sqrt(S_psd)) and dB(S_psd, power=True) give identical results because 20·log₁₀(√x) = 10·log₁₀(x).

    Works element-wise on 2D stepped results (shape n_steps × n_sweep).

  • sympy Laplace expression: always uses 20·log₁₀|H(j·2π·f)| via _dB_magFunc_f(); the power flag is ignored.

Parameters:

  • data (numpy.ndarray, sympy.Expr) – Complex numpy array or sympy Laplace expression.

  • f (list, numpy.ndarray, NoneType) – Frequency array [Hz], required when data is a sympy expression.

  • power (bool) – Set True when data is a power spectral density (V²/Hz). Defaults to False.

Returns:

dB values.

Return type:

numpy.ndarray, list

delay(data, f)

Group delay of data.

  • numpy array: -d(phase)/d(ω) computed via np.gradient along axis=-1. Works on 2D stepped results (shape n_steps × n_sweep).

  • sympy Laplace expression: evaluates via _delayFunc_f().

Parameters:

  • data (numpy.ndarray, sympy.Expr) – Complex numpy array or sympy Laplace expression.

  • f (list, numpy.ndarray) – Frequency array [Hz].

Returns:

Group delay [s].

Return type:

numpy.ndarray, list

det(M, method='ME')

Returns the determinant of a square matrix ‘M’ calculated using recursive minor expansion (Laplace expansion). For large matrices with symbolic entries, this is faster than the built-in sympy.Matrix.det() method.

Parameters:

  • M (sympy.Matrix) – Sympy matrix

  • method –

    Method used:

    • ME: SLiCAP Minor expansion

    • MECPP: Minor expansion by the external C++/GiNaC engine ‘slicap_det’ (see SLiCAP_GiNAC.md). The command is configured in the main configuration file [commands]; if it is not available, det() falls back to ‘ME’ (same result, computed in Python).

    • BS: deprecated (removed); redirected to ‘ME’

    • LU: Sympy built-in LU method

    • bareiss: Sympy built-in Bareis method

Returns:

Determinant of ‘M’

Return type:

sympy.Expr

doCDS(result, tau)

Returns a copy of the noise execution result with all onoise results in it multiplied with (2*sin(pi*ini.frequency*tau))^2, and deleted inoise results.

Parameters:

  • result (sympy.instruction, int, float, sympy.Expr) – sympy instruction object, or variable

  • tau (sympy.Expr, sympy.Symbol, int or float) – Time between two samples

Returns:

sympy instruction object

Return type:

sympy.instruction

equateCoeffs(protoType, transfer, noSolve=[], numeric=True)

Returns the solutions of the equation transferFunction = protoTypeFunction.

Both transfer and prototype should be Laplace rational functions. Their numerators should be polynomials of the Laplace variable of equal order and their denominators should be polynomials of the Laplace variable of equal order.

Parameters:

  • protoType (sympy.Expr) – Prototype rational expression of the Laplace variable

  • transfer

Transfer fucntion of which the parameters need to be solved. The numerator and the denominator of this rational expression should be of the same order as those of the prototype.

Parameters:

  • noSolve (list) – List with variables (str, sympy.core.symbol.Symbol) that do not need to be solved. These parameters will remain symbolic in the solutions.

  • numeric (bool) – True will convert numeric results with floats instead of rationals

Returns:

Dictionary with key-value pairs:

  • key: name of the parameter (sympy.core.symbol.Symbol)

  • value: solution of this parameter: (sympy.Expr, int, float)

Return type:

dict

filterFunc(f_char, f_type, f_order, f_low=None, f_high=None, ripple=1)

Returns a f_type prototype function based on a f_char polynomial:

  • f_char = butterworth

  • f_char = bessel

  • f_char = chebyshev1 # Chebyshev type 1 (passband ripple)

  • f_type = lp : low-pass, requires f_high

  • f_type = hp : high-pass, requires f_low

  • f_type = bp : band-pass, requires f_low and f_high

  • f_type = bs : band-stop, requires f_low and f_high

  • f_type = ap : all-pass, requires f_high

Parameters:

  • f_char (str) – filter characteristic: Butterworth or Bessel

  • f_type (str) – filter type: lp, hp, bp, bs, ap

  • f_order (str, int) – order of the filter

  • f_low (sympy.Symbol, float, int) – low-frequency -3dB corner [Hz]

  • f_high (sympy.Symbol, float, int) – high-frequency -3dB corner [Hz]

  • ripple (int, float) – pass-band ripple in [dB]

Returns:

Filter prototype function (Laplace Transform)

Return type:

sympy.Expr

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

float2rational(expr)

Converts floats in expr into rational numbers.

Parameters:

expr (sympy.Expression) – Sympy expression in which floats need to be converterd into rational numbers.

Returns:

expression in which floats have been replaced with rational numbers.

Return type:

sympy.Expression

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

goal_max(x, y)

Maximum value of y.

Parameters:

  • x (numpy.ndarray) – 1-D sweep-axis array (unused, present for uniform signature).

  • y (numpy.ndarray) – 1-D signal array.

Returns:

max(y).

Return type:

float

goal_mean(x, y)

Mean of y over x: trapz(y, x) / (x[-1] - x[0]).

Parameters:

  • x (numpy.ndarray) – 1-D sweep-axis array.

  • y (numpy.ndarray) – 1-D signal array.

Returns:

Mean value.

Return type:

float

goal_min(x, y)

Miniimum value of y.

Parameters:

  • x (numpy.ndarray) – 1-D sweep-axis array (unused, present for uniform signature).

  • y (numpy.ndarray) – 1-D signal array.

Returns:

min(y).

Return type:

float

goal_rms(x, y)

RMS of y integrated over x: sqrt(trapz(y², x) / (x[-1] - x[0])).

Suitable as a goal_fn argument to ngspice_instr2traces() (or ngspice_dict2traces()).

Parameters:

  • x (numpy.ndarray) – 1-D sweep-axis array.

  • y (numpy.ndarray) – 1-D signal array (already post-processed by trace_type).

Returns:

RMS value.

Return type:

float

goal_x_at_max_y(x, y)

x value at which y is maximum

Parameters:

  • x (numpy.ndarray) – 1-D sweep-axis array.

  • y (numpy.ndarray) – 1-D signal array.

Returns:

x at maximum y.

Return type:

float

goal_x_at_min_y(x, y)

x value at which y is minimum.

Parameters:

  • x (numpy.ndarray) – 1-D sweep-axis array.

  • y (numpy.ndarray) – 1-D signal array.

Returns:

x at minimum y.

Return type:

float

goal_x_at_nth_y(y0, n=1)

Return a goal function that gives the x of the n-th crossing of y = y0 (linear interpolation between the samples around the crossing; n counts from 1). Returns x[-1] (end of sweep) when fewer than n crossings exist.

Parameters:

  • y0 (float) – The y level whose crossing is sought.

  • n (int) – Which crossing (1 = first).

Returns:

goal_fn(x, y) callable.

Return type:

callable

goal_y_at_x(x0)

Return a goal function that interpolates y at x = x0.

Parameters:

x0 (float) – Target x value.

Returns:

goal_fn(x, y) callable.

Return type:

callable

Example:

>>> # Value of v(out) at f = 1 kHz across all steps
>>> traces = sl.ngspice_instr2traces(AC1, goal_fn=sl.goal_y_at_x(1e3))
groupDelay(frequency, realPart, imagPart, Hz=True)

Returns the group delay of a sampled complex frequency response:

\[\tau_g = -\frac{ d \varphi }{ d \omega }\]

where the phase \(\varphi\) (radians) is obtained from the real and imaginary parts and unwrapped before differentiation, and \(\omega\) is the radian frequency. The finite-difference derivative shortens the array by one point; the last point is duplicated so the returned array has the same length as frequency.

Parameters:

  • frequency (list, numpy.ndarray) – Frequency values, in Hz (Hz=True, default) or in rad/s (Hz=False). Must be monotonic.

  • realPart (list, numpy.ndarray) – Real part of the response at each frequency.

  • imagPart (list, numpy.ndarray) – Imaginary part of the response at each frequency.

  • Hz (bool) – True if frequency is in Hz; the values are then multiplied with \(2 \pi\) before differentiation. Defaults to True.

Returns:

Group delay in seconds at each frequency; same length as frequency.

Return type:

numpy.ndarray

ilt(expr, s, t, integrate=False)

Returns the Inverse Laplace Transform f(t) of an expression F(s) for t > 0.

Parameters:

  • expr (Sympy expression, integer, float, or str.) – Function of the Laplace variable F(s).

  • s (sympy.Symbol) – Laplace variable

  • t (sympy.Symbol) – time variable

  • integrate (Bool) – True multiplies expr with 1/s, defaults to False

Returns:

Inverse Laplace Transform f(t)

Return type:

sympy.Expr

integrate_monomial_coeffs(expr, variables, x, x_lower, x_upper, doit=True, wf=1, method='auto', CDS=False, tau=None, points=1000, numeric=True)

Returns expr in which x in coefficients of monomials of variables are integrated over the range x_lower … x_upper. If doit=True the integration will be performed, else integral operators will be returned.

Parameters:

  • expr – Sympy expression

  • variables (list with sympy.Symbol objects) – List or tuple with variables (currently only two variables accepted)

  • x (sympy.Symbol) – integration variable

  • x_lower (sympy.Symbol, int or float) – start value integration

  • x_upper (sympy.Symbol, int or float) – end value integration

  • doit (bool) – True/False; If True, the integration will be performed, else integral operators will be returned.

  • CDS (Bool) – True if correlated double sampling is required, defaults to False If True parameter ‘tau’ must be given a nonzero finite value (can be symbolic). If method==”log” a logarithmic frequency seep will be used from the lowest frequency until the frequency of the first notch: f=1/tau. Linear sweeping will be used for all other frequency segments. The number of points per segment will be set to points. If type(points) == list, the method will be set to ‘scipy’.

  • tau (str, int, float, sp.Symbol) – CDS delay time

  • method (str) –

    Integration method, implemented methods are:

    • ”auto”: automatic selection of integration method

    • ”symbolic”: forces symbolic integration

    • ”scipy”: numeric integration using scipy.integrate.quad

      CDS will use integration per section f=1/tau

    • ”log”: numeric integration using numpy.trapezoid with a

      logarithmic frequency sweep from f_min to f_max and the number of points (CDS: per section) set by points

    • ”lin”: numeric integration using numpy.trapezoid with a

      linear frequency sweep from fmin to fmax and the number of points (CDS: per section) set by points

    • ”list”: numeric integration using numpy.trapezoid with frequency

      points taken from points (CDS: switches method to ‘scipy’).

    Defaults to ‘auto’

  • points (int, list) – Number of frequency points for integration for method=”lin” and method=”log”, or a list with points. Defaults to 0. If type(points) == list f_min, and f_max will be ignored.

  • numeric (Bool) – If True the result will be converted to numeric. Defaults to True

Returns:

Integration result

Return type:

sympy.expr, int or float

integrated_monomial_coeffs(expr, variables, x, x_lower, x_upper, doit=True, wf=1, method='auto', CDS=False, tau=None, points=1000, numeric=True)

Returns a dictionary with key-value pairs:

  • key: monomial of variables

  • coefficient of this monomial with x integrated over the range x_lower … x_upper.

If doit=True the integration will be performed, else integral operators will be returned.

Parameters:

  • expr – Sympy expression

  • variables (list with sympy.Symbol objects) – List or tuple with variables (currently only two variables accepted)

  • x (sympy.Symbol) – integration variable

  • x_lower (sympy.Symbol, int or float) – start value integration

  • x_upper (sympy.Symbol, int or float) – end value integration

  • doit (bool) – True/False; If True, the integration will be performed, else integral operators will be returned.

Returns:

Dictionary with key-value pairs:

  • key (sympy.Expr): monomial

  • value (sympy.Expr): integrated monomial coefficient

Return type:

sympy.expr, int or float

listPZ(pzResult)

Prints lists with numeric poles and zeros.

Parameters:

pzResult (SLiCAPinstruction.instruction) – SLiCAP execution results of pole-zero analysis.

Returns:

None

Return type:

NoneType

mag(data, f=None)

Magnitude of data.

  • numpy array (AC result or noise ASD): returns np.abs(data). Works element-wise on 2D stepped results (shape n_steps × n_sweep).

  • sympy Laplace expression: evaluates |H(j·2π·f)| at the frequencies in f using _magFunc_f().

Parameters:

  • data (numpy.ndarray, sympy.Expr) – Complex numpy array or sympy Laplace expression.

  • f (list, numpy.ndarray, NoneType) – Frequency array [Hz], required when data is a sympy expression.

Returns:

Magnitude.

Return type:

numpy.ndarray, list

noiseWeighting(filters_dict)

Build the combined squared-magnitude noise weighting function from a dict of cascaded weighting filters.

The result is a sympy expression in ini.frequency that evaluates to |H_1(f)|^2 * |H_2(f)|^2 * … for all cascaded filters. Pass this to weightedRMS() to integrate a NGspice noise spectrum with weighting.

Supported filter-dict keys:

  • “din_a” : DIN A audio weighting, no sub-parameters needed ({})

  • “cds” : Correlated Double Sampling; requires {“tau”: <value>}

  • “lp”,”hp”,”ap”,”bp”,”bs” : see WeightingFilter; sub-dict is its kwargs

  • “custom” : see WeightingFilter; sub-dict must contain {“expr”: <expr>}

Example:

wf = noiseWeighting({
    "din_a": {},
    "hp"   : {"char": "Butterworth", "f_c": 20, "order": 2},
})
Parameters:

filters_dict (dict) – Mapping of filter-type key to parameter dict.

Returns:

Squared magnitude of cascaded filters as a sympy expression in ini.frequency. Returns 1 if filters_dict is empty.

Return type:

sympy.Expr

nonPolyCoeffs(expr, var)

Returns a dictionary with coefficients of negative and positive powers of var.

Parameters:

var (sympy.Symbol) – Variable of which the coefficients will be returned

Returns:

Dict with key-value pairs:

  • key: order of the variable

  • value: coefficient of that order

normalizeRational(rational, var=s, method='lowest')

Normalizes a rational expression to:

\[F(s) = gain\,s^{\ell} \frac{1+b_1s + ... + b_ms^m}{1+a_1s + ... + a_ns^n}\]
Parameters:

  • Rational (sympy.Expr) – Rational function of the variable.

  • var (sympy.Symbol) – Variable of the rational function

  • method (str) –

    Normalization method:

    • ”highest”: the coefficients of the highest order of <variable> of the denominator will be noramalized to unity.

    • ”lowest”: the coefficients of the lowest order of <variable> of the denominator will be noramalized to unity.

Returns:

Normalized rational function of the variable; input that is not a rational function of ‘var’ (matrices, non-rational expressions) is returned unchanged — normalization is a presentation step and must pass anything else through.

Return type:

sympy.Expr

phase(data, f=None, deg=True)

Phase angle of data.

  • numpy array: unwrapped phase along the last axis (axis=-1), so 2D stepped results (shape n_steps × n_sweep) are handled row-wise. Returns degrees when deg is True (default), radians otherwise.

  • sympy Laplace expression: evaluates ∠H(j·2π·f) at f via _phaseFunc_f() (always returns degrees when ini.hz is True).

Parameters:

  • data (numpy.ndarray, sympy.Expr) – Complex numpy array or sympy Laplace expression.

  • f (list, numpy.ndarray, NoneType) – Frequency array [Hz], required when data is a sympy expression.

  • deg (bool) – Return degrees (True, default) or radians (False). Ignored for sympy input.

Returns:

Phase angle.

Return type:

numpy.ndarray, list

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

rational2float(expr)

Converts rational numbers in expr into floats.

Parameters:

expr (sympy.Expression) – Sympy expression in which rational numbers need to be converterd into floats.

Returns:

expression in which rational numbers have been replaced with floats.

Return type:

sympy.Expression

rmsNoise(noiseResult, noise, fmin, fmax, source=None, CDS=False, tau=None, method='auto', points=0, wf=1)

Calculates the RMS source-referred noise or detector-referred noise, or the contribution of a specific noise source or a collection of sources to it.

Parameters:

  • noiseResult (SLiCAPinstruction.instruction) – Results of the execution of an instruction with data type ‘noise’.

  • noise – ‘inoise’ or ‘onoise’ for source-referred noise or detector- referred noise, respectively.

  • fmin (str, int, float, sp.Symbol) – Lower limit of the frequency range in Hz.

  • fmax (str, int, float, sp.Symbol) – Upper limit of the frequency range in Hz.

  • source (str, list) – refDes (ID) or list with IDs of noise sources of which the contribution to the RMS noise needs to be evaluated. Only IDs of current of voltage sources with a nonzero value for their ‘noise’ parameter are accepted.

  • CDS (Bool) – True if correlated double sampling is required, defaults to False If True parameter ‘tau’ must be given a nonzero finite value (can be symbolic). If method==”log” a logarithmic frequency seep will be used from the lowest frequency until the frequency of the first notch: f=1/tau. Linear sweeping will be used for all other frequency segments. The number of points per segment will be set to points. If type(points) == list, the method will be set to ‘scipy’.

  • tau (str, int, float, sp.Symbol) – CDS delay time

  • method (str) –

    Integration method, implemented methods are:

    • ”auto”: automatic selection of integration method

    • ”symbolic”: forces symbolic integration

    • ”scipy”: numeric integration using scipy.integrate.quad.

      CDS will use integration per section f=1/tau

    • ”log”: numeric integration using numpy.trapezoid with a

      logarithmic frequency sweep from f_min to f_max and the number of points (CDS: per section f=1/tau) set by points

    • ”lin”: numeric integration using numpy.trapezoid with a

      linear frequency sweep from fmin to fmax and the number of points (CDS: per section f=1/tau) set by points

    • ”list”: numeric integration using numpy.trapezoid with frequency

      points taken from points (CDS: switches method to ‘scipy’).

    Defaults to ‘auto’

  • points (int, list) – Number of frequency points for integration for method=”lin” and method=”log”, or a list with points. Defaults to 0. If type(points) == list f_min, and f_max will be redefined to the first and the last number in the list.

  • wf (str, int, float, sympy expr) – Frequency weighting function (H(s) or H(f))

Returns:

RMS noise over the frequency interval.

  • An expression or value if parameter stepping of the instruction is disabled.

  • A list with expressions or values if parameter stepping of the instruction is enabled.

Return type:

int, float, sympy.Expr

roundN(expr, numeric=False)

Rounds all float and rational numbers in an expression to ini.disp digits, and converts integers into floats if their number of digits exceeds ini.disp

Parameters:

  • expr (sympy.Expr) – Input expression

  • numeric (Bool) – True if numeric evaluation (pi = 3.14…) must be done

Returns:

modified expression

Return type:

sympy.Expr

routh(charPoly, eps=epsilon)

Returns the Routh array of a polynomial of the Laplace variable (ini.laplace).

Parameters:

  • charPoly (sympy.Expr) – Expression that can be written as a polynomial of the Laplace variable (ini.laplace).

  • eps (sympy.Symbol) – Symbolic variable used to indicate marginal stability. Use a symbol that is not present in charPoly.

Returns:

Routh array

Return type:

sympy.Matrix

Example:

>>> # ini.laplace = sp.Symbol('s')
>>> s, eps = sp.symbols('s, epsilon')
>>> charPoly = s**4+2*s**3+(3+k)*s**2+(1+k)*s+(1+k)
>>> M = routh(charPoly, eps)
>>> print(M.col(0)) # Number of roots in the right half plane is equal to
>>>                 # the number of sign changes in the first column of the
>>>                 # Routh array
Matrix([[1], [2], [k/2 + 5/2], [(k**2 + 2*k + 1)/(k + 5)], [k + 1]])
step2PeriodicPulse(ft, t_pulse, t_period, n_periods)

Converts a step response in a periodic pulse response. Works with symbolic and numeric time functions.

For evaluation of numeric values, use the SLiCAP function: _makeNumData().

Parameters:

  • ft (sympy.Expr) – Time function f(t)

  • t_pulse (int, float) – Pulse width

  • t_period (int, float) – Pulse period

  • n_periods – Number of pulses

Typen_periods:

int, float

Returns:

modified time function

Return type:

sympy.Expr

str2number(var)

Returns a number with its value represented by var.

Parameters:

var (str, sympy object, int, float) – Variable that may represent a number.

Returns:

number

Return type:

float, int

units2TeX(units)

Returns units in LaTeX format, without opening and closing ‘$’.

Parameters:

units (str) – String representing an expression with units

Returns:

LaTeX code of ‘units’ without opening or closing tags.

Return type:

str

weightedRMS(spectrum, frequencies, sq_mag_wf=1)

Apply a noise weighting filter to a numpy noise power spectrum and return unweighted and weighted RMS values.

The weighting is applied outside NGspice: NGspice computes the raw noise power spectral density; this function multiplies it by the squared magnitude of the weighting filter(s) and integrates.

Parameters:

  • spectrum (numpy.ndarray) – 1D numpy array of noise power spectral density (V^2/Hz or A^2/Hz) as returned by a NGspice noise analysis.

  • frequencies (numpy.ndarray) – 1D numpy array of frequency points corresponding to spectrum.

  • sq_mag_wf (sympy.Expr, int, float) – Squared magnitude of the weighting filter as a sympy expression in ini.frequency, as returned by noiseWeighting(). Pass 1 (default) for unweighted RMS.

Returns:

Tuple (rms_unweighted, rms_weighted, weighted_spectrum) where:

  • rms_unweighted : float — RMS of the unweighted spectrum

  • rms_weighted : float — RMS of the weighted spectrum

  • weighted_spectrum : numpy.ndarray — weighted noise PSD (same units as spectrum)

Return type:

tuple