# Parameters: Linear Solver

Model ElementParam_Linear defines the solution control parameters for a linear analysis. These parameters control the types of linear analyses to be done and the output options.

## Description

- Eigenvalue and eigenvector calculations for the system, and,
- State matrix calculation (E, A, B, C, and D matrices) for the linearized system, when a set of inputs and outputs are defined.

Linear analysis can be performed at any operating point. This may be done either after a static equilibrium solution or after a dynamic solution. Usually, a steady state configuration is chosen as the operating condition. Not all the MotionSolve modeling elements are supported for a linear analysis. For more details, please see the Comments section.

## Format

```
<Param_Linear
[
anim_scale = "real"
balancing = {"TRUE" | "FALSE" | "AUTO"}
disable_damping = {"TRUE" | "FALSE" }
gyroscopic = {"NONE"|"PARTIAL"|"FULL"}
eigen_analysis = {"TRUE"|"FALSE"}
write_energy_dist = {"TRUE"|"FALSE"}
write_energy_html = {"TRUE"|"FALSE"}
write_eig_info = {"TRUE"|"FALSE"}
write_simulinkmdl = {"TRUE"|"FALSE"}
write_matlabfiles = {"TRUE"|"FALSE"}
write_oml = {"TRUE"|"FALSE"}
pinput_id = "integer"
poutput_id = "integer"
pstate_id = "integer"
{
ke_modes_exclude = "string"
ke_modes_include = "string"
}
{
se_modes_exclude = "string"
se_modes_include = "string"
}
{
de_modes_exclude = "string"
de_modes_include = "string"
}
]
/>
```

## Attributes

`anim_scale`- Specifies a scale factor for magnifying the mode shapes during animation.
The default is

`1.0`.

`balancing`- Specifies whether the A matrix should be pre-conditioned using diagonal scaling to
improve robustness of the eigenvalue solution. Choose
from:
`TRUE`: MotionSolve will always balance the A matrix using diagonal scaling.`FALSE`: MotionSolve will not balance the A matrix.`AUTO`: MotionSolve determines when to balance the A matrix based on the condition number of the eigenvector matrix. See Comment 8 for more details.The default for

`balancing`is`AUTO`. `disable_damping`- Specifies whether the linearization solver should disable damping from all force elements for the eigenvalue solution.
`gyroscopic`- Specifies how MotionSolve should compute gyroscopic
effects when linearizing a rotating system. Choose from:
`NONE`: MotionSolve will not consider gyroscopic effects during linear analysis.`PARTIAL`: MotionSolve will consider partial gyroscopic effect without accounting for angular momentum.`FULL`: MotionSolve will consider the full gyroscopic effect including angular momentum.

`eigen_analysis`- Specifies whether linear analysis should perform or skip the eigen analysis. This can
be used in cases when only the A, B, C, and D matrix are needed. If
`NO`is selected, then eigen information and energy distribution information will not be written. Select from`TRUE`or`FALSE`.The default is

`TRUE`. `write_energy_dist`- Specifies whether the modal kinetic strain and dissipative energy distribution is
written out to the solver log file and the *_linz.mrf output file.
Select from
`TRUE`or`FALSE`. `write_energy_html`- Specifies whether the modal kinetic strain and dissipative energy distribution is
written out in an HTML format that
can be displayed by any modern browsers. Select from
`TRUE`or`FALSE`. `write_eig_info`- Specifies whether the eigenvalue and eigenvector data are written to an
.eig file. Select from
`TRUE`or`FALSE`. `write_simulinkmdl`- Specifies whether the A, B, C, and D matrices that are calculated are to be written
out in the Simulink MDL format or not. Select from
`TRUE`or`FALSE`. `write_matlabfiles`- Specifies whether the A, B, C, and D matrices that are calculated are to be written
out to a file that can be read by MATLAB. Select from
`TRUE`or`FALSE`. `write_oml`- Specifies whether the A, B, C, and D matrices that are calculated are to be written
out to a file that can be read by Compose or any other
OML-based math tool, such as GNU Octave. Select from
`TRUE`or`FALSE`. `pinput_id`- Specifies the plant input ID used for the B and D state matrices. Can be optionally
used with the
`write_simulinkmdl`,`write_matlabfile`, and/or`write_oml`option. `poutput_id`- Specifies the plant output ID used for the C and D state matrices. Can be optionally
used with the
`write_simulinkmdl`,`write_matlabfile`, and/or`write_oml`option. `pstate_id`- An integer that specifies the id of the Reference_PlantState that
defines some or all of the states MotionSolve used for linearizing the
equations of motion. When the
`pstate_id`attribute is not specified, MotionSolve uses its own internal states to linearize the equations. `ke_modes_exclude`,`ke_modes_include`,`se_modes_exclude`,`se_modes_include`,`de_modes_exclude`,`de_modes_include`- These attributes allow you to exclude or include modes from the following energy distribution tables.

## Comments

- Eigenvector and Eigenvalue Analysis:
The eigenvalues and eigenvectors of a nonlinear system can change with time. An eigenvalue analysis is useful for understanding the underlying vibration characteristics of the system at a

*specific*operating point or a series of operating points.The eigenvalues represent the complex frequencies of vibration of the system and the eigenvectors represent the modes of vibration.

- State Matrix Analysis:
Given a set of inputs "u", a set of outputs "y", and a linearized mechanical system represented by a set of dynamical states "x", the transfer function for the system can be represented in the time domain as:

$E\dot{x}=Ax+Bu$

$y=Cx+Du$

The matrices E, A, B, C, and D are called the state matrices for the system. If there are nx states, nu inputs, and ny outputs, the dimensions of the matrices are as follows:- E: nx x nx
- A: nx x nx
- B: nx x nu
- C: nu x nx
- D: nu x nu

The inputs "u" are defined using the Control_PlantInput modeling element specified in the

`pinput_id`and the outputs "y" are defined using Control_PlantOutput modeling element specified in the`poutput_id`.The inputs "u" can be displacements, forces, or moments. If the inputs are forces or moments, then matrix E becomes an identity matrix and the transfer function for the system can be simplified to:$$\begin{array}{l}\dot{x}=Ax+Bu\\ y=Cx+Du\end{array}$$State matrix output is particularly useful for control engineers, who need a linear plant representation to design a controller.

Another common application of state matrices is to calculate the system Frequency Response Functions to a series of time-based inputs. This is the traditional vibration analysis of linearized mechanical systems.

- State matrix output:
- When the write_simulinkmdl attribute is chosen, the A, B, C, and D matrices are written in Simulink format in a Simulink MDL file.
- When the write_matlabfiles attribute is chosen, the A, B, C, and D matrices are written in MATLAB format in four separate files with extensions .a, .b, .c and .d, respectively.
- When the write_oml attribute is chosen, the A, B, C, and D matrices are written in OML format in one file with extension .oml.

- Eigenvalue analysis output:
- Eigenvalues are written to the *.eig file.
- To visualize the mode shapes, set the linear_animation = “TRUE” attribute in the H3DOutput command. Each mode shape will be written as new subcase in the H3D file.

- Significance of eigenvalues and eigenvectors:
Eigenvalues and eigenvectors can be computed from state matrices. Once a linear analysis is initiated, the system is linearized to the form:

$$\begin{array}{l}M\ddot{q}+C\dot{q}+{E}_{1}\dot{z}+{E}_{2}z=0\\ {E}_{3}\dot{q}+{E}_{4}q+\dot{z}+{E}_{5}z=0\end{array}$$q represents the linearized displacement coordinates, and z represents non-mechanical states due to other differential equations.

All constraints are eliminated from the formulation. The equations are converted to first-order form as follows:

$$\left[\begin{array}{ccc}M& 0& {E}_{1}\\ 0& I& 0\\ 0& {E}_{3}& I\end{array}\right]\left\{\begin{array}{c}\dot{u}\\ \dot{q}\\ \dot{z}\end{array}\right\}+\left[\begin{array}{ccc}C& K& {E}_{2}\\ -I& 0& 0\\ 0& {E}_{4}& {E}_{5}\end{array}\right]\left\{\begin{array}{c}u\\ q\\ z\end{array}\right\}=\left\{\begin{array}{c}0\\ 0\\ 0\end{array}\right\}$$This results in the eigenvalue problem:

$\widehat{K}x=\lambda \widehat{M}x$ where ${x}^{T}=\left[\begin{array}{ccc}{u}^{T}& {q}^{T}& {z}^{T}\end{array}\right]$ , $\widehat{M}=\left[\begin{array}{ccc}M& 0& {E}_{1}\\ 0& I& 0\\ 0& {E}_{3}& I\end{array}\right]\text{}$ , and $\widehat{K}=\left[\begin{array}{ccc}C& K& {E}_{2}\\ -I& 0& 0\\ 0& {E}_{4}& {E}_{5}\end{array}\right]$- Let an Eigenvalue be represented as:
$\lambda ={\lambda}_{r}+j{\lambda}_{i}\text{;}j=\sqrt{-1}$
The undamped natural frequency of the this mode is: ${\omega}_{n}=\sqrt{\left({\lambda}_{r}^{2}+{\lambda}_{i}^{2}\right)}$

The damping ratio for this mode is: $\zeta =\frac{{\lambda}_{r}}{{\omega}_{n}}$

The damped natural frequency for this mode is: ${\omega}_{d}={\omega}_{n}\sqrt{\left(1+{\zeta}^{2}\right)}$

- The real part of the Eigenvalue corresponds to the system damping. For all stable systems, this must be less than zero. A positive real component for an eigenvalue indicates instability in the system. The system becomes unstable if this mode is ever excited. Such designs are to be avoided.
- By successfully varying design parameters like stiffness and damping in the system and calculating the eigenvalues, a root locus plot of the system at an operating point can be generated.
- The eigenvectors can be used to validate the analytical model with actual physical tests that may have been performed in the frequency domain.

- Let an Eigenvalue be represented as:
$\lambda ={\lambda}_{r}+j{\lambda}_{i}\text{;}j=\sqrt{-1}$
- Significance of state matrices:
Take the Laplace transform of the linearized equations of motion:

$$L\left(\begin{array}{l}\dot{x}=Ax+Bu\\ y=Cx+Du\end{array}\right)=\left(\begin{array}{l}sX(s)-X(0)=AX(s)+BU(s)\\ Y(s)=CX(s)+Du(s)\end{array}\right)$$Ignoring the initial value X(0), and rearranging terms, you obtain:

System Transfer Function = $\frac{Y(s)}{U(s)}=C{\left(sI-A\right)}^{-1}B+D$

The meaning of the transfer function can change based on its input and output types:- When the input "u" are displacements and the output "y" forces, the matrices E-A-B-C-D together represent the dynamic compliance at the operating point
- When the input "u" are Forces and the output "y" displacements, the matrices A-B-C-D together (E is identity) represent the dynamic stiffness at the operating point
- When the input "u" are Forces and the output "y" velocities, the matrices A-B-C-D together (E is identity) represent the mechanical impedance at the operating point
- When the input "u" are Forces and the output "y" accelerations, the matrices A-B-C-D together (E is identity) represent the apparent mass at the operating point

Compliance matrices are used in the automotive industry for suspension design. A compliance matrix is a MIMO transfer function that relates a set of forces and torques applied at specific points on the suspension to the displacements measured at other specific points on the suspension.

Traditionally, compliance matrices have been computed about a static equilibrium position and the data used for suspension design. This approach ignores three effects: (a) The effects of inertia and damping on the system compliance, (b) The variation of compliance on during vehicle operation, and (c) The variation of compliance with the frequency of the input.

The use of ABCD matrices to calculate the compliance transfer function about dynamic operating points overcomes all of these issues.

- Computing the energy distribution in the system:
If

`write_energy_dist`is set to`TRUE`, MotionSolve computes the kinetic, strain, and dissipative energy distributions for parts and forces in the model for the modes specified.If

`write_energy_dist`is set to`FALSE`, MotionSolve will not compute any energy distribution regardless of the`ke_modes_include`/`ke_modes_exclude`,`se_modes_include`/`se_modes_exclude`, or`de_modes_include`/`de_modes_exclude`attributes and their values.You can specify the modes that MotionSolve should compute the energy distributions for. This can be useful when there are a large number of modes in your system and you are interested only in the energy distribution for a subset of these modes.

You can specify the modes MotionSolve should include or exclude, separately, for kinetic, strain, or dissipative energy by using the following attributes:`ke_modes_include`– for including modes in the kinetic energy distribution`ke_modes_exclude`– for excluding modes in the kinetic energy distribution`se_modes_include`– for including modes in the strain energy distribution`se_modes_exclude`– for excluding modes in the strain energy distribution`de_modes_include`– for including certain modes in the dissipative energy distribution`de_modes_exclude`– for excluding certain modes in the dissipative energy distribution

Typically, you only need to specify the modes to be included, or the modes to be excluded, but not both. If you specify both - modes to be included and modes to be excluded - the definition that appears later in the Param_Linear statement will be honored.

Kinetic Energy:

MotionSolve computes the modal kinetic energy distribution for all bodies in the MBD model, for the modes specified. These are then written to the log file in tabular format. Each row in this table represents a body. Within a row, each number represents the percentage distribution of modal kinetic energy between the translational (X, Y, Z), rotational (RXX, RYY, RZZ) and cross-rotational, RXY, RXZ, RYZ directions of the part. The total modal kinetic energy distributions for each mode should add up to 100%.

The total kinetic energy for each mode is calculated as follows:

$$KE=\left({\Phi}^{T}M\Phi \right){\omega}_{n}^{2}$$$\Phi $ is the eigenvector

$M$ is the mass matrix of size n

_{DOF}*n_{Bodies}X n_{DOF}*n_{Bodies}. n_{DOF}is the number of degrees of freedom per body = 6 and n_{Bodies}is the total number of bodies in the system.${\omega}_{n}$ is the undamped frequency of the mode.

The modal kinetic energy distribution for each part is calculated for nine coordinates: X, Y, Z, RX, RY, RZ, RXY, RXZ, and RYZ.

For example, the percentage of total KE for the Z direction is calculated as:$$\%K{E}_{z}=\left(\frac{{p}_{1}^{T}M{p}_{1}}{{p}_{1}^{T}Mp}\right)\times 100$$$\%K{E}_{z}$ is percentage of modal kinetic energy in the Z direction.

$M$ is the mass matrix as described above.

$p$ is a column of the eigenvector matrix Φ corresponding to the current mode number. If mode number = 10, then this is the 10

^{th}column vector in the eigenvector matrix. This is a vector of size 6*n_{Bodies}X 1.${p}_{1}$ is the same vector as $p$ with all entries zeroed-out except for the coordinate of interest, the Z coordinate, in this example.

For cross rotational terms (RXY, RXZ, RYZ), the calculation is slightly different. For example, for the RXZ percentage:

$\%K{E}_{Rxz}=\left(\frac{{p}_{1}^{T}M{p}_{2}}{{p}_{1}^{T}Mp}\right)\times 100$

$\%K{E}_{Rxz}$ is the percentage of modal kinetic energy in the Rxz direction.

$M$ is the mass matrix as described above.

$p$ is a column of the eigenvector matrix Φ corresponding to the current mode number.

${p}_{1}$ is the same vector as $p$ with all entries zeroed-out except for the Rx coordinate.

${p}_{2}$ is the same vector as $p$ with all entries zeroed out except for the Rz coordinate.

Strain and Dissipative Energy:

MotionSolve can also compute the modal strain and dissipative energy distribution for certain force entities in the MBD model, for the modes specified (these are listed in the table below).

The energy distributions are then written to the log file in tabular format. Each row in this table represents a force entity. Within a row, each number represents the percentage distribution of modal strain or dissipative energy between the translational (X, Y, Z) and rotational (RX, RY, RZ) directions.Model Element Total X Y Z RX RY RZ Force_Beam Yes Yes Yes Yes Yes Yes Yes Force_Bushing Yes Yes Yes Yes Yes Yes Yes Force_Field Yes Yes Yes Yes Yes Yes Yes Force_Vector_OneBody, Force_Vector_TwoBody type = ForceAndTorque

Yes Yes Yes Yes Yes Yes Yes Force_Vector_OneBody, Force_Vector_TwoBody type = ForceOnly

Yes Yes Yes Yes No No No Force_Vector_OneBody, Force_Vector_TwoBody type = TorqueOnly

Yes No No No Yes Yes Yes Force_Scalar_TwoBody type = Force

Yes Yes Yes Yes No No No Force_Scalar_TwoBody type = Torque

Yes No No No No No No ForceSpringDamper type=TRANSLATION

Yes Yes Yes Yes Yes Yes Yes Force_SpringDamper type = ROTATION

No No No No No No No Note: If a force entity does not contribute to the modal strain or dissipative energy, then that force entity’s row will be zero.The Strain and Dissipative energy calculations are done in a manner similar to the Kinetic energy distributions except that the stiffness and damping matrices are used in place of the mass matrix to calculate the percentage distributions for force elements.

In addition to the energy distribution tables, MotionSolve also displays a header for each mode that includes information about the mode number, damping ratio, undamped natural frequency, and the total value of the modal kinetic energy. An example of this energy distribution that is written to the output log file as shown below:

`************************* Mode number = 10 Damping ratio = 5.0000000E-02 Undamped natural freq.= 1.5915494E+00 Kinetic energy = 1.1427840E-05 Percentage distribution of Kinetic energy | X Y Z RXX RYY RZZ RXY RXZ RYZ +---------------------------------------------------------------- PART/30301 | 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 PART/30302 | 0.00 98.69 0.00 1.31 0.00 0.00 0.00 0.00 0.00 +---------------------------------------------------------------- Percentage distribution of Strain energy | Total X Y Z RXX RYY RZZ +------------------------------------------------- VFOR/30301 | 0.00 0.00 0.00 0.00 VFOR/30302 | 0.00 0.00 0.00 0.00 SPDP/303001 | 0.00 0.00 0.00 0.00 0.00 0.00 0.00 SPDP/303002 | 50.00 50.00 0.00 0.00 0.00 0.00 0.00 SPDP/303003 | 50.00 50.00 0.00 0.00 0.00 0.00 0.00 +------------------------------------------------- Percentage distribution of Dissipative energy | Total X Y Z RXX RYY RZZ +------------------------------------------------- VFOR/30301 | 0.00 0.00 0.00 0.00 VFOR/30302 | 0.00 0.00 0.00 0.00 SPDP/303001 | 0.00 0.00 0.00 0.00 0.00 0.00 0.00 SPDP/303002 | 50.00 50.00 0.00 0.00 0.00 0.00 0.00 SPDP/303003 | 50.00 50.00 0.00 0.00 0.00 0.00 0.00 +-------------------------------------------------`

These energy distributions are additionally written to the output *_linz.mrf file, which may be used for post-processing.Note: The *_linz.mrf contains information for all modes regardless of which were specified for inclusion or exclusion. - Matrix Balancing
For certain models, the eigenvalues computed by MotionSolve can be extremely sensitive to small perturbations in the $A$ matrix. This occurs because the eigenvector matrix, $V$ , for such a model is highly ill-conditioned. As a result, even seemingly minor changes for such models may result in large changes in the eigenvalue solution.

$K\left(V\right)={\Vert V\Vert}^{-1}\Vert V\Vert \text{\hspace{0.17em}}$ is the condition number of a matrix $V$ . Consider the linear equation $Vx=b$ . $K\left(V\right)\text{\hspace{0.17em}}$ measures the rate at which the solution x will change due to a change in b. If $K\left(V\right)\text{\hspace{0.17em}}$ is large, then even a small change in b can cause large changes in the solution x. In such as case, the matrix V is said to be ill-conditioned.

To obtain a robust eigenvalue solution in such cases, MotionSolve must

*balance*the $A$ matrix by finding a diagonal similarity transformation $DA{D}^{-1}$ such that the row and column norms of $A$ are numerically close. By doing so, the eigenvector matrix becomes better conditioned and the eigenvalue solution is more robust to numerical noise in $A$ .The`balancing`attribute controls whether matrix balancing is done or not.- Set this to
`TRUE`to always balance the A matrix regardless of whether the eigenvector matrix is ill-conditioned or not. - Set balancing to
`FALSE`to never balance the A matrix. - The default for balancing is
`AUTO`, which lets MotionSolve decide if balancing is needed or not.Let $R=K{\left(V\right)}^{-1}$ be the reciprocal of the condition number of $V$ .

If $R<500*{\epsilon}_{machine}$ , then balancing is performed. Otherwise, it is not performed.

If ${\epsilon}_{machine}=2.2E-16$ , then balancing is performed when $R\text{}500\text{}*\text{}2.2E-16\text{}=\text{}1.11\text{}E-13$ .

While balancing a matrix is generally a good idea, you need to be judicious in its use. There are some rare situations where balancing will not provide the benefits you expect. Specifically, you should be aware of the following:- If a matrix contains small elements that are due to round-off error, balancing might make them more significant than they should be. MotionSolve tries to minimize this by zeroing-out very small entries in the Jacobian.
- The condition number of the eigenvector matrix,
$K\left(V\right)\text{\hspace{0.17em}}$
, can only be computed after
$V$
is computed. When balancing is set to
`AUTO`, the eigenvalue solver may be called twice: first, without balancing and then, if $K\left(V\right)\text{\hspace{0.17em}}$ is small, with balancing. As a result, an increase in run-time may occasionally be seen.

- Set this to
- Element SupportMotionSolve does not support all modeling elements for a linear analysis. The following elements are currently not supported:
- Body_Flexible (NLFE bodies only)
- Constraint_General
- Force_Contact
- Force_Penalty
- Reference_2DCluster
- Reference_Variable (Implicit only)
- Subsystem_Planar/Reference 2DCluster

- Simulation sequenceThe linear analysis step should always be the last step in a sequence of analysis steps. The following sequences are valid:
- 1:Linear
- 1:(Quasi-) Static, 2:Linear
- 1:Transient, 2:Linear
- 1:Static, 2:Transient, 3: Linear
- Other combinations

- 1: Transient
- 2: Save
- 3: Linear
- 4: Reload model from step 2

- Cosimulation
The linear analysis does not include elements with which you can perform a cosimulation.