Callback

Arguments

Description

While solving nonlinear equations or integrating ODEs or DAEs, the solver can call a Scilab function or SUNDIALS DLL entrypoint after every successfull internal or user prescribed step. General information about the different ways of providing a user function (and eventual user parameters) is given in the User Functions help page.

Callback function given as a Scilab function

In that case cbFn is a Scilab function with prototype

term = cbFn(y,flag,stats, ...)
term = cbFn(t,y,flag,stats, ...)
term = cbFn(t,y,yp,flag,stats, ...)

for nonlinear equations, ODEs or DAEs, respectively. The flag input argument can take the string values "init", "step", "event" (ODE and DAE only) or "done" and stats is a structure gathering the solver statistics. The function has to return %f to continue iterations whereas returning %t will stop the solver. Here is a basic example displaying a progressbar when solving an ODE with solver time synchronization:

function out=cbFn(t, y, flag, stats, tf)
    global h
    if flag == "init"
        h=waitbar(0)
        realtimeinit(1)
        realtime(0)
    elseif flag == "step"
        waitbar(t/tf,msprintf("t = %g s",t),h)
        realtime(t)
    else
        delete(h)
    end
    out = %f
end
cvode(%SUN_vdp1,[0 10],[2;1],callback=list(cbFn,10))

Callback function given as a SUNDIALS DLL entrypoint

In that case cbFn must have the C prototype

int cbFn(int flag, N_Vector Y, void *user_data)
int cbFn(realtype t, int flag, N_Vector Y, void *user_data)
int cbFn(realtype t, int flag N_Vector Y, N_Vector Yp, void *user_data)

for nonlinear equations, ODEs or DAEs, respectively. The entrypoint has to return 0 or 1, for normal continuation or solver termination, respectively. The flag input argument takes values -1,0,1 or 2 for "init", "step", "done" and "event" solver phases. Here is an example where values of an ODE solution are written to a text file in the current directory:

code=[
    "#include <stdio.h>"
    "#include <nvector/nvector_serial.h>"
    "FILE *fp;"
    "int sunRhs(realtype t, N_Vector Y, N_Vector Yd, void *user_data)"    
    "{"
    "double *y = NV_DATA_S(Y);"
    "double *ydot = NV_DATA_S(Yd);"
    "ydot[0] = -y[0]*y[0];"
    "return 0;"
    "}" 
    "int sunCb(realtype t, int flag, N_Vector Y, void *user_data)"
    "{"
    "double *y = NV_DATA_S(Y);"
    "if (flag == -1) {"
    "  fp = fopen(""output.txt"",""w"");"
    "} else if (flag == 2) {"
    "  fclose(fp);"
    "  return 0;"
    "}"
    "fprintf(fp,""t=%f, y=%f, flag=%d\n"",t, y[0], flag);"
    "return 0;"
    "}"];
mputl(code,"code.c");
SUN_Clink(["sunRhs","sunCb"],"code.c",load=%t);
cvode("sunRhs",[0 1],1,callback="sunCb");
mgetl("output.txt")

See also

• arkode — SUNDIALS ordinary differential equation additive Runge-Kutta solver
• cvode — SUNDIALS ordinary differential equation solver
• ida — SUNDIALS differential-algebraic equation solver
• kinsol — SUNDIALS general-purpose nonlinear system solver
• User functions — Coding user functions used by SUNDIALS solvers
• Options (ODE and DAE solvers) — Changing the default behavior of solver
• Options (kinsol) — Changing the default behavior of solver
• SUN_Clink — Compiling and linking a C user function