Linearize

linearize the equations of an active MapleSim model

Parameters

 options - (optional) equation(s) of the form name = value

Returns

 • By default, the Linearize command returns a DynamicSystems object that is a linearized form of a linked subsystem.  Alternatively, the user can specify format=all to return a Maple record containing complete linearization information.
 • If format = all then Linearize returns a record with the following fields:
 – stateeqs - a set of linearized state equations
 – outeqs - a set of linearized output equations
 – A - state-space Matrix $A$
 – B - state-space Matrix $B$
 – C - state-space Matrix $C$
 – D - state-space Matrix $\mathrm{D}$
 – varsubs - a list of variable name substitutions: a state, input, and output remapping list
 – linpoint - a set of equations of the form $x\left(t\right)=0$ defining the linearization point
 – dsobject - a DynamicSystems object created using linearized equations
 – params - parameter definitions
 • If implicitform=true and format=all then Linearize returns the following fields:
 – linres - a list of two sets: first set has linearized implicit expressions including those for output variables, and the second set contains all the input variables.  The presence of input variables makes the resulting system non-square (number of equations does not match the number of variables) thus the user is made aware of their presence.
 – linpoint - a set of equations of the form $x\left(t\right)=0$ defining the linearization point
 – dsobject - a DynamicSystems object created using linearized expressions
 – params - parameter definitions

Options

 • ics = set
 Specifies the system's initial condition override equations of the form variable = value, for example $x\left(t\right)=5$. These will be used as overrides during the computation of the initial point for the model. The default initial value stored in a model will be used for any variables for which an override value is not provided.  The model is then initialized with default and override values. Note that the only case where an override value is guaranteed to match the computed initial value is when the corresponding variable has a fixed initial condition.  Any default or override values for fixed initial conditions must be consistent.
 • inputs = list
 A list of the system's inputs. The default value is the linked model A subsystem's inputs.
 • outputs = list
 A list of the system's outputs. The default value is the linked model A subsystem's outputs.
 • params = list
 Specifies a list of parameter equations of the form name = value for parameters that should be left in symbolic form in the linearized equations.  The numerical value of the parameter (the right hand side) will be used to compute the initial and equilibrium points.
 • paramcheck = true or false
 Specifies if parameter analysis should be performed on the linked subsystem.  If set to true, then each of the params occurring in the equations is analyzed for its effect on the model. If it is determined to affect the structure of the linearized equations then its value is substituted into the system prior to linearization since that value is not free to change. If the parameter does not affect the structure of the linearized equations then it is free to appear as a symbolic parameter in the linearized system. If this option is set to false then this check is skipped and all parameters will be left in their symbolic form in the linearized equations even though changing their values may make the linearized system invalid. The default is true.
 • baumgarte = list
 Specifies derivative (alpha) and proportional (beta) gains for Baumgarte constraint stabilization in the form baumgarte=[alpha,beta].  These values are scale factors used for the constraints during the linearization process. If this option is set to an empty list, the default, then the Baumgarte stabilization is not used and the constraint equations are used to reduce the order of the system.
 • format = 'DynamicSystems' or 'all'
 Specifies whether the linearized subsystem should be returned as a DynamicSystems object or a record containing complete linearization information.  The default is DynamicSystems. See the Return section for the description of these output forms.
 • implicitform = true or false
 Specifies if the linearization process should skip an explicit solve of the linearized equations and return an implicit set of linearized expressions. This option should be used when the system has symbolic parameters and thus obtaining an explicit form can be expensive. When the system has constraints and the baumgarte option is not used, additional dummy variables will be introduced to account for higher order constraints.  These are algebraic variables starting with "_derN_" where N is the order of the derivative variable that was eliminated. This option is set to false by default.
 • inputdata = set or list
 Specifies a set or list of equations of the form $x\left(t\right)=\mathrm{value}$ that should be used as overrides for input values.  These values are then used in the equilibrium point computation and linearization instead of the values specified in the linked subsystem. Adding many input overrides may result in an inconsistent set of equations if the values are not consistent to within an appropriate precision.
 • linpoint = one of 'icpoint' or 'eqpoint'
 Specifies whether the equations should be linearized around an equilibrium point or the initial point. The default is icpoint.
 • nosubs = true or false
 Specifies whether the parameters and initial conditions are entered as the original model names or the shortened, substituted names.  Setting nosubs=true avoids substitution and returns long form names. The default is false.
 • useoffset = true or false
 Specifies if offsets (linearization points as they appear in the variable substitution lists) should be included in the DynamicSystems object creation.  The default is true.

Description

 • The Linearize command returns a DynamicSystems model that is a linearized form of a linked subsystem, one that can be represented in first-order form:

$\frac{ⅆ}{ⅆt}x\left(t\right)=f\left(x\left(t\right),u\left(t\right)\right)$

$y\left(t\right)=g\left(x\left(t\right),u\left(t\right)\right)$

 where:

$x\left(t\right)$ represents the state variables;

$u\left(t\right)$ represents the input variables specified by inputs;

$y\left(t\right)$ represents the output variables specified by outputs;

$f$ and $g$ are functions to be linearized;

 • The output of Linearize can also be represented in state-space form:

$\frac{ⅆ}{ⅆt}x\left(t\right)=A\left(x\left(t\right)-{x}_{0}\right)+B\left(u\left(t\right)-{u}_{0}\right)+f\left({x}_{0},{u}_{0}\right)$

$y\left(t\right)=C\left(x\left(t\right)-{x}_{0}\right)+\mathrm{D}\left(u\left(t\right)-{u}_{0}\right)+g\left({x}_{0},{u}_{0}\right)$

 where $A=\frac{\partial }{\partial x}f$, $B=\frac{\partial }{\partial u}f$, $C=\frac{\partial }{\partial x}g$, and $\mathrm{D}=\frac{\partial }{\partial u}g$ are the Jacobian matrices evaluated at the linearization point (${x}_{0},{u}_{0}$), which is the equilibrium or initial point.  At the equilibrium point $f\left({x}_{0},{u}_{0}\right)=0$ and $g\left({x}_{0},{u}_{0}\right)=0$.  At the initial point $f\left({x}_{0},{u}_{0}\right)$ may not be zero but this offset value will be returned in the equations.
 • The linearization algorithm uses an initial point of the system in order to compute its equilibrium point (where derivatives of states are set to zero).  If no equilibrium point can be found then the user is invited to linearize the system around the initial point. The ics option can be used to affect the computation of the initial point.
 • The system must have state variables or output equations in order for linearization to occur. If there are output equations but no states then the state-space matrices $A$, $B$, and $C$ will be empty and only the $\mathrm{D}$ matrix representing the $y\left(t\right)=\mathrm{D}u\left(t\right)$ part of the linearized system will be populated.
 • The Linearize command provides information about the linearized model that can be used for various purposes, including model analysis and control design. For example, a MapleSim model with no inputs or outputs will be represented by its system matrix after linearization and this information can be used for modal analysis as shown in the Examples section.
 • The A := MapleSim:-LinkModel() statement needs to be run prior to successfully using any of the ModelObject A's export functions.

Examples

 > $\mathrm{with}\left(\mathrm{MapleSim}\right):$

Linearization point of a MapleSim model

 > $A≔\mathrm{MapleSim}:-\mathrm{LinkModel}\left('\mathrm{filename}'=\mathrm{cat}\left(\mathrm{kernelopts}\left('\mathrm{toolboxdir}'=\mathrm{MapleSim}\right),"/data/examples/RLCcircuit.msim"\right)\right):$
 > $A:-\mathrm{ListSubsystems}\left(\right)$
 $\left[{"RLC"}\right]$ (1)
 > $A:-\mathrm{SetSubsystemName}\left("RLC"\right)$
 • Call Linearize to generate a linearized, DynamicSystems model, using all the parameters in the subsystem.
 > $\mathrm{sys}≔A:-\mathrm{Linearize}\left('\mathrm{params}'=A:-\mathrm{GetParameters}\left(\right)\right):$
 > $\mathrm{sys}:-\mathrm{parameters}$
 $\left[{C}{=}{1}{,}{L}{=}{1}\right]$ (2)
 > $\mathrm{with}\left(\mathrm{DynamicSystems}\right):$
 > $\mathrm{PrintSystem}\left(\mathrm{sys}\right)$
 $\left[\begin{array}{l}{\mathbf{Diff. Equation}}\\ {\mathrm{continuous}}\\ {\mathrm{1 output\left(s\right); 1 input\left(s\right)}}\\ {\mathrm{inputvariable}}{=}\left[{\mathrm{InputSignal}}{}\left({t}\right)\right]\\ {\mathrm{outputvariable}}{=}\left[{\mathrm{OutputSignal}}{}\left({t}\right)\right]\\ {\mathrm{de}}{=}{{}\begin{array}{l}{[}\stackrel{{\mathbf{.}}}{{{x}}_{{1}}}{}\left({t}\right){=}\frac{{{x}}_{{2}}{}\left({t}\right)}{{L}}{,}\\ {}\stackrel{{\mathbf{.}}}{{{x}}_{{2}}}{}\left({t}\right){=}{-}\frac{{{x}}_{{1}}{}\left({t}\right){-}{{u}}_{{1}}{}\left({t}\right){+}{{x}}_{{2}}{}\left({t}\right)}{{C}}{,}\\ {}{{y}}_{{1}}{}\left({t}\right){=}{{x}}_{{2}}{}\left({t}\right){,}\\ {}{{x}}_{{1}}{}\left({t}\right){=}{\mathrm{I1_p_i}}{}\left({t}\right){,}\\ {}{{x}}_{{2}}{}\left({t}\right){=}{\mathrm{SC1_n_v}}{}\left({t}\right){,}\\ {}{{u}}_{{1}}{}\left({t}\right){=}{\mathrm{InputSignal}}{}\left({t}\right){,}\\ {}{{y}}_{{1}}{}\left({t}\right){=}{\mathrm{OutputSignal}}{}\left({t}\right){]}\end{array}\end{array}\right$ (3)
 > $\mathrm{BodePlot}\left(\mathrm{sys},\mathrm{parameters}=\left[C=10\right]\right)$
 • Call Linearize with format=all option to obtain the linearization point.
 > $\mathrm{sys}≔A:-\mathrm{Linearize}\left('\mathrm{params}'=A:-\mathrm{GetParameters}\left(\right),'\mathrm{format}'='\mathrm{all}'\right):$
 > $\mathrm{sys}:-\mathrm{linpoint}$
 $\left\{{\mathrm{I1_p_i}}{}\left({t}\right){=}{0.}{,}{\mathrm{SC1_n_v}}{}\left({t}\right){=}{0.}{,}{\mathrm{InputSignal}}{}\left({t}\right){=}{0}{,}{\mathrm{OutputSignal}}{}\left({t}\right){=}{0.}\right\}$ (4)

Modal analysis of a MapleSim model

 • Consider a MapleSim model of a double mass-spring-damper system
 > $A≔\mathrm{MapleSim}:-\mathrm{LinkModel}\left('\mathrm{filename}'=\mathrm{cat}\left(\mathrm{kernelopts}\left('\mathrm{toolboxdir}'=\mathrm{MapleSim}\right),"/data/examples/MassSpringDamper.msim"\right)\right):$
 • Call Linearize with paramcheck=false option to keep all symbolic parameters.
 > $\mathrm{linsys}≔A:-\mathrm{Linearize}\left('\mathrm{params}'=A:-\mathrm{GetParameters}\left(\right),'\mathrm{format}'='\mathrm{all}','\mathrm{paramcheck}'=\mathrm{false}\right):$
 • Obtain the parameter values.
 > $p≔\mathrm{linsys}:-\mathrm{params}$
 ${p}{:=}\left[{\mathrm{c1}}{=}{10}{,}{\mathrm{c2}}{=}{1}{,}{\mathrm{k1}}{=}{10000}{,}{\mathrm{k2}}{=}{1000}{,}{\mathrm{m1}}{=}{2}{,}{\mathrm{m2}}{=}{1}\right]$ (5)
 • Analyze the system matrix A.
 > $a≔\mathrm{linsys}:-A$
 ${a}{:=}\left[\begin{array}{cccc}{0}& {1}& {0}& {0}\\ {-}\frac{{\mathrm{k1}}{+}{\mathrm{k2}}}{{\mathrm{m1}}}& {-}\frac{{\mathrm{c1}}{+}{\mathrm{c2}}}{{\mathrm{m1}}}& \frac{{\mathrm{k2}}}{{\mathrm{m1}}}& \frac{{\mathrm{c2}}}{{\mathrm{m1}}}\\ {0}& {0}& {0}& {1}\\ \frac{{\mathrm{k2}}}{{\mathrm{m2}}}& \frac{{\mathrm{c2}}}{{\mathrm{m2}}}& {-}\frac{{\mathrm{k2}}}{{\mathrm{m2}}}& {-}\frac{{\mathrm{c2}}}{{\mathrm{m2}}}\end{array}\right]$ (6)
 • Get its characteristic polynomial.
 > $\mathrm{LinearAlgebra}:-\mathrm{CharacteristicPolynomial}\left(a,s\right)$
 ${{s}}^{{4}}{+}\frac{\left({\mathrm{c1}}{}{\mathrm{m2}}{+}{\mathrm{c2}}{}{\mathrm{m1}}{+}{\mathrm{c2}}{}{\mathrm{m2}}\right){}{{s}}^{{3}}}{{\mathrm{m2}}{}{\mathrm{m1}}}{+}\frac{\left({\mathrm{c1}}{}{\mathrm{c2}}{+}{\mathrm{k1}}{}{\mathrm{m2}}{+}{\mathrm{k2}}{}{\mathrm{m1}}{+}{\mathrm{k2}}{}{\mathrm{m2}}\right){}{{s}}^{{2}}}{{\mathrm{m2}}{}{\mathrm{m1}}}{+}\frac{\left({\mathrm{c1}}{}{\mathrm{k2}}{+}{\mathrm{c2}}{}{\mathrm{k1}}\right){}{s}}{{\mathrm{m1}}{}{\mathrm{m2}}}{+}\frac{{\mathrm{k1}}{}{\mathrm{k2}}}{{\mathrm{m1}}{}{\mathrm{m2}}}$ (7)
 • Get the system matrix with numeric parameters.
 > $\mathrm{An}≔\mathrm{eval}\left(\mathrm{linsys}:-A,\mathrm{linsys}:-\mathrm{params}\right)$
 ${\mathrm{An}}{:=}\left[\begin{array}{cccc}{0}& {1}& {0}& {0}\\ {-}{5500}& {-}\frac{{11}}{{2}}& {500}& \frac{{1}}{{2}}\\ {0}& {0}& {0}& {1}\\ {1000}& {1}& {-}{1000}& {-}{1}\end{array}\right]$ (8)
 • Get the eigenvalues.
 > $\mathrm{eigs}≔\mathrm{evalf}\left(\mathrm{LinearAlgebra}:-\mathrm{Eigenvalues}\left(\mathrm{An}\right)\right)$
 ${\mathrm{eigs}}{:=}\left[\begin{array}{c}{-}{0.445752358}{+}{29.85474874}{}{I}\\ {-}{0.445752358}{-}{29.85474874}{}{I}\\ {-}{2.804247642}{+}{74.83736686}{}{I}\\ {-}{2.804247642}{-}{74.83736686}{}{I}\end{array}\right]$ (9)
 • The damping ratios of the two modes are given by:
 > $\mathrm{damprat1}≔\frac{1}{\sqrt{1+{\left(\frac{\mathrm{ℑ}\left({\mathrm{eigs}}_{1}\right)}{\mathrm{ℜ}\left({\mathrm{eigs}}_{1}\right)}\right)}^{2}}}$
 ${\mathrm{damprat1}}{:=}{0.01492903810}$ (10)
 > $\mathrm{damprat2}≔\frac{1}{\sqrt{1+{\left(\frac{\mathrm{ℑ}\left({\mathrm{eigs}}_{3}\right)}{\mathrm{ℜ}\left({\mathrm{eigs}}_{3}\right)}\right)}^{2}}}$
 ${\mathrm{damprat2}}{:=}{0.03744494387}$ (11)
 • The natural frequencies of the two modes are:
 > $\mathrm{natfreq1}≔-\frac{\mathrm{ℜ}\left({\mathrm{eigs}}_{1}\right)}{\mathrm{damprat1}}$
 ${\mathrm{natfreq1}}{:=}{29.85807625}$ (12)
 > $\mathrm{natfreq2}≔-\frac{\mathrm{ℜ}\left({\mathrm{eigs}}_{3}\right)}{\mathrm{damprat2}}$
 ${\mathrm{natfreq2}}{:=}{74.88988772}$ (13)
 • The periods of the two modes are given by:
 > $\mathrm{T1}≔\mathrm{evalf}\left(\frac{2\mathrm{π}}{\mathrm{natfreq1}\sqrt{1-{\mathrm{damprat1}}^{2}}}\right)$
 ${\mathrm{T1}}{:=}{0.2104584890}$ (14)
 > $\mathrm{T2}≔\mathrm{evalf}\left(\frac{2\mathrm{π}}{\mathrm{natfreq2}\sqrt{1-{\mathrm{damprat2}}^{2}}}\right)$
 ${\mathrm{T2}}{:=}{0.08395786184}$ (15)