Components and Data Structures
Introduction
NDSolve is broken up into several basic steps. For advanced usage, it can sometimes be advantageous to access components to carry out each of these steps separately.
- Equation processing and method selection
NDSolve performs each of these steps internally, hiding the details from a casual user. However, for advanced usage it can sometimes be advantageous to access components to carry out each of these steps separately.
Here are the low-level functions that are used to break up these steps.
classifies the differential system into initial value problem, boundary value problem, differential-algebraic problem, partial differential problem, etc. It also chooses appropriate default integration methods and constructs the main
data structure.
advances the numerical solution. The first invocation (there can be several) initializes the numerical integration methods.
converts numerical data into an
InterpolatingFunction to represent each solution.
Note that
can take a significant portion of the overall time to solve a differential system. In such cases, it can be useful to perform this step only once and use
to repeatedly solve for different options or initial conditions.
Example
Process equations and set up data structures for solving the differential system.
| Out[1]= |  |
Initialize the method
and integrate the system up to time 10. The return value of
is
Null in order to avoid extra references, which would lead to undesirable copying.
| Out[3]= |  |
Representing the solution as an
InterpolatingFunction allows continuous output even for points that are not part of the numerical solution grid.
| Out[4]= |  |
ProcessEquations
The first stage of any solution using
NDSolve is processing the equations specified into a form that can be efficiently accessed by the actual integration algorithms. This stage minimally involves determining the differential order of each variable, making substitutions needed to get a first-order system, solving for the time derivatives of the functions in terms of the functions, and forming the result into a
object. If you want to save the time of repeating this process for the same set of equations or if you want more control over the numerical integration process, the processing stage can be executed separately with
.
| NDSolve`ProcessEquations[{eqn1,eqn2,...},{u1,u2,...},t] |
| process the differential equations  for the functions  into a normal form; return a list of  objects containing the solution and data associated with each solution for the time derivatives of the functions in terms of the functions; t may be specified in a list with a range of values as in NDSolve |
| NDSolve`ProcessEquations[{eqn1,eqn2,...},{u1,u2,...},{x1,x1min,x1max},{x2,x2min,x2max},...] |
| process the partial differential equations  for the functions  into a normal form; return a list of  objects containing the solution and data associated with each solution for the time derivatives of the functions in terms of the functions; if  is the temporal variable, it need not be specified with the boundaries  |
Processing equations for NDSolve.
This creates a list of two
objects because there are two possible solutions for the
in terms of
.
| Out[1]= |  |
Reinitialize
It is not uncommon that the solution to a more sophisticated problem involves solving the same differential equation repeatedly, but with different initial conditions. In some cases, processing equations may be as time-consuming as numerically integrating the differential equations. In these situations, it is a significant advantage to be able to simply give new initial values.
| NDSolve`Reinitialize[state,conditions] | assuming the equations and variables are the same as the ones used to create the  object state, form a list of new  objects, one for each of the possible solutions for the initial values of the functions of the equations conditions |
Reusing processed equations.
This creates an
object for the harmonic oscillator.
| Out[2]= |  |
This creates three new
objects, each with a different initial condition.
| Out[3]= |  |
Using
may save computation time when you need to solve the same differential equation for many different initial conditions, as you might in a shooting method for boundary value problems.
A subset of
NDSolve options can be specified as options to
.
This creates a new
object, specifying a starting step size.
| Out[3]= |  |
Iterating Solutions
One important use of
objects is to have more control of the integration. For some problems, it is appropriate to check the solution and start over or change parameters, depending on certain conditions.
| NDSolve`Iterate[state,t] | compute the solution of the differential equation in an  object that has been assigned as the value of the variable state from the current time up to time t |
Iterating solutions to differential equations.
This creates an
object that contains the information needed to solve the equation for an oscillator with a varying coefficient using an explicit Runge-Kutta method.
| Out[4]= |  |
Note that when you use
, you do not need to give the range of the
variable explicitly because that information is not needed to set up the equations in a form ready to solve. (For PDEs, you do have to give the ranges of all spatial variables, however, since that information is essential for determining an appropriate discretization.)
This computes the solution out to time
.
does not return a value because it modifies the
object assigned to the variable state. Thus, the command affects the value of the variable in a manner similar to setting parts of a list, as described in "
Manipulating Lists by Their Indices". You can see that the value of
state has changed since it now displays the current time to which it is integrated.
The output form of
state shows the range of times over which the solution has been integrated.
| Out[6]= |  |
If you want to integrate further, you can call
again, but with a larger value for time.
This computes the solution out to time
.
You can specify a time that is earlier than the first current time, in which case the integration proceeds backwards with respect to time.
This computes the solution from the initial condition backwards to
.
allows you to specify intermediate times at which to stop. This can be useful, for example, to avoid discontinuities. Typically, this strategy is more effective with so-called one-step methods, such as the explicit Runge-Kutta method used in this example. However, it generally works with the default NDSolve method as well.This computes the solution out to
, making sure that the solution does not have problems with the points of discontinuity in the coefficients at
,
, ....
Getting Solution Functions
Once you have integrated a system up to a certain time, typically you want to be able to look at the current solution values and to generate an approximate function representing the solution computed so far. The command
allows you to do both.
| NDSolve`ProcessSolutions[state] | give the solutions that have been computed in state as a list of rules with InterpolatingFunction objects |
Getting solutions as InterpolatingFunction objects.
| Out[10]= |  |
| Out[11]= |  |
Just as when using
NDSolve directly, there will be a rule for each function you specified in the second argument to
. Only the specified components of the solutions are saved in such a way that an
InterpolatingFunction object can be created.
| NDSolve`ProcessSolutions[state,dir] | give the solutions that have been most recently computed in direction  in  as a list of rules with values for both the functions and their derivatives |
Obtaining the current solution values.
This gives the current solution values and derivatives in the forward direction.
| Out[12]= |  |
The choices you can give for the direction
dir are
and
, which refer to the integration forward and backward from the initial condition.
| "Forward" | integration in the direction of increasing values of the temporal variable |
| "Backward" | integration in the direction of decreasing values of the temporal variables |
| "Active" | integration in the direction that is currently being integrated; typically, this value should only be called from method initialization that is used during an active integration |
Integration direction specifications.
The output given by
is always given in terms of the dependent variables, either at a specific value of the independent variable, or interpolated over all of the saved values. This means that when a partial differential equation is being integrated, you will get results representing the dependent variables over the spatial variables.
This computes the solution to the heat equation from time
to
.
This gives the solution at
.
| Out[13]= |  |
The solution is given as an
InterpolatingFunction object that interpolates over the spatial variable
.
This gives the solution at
.
| Out[14]= |  |
When you process the current solution for partial differential equations, the
spatial error estimate is checked. (It is not generally checked except when solutions are produced because doing so would be quite time consuming.) Since it is excessive, the
NDSolve
message is issued. The typical association of the word "backward" with the heat equation as implying instability gives a clue to what is wrong in this example.
Here is a plot of the solution at
.
| Out[15]= |  |
The plot of the solution shows that instability is indeed the problem.
Even though the heat equation example is simple enough to know that the solution backward in time is problematic, using
and
to monitor the solution of a PDE can be used to save computing a solution that turns out not to be as accurate as desired. Another simple form of monitoring follows.
Entering the following commands generates a sequence of plots showing the solution of a generalization of the sine-Gordon equation as it is being computed.
| Out[60]= |  |
When you monitor a solution in this way, it is usually possible to interrupt the computation if you see that the solution found is sufficient. You can still use the
object to get the solutions that have been computed.
NDSolve`StateData Methods
An
object contains a lot of information, but it is arranged in a manner which makes it easy to iterate solutions, and not in a manner which makes it easy to understand where the information is kept. However, sometimes you will want to get information from the state data object: for this reason several method functions have been defined to make accessing the information easy.
| state@"TemporalVariable" | give the independent variable that the dependent variables (functions) depend on |
| state@"DependentVariables" | give a list of the dependent variables (functions) to be solved for |
| state@"VariableDimensions" | give the dimensions of each of the dependent variables (functions) |
| state@"VariablePositions" | give the positions in the solution vector for each of the dependent variables |
| state@"VariableTransformation" | give the transformation of variables from the original problem variables to the working variables |
| state@"NumericalFunction" | give the  object used to evaluate the derivatives of the solution vector with respect to the temporal variable t |
| state@"ProcessExpression"[args,expr,dims] |
| process the expression expr using the same variable transformations that NDSolve used to generate state to give a  object for numerically evaluating expr; args are the arguments for the numerical function and should either be All or a list of arguments that are dependent variables of the system; dims should be Automatic or an explicit list giving the expected dimensions of the numerical function result |
| state@"SystemSize" | give the effective number of first-order ordinary differential equations being solved |
| state@"MaxSteps" | give the maximum number of steps allowed for iterating the differential equations |
| state@"WorkingPrecision" | give the working precision used to solve the equations |
| state@"Norm" | the scaled norm to use for gauging error |
General method functions for an 
object state.
Much of the available information depends on the current solution values. Each
object keeps solution information for solutions in both the forward and backward direction. At the initial condition these are the same, but once the problem has been iterated in either direction, these will be different.
| state@"CurrentTime"[dir] | give the current value of the temporal variable in the integration direction dir |
| state@"SolutionVector"[dir] | give the current value of the solution vector in the integration direction dir |
| state@"SolutionDerivativeVector"[dir] | give the current value of the derivative with respect to the temporal variable of the solution vector in the integration direction dir |
| state@"TimeStep"[dir] | give the time step size for the next step in the integration direction dir |
| state@"TimeStepsUsed"[dir] | give the number of time steps used to get to the current time in the integration direction dir |
| state@"MethodData"[dir] | give the method data object used in the integration direction dir |
Directional method functions for an 
object state.
If the direction argument is omitted, the functions will return a list with the data for both directions (a list with a single element at the initial condition). Otherwise, the direction can be
,
, or
as specified in the
previous subsection.
Here is an
object for a solution of the nonlinear Schrodinger equation that has been computed up to
.
| Out[24]= |  |
"Current" refers to the most recent point reached in the integration.
This gives the current time in both the forward and backward directions.
| Out[27]= |  |
This gives the size of the system of ordinary differential equations being solved.
| Out[28]= |  |
The method functions are relatively low-level hooks into the data structure; they do little processing on the data returned to you. Thus, unlike
, the solutions given are simply vectors of data points relating to the system of ordinary differential equations
NDSolve is solving.
This makes a plot of the modulus of current solution in the forward direction.
| Out[29]= |  |
This plot does not show the correspondence with the
-grid values correctly. To get the correspondence with the spatial grid correctly, you must use
.
There is a tremendous amount of control provided by these methods, but an exhaustive set of examples is beyond the scope of this documentation.
One of the most important uses of the information from an
object is to initialize integration methods. Examples are shown in
"The NDSolve Method Plug-in Framework".
