API Reference

Application Layer

class pid_controllers.zeroPoleTool.app.AppConfig(plant_form: 'str' = 'coeff', num: 'Optional[str]' = None, den: 'Optional[str]' = None, num_poly: 'Optional[str]' = None, den_poly: 'Optional[str]' = None, gain: 'Optional[float]' = None, zeros: 'Optional[str]' = None, poles: 'Optional[str]' = None, arch: 'str' = 'fig8-31', a_vals: 'Optional[str]' = None, b_vals: 'Optional[str]' = None, c_vals: 'Optional[str]' = None, a_range: 'Optional[Tuple[float, float]]' = None, a_n: 'Optional[int]' = None, b_range: 'Optional[Tuple[float, float]]' = None, b_n: 'Optional[int]' = None, c_range: 'Optional[Tuple[float, float]]' = None, c_n: 'Optional[int]' = None, os_min: 'float' = 0.0, os_max: 'float' = 100.0, ts_max: 'float' = 10.0, settle_tol: 'float' = 0.02, best_effort: 'bool' = False, export_json: 'bool' = False, export_csv: 'bool' = False, plots: 'List[str]' = None, no_progress: 'bool' = False, debug: 'bool' = False, rank_dist_peak_weight: 'float' = 0.0, save_prefix: 'str' = 'zp_design', plot_prefix: 'str' = 'zp_design')[source]
Parameters:

  • plant_form (str)

  • num (str | None)

  • den (str | None)

  • num_poly (str | None)

  • den_poly (str | None)

  • gain (float | None)

  • zeros (str | None)

  • poles (str | None)

  • arch (str)

  • a_vals (str | None)

  • b_vals (str | None)

  • c_vals (str | None)

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

  • a_n (int | None)

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

  • b_n (int | None)

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

  • c_n (int | None)

  • os_min (float)

  • os_max (float)

  • ts_max (float)

  • settle_tol (float)

  • best_effort (bool)

  • export_json (bool)

  • export_csv (bool)

  • plots (List[str])

  • no_progress (bool)

  • debug (bool)

  • rank_dist_peak_weight (float)

  • save_prefix (str)

  • plot_prefix (str)

a_n: int | None
a_range: Tuple[float, float] | None
a_vals: str | None
arch: str
b_n: int | None
b_range: Tuple[float, float] | None
b_vals: str | None
best_effort: bool
c_n: int | None
c_range: Tuple[float, float] | None
c_vals: str | None
debug: bool
den: str | None
den_poly: str | None
export_csv: bool
export_json: bool
gain: float | None
no_progress: bool
num: str | None
num_poly: str | None
os_max: float
os_min: float
plant_form: str
plot_prefix: str
plots: List[str]
poles: str | None
rank_dist_peak_weight: float
save_prefix: str
settle_tol: float
ts_max: float
zeros: str | None
class pid_controllers.zeroPoleTool.app.ZeroPoleApp(cfg)[source]
Parameters:

cfg (AppConfig)

run()[source]

Core Computation

class pid_controllers.zeroPoleTool.core.PlantPolys(Kp: 'float', A: 'np.ndarray', B: 'np.ndarray')[source]
Parameters:

  • Kp (float)

  • A (ndarray)

  • B (ndarray)

A: ndarray
B: ndarray
Kp: float
pid_controllers.zeroPoleTool.core.plant_polys(Gp)[source]

Factor Gp(s) = Kp * A(s)/B(s) with monic A,B.

Parameters:

Gp (TransferFunction)

Return type:

PlantPolys

pid_controllers.zeroPoleTool.core.tf_from_coeff(num, den)[source]
Return type:

TransferFunction

pid_controllers.zeroPoleTool.core.tf_from_poly(num_expr, den_expr, s)[source]
Parameters:

  • num_expr (str)

  • den_expr (str)

  • s (Symbol)

Return type:

TransferFunction

pid_controllers.zeroPoleTool.core.tf_from_zpk(zeros, poles, gain=1.0)[source]
Parameters:

gain (float)

Return type:

TransferFunction

Design Utilities

class pid_controllers.zeroPoleTool.design.Architecture[source]
build_channels(a, b, c, P)[source]
Parameters:
Return type:

Tuple[TransferFunction, TransferFunction, TransferFunction, TransferFunction, TransferFunction, List[float], float, float, float]

name: str
class pid_controllers.zeroPoleTool.design.Candidate(a: 'float', b: 'float', c: 'float', Kc: 'float', z1: 'float', z0: 'float', Gc1: 'ct.TransferFunction', Gc2: 'ct.TransferFunction', Gc_sum: 'ct.TransferFunction', T_ref: 'ct.TransferFunction', T_dist: 'ct.TransferFunction', metrics_ref: 'StepMetrics', metrics_dist: 'StepMetrics', den_cl: 'List[float]', dist_peak: 'float')[source]
Parameters:

  • a (float)

  • b (float)

  • c (float)

  • Kc (float)

  • z1 (float)

  • z0 (float)

  • Gc1 (TransferFunction)

  • Gc2 (TransferFunction)

  • Gc_sum (TransferFunction)

  • T_ref (TransferFunction)

  • T_dist (TransferFunction)

  • metrics_ref (StepMetrics)

  • metrics_dist (StepMetrics)

  • den_cl (List[float])

  • dist_peak (float)

Gc1: TransferFunction
Gc2: TransferFunction
Gc_sum: TransferFunction
Kc: float
T_dist: TransferFunction
T_ref: TransferFunction
a: float
b: float
c: float
den_cl: List[float]
dist_peak: float
metrics_dist: StepMetrics
metrics_ref: StepMetrics
z0: float
z1: float
class pid_controllers.zeroPoleTool.design.Designer(arch='fig8-31')[source]

Perform grid search and ranking for two-DOF zero placement.

Parameters:

arch (str)

search(Gp, a_grid, b_grid, c_grid, os_min, os_max, ts_max, settle_tol, dist_peak_weight=0.0, show_progress=True, debug=False)[source]
Parameters:

  • Gp (TransferFunction)

  • a_grid (List[float])

  • b_grid (List[float])

  • c_grid (List[float])

  • os_min (float)

  • os_max (float)

  • ts_max (float)

  • settle_tol (float)

  • dist_peak_weight (float)

  • show_progress (bool)

  • debug (bool)

class pid_controllers.zeroPoleTool.design.Fig8_30[source]
build_channels(a, b, c, P)[source]
Parameters:

P (PlantPolys)

name: str = 'fig8-30'
class pid_controllers.zeroPoleTool.design.Fig8_31[source]
build_channels(a, b, c, P)[source]
Parameters:

P (PlantPolys)

name: str = 'fig8-31'
class pid_controllers.zeroPoleTool.design.StepMetrics(overshoot: 'float', settling_time: 'float', rise_time: 'float', ess: 'float', tfinal_used: 'float')[source]
Parameters:

  • overshoot (float)

  • settling_time (float)

  • rise_time (float)

  • ess (float)

  • tfinal_used (float)

ess: float
overshoot: float
rise_time: float
settling_time: float
tfinal_used: float
pid_controllers.zeroPoleTool.design.linspace_or_vals(vals, rng, n)[source]
Parameters:

  • vals (List[float])

  • rng (Tuple[float, float])

  • n (int)

Return type:

List[float]

pid_controllers.zeroPoleTool.design.step_metrics(sys, settle_tol=0.02)[source]
Parameters:

  • sys (TransferFunction)

  • settle_tol (float)

Return type:

StepMetrics

Input and Output

pid_controllers.zeroPoleTool.io.export_results(prefix, plant_str, arch, Kp, A, B, cands, want_json, want_csv)[source]
Parameters:

  • prefix (str)

  • plant_str (str)

  • arch (str)

  • Kp (float)

  • A (ndarray)

  • B (ndarray)

  • cands (List[Candidate])

  • want_json (bool)

  • want_csv (bool)

Return type:

None

Utilities

pid_controllers.zeroPoleTool.utils.ensure_out_dir(base=None)[source]

Ensure output directory exists (package-local ./out by default).

Parameters:

base (str)

Return type:

str

pid_controllers.zeroPoleTool.utils.forced_xy(sys, t, u)[source]
Parameters:

  • sys (TransferFunction)

  • t (ndarray)

  • u (ndarray)

pid_controllers.zeroPoleTool.utils.parse_list_of_complex(s)[source]
Parameters:

s (str | None)

Return type:

List[complex]

pid_controllers.zeroPoleTool.utils.parse_list_of_floats(s)[source]
Parameters:

s (str | None)

Return type:

List[float]

pid_controllers.zeroPoleTool.utils.pick_tgrid_from_poles(p, safety=8.0)[source]
Parameters:

  • p (Sequence[complex])

  • safety (float)

Return type:

ndarray

pid_controllers.zeroPoleTool.utils.poly_from_string(expr, s_symbol)[source]
Parameters:

  • expr (str)

  • s_symbol (Symbol)

Return type:

List[float]

pid_controllers.zeroPoleTool.utils.pretty_tf(name, G)[source]
Parameters:

  • name (str)

  • G (TransferFunction)

Return type:

str

pid_controllers.zeroPoleTool.utils.squeeze_poly(arr_like)[source]
Return type:

ndarray