Libnum Classes

Namespace NumericMethods

See: gear.h, gear.asst.h, gear.proc.h and gear.output.h files.

class GearUserProc;
struct GearEngineContext;
class GearEngineCallback;
class GearAssistant;
typedef DoubleParamsMap GearParams;
class GearStatistics;
class GearAllocator;

class Gear
{
 public:
  Gear();
 ~Gear();
  void set(int n, GearUserProc* derFunc, GearUserProc* jacFunc);
  void setCallback(GearEngineCallback& f);
  Message solve(const double t_begin, const double t_end, const double* y0);
  GearEngineContext engineContext;
  GearAssistant assistant;
};

The 'set' method of Gear objects defines the dimension, starting Y values and functions to calculate the derivative function values and DY, the Jacobian.

The Gear object has its private Allocator which provides memory to consecutive runs of 'solve' procedure.

The rest settings and user interactions are done via GearAssistance object, the public property of the Gear object. E.g. 'parameters', 'statistics'.

The Base class of procedures to calculate y'= ∂y/∂t and jacobian = Dy'/Dy. May be used as the default, being the wrapper of ordinary C-functions bool(*)(int n, double t, const double* y, double* result).

class GearUserProc {
 public:
  typedef bool(*PUDF)(int, double, const double[], double[]);
  GearUserProc(PUDF = nullptr);
  //virtual bool operator()(int n, double x, const double y[], double result[]);
  virtual bool call(int n, double x, const double y[], double result[]);
};

Read-only references to member variables of the Gear object.

struct GearEngineContext
{
 const int&    n;        // dimension
 const int&    q;        // current degree of interpolation
 const double& h;        // current step of integration 
 const double& t;        // current time
 const double* const& Z; // values (ref to Z[])
};

The hook/callback object in Gear::solve(). The Base class for user defined interfaces. Default callback does nothing. Use GearEngineCallbackEmbed to provide an ordinary C-function.

class GearEngineCallback
{
 public:
  virtual bool call(const GearEngineContext&) {
    return true;  // return 'false' to cancel caller proc
  }
};

class GearEngineCallbackEmbed : public GearEngineCallback
{
 public:
  typedef bool (*PCallback)(const GearEngineContext&);
  GearEngineCallbackEmbed(PCallback = nullptr); // nullptr -- no output in solve()
  virtual bool call(const GearEngineContext&) override;
};

class GearAssistant
{
 public:
  GearParams     params;
  GearStatistics statistics;
};

class GearAllocator
{
 public:
  GearAllocator(Gear& owner);
  ~GearAllocator();
  bool allocateMemory(int task_dimension);
};

class DoubleParamsMap
{
 public:
  DoubleParamsMap() : params() {}
  bool declareParameter(const char* name, double value=0);
  bool setParameter(ParamID id, double value);  // parameter SHOULD be declared before!
  double getParameter(ParamID id) const;
  std::string getParameterNames() const;  // informative/debug purposes
 private:
  std::map<ParamID,double> params; 
};

GearEngine tuning parameters are (doubles):

EPS = 0.01;
HINI = 1e-10;
HMIN = 1e-18;
HMAX = BIG_VAL;
RHMAX = 1;

See Gear Algorithm for details.

The Output is implemented via GearEngineCallback interface. The most GearEngine data are available via GearEngineContext object, passed to its method call(const GearEngineContext& context).

The libnum library includes the following two classes for general useage: GearPrintToStream and GearPrintTable. Both interfaces use user-declared output stream for their target (see STL manual). It can be:

• standard C output stream stdout (std::cout)
• string buffer (std::stringstream)
• file (std::ofstream)
• and the like

The GearPrintToStream interface enables us to output time/values data of each integration point into the output stream, GearPrintTable outputs tabulated data (it uses interpolation to calculate variables' values for user declared output time-step). One can set a format of double value presentation, std::format syntax being supposed, for example “{:8.5f}\t”.

class GearPrintToStream : public GearEngineCallback
{
public:
  GearPrintToStream(std::ostream& target, const char* format = "{} ");
  virtual bool call(const GearEngineContext&) override;
  void setFormat(const char* format);
};

class GearPrintTable : public GearPrintToStream
{
public:
  GearPrintTable(std::ostream& target, double output_step, const char* format = "{} ");
  virtual bool call(const GearEngineContext&) override;
  void reset();
};

[ Libnum classes ] [ Examples of usage ]