msim

Method of mss.

Simulate an mss model over a given input trajectory.

Source: src/model/@mss/msim.m

Syntax

y = msim(sys, inputTrajectory, inputTime, initialState)
[y, t] = msim(sys, inputTrajectory, inputTime, initialState)
[y, t, x] = msim(sys, inputTrajectory, inputTime, initialState)
[...] = msim(sys, inputTrajectory, inputTime, initialState, solverOptions)
[...] = msim(sys, inputTrajectory, inputTime, initialState, solverOptions, solverType)

Description

msim is the user-facing simulation entry point for an mss model — the lsim analogue for multilinear systems. It validates the signal dimensions, hands everything to the matching simulator object, and returns the trajectories.

The model’s timeStepSize selects the scheme:

`timeStepSize`	Simulator	What it does
`0`	`continuousTimeMss`	Integrates $\dot x = f(x,u(t))$ with the MATLAB `ode` solver named by `solverType`.
`> 0`	`discreteTimeMss`	Marches $x_{k+1} = f(x_k,u_k)$ over the samples of `inputTime`.

The simulator runs inside its own constructor; msim then reads time and variableTrajectory back out and transposes the latter, so the trajectories it returns have one row per time point.

Outputs are computed on demand

The output trajectory is only evaluated when the model has outputs and a return value is asked for — one evaluation of $y = g(x,u)$ per simulated time point is not free, and for a discrete run that is one per sample. Since it is the first output, every call that takes a result pays for it, including [~, ~, x] = msim(...) for the state alone. For a CPNTensor the output block is compiled once into the MTISIM kernel form instead of calling outputValue per point. Inputs are interpolated (linear/extrap) at the solver’s time points in the continuous case and taken sample-wise in the discrete case.

Only the monomial columns are sliced when that block is compiled — the structure-matrix rows stay in model order — so the signal vector handed to the kernel is assembled by scattering the state and input through stateIndex and inputIndex. A model whose rows are not in the natural [x; u] order therefore returns the same output trajectory as its naturally-ordered twin.

Called with no output argument msim currently does nothing; plotting the trajectories the way lsim does is not implemented yet.

Validation

Two checks run before simulation, both hard errors:

numel(initialState) must equal sys.nState;
size(inputTrajectory,2) must equal sys.nInput — the message prints both counts and suggests transposing, since an input matrix laid out the wrong way round is the usual cause.

Input arguments

Argument	Description
`mssModel`	The `mss` model to simulate.
`inputTrajectory`	Input values, one column per input and one row per entry of `inputTime`.
`inputTime`	Time vector of the input trajectory. For a discrete model its spacing should match `timeStepSize` and its length sets the number of simulated samples; for a continuous model its first and last entry define the time span.
`initialState`	Initial state $x_0$ (`sys.nState` × 1).
`solverOptions`	(optional) Option struct forwarded to `applySolverOptions`; `[]` (default) uses the defaults. Unused by the discrete scheme.
`solverType`	(optional) Name of the MATLAB ODE solver, default `"ode45"`. Continuous models only; explicit Runge–Kutta solvers skip the Jacobian, others use the analytic one.

Output arguments

The order matches lsim: outputs first, then time, then states.

Output	Description
`simulatedOutput`	Output trajectory, one row per time point, one column per output; `[]` if the model has no outputs.
`simulatedTime`	Simulation time vector: the solver’s own grid (continuous) or `inputTime` (discrete).
`simulatedState`	State trajectory, one row per time point, one column per state.

Example

sys = rmss(3,1,1,4);                 % continuous-time model

t = (0:1e-3:10)';
u = sin(t);                          % one column per input
x0 = [1; 0; -1];

[y, tsim, x] = msim(sys, u, t, x0);

% stiff model: pick an implicit solver (uses the analytic Jacobian)
[y, tsim] = msim(sys, u, t, x0, [], "ode15s");

% discrete-time model: one step per sample of t
sysd = c2d(sys, 1e-3);
[~, ~, xd] = msim(sysd, u, t, x0);