rlocus — Compute or plot root loci of SISO transfer-function or state-space models.
rlocus(sys, ...) plots or returns closed-loop pole locations for supported SISO tf and ss models. Roots are computed from the characteristic polynomial den(sys) + k*num(sys) for each gain value.
Syntax
r = rlocus(sys)
r = rlocus(sys, k)
[r,k] = rlocus(sys)
[r,k] = rlocus(sys, k)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
sys | Any | Yes | — | SISO tf or ss model. |
k | NumericArray | Yes | — | Finite nonnegative gain vector. |
Returns
| Name | Type | Description |
|---|---|---|
r | Any | Closed-loop pole locations as a branches-by-gains matrix. |
k | NumericArray | Gain vector used to compute the root locus. |
Returned values from rlocus depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:rlocus:InvalidArgument | Inputs do not match supported rlocus invocation forms. | rlocus: invalid argument |
RunMat:rlocus:InvalidModel | Input system is not a valid SISO tf or ss object. | rlocus: invalid model |
RunMat:rlocus:UnsupportedModel | Model form is not supported by the current implementation. | rlocus: unsupported model |
RunMat:rlocus:PlotFailed | Statement-form plotting failed for reasons other than known nonfatal setup conditions. | rlocus: plotting failed |
RunMat:rlocus:Internal | Root-locus computation or output construction failed. | rlocus: internal error |
How rlocus works
- Supports SISO
tfobjects with real or complex coefficients. - Supports SISO
ssobjects by converting state-space metadata to equivalent numerator and denominator polynomials. - Accepts an explicit finite nonnegative gain vector
k. - Chooses a deterministic logarithmic gain grid when
kis omitted and adds samples around real positive breakaway candidates. - Returns
ras a branches-by-gains matrix, using complex output when any branch has a nonzero imaginary component. - Returns
[r, k]for two-output calls, wherekis a row vector. - Plots branch trajectories for no-output calls and marks open-loop poles and zeros.
- Supports continuous-time and discrete-time
tfmodels. - Input/output delays raise clear unsupported-model diagnostics.
GPU memory and residency
rlocus returns host-resident root and gain tensors.
Examples
Return roots for explicit gains
H = tf(1, [1 1]);
[r, k] = rlocus(H, [0 1 3]);
fprintf("%.0f %.0f %.0f %.0f\n", r(1,1), r(1,2), r(1,3), k(3));Expected output:
-1 -2 -4 3Plot a root locus
s = tf('s');
H = (s + 2) / (s^2 + 3*s + 4);
rlocus(H);
fprintf("ok\n");Expected output:
okUse a discrete-time transfer function
H = tf(1, [1 -0.5], 0.1);
r = rlocus(H, 0.5);
fprintf("%.1f\n", r(1));Expected output:
0.0How RunMat validates rlocus
rlocus validates object class, delay properties, gain-vector type/shape/range, output shapes, continuous and discrete characteristic polynomials, complex roots, plotting smoke, and VM dispatch.
- Implementation: `crates/runmat-runtime/src/builtins/control/rlocus.rs`
See Correctness & Trust for the full methodology and coverage table.
Using rlocus with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how rlocus changes the result.
Run a small rlocus example, explain the result, then change one input and compare the output.
FAQ
What equation does rlocus solve?⌄
For each gain k, it computes roots of den(sys) + k*num(sys), matching unity negative-feedback root-locus convention.
Does rlocus support state-space or MIMO models?⌄
rlocus supports SISO ss models. MIMO model arrays remain unsupported by the current RunMat control-model path.
Does rlocus run on the GPU?⌄
No. It is a model-analysis operation and returns host-resident tensors.
Related Control functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how rlocus is executed, line by line, in Rust.
- View the source for rlocus in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.