API Reference

quadratic_control.quadraticTool.cli

Command-line interface for quadratic_control.quadraticTool.

The CLI preserves the original YAML-driven solve workflow and adds a sphinx-skel helper for generating a conservative, GitHub Pages friendly Sphinx documentation skeleton.

quadratic_control.quadraticTool.cli.build_parser()[source]

Build the command-line parser.

Return type:

ArgumentParser

quadratic_control.quadraticTool.cli.main(argv=None)[source]

Run the quadraticTool command-line interface.

Parameters:

argv (list[str] | None)

Return type:

int

quadratic_control.quadraticTool.apis

class quadratic_control.quadraticTool.apis.RunRequest(mode: 'str', infile: 'Optional[str]' = None, name: 'str' = 'case', outdir: 'str' = 'out', plot: 'str' = 'none', params: 'Optional[Dict[str, float]]' = None, sweep: 'Optional[str]' = None)[source]

Bases: object

Parameters:

  • mode (str)

  • infile (str | None)

  • name (str)

  • outdir (str)

  • plot (str)

  • params (Dict[str, float] | None)

  • sweep (str | None)

infile: str | None = None
mode: str
name: str = 'case'
outdir: str = 'out'
params: Dict[str, float] | None = None
plot: str = 'none'
sweep: str | None = None

quadratic_control.quadraticTool.app

class quadratic_control.quadraticTool.app.QuadraticApp[source]

Bases: object

run(req)[source]
Parameters:

req (RunRequest)

Return type:

str

quadratic_control.quadraticTool.core

class quadratic_control.quadraticTool.core.CTDiscretizeResult(G: 'np.ndarray', H: 'np.ndarray', Q1: 'np.ndarray', M1: 'np.ndarray', R1: 'np.ndarray')[source]

Bases: object

Parameters:

  • G (numpy.ndarray)

  • H (numpy.ndarray)

  • Q1 (numpy.ndarray)

  • M1 (numpy.ndarray)

  • R1 (numpy.ndarray)

G: numpy.ndarray
H: numpy.ndarray
M1: numpy.ndarray
Q1: numpy.ndarray
R1: numpy.ndarray
class quadratic_control.quadraticTool.core.CTtoDTWeights[source]

Bases: object

siso_ogata(a, b, T)[source]
Parameters:

  • a (float)

  • b (float)

  • T (float)

Return type:

CTDiscretizeResult

class quadratic_control.quadraticTool.core.FHResult(P_seq: 'List[np.ndarray]', K_seq: 'List[np.ndarray]', x_seq: 'List[np.ndarray]', u_seq: 'List[np.ndarray]', J: 'float')[source]

Bases: object

Parameters:

  • P_seq (List[numpy.ndarray])

  • K_seq (List[numpy.ndarray])

  • x_seq (List[numpy.ndarray])

  • u_seq (List[numpy.ndarray])

  • J (float)

J: float
K_seq: List[numpy.ndarray]
P_seq: List[numpy.ndarray]
u_seq: List[numpy.ndarray]
x_seq: List[numpy.ndarray]
class quadratic_control.quadraticTool.core.FiniteHorizonLQR[source]

Bases: object

solve(G, H, Q, R, N, S=None, M=None, x0=None)[source]
Parameters:

  • G (numpy.typing.ArrayLike)

  • H (numpy.typing.ArrayLike)

  • Q (numpy.typing.ArrayLike)

  • R (numpy.typing.ArrayLike)

  • N (int)

  • S (numpy.typing.ArrayLike | None)

  • M (numpy.typing.ArrayLike | None)

  • x0 (numpy.typing.ArrayLike | None)

Return type:

FHResult

class quadratic_control.quadraticTool.core.LyapResult(P: 'np.ndarray', J: 'Optional[float]')[source]

Bases: object

Parameters:

  • P (numpy.ndarray)

  • J (float | None)

J: float | None
P: numpy.ndarray
class quadratic_control.quadraticTool.core.LyapunovAnalyzer[source]

Bases: object

solve(G, Q, x0=None)[source]
Parameters:

  • G (numpy.typing.ArrayLike)

  • Q (numpy.typing.ArrayLike)

  • x0 (numpy.typing.ArrayLike | None)

Return type:

LyapResult

class quadratic_control.quadraticTool.core.LyapunovSweep[source]

Bases: object

solve(G_template, Q_template, param_name, start, stop, points, x0=None, stability_tol=1e-09)[source]

Sweep parameter param_name across [start, stop] with points samples. For each value, substitute into templates and try to solve the discrete Lyapunov equation G’ P G - P = -Q.

Unstable (spectral radius >= 1 - tol) or numerically unsolvable points are skipped and marked with cost +inf, so the CLI and app won’t crash.

Parameters:

  • G_template (numpy.typing.ArrayLike)

  • Q_template (numpy.typing.ArrayLike)

  • param_name (str)

  • start (float)

  • stop (float)

  • points (int)

  • x0 (numpy.typing.ArrayLike | None)

  • stability_tol (float)

Return type:

LyapunovSweepResult

class quadratic_control.quadraticTool.core.LyapunovSweepResult(P_star: 'Optional[np.ndarray]', a_star: 'Optional[float]', J_min: 'Optional[float]', grid: 'np.ndarray', Js: 'np.ndarray')[source]

Bases: object

Parameters:

  • P_star (numpy.ndarray | None)

  • a_star (float | None)

  • J_min (float | None)

  • grid (numpy.ndarray)

  • Js (numpy.ndarray)

J_min: float | None
Js: numpy.ndarray
P_star: numpy.ndarray | None
a_star: float | None
grid: numpy.ndarray
class quadratic_control.quadraticTool.core.SSLQRResult(P: 'np.ndarray', K: 'np.ndarray')[source]

Bases: object

Parameters:

  • P (numpy.ndarray)

  • K (numpy.ndarray)

K: numpy.ndarray
P: numpy.ndarray
class quadratic_control.quadraticTool.core.ServoLQR[source]

Bases: object

solve(G, H, C, Qx, Qi, R)[source]
Parameters:

  • G (numpy.typing.ArrayLike)

  • H (numpy.typing.ArrayLike)

  • C (numpy.typing.ArrayLike)

  • Qx (numpy.typing.ArrayLike)

  • Qi (numpy.typing.ArrayLike)

  • R (numpy.typing.ArrayLike)

Return type:

ServoResult

class quadratic_control.quadraticTool.core.ServoResult(P: 'np.ndarray', Kx: 'np.ndarray', Ki: 'np.ndarray', K_full: 'np.ndarray')[source]

Bases: object

Parameters:

  • P (numpy.ndarray)

  • Kx (numpy.ndarray)

  • Ki (numpy.ndarray)

  • K_full (numpy.ndarray)

K_full: numpy.ndarray
Ki: numpy.ndarray
Kx: numpy.ndarray
P: numpy.ndarray
class quadratic_control.quadraticTool.core.SteadyStateLQR[source]

Bases: object

solve(G, H, Q, R)[source]
Parameters:

  • G (numpy.typing.ArrayLike)

  • H (numpy.typing.ArrayLike)

  • Q (numpy.typing.ArrayLike)

  • R (numpy.typing.ArrayLike)

Return type:

SSLQRResult

quadratic_control.quadraticTool.core.substitute_params_matrix(template, params)[source]

Substitute numeric values into a matrix template that may contain strings (expressions or parameter names). Safe locals are only the provided params.

Parameters:

  • template (numpy.typing.ArrayLike)

  • params (Dict[str, float])

Return type:

numpy.ndarray

quadratic_control.quadraticTool.io

quadratic_control.quadraticTool.io.load_yaml(path)[source]
Parameters:

path (str)

Return type:

Dict[str, Any]

quadratic_control.quadraticTool.io.save_csv_matrix(path, M)[source]
Parameters:

  • path (str)

  • M (numpy.ndarray)

Return type:

None

quadratic_control.quadraticTool.io.save_csv_vector(path, vec)[source]
Parameters:

  • path (str)

  • vec (Iterable[float])

Return type:

None

quadratic_control.quadraticTool.io.write_text(path, text)[source]
Parameters:

  • path (str)

  • text (str)

Return type:

None

quadratic_control.quadraticTool.utils

quadratic_control.quadraticTool.utils.ensure_dir(d)[source]

Create a directory when it does not already exist.

Parameters:

d (str)

Return type:

None

quadratic_control.quadraticTool.utils.in_path(*parts)[source]

Return a path inside the package input directory.

Parameters:

parts (str)

Return type:

str

quadratic_control.quadraticTool.utils.native_to_np(x)[source]

Convert JSON-friendly values produced by np_to_native back to arrays.

Dictionaries containing a __ndarray__ key are converted to NumPy arrays with dtype=float. Lists and dictionaries are processed recursively. Plain scalar values are returned unchanged.

Parameters:

x (Any)

Return type:

Any

quadratic_control.quadraticTool.utils.np_to_native(x)[source]

Convert NumPy objects into JSON-friendly Python values.

Arrays are represented as dictionaries with a __ndarray__ key. NumPy scalar values are converted with item. Lists, tuples, and dictionaries are processed recursively. Other values are returned unchanged.

Parameters:

x (Any)

Return type:

Any

quadratic_control.quadraticTool.utils.out_path(*parts)[source]

Return a path inside the package output directory.

Parameters:

parts (str)

Return type:

str

quadratic_control.quadraticTool.utils.pkg_path(*parts)[source]

Return a path relative to the package directory.

Parameters:

parts (str)

Return type:

str

quadratic_control.quadraticTool.utils.setup_logging(level='INFO')[source]

Initialize basic logging with a compact readable format.

Parameters:

level (str)

Return type:

None

quadratic_control.quadraticTool.utils.timeit(fn)[source]

Return a wrapper that yields the wrapped result and elapsed seconds.

The decorated callable returns a two-item tuple. The first item is the original return value from the wrapped callable. The second item is the elapsed wall-clock time in seconds, measured with time.perf_counter.

Parameters:

fn (Callable[[...], Any])

Return type:

Callable[[…], Tuple[Any, float]]

quadratic_control.quadraticTool.design

quadratic_control.quadraticTool.design.plot_series_mpl(series, title, out_png, figsize=(6, 4), dpi=140, xlabel='k', ylabel='value')[source]

Save a simple scatter-style plot (markers only) with matplotlib.

Notes: - Uses a non-interactive backend for headless test environments. - Ensures the output directory exists.

Parameters:

  • series (Dict[str, numpy.ndarray])

  • title (str)

  • out_png (str)

  • figsize (tuple[int, int])

  • dpi (int)

  • xlabel (str)

  • ylabel (str)

Return type:

None

quadratic_control.quadraticTool.design.plot_series_plotly(series, title, out_html, xlabel='k', ylabel='value')[source]

Save a simple scatter plot page with Plotly.

Ensures the output directory exists before writing.

Parameters:

  • series (Dict[str, numpy.ndarray])

  • title (str)

  • out_html (str)

  • xlabel (str)

  • ylabel (str)

Return type:

None