generateMATLABFunction

Generate MATLAB functions that evaluate the state and output functions of a neural state-space object, and their Jacobians

Since R2022b

Syntax

generateMATLABFunction(nss,stateFcnName)

generateMATLABFunction(nss,stateFcnName,outputFcnName)

Description

This function generates evaluation functions for the state, output, and Jacobians of a neural state-space object. You can use these functions to simulate the neural state-space system and to generate C/C++ code for deployment purposes, for applications such as nonlinear state estimation and model predictive control. 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. 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(nss,stateFcnName) generates, in the current folder, two MATLAB functions that calculate the state of nss 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(nss,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 nss 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 nss 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 nss. 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 two states, one inputs, one 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.

Input Arguments

nss — Neural state-space system

idNeuralStateSpace object

Neural state-space system, specified as an idNeuralStateSpace object.

Example: myNrlSS

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