generateMATLABFunction

Generate MATLAB functions that evaluate the state and output functions, and their Jacobians, of a nonlinear grey-box or neural state-space model

Since R2022b

Syntax

generateMATLABFunction(sys,stateFcnName)

generateMATLABFunction(sys,stateFcnName,outputFcnName)

Description

This function generates evaluation functions for the state, output, and Jacobians of a nonlinear grey-box model or a neural state-space model without autoencoder. You can use these functions to simulate the neural state-space or nonlinear grey-box system and to generate C/C++ code for deployment purposes, for applications such as nonlinear state estimation and model predictive control.

For a nonlinear grey-box model, if the file defining the model structure is a MEX file, you cannot generate the evaluation function for the Jacobians of the state and output functions. For information on nonlinear grey-box models, see idnlgrey.

For a neural state-space model, to properly execute, the generated functions require the Deep Learning Toolbox™ and the data files that store network information, which are also generated in the process. To generate C/C++ code, the state and output networks of the neural state-space model should be multi-layer perceptron (MLP) networks created using createMLPNetwork with tanh, sigmoid, or relu as the activation function. For more information on the state and output functions of a neural state-space object, see the corresponding properties of idNeuralStateSpace.

For more information on Nonlinear MPC design, see Nonlinear MPC (Model Predictive Control Toolbox).

generateMATLABFunction(sys,stateFcnName) generates, in the current folder, two MATLAB functions that calculate the state of sys and its Jacobians, respectively. The second argument is the desired name of the state function. The state Jacobians function has the same name with the suffix Jacobian attached at the end. If stateFcnName is empty, no state function or data file is generated.

generateMATLABFunction(sys,stateFcnName,outputFcnName) also specifies the name of the output function as a third argument. The output Jacobians function has the same name with the suffix Jacobian attached at the end. If outFcnName is empty, no output function or data file is generated.

Note

When a neural state-space object has a number of outputs equal to its number of states, the generated output returns only the states. Therefore its Jacobian with respect to the state (the C matrix) is an identity and its Jacobian with respect to the input (the D matrix) is zero.

When a neural state-space object has a number of outputs greater than its number of states, the generated output function only contains the non-trivial outputs, that is the ones related to y₂(t) = H(t,x,u). In other words, the generated function is only based on the second network in the OutputNetwork property of the object. For more information, see idNeuralStateSpace.

Examples

Generate MATLAB Functions from Neural State-Space Object

Use idNeuralStateSpace to create a continuous-time neural state-space object with three states, two inputs, one non-trivial output, and direct feedthrough from input to output.

nss = idNeuralStateSpace(3,NumInputs=2,NumOutputs=3+1,HasFeedthrough=true)

nss =

Continuous-time Neural State-Space Model with 4 outputs, 3 states, and 2 inputs
     dx/dt = f(x(t),u(t))
    y_1(t) = x(t) + e_1(t)
    y_2(t) = g(x(t),u(t)) + e_2(t)
      y(t) = [y_1(t); y_2(t)]
 
f(.) network:
  Deep network with 2 fully connected, hidden layers
  Activation function: tanh
g(.) network:
  Deep network with 2 fully connected, hidden layers
  Activation function: tanh
 
Inputs: u1, u2
Outputs: y1, y2, y3, y4
States: x1, x2, x3
 
Status:                                                         
Created by direct construction or transformation. Not estimated.

The state and output networks of nss are initialized randomly. Fix the random generator seed for reproducibility.

rng(0)

Use generateMATLABFunction to generate evaluation functions for the state, the output, and their Jacobians, from nss.

generateMATLABFunction(nss,"xdotFcn","yFcn")

Evaluate the state function.

xdotFcn(rand(3,1),rand(2,1))

ans = 3×1

   -0.2074
   -0.4935
   -0.2605

Evaluate the state Jacobian function.

[A,B] = xdotFcnJacobian(rand(3,1),rand(2,1))

A = 3×3

   -0.6743    0.3073    0.0554
   -0.1970   -0.3229   -0.0754
   -0.1016   -0.0782   -0.2600

B = 3×2

    0.0081   -0.0416
   -0.0484   -0.0686
   -0.0570    0.0577

Display the Jacobian of the output function.

type("yFcnJacobian")

function [C, D] = yFcnJacobian(x,u)
%% auto-generated output Jacobian function of neural state space system
%# codegen
C1 = eye(3);
D1 = zeros(3,2);
persistent OutputNetwork
MATname = 'yFcnData';
if isempty(OutputNetwork)
    OutputNetwork = coder.load(MATname);
end
out = [x;u];
J = eye(length(out));
% hidden layer #1
Jfc = OutputNetwork.fc1.Weights;
out = OutputNetwork.fc1.Weights*out + OutputNetwork.fc1.Bias;
Jac = deep.internal.coder.jacobian.tanh(out);
out = deep.internal.coder.tanh(out);
J = Jac*Jfc*J;
% hidden layer #2
Jfc = OutputNetwork.fc2.Weights;
out = OutputNetwork.fc2.Weights*out + OutputNetwork.fc2.Bias;
Jac = deep.internal.coder.jacobian.tanh(out);
out = deep.internal.coder.tanh(out);
J = Jac*Jfc*J;
% output layer
J = OutputNetwork.output.Weights*J;
% generate Jacobian matrices
C2 = J(:,1:3);
D2 = J(:,4:5);
C = [C1; C2];
D = [D1; D2];

You can use these functions to simulate the neural state-space system and to generate C/C++ code for deployment purposes.

Generate MATLAB Functions from Nonlinear Grey-Box Model Object

Load data.

load('dcmotordata');
z = iddata(y,u,0.1,'Name','DC-motor');

The data is from a linear DC motor with one input (voltage), and two outputs (angular position and angular velocity). The structure of the model is specified by dcmotor_m.m file.

Create a nonlinear grey-box model.

file_name = 'dcmotor_m';
Order = [2 1 2];
Parameters = [1;0.28];
InitialStates = [0;0];

nlgr = idnlgrey(file_name,Order,Parameters,InitialStates,0, ...
    'Name','DC-motor')

nlgr =

Continuous-time nonlinear grey-box model defined by 'dcmotor_m' (MATLAB file):

   dx/dt = F(t, x(t), u(t), p1, p2)
    y(t) = H(t, x(t), u(t), p1, p2) + e(t)

 with 1 input(s), 2 state(s), 2 output(s), and 2 free parameter(s) (out of 2).

Name: DC-motor

Status:                                                         
Created by direct construction or transformation. Not estimated.

Fix the random number seed for reproducibility.

rng(0)

Use generateMATLABFunction to generate evaluation functions for the state, the output, and their Jacobians, from nlgr.

generateMATLABFunction(nlgr,"xdotFcn")

Evaluate the state function.

xdotFcn(rand(2,1),rand(1))

ans = 2×1

    0.9058
   -0.8702

Evaluate the state Jacobian function.

[A,B] = xdotFcnJacobian(rand(2,1),rand(1))

A = 2×2

     0     1
     0    -1

B = 2×1

         0
    0.2800

Input Arguments

sys — Neural state-space or nonlinear grey-box system

idNeuralStateSpace object | idnlgrey object

Neural state-space system, specified as an idNeuralStateSpace object or a nonlinear grey-box system, specified as an idnlgrey object.

stateFcnName — Name of the generated state function

string | character vector

Name of the generated state function, specified as a string or character vector. If a file with the specified name (with .m extension) already exists in the current MATLAB folder, it is overwritten. If you specify an invalid file name, it is automatically converted to a valid name. A file that contains data needed to execute the function is also generated, with the same name and the .mat extension. The generated function that calculates the state Jacobians has the same name with the additional Jacobian suffix. If stateFcnName is empty, no state function or data file is generated.

Example: "xdotFcn"

outputFcnName — Name of the generated output function

string | character vector

Name of the generated output function, specified as a string or character vector. If a file with the specified name (with .m extension) already exists in the current MATLAB folder, it is overwritten. If you specify an invalid file name, it is automatically converted to a valid name. A file that contains data needed to execute the function is also generated, with the same name and the .mat extension. The generated function that calculates the output Jacobians has the same name with the additional Jacobian suffix. If outFcnName is empty, no output function or data file is generated.

Example: "yFcn"

Version History

Introduced in R2022b