====== Managing Time Steps ======
===== Archiving manager =====
==== General Points ====
[[doc:user:general:glossaire#Fac|Archiving]] is done with ''metafor.getTimeStepManager()''. An initial time and time step is set using ''setInitialTime()'', then a series of subsequent steps are set using ''setNextTime()''. Then number of archives between two time steps is given as argument to ''setNextTime()''.

    tsm = metafor.getTimeStepManager()
    tsm.setInitialTime(t0, muli)
    tsm.setNextTime(t1, npas, mulm)
    ...

where

| ''t0'' | initial time| 
| ''t1'' | next time| 
| ''muli'' | initial time step| 
| ''mulm'' | maximal time step between ''t0'' and ''t1''| 
| ''npas'' | number of archives between ''t0'' and ''t1''| 

==== Use of Metafac ====

=== Introduction ===

This section describes how to deal with Metafor output, which are called [[doc:user:general:glossaire#Fac]] files, and created by the object called ''Metafac'' (''.bfac'', ''.tfac'').

Each time step is saved in a different file. This way, useless steps can be easily deleted, and a ''restart'' can be done. 

By default, archiving is done in binary (''.bfac'' - in opposition to ''.tfac'', text version or ASCII). If  [[http://www.zlib.net/|zlib]] is available, files are compressed immediately (into ''.bfac.gz'').

Note that a binary file is usually not portable between various OS.

By default, archiving files are sent to a folder called ''workspace/test_name/'' and are called ''step_*.bfac.gz''. 

=== Useful scripts===

Some scripts, found in ''oo_meta/toolbox/utilities.py'', were written to easily see the result of a simulation, to convert into a different format, ... These files can be modified by the user to suit a particular application.

=== View a given step with VizWin ===

To load the 10th time step, 

    loadFac('rep1.rep2.mytest', 10)

(assuming that the file ''mytest.py'' is located in ''/rep1/rep2/''). If no time step is specified, Metafor loads the one having the highest number.

To view it : 

    vizu('rep1.rep2.mytest')

=== Movie ===


__Automatic conversion from bfac/tfac to bmp:__

    * Type ''makeAnimation('rep1.rep2.mytest')''
    * A ''VizWin'' window is opened with the first time step and the user is put on hold.
    * Activate options (scales, etc)
    * Check that the ''VizWin'' window is not hidden by an object on the screen (otherwise it might appear in the screenshots).
    * Type ENTER once ready

__Automatic creation of the movie:__

    * Run a program to create movies from the files (for example [[http://www.helesic.cz/en/avimaker.php|AVImaker]]).



===== Time step manager =====

The time step is monitored using the commands:

    tsm = metafor.getTimeStepManager()
    tsm.setTimeStepComputationMethod(meth)
    tsm.setTolOnFac(tolOnFac)
    tsm.setIntegrationErrorTolerance(prec)
    tsm.setExplicitTimeStepSecurity(secu)
    tsm.setNbOfStepsForCriticalTimeStepUpdate(nrit)
    tsm.setMaxNbOfItInAdaptOfTimeStep(nbIter) (option: used in implicit or quasi-static)
    tsm.setMinimumTimeStep(minTimeStep)
    
^ Parameter ^ Default value ^ Description ^
| ''meth'' |   | = ''TSM_NBOFITERATIONSMETHOD'' : in implicit, the current time step depends on the number of iterations in the previous time step, when in explicit it only depends on the critical one and the parameter ''secu''|
|   |    |= ''TSM_INTEGRATIONERRORMETHOD'' : the current time step is computed based on an integration error (and based on the critical one and the parameter ''secu'' in explicit) |
| ''prec'' |  1.E-4  |accuracy on the integration error |
| ''secu'' |  2.0/3.0  | safety coefficient which multiplies the critical time step in explicit |
| ''nrit'' |  1  | number of time steps before updating the critical time step |
| ''nbIter'' |  5  | Minimal number of iterations in the algorithm in charge of reducing the time step. If the required number is greater than ''nbIter'', the subsequent time step will be lower than the current one. Otherwise, it will be equal or greater. |
| ''minTimeStep'' |  1.0E-10  | minimum time step below which metafor stops running. |
| ''tolOnFac'' | 0.1 | tolerance on time step for the discrete times corresponding to archiving (FAC). |
==== Quasi-static and dynamic implicit schemes =====

Two possibilities are used to compute the time step:
  * A method based on the number of iterations before convergence. If lower than 3, the time step is increased. If greater than 4, it is decreased. This method does not provide any guaranty on accuracy. 
  * A method based on an integration error. It computes an integration error based on the difference of the norm of the acceleration (dynamic case) or speed (quasi-static case) to adjust the time step, depending on the accuracy required.


==== Dynamic explicit schemes =====

Since these schemes are conditionally stable, the time step $\Delta t$ is given by :\\
$ \Delta t = \gamma_s \Delta t_{crit} $

Where $\Delta t_{crit}$ depends on the maximal eigenfrequency of the system (obtained using the method called "power iteration", and updated regularly) and $\gamma_s$, a safety coefficient which can be computed two ways:
  * Constant safety, coefficient, no guaranty on the accuracy.
  * Safety coefficient based on an integration error. It computes an integration error based on the difference of the norm of the acceleration. A maximal value is set by the user. Practically, the safety coefficient will only be lower than this user parameter for highly dynamic situations, such as impact.

==== New Interface For Time Step Computation Method ====

<note important>
The commands from the new interface are discussed in the following page
Cf. [[commit:2015:11_18]] 
</note>