Class Documentation – Properties and Methods
In this section the classes are documented with their methods and properties. Only the methods which have public access are listed. All properties are READ ONLY and can only be modified within the methods of the classes.
The tool is based on object-oriented classes.
Meaning of colors:
- Yellow: Classes provided by MATLAB
- Gray: Abstract Classes provide functionalities
- White: These Classes may be instanced and used by the User
- Blue: Representation of classes created by the User
-
BaseClass This class is used to keep track of the ODESCA version.
-
Object This class stores the information about inputs, outputs and parameters including symbolic expressions, names and units.
-
ODE This class stores differential equation systems in the form
xdot = f(x,u)y = g(x,u)in symbolic variables. Furthermore, it provides a system to handle parameters and methods to organize the equation system. -
Component The class provides functionality for the creation of differential equations and their parameters. It is used as a super class for custom components which may also added to an ODESCA_System.
-
CustomComponent The custom components are created by the user. They represent the different parts of a system and are used to define the differential equations which describe the dynamic behavior. After a custom component class has been created, it can be instanced, parameterized and added to an ODESCA_System. To create a new class file for a new custom component the user may using the method “createNewComponentFile()” of the class ODESCA_Util. For more information on the utilities, see section Creation of a custom component.
-
System This class is used to combine ODESCA_Components to an ODESCA_System and analyze it with mathematical approaches. Furthermore, a nonlinear Simulink model can be created of the system. ODESCA_System is created directly by the user.
-
ControlAffineSystem This class contains the control affine representation of a nonlinear dynamic system. It stores differential equation systems in the form
xdot = f0(x)+f1(x)*uy = g(x,u)and can only be created out of an existing ODESCA_System. -
SteadyState For the handling and analysis of a systems steady states (f(x,u) = 0!) the class called SteadyState is used. It is the representation of a system in a chosen steady state and provides the functionality to approximate the system around the steady state. This is useful to analyze the behavior of the System the steady state belongs to. ODESCA_SteadyState is not existing without its linked ODESCA_System. Hence ODESCA_SteadyState vanishes when ODESCA_System is deleted.
-
Approximation All approximations attached to a ODESCA_SteadyState (e.g. a linearized or a bilinearized system) are subclasses of the class ODESCA_Approximation. ODESCA_Approximation mainly serves as an interface. ODESCA_Approximation cannot exist without ODESCA_SteadyState.
-
Linear This class is a subclass of Approximation. It represents the linear behavior of a system at the steady state the instance of this class belongs to. This makes use of the state space object (ss) of the control system toolbox and adds and improves functionalities. The main use of this class is to perform a linear analysis of a system in a steady state.
-
Bilinear This class is a subclass of ODESCA_Approximation. It stores the matrices of a bilinear system. The bilinear system represents the bilinearized ODESCA_System in its steady state.
Note all class names of the tool ODESCA start with the name ODESCA_. E.g.: the system class is called ODESCA_System.
The BaseClass is the base of all classes in ODESCA and cannot be instantiated. Every other class in ODESCA is derived from this class. The main reason for the base class to exist is to keep track of the version number of ODESCA an instance of a class was create under. For this reason, the class provides two hidden properties.
| Name | Description |
|---|---|
| version | Version of ODESCA the instance of the class was first created in |
| classDefinitionVersion | Current version of ODESCA (version of the class definition) |
The properties have a public get access.
The two properties are hidden which means they do NOT appear in the list of properties, but trust me, they are there! The properties have a public get access. The difference between version and classDefinitionVersion shows up after an instance which was saved to a .mat file is loaded. The property version is set at the first initialization of a class and never changes afterwards. The property classDefinitionVersion always matches the current ODESCA version. So if an instance of a class is created, the two properties have the same value. If an instance was saved and loaded in a later ODESCA version, the version is still the same as when it was saved but the classDefinitionVersion has changed. This properties can help with problems occurring after an instance is loaded from a .mat file.
Note, that the listed properties of the BaseClass have no own help side.
The class ODESCA_Object is the absolute base for all other classes in the tool. It provides the possibility to store everything needed to describe nonlinear differential equations, like the states, inputs, outputs and parameters. It provides methods to modify the parameters of the object and methods to get information about the object.
This class is abstract so no instance can be created. It is meant to be the super class for the classes ODESCA_Component and ODESCA_System.
| Name | Description |
|---|---|
| name | Stores the name of the instance of this class |
| param | Structure that stores the parameters used in the equations with their current value |
| p | Array that stores the symbolic counterparts for the parameters |
| paramUnits | Cell array that stores the units of the parameters |
| x | Array with the symbolic states of the system |
| u | Array with the symbolic inputs of the system |
| stateNames | Cell array that stores the names of the states |
| inputNames | Cell array that stores the names of the inputs |
| outputNames | Cell array that stores the names of the outputs |
| stateUnits | Cell array that stores the units of the states |
| inputUnits | Cell array that stores the units of the inputs |
| outputUnits | Cell array that stores the units of the outputs |
To store the nonlinear differential equations in the form of
xdot = f(x,u)
y = g(x,u)
all components of the equations (states, inputs, parameters) have to be stored as symbolic variables.
The names of the states are stored in the array stateNames and the symbolic variables representing the states are stored in the array x (e.g. x = [x1, x2, x3 …]) at the same position as the corresponding name. The inputs are stored in the same way: inputNames stores the names and u stores the corresponding symbolic variables (e.g. u = [u1, u2, u3 …]). The names of the outputs are stored in the array outputNames. There are no symbolic variables for the outputs because they do not appear inside the equations. The parameters are stored in the structure param where the name of each field is the name of the parameter and the given value is stored in the field. The symbolic representation of each parameter is stored in the array p where the position corresponds to the order of the fields (first symbolic parameter corresponds to the first field of the structure). The symbolic parameters have the same name as the parameters in the structure. The physical units of the components are stored as strings in the arrays stateUnits, inputUnits, outputUnits and paramUnits where the position corresponds to the arrays with the names. The units are mandatory even though the correctness of the strings as physical units cannot be checked.
Note that ALL properties are READ ONLY. For modification use the methods of the object.
For detailed information on each property use the MATLAB help function in the way “help ODESCA_Object.PROPERTYNAME” (E.g.: use “help ODESCA_Object.param” to get more information about how the parameters are stored.)
| Name | Description |
|---|---|
| checkParam | Checks if all parameters are set to a value |
| getInfo | Creates structure with information about states, inputs and outputs |
| getParam | Returns the values and names of the parameters as cell arrays |
| isValidSymoblic | Checks if all symbolic variables are part of the object |
| setName | Sets the name of the instance |
| setParam | Sets a parameter to a scalar numeric value or the empty |
For detailed information on each method use the MATLAB help function for the class or for the single method. E.g.: “help ODESCA_Object” or “help ODESCA_Object.METHODNAME”
ODE is short for ordinary differential equations. This class is the basic class for an ODESCA_Object. The Class provides a system to handle parameters and methods to organize the equation system. This class is used as a superclass.
| Name | Description |
|---|---|
| f | Stores the symbolic equations which describe the change of states |
| g | Stores the symbolic equations which describe the output of the system |
The equations of the outputs are stored in the array g. The equations describing the change of the states (xdot) are stored in the array f. The protected properties are meant to changed inside a sub class in a way depending on the function of the subclass.
| Name | Description |
|---|---|
| calculateNumericEquations | Calculates the numeric equations if all parameters are set |
| copyElement | Copy the element entirely |
| show | Shows the equations, states, inputs, outputs and parameters of the object |
| setAllParamAsInput | Sets all parameters as inputs of the object |
| setParamAsInput | Sets the specified parameter as an input of the object |
| switchInputs | Switches two inputs |
| switchOutputs | Switches two outputs |
| switchStates | Switches two states |
| getSymbolicStructure | Gets the symbolic structure |
The class ODESCA_Component is a child of the class ODESCA_Object. It is used to create the nonlinear differential equations, inputs, outputs, states and parameters. The creation of these parts may depend on so called construction parameters defined in the component.
Instances of subclasses of the ODESCA_Component class may be added to systems (see ODESCA_System.addComponent()). Note that the class ODESCA_Component itself is abstract so it cannot be initialized directly. Use the utility function ODESCA_Util.createNewComponentFile to create new custom components. For detailed information on the creation of custom components see chapter Creation of a custom component in this wiki.
If an instance of a subclass of the ODESCA_Component class (e.g.: the class “Pipe” is a subclass of “ODESCA_Component”) is created and has construction parameters, none of the fields except of the construction parameters are filled. The reason for this is the creation of the content depends on the construction parameters (e.g.: the number of nodes used to simulate the behavior of a pipe). To create the equations, states, inputs, outputs and parameters the construction parameters need to be set first. After all construction parameters are set, the equations can be calculated. A component without construction parameters will be fully initialized on the creation of the instance.
Note the process of adding the component will fail if there are unset construction parameters.
This class inherits from ODESCA_Object. Therefore, it is passed by reference and can be copied.
| Name | Description |
|---|---|
| constructionParam | Structure of parameters needed for the construction of the equations |
| FLAG_EquationsCalculated | Flag that determines if the equations have been calculated |
The structure constructionParam stores all parameters which are needed in the process of creating the equations, inputs, outputs and states. E.g.: A pipe always contains the same equations but the number of states depends on the number of nodes the model uses. Therefore, if a pipe is being modeled, ‘nodes’ would be set as a construction parameter. These construction parameters have to be set before the equations are created. The property FLAG_EquationsCalculated determines if the equations have been created already. It is set false before the calculation and changed to true afterwards.
Note that ALL properties are READ ONLY. For modification use the methods of the object.
For detailed information on each property use the MATLAB help function in the way “help ODESCA_Component.PROPERTYNAME” (E.g.: use “help ODESCA_Component.constructionParam” to find out more about how the construction parameters are stored.)
| Name | Description |
|---|---|
| checkConstructionParam | Checks if all construction parameters are set |
| checkEquationsCorrect | Checks if all equations were set, true if they are set |
| setConstructionParam | Set a construction parameter to a numeric value |
| tryCalculateEquations | Calculates the Equations if all construction parameters are set |
For detailed information on each method use the MATLAB help function for the class or for the single method. E.g.: “help ODESCA_Component” or “help ODESCA_Component.METHODNAME”
The class ODESCA_System is the most important class for the user. It is used to combine components into a system, to connect the equations of the components and most importantly to analyze the system with mathematical methods.
The system class is used directly by creating an instance of it. After initializing a new instance, one or more components can be added and connected. Furthermore, it is possible to add other systems.
By adding a component or system, all the equations, states, inputs, outputs and parameters are added to the existing arrays. By this means, changes inside an instance of a component, after adding to a system, will not affect the system.
Note that the name of a component is added to all states, inputs, outputs and parameters when the component is added to the system. This is necessary for the tool to work correctly and the prevention of name conflicts.
It is possible to rename a component after adding to a system, to avoid name conflicts. This is could be the case by combining two systems owning some components with the same name. Otherwise these components will be renamed.
The utility functions provide a possibility to create a nonlinear Simulink model from the system. For more information on utility functions see the chapter Utility.
A subpart of the system is the steady state. In this state the system is in an equilibrium which means with constant inputs the states are also constant:
xdot = f(x_0,u_0 )=0 !
The steady states are used for linear analysis of the nonlinear system. Each steady state has a reference to the system it belongs to and a system has a list of all its steady states. The steady states are represented in the class ODESCA_SteadyState .
Use the methods createSteadyState() to create a new steady state for a system. They can be deleted with the method removeSteadyState() or by calling the delete() method on the instance of a steady state.
The class ODESCA_System inherits from ODESCA_Object. Therefore it is passed by reference and can be copied. Note that on creating a copy of the system, all steady states are copied and do not depend on the original instance of ODESCA_System.
| Name | Description |
|---|---|
| components | Names of components which have been added to the system |
| defaultSampleTime | Default size of a time step for discrete systems |
| steadyStates | List of steady states linked to the system |
The property defaultSampleTime is used as the sample time if a discrete system is created without providing a sample time. The array components stores the names of all components which have been added to the system. In the property steadyStates all steady states linked to the system are stored.
Note that ALL properties are READ ONLY. For modification use the methods of the object.
For detailed information on each property use the MATLAB help function in the way “help ODESCA_System.PROPERTYNAME” (E.g.: use “Help ODESCA_System.steadyStates” to get more information about how the steady states are stored.)
| Name | Description |
|---|---|
| addComponent | Adds a component to the system |
| addSystem | Adds the given system to the existing |
| calculateValidSteadyStates | Calculates all valid steady states and links them to the system |
| connectInput | Substitutes the chosen input with a symbolic expression |
| createControlaffineSystem | Creates a control-affine system out of the equations of the system |
| createMatlabFunction | Creates a Matlab functions out of the equations of the system |
| createNonlinearSimulinkModel | Creates a Simulink model of the ODESCA_System instance |
| createSteadyState | Creates a new ODESCA_SteadyState and links it to the system |
| createPIDController | Creates a PID controller for MIMO systems and links it to the nonlinear simulink model |
| equalizeParam | Equalizes parameter values in the same units |
| findSteadyState | Method to find steady states, can retrun one, multiple or no results |
| removeOutput | Removes an output from the system |
| removeSteadyState | Removes a steady state and its link to the system |
| renameComponent | Renames a component within a system |
| setDefaultSampleTime | Sets the default sample time of the system |
| simulateStep | Simulates a step in the nonlinear system |
| symLinearize | Linearize the equations symbolically |
For detailed information on each method use the MATLAB help function for the class or for the single method. E.g.: “help ODESCA_System” or “help ODESCA_System.METHODNAME”
This class contains the control-affine representation of a nonlinear dynamic system. Using a coordinate neighborhood, a control-affine system has the form:
xdot = f0(x) + ∑ fi(x) * ui
If the system equations are already in the control-affine form, the property approxflag is set to false. Otherwise, first order low passes with small time constant are added in order to get a control affine approximation. In this case, the property approxflag is set to true.
This class can only be created with the method createControlAffineSystem() of the class ODESCA_System. An instance of this class belongs to an ODESCA_System instance at every time. If the instance is deleted, the instance of this class will be deleted too.
| Name | Description |
|---|---|
| f0 | Array with the part f0(x) of the symbolic equations for the state changes |
| f1 | Array with the part f1(x) of the symbolic equations for the state changes |
| approxflag | Array with the Boolean variable that indicate if approximation was used |
| system | System that belongs to the created control-affine system |
The array f0 stores the equation parts form the initialized system which contains no inputs. Hence f1 stores the parts which contains inputs. As mentioned earlier, if the inputs are nonlinear, an approximation with a first order low pass is signaled through the approxflag.
Methods for control-affine system are not implemented jet.
A steady state of a system is a state, where all the inputs and states (and thereby outputs) are constant over time:
xdot = f(x_0,u_0 ) = 0 !
In this state a nonlinear system can be analyzed in many ways. Approximations of a system in a steady state (like linearization, bilinearization, etc) can be calculated. These approximations can be used to perform analysis of a system in the steady state. A list of all approximations in the steady state is stored in the property approximations. The steady state and its approximations have references of each other.
To create a steady state, the method createSteadyState(x0, u0) of the class ODESCA_System need to be used. It returns a new instance of the class steady state.
Logically a steady state cannot exist without an instance of the class ODESCA_System. Therefor if the system is deleted, the steady state will be deleted too.
Note: The steady state is completely numeric; hence all parameters of a system have to be set in order to create a steady state! To create a symbolic linearization of a system, see the method ODESCA_System.symLinearize().
The steady state has a flag called isStructuralValid. It determines the steady state matches the structure of the system. If the system has no changes after the steady state was created, it is set true. Otherwise the flag is set false. For an invalid steady state, no approximations can be made. Some of the methods of the approximations might not work with an invalid steady state.
The ODESCA_SteadyState is a subclass of the MATLAB class handle so the instances is passed by reference and can be stored in variables.
| Name | Description |
|---|---|
| name | Name of the steady state |
| x0 | Values of the states in the steady state |
| u0 | Values of the inputs in the steady state |
| y0 | Values of the outputs in the steady state |
| approximations | Array of the system approximations at the steady state |
| system | System instance the steady state refers to |
| param | Parameter set of the system the steady state refers to |
| structuralValid | Flag to determine if the steady state is structural valid |
| numericValid | Flag to determine if the steady state is numerical valid |
The property name stores the name of the steady state. If it is not given while creation, the steady state designated a default name. The properties x0, u0 and y0 store the values of the states, inputs and outputs for which the system is in a steady state. The approximations of a system in a steady state are stored in the property approximations. The approximations can be created with the corresponding methods. If the steady state is deleted, all approximations are deleted as well and therefore aren’t useable anymore. The property system is a reference to the ODESCA_System instance the steady state belongs to. The property param holds the parameter structure of the system the steady state refers to at the point the steady state was created. The property structuralValid determines if the system the steady belongs to has changed structural (e.g.: remove of an output, switch of equations). In this case some functions like the approximation are not possible anymore. The property numericalValid determines if the given values for x0, u0 and y0 lead to a steady state of the system. If the values are not correct in a certain rang of precision, numerical problems can occur on the analysis of the steady state. A warning is thrown in this case.
Note that ALL properties are READ ONLY. For modification use the methods of the object.
For detailed information on each property use the MATLAB help function in the way “help ODESCA_SteadyState.PROPERTYNAME” (E.g.: use “help ODESCA_SteadyState.H” to find out more about how the transfer functions are stored.)
| Name | Description |
|---|---|
| isNumericValid | Checks if the steady state is numerically valid for the system |
| setName | Sets the name of the steady state |
| delete | Custom delete() method which overwrites the default delete() |
The methods for the approximations are listed below:
| Name | Description |
|---|---|
| linearize | Calculate the linear approximation of the system in the steady state |
| linear | Returns the instances of the ODESCA_Linear class |
For detailed information on each method use the MATLAB help function for the class or for the single method. E.g.: “help ODESCA_SteadyState” or “elp ODESCA_SteadyState.METHODNAME”
The approximation class serves as an interface for all approximations which can be created of a system in a steady state. It specifies the behavior for the deletion and the reference to the steady state it belongs to. An approximation cannot exist without a steady state.
The class is abstract and cannot be instanziated. It is a subclass of matlab.mixin.heterogeneous which means all subclasses which derive from approximation can be stored in the same array even so they may have different properties and methods.
| Name | Description |
|---|---|
| steadyState | Steady State the approximation belongs to |
The property steadyState is a reference to the steady state the approximation belongs to. Since an approximation cannot exist without a steady state, this property is always filled. If the steady state it refers to is deleted, this approximation is deleted too.
| Name | Description |
|---|---|
| delete | Custom delete() method which overwrites the default delete() |
The class approximation overwrites the default delete() behavior to make sure the delete method is called correctly. If the method is called at an approximation, the reference to the approximation is automatically removed from the steady state it belongs to.
The class Linear represents the linear approximation of a system in a steady state. It has the form
xdot = (A x x) + (B x u)
y = (C x x) + (D x u)
where the Matrices A, B, C and D are numeric.
The class provides a number of method for the linear analysis of the system like the plotting of bode- and nyquist plots or the analysis of stability, controllability and observability.
The linear class contains a state space object (ss) and a transfer function object (tf) of the control system toolbox which represent the same linearization. The methods of the class linear make use of the functionalities of the control system toolbox and extend them.
The methods of this class are designed to work with arrays of the class to make analysis and comparison as easy as possible.
The instances of the class have to belong to a steady state. If the steady state the instance belongs to is deleted, the instance is deleted too.
| Name | Description |
|---|---|
| A | Time continuous system matrix |
| B | Time continuous input matrix |
| C | Output matrix |
| D | Feedthrough matrix |
| Ad | Time discrete system matrix |
| Bd | Time discrete input matrix |
| K | State feedback gain |
| L | Observer feedback gain |
| V | Precompensation matrix |
| form | Form of the system matrices (canonical forms or normal forms) |
| discreteSampleTime | Default sample time of the system the steady state refers to |
| ss | State space model of the linearization |
| tf | Transfer functions of the linearization |
The properties A, B, C and D store the system matrices of a LTI system. Ad and Bd store the time discrete counterparts of the A and B. The property discreteSampleTime stores the sample time with which the discrete matrices Ad and Bd where calculated. The property ss stores a state space object (ss) of the control system toolbox. It contains all information available in the system, the linearization’s steady state belongs to and is set up for the time continuous linear system. The property tf stores a transfer function object (tf) of the control system toolbox. The properties K, L and V store state feedback gain, observer feedback gain and the precompensation matrix. This are needed for create an observer or a full state feedback controller.
| Name | Description |
|---|---|
| bodeplot | Plots the bode diagram for the linearization |
| createFSF | Creates a full state feedback controller |
| createKalmanFilter | Creates a kalman filter |
| createLQR | Creates a linear quadradic controller |
| createLuenbergerObserver | Creates a Luenberger observer |
| discretize | Calculates the discrete linear matrices |
| isAsymptoticStable | Checks if the linearizations are asymptotically stable |
| isControllable | Checks if the linearizations are observable |
| isObservable | Checks if the linearizations are controllable |
| nyquistplot | Plots the nyquist diagram for the linearization |
| stepplot | Plots the step response for the linearization |
| toCCF | Creates the controllable canonical form of the linear system |
| toOCF | Creates the observable canonical form of the linear system |
The method bodeblot() creates a bodeplot for the linearization's. It can take multiple name-value-pair arguments to specify the plotting behavior. Refer to Getting Started for an example on how to use bodeplot.
For the creation of a full state feedback controller refer to Example: State Controller for an Inverted Pendulum.
NOTE: The methods of the class steady state are designed to work for arrays of the class! This is useful to compare linear approximations with little effort.
For detailed information on each method use the MATLAB help function for the class or for the single method. E.g.: “help ODESCA_Linear” or “help ODESCA_Linear.METHODNAME”
The linearized model mentioned is sometimes inadequate, and there is a growing need for a better approximation of the nonlinear system when robust behavior of nonlinear systems is required over the complete operating range. One method to deal with systems of this type
xdot(t) = f0(x) + ∑ gi(x) * ui(t)
y(t) = g(x)
is bilinearization.
This class represents the bilinearization of a nonlinear dynamic system in a steady state. The bilinearisation is described with the matrices A, B, C, D, G, M and N. It has the form
xdot = A*x + ∑(u_i * G_i * u) + ∑(u_i * N_i * x) + ∑(x_i * M_i * x) + B*u y = C*x + D*u
where m is the number of inputs and n is the number of states. The matrices A, B, C and D are equal to the matrices of a linear approximation.
The matrices G, N and M take into account if different states and/or inputs are multiplied with each other in the nonlinear system equations. Hence a multiplication of a state or an input with itself would represent a nonlinearity, the corresponding matrix entries are 0.
The instances of the class have to belong to a steady state. If the steady state the instance belongs to is deleted, the instance is deleted too.
| Name | Description |
|---|---|
| A | Time continuous system matrix |
| B | Time continuous input matrix |
| C | Output matrix |
| D | Feedthrough matrix |
| G | Matrix for input-input bilinearity |
| N | Matrix for input-state bilinearity |
| M | Matrix for state-state bilinearity |
| discreteSampleTime | Default sample time of the system the steady state refers to |
Methods for bilinear approximations are not implemented jet.
Refer to Example: Bilinear Estimator for a Plate Heat Exchanger for a detail view on how to use a bilinear estimator.
In addition to the classes mentioned in the section above, the tool provides a number of utility functions which provide interfaces to other programs and some additional features. These features may have additional toolboxes or programs as requirement to be used. They are grouped in the class ODESCA_Util where the utility functions are static methods which can be called without creating an instance of the class.
List of all utility functions:
| Name | Description | Requirement |
|---|---|---|
| createNewComponentFile | Starts a dialog to create a new custom component file from a template | None |
| toPDF | Creates a .pdf which documents a ODESCA_Object class in latex style | MiKTeX (v2.9) |