API Reference

pole_placement.observerTool.cli

Command-line interface for pole_placement.observerTool.

The CLI preserves the original observer-tool subcommands:

  • design

  • closedloop

  • k0

  • select

  • sim

  • example

It also adds a sphinx-skel helper for generating a conservative, GitHub Pages friendly Sphinx documentation skeleton.

pole_placement.observerTool.cli.build_parser()[source]

Build the command-line parser.

Return type:

ArgumentParser

pole_placement.observerTool.cli.main(argv=None)[source]

Run the observerTool command-line interface.

Parameters:

argv (list[str] | None)

Return type:

int

pole_placement.observerTool.apis

class pole_placement.observerTool.apis.ClosedLoopRequest(A: 'str | list', B: 'str | list', C: 'str | list', K: 'str | list', L: 'str | list', out: 'Optional[str]' = None, config: 'Optional[str]' = None)[source]

Bases: object

Parameters:

  • A (str | list)

  • B (str | list)

  • C (str | list)

  • K (str | list)

  • L (str | list)

  • out (str | None)

  • config (str | None)

A: str | list
B: str | list
C: str | list
K: str | list
L: str | list
config: str | None = None
out: str | None = None
class pole_placement.observerTool.apis.DesignRequest(kind: 'str', A: 'str | list', C: 'str | list', poles: 'Optional[str | list]' = None, B: 'Optional[str | list]' = None, method: 'str' = 'place', G: 'Optional[str | list]' = None, Qn: 'Optional[str | list]' = None, Rn: 'Optional[str | list]' = None, csv: 'Optional[str]' = None, out: 'Optional[str]' = None, config: 'Optional[str]' = None)[source]

Bases: object

Parameters:

  • kind (str)

  • A (str | list)

  • C (str | list)

  • poles (str | list | None)

  • B (str | list | None)

  • method (str)

  • G (str | list | None)

  • Qn (str | list | None)

  • Rn (str | list | None)

  • csv (str | None)

  • out (str | None)

  • config (str | None)

A: str | list
B: str | list | None = None
C: str | list
G: str | list | None = None
Qn: str | list | None = None
Rn: str | list | None = None
config: str | None = None
csv: str | None = None
kind: str
method: str = 'place'
out: str | None = None
poles: str | list | None = None
class pole_placement.observerTool.apis.ExampleRequest(which: 'str', Ts: 'float' = 0.2)[source]

Bases: object

Parameters:

  • which (str)

  • Ts (float)

Ts: float = 0.2
which: str
class pole_placement.observerTool.apis.K0Request(A: 'str | list', B: 'str | list', C: 'str | list', K: 'str | list', L: 'Optional[str | list]' = None, mode: 'str' = 'state', ogata_extra_gain: 'Optional[float]' = None, out: 'Optional[str]' = None, config: 'Optional[str]' = None)[source]

Bases: object

Parameters:

  • A (str | list)

  • B (str | list)

  • C (str | list)

  • K (str | list)

  • L (str | list | None)

  • mode (str)

  • ogata_extra_gain (float | None)

  • out (str | None)

  • config (str | None)

A: str | list
B: str | list
C: str | list
K: str | list
L: str | list | None = None
config: str | None = None
mode: str = 'state'
ogata_extra_gain: float | None = None
out: str | None = None
class pole_placement.observerTool.apis.SelectRequest(A: 'str | list', B: 'str | list', C: 'str | list', K: 'str | list', method: 'str' = 'place', rule_of_thumb: 'Optional[str]' = None, speedup: 'float' = 5.0, sweep: 'Optional[str]' = None, steps: 'int' = 200, dlqe: 'bool' = False, G: 'Optional[str | list]' = None, Qn: 'Optional[str | list]' = None, Rn: 'Optional[str | list]' = None, csv: 'Optional[str]' = None, out: 'Optional[str]' = None, config: 'Optional[str]' = None)[source]

Bases: object

Parameters:

  • A (str | list)

  • B (str | list)

  • C (str | list)

  • K (str | list)

  • method (str)

  • rule_of_thumb (str | None)

  • speedup (float)

  • sweep (str | None)

  • steps (int)

  • dlqe (bool)

  • G (str | list | None)

  • Qn (str | list | None)

  • Rn (str | list | None)

  • csv (str | None)

  • out (str | None)

  • config (str | None)

A: str | list
B: str | list
C: str | list
G: str | list | None = None
K: str | list
Qn: str | list | None = None
Rn: str | list | None = None
config: str | None = None
csv: str | None = None
dlqe: bool = False
method: str = 'place'
out: str | None = None
rule_of_thumb: str | None = None
speedup: float = 5.0
steps: int = 200
sweep: str | None = None
class pole_placement.observerTool.apis.SimRequest(A: 'str | list', B: 'str | list', C: 'str | list', K: 'str | list', L: 'str | list', N: 'int' = 60, Ts: 'float' = 1.0, ref: 'str' = 'step', K0: 'Optional[str]' = None, k0_mode: 'str' = 'state', ogata_extra_gain: 'Optional[float]' = None, csv: 'Optional[str]' = None, out: 'Optional[str]' = None, plot: 'bool' = False, plot_type: 'str' = 'points', plotly: 'bool' = False, html: 'Optional[str]' = None, config: 'Optional[str]' = None)[source]

Bases: object

Parameters:

  • A (str | list)

  • B (str | list)

  • C (str | list)

  • K (str | list)

  • L (str | list)

  • N (int)

  • Ts (float)

  • ref (str)

  • K0 (str | None)

  • k0_mode (str)

  • ogata_extra_gain (float | None)

  • csv (str | None)

  • out (str | None)

  • plot (bool)

  • plot_type (str)

  • plotly (bool)

  • html (str | None)

  • config (str | None)

A: str | list
B: str | list
C: str | list
K: str | list
K0: str | None = None
L: str | list
N: int = 60
Ts: float = 1.0
config: str | None = None
csv: str | None = None
html: str | None = None
k0_mode: str = 'state'
ogata_extra_gain: float | None = None
out: str | None = None
plot: bool = False
plot_type: str = 'points'
plotly: bool = False
ref: str = 'step'

pole_placement.observerTool.app

class pole_placement.observerTool.app.ObserverApp[source]

Bases: object

run(req)[source]
Parameters:

req (Any)

Return type:

Dict[str, Any]

pole_placement.observerTool.core

class pole_placement.observerTool.core.MinObsDesign(Ke: 'np.ndarray', T: 'np.ndarray', Ti: 'np.ndarray', blocks: 'Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]', err_poles: 'np.ndarray')[source]

Bases: object

Parameters:

  • Ke (numpy.ndarray)

  • T (numpy.ndarray)

  • Ti (numpy.ndarray)

  • blocks (Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray])

  • err_poles (numpy.ndarray)

Ke: numpy.ndarray
T: numpy.ndarray
Ti: numpy.ndarray
blocks: Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]
err_poles: numpy.ndarray
pole_placement.observerTool.core.design_current_observer(A, C, poles, method='place')[source]
pole_placement.observerTool.core.design_minimum_order_observer(A, B, C, poles, method='place')[source]
Parameters:

  • A (numpy.ndarray)

  • B (numpy.ndarray)

  • C (numpy.ndarray)

  • poles (List[complex])

Return type:

MinObsDesign

pole_placement.observerTool.core.design_prediction_observer(A, C, poles, method='place')[source]
pole_placement.observerTool.core.dlqe_gain(A, G, C, Qn, Rn)[source]
pole_placement.observerTool.core.k0_ogata(A, B, C, K, L, extra_gain=None)[source]
Parameters:

  • A (numpy.ndarray)

  • B (numpy.ndarray)

  • C (numpy.ndarray)

  • K (numpy.ndarray)

  • L (numpy.ndarray)

  • extra_gain (float | None)

Return type:

float

pole_placement.observerTool.core.k0_state(A, B, C, K)[source]
Parameters:

  • A (numpy.ndarray)

  • B (numpy.ndarray)

  • C (numpy.ndarray)

  • K (numpy.ndarray)

Return type:

float

Parameters:

pole_grid (List[List[complex]])

pole_placement.observerTool.core.ke_rule_of_thumb(A, C, plant_poles, speedup=5.0, method='place')[source]
Parameters:

  • plant_poles (Iterable[complex])

  • speedup (float)

pole_placement.observerTool.core.minobs_step(Ke, blocks, yk, uk, eta_k)[source]
pole_placement.observerTool.core.reconstruct_xhat_from_minobs(T, yk, xbh)[source]
Parameters:

  • T (numpy.ndarray)

  • yk (numpy.ndarray)

  • xbh (numpy.ndarray)

Return type:

numpy.ndarray

pole_placement.observerTool.core.simulate_full_observer(A, B, C, K, L, x0=None, xh0=None, N=60, r=None, Ts=1.0, K0=None)[source]

pole_placement.observerTool.io

pole_placement.observerTool.io.load_yaml(path)[source]

Load a YAML file and return its top-level mapping.

Parameters:

path (str | Path) – File path to read.

Return type:

dict

pole_placement.observerTool.io.maybe_json(v)[source]

Return parsed JSON when v looks like JSON text.

Non-string values are returned unchanged. Strings that do not start with [ or { are also returned unchanged. If JSON parsing fails, the original value is returned.

Parameters:

v (Any)

Return type:

Any

pole_placement.observerTool.io.parse_matrix(s)[source]

Parse a matrix-like value from CLI, JSON, YAML, or Python objects.

Supported inputs include strings such as "1 2; 3 4", Python-style nested lists such as "[[1, 2], [3, 4]]", one-dimensional row or column vector strings, Python lists/tuples, and numpy.ndarray values.

The return value is always at least two-dimensional. Real-valued complex inputs are reduced to real arrays when possible. The final return type is a floating-point numpy.ndarray because the observer workflows expect real state-space matrices.

Parameters:

s (str | list | tuple | np.ndarray)

Return type:

np.ndarray

pole_placement.observerTool.io.parse_poles(s)[source]

Parse a pole list from a comma-separated string or Python list.

The parser accepts i or j as the imaginary-unit suffix. For example, "0.5+0.5j,0.5-0.5j" and "0.5+0.5i,0.5-0.5i" are both valid.

Parameters:

s (str | list)

Return type:

List[complex]

pole_placement.observerTool.utils

pole_placement.observerTool.utils.asjson(obj)[source]
Parameters:

obj (Any)

Return type:

str

pole_placement.observerTool.utils.eigvals_sorted(M)[source]
Parameters:

M (numpy.ndarray)

Return type:

List[complex]

pole_placement.observerTool.utils.ensure_dir(p)[source]
Parameters:

p (str | PathLike)

Return type:

Path

pole_placement.observerTool.utils.multiset_close(a, b, tol=1e-08)[source]
Parameters:

  • a (Iterable[complex])

  • b (Iterable[complex])

  • tol (float)

Return type:

bool

pole_placement.observerTool.utils.out_path(filename)[source]

If filename is None -> return None. If filename is an absolute/relative path with dirs, use as-is. If it’s just a bare filename, place it under the package ./out/.

Parameters:

filename (str | None)

Return type:

Path | None

pole_placement.observerTool.utils.save_csv_matrix(path, M, header=None)[source]
Parameters:

  • path (str | PathLike)

  • M (numpy.ndarray)

  • header (Iterable[str] | None)

Return type:

None

pole_placement.observerTool.utils.save_csv_series(path, columns)[source]
Parameters:

  • path (str | PathLike)

  • columns (Dict[str, Iterable[float]])

Return type:

None

pole_placement.observerTool.utils.save_json(path, obj)[source]
Parameters:

  • path (str | PathLike)

  • obj (Any)

Return type:

None

pole_placement.observerTool.utils.to_jsonable(obj)[source]
Parameters:

obj (Any)

Return type:

Any

pole_placement.observerTool.utils.to_python_scalar(x)[source]
Parameters:

x (Any)

Return type:

Any

pole_placement.observerTool.design

pole_placement.observerTool.design.closedloop_poles(A, B, C, K, L, out=None)[source]
pole_placement.observerTool.design.compute_k0(A, B, C, K, L=None, mode='state', ogata_extra_gain=None, out=None)[source]
pole_placement.observerTool.design.design_observer(kind, A, C, poles=None, B=None, method='place', G=None, Qn=None, Rn=None, csv=None, out=None)[source]
Parameters:

kind (str)

pole_placement.observerTool.design.select_L(A, B, C, K, method='place', rule_of_thumb=None, speedup=5.0, sweep=None, steps=200, dlqe=False, G=None, Qn=None, Rn=None, csv=None, out=None)[source]
pole_placement.observerTool.design.simulate(A, B, C, K, L, N=60, Ts=1.0, ref='step', K0=None, k0_mode='state', ogata_extra_gain=None, csv=None, out=None, plot=False, plot_type='points', plotly=False, html=None)[source]