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

Returns

Returned values from rlocus depend on how many outputs the caller requests.

Errors

How rlocus works

• Supports SISO tf objects with real or complex coefficients.
• Supports SISO ss objects by converting state-space metadata to equivalent numerator and denominator polynomials.
• Accepts an explicit finite nonnegative gain vector k.
• A native typed-integer gain vector is a declared RunMat extension and must be exactly representable at the root-locus double boundary; MATLAB compatibility mode rejects it before gathering model or gain data.
• Chooses a deterministic logarithmic gain grid when k is omitted and adds samples around real positive breakaway candidates.
• Returns r as a branches-by-gains matrix, using complex output when any branch has a nonzero imaginary component.
• Returns [r, k] for two-output calls, where k is a row vector.
• Plots branch trajectories for no-output calls and marks open-loop poles and zeros.
• Supports continuous-time and discrete-time tf models.
• 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 3

Plot a root locus

s = tf('s');
H = (s + 2) / (s^2 + 3*s + 4);
rlocus(H);
fprintf("ok\n");

Expected output:

ok

Use 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.0

How 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.

FAQ

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.

Getting started · Benchmarks · Pricing