API Reference

Application Layer

class root_locus_analysis.compensatorTool.app.AppOptions(plot=None)[source]

Options for high-level app presentation.

Parameters:

plot (Sequence[str] | None)

plot: Sequence[str] | None
class root_locus_analysis.compensatorTool.app.CompensatorApp[source]

High-level orchestrator: run design, print summary, optional plots.

run(**kwargs)[source]

Execute a design run and print a summary.

Notes: - UI-only kwargs (like ‘plot’) are consumed here and not forwarded to the service layer. - This function is side-effectful (prints/plots) but returns the design result.

API Schemas

class root_locus_analysis.compensatorTool.apis.CompensatorService[source]

Façade for compensator design. Test-oriented and dependency-light.

design(case, num, den, pole, *, lead_method='bisector', cancel_at=None, manual_lead=None, nlead=1, phi_per_lead=None, phi_cap=60.0, auto_nlead=True, err='kv', target=None, factor=None, beta=None, T2=None, thetamax=5.0, magwin=(0.98, 1.02), T2max=1000.0)[source]
Parameters:

  • case (Literal['indep', 'coupled'])

  • num (str)

  • den (str)

  • pole (PoleSpec)

  • lead_method (str)

  • cancel_at (float | None)

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

  • nlead (int)

  • phi_per_lead (float | None)

  • phi_cap (float)

  • auto_nlead (bool)

  • err (str)

  • target (float | None)

  • factor (float | None)

  • beta (float | None)

  • T2 (float | None)

  • thetamax (float)

  • magwin (tuple[float, float])

  • T2max (float)

Return type:

DesignResult

class root_locus_analysis.compensatorTool.apis.PoleSpec(sstar, desc)[source]

Desired location, provided either directly or via (zeta, wn).

Parameters:

  • sstar (complex)

  • desc (str)

desc: str
static from_parts(sreal, wimag)[source]
Parameters:

  • sreal (float)

  • wimag (float)

Return type:

PoleSpec

static from_zeta_wn(zeta, wn)[source]
Parameters:

  • zeta (float)

  • wn (float)

Return type:

PoleSpec

sstar: complex

Lead Compensation

class root_locus_analysis.compensatorTool.lead.LeadCompensatorApp[source]

Small orchestrator that builds the plant from num/den, calls the service, and prints a human-friendly report.

run(*, pole, num, den, method='method1', cancel_at=None)[source]
Parameters:

  • pole (PoleSpec)

  • num (str | ndarray)

  • den (str | ndarray)

  • method (Literal['method1', 'method2'])

  • cancel_at (float | None)

Return type:

LeadDesignResult

class root_locus_analysis.compensatorTool.lead.LeadCompensatorService[source]
Lightweight service implementing Ogata lead designs:

  • Method 1 (bisector construction)

  • Method 2 (zero cancels a given real pole)

method1(G, pole)[source]
Parameters:
Return type:

LeadDesignResult

method2(G, pole, cancel_at)[source]
Parameters:

  • G (TransferFunction)

  • pole (PoleSpec)

  • cancel_at (float)

Return type:

LeadDesignResult

class root_locus_analysis.compensatorTool.lead.LeadDesignResult(method: "Literal['method1', 'method2']", sstar: 'complex', Kc: 'float', z: 'float', p: 'float', Gc: 'ct.TransferFunction', L1: 'ct.TransferFunction')[source]
Parameters:

  • method (Literal['method1', 'method2'])

  • sstar (complex)

  • Kc (float)

  • z (float)

  • p (float)

  • Gc (TransferFunction)

  • L1 (TransferFunction)

Gc: TransferFunction
Kc: float
L1: TransferFunction
method: Literal['method1', 'method2']
p: float
sstar: complex
z: float

Lag Compensation

class root_locus_analysis.compensatorTool.lag.LagCompensatorApp[source]

High-level orchestrator for lag-compensator design and reporting.

run(**kwargs)[source]

Run a lag-compensator design from caller-provided keyword arguments.

The caller provides a resolved pole specification, plant coefficients, and lag-specific options. The method prints a compact text report and returns the computed design result.

Return type:

LagDesignResult

class root_locus_analysis.compensatorTool.lag.LagCompensatorService[source]

Service layer for single-stage lag-compensator design.

The service improves the selected steady-state error constant using a requested target, an improvement factor, or a chosen beta value. It then sizes the compensator gain from the loop-magnitude condition at the desired dominant pole.

design(G, sstar, err='kv', beta=None, target=None, factor=None, z_user=None, p_user=None, T_user=None, thetamax=5.0)[source]
Parameters:

  • G (TransferFunction)

  • sstar (complex)

  • err (Literal['kp', 'kv', 'ka'])

  • beta (float | None)

  • target (float | None)

  • factor (float | None)

  • z_user (float | None)

  • p_user (float | None)

  • T_user (float | None)

  • thetamax (float)

Return type:

LagDesignResult

class root_locus_analysis.compensatorTool.lag.LagDesignResult(sstar: 'complex', Kc: 'float', z: 'float', p: 'float', beta: 'float', angle_deg: 'float', Gc: 'ct.TransferFunction', L: 'ct.TransferFunction', before: 'dict', after: 'dict')[source]
Parameters:

  • sstar (complex)

  • Kc (float)

  • z (float)

  • p (float)

  • beta (float)

  • angle_deg (float)

  • Gc (TransferFunction)

  • L (TransferFunction)

  • before (dict)

  • after (dict)

Gc: TransferFunction
Kc: float
L: TransferFunction
after: dict
angle_deg: float
before: dict
beta: float
p: float
sstar: complex
z: float
root_locus_analysis.compensatorTool.lag.choose_lag_zp_by_angle(sstar, beta, thetamax_deg=5.0, T_grid=None)[source]

Select lag zero and pole locations using an angle limit.

The search uses z equal to 1/T and p equal to 1/(beta*T). Larger T values are preferred because they place the lag network closer to the origin and reduce the effect on the desired dominant pole location.

Returns a tuple containing z, p, and the angle contribution in degrees.

Parameters:

  • sstar (complex)

  • beta (float)

  • thetamax_deg (float)

  • T_grid (ndarray | None)

Return type:

Tuple[float, float, float]

root_locus_analysis.compensatorTool.lag.lag_angle_contribution(sstar, z, p)[source]

Return the absolute lag-network angle contribution in radians.

Parameters:

  • sstar (complex)

  • z (float)

  • p (float)

Return type:

float

Parallel Compensation

class root_locus_analysis.compensatorTool.parallel.ParallelCompensatorApp[source]

Application service for series-equivalent parallel-compensation studies.

The service builds a root-locus model from block data, characteristic-equation data, or a directly supplied transfer function. It then computes the gain for a requested design point or searches along a constant-damping-ratio ray.

run(*, g1_num, g1_den, g2_num, g2_den, h_num, h_den, gcb_num, gcb_den, A_num, B_num, step_num, F_num, F_den, zeta, wn, sreal, wimag, plot=None, k_range=None, k_pts=600, locus_clip=0.01, plotly_locus=None, plotly_step=None, wn_range=None, grid=2400, no_ogata_grid=False, no_real_axis_hint=False, legend='outside', xlim=None, ylim=None, pad=1.0, mpl_grid='on', plotly_grid='on', plotly_cross_axes=False, scale=1.0, verbose=0)[source]

Run the parallel-compensation analysis and return computed solutions.

Parameters:

  • g1_num (str | None)

  • g1_den (str | None)

  • g2_num (str | None)

  • g2_den (str | None)

  • h_num (str | None)

  • h_den (str | None)

  • gcb_num (str | None)

  • gcb_den (str | None)

  • A_num (str | None)

  • B_num (str | None)

  • step_num (str | None)

  • F_num (str | None)

  • F_den (str | None)

  • zeta (float | None)

  • wn (float | None)

  • sreal (float | None)

  • wimag (float | None)

  • plot (Tuple[str, ...] | None)

  • k_range (str | None)

  • k_pts (int)

  • locus_clip (float)

  • plotly_locus (str | None)

  • plotly_step (str | None)

  • wn_range (str | None)

  • grid (int)

  • no_ogata_grid (bool)

  • no_real_axis_hint (bool)

  • legend (str)

  • xlim (List[str] | None)

  • ylim (List[str] | None)

  • pad (float)

  • mpl_grid (str)

  • plotly_grid (str)

  • plotly_cross_axes (bool)

  • scale (float)

  • verbose (int)

Return type:

List[ParallelSolution]

class root_locus_analysis.compensatorTool.parallel.ParallelSolution(sstar, wn, K, k_scaled)[source]

Computed solution point for the parallel-compensation design.

Parameters:

  • sstar (complex)

  • wn (float)

  • K (float)

  • k_scaled (float)

K: float
k_scaled: float
sstar: complex
wn: float
root_locus_analysis.compensatorTool.parallel.build_F_direct(*, F_num, F_den)[source]

Build the series-equivalent model from numerator and denominator data.

Parameters:

  • F_num (str | None)

  • F_den (str | None)

Return type:

TransferFunction | None

root_locus_analysis.compensatorTool.parallel.build_F_from_blocks(*, g1_num, g1_den, g2_num, g2_den, h_num, h_den, gcb_num, gcb_den)[source]

Build the series-equivalent transfer function from block data.

Parameters:

  • g1_num (str | None)

  • g1_den (str | None)

  • g2_num (str | None)

  • g2_den (str | None)

  • h_num (str | None)

  • h_den (str | None)

  • gcb_num (str | None)

  • gcb_den (str | None)

Return type:

TransferFunction | None

root_locus_analysis.compensatorTool.parallel.build_F_from_char_split(*, A_num, B_num)[source]

Build the series-equivalent model from characteristic-equation data.

Parameters:

  • A_num (str | None)

  • B_num (str | None)

Return type:

Tuple[TransferFunction, TransferFunction, TransferFunction] | None

root_locus_analysis.compensatorTool.parallel.compute_step_traces(*, solutions, g1_num, g1_den, g2_num, g2_den, h_num, h_den, gcb_num, gcb_den, A_num, B_num, step_num)[source]

Return a time vector and response traces for the computed solutions.

Parameters:

  • solutions (List[ParallelSolution])

  • g1_num (str | None)

  • g1_den (str | None)

  • g2_num (str | None)

  • g2_den (str | None)

  • h_num (str | None)

  • h_den (str | None)

  • gcb_num (str | None)

  • gcb_den (str | None)

  • A_num (str | None)

  • B_num (str | None)

  • step_num (str | None)

Return type:

Tuple[ndarray | None, List[Tuple[str, ndarray]]]

root_locus_analysis.compensatorTool.parallel.constant_zeta_scan(F, zeta, wn_lo, wn_hi, ngrid)[source]

Scan along a constant-damping-ratio ray and return intersection candidates.

Parameters:

  • F (TransferFunction)

  • zeta (float)

  • wn_lo (float | None)

  • wn_hi (float | None)

  • ngrid (int)

Return type:

List[Tuple[complex, float]]

root_locus_analysis.compensatorTool.parallel.plot_root_locus(F, solutions, *, kmin, kmax, kpts, clip, title, plotly_html, zeta_for_ray=None, ogata_grid=True, show_real_axis_segments=True, xlim_override=None, ylim_override=None, pad_units=1.0, legend_mode='outside', mpl_grid=True, plotly_grid=True, plotly_cross_axes=False)[source]

Plot a root locus with optional design points and HTML export.

Parameters:

  • F (TransferFunction)

  • solutions (List[ParallelSolution])

  • kmin (float | None)

  • kmax (float | None)

  • kpts (int)

  • clip (float)

  • title (str)

  • plotly_html (str | None)

  • zeta_for_ray (float | None)

  • ogata_grid (bool)

  • show_real_axis_segments (bool)

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

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

  • pad_units (float)

  • legend_mode (str)

  • mpl_grid (bool)

  • plotly_grid (bool)

  • plotly_cross_axes (bool)

Return type:

None

Utilities

root_locus_analysis.compensatorTool.utils.angle(z)[source]
Parameters:

z (complex)

Return type:

float

root_locus_analysis.compensatorTool.utils.build_logger(name='compensatorTool', level=20)[source]
Parameters:

name (str)

Return type:

Logger

root_locus_analysis.compensatorTool.utils.error_constants(L)[source]

Unity‑feedback open‑loop constants: Kp, Kv, Ka and type.

Parameters:

L (TransferFunction)

Return type:

dict

root_locus_analysis.compensatorTool.utils.parse_list(s)[source]
Parameters:

s (str)

Return type:

ndarray

root_locus_analysis.compensatorTool.utils.polyval(n, s)[source]
Parameters:

  • n (ndarray)

  • s (complex)

Return type:

complex

root_locus_analysis.compensatorTool.utils.pretty_poly(c)[source]
Parameters:

c (ndarray)

Return type:

str

root_locus_analysis.compensatorTool.utils.pretty_tf(sys)[source]
Parameters:

sys (TransferFunction)

Return type:

str

root_locus_analysis.compensatorTool.utils.tf_arrays(G)[source]
Parameters:

G (TransferFunction)

Return type:

Tuple[ndarray, ndarray]

root_locus_analysis.compensatorTool.utils.wrap_pi(th)[source]
Parameters:

th (float)

Return type:

float