API Reference

transient_analysis.hurwitzTool.cli

transient_analysis.hurwitzTool.cli.build_parser()

Build the command-line parser.

Return type:

ArgumentParser

transient_analysis.hurwitzTool.cli.main(argv=None)

Run the hurwitzTool command-line interface.

Parameters:

argv (list[str] | None)

Return type:

int

transient_analysis.hurwitzTool.apis

class transient_analysis.hurwitzTool.apis.HurwitzService(base_dir)

Bases: object

Parameters:

base_dir (Path)

numeric_check(req)

Parameters:

req (NumericCheckRequest)

Return type:

NumericCheckResult

scan1d(req)

Parameters:

req (Scan1DRequest)

Return type:

Scan1DResult

scan2d(req)

Parameters:

req (Scan2DRequest)

Return type:

Scan2DResult

symbolic_region(req)

Parameters:

req (SymbolicRegionRequest)

Return type:

SymbolicRegionResult

class transient_analysis.hurwitzTool.apis.NumericCheckRequest(coeffs: 'str', subs: 'Dict[str, float]', use_lienard: 'bool' = False, tol: 'float' = 1e-10)

Bases: object

Parameters:

• coeffs (str)

• subs (Dict[str, float])

• use_lienard (bool)

• tol (float)

coeffs: str

subs: Dict[str, float]

tol: float

use_lienard: bool

class transient_analysis.hurwitzTool.apis.NumericCheckResult(ok: 'bool', used: 'str', a_numeric: 'List[float]', minors_numeric: 'List[float]', a0_pos: 'bool', coeff_pos: 'bool')

Bases: object

Parameters:

• ok (bool)

• used (str)

• a_numeric (List[float])

• minors_numeric (List[float])

• a0_pos (bool)

• coeff_pos (bool)

a0_pos: bool

a_numeric: List[float]

coeff_pos: bool

minors_numeric: List[float]

ok: bool

used: str

class transient_analysis.hurwitzTool.apis.Scan1DRequest(coeffs: 'str', symbol: 'str', lo: 'float', hi: 'float', step: 'float', use_lienard: 'bool' = False)

Bases: object

Parameters:

• coeffs (str)

• symbol (str)

• lo (float)

• hi (float)

• step (float)

• use_lienard (bool)

coeffs: str

hi: float

lo: float

step: float

symbol: str

use_lienard: bool

class transient_analysis.hurwitzTool.apis.Scan1DResult(samples: 'List[Tuple[float, bool]]')

Bases: object

Parameters:

samples (List[Tuple[float, bool]])

samples: List[Tuple[float, bool]]

class transient_analysis.hurwitzTool.apis.Scan2DRequest(coeffs: 'str', sx: 'str', sy: 'str', xlo: 'float', xhi: 'float', dx: 'float', ylo: 'float', yhi: 'float', dy: 'float', use_lienard: 'bool' = False)

Bases: object

Parameters:

• coeffs (str)

• sx (str)

• sy (str)

• xlo (float)

• xhi (float)

• dx (float)

• ylo (float)

• yhi (float)

• dy (float)

• use_lienard (bool)

coeffs: str

dx: float

dy: float

sx: str

sy: str

use_lienard: bool

xhi: float

xlo: float

yhi: float

ylo: float

class transient_analysis.hurwitzTool.apis.Scan2DResult(xs: 'np.ndarray', ys: 'np.ndarray', Z: 'np.ndarray')

Bases: object

Parameters:

• xs (ndarray)

• ys (ndarray)

• Z (ndarray)

Z: ndarray

xs: ndarray

ys: ndarray

class transient_analysis.hurwitzTool.apis.SymbolicRegionRequest(coeffs: 'str', symbols: 'Optional[str]' = None, solvefor: 'Optional[str]' = None, use_lienard: 'bool' = False, intervals_pretty: 'bool' = False)

Bases: object

Parameters:

• coeffs (str)

• symbols (str | None)

• solvefor (str | None)

• use_lienard (bool)

• intervals_pretty (bool)

coeffs: str

intervals_pretty: bool

solvefor: str | None

symbols: str | None

use_lienard: bool

class transient_analysis.hurwitzTool.apis.SymbolicRegionResult(variables: 'List[str]', used: 'str', region: 'str', pretty: 'Optional[str]' = None, latex: 'Optional[str]' = None)

Bases: object

Parameters:

• variables (List[str])

• used (str)

• region (str)

• pretty (str | None)

• latex (str | None)

latex: str | None

pretty: str | None

region: str

used: str

variables: List[str]

transient_analysis.hurwitzTool.utils

transient_analysis.hurwitzTool.utils.ascii_heatmap(xs, ys, Z, invert_y=True)

Parameters:

• xs (ndarray)

• ys (ndarray)

• Z (ndarray)

• invert_y (bool)

Return type:

str

transient_analysis.hurwitzTool.utils.detect_free_symbols(a)

Parameters:

a (List[Expr])

Return type:

List[Symbol]

transient_analysis.hurwitzTool.utils.interval_to_string(I, latex=False)

Parameters:

• I (Interval)

• latex (bool)

Return type:

str

transient_analysis.hurwitzTool.utils.one_dim_interval_set(expr_bool, sym)

Parameters:

• expr_bool (sp.Boolean | sp.Rel)

• sym (sp.Symbol)

transient_analysis.hurwitzTool.utils.parse_coeffs(s)

Parameters:

s (str)

Return type:

List[Expr]

transient_analysis.hurwitzTool.utils.parse_subs_list(s)

Parameters:

s (str | None)

Return type:

Dict[Symbol, float]

transient_analysis.hurwitzTool.utils.parse_symbols_arg(symbols)

Parameters:

symbols (str | None)

Return type:

List[Symbol]

transient_analysis.hurwitzTool.utils.set_to_pretty_intervals(S, latex=False)

Parameters:

• S (Set)

• latex (bool)

Return type:

str

transient_analysis.hurwitzTool.utils.sympify_list(seq)

Parameters:

seq (List[str])

Return type:

List[Expr]

transient_analysis.hurwitzTool.io

class transient_analysis.hurwitzTool.io.IOManager(base_dir: 'Path')

Bases: object

Parameters:

base_dir (Path)

base_dir: Path

property in_dir: Path

property out_dir: Path

save_csv(path, header, rows)

Parameters:

• path (Path)

• header (list[str])

• rows (list[list[object]])

Return type:

Path

save_png_heatmap(path, xs, ys, Z)

Parameters:

• path (Path)

• xs (ndarray)

• ys (ndarray)

• Z (ndarray)

Return type:

str

transient_analysis.hurwitzTool.app

class transient_analysis.hurwitzTool.app.HurwitzApp(base_dir, tol=1e-10)

Bases: object

Application context for the Hurwitz stability tool.

Parameters:

• base_dir (Path)

• tol (float)

base_dir: Path

check_numeric(poly, subs, use_lienard)

Parameters:

• poly (Polynomial)

• subs (Dict[Symbol, float])

• use_lienard (bool)

detect_symbols(a, symbols_arg, solvefor)

Parameters:

• a (List[Expr])

• symbols_arg (str | None)

• solvefor (str | None)

Return type:

List[Symbol]

hurwitz_matrix(poly)

Parameters:

poly (Polynomial)

Return type:

MutableDenseMatrix

inequalities(poly, use_lienard)

Parameters:

• poly (Polynomial)

• use_lienard (bool)

io: IOManager

minors(poly)

Parameters:

poly (Polynomial)

Return type:

List[Expr]

num: NumericChecker

polynomial_from_str(coeffs)

Parameters:

coeffs (str)

Return type:

Polynomial

pretty_intervals_1d(region, sym)

Parameters:

• region (sp.Boolean | sp.Set)

• sym (sp.Symbol)

Return type:

tuple[str, str] | None

reduce_region(ineqs, syms)

Parameters:

• ineqs (List[sp.Rel])

• syms (List[sp.Symbol])

Return type:

sp.Boolean | sp.Set

scan1d(poly, sym, lo, hi, step, use_lienard)

Parameters:

• poly (Polynomial)

• sym (Symbol)

• lo (float)

• hi (float)

• step (float)

• use_lienard (bool)

scan2d(poly, sx, xlo, xhi, dx, sy, ylo, yhi, dy, use_lienard)

Parameters:

• poly (Polynomial)

• sx (Symbol)

• xlo (float)

• xhi (float)

• dx (float)

• sy (Symbol)

• ylo (float)

• yhi (float)

• dy (float)

• use_lienard (bool)

tol: float

transient_analysis.hurwitzTool.core

class transient_analysis.hurwitzTool.core.HurwitzConditions

Bases: object

Build Hurwitz or Lienard-Chipart inequality sets.

classmethod inequalities(poly, use_lienard)

Return symbolic positivity inequalities and the criterion label.

Strict SymPy relations are created with evaluate=False so display and tests can still show relations such as 1 > 0 instead of folding them immediately to True.

Parameters:

• poly (Polynomial)

• use_lienard (bool)

Return type:

Tuple[List[Relational], str]

static lienard_indices(n)

Return the required minor indices for the Lienard-Chipart test.

Parameters:

n (int)

Return type:

List[int]

exception transient_analysis.hurwitzTool.core.HurwitzError

Bases: Exception

Base exception for Hurwitz stability errors.

class transient_analysis.hurwitzTool.core.HurwitzMatrixBuilder

Bases: object

Build Hurwitz matrices from descending polynomial coefficients.

The matrix convention used here is H[i, j] = a_{2*j + (1 - i)}, with a_k = 0 outside the coefficient range 0 <= k <= n.

classmethod matrix(a_desc)

Return the Hurwitz matrix as a SymPy Matrix.

Parameters:

a_desc (List[Expr])

Return type:

MutableDenseMatrix

static matrix_tuple(a_desc_tuple)

Return the Hurwitz matrix as a cacheable tuple of tuples.

Parameters:

a_desc_tuple (Tuple[Expr, ...])

Return type:

Tuple[Tuple[Expr, …], …]

class transient_analysis.hurwitzTool.core.HurwitzMinors

Bases: object

Compute and cache the leading principal Hurwitz minors.

static leading_minors(a_desc_tuple)

Return the leading principal minors Δ1 through Δn.

Parameters:

a_desc_tuple (Tuple[Expr, ...])

Return type:

Tuple[Expr, …]

classmethod minors(a_desc)

Return the leading principal minors as a list.

Parameters:

a_desc (List[Expr])

Return type:

List[Expr]

class transient_analysis.hurwitzTool.core.NumericChecker(tol=1e-10)

Bases: object

Evaluate Hurwitz conditions numerically and run parameter scans.

Parameters:

tol (float)

check(poly, subs, use_lienard)

Check whether a polynomial satisfies the selected stability test.

Parameters:

• poly (Polynomial)

• subs (Dict[Symbol, float])

• use_lienard (bool)

Return type:

Tuple[bool, Dict]

eval_numeric(expr, subs)

Evaluate a numeric or symbolic expression after substitutions.

Parameters:

• expr (Expr)

• subs (Dict[Symbol, float])

Return type:

float

rhp_roots(a_num)

Count roots whose real part is greater than the numeric tolerance.

Parameters:

a_num (List[float])

Return type:

int

scan1d(poly, sym, lo, hi, step, use_lienard)

Sample stability over one scalar parameter.

Parameters:

• poly (Polynomial)

• sym (Symbol)

• lo (float)

• hi (float)

• step (float)

• use_lienard (bool)

Return type:

List[Tuple[float, bool]]

scan2d(poly, sx, xlo, xhi, dx, sy, ylo, yhi, dy, use_lienard)

Sample stability over two scalar parameters and return a Boolean grid.

Parameters:

• poly (Polynomial)

• sx (Symbol)

• xlo (float)

• xhi (float)

• dx (float)

• sy (Symbol)

• ylo (float)

• yhi (float)

• dy (float)

• use_lienard (bool)

Return type:

Tuple[ndarray, ndarray, ndarray]

class transient_analysis.hurwitzTool.core.Polynomial(a_desc, var=s)

Bases: object

Real-coefficient polynomial stored with descending coefficients.

The coefficient list is interpreted as [a0, a1, ..., an] for a0*s**n + a1*s**(n-1) + ... + an. The default polynomial variable is s. The field-level documentation is intentionally kept out of the class docstring so Sphinx/Napoleon does not emit duplicate object warnings for the dataclass fields when :members: is enabled in api.rst.

Parameters:

• a_desc (List[Expr])

• var (Symbol)

a_desc: List[Expr]

as_expr()

Return the polynomial as a SymPy expression.

Return type:

Expr

property degree: int

Return the polynomial degree.

is_numeric()

Return True when all coefficients are numeric.

Return type:

bool

var: Symbol

transient_analysis.hurwitzTool.design

class transient_analysis.hurwitzTool.design.Preset(name: 'str', coeffs: 'List[sp.Expr]')

Bases: object

Parameters:

• name (str)

• coeffs (List[Expr])

coeffs: List[Expr]

name: str

transient_analysis.hurwitzTool.design.example_numeric()

Return type:

Preset

transient_analysis.hurwitzTool.design.example_symbolic_K()

Return type:

Preset