sample

R2026b

(Not recommended) Sample linear parameter-varying or time-varying dynamics

Since R2023a

collapse all in page

sample is not recommended. Use psample instead (since R2024a).

Syntax

ssArray = sample(vSys,T)
ssArray = sample(vSys,T,P)
ssArray = sample(vSys,T,P1,...,Pn)
ssArray = sample(vSys,S)
ssArray = sample(vSys)
[ssArray,offsets] = sample(___)

Description

ssArray = sample(vSys,T) samples the dynamics of the linear time-varying (LTV) model vSys at the times specified in the time vector T and returns an array of time-invariant state-space (ss) models.

example

ssArray = sample(vSys,T,P) samples the dynamics of the linear-parameter varying (LPV) model vSys at the single point (T,P) and returns an array of time-invariant state-space (ss) models. Set T to [] if the dynamics of the LPV model only depend on P.

ssArray = sample(vSys,T,P1,...,Pn) samples the dynamics over a grid of (T,P) values. P1,...,Pn are arrays specifying the values of each parameter of the LPV model.

ssArray = sample(vSys,S) specifies the sample values as a structure S.

ssArray = sample(vSys) samples a gridded LTV or LPV model at values obtained from vSys.Grid. You can use this syntax as a quick way to access the state-space data and offsets used to construct the gridded LTV or LPV model.

[ssArray,offsets] = sample(___) also returns a structure array offsets containing the derivative, state, input, and output offset values at the specified times. You can use this syntax with any of the input-argument combinations in previous syntaxes.

Examples

collapse all

You can sample the dynamics of an LTV model over a point or a vector of t values to obtain affine dynamics for a given time.

Consider a model defined by the data function ltvssDataFcn.m.

Create an LTV model.

ltvSys = ltvss(@ltvssDataFcn)
Continuous-time state-space LTV model with 1 outputs, 1 inputs, and 1 states.
Model Properties

Define a set of times values to sample this model over.

t = 5:0.5:10;

Use the psample command to obtain an array of ss models.

ssArray = psample(ltvSys,t);
size(ssArray)
1x11 array of state-space models.
Each model has 1 outputs, 1 inputs, and 1 states.

In ssArray, the SamplingGrid property tracks the dependence of each model on time and the Offsets property contains the offset values as a function of time. 

ssArray.SamplingGrid
ans = struct with fields:
    Time: [5 5.5000 6 6.5000 7 7.5000 8 8.5000 9 9.5000 10]


ssArray.Offsets
ans=1×11 struct array with fields:
    dx
    x
    u
    y

View the data function.

type ltvssDataFcn.m
function [A,B,C,D,E,dx0,x0,u0,y0,Delays] = ltvssDataFcn(t)
% SISO, first order
A = -(1+0.5*sin(t));
B = 1;
C = 1;
D = 0;
E = [];
dx0 = [];
x0 = [];
u0 = [];
y0 = 0.1*sin(5*t);
Delays = [];

Input Arguments

collapse all

Varying model to sample, specified as an ltvss or lpvss object.

Time values at which the model is sampled.

  • For LTV models, specify T as a scalar or vector for real and finite values to sample the dynamics at a single time value or multiple ones, respectively.

  • For LPV models, specify T as one of the following:

    • [] — LPV model dynamics only depend only on parameters p.

    • Scalar — Sample the dynamics at a single time value.

    • Vector — Sample the dynamics at multiple time values.

    • Multidimensional array — Sample the dynamics at a grid of values. You must specify a rectangular (T,P) grid of values, such as the ones you create using ndgrid.

      [t,p1,p2,p3] = ndgrid(tvals,p1vals,p2vals,p3vals)

    The vectors or arrays T and P1,...,Pn must be of the same size.

In discrete time, specify T as integer index values k that count the number of sampling periods Ts. The absolute time is given by t = k*Ts.

Parameter values at which the LPV model is sampled.

For an LPV model with n parameters, use comma-separated arguments P1,...,Pn to specify the values for each parameter.

Specify P as one of the following:

  • Scalar — Sample the dynamics at a single parameter value.

  • Vector — Sample the dynamics at multiple parameter values.

  • Multidimensional array — Sample the dynamics at a grid of values. You must specify a rectangular (T,P) grid of values, such as the ones you create using ndgrid.

    [t,p1,p2,p3] = ndgrid(tvals,p1vals,p2vals,p3vals)

    The vectors or arrays T and P1,...,Pn must be of the same size.

Sampling grid structure array used to specify values at which the model is sampled.

  • For LTV models, S is a structure array with field Time. For example, if an array Tvalues specifies the sampling time, S is the following structure.

    S = struct('Time',Tvalues)

  • For LPV models, S is a structure with fields for parameter names corresponding to the ParameterName property of the lpvss model vSys and Time. For example, if vSys has two parameters named 'speed' and 'altitude' with values specified using arrays P1vals and P2vals, respectively, S is the following structure.

    S = struct('speed',P1vals,'altitude',P2vals)

    If the dynamics of your LPV model depend on parameter values, do not specify the field Time for S.

Output Arguments

collapse all

Sampled dynamics, returned as an array of time-invariant state-space (ss) models.

The dimensions of ssArray depend on the number of sampling points in the array or grid.

Model offsets, returned as a structure array with the same dimensions as the sampling points or grid. Each offset structure has the following fields:

FieldDescription
xState offsets, returned as a column vector of length nx, where nx is the number of states in vSys
dxDerivative offsets, returned as a column vector of length nx, where nx is the number of states in vSys
uInput offsets, returned as a column vector of length nu, where nu is the number of inputs in vSys
yOutput offsets, returned as a column vector of length ny, where ny is the number of outputs in vSys

Some fields of offsets may be [] if the offset is absent (zero) for all values of (t,p).

Version History

Introduced in R2023a

collapse all

See Also

| | | |