API Reference¶

transient_analysis.responseTool.cli¶

transient_analysis.responseTool.cli.build_parser()[source]¶

Build the command-line parser.

Return type:: ArgumentParser

transient_analysis.responseTool.cli.main(argv=None)[source]¶

Run the responseTool command-line interface.

Parameters:: argv (list[str] | None)
Return type:: int

transient_analysis.responseTool.cli.parse_overlay_list(s)[source]¶

Parse an optional damping-ratio overlay list.

Parameters:: s (str | None)
Return type:: list[float]

transient_analysis.responseTool.cli.parse_zetas_list(s)[source]¶

Parse a damping-ratio list and return a default grid when empty.

Parameters:: s (str | None)
Return type:: list[float]

transient_analysis.responseTool.app¶

class transient_analysis.responseTool.app.ResponseResult(T: 'np.ndarray', y: 'np.ndarray', u: 'np.ndarray | None' = None)[source]¶

Bases: object

Parameters:

T (ndarray)
y (ndarray)
u (ndarray | None)

T: ndarray¶

u: ndarray | None¶

y: ndarray¶

class transient_analysis.responseTool.app.ResponseToolApp(root: 'Path | None' = None, show_plots: 'bool' = False)[source]¶

Bases: object

Parameters:

root (Path | None)
show_plots (bool)

compute_unit_ramp_ss(A, B, C, D, *, tfinal=10.0, dt=0.01, title_suffix='')[source]¶

Parameters:

tfinal (float)
dt (float)
title_suffix (str)

Return type:

ResponseResult

engine: ResponseEngine¶

io: IOConfig¶

root: Path | None¶

second_order_mesh(*, wn, zeta_min=0.0, zeta_max=1.0, zeta_steps=41, tfinal=10.0, dt=0.01, save_prefix='std2_surface', title_suffix='', plot_heatmap=True, plotly=False)[source]¶

Generate a 3D mesh Z(ζ, t) of step responses; save JSON and optional PNGs.

Parameters:

wn (float)
zeta_min (float)
zeta_max (float)
zeta_steps (int)
tfinal (float)
dt (float)
save_prefix (str)
title_suffix (str)
plot_heatmap (bool)
plotly (bool)

Return type:

dict

second_order_overlays(*, wn, zetas=None, tfinal=10.0, dt=0.01, save_prefix='std2_overlays', title_suffix='')[source]¶

Generate 2D overlay curves for selected ζ values; save JSON and optional PNG.

Parameters:

wn (float)
zetas (list[float] | None)
tfinal (float)
dt (float)
save_prefix (str)
title_suffix (str)

Return type:

dict

second_order_plotly_surface(*, wn=1.0, zeta_min=0.0, zeta_max=1.0, zeta_steps=51, tfinal=10.0, dt=0.01, overlay=None, title='', save_prefix='plotly_surface', save_html=None, save_png=None)[source]¶

Interactive Plotly 3D surface y(t, zeta) for the standard 2nd-order system.

Always writes JSON snapshot: <out>/<save_prefix>_plotly3D.json
If save_html is given, writes interactive HTML.
If save_png is given, attempts PNG (requires kaleido).

Parameters:

wn (float)
zeta_min (float)
zeta_max (float)
zeta_steps (int)
tfinal (float)
dt (float)
overlay (list[float] | None)
title (str)
save_prefix (str)
save_html (str | None)
save_png (str | None)

Return type:

dict

second_order_single(*, wn=None, zeta=None, K=None, coeffs=None, tfinal=None, dt=0.001, save_prefix='second_order')[source]¶

Single step response + metrics. Either (wn,zeta[,K]) or coeffs=(K,a2,a1,a0).

Parameters:

wn (float | None)
zeta (float | None)
K (float | None)
coeffs (tuple[float, float, float, float] | None)
tfinal (float | None)
dt (float)
save_prefix (str)

Return type:

ResponseResult

second_order_sweep(*, wn, zetas, tfinal=None, dt=0.001, save_prefix='second_order')[source]¶

Zeta sweep step responses (stores all curves).

Parameters:

wn (float)
zetas (list[float])
tfinal (float | None)
dt (float)
save_prefix (str)

Return type:

dict

show_plots: bool¶

simulate_tf_input(num, den, *, u='ramp', tfinal=10.0, dt=0.01, title=None)[source]¶

Parameters:

u (str)
tfinal (float)
dt (float)
title (str | None)

Return type:

ResponseResult

ss_step_metrics(A, B, C, D)[source]¶

Return type:: dict

step_ss_from_input(A, B, C, D, *, input_index, tfinal=10.0, dt=0.01, title=None, save_prefix='ex5_3_from_u')[source]¶

Parameters:

input_index (int)
tfinal (float)
dt (float)
title (str | None)
save_prefix (str)

Return type:

ResponseResult

step_ss_states(A, B, C, D, *, input_index, tfinal=10.0, dt=0.01, save_name='ex5_3_states_u')[source]¶

Parameters:

input_index (int)
tfinal (float)
dt (float)
save_name (str)

Return type:

ResponseResult

transient_analysis.responseTool.utils¶

transient_analysis.responseTool.utils.forced_response(sys, U, T)[source]¶

Parameters:

U (ndarray)
T (ndarray)

transient_analysis.responseTool.utils.mk_ss(A, B, C, D)[source]¶

transient_analysis.responseTool.utils.mk_tf(num, den)[source]¶

transient_analysis.responseTool.utils.parse_matrix(s)[source]¶

Parameters:: s (str | None)
Return type:: ndarray | None

transient_analysis.responseTool.utils.parse_vector(s)[source]¶

Parameters:: s (str | None)
Return type:: ndarray | None

transient_analysis.responseTool.utils.parse_zetas_list(s)[source]¶

Parse comma/space-separated list of zeta values; provide a sensible default.

Parameters:: s (str | None)
Return type:: list[float]

transient_analysis.responseTool.utils.step_response(sys, T)[source]¶

Parameters:: T (ndarray)
Return type:: Tuple[ndarray, ndarray]

transient_analysis.responseTool.utils.time_grid(tfinal, dt)[source]¶

Parameters:

tfinal (float)
dt (float)

Return type:

ndarray

transient_analysis.responseTool.apis¶

transient_analysis.responseTool.apis.lsim_tf_api(num, den, *, u='ramp', tfinal=10.0, dt=0.01, root='.')[source]¶

Parameters:

u (str)
tfinal (float)
dt (float)
root (str | Path)

Return type:

ResponseResult

transient_analysis.responseTool.apis.ramp_ss_api(A, B, C, D, *, tfinal=10.0, dt=0.01, root='.')[source]¶

Parameters:

tfinal (float)
dt (float)
root (str | Path)

Return type:

ResponseResult

transient_analysis.responseTool.core¶

class transient_analysis.responseTool.core.AugmentationEngine[source]¶

Bases: object

Ramp via augmentation trick for SISO SS.

x_a = [x; z], z = ∫ y dt A_A = [[A, 0], [C, 0]]; B_B = [[B], [D]]; C_C = [0…01]; D_D = [0]

static augment_for_ramp(A, B, C, D)[source]¶

unit_ramp_response(model, tfinal, dt)[source]¶

Parameters:

model (SSModel)
tfinal (float)
dt (float)

Return type:

tuple[ndarray, ndarray, ndarray]

class transient_analysis.responseTool.core.InputSignal[source]¶

Bases: object

static ramp(T)[source]¶

Parameters:: T (ndarray)
Return type:: ndarray

static sine(T, freq_hz=0.5, phase=0.0)[source]¶

Parameters:

T (ndarray)
freq_hz (float)
phase (float)

Return type:

ndarray

static square(T, freq_hz=0.5)[source]¶

Parameters:

T (ndarray)
freq_hz (float)

Return type:

ndarray

class transient_analysis.responseTool.core.MIMOStepEngine[source]¶

Bases: object

MIMO step responses and utilities for state-space models (non-deprecated API usage).

static forced_step_states(model, *, input_index, tfinal, dt)[source]¶

Parameters:

model (SSModel)
input_index (int)
tfinal (float)
dt (float)

Return type:

Tuple[ndarray, ndarray | None, ndarray | None]

static ss2tf_matrix(model)[source]¶

Parameters:: model (SSModel)

static step_from_input(model, *, input_index, tfinal, dt)[source]¶

Parameters:

model (SSModel)
input_index (int)
tfinal (float)
dt (float)

Return type:

Tuple[ndarray, ndarray]

static step_metrics(tf_matrix)[source]¶

Return type:: Dict[str, Dict[str, Any] | None]

class transient_analysis.responseTool.core.ResponseEngine[source]¶

Bases: object

High-level façade for SISO ramp and TF arbitrary input.

lsim_tf(model, *, u='ramp', tfinal=10.0, dt=0.01)[source]¶

Parameters:

model (TFModel)
u (Literal['ramp', 'sine', 'square'])
tfinal (float)
dt (float)

ramp_ss(model, *, tfinal=10.0, dt=0.01)[source]¶

Parameters:

model (SSModel)
tfinal (float)
dt (float)

class transient_analysis.responseTool.core.SSModel(A: 'np.ndarray', B: 'np.ndarray', C: 'np.ndarray', D: 'np.ndarray')[source]¶

Bases: object

Parameters:

A (ndarray)
B (ndarray)
C (ndarray)
D (ndarray)

A: ndarray¶

B: ndarray¶

C: ndarray¶

D: ndarray¶

system()[source]¶

class transient_analysis.responseTool.core.SecondOrderEngine[source]¶

Bases: object

Analytics + simulation for standard second-order systems.

static analytic_metrics(wn, zeta)[source]¶

Parameters:

wn (float)
zeta (float)

Return type:

Dict[str, float]

static auto_time(wn, zeta, tfinal=None, dt=0.001)[source]¶

Parameters:

wn (float)
zeta (float)
tfinal (float | None)
dt (float)

Return type:

ndarray

static classify(zeta)[source]¶

Parameters:: zeta (float)
Return type:: str

static infer_from_coeffs(K, a2, a1, a0)[source]¶

Parameters:

K (float)
a2 (float)
a1 (float)
a0 (float)

Return type:

Tuple[float, float, float]

static measure_step(T, y, tol=0.02)[source]¶

Parameters:

T (ndarray)
y (ndarray)
tol (float)

Return type:

Dict[str, float]

static step(model, t)[source]¶

Parameters:

model (SecondOrderModel)
t (ndarray)

Return type:

Tuple[ndarray, ndarray]

static sweep_zeta(wn, zetas, t)[source]¶

Parameters:

wn (float)
zetas (List[float])
t (ndarray)

Return type:

Dict[str, Any]

class transient_analysis.responseTool.core.SecondOrderModel(wn, zeta, K=None)[source]¶

Bases: object

Standard 2nd order: G(s) = K / (s^2 + 2*zeta*wn*s + wn^2).

Parameters:

wn (float)
zeta (float)
K (float | None)

K: float | None¶

system()[source]¶

Return type:: TransferFunction

wn: float¶

zeta: float¶

class transient_analysis.responseTool.core.SecondOrderSurfaceEngine[source]¶

Bases: object

Engines for standard second-order system surfaces and overlays.

Standard form:: G(s) = wn^2 / (s^2 + 2*zeta*wn*s + wn^2)

mesh(wn, zeta_grid, *, tfinal, dt)[source]¶

Return (T, Z) where Z has shape (len(zeta_grid), len(T)).

Parameters:

wn (float)
zeta_grid (ndarray)
tfinal (float)
dt (float)

Return type:

tuple[ndarray, ndarray]

static metrics_from_step(y, T, tol=0.02)[source]¶

Parameters:

y (ndarray)
T (ndarray)
tol (float)

Return type:

dict

overlays(wn, zetas, *, tfinal, dt)[source]¶

Return (T, curves) where curves[zeta] = y(T).

Parameters:

wn (float)
zetas (list[float])
tfinal (float)
dt (float)

Return type:

tuple[ndarray, dict]

static std2_tf(wn, zeta)[source]¶

Parameters:

wn (float)
zeta (float)

static step_response_1d(sys, T)[source]¶

Parameters:: T (ndarray)
Return type:: ndarray

class transient_analysis.responseTool.core.TFModel(num: 'np.ndarray', den: 'np.ndarray')[source]¶

Bases: object

Parameters:

num (ndarray)
den (ndarray)

den: ndarray¶

num: ndarray¶

system()[source]¶

transient_analysis.responseTool.io¶

class transient_analysis.responseTool.io.IOConfig(in_dir: 'Path', out_dir: 'Path')[source]¶

Bases: object

Parameters:

in_dir (Path)
out_dir (Path)

ensure()[source]¶

in_dir: Path¶

out_dir: Path¶

transient_analysis.responseTool.io.dump_ndarray(path, arr)[source]¶

Parameters:

path (Path)
arr (ndarray)

Return type:

Path

transient_analysis.responseTool.io.save_json(path, obj)[source]¶

Parameters:

path (Path)
obj (dict)

Return type:

Path

transient_analysis.responseTool.io.save_plot(path)[source]¶

Parameters:: path (Path)
Return type:: Path

transient_analysis.responseTool.design¶

Design presets (Ogata examples, canned models) for quick experiments.

class transient_analysis.responseTool.design.Presets[source]¶

Bases: object

static ogata_ss_simple()[source]¶

Return type:: SSModel

static ogata_tf_ex56()[source]¶

Return type:: TFModel