odeMassMatrix

ODE mass matrix

Since R2023b

Description

An odeMassMatrix object represents the mass matrix for a system of ordinary differential equations.

ode objects can represent problems of the form $$M\left(t,y\right)y\text{'}=f\left(t,y\right)$$, where $$M\left(t,y\right)$$ is a mass matrix that can be full or sparse. The mass matrix encodes linear combinations of derivatives on the left side of the equation.

Create an ode object to represent the ODE problem, and specify the odeMassMatrix object as the value of the MassMatrix property to incorporate a mass matrix into the problem.

Creation

Syntax

M = odeMassMatrix

M = odeMassMatrix(PropertyName=Value)

Description

M = odeMassMatrix creates an odeMassMatrix object with empty properties.

M = odeMassMatrix(PropertyName=Value) specifies one or more property values using name-value arguments.

Properties

MassMatrix — Mass matrix

matrix | function handle

Mass matrix, specified as a matrix or handle to a function that evaluates the mass matrix.

ode objects can represent problems of the form $$M\left(t,y\right)y\text{'}=f\left(t,y\right)$$, where $$M\left(t,y\right)$$ is a mass matrix that can be full or sparse. The mass matrix encodes linear combinations of derivatives on the left side of the equation.

• When the mass matrix is nonsingular, the equation simplifies to $$y\text{'}=M^{-1}f\left(t,y\right)$$ and the ODE has a solution for any initial value. However, it is often more convenient and natural to express the model in terms of the mass matrix directly using $$M\left(t,y\right)y\text{'}=f\left(t,y\right)$$, and avoiding the computation of the matrix inverse reduces the storage and execution time needed to solve the problem.

• When the mass matrix is singular, the problem is a system of differential algebraic equations (DAEs). A DAE has a solution only when the initial values are consistent; that is, you must specify the initial slope $$y{\text{'}}_0$$ using the InitialSlope property of the ode object such that the initial conditions are all consistent, $$M\left(t_0,y_0\right)y{\text{'}}_0=f\left(t_0,y_0\right)$$. For more information, see Solve Differential Algebraic Equations (DAEs).

You can specify the value of the MassMatrix property as:

• A constant matrix with calculated values for $$M\left(t,y\right)$$.

• A handle to a function that computes the matrix elements and that accepts two input arguments, M = Mass(t,y). To give the function access to parameter values in the Parameters property, specify a third input argument in the function definition, M = Mass(t,y,p).

Example: M = odeMassMatrix(MassMatrix=@Mass) specifies the function Mass that evaluates the mass matrix.

Example: M = odeMassMatrix(MassMatrix=[1 0; -2 1]) specifies a constant mass matrix.

Data Types: single | double | function_handle
Complex Number Support: Yes

Singular — Singular mass matrix toggle

"maybe" (default) | "yes" | "no"

Singular mass matrix toggle, specified as "maybe", "yes", or "no". The default value of "maybe" causes the solver to test whether the problem is a differential algebraic equation (DAE) by testing whether the mass matrix is singular. Avoid this check by specifying "yes" if you know the system is a DAE with a singular mass matrix, or "no" if it is not.

Example: M = odeMassMatrix(MassMatrix=X,Singular="no")

StateDependence — State dependence of mass matrix

"weak" (default) | "none" | "strong"

State dependence of the mass matrix, specified as "weak", "strong", or "none".

• For ODE problems of the form $$M\left(t\right)y\text{'}=f\left(t,y\right)$$, set the StateDependence property to "none". This value ensures that the solver calls the mass matrix function with a single argument as in Mass(t) (or two arguments as in Mass(t,p) if you use the Parameters property of the ode object to pass parameters).

• If the mass matrix depends on y, then set StateDependence to either "weak" (default) or "strong". In both cases, the solver calls the mass matrix function with two arguments as in Mass(t,y) (or three arguments as in Mass(t,y,p) if you use the Parameters property of the ode object to pass parameters). However, a value of "weak" results in implicit solvers using approximations when solving algebraic equations.

Example: M = odeMassMatrix(MassMatrix=@Mass,StateDependence="none") specifies that the mass matrix function Mass depends only on t.

SparsityPattern — Mass matrix sparsity pattern

sparse matrix

Mass matrix sparsity pattern, specified as a sparse matrix. Use this property to specify the sparsity pattern of the matrix $$\frac{\partial }{\partial y}\left[M\left(t,y\right)v\right]$$. The sparse matrix S has S(i,j) = 1 if, for any k, the (i,k) component of $$M\left(t,y\right)$$ depends on component j of y. This property is similar to the MvPattern option of odeset.

Note

The SparsityPattern property is used by the ode15s, ode23t, and ode23tb solvers when StateDependence is "strong".

Example: M = odeMassMatrix(MassMatrix=@Mass,StateDependence="strong",SparsityPattern=S)

Data Types: single | double

Examples

Solve System of DAEs with Mass Matrix

Consider this system of first-order equations.

$$\begin{array}{l}{y}_1^{\prime }=y_1{y}_3-y_2\\ y_2^{\prime }=y_1-1\\ 0=y_1+y_2+y_3\end{array}$$

The left side of the equations contain time derivatives, ${\mathit{y}}_{\mathit{n}}^{\prime }=\frac{{\mathrm{dy}}_{\mathit{n}}}{\mathrm{dt}}$. However, because the derivative for ${\mathit{y}}_3$ does not appear in the system, the equations define a system of differential algebraic equations. Rewriting the system in the form ${\mathrm{My}}^{\prime }=\mathit{f}\left(\mathit{t},\mathit{y}\right)$ shows a constant, singular mass matrix on the left side.

$$\left[\begin{array}{ccc}1& 0& 0\\ 0& 1& 0\\ 0& 0& 0\end{array}\right]\underset{}{\overset{\dot{}}{\left[\begin{array}{c}{y}_1^{\prime }\\ y_2^{\prime }\\ y_3^{\prime }\end{array}\right]}}=\left[\begin{array}{c}{y}_1{y}_3-y_2\\ y_1-1\\ y_1+y_2+y_3\end{array}\right]$$

Solve the system of equations using the initial values [1 1 -2] by creating an ode object to represent the problem.

• Specify the initial values in the InitialValue property.

• Specify the system of equations as an anonymous function in the ODEFcn property.

• Use an odeMassMatrix object to specify the constant, singular mass matrix in the MassMatrix property.

F = ode;
F.InitialValue = [1 1 -2];
F.ODEFcn = @(t,y) [y(1)*y(3)-y(2); 
                   y(1)-1; 
                   y(1)+y(2)+y(3)];
F.MassMatrix = odeMassMatrix(MassMatrix=[1 0 0; 0 1 0; 0 0 0],Singular="yes");

Display the ode object. The SelectedSolver property shows that the ode15s solver was automatically chosen for this problem.

F

F = 
  ode with properties:

   Problem definition
               ODEFcn: @(t,y)[y(1)*y(3)-y(2);y(1)-1;y(1)+y(2)+y(3)]
          InitialTime: 0
         InitialValue: [1 1 -2]
             Jacobian: []
           MassMatrix: [1×1 odeMassMatrix]
         EquationType: standard

   Solver properties
    AbsoluteTolerance: 1.0000e-06
    RelativeTolerance: 1.0000e-03
               Solver: auto
       SelectedSolver: ode15s

  Show all properties

Solve the system of equations over the time interval [0 10] by using the solve method. Plot all three solution components.

S = solve(F,0,10);
plot(S.Time,S.Solution,"-o")
legend("y_1","y_2","y_3",Location="southeast")

Version History

Introduced in R2023b

R2025a: Specify single-precision property values

You can specify the mass matrix MassMatrix and sparsity pattern SparsityPattern as single-precision sparse matrices. You can also specify MassMatrix as a function handle that returns single-precision outputs.