API Reference

Application Layer

class frequency_response.compensatorTool.app.CompensatorApp[source]
run(spec)[source]

Dispatch to the appropriate designer based on the spec type. - LagLeadDesignSpec -> LagLeadDesigner - LeadDesignSpec -> LeadDesigner

static spec_ogata_7_28(*, backend: str = 'mpl', plots: str = 'bode,nyquist,nichols', save: str | None = None, no_show: bool = True) → LagLeadDesignSpec[source]

Convenience builder for the Ogata 7-28 preset (lag–lead).

API Schemas

class frequency_response.compensatorTool.apis.DesignOptions(Kv: float | None = None, pm_target: float | None = None, pm_allow: float = 5.0, wc_hint: float | None = None, r_lead: float = 10.0, r_lag: float = 10.0, alpha: float | None = None, beta: float | None = None, wz_lead: float | None = None, wp_lead: float | None = None, wz_lag: float | None = None, wp_lag: float | None = None, Kc: float = 1.0, ogata_7_28: bool = False)[source]

Options controlling lag-lead compensator design.

If ogata_7_28 is true, the Ogata Example 7-28 preset design is used. Otherwise, the designer can auto-scale gain to meet Kv for type-1 systems, auto-place lead and lag elements from the phase-margin target, or accept manual lead and lag parameters.

Kc: float
Kv: float | None
alpha: float | None
beta: float | None
ogata_7_28: bool
pm_allow: float
pm_target: float | None
r_lag: float
r_lead: float
wc_hint: float | None
wp_lag: float | None
wp_lead: float | None
wz_lag: float | None
wz_lead: float | None
class frequency_response.compensatorTool.apis.FrequencyGrid(wmin: float = 0.001, wmax: float = 1000.0, wnum: int = 2000)[source]

Frequency grid used for frequency-response computations and plots.

wmax: float
wmin: float
wnum: int
class frequency_response.compensatorTool.apis.LagDesignOptions(Kv: float | None = None, pm_target: float | None = None, pm_add: float = 8.0, w_ratio_z: float = 10.0, beta: float | None = None, T: float | None = None, Kc: float | None = None)[source]

Options for the lag-only designer.

A manual single-stage design can be requested with beta and T. Automatic design can be requested with pm_target. Kv can optionally auto-scale plant gain for type-1 systems before lag design.

Kc: float | None
Kv: float | None
T: float | None
beta: float | None
pm_add: float
pm_target: float | None
w_ratio_z: float
class frequency_response.compensatorTool.apis.LagDesignResult(pack: Dict[str, Any], files: List[str])[source]

Output of a lag-only design and visualization run.

The pack field contains JSON-serializable design results. The files field contains paths to artifacts written to disk.

files: List[str]
pack: Dict[str, Any]
class frequency_response.compensatorTool.apis.LagDesignSpec(plant: ~frequency_response.compensatorTool.apis.PlantSpec, design: ~frequency_response.compensatorTool.apis.LagDesignOptions, plot: ~frequency_response.compensatorTool.apis.PlotOptions = <factory>, grid: ~frequency_response.compensatorTool.apis.FrequencyGrid = <factory>)[source]

Complete specification for a lag-only design and visualization run.

design: LagDesignOptions
grid: FrequencyGrid
plant: PlantSpec
plot: PlotOptions
class frequency_response.compensatorTool.apis.LagLeadDesignResult(pack: Dict[str, Any], files: List[str])[source]

Output of a lag-lead design and visualization run.

The pack field contains JSON-serializable design results. The files field contains paths to artifacts written to disk.

files: List[str]
pack: Dict[str, Any]
class frequency_response.compensatorTool.apis.LagLeadDesignSpec(plant: ~frequency_response.compensatorTool.apis.PlantSpec, design: ~frequency_response.compensatorTool.apis.DesignOptions, plot: ~frequency_response.compensatorTool.apis.PlotOptions = <factory>, grid: ~frequency_response.compensatorTool.apis.FrequencyGrid = <factory>)[source]

Complete specification for a lag-lead design and visualization run.

design: DesignOptions
grid: FrequencyGrid
plant: PlantSpec
plot: PlotOptions
class frequency_response.compensatorTool.apis.LeadDesignOptions(Kv: float | None = None, pm_target: float | None = None, pm_add: float = 5.0, stages: int = 1, phi_split: str | None = None, alpha: float | None = None, T: float | None = None, Kc: float | None = None)[source]

Options for the lead-only designer.

A manual single-stage design can be requested with alpha and T. Automatic one-stage or multi-stage design can be requested with pm_target. Kv can optionally auto-scale plant gain for type-1 systems before lead design.

Kc: float | None
Kv: float | None
T: float | None
alpha: float | None
phi_split: str | None
pm_add: float
pm_target: float | None
stages: int
class frequency_response.compensatorTool.apis.LeadDesignResult(pack: Dict[str, Any], files: List[str])[source]

Output of a lead-only design and visualization run.

The pack field contains JSON-serializable design results. The files field contains paths to artifacts written to disk.

files: List[str]
pack: Dict[str, Any]
class frequency_response.compensatorTool.apis.LeadDesignSpec(plant: ~frequency_response.compensatorTool.apis.PlantSpec, design: ~frequency_response.compensatorTool.apis.LeadDesignOptions, plot: ~frequency_response.compensatorTool.apis.PlotOptions = <factory>, grid: ~frequency_response.compensatorTool.apis.FrequencyGrid = <factory>)[source]

Complete specification for a lead-only design and visualization run.

design: LeadDesignOptions
grid: FrequencyGrid
plant: PlantSpec
plot: PlotOptions
class frequency_response.compensatorTool.apis.PlantSpec(tf_expr: str | None = None, num: str | None = None, den: str | None = None, z: str | None = None, p: str | None = None, k: str | None = None, A: str | None = None, B: str | None = None, C: str | None = None, D: str | None = None, params: str = '')[source]

Declarative specification for the plant model.

Provide exactly one plant representation: a transfer-function expression, numerator and denominator coefficients, zero-pole-gain data, or state-space matrices.

The params field can provide named constants for transfer-function parsing, using a string such as “K=4,T=0.2”.

A: str | None
B: str | None
C: str | None
D: str | None
den: str | None
k: str | None
num: str | None
p: str | None
params: str
tf_expr: str | None
z: str | None
class frequency_response.compensatorTool.apis.PlotOptions(backend: str = 'mpl', plots: str = 'bode,nyquist,nichols,step,ramp', ogata_axes: bool = False, nichols_templates: bool = False, nichols_Mdb: List[float] | None = None, nichols_Ndeg: List[float] | None = None, nyquist_M: List[float] | None = None, nyquist_marks: List[float] | None = None, save: str | None = None, save_img: str | None = None, export_json: str | None = None, export_csv_prefix: str | None = None, no_show: bool = False, verbose: bool = False, show_unstable: bool = False)[source]

Plotting, export, and runtime options.

The numeric list fields can be populated by the CLI from space-separated or comma-separated inputs. If a list field is None, the default behavior for that feature applies.

backend: str
export_csv_prefix: str | None
export_json: str | None
nichols_Mdb: List[float] | None
nichols_Ndeg: List[float] | None
nichols_templates: bool
no_show: bool
nyquist_M: List[float] | None
nyquist_marks: List[float] | None
ogata_axes: bool
plots: str
save: str | None
save_img: str | None
show_unstable: bool
verbose: bool

Core Lag-Lead Engine

frequency_response.compensatorTool.core.eval_L(G: TransferFunction, w: ndarray) → ndarray[source]
frequency_response.compensatorTool.core.frequency_response_arrays(G: <module 'control.lti' from '/opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages/control/lti.py'>, w: ~numpy.ndarray)[source]
frequency_response.compensatorTool.core.get_margins(G: <module 'control.lti' from '/opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages/control/lti.py'>) → Tuple[float, float, float, float][source]
frequency_response.compensatorTool.core.is_stable(sys: <module 'control.lti' from '/opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages/control/lti.py'>) → bool[source]
frequency_response.compensatorTool.core.kv_of_tf(sys_tf: TransferFunction) → float[source]
frequency_response.compensatorTool.core.nichols_templates(Mdb_list, Ndeg_list, phase_span=(-360.0, 0.0), npts=800)[source]
frequency_response.compensatorTool.core.set_gain_for_Kv(G: <module 'control.lti' from '/opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages/control/lti.py'>, Kv_target: float)[source]
frequency_response.compensatorTool.core.tf_arrays(G: TransferFunction)[source]

Lead-Only Engine

class frequency_response.compensatorTool.lead.LeadDesigner[source]
run(spec: LeadDesignSpec) → LeadDesignResult[source]
class frequency_response.compensatorTool.lead.LeadStage(alpha: 'float', T: 'float', wz: 'float', wp: 'float')[source]
T: float
alpha: float
wp: float
wz: float

Lag-Only Engine

class frequency_response.compensatorTool.lag.LagDesigner[source]

Lag-only designer (Ogata-style; single-stage auto/manual).

run(spec: LagDesignSpec) → LagDesignResult[source]
class frequency_response.compensatorTool.lag.LagStage(beta: 'float', T: 'float', wz: 'float', wp: 'float')[source]
T: float
beta: float
wp: float
wz: float
frequency_response.compensatorTool.lag.parse_matrix(mat: str, params: dict) → ndarray[source]

Parse a semicolon/comma-separated matrix with symbol support via params.

frequency_response.compensatorTool.lag.parse_vector(vec: str | None, params: dict) → ndarray | None[source]

Parse a comma/space-separated vector with symbol support via params.

Utilities

frequency_response.compensatorTool.utils.db(x)[source]
frequency_response.compensatorTool.utils.parse_list_floats(s) → list[float] | None[source]
frequency_response.compensatorTool.utils.parse_params(s: str) → dict[source]
frequency_response.compensatorTool.utils.tf_from_expr(expr: str, params: dict) → TransferFunction[source]
frequency_response.compensatorTool.utils.undb(x_db)[source]