<< CVODE user functions sci_sundials IDA user functions >>

sci_sundials >> sci_sundials > IDA

IDA

Sundials differential-algebraic equation solver

Syntax

[t,y,yp] = ida(f,tspan,y0,yp0,options)
[t,y,yp,te,ye,ype,ie] = ida(f,tspan,y0,yp0,options)
sol = ida(...)
solext = ida(sol,tfinal,options)

Arguments

f

a function, a string or a list, the residual of the differential-algebraic equation.

tspan

double vector, time interval or time points.

y0,yp0

double arrays: initial state and state derivative

options

a sequence of optional named arguments (see sundials options)

t

vector of time points used by the solver.

y,yp

arrays of solution and derivative of solution at time values in t

te,ye,ype,ie

time of event, solution, derivative of solution and index of event.

sol, solext

MList of _odeSolution type

tfinal

final time of extended solution

Description

IDA computes the solution of real or complex ordinary different-algebraic equation defined by f(t,y,y. It is an interface to IDA solver of Sundials library using BDF method. The simplest call of IDA is when tspan is a two component vector:

[t,y,yp] = ida(f,[t0 tf],y0,yp0)

where t0, tf are the initial and final time, y is the array of solutions [y(t(1)),y(t(2)),...] at time values in t, yp is the array of solutions [y'(t(1)),y'(t(2)),...]. Concatenation is done on next dimension if y0 is not a vector. The time values in t are those used by the solver to meet default relative and absolute estimated local error (which can be changed in options). In the simplest case the right hand side is computed by a Scilab function with three arguments, for example for y the residual function is coded as

function res = f(t,y,yp)
  res = yp+y
end

See the IDA user functions to learn how to pass extra parameters and/or use DLL entrypoints. When t has more than two components:

[t,y,yp] = ida(f,[t0 t1 ... tf],y0,yp0)

the solution is computed at prescribed points with the same precision as the two components syntax. However, the result may slightly differ (within chosen tolerance) since t1-t0 may give a different guess of the initial step used by the solver. Solver internal steps are the same and solution at user points is computed by continuous extension formulas.

When searching for (t,y,yp) where some functions defined in options vanish (see the Events section below) the syntax

[t,y,yp,te,ye,ype,ie] = ida(f,tspan,y0,yp0,options)

allows to recover (t,y,yp) values in te,ye,ype and in ie the number(s) of the vanishing function.

When solution has to be further evaluated at arbitrary points which are not known in advance, then the syntax

sol = ida(f,[t0 tf],y0,yp0)

yields an MList of _odeSolution type, which can be used later as an interpolant, see the Solution output section.

When y0 and/or yp0 do not fullfill the equation at initial time they can be used as initial guesses when using the calcIc option, see the Initial conditionssection.

Example

In the following example, we solve the equations of the SIR model. The right hand side is computed by the function %ida_sir (defined in the Sundials module):

function r=%ida_sir(t, y, yp)
    r = [yp(1)+0.2*y(1)*y(2)
         yp(2)-0.2*y(1)*y(2)+0.05*y(2)  
          y(1)+y(2)+y(3)-1];
end

y0  = [1-1e-6; 1e-6; 0];
yp0 = [-2e-7; 1.5e-7; 5e-8];
[t,y] = ida(%ida_sir, [0,200], y0, yp0);
clf
plot(t, y)

Initial conditions

When y(0) is known but y'(0) is not known it can be computed by using the calcIc option with value "y0yp0" and yp0 is used as an initial guess:

y0  = [1-1e-6; 1e-6; 0];
yp0 = zeros(3,1);
[t,y,yp] = ida(%ida_sir, [0,200], y0, yp0, calcIc="y0yp0");
disp(yp(:,1))

This option also allows to compute purely algebraic states by using the yIsAlgebric = idx option, where idx is a vector with the indexes of such states. When y'(0) is known but y(0) is not, use calcIc option with value "y0".

Events

Agebraic equations to be solved simultaneously with the integration of the equation can be specified by using the events option:

[t,y,yp,te,ye,ype,ie] = ida(f,tspan,y0,yp0,events = g)

where g in its simplest form is a Scilab function with prototype [eq,term,dir] = g(t,y,yp), where eq(i)=0 when event i occurs, term is a boolean vector, with term(i)=%t value if integration has to be stopped when event i occurs. Vector dir allows to select event direction, with term(i) can take the values -1,1 if solution has to be decreasing or increasing or 0 if direction does not matter. If the corresponding behavior does not matter, dir or both term,dir outputs can be omitted in the function prototype. For example, in order to find the time and value of the maximum of y2 in SIR model above we use the following code:

function eq=g(t, y, yp)
    eq = yp(2)
end
y0=[1-1e-6;1e-6;0];
yp0=[-2e-7;1.5e-7;5e-8];
[t,y,yp,te,ye] = ida(%ida_sir, [0,200], y0, yp0, events=g);
clf
plot(t,y,te,ye(2),'or')
xstring(te,ye(2),msprintf("t=%g, y=%g",te,ye(2)))

Solution output

The syntax sol = ida(f,[t0 tf],y0,yp0) yields an MList with fields sol.solver (the solver name, here "ida"), sol.method = "bdf", sol.t (the solver time steps), sol.y, sol.yp (the solution and its derivative at solver timesteps), sol.idata (a pointer to an internal IDA object) and sol.stats, a structure hosting the solver statistics. When events have been considered additional fields sol.te, sol.ye, sol.yp, sol.ie are also present.

For an arbitrary time vector t, with values in the interval [t0,tf], y=sol(t) yields by costless interpolation the same approximation as if components of t where used in tspan. The MList sol can also be used to restart the solver and extend the solution for t>tf (see the following section). The derivative of solution can also be obtained with [y,yp]=sol(t) and a particular component i of the solution is obtained with y=sol(t,i). For example, the solution of SIR equation can be refined in [95,100] with the following code

y0=[1-1e-6;1e-6;0];
yp0=[-2e-7;1.5e-7;5e-8];
sol = ida(%ida_sir,[0,200],y0,yp0);
t = linspace(95,100,1000);
clf
plot(t,sol(t,2),sol.t,sol.y(2,:),"o")
gca().data_bounds = [95,100,0.396,0.404];

Extending a solution

The syntax solext = ida(sol,tfinal) extends the solution by restarting the solver from initial time sol.t($) and initial conditions sol.y(:,$), sol.yp(:,$). It can be used when you know in advance that the solution is not differentiable at some time point. By stopping then restarting the solver at time of discontinuity you optimize solver effort by avoiding very small time steps. In the options sequence you can change almost all previously used options used in the call of ida which yielded sol. The right hand side and the initial conditions can be overriden by using the specific f option and y0,yp0 options, respectively.

See also

Bibliography

A. C. Hindmarsh, P. N. Brown, K. E. Grant, S. L. Lee, R. Serban, D. E. Shumaker, and C. S. Woodward, "SUNDIALS: Suite of Nonlinear and Differential/Algebraic Equation Solvers," ACM Transactions on Mathematical Software, 31(3), pp. 363-396, 2005. Also available as LLNL technical report UCRL-JP-200037.


Report an issue
<< CVODE user functions sci_sundials IDA user functions >>