Callback Specifying a user callback

## Syntax

                ... = solver( ... , callback = cbFn)

## Arguments

cbFn | A Scilab function, a list or a string

## 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
- cvode
- ida
- kinsol
- User functions
- Options (ODE and DAE solvers)
- Options (kinsol)
- SUN_Clink