RHS

class otp.RHS

The right-hand side and related properties of a differential equation.

This immutable class contains properties required by time integrators and other numerical methods to describe the following differential equation:

\[M(t, y(t); p) y'(t) = f(t, y(t); p)\]

Despite the name, an RHS includes information about the mass matrix \(M(t, y(t); p)\) on the left-hand side. The mass matrix is permitted to be singular in which case the problem is a differential-algebraic equation. RHS also includes most of the properties available in MATLAB`s odeset so that it can easily be used with built-in solvers like ode15s.

Note

The parameters \(p\) do not appear explicitly in the arguments of functions in this class. Rather, they can be provided through the closure of an anonymous function.

Examples

>>> param = 1;
>>> rhs = otp.RHS(@(t, y) [y(2) + param * t; y(1) * y(2)], ...
...     'Jacobian', @(~, y) [0, 1; y(2), y(1)], ...
...     'Mass', [1, 2; 3, 4]);
>>> sol = ode23s(rhs.F, [0, 1], [1, -1], rhs.odeset());
>>> sol.y(:, end)
ans =

   1.0770
  -1.4465

>>> rhs = otp.RHS(@(~, y) y);
>>> rhs2 = 2 * rhs + 1;
>>> rhs2.F(0, 1)
ans = 3

See also

otp.Problem.RHS

odeset

https://www.mathworks.com/help/matlab/ref/odeset.html

Constructor Summary
RHS(F, varargin)

Create a right-hand side object.

Parameters:

  • F (function_handle) – The function handle for \(f\) in the differential equation.

  • varargin – A variable number of name-value pairs. A name can be any property of this class, and the subsequent value initializes that property.

Warning

In Octave, the value for otp.RHS.Vectorized is ignored because it is not used by built in solvers and causes an error for ode15s.

Property Summary
F

The function handle for \(f\) in the differential equation.

Parameters:

  • t (numeric) – The time at which \(f\) is evaluated.

  • y (numeric(:, 1) or numeric(:, :)) – The state at which \(f\) is evaluated. If otp.RHS.Vectorized is 'on', it can be a matrix where each column is a state.

Returns:

f – The evaluation of \(f\) with each column corresponding to a column of \(y\).

Return type:

numeric(:, 1) or numeric(:, :)

Jacobian

The partial derivative of \(f\) with respect to \(y\).

This follows the same specifications as in odeset. If set, it is a matrix if it is independent of t and y or a function handle. In either case, it provides a square matrix in which element \((i,j)\) is \(\frac{\partial f_i(t, y; p)}{\partial y_j}\). If Jacobian is a function handle, it has the following signature:

Parameters:

  • t (numeric) – The time at which the Jacobian is evaluated.

  • y (numeric(:, 1)) – The state at which the Jacobian is evaluated.

Returns:

jacobian – The evaluation of the Jacobian.

Return type:

numeric(:, :)

See also

JacobianMatrix JacobianFunction

JPattern

The sparsity pattern of the Jacobian matrix.

This follows the same specifications as in odeset.

Mass

The mass matrix \(M(t, y(t); p)\).

This follows the same specifications as in odeset.

See also

MassMatrix MassFunction

MassSingular

Whether the mass matrix is singular, i.e., the problem is a differential-algebraic equation.

This follows the same specifications as in odeset.

MStateDependence

State dependence of the mass matrix.

This follows the same specifications as in odeset.

MvPattern

The sparsity pattern of \(\frac{\partial}{\partial y} M(t, y; p) v\).

This follows the same specifications as in odeset.

NonNegative

A vector of solution components which should be nonnegative.

This follows the same specifications as in odeset.

Vectorized

Whether \(f\) can be evaluated at multiple states.

This follows the same specifications as in odeset.

Warning

In Octave, this is always unset because it is not used by built in solvers and causes an error for ode15s.

Events

A function which detects events and determines whether to terminate the integration.

This follows the same specifications as in odeset.

OnEvent

Response to a terminal event occurring.

If set, it is a function handle with the following signature:

Parameters:

  • sol (struct) – The solution generated by an ODE solver once an event occurs.

  • problem (Problem) – The problem for which the event occurred. This should not be modified by the function.

Returns:

  • terminal (logical) – true if the integration should stop and false if it can continue.

  • newProblem (Problem) – A new Problem to use after the event, possibly with the time span, initial conditions, or parameters updated.

Warning

With Octave solvers, event data in sol is transposed compared to MATLAB. Therefore, we recommend accessing the state at which the event occurred with sol.y(:, end) as opposed to sol.ye(:, end).

JacobianVectorProduct

The action of the Jacobian multiplying a vector.

This offers an alternative approach to access the Jacobian when constructing or storing it as a matrix is impractical. If set, it is a function handle with the following signature:

Parameters:

  • t (numeric) – The time at which the Jacobian is evaluated.

  • y (numeric(:, 1)) – The state at which the Jacobian is evaluated.

  • v (numeric(:, 1)) – The vector multiplying the Jacobian.

Returns:

jvp – A vector in which element \(i\) is \(\sum_j \frac{\partial f_i(t, y; p)}{\partial y_j} v_j\).

Return type:

numeric(:, 1)

JacobianAdjointVectorProduct

The action of the adjoint (conjugate transpose) of the Jacobian multiplying a vector.

This is often useful for sensitivity analysis and data assimilation. If set, it is a function handle with the following signature:

Parameters:

  • t (numeric) – The time at which the Jacobian is evaluated.

  • y (numeric(:, 1)) – The state at which the Jacobian is evaluated.

  • v (numeric(:, 1)) – The vector multiplying the adjoint of the Jacobian.

Returns:

javp – A vector in which element \(i\) is \(\sum_j \frac{\partial \overline{f_j(t, y; p)}}{\partial y_i} v_j\).

Return type:

numeric(:, 1)

PartialDerivativeParameters

The partial derivative of \(f\) with respect to parameters.

If set, it is a function handle with the following signature:

Parameters:

  • t (numeric) – The time at which the derivative is evaluated.

  • y (numeric(:, 1)) – The state at which the derivative is evaluated.

Returns:

pdp – A matrix in which element \((i, j)\) is \(\frac{\partial f_i(t, y; p)}{\partial p_j}\).

Return type:

numeric(:, :)

PartialDerivativeTime

The partial derivative of \(f\) with respect to \(t\).

This property is often required by Rosenbrock methods when solving nonautonomous problems. If set, it is a function handle with the following signature:

Parameters:

  • t (numeric) – The time at which the derivative is evaluated.

  • y (numeric(:, 1)) – The state at which the derivative is evaluated.

Returns:

pdt – A vector in which element \(i\) is \(\frac{\partial f_i(t, y; p)}{\partial t}\).

Return type:

numeric(:, 1)

Note

This is not the total derivative with respect to \(t\).

HessianVectorProduct

The action of the Hessian, a bilinear operator involving second derivatives of \(f\), on two vectors.

If set, it is a function handle with the following signature:

Parameters:

  • t (numeric) – The time at which the Hessian is evaluated.

  • y (numeric(:, 1)) – The state at which the Hessian is evaluated.

  • u (numeric(:, 1)) – The vectors applied to the Hessian.

  • v (numeric(:, 1)) – The vectors applied to the Hessian.

Returns:

hvp – A vector in which element \(i\) is \(\sum_{j,k} \frac{\partial^2 f_i(t, y; p)}{\partial y_j \partial y_k} u_j v_k\).

Return type:

numeric(:, 1)

HessianAdjointVectorProduct

The action of a vector on the partial derivative of otp.RHS.JacobianAdjointVectorProduct with respect to \(y\).

If set, it is a function handle with the following signature:

Parameters:

  • t (numeric) – The time at which the Hessian is evaluated.

  • y (numeric(:, 1)) – The state at which the Hessian is evaluated.

  • u (numeric(:, 1)) – The vectors applied to the adjoint of the Hessian.

  • v (numeric(:, 1)) – The vectors applied to the adjoint of the Hessian.

Returns:

havp – A vector in which element \(i\) is \(\sum_{j,k} \frac{\partial^2 \overline{f_j(t, y; p)}}{\partial y_i \partial y_k} u_j v_k\).

Return type:

numeric(:, 1)

JacobianMatrix

A dependent property which returns otp.RHS.Jacobian if it is a matrix and [] if it is a function handle.

JacobianFunction

A dependent property which wraps otp.RHS.Jacobian in a function handle if necessary.

MassMatrix

A dependent property which returns otp.RHS.Mass if it is a matrix and [] if it is a function handle.

MassFunction

A dependent property which wraps otp.RHS.Mass in a function handle if necessary.

Method Summary
odeset(varargin)

Convert an RHS to a options structure which can be used by built-in ODE solvers.

Parameters:

varargin – Additional name-value pairs which have precedence over the values in this class when constructing the options structure. Accept names include those supported by the built-in odeset.

Returns:

opts – An options structure containing the subset of properties compatible with built-in ODE solvers.

Return type:

struct

Example

>>> problem = otp.oregonator.presets.Canonical;
>>> opts = problem.RHS.odeset('AbsTol', 1e-12, 'RelTol', 1e-4);
>>> sol = ode23s(problem.RHS.F, problem.TimeSpan, problem.Y0, opts);

See also

odeset

https://www.mathworks.com/help/matlab/ref/odeset.html