====== Libnum Classes ======
===== Gear Integration Method =====

===== class Gear; =====
Namespace //NumericMethods//

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

class [[#GearUserProc|GearUserProc]]; \\
struct [[#GearEngineContext|GearEngineContext]]; \\
class [[#GearEngineCallback|GearEngineCallback]]; \\
class [[#GearAssistant|GearAssistant]]; \\
typedef DoubleParamsMap [[#GearParams|GearParams]]; \\
class [[#GearStatistics|GearStatistics]]; \\
class [[#GearAllocator|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'.

===== GearUserProc =====
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[]);
  };

===== GearEngineContext =====
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[])
  };
===== GearEngineCallback =====
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;
  };

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

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

===== GearParams =====
  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.

===== Gear Output =====
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 [[https://en.cppreference.com/w/cpp/io/basic_ostream.html|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:gear|Examples of usage]] ]