File kernel/src/modelingTools/FirstOrderNonLinearR.hpp

Go to the source code of this file

General interface for first-order nonlinear relations.

class FirstOrderNonLinearR : public FirstOrderR

#include <FirstOrderNonLinearR.hpp>

FirstOrder Non Linear Relation.

This is the most generic relation for First Order Dynamical Systems, with:

\[\begin{split} y &=& h(X,t,\lambda,Z) \\ R &=& g(X,t,\lambda,Z) \end{split}\]

where X, Z, and R corresponds to DynamicalSystem variables. If more than 2 DynamicalSystem are involved in the Interaction, then X = [x1 x2], Z=[z1 z2] R = [r1 r2].

\( y \) and \( \lambda \) are specific variables of the Interaction (see this class for more details).

Let us define the following jacobians:

\[\begin{split} C &=& \nabla_x h\\ B &=& \nabla_{\lambda} g\\ D &=& \nabla_{\lambda} h\\ K &=& \nabla_x g. \end{split}\]

There are 2 ways to define this relation:

• by using the plugin mechanism of calling C functions

• by using the inheritance mechanism (of C++ or Python) and overloading methods.

For the plugins, the following definitions are mandatory:

• A function to compute \( h \) with signature

   (double time, unsigned x_size, double *x, unsigned size_lambda,
  double* lambda, double *y, unsigned z_size, double *z) 
  

• A function to compute \( g \) with signature

   (double time, unsigned x_size, double *x, unsigned size_lambda,
  double* lambda, double *r, unsigned z_size, double *z) 
  

Note that the size of \( y \) is the same as \( \lambda \), and the size of \( R \) is the same as \( X \) . Thus those are not specified in the plugin function signatures.

For the various jacobians, there are two possibilities: If one is constant, the value may directly be set: for instance, if \( C \) is constant, then one can use setCPtr to fix the value. A word of cautions: whenever a jacobian matrix is fixed using this call, then the corresponding C++ function (and not plugin) is not called anymore. A small example: if \( C \) is fixed via setCPtr, then computeJachx is never called again.

The other option is to use the plugin mechanism. They all share the same signature:

 (double time, unsigned x_size, double *x, unsigned size_lambda,
double* lambda, double *mat, unsigned z_size, double *z) 

where mat is the pointer to the array of values for each Jacobian. This implies that only dense matrix are supported.

Public Functions

inline FirstOrderNonLinearR()

basic constructor

virtual ~FirstOrderNonLinearR() noexcept = default

destructor

virtual void initialize(Interaction &inter) override

initialize the relation (check sizes, memory allocation …)

Parameters:

inter – the interaction using this relation

virtual void checkSize(Interaction &inter) override

check sizes of the relation specific operators.

Parameters:

inter – an Interaction using this relation

virtual void computeh(double time, const BlockVector &x, const SiconosVector &lambda, BlockVector &z, SiconosVector &y)

default function to compute \( h \)

Parameters:

• time – current time

• x – current state variables

• lambda – current nonsmooth variables

• z – current auxiliary variable

• y – [out] output value

virtual void computeg(double time, const BlockVector &x, const SiconosVector &lambda, BlockVector &z, BlockVector &r)

default function to compute \( g \)

Parameters:

• time – current time

• x – current state variables

• lambda – current nonsmooth variables

• z – current auxiliary variable

• r – [out] input value

virtual void computeJachx(double time, const BlockVector &x, const SiconosVector &lambda, BlockVector &z, SimpleMatrix &C)

default function to compute \( C = \nabla_x h \)

Parameters:

• time – current time

• x – current state variables

• lambda – current nonsmooth variables

• z – current auxiliary variable

• C – [out] jacobian matrix

virtual void computeJachlambda(double time, const BlockVector &x, const SiconosVector &lambda, BlockVector &z, SimpleMatrix &D)

default function to compute \( D = \nabla_{\lambda} h \)

Parameters:

• time – current time

• x – current state variables

• lambda – current nonsmooth variables

• z – current auxiliary variables

• D – [out] jacobian matrix

virtual void computeJach(double time, Interaction &inter) override

compute all the H Jacobian

Parameters:

• time – the current time

• inter – the interaction using this relation

virtual void computeJacglambda(double time, const BlockVector &x, const SiconosVector &lambda, BlockVector &z, SimpleMatrix &B)

default function to compute \( B = \nabla_{\lambda}g \)

Parameters:

• time – current time

• x – current state variables

• lambda – current nonsmooth variables

• z – current auxiliary variables

• B – [out] jacobian matrix

virtual void computeJacgx(double time, const BlockVector &x, const SiconosVector &lambda, BlockVector &z, SimpleMatrix &K)

default function to compute \( K = \nabla_{\lambda}g \)

Parameters:

• time – current time

• x – current state variables

• lambda – current nonsmooth variables

• z – current auxiliary variables

• K – [out] jacobian matrix

virtual void computeJacg(double time, Interaction &inter) override

compute all the G Jacobian

Parameters:

• time – the current time

• inter – the interaction using this relation

• interProp –

virtual void computeOutput(double time, Interaction &inter, unsigned int level = 0) override

default function to compute y, using the data from the Interaction and DS

Parameters:

• time – current time (not used)

• inter – Interaction using this Relation

• level – not used

virtual void computeInput(double time, Interaction &inter, unsigned int level = 0) override

default function to compute r, using the data from the Interaction and DS

Parameters:

• time – current time (not used)

• inter – Interaction using this Relation

• level – not used

inline virtual bool requireResidu() override

return true if the relation requires the computation of residu

Returns:

true if residu are required, false otherwise

Protected Functions

ACCEPT_SERIALIZATION(FirstOrderNonLinearR)