Kernel Components > Simulation

Release Information

Project: Siconos
Internal Release Number: 1.0
Last update: November 29, 2006
Related Documents:
     

Simulation component


What for? all classes/objects to define a simulation to solve the pre-defined NonSmoothDynamicalSystem.
Feature sets: F-2001. and F-2.100, F-2.106;
Depencies: Siconos/Numerics, Input-output (xml), Modeling
Interfaces: Siconos/Numerics
Sources directory name: Kernel/src/simulationTools

To find more details on objects described in this section, see Doxygen documentation of Siconos/Kernel.

Siconos Simulation and related objects

Simulation object is used to describe how a previously defined NonSmoothDynamicalSystem will be computed.

So before starting any simulation process, you need to have a complete non smooth dynamical system (roughly some DynamicalSystems and some Interactions), attached to a Model. Then the key points of the Simulation are:

Above all these points, a global strategy must be defined. At the time, two possibilities exist in Siconos:

classSimulation.png
For a complete description of Time Stepping and Event Driven algorithm see the User Manual related pages at Moreau's Time Stepping scheme or Event Driven algorithm

Finally to build a Simulation, four steps are required:

and so, the C++ code looks like:

// Prerequisite: 
// a Model*, say m, that holds a NonSmoothDynamicalSystem* named nsds. 
//
// Step 1: choose the strategy, build the Simulation and link it to the Model
TimeStepping * s = new TimeStepping(m); 

// or
EventDriven * s = new EventDriven(m);

// Step 2: the time discretisation, linked with the Simulation when built. 
TimeDiscretisation * td = new TimeDiscretisation(...,s)


// Step 3: OneStepIntegrators; applied to DynamicalSystems that belong to nsds.
Moreau * integrator = new Moreau(someDS,...,s) ; 
// or
Lsodar * integrator = new Lsodar(someDS,s);

// Step 4: OneStepNSProblems; applied to all the Interactions of the nsds.
OneStepNSProblem * lcp = new LCP(s, ...)

Then, from this point the Model is complete and the simulation process can start. Its development depends strongly on the chosen strategy and will then be detailed in the corresponding sections (see Moreau's Time Stepping scheme or Event Driven algorithm).
Warning: it is important to make a clear difference between the building of the Simulation, which is part of the Model, and the computation process which consists mainly in some calls to specific functions of the Simulation.

Main components of a Simulation

Time Discretisation

The discretization scheme is characterized by a vector of size nSteps+1, denoted tk, that handles the values at each time-step, nSteps being the number of time steps. At the time, only constant time-step (denoted h) time discretisation is available.
A TimeDiscretisation must be linked to one and only one Simulation (required parameter of any constructor). The initial time value is always given by the Model that holds the Simulation, while the final time value is an optional parameter of the Model. Thus depending on the constructor you use, you may need to give the time-step, the final time ... Just take care to avoid redundant or conflicting information. See the constructors list in the TimeDiscretisation class documentation for full details.

Example:

Model * m = new Model(t0); // only initial time is provided
Simulation * s = new TimeStepping(m); // s belongs to the Model m

double h = ...;
unsigned int nSteps = ...;
TimeDiscretisation * td = new TimeDiscretisation(h, nSteps);
// tk and final time will be automatically computed. 

One Step Integrators

OneStepIntegrator ("OSI") class defines how Dynamical Systems will be integrated over a time-step. Two types of integrators are available at the time in the platform: Moreau (see details in docSimuMoreau) and Lsodar.
To build an OSI, you need to provide a set of DynamicalSystems (and possibly a set of Interactions) and some specific values depending on the type of the integrator. Moreover, the "size of the memory" (variable sizeMem) can be set: it concerns the number of time steps for which states values are saved, but at the time no multi-steps integrators are available in Siconos, so keep default value, 1.

main functions:

  • integrate(t0, t, ...): integrate the system between t0 and t.
  • updateState(...): computes DynamicalSystems states values

Moreau

Integration thanks to a theta-method. See docSimuMoreau for a full description.

Main variables: $ \theta $ (a double) and $ W $ (a matrix of double). One value of each parameter is attached to each DynamicalSystem concerned by the OSI through a map (STL). For example:

// allDS is a set of DynamicalSystems : ds1, ds2 ...

// s is a Simulation*
Moreau * integrator = new Moreau(allDS, 0.5, s);
// all values of theta are initialized to 0.5

double theta = integrator->getTheta(ds1);

// returns the value of theta for the dynamical system ds1.

SiconosMatrix * W = integrator->getW(ds1);
// W is a SimpleMatrix *, that represents the W linked to ds1. 

Lsodar

This class is an interface for LSODAR, odepack integrator (see http://www.netlib.org/alliant/ode/doc).
"Lsodar solves problems dy/dt = f with full or banded Jacobian and automatic method selection, and at the same time, it finds the roots of any of a set of given functions of the form g(t,y). This is often useful for finding stop conditions or points at which switches are to be made in the function f".
In Siconos, Lsodar is used for EventDriven algorithm, to integrate the dynamics with stops at new non-smooth events (violation of a constraint). That will be detailed in Event Driven algorithm.

Construction:

// allDS is a set of DynamicalSystems and s a Simulation*

Lsodar * integrator = new Lsodar(allDS,s);
At the time, all specific parameters of Lsodar are set by default, but you can set them thanks to set functions. See Lsodar class doxygen documentation for details.

One Step Non Smooth Problems

Considering a set of Interactions, the role of the OneStepNSProblem ("OSNS") is to write in a "pleasant" form the non smooth problem and then to solve it. So, the main variables of this class are:

Non smooth solvers

Solvers algorithms are implemented in Numerics package and Kernel Solver class is just an interface to those algorithms. The possible solvers are:
  • LexicoLemke (maxIter)
  • NLGS (Non Linear Gauss Seidel) (tolerance, maxIter)
  • NSQP (Non Smooth Quadratic Programming) (tolerance)
  • QP (tolerance)
  • CPG (Conjugate Projected Gradient) (tolerance, maxIter)
  • Latin (tolerance, maxIter, searchDirection)

For each of them, the required parameters are indicated between parenthesis. Their default values are:

  • maxIter (maximum number of iterations): 101
  • tolerance: 0.0001
  • normType: "max"
  • searchDir: 0.6

Obviously, depending on the problem type, some solvers fit more than others.

LCP formalization and solving

A Linear Complementarity Problem (LCP) is defined by :

\begin{eqnarray*} w = Mz+q \\ w \geq 0, z \geq 0, z^{T} w = 0 \end{eqnarray*}

where $ w \in R^{n} $ and $ z \in R^{n} $ are the unknowns and $ M \in R^{n \times n } $ and $ q \in R^{n} $.

Thus, "formalizing" a LCP consists in writing M matrix and q vector (functions assembleM and computeQ ).

Friction-Contact Non Smooth Problem

In Siconos, a Friction Contact is written as a LCP like above:

\begin{eqnarray*} w = Mz+q \\ w \geq 0, z \geq 0, z^{T} w = 0 \end{eqnarray*}

plus a Coulomb-Friction law.

Unitary Relations and Index Sets

Warning: reading this section is only useful if you need more understanging and details in EventDriven algorithm.

classes: UnitaryRelation, UnitaryRelationsSet

The Simulation class has a specific member named indexSets, which is a vector (STL) of UnitaryRelationsSet.

Unitary Relation definition

Remember that each Interaction has two specific local variables, named y (output) and $ \lambda $, used to define the non-smooth behavior of the system. The size of the Interaction was defined as the one of y vector. Roughly speaking y corresponds to a set of constraints applied to the system, like in Linear Relations (LinearTIR) where: $ y = CX + FU + D \lambda + e $

In that case, if D is diagonal, the previous set is equivalent to n independent scalar equations, n being the size of the Interaction: $ y_i = C_i X +F_i U + d_{ii} \lambda_i+e_i $

So a model with n Interactions of size one with the n relation $ y_i = \cdots $ will be equivalent.
But if D is not diagonal, all relations are to be treated all together, in one block. The same think occurs for a friction problem, where the minimum block size is 2 or 3 (for 2 or 3 dimensional friction) because we need to consider normal and tangential part(s) of y.

So to avoid confusion during Simulation process, we define UnitaryRelation object, which "cuts" the Interaction and its vectors into the smallest possible blocks. The size of these blocks corresponds to the non-smooth law size.

What is important is that during Simulation process we do not handles Interactions but UnitaryRelations. From the user point of view, that did not change anything and since Interactions and UnitaryRelations are linked you can goes on using Interactions in a transparent way. But if you intend to use or have a look into IndexSets, you should know what they handle, UnitaryRelations.

Index Sets definition

As suggested at the end of the previous section, an index set is a set of unitary relations.
Thus we define $ I_0 $ as the sets of all the unitary relations of the system, which more or less corresponds to the set of all the Interactions of the NonSmoothDynamicalSystem.
For example, in a contact-problem, that represents all the unilateral constraints (active or not). The set $ I_0 $ is saved in the Topology of the NonSmoothDynamicalSystem, and build during Simulation initialization. From this one, we define all the other sets:

\[ I_i = \{ UR\in I_{i-1} , y_{ur}[i-1] = 0 \} \]

with UR=UnitaryRelation, and $ y_{ur}[i-1] $ the i-1 derivative of the relation of ur.

Event Driven algorithm

General Principle

The principle of the event-driven is based on the time-decomposition of the dynamics in modes, time-intervals where the dynamics is smooth, and discrete events, times where the dynamics are nonsmooth. From the numerical point of view, the event-driven scheme use the decomposition in time of the dynamics in order to
  • detect and solve the non smooth dynamics at events with a reinitialization rule of the state,
  • integrate the smooth dynamics between two events with any ODE solvers with root-findings and possibly bilateral constraints on the state.

Event Driven implementation

Related classes: EventDriven, EventsManager, TimeDiscretisationEvent, NonSmoothEvent, Lsodar.
The figure below represents the class architecture for EventDriven simulation.

classEventDriven.png

Integration of the smooth dynamics

Between events, the dynamics are integrated thanks to Lsodar algorithm and with the function EventDriven::integrate.
Considering two given functions f(x,t) and g(x,t), a call to integrate(tinit, tend, tout, iout) results in the integration of the function f(x,t) between tinit and tend, and search for roots of the function g(x,t). If roots are found, integration stops, and last time is saved in tout.
The in-out parameter iout is an indicator that must be set to 1 at first call. If no root was found, it is equal to 2 if so to 3.
Thus for an EventDriven simulation:
  • the dynamics of all the concerned DynamicalSystems is rewritten as $ \dot = f(x,t) $
  • the relations are used to defined the g(x,t) functions

Once again the proper definition of f and g depends on the system type, so for details see Event Driven algorithm for Lagrangian systems.

Events

In Siconos the object Event just handle a type (see below) and a long int which corresponds to the time of occurrence of the event. A process function is also defined, which action depends on the event type.

The possible types (derived classes) are:

  • TimeDiscretisationEvent: event that corresponds to user-defined time discretisation points. These events are created and schedule when the EventDriven simulation is initialized. Process function call results in :
    • update (compute) output for all the concerned Interactions
    • save current values (DynamicalSystems states and Interactions input/output) in memory vectors. Last saved values become initial values for next integration.

  • NonSmoothEvent: "points" where the dynamics are non smooth and which required a special treatment. These events are detected thanks to a roots-finding algorithm, and corresponds to violation of some given constraints (relation). The action of the process function is roughly (the full process depends on the system type and is described in Event Driven algorithm for Lagrangian systems):
    • update (compute) output for all the concerned Interactions
    • update the index sets
    • formalize and solve one or more non-smooth problems
    • save current values (DynamicalSystems states and Interactions input/output) in memory vectors. Last saved values become initial values for next integration.

The Events manager

To handle all the events, a specific object is built: the EventsManager. It belongs to the EventDriven class and holds two eventsContainers (sets of Events):
  • pastEvents: for all the Events that has already been treated
  • unProcessedEvents: for the future events, already scheduled but not treated We also denote "currentEvent" the last processed event, which corresponds to the initial point of the current integration, and "nextEvent" the event following "currentEvent".

The events manager is initialized with time-discretisation events, from the user time-discretisation. Then, each time a new event is detected (added by user or when a root is found during integration) it is scheduled in the manager.
The manager has also a processEvents function, which moves currentEvent to past events set, processes nextEvent and prepare the next step.

Other useful functions are:

The Simulation process

Thus, a general step of integration for EventDriven will looks like: "While there are some events in the unProcessedEvents set, integrate the smooth dynamics between current and next event and then process with the behavior at event". Or:
EventDriven * s = new EventDriven(myModel);

s->initialize();

// We get the events manager
EventsManager * eventsManager = s->getEventsManagerPtr();

// while there are some events ...
while(eventsManager->hasNextEvent())
{
  // integrate between current and next event
  s->advanceToEvent();
  // solve the non-smooth dynamics, if necessary ...
  eventsManager->processEvents();
}

// Or in one step:
while(eventsManager->hasNextEvent())
{
 s->computeOneStep();
}

Event Driven algorithm for Lagrangian systems

Foreword: At the time, the only available event-driven algorithm in Siconos is for Lagrangian dynamical systems, subjected to perfect unilateral constraints and with the Newton impact rules.
A full description of such systems will be given in the Theoretical Manual and the results below are just a short and incomplete summary.

Because of the unilateral constraints, the evolution of the considered system may be non-smooth. Some jumps can occur in the velocity and the "acceleration" may not be defined everywhere. The generalized coordinates, assumed to be absolutely continuous are:

\[ q(t) = q(t_0) +\int_{t_0}^t v^+(t)dt \ with \ v = \dot q \]

We will index with "+" and "-" right and left values of the variable at discontinuity.

The equations of motion are written in terms of a measure differential equation:

\[ M(q)dv + F_{int}(t, q, v^+)dt=F_{ext}(t) + dr \]

r being the generalized force due the unilateral constraints. Using the Lebesgue decomposition theorem and its variants, the differential measure dv and dr are decomposed in:

\begin{eqnarray*} dv = \gamma dt + (v^+-v^-)\sum_i\delta_{t_i} + dv_s \\ dr = fdt + \sum_ip_i\delta_{t_i}+dr_s \end{eqnarray*}

First term of the decomposition corresponds to the smooth part, with $ \gamma =\ddot q $, the acceleration in the usual sense. The second term corresponds to the behavior at times of discontinuities, ( $ \delta_{t_i} $: Dirac), and the last term, a singular measure, will be neglected.

Thanks to these decompositions, the non-smooth Dynamics can be split into "impact equations", that will correspond to the non-smooth events, and some "smooth Dynamics". These equations are completed by the constraints, formulated at different kinematics levels, as shown in the following paragraphs.

The impact equations.

The impact equations can be written at the time, $ t_i $ of discontinuities:

\[ M(q(t_i))(v^{+}(t_i)- v^{-}(t_i)) = p_i, \]

$ p_i $ is like an impulsion.
This equation will be solved at the time of impact together with an impact law. That is for a Newton impact law

\begin{eqnarray*} M(q(t_i))(v^{+}(t_i)- v^{-}(t_i)) = p_i, \\ \dot y^{+}(t_i) = \nabla_q h(q(t_i)) v^{+}(t_i) \\ \dot y^{-}(t_i) = \nabla_q h(q(t_i)) v^{-}(t_i) \\ p_i = \nabla_q^T h(q(t_i)) P_{N,i}\\ 0\leq \dot y^{+}(t_i)+ e \dot y^{-}(t_i) \perp P_{N,i} \geq 0 \end{eqnarray*}

This problem can be reduced on the local unknowns $ \dot y^{+}(t_i),P_{N,i} $ if the matrix $ M(q(t_i)) $ is assumed to be invertible, leading to the following Linear Complementarity Problem at time $ t_i $ of discontinuities of v:

\begin{eqnarray*} \dot y^{+}(t_i) = \nabla_q h(q(t_i)) (M(q(t_i)))^{-1} \nabla_q^T h(q(t_i)) P_{N,i} + \dot y^{-}(t_i) \\ 0\leq \dot y^{+}(t_i)+ e \dot y^{-}(t_i) \perp P_{N,i} \geq 0 \end{eqnarray*}

Later this system will be identified as "LCP at velocity level".

The smooth Dynamics.

The smooth dynamics which is valid almost everywhere for the Lebesgue measure $ dt $ is governed by the following equation:

\begin{eqnarray*} M(q) \ddot q^+ + F_{int}(t, q, v^+)&=& F_{ext}(t) + f^+ \quad (dt-a.e.) \end{eqnarray*}

where we assume that $ f^+=f^-=f\, (dt-a.e.) $.

The following smooth systems are then to be solved:

\begin{eqnarray*} M(q(t)) \ddot q^{+}(t) + F_{int}(t, q, v^+)= F_{ext}(t) + f^{+}(t)\\ y = h(q(t)) \\ f^+ = \nabla_q h(q(t))^T F^+(t) \\ 0 \leq y \perp F^+(t) \geq 0 \end{eqnarray*}

To solve these systems, at each time, i.e. to known the configuration after each events and to integrate it numerically, it is useful to express the complementarity laws at different kinematics level. We also introduce the pre-defined index sets (about index sets, see Index Sets definition):

$ I_0 $ is the set of all the potential UnitaryRelations (UR).

$ I_1 = \{ ur_\alpha\in I_{0} , y_{\alpha} = 0 \} $ (or if the UR is in $ I_1 $ then contact occurs).

$ I_2 = \{ ur_\alpha\in I_{1} , \dot y_{\alpha} = 0 \} $ (or if the UR is in $ I_2 $, contact remains, no take off).

This results in the new writing of the "Bilateral Smooth Dynamics:

\begin{eqnarray*} M(q) \ddot q^{+} + F_{int}(t, q, v)= F_{ext} + \nabla_q h(q)^T F^+\\ \\ \ddot y^+ = \nabla_q h(q) \ddot q^+ + \dot{ \nabla_q h(q)} v^+ \\ \\ F^{+,\alpha} = 0, \quad \forall \alpha \in I_0-I_2 \\ \\ \ddot y^{+,\alpha} = 0 \quad \forall \alpha \in I_2 \end{eqnarray*}

which can be reduced on variable $ \ddot y^+ $ and $ F^+ $, if M(q) is invertible, when $ \alpha \in I_2 $:

\begin{eqnarray*} \ddot y^{+,\alpha} = \nabla_q h(q) M^{-1}(q)(- F_{int}(t, q, v^+)+ F_{ext}(t) ) + \dot{ \nabla_q h(q)} v^+ +\nabla_q h(q) M^{-1} \nabla_q h(q(t))^T F^{+,\alpha}(t) \\ \\ 0 \leq \ddot y^{+,\alpha} \perp F^{+,\alpha} \geq 0 \end{eqnarray*}

Later this system will be identified as "LCP at acceleration level".

The algorithm

Finally, the event-driven algorithm will be:

knowing the value of $ y, \dot y $ and $ I_1, I_2 $ at the beginning of the time step $ [t_k, t_{k+1}] $:

  1. Integration of the Bilateral Smooth Dynamics up to an event given by the root-finding of the following function :

    \begin{eqnarray*} y^\alpha =0,\quad \forall \alpha \in I_0 - I_2 \\ or \\ F^{+,\alpha} = 0, \quad \forall \alpha \in I_2 \end{eqnarray*}

    This results in the computation of $ y, \dot y $ at this new point and to an update of the index sets $ I_1 $ and $ I_2 $.

  2. if $ I_1 - I_2 \neq \emptyset $ then Impacts occur:
    • Formalize and solve the "LCP at velocity level"
    • Update the index sets $ I_1 $ and $ I_2 $ and check that $ I_1 - I_2 =\emptyset $
      endif
  3. if $ I_2\neq \emptyset $ then
    • Formalize and solve the "LCP at acceleration level"
    • for $ \alpha \in I_2 $ do
      if $ \ddot y_{\alpha} >0, F_{\alpha} = 0 $ remove $ \alpha $ from $ I_2 $ and $ I_1 $
      else if $ \ddot y_{\alpha} =0, F_{\alpha}=0 $ then undetermined case. endif
      endfor
      endif
  4. go to the next time step.

Implementation in Siconos

According to Second order non linear Lagrangian dynamical systems, in Siconos, the Dynamics of Lagrangian systems is written as:

\begin{eqnarray*} M(q) \ddot q + NNL(\dot q, q) + F_{Int}(\dot q , q , t) &=& F_{Ext}(t) + p \\ \end{eqnarray*}

Next,$ NNL $ term will be forget and considered as included in $ F_{Int} $.
And Lagrangian relations are (see Lagrangian Relation):

\begin{eqnarray*} y &=& h(Q) \\ \dot y &=& \nabla_q h(Q)\dot Q \\ P &=& \nabla_q h(Q)^t\lambda \end{eqnarray*}

Q (resp. P) being a collection of all the q (resp. p) of the Dynamical Systems involved in the Interaction.

As we have seen in the previous section, the notion of kinematics level is really important. We introduce this in Siconos thanks to "[i]" notation. More precisely, for each Unitary Relation, we define y[i] as the derivative number i of variable y, according to time. In the same way, we denote $ \lambda[i] $ the variable that is linked with y[i] through a Non-Smooth law (usually a complementarity). Finally to each $ \lambda[i] $ corresponds a p[i].
To make things clearer, let us rewrite the previous defined systems with Siconos notations:

  • "Bilateral Smooth Dynamics:

    \begin{eqnarray*} M(q) \ddot q + F_{int}(t, q, \dot q)= F_{ext} + \nabla_q h(q)^T \lambda[2] \\ \\ y[2] = \nabla_q h(q) \ddot q + \dot{ \nabla_q h(q)} \dot q \\ \\ \lambda[2]_{\alpha} = 0, \quad \forall \alpha \in I_0-I_2 \\ \\ y[2]_{\alpha} = 0 \quad \forall \alpha \in I_2 \end{eqnarray*}

    with roots finding of:

    \begin{eqnarray*} g(x,t) = y[0]_\alpha,\quad \forall \alpha \in I_0 - I_2 \\ or \\ g(x,t) = \lambda[2]_\alpha, \quad \forall \alpha \in I_2 \end{eqnarray*}

  • "LCP at velocity level"

    \begin{eqnarray*} y[1]^{+} = \nabla_q h(q(t_i)) (M(q(t_i)))^{-1} \nabla_q^T h(q(t_i))\lambda[1] + y[1]^{-} \\ 0\leq y[1]^{+} + e y[1]^{-} \perp \lambda[1] \geq 0 \end{eqnarray*}

  • "LCP at acceleration level"

    \begin{eqnarray*} y[2]_{\alpha} = \nabla_q h(q) M^{-1}(q)(- F_{int}(t, q, \dot q)+ F_{ext}(t) ) + \dot{ \nabla_q h(q)} \dot q +\nabla_q h(q) M^{-1} \nabla_q h(q(t))^T \lambda[2]_{\alpha} \\ \\ 0 \leq y[2]_{\alpha}\perp \lambda[2]_{\alpha} \geq 0 \end{eqnarray*}

Then, to build an EventDriven simulation, it is necessary to define two OneStepNSProblems, one at velocity and one at acceleration level. So here is a classical code for simulation construction:

EventDriven* s = new EventDriven(ball);
// -- Time discretisation --
TimeDiscretisation * t = new TimeDiscretisation(timeStep,s);
// -- OneStepIntegrators --
OneStepIntegrator * OSI = new Lsodar(setOfDS,s); 
// -- OneStepNsProblem --
OneStepNSProblem * impact = new LCP(s, "impact",solverName,101, 0.0001,"max",0.6);
OneStepNSProblem * acceleration = new LCP(s, "acceleration",solverName,101, 0.0001,"max",0.6);

Finally, the algorithm described earlier is:

  1. Integration of the Bilateral Smooth Dynamics:
    To integrate these systems thanks to lsodar, we need to define f(x,t) and g(x,t).
    To compute f(x,t), we:
    • formalize and solve a "LCP at acceleration level" to compute $ (y[2],lambda[2]) $
    • collect and rewrite the Dynamics of all the Dynamical Systems as a first order system, including the result of the LCP computation. The function g(x,t) is given by:

      \begin{eqnarray*} g(x,t) &=& y[0], \quad \forall \alpha \in I_0 - I_2 \\ \\ g(x,t) &=& \lambda[2], \quad \forall \alpha \in I_2 \end{eqnarray*}

      Corresponding code:

      s->advanceToEvent()
      // This results in a call to Lsodar->integrate and to schedule of new non-smooth events if necessary
      
      The next steps are done during call to eventsManager->processEvents(), but they will be detailed below.
  2. Compute y[0] and y[1] and update the index sets
    simulation->updateOutput(0, 1);
    simulation->updateIndexSets();
    
  3. if $ I_1 - I_2 \neq \emptyset $, formalize and solve a LCP at velocity level:
    simulation->computeOneStepNSProblem("impact"); 
    
  4. compute p[1], post-impact velocity, y[1] and indexSet[2] simulation->update(1);
  5. if $ I_2 \neq \emptyset $, formalize and solve a LCP at acceleration level, and update index sets with some conditions
    simulation->computeOneStepNSProblem("acceleration");
    simulation->updateIndexSetsWithDoubleCondition();
    
  6. next time step
    simulation->nextStep();
    

Moreau's Time Stepping scheme

Foreword: At the time, Moreau's Time Stepping scheme is only implemented for first order linear systems and for Lagrangian systems.

General Principle

Roughtly speaking, this algorithm consists first in the discretisation of the whole system (dynamics + relations + non-smooth laws) over a time step. Then the system is integrated and that leads to the computation of some "free" solutions, ie without any constraints. Finally a Non-Smooth problem (usually a LCP) is formalized and solved to obtain the complete solution.

Implementation

Related classes: TimeStepping, Moreau, LCP, FrictionContact

The figure below represents the class architecture for TimeStepping simulation.

classTimeStepping.png

We will now describe discretisation process for two differents cases: first order linear systems and then Lagrangian systems, linear and time invariant.

First order linear systems

This section concerns LinearTIDS DynamicalSystems (see Dynamical Systems formulations in Siconos)

\begin{eqnarray*} \dot x &=& Ax + Tu + b + r \\ x(t_0) &=& x_0 \end{eqnarray*}

with linear relations (LinearTIR):

\begin{eqnarray*} y &=& CX + FU + D \lambda + e \\ R &=& B \lambda \end{eqnarray*}

Time Discretisation of the Dynamics

The integration of the ODE over a time step $ [t_i,t_{i+1}]$ of length $ h$ is :

\[ \int_{t_i}^{t_{i+1}}\dot x\,dt = \int_{t_i}^{t_{i+1}} A \cdot x\,dt + \int_{t_i}^{t_{i+1}}(T \cdot u + b) dt + \int_{t_i}^{t_{i+1}}r\,dt \]

The left-hand term is $ x(t_{i+1})-x(t_i)$ .
Right-hand terms are approximated this way :

$ \int_{t_i}^{t_{i+1}} A \cdot x\,dt$ is approximated using a $ \theta$ -method

\[ \int_{t_i}^{t_{i+1}} A \cdot x\,dt \approx h \theta (A \cdot x(t_{i+1})) + h (1-\theta) (A \cdot x(t_{i})) \]

since the second integral comes from independent sources, it can be evaluated with whatever quadrature method, for instance a $ \theta$ -method

\[ \int_{t_i}^{t_{i+1}}(T \cdot u + b) dt \approx h \theta (T \cdot u(t_{i+1}) + b(t_{i+1})) + h (1-\theta) (E \cdot u(t_{i}) + b(t_{i})) \]

the third integral is approximated like in an implicit Euler integration

\[ \int_{t_i}^{t_{i+1}}r\,dt \approx h r(t_{i+1}) \]

By replacing the accurate solution $ x(t_i)$ by the approximated value $ x_i$ , we get :

\[ x_{i+1}-x_i = h \theta (A \cdot x_{i+1}) + h (1-\theta) (A \cdot x_{i}) + h \theta (T \cdot u(t_{i+1}) + b(t_{i+1})) + h (1-\theta) (T \cdot u(t_{i}) + b(t_{i})) + h r_{i+1} \]

Assuming that $ I - h \theta A$ is invertible, matrix $ W$ is defined as $ (I - h \theta A)^{-1}$ . We get then :

\[ x_{i+1} = W(I + h (1-\theta) A) \cdot x_{i} + W (h \theta (T \cdot u(t_{i+1}) + b(t_{i+1})) + h (1-\theta) (T \cdot u(t_{i}) + b(t_{i}))) + h W r_{i+1} \]

An intermediate variable $ x_{free}$ related to the smooth part of the system is defined as :

\[ x_{free} = W(I + h (1-\theta) A) \cdot x_{i} + W (h \theta (T \cdot u(t_{i+1}) + b(t_{i+1})) + h (1-\theta) (T \cdot u(t_{i}) + b(t_{i}))) \]

Thus the calculus of $ x_{i+1}$ becomes :

\[ x_{i+1} = x_{free} + h W r_{i+1} \]

Time discretization of the relations

It comes straightforwardly :

$ r_{i+1} = B \cdot \lambda_{i+1}$

$ y_{i+1} = C \cdot x_{i+1} + D \cdot \lambda_{i+1} + F \cdot u(t_{i+1}) + e $

Time discretization of the non-smooth law

It comes straightforwardly :

\[ 0 \leq y_{i+1} \, \perp \, \lambda_{i+1} \geq 0 \]

Summary of the time discretized equations

These equations are summarized assuming that there is no source term and simplified relations as for the electrical oscillator with full-wave rectifier.

\begin{eqnarray*} W & = & (I - h \theta A)^{-1} \\ x_{free} &= & W(I + h (1-\theta) A) \cdot x_{i} \\ x_{i+1} &= & x_{free} + h W r_{i+1} \\ r_{i+1} &= & B \cdot \lambda_{i+1} \\ y_{i+1} &= & C \cdot x_{i+1} + D \cdot \lambda_{i+1}+ Fu_{i+1} \\ 0 \leq y_{i+1} \, &\perp& \, \lambda_{i+1} \geq 0 \end{eqnarray*}

Lagrangian Linear Systems case

We consider now Lagrangian Linear and Time Invariant systems (LagrangianLinearTIDS, see Second order linear and time-invariant Lagrangian dynamical systems.):

\begin{eqnarray*} M \ddot q + C \dot q + K q = F_{Ext}(t) + p \\ q(t_0) = q0 \\ \dot q(t_0) = velocity0 \end{eqnarray*}

with Lagrangian Linear Relations (LagrangianR, see Lagrangian Linear Relation):

\begin{eqnarray*} y&=& H q + b + D\lambda \\ p&=& H^t \lambda \end{eqnarray*}

Time discretization of the dynamical system

We provide in this section a time discretization method of the Lagrange dynmical system, consistent with the non smooth character of the solution. Let us consider here only the linear time invariant case. The equation may be reformulated equivalently in terms of an integral over a time step $ [t_i,t_{i+1}] $ of length h such that :

\begin{eqnarray*} \int_{[t_i,t_{i+1}]} M \ddot q + C \dot q + K q \,dt = \int_{[t_i,t_{i+1}]} F_{ext}(t)\,dt + \int_{[t_i,t_{i+1}]} r \,d\nu \end{eqnarray*}

Due to the non smooth character of the motion, the first term is integrated by an one order scheme( backward Euler-like) such that :

\begin{eqnarray*} \int_{[t_i,t_{i+1}]} M \ddot q \, dt \approx M (\dot q(t_{i+1})-\dot q(t_{i})) \end{eqnarray*}

For simplicity sake, we note the approximation of q and $ \dot q $:

\begin{eqnarray*} \dot q_{i+1}\approx\dot q(t_{i+1}), \dot q_{i}\approx \dot q(t_{i}) \end{eqnarray*}

For the other terms, a $ \theta $-method is used :

\begin{eqnarray*} \int_{[t_i,t_{i+1}]} C \dot q + K q \,dt &\approx& h\left[\theta (C \dot q_{i+1}+K q_{i+1}) + (1-\theta) (C \dot q_{i}+K q_{i}) \right]\\ \int_{[t_i,t_{i+1}]} F_{ext}(t) \,dt &\approx& h\left[\theta F_{ext}(t_{i+1})+(1-\theta) F_{ext}(t_{i}) \right] \end{eqnarray*}

For the term which contains the reaction force, we state a new variable such that :

\begin{eqnarray*} R_{i+1} = \frac 1 h \int_{[t_i,t_{i+1}]} r \,d\nu \end{eqnarray*}

The displacement is integrated through the velocity with :

\begin{eqnarray*} q_{i+1} = q_{i} + h\left[\theta \dot q_{i+1}+(1-\theta) \dot q_{i} \right]\\ \end{eqnarray*}

Finally, we obtain the time discretized equation of motion:

\begin{eqnarray*} \left[M+h\theta C + h^2 \theta^2 K\right] (\dot q_{i+1} - \dot q_{i}) = - h C \dot q_{i} - h K q_{i} - h^2 \theta K \dot q_{i} + h\left[\theta F_{ext}(t_{i+1})+(1-\theta) F_{ext}(t_{i}) \right] +h R_{i+1}, \end{eqnarray*}

which can be written :

\begin{eqnarray*} \dot q_{i+1} = \dot q_{free} + h W R_{i+1} \end{eqnarray*}

where

\begin{eqnarray*} W &=& \left[M+h\theta C + h^2 \theta^2 K\right]^{-1}\\ \dot q_{free} &=& \dot q_{i}+ W \left[ - h C \dot q_{i} - h K q_{i} - h^2 \theta K \dot q_{i} + h\left[\theta F_{ext}(t_{i+1})+(1-\theta) F_{ext}(t_{i}) \right] \right] \end{eqnarray*}

The free velocity $ \dot q_{free} $ correponds to the velocity of the system without any constraints.

Time discretization of the relations

The Time discretization of the relations is fully implicit and may be written as :

\begin{eqnarray*} y_{i+1} &=& H^{T} q_{i+1} + b\\ \dot y_{i+1} &=& H^{T}\dot q_{i+1} \\ R_{i+1} &=& H \lambda_{i+1} \end{eqnarray*}

Time discretization of the Non Smooth laws

A natural way of discretizing the unilateral constraint leads to the following implicit discretization :

\begin{eqnarray*} 0 \leq y_{i+1} \perp \lambda_{i+1} \geq 0 \end{eqnarray*}

In the Moreau's time--stepping, we use a reformulation of the unilateral constraints in terms of velocity:

\begin{eqnarray*} If y(t) =0, \ then \ 0 \leq \dot y \perp \lambda \geq 0 \end{eqnarray*}

which leads to the following discretisation :

\begin{eqnarray*} If \ y^{p} \leq 0, \ then \ 0 \leq \dot y_{i+1} \perp \lambda_{i+1} \geq 0 \end{eqnarray*}

where $ y^{p} $ is a prediction of the position at time $ t_{i+1} $, for instance, $ y^{p} = y_{i} + \frac{h}{2} \dot y_i $.

If we want to introduce now the Newton impact law, we consider an equivalent velocity defined by

\begin{eqnarray*} \dot y^{e}_{i+1} = \dot y_{i+1} + e \dot y_{i} \end{eqnarray*}

and we apply the constraints directly on this velocity :

\begin{eqnarray*} If \ y^{p} \leq 0, \ then \ 0 \leq \dot y^{e}_{i+1} \perp \lambda_{i+1} \geq 0 \end{eqnarray*}

Summary of the time discretized equations

\begin{eqnarray*} \dot q_{i+1} &=& \dot q_{free} + h W R_{i+1} \\ q_{i+1} &=& q_{i} + h\left[\theta \dot q_{i+1}+(1-\theta) \dot q_{i} \right] \\ \dot y_{i+1} &=& H^{T}\dot q_{i+1} \\ R_{i+1} &=& H \lambda_{i+1}\\ y^{p} &=& y_{i} + \frac{h}{2} \dot y_i\\ If &y^{p}& \leq 0, \ then \ 0 \leq \dot y^{e}_{i+1} \perp \lambda_{i+1} \geq 0 \end{eqnarray*}

This set of equations can be reduced to a "condensed" system in terms of $ \dot y^{e}_{i+1} $ and $ {\lambda_{i+1}} $ :

\begin{eqnarray*} \dot y^{e}_{i+1} &=& H^{T} \dot q_{free} + h H^{T} W H \lambda_{i+1} + e \dot y_{i}\\ y^{p} &=& y_{i} + \frac{h}{2} \dot y_i\\ If &y^{p}& \leq 0, \ then \ 0 \leq \dot y^{e}_{i+1} \perp \lambda_{i+1} \geq 0 \end{eqnarray*}

The Simulation process

As for Event-Driven, we introduce level index sets, with level = 0 for first order systems and level=1 for second order systems (this is related to the relative degrees but we won't get into details about that here).

$ I_0 $ is the set of all the potential UnitaryRelations (UR).
For second order systems:
$ I_1 = \{ ur_\alpha\in I_{0} , y^p_{\alpha} = 0 \} $.
Thus, the LCP is built only for unitary relations that belongs to $ I_level $, level=0 for first order and level=1 for second order systems.

Then, the steps of a Moreau's Time-Stepping simulation will be:

Knowing all values at the beginning of the time step $ [t_i,t_{i+1}] $,

  1. compute the free solutions
  2. for $ ur \in I_level $ formalize and solve a LCP
  3. update the state (according to the possibly LCP results)
  4. go to next time step

TimeStepping * s = new TimeStepping(myModel);
TimeDiscretisation * t = new TimeDiscretisation(timeStep,s);

s->initialize();

int k = t->getK(); // Current step 
int N = t->getNSteps(); // Number of time steps

// --- Time loop ---
while(k < N)// for each time step ...
{
// transfer of state i+1 into state i and time incrementation
s->nextStep();
// get current time step
k = t->getK();
// compute xFree, or qFree,vFree
s->computeFreeStep();
// Update the index sets (ie compute prediction yp for Lagrangian Systems)
s->updateIndexSets();
// Formalize and solve a LCP
computeOneStepNSProblem("timeStepping");
// Update state, using last computed values
s->update(level); // 
}

Note that all time-independent operators are computed during simulation initialisation.