Main Content

generateMATLABFunction

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

    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.

    example

    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 y2(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

    collapse all

    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)

    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.4544
        0.0984
        0.3419
    
    

    Evaluate the state Jacobian function.

    [A,B] = xdotFcnJacobian(rand(3,1),rand(2,1))
    A = 3×3
    
       -0.1288   -0.3136    0.3468
        0.0013    0.0034    0.4129
        0.1110    0.1616    0.0234
    
    
    B = 3×2
    
       -0.1504   -0.0315
       -0.0011    0.0257
        0.0168    0.1618
    
    

    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

    collapse all

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

    Example: myNrlSS

    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"

    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