====== Dynamic implicit/explicit integration scheme ======

===== Description =====

Can shift from implicit scheme to explicit scheme and reciprocally.

===== Data set =====

==== Old Metafor Version <= 2422 ====

See dynamic [[doc:user:integration:scheme:dynimpl|implicit]] and [[doc:user:integration:scheme:dynexpl|explicit]] for a description of schemes and the definition of density and initial velocities.

In addition, parameters must be defined to handle the shift ([[doc:user:integration:general:parameters]]): 

  * ''MDE_SHIM'' : implicit scheme (= ''MDE_NDYN'') 
  * ''MDE_SHEX'' : explicit scheme 

Shifting can be done automatically or manually or both. Another application of this algorithm is to stabilize explicit steps. 

==== New Metafor Version > 2422 ====

<code>
ti = IeTimeIntegration(metafor)
ti.setExplicitTimeIntegration(tiExp)
ti.setImplicitTimeIntegration(tiImp)
ti.setCurrentDynamicTimeIntegration(tiImp)
</code>

where tiExp and tiImp are the references towards the explicit and implicit time integration scheme respectively.

===== Automatic Shift (method 1 or 2) =====

By default, the algorithm chooses the method based on an integration error, the time step and the machine time. The definition ''MDE_ICPU = 1'' must be done (shift based on CPU time, otherwise dummy shift for the battery). The shift is done only if estimated and critical time steps are equal (to a safety factor). When shifting from an explicit alpha-generalized method, explicit time steps can be computed with a bifurcation radius equal to zero to increase numerical dissipation. The option is activated for ''method=1'' but not for ''method=2'' (see [[#Implicit/explicit shift management]]).

===== Manual Shift (method 3 or 4) =====

The user can impose shifts (see command ''.sie''). When shifting from an explicit alpha-generalized method, explicit time steps can be computed with a bifurcation radius equal to zero to increase numerical dissipation. The option is activated for ''method=3'' but not for ''method=4'' (see [[#Implicit/explicit shift management]]).

===== Balancing=====

When shifting from explicit to implicit, the first implicit time step is computed based on an integration error (majored by a value equal to the maximal change of step times the explicit step) in automatic shift and is equal to this value (maximal change of step times the explicit step) in manual shift. In addition, the user can impose a number of implicit balancing time steps when shifting from explicit to implicit. An implicit balancing step is computed based on an explicit number of steps corresponding to the maximal change, justifying why this is an integer.


===== Balancing all explicit time steps (method 5) =====

All the computation is done with explicit time steps (''method5''). All explicit maximal change of explicit steps are balanced by an implicit step.

===== Implicit/explicit shift management =====

It is **mandatory** to instanciate the IeShifManager and then the parameters can adjusted if required :
    iesm = IeShiftManager(metafor)
    iems.setIeShiftMethod(meth)
    iesm.setNbOfBalanceSteps(nbbs)
    iesm.setMaxStepIncrease(msin)
    iesm.setAutomaticShiftSecurity(secu)
    iesm.setCpuDependency(cpuDep)
^ Parameter ^ default ^ description ^
|''meth''| | = ''IESM_NOSHIFTMETHOD'' : no shift (default)|
|        | | = ''IESM_AUTOMATICSHIFTMETHODWITHDISS'' shift done automatically from integration error and CPU times (requires ''MDE_ICPU=1''); when shifting to an implicit method, explicit time steps are computed with numerical dissipation|
|        | | = ''IESM_AUTOMATICSHIFTMETHOD'' : shift done automatically from integration error and CPU times (requires ''MDE_ICPU=1''); when shifting to an implicit method, there is no explicit time steps computed with numerical dissipation|
|        | | = ''IESM_MANUALSHIFTMETHODWITHDISS'' : shift times are set with the command ''.sie'' (see below); when shifting to an implicit method, explicit time steps are computed with numerical dissipation|
|        | | = ''IESM_MANUALSHIFTMETHOD'' : shift times are set with the command ''.sie'' (see below); when shifting to an implicit method, there is no explicit time steps computed with numerical dissipation|
|        | | = ''IESM_BALANCEDEXPLICITMETHOD'' : every msin explicit steps, balanced is done with an implicit step to stabilize nonlinear computing|
|''nbbs'' |  0  | when shifting to implicit, is equal to the number of balancing steps |
|''msin'' |  6  |maximal change of the time step; this value is the ratio of the implicit step to the explicit step for a change to implicit or a balancing, so this is an integer|
|''secu'' |  1.5  | safety coefficient for automatic shift|
|''cpuDep''| ''False'' | specify if the automatic criterion for shifting from one time integration to another depends on the User CPU time. (Metafor Version > 2422)|. 
For manual shift, the user can set times at which method is changed. This is done with the commands:

    metafor.getIeShiftManager().pushTimeOfShiftingToExplicit(time)
    metafor.getIeShiftManager().pushTimeOfShiftingToImplicit(time)

where

| ''time'' | time at which the shift takes place|