# Class FirstOrderNonLinearR¶

class FirstOrderNonLinearR : public FirstOrderR

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)

• interInteraction 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)

• interInteraction 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