API Reference

state_space_design.regulatorTool.cli

state_space_design.regulatorTool.cli.build_parser()[source]

Build the command-line parser.

Return type:

ArgumentParser

state_space_design.regulatorTool.cli.main(argv=None)[source]

Run the regulator command-line interface.

Parameters:

argv (list[str] | None)

Return type:

int

state_space_design.regulatorTool.apis

apis.py — public API (service layer) for programmatic use and the CLI.

class state_space_design.regulatorTool.apis.RegulatorRunRequest(num: 'np.ndarray', den: 'np.ndarray', K_poles: 'Optional[np.ndarray]' = None, obs_poles: 'Optional[np.ndarray]' = None, ts: 'Optional[float]' = None, undershoot: 'Optional[Tuple[float, float]]' = None, obs_speed_factor: 'float' = 5.0, x0: 'Optional[np.ndarray]' = None, e0: 'Optional[np.ndarray]' = None, t_final: 'float' = 8.0, dt: 'float' = 0.01, rl_axes: 'Tuple[float, float, float, float]' = (-14.0, 2.0, -8.0, 8.0), rl_k: 'str' = 'auto', pretty: 'bool' = False, plots: 'str' = 'both', save_prefix: 'Optional[str]' = None, export_json: 'Optional[str]' = None, ply_width: 'int' = 0, verbose: 'bool' = False)[source]

Bases: object

Parameters:

  • num (ndarray)

  • den (ndarray)

  • K_poles (ndarray | None)

  • obs_poles (ndarray | None)

  • ts (float | None)

  • undershoot (Tuple[float, float] | None)

  • obs_speed_factor (float)

  • x0 (ndarray | None)

  • e0 (ndarray | None)

  • t_final (float)

  • dt (float)

  • rl_axes (Tuple[float, float, float, float])

  • rl_k (str)

  • pretty (bool)

  • plots (str)

  • save_prefix (str | None)

  • export_json (str | None)

  • ply_width (int)

  • verbose (bool)

K_poles: ndarray | None = None
den: ndarray
dt: float = 0.01
e0: ndarray | None = None
export_json: str | None = None
num: ndarray
obs_poles: ndarray | None = None
obs_speed_factor: float = 5.0
plots: str = 'both'
ply_width: int = 0
pretty: bool = False
rl_axes: Tuple[float, float, float, float] = (-14.0, 2.0, -8.0, 8.0)
rl_k: str = 'auto'
save_prefix: str | None = None
t_final: float = 8.0
ts: float | None = None
undershoot: Tuple[float, float] | None = None
verbose: bool = False
x0: ndarray | None = None
class state_space_design.regulatorTool.apis.RegulatorService(req)[source]

Bases: object

Parameters:

req (RegulatorRunRequest)

run()[source]
Return type:

Dict[str, Any]

state_space_design.regulatorTool.app

app.py — app orchestration for regulatorTool (handles plotting choices).

state_space_design.regulatorTool.app.run_app(req)[source]
Parameters:

req (RegulatorRunRequest)

Return type:

None

state_space_design.regulatorTool.utils

Utility helpers for regulatorTool.

This module contains parsing helpers, small matrix formatting utilities, and frequency-domain helpers used by the regulator design workflow. The docstrings are intentionally plain text so Sphinx autodoc can parse this module without reStructuredText formatting errors.

state_space_design.regulatorTool.utils.array2str(M, p=6)[source]

Format a numeric array as a compact string.

Parameters:

  • M (ndarray)

  • p (int)

Return type:

str

state_space_design.regulatorTool.utils.bode_data(tf, w)[source]

Return Bode magnitude in dB and unwrapped phase in degrees.

Parameters:

  • tf (TransferFunction)

  • w (ndarray)

Return type:

tuple[ndarray, ndarray]

state_space_design.regulatorTool.utils.log_call(fn)[source]

Log a function call at DEBUG level and then run the function.

Parameters:

fn (Callable)

Return type:

Callable

state_space_design.regulatorTool.utils.mat_inline(M, precision=4)[source]

Format a matrix as a compact one-line string.

Parameters:

  • M (ndarray)

  • precision (int)

Return type:

str

state_space_design.regulatorTool.utils.parse_complex_list(s)[source]

Parse a comma- or whitespace-separated string into complex values.

Parameters:

s (str)

Return type:

ndarray

state_space_design.regulatorTool.utils.parse_real_vec(s)[source]

Parse a comma- or whitespace-separated string into a real vector.

Parameters:

s (str)

Return type:

ndarray

state_space_design.regulatorTool.utils.phi_of_A(A, coeff)[source]

Evaluate a monic characteristic polynomial at a square matrix.

Parameters:

  • A (ndarray)

  • coeff (ndarray)

Return type:

ndarray

state_space_design.regulatorTool.utils.poly_from_roots(roots)[source]

Return real polynomial coefficients from a set of roots.

Parameters:

roots (ndarray)

Return type:

ndarray

state_space_design.regulatorTool.utils.rlocus_from_control(L, kvect)[source]

Compute root-locus branches and gains using python-control.

The function first tries the newer root_locus_map API when available. If that path is unavailable or incompatible, it falls back to the legacy root_locus API with the related future warning suppressed.

Parameters:

  • L (TransferFunction)

  • kvect (ndarray | None)

Return type:

tuple[ndarray, ndarray]

state_space_design.regulatorTool.utils.tf_eval_jw(tf, w)[source]

Evaluate a transfer function along the imaginary axis.

Parameters:

  • tf (TransferFunction)

  • w (ndarray)

Return type:

ndarray

state_space_design.regulatorTool.core

core.py — core dataclasses for plant representation and regulator parameters/results.

class state_space_design.regulatorTool.core.Plant(num: 'np.ndarray', den: 'np.ndarray', A: 'np.ndarray', B: 'np.ndarray', C: 'np.ndarray', D: 'float')[source]

Bases: object

Parameters:

  • num (ndarray)

  • den (ndarray)

  • A (ndarray)

  • B (ndarray)

  • C (ndarray)

  • D (float)

A: ndarray
B: ndarray
C: ndarray
D: float
den: ndarray
num: ndarray
class state_space_design.regulatorTool.core.RegulatorDesignResult(K: 'np.ndarray', Ke: 'np.ndarray', Ahat: 'np.ndarray', Bhat: 'np.ndarray', Fhat: 'np.ndarray', Atil: 'np.ndarray', Btil: 'np.ndarray', Ctil: 'np.ndarray', Dtil: 'np.ndarray', Gc: 'ct.TransferFunction', G: 'ct.TransferFunction', L: 'ct.TransferFunction', T: 'ct.TransferFunction')[source]

Bases: object

Parameters:

  • K (ndarray)

  • Ke (ndarray)

  • Ahat (ndarray)

  • Bhat (ndarray)

  • Fhat (ndarray)

  • Atil (ndarray)

  • Btil (ndarray)

  • Ctil (ndarray)

  • Dtil (ndarray)

  • Gc (TransferFunction)

  • G (TransferFunction)

  • L (TransferFunction)

  • T (TransferFunction)

Ahat: ndarray
Atil: ndarray
Bhat: ndarray
Btil: ndarray
Ctil: ndarray
Dtil: ndarray
Fhat: ndarray
G: TransferFunction
Gc: TransferFunction
K: ndarray
Ke: ndarray
L: TransferFunction
T: TransferFunction
class state_space_design.regulatorTool.core.RegulatorParams(K_poles: 'Optional[np.ndarray]' = None, obs_poles: 'Optional[np.ndarray]' = None, ts: 'Optional[float]' = None, undershoot: 'Optional[Tuple[float, float]]' = None, obs_speed_factor: 'float' = 5.0)[source]

Bases: object

Parameters:

  • K_poles (ndarray | None)

  • obs_poles (ndarray | None)

  • ts (float | None)

  • undershoot (Tuple[float, float] | None)

  • obs_speed_factor (float)

K_poles: ndarray | None = None
obs_poles: ndarray | None = None
obs_speed_factor: float = 5.0
ts: float | None = None
undershoot: Tuple[float, float] | None = None
class state_space_design.regulatorTool.core.Signals(t: 'np.ndarray', X: 'np.ndarray', E: 'np.ndarray', U: 'np.ndarray', Y: 'np.ndarray')[source]

Bases: object

Parameters:

  • t (ndarray)

  • X (ndarray)

  • E (ndarray)

  • U (ndarray)

  • Y (ndarray)

E: ndarray
U: ndarray
X: ndarray
Y: ndarray
t: ndarray
class state_space_design.regulatorTool.core.SimulationSpec(x0: 'Optional[np.ndarray]' = None, e0: 'Optional[np.ndarray]' = None, t_final: 'float' = 8.0, dt: 'float' = 0.01)[source]

Bases: object

Parameters:

  • x0 (ndarray | None)

  • e0 (ndarray | None)

  • t_final (float)

  • dt (float)

dt: float = 0.01
e0: ndarray | None = None
t_final: float = 8.0
x0: ndarray | None = None

state_space_design.regulatorTool.io

Filesystem helpers for regulatorTool.

The helpers in this module resolve package-local input and output paths and write JSON payloads for reports. The docstrings avoid reStructuredText lists so that Sphinx autodoc can parse the module safely.

state_space_design.regulatorTool.io.ensure_dir(d)[source]

Create a directory when it does not already exist.

Parameters:

d (str)

Return type:

None

state_space_design.regulatorTool.io.out_path(*parts, out_dir=None)[source]

Build a path under the regulatorTool output directory.

Parameters:

  • parts (str)

  • out_dir (str | None)

Return type:

str

state_space_design.regulatorTool.io.resolve_save_prefix(prefix)[source]

Resolve a save prefix to a path that can receive file suffixes.

A missing prefix returns None. Absolute paths are returned after ensuring their parent directory exists. Prefixes beginning with out are resolved under the package output directory. Bare basenames are also placed under the package output directory. Other relative paths are resolved relative to the current working directory after ensuring their parent directory exists.

Parameters:

prefix (str | None)

Return type:

str | None

state_space_design.regulatorTool.io.save_json(obj, path)[source]

Write an object as formatted JSON.

Parameters:

  • obj (Any)

  • path (str)

Return type:

None

state_space_design.regulatorTool.design

design.py — classes that implement the regulator design with reduced-order observer.

class state_space_design.regulatorTool.design.PlantFactory[source]

Bases: object

Create a controllable companion form realization with x1=y that matches the given TF.

static from_tf(num, den)[source]
Parameters:

  • num (ndarray)

  • den (ndarray)

Return type:

Plant

class state_space_design.regulatorTool.design.ReducedObserverDesigner[source]

Bases: object

Implements Ogata’s minimum-order observer (p=1 → r=n-1).

static min_order_acker(Abb, Aab, poles)[source]
Parameters:

  • Abb (ndarray)

  • Aab (ndarray)

  • poles (ndarray)

Return type:

ndarray

class state_space_design.regulatorTool.design.RegulatorDesigner(plant, params)[source]

Bases: object

Top-level orchestrator for regulator design + simulation + analysis.

Parameters:
bode_open_closed(design)[source]
Parameters:

design (RegulatorDesignResult)

Return type:

Tuple[Tuple[ndarray, ndarray], Tuple[ndarray, ndarray], ndarray, ndarray]

root_locus(design, rl_k)[source]
Parameters:
Return type:

Tuple[ndarray, ndarray]

run()[source]
Return type:

RegulatorDesignResult

simulate_initial(design, spec)[source]
Parameters:
Return type:

Signals