Problem

class otp.Problem

Bases: handle

The superclass for all problems in OTP.

A problem is defined by a differential equation

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

a time span \(t ∈ [t_0, t_f]\), initial conditions \(y(t_0) = y_0\), and any parameters \(p\). The unknown solution function is \(y(t) ∈ ℂ^N\).

This class provides the basic infrastructure for defining, solving, plotting, and animating a problem.

See also

otp.RHS, otp.Parameters

ode

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

Constructor Summary
Problem(name, expectedNumVars, timeSpan, y0, parameters)

Create a problem object.

Parameters:

  • name (char(1, :)) – A human-readable representation of the problem.

  • expectedNumVars (numeric or []) – The expected number of variables or an empty array for an arbitrary number.

  • timeSpan (numeric(1, 2)) – The start and final time.

  • y0 (numeric(:, 1)) – The initial conditions.

  • parameters (otp.Parameters) – The parameters.

Property Summary
Name

A human-readable representation of the problem.

RHS

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

This property is an otp.RHS which is regenerated when the problem’s time span, initial conditions, or parameters change.

Example

>>> problem = otp.linear.presets.Canonical;
>>> problem.RHS.F
ans =

@(~, y) lambda * y

See also

otp.RHS

TimeSpan

A mutable time interval \([t_0, t_f]\) over which the problem is defined.

Example

>>> problem = otp.protherorobinson.presets.Canonical;
>>> problem.TimeSpan
ans =

    0   15
>>> problem.TimeSpan(2) = 100;
Y0

A mutable column vector for the initial conditions \(y(t_0) = y_0\).

Example

>>> problem = otp.lotkavolterra.presets.Canonical;
>>> problem.Y0
ans =

    1
    2
>>> problem.Y0 = [3; 4];
Parameters

A mutable otp.Parameters representing the problem parameters \(p\).

Example

>>> problem = otp.nbody.presets.Canonical;
>>> problem.Parameters.GravitationalConstant
ans = 1
>>> problem.Parameters.Masses(1) = 2;

See also

otp.Parameters

NumVars

The number of variables \(N\) of the problem.

Example

>>> problem = otp.cusp.presets.Canonical;
>>> problem.NumVars
ans = 96
>>> problem.Y0 = ones(30, 1);
>>> problem.NumVars
ans = 30
Method Summary
plot(sol, varargin)

Plot all solution trajectories with time on the x-axis and \(y(t)\) on the y-axis.

Each call to this function creates a new figure and displays all solution variables. It accepts as input the two standard output formats of MATLAB’s differential equation solvers: a solution structure or a [t, y] pair.

Warning

A plot can appear jagged if the solution time points are too coarse. In MATLAB, deval can be used to evaluate the solution at a user-specified set of points.

Parameters:

  • sol (struct or numeric(1, :) or numeric(:, 1)) – A solution structure with properties x and y. The length of one dimension of the matrix y must match the length (number of time points) of the vector x. If y is square, each column should be a state and each row the trajectory of a single variable. Alternatively, this argument can be a vector of time points.

  • y (numeric(:, :), optional) – If the first argument is a vector of time points, this should be the corresponding matrix of solutions. The length of one dimension must match the length (number of time points) of x. If square, each row should be a state and each column the trajectory of a single variable.

  • varargin –

    A variable number of name-value pairs. Accepted names include

    • Title – A string for the figure title.

    • XLabel – A string for the x-axis label.

    • YLabel – A string for the y-axis label.

    • ZLabel – A string for the z-axis label.

    • View – An array specifying the camera line of sight following MATLAB’s specification.

    • ColorOrder – The color order palette following MATLAB’s specification.

    • Axis – The axis limits and aspect ratios following MATLAB’s specification.

    • LineStyleOrder – The line style order following MATLAB’s specification.

    • XScale – Either 'linear' or 'log'.

    • YScale – Either 'linear' or 'log'.

    • ZScale – Either 'linear' or 'log'.

    • FontName – A string for the font name.

    • FontSize – A size in the unit of points for the font.

    • Legend – A cell array of strings or a function handle with the signature label = fun(index) specifying the label of lines to show in the legend.

    • MaxLegendLabels – The maximum number of entries to show in the legend. If the number of lines exceeds this, only an evenly-spaced subset appears in the legend.

Returns:

fig – The figure created for the plot.

Return type:

figure, optional

Examples

>>> problem = otp.trigonometricdae.presets.Canonical;
>>> sol = problem.solve();
>>> problem.plot(sol, 'Axis', 'square', 'XLabel', 'Time');
>>> x = linspace(p.TimeSpan(1), p.TimeSpan(2), 500);
>>> fig = problem.plot(x, deval(x, sol), 'Title', 'Another Plot');

>>> problem = otp.vanderpol.presets.Canonical;
>>> [t, y] = ode15s(problem.RHS.F, problem.TimeSpan, problem.Y0);
>>> problem.plot(t, y);
plotPhaseSpace(sol, varargin)

Plot a selection of solution trajectories with respect to each other.

A phase plot is 2D or 3D with one or more lines. For each line, the x-, y-, and z-axis can represent a different user-specified component of the solution. Each call to this function creates a new figure. It accepts as input the two standard output formats of MATLAB’s differential equation solvers: a solution structure or a [t, y] pair.

Warning

A plot can appear jagged if the solution time points are too coarse. In MATLAB, deval can be used to evaluate the solution at a user-specified set of points.

Parameters:

  • sol (struct or numeric(1, :) or numeric(:, 1)) – A solution structure with properties x and y. The length of one dimension of the matrix y must match the length (number of time points) of the vector x. If y is square, each column should be a state and each row the trajectory of a single variable. Alternatively, this argument can be a vector of time points.

  • y (numeric(:, :), optional) – If the first argument is a vector of time points, this should be the corresponding matrix of solutions. The length of one dimension must match the length (number of time points) of x. If square, each row should be a state and each column the trajectory of a single variable.

  • varargin –

    A variable number of name-value pairs. Accepted names include those supported by otp.Problem.plot() as well as the following:

    • Vars – a matrix of variable indices where each row corresponds to a line in the plot and columns one, two, and optionally three correspond to the x-, y-, and z-axis, respectively.

Returns:

fig – The figure created for the plot.

Return type:

figure, optional

Examples

>>> problem = otp.lorenz63.presets.Canonical;
>>> sol = problem.solve();
>>> problem.plotPhaseSpace(sol, 'Title', 'Lorenz Butterfly');
>>> problem.plotPhaseSpace(sol, 'Vars', [1, 2; 2, 3; 3, 1]);
movie(sol, varargin)

Create an animation of solution trajectories.

Each call to this function creates a new figure. It accepts as input the two standard output formats of MATLAB’s differential equation solvers: a solution structure or a [t, y] pair.

Warning

Octave has limited movie functionality and support. For most problems, the movie will not work. Saving a movie to a file is currently unsupported.

Warning

A movie can appear jerky if the solution time points are too coarse. In MATLAB, deval can be used to evaluate the solution at a user-specified set of points.

Parameters:

  • sol (struct or numeric(1, :) or numeric(:, 1)) – A solution structure with properties x and y. The length of one dimension of the matrix y must match the length (number of time points) of the vector x. If y is square, each column should be a state and each row the trajectory of a single variable. Alternatively, this argument can be a vector of time points.

  • y (numeric(:, :), optional) – If the first argument is a vector of time points, this should be the corresponding matrix of solutions. The length of one dimension must match the length (number of time points) of x. If square, each row should be a state and each column the trajectory of a single variable.

  • varargin –

    A variable number of name-value pairs. Accepted names include those supported by otp.Problem.plot() as well as the following:

    • Save – If false (default) the movie will play but the frames will not be save for playback. If true the frames will be saved in memory for playback. If a string or a VideoWriter, the movie will be written to a file.

    • FrameRate – The number of frames per second when playing the movie.

    • Duration – The length in seconds of the movie. Frames may need to be skipped or duplicated to accommodate.

    • Size – An array [width, height] for the figure size in pixels.

    • Smooth – If true (default), solution states are uniformly sampled for frames based on the corresponding solution times. If false solution states are sampled uniformly by time step index which may lead to the inconsistent playback speeds.

Returns:

mov – A movie object which can be replayed using the play() method if saved.

Return type:

otp.utils.movie.Movie, optional

Examples

>>> problem = otp.pendulum.presets.Canonical('NumBobs', 8);
>>> sol = problem.solve();
>>> mov = problem.movie(sol, 'Save', true, 'Duration', 5);
>>> mov.play();

>>> problem = otp.bouncingball.presets.RandomTerrain;
>>> sol = problem.solve();
>>> mov = problem.movie(sol, 'Save', 'movie.avi', 'FrameRate', 30);
index2label(index)

Get a human-readable label for a particular component of the differential equation

Parameters:

index – An index \(i\) between \(1\) and \(N\) for component \(y_i(t)\).

Returns:

label – The name of the component.

Return type:

char(1, :)

Example

>>> problem = otp.brusselator.presets.Canonical;
>>> problem.index2label(2)
ans = Reactant Y
solve(varargin)

Numerically compute a solution to the differential equation.

This function will numerically integrate the differential equation until a terminal event is triggered, the end of the time span is reached, or the solver throws an error. It is handy for generating a reference solution or studying convergence of an integrator with respect to the tolerance.

Note

Different problem subclasses use different default solvers. The solver used is stored in the solver property of the returned solution structure.

Warning

ode15s in Octave transposes the y property of the returned solution structure. All Octave solvers transpose event data compared to MATLAB.

Parameters:

varargin –

A variable number of name-value pairs. Accepted names include those supported by otp.RHS.odeset() as well as the following:

  • Solver – A function handle to a differential equation solver which can be evaluated as sol = Solver(odefun, tspan, y0, options).

Returns:

sol – A solution structure in the standard MATLAB solver output format. The time and solution steps are stored in the x and y properties, respectively.

Return type:

struct

Example

>>> problem = otp.pendulum.presets.Canonical;
>>> sol1 = problem.solve();
>>> sol2 = problem.solve('RelTol', 1e-8, 'Solver', @ode23);
solveExactly(t)

Compute the exact solution to the differential equation if available or throw an error otherwise.

Parameters:

t (numeric or numeric(1, :) or numeric(:, 1), optional) – The times at which to generate the exact solution. If not provided, the end of the time span \(t_f\) is used.

Returns:

y – A matrix in which element \((i, j)\) is \(y_i(t_j)\).

Return type:

numeric(:, :)

Examples

>>> problem = otp.ascherlineardae.presets.Canonical;
>>> problem.solveExactly()
ans =

    1.5772
    1.2094

>>> problem = otp.protherorobinson.presets.Canonical;
>>> sol = problem.solve();
>>> err = sol.y - problem.solveExactly(sol.x);
>>> problem.plot(sol.x, err, 'YLabel', 'Error');