include/sk_solv.h

   1 /* Apache 2.0 INS-AMU 2015 */
   2
   3 /**
   4  * \file sk_solv.h
   5  *
   6  * \brief sk_solv.h defines sddekit's solver framework in terms of a system,
   7  * a time-stepping scheme and an output handling callback.
   8  */
   9
  10 #ifndef SK_SOLV_H
  11 #define SK_SOLV_H
  12
  13 #include "randomkit.h"
  14 #include "sk_hist.h"
  15
  16 /**
  17  * SK_DEFSYS aids in creating a new system defintion.
  18  * See ::sk_sys for explanation of callback signature.
  19  *
  20  * \param name name of expanded system definition.
  21  */
  22 #define SK_DEFSYS(name) int name(\
  23                 void *data,\
  24                 double t,\
  25                 int nx, double *x, double *f, double *g,\
  26                 double *Jf, double *Jg,\
  27                 int nc, double *c)
  28
  29 /**
  30  * Callback signature expected by solver framework for system definitions.
  31  * Use #SK_DEFSYS to declare or define a new system.
  32  *
  33  * \param data user data passed to system for defining e.g. parameters of the system.
  34  * \param t current time in solution.
  35  * \param nx number of state variables of system.
  36  * \param x vector of current state variable values.
  37  * \param f vector of drift terms per state variable.
  38  * \param f vector of diffusion terms per state variable.
  39  * \param Jf Jacobian of drift terms.
  40  * \param Jg Jacobian of diffusion terms.
  41  * \param nc number of coupling terms.
  42  * \param c vector of afferent coupling terms as input, efferent coupling as output.
  43  * \return 0 to indicate success.
  44  */
  45 typedef SK_DEFSYS((*sk_sys));
  46
  47 /** SK_DEFSCH aids in creating a new scheme definition.
  48  * See ::sk_sch for details of the generated callback signature.
  49  *
  50  * \param name name of scheme being defined.
  51  */
  52
  53 #define SK_DEFSCH(name) int name(\
  54         void *data, rk_state *rng,\
  55         sk_sys sys, void *sysd,\
  56         double t, double dt,\
  57         int nx, double *x,\
  58         int nc, double *c)
  59
  60 /**
  61  * Callback signature expected by solver framework for scheme definitions.
  62  * Use #SK_DEFSCH to declare or define a new scheme.
  63  *
  64  * \param data user data for scheme such as storage for intermediate steps
  65  * \param rng random number generator state
  66  * \param sys system being solved
  67  * \param sysd user data for system
  68  * \param t current time
  69  * \param dt current time step to use
  70  * \param nx number of state variables
  71  * \param x state variable vector
  72  * \param nc number of coupling variables
  73  * \param c coupling variable vector
  74  * \return 0 in case of success
  75  */
  76 typedef SK_DEFSCH((*sk_sch));
  77
  78 /** SK_DEFOUT aids in creating a new output definition.
  79  * See ::sk_out for details of the generated output callback signature.
  80  *
  81  * \param name name of output callback being defined.
  82  */
  83 #define SK_DEFOUT(name) int name(void *data,\
  84                 double t,\
  85                 int nx, double *x)
  86
  87 /**
  88  * Callback signature expected by solver framework for output callbacks.
  89  * Use #SK_DEFOUT to declare or define a new output callback.
  90  *
  91  * \param data user data for output function such as simulation length.
  92  * \param t current time.
  93  * \param nx number of state variables.
  94  * \param x state variable vector.
  95  * \return 1 if the solver should continue, 0 to stop solver.
  96  */
  97 typedef SK_DEFOUT((*sk_out));
  98
  99 /* TODO typedef */
 100 typedef struct
 101 {
 102         int nx, nc, cont;
 103         sk_sys sys;
 104         sk_sch sch;
 105         sk_out out;
 106         void *sysd, *schd, *outd, *hfd;
 107         sk_hist_filler hf;
 108         sk_hist hist; /* nd==nc, ci, cd */
 109         rk_state rng;
 110         double t, dt, *x, *c, *x0;
 111 } sk_solv;
 112
 113 /**
 114  * Initialize a solver.
 115  *
 116  * \note references are maintained to all parameters, thus must remain
 117  * valid for the lifetime of the solver instance.
 118  *
 119  * \param solv solver to initialize.
 120  * \param sys system to be integrated
 121  * \param sys_data user data passed to sys
 122  * \param scheme time-stepping scheme to use for solution
 123  * \param scheme_data user data passed to scheme
 124  * \param out output handler
 125  * \param out_data
 126  */
 127 int sk_solv_init(
 128         sk_solv *solv,
 129         sk_sys sys, void *sys_data,
 130         sk_sch scheme, void *scheme_data,
 131         sk_out out, void *out_data,
 132         sk_hist_filler hf, void *hfill_data,
 133         int seed,
 134         int nx, double *x0,
 135         int nc, int *vi, double *vd,
 136         double t0, double dt
 137         );
 138
 139 /**
 140  * Frees the internal data structures in *s, but user is
 141  * responsible for free the memory at s.
 142  *
 143  * \param s solver
 144  */
 145 void sk_solv_free(sk_solv *s);
 146
 147 /**
 148  * Continue solution described in *s
 149  *
 150  * \param s solver.
 151  * \return 0 if successful else 1.
 152  */
 153 int sk_solv_cont(sk_solv *s);
 154
 155 #endif