.. sec:InputsTimeStepping:

Time stepping
=============

There are several ways that the inputs are used to determine the time step of particle-only,
fluid-only, and coupled fluid-particle systems.

.. rubric:: Fluid-only simulations

In fluid-only simulations, setting ``mfix.fixed_dt`` causes the fluid to advance with a
fixed (constant) time step. If ``mfix.fixed_dt`` is not defined, then an appropriate time
step is computed based on the advective CFL condition.

.. caution::

  **The adaptive time step based on the advective CFL condition is always computed
  and is stronly recommended for most cases.**

  * For a fixed time step simiulation, if the computed step size is smaller than
    ``mfix.fixed_dt`` for a fixed, the simulation aborts with the message:

    .. highlight:: c++

    ::

        amrex::Abort::0::"Fixed dt is too large for fluid solve !!!


  * For simulations using the adaptive time step:

    * If the computed time step is larger than ``mfix.dt_max``,  then the
      time step is set to ``dt_max``

    * If the computed time step is smaller than ``mfix.dt_min``, then the
      simulation aborts with the message:

      .. highlight:: c++

      ::

          amrex::Abort::0::"Current dt is smaller than dt_min !!!

.. rubric:: Particle-only DEM simulations

In particle-only DEM simulations, the time step used to advance particles, ``dtsolid``,
is determined by computing the collision time ``tcoll`` from particle properties, then dividing
the result by the number of steps per collision, ``tcoll_ratio``:

.. highlight:: c++

::

    dtsolid = tcoll / tcoll_ratio;

.. note::

  ``mfix.fixed_dt`` must be defined for particle-only DEM simulations, however it is only
  used to determine the frequency of outputs and has no effect on the particle advance. If
  a positive value is not specified for ``mfix.fixed_dt``, then the code aborts with the
  following message:

  .. highlight:: c++

  ::

      amrex::abort::0::if running particle-only must specify fixed_dt in the inputs file !!!


.. rubric:: Coupled fluid-DEM simulations

In a coupled fluid-DEM simulation, the fluid time step, ``dt``, and the particle time step,
``dtsolid``, are computed the same as in fluid-only and DEM-only simulations, respectively.
If ``dt < dtsolid``, then the particle sub-time step, ``subdt``, is set to the fluid time
step and one particle advance is taken. However, if ``dt > dtsolid`` (which is usually the
case), then the number of sub-steps needed for DEM particles to advance the same total time
as the fluid, ``nsubsteps``, is computed by dividing ``dt`` by ``dtsolid`` and the particle
sub-time step is computed by dividing ``dt`` by ``nsubsteps``.

.. highlight:: c++

::

    int nsubsteps = 1;
    amrex::Real subdt = dt;

    if (dt > dtsolid) {
     nsubsteps = amrex::Math::ceil(dt / dtsolid);
     subdt = dt / nsubsteps;
    }


The following inputs are defined using the ``mfix`` prefix.

+----------------------+-----------------------------------------------------------------------+-------------+--------------+
| Key                  | Description                                                           |   Type      | Default      |
+======================+=======================================================================+=============+==============+
| max_step             | Maximum number of time steps to take                                  |    Int      |  -1          |
+----------------------+-----------------------------------------------------------------------+-------------+--------------+
| stop_time            | Maximum time to reach (s)                                             |    Real     | -1.0         |
+----------------------+-----------------------------------------------------------------------+-------------+--------------+
| fixed_dt             | Flag to use a fixed time step                                         |    Int      |   0          |
+----------------------+-----------------------------------------------------------------------+-------------+--------------+
| cfl                  | CFL constraint (dt < cfl * dx / u)                                    |    Real     |  See note    |
|                      |                                                                       |             |              |
|                      | * Defaults to 0.5 if ``mfix.advection_type = MOL``                    |             |              |
|                      | * Defaults to 0.9 if ``mfix.advection_type = Godunov``                |             |              |
|                      | * ignored if ``mfix.fixed_dt = 1``                                    |             |              |
+----------------------+-----------------------------------------------------------------------+-------------+--------------+
| dt_min               | Abort if ``dt`` gets smaller than this value                          |    Real     |  1.e-6       |
+----------------------+-----------------------------------------------------------------------+-------------+--------------+
| dt_max               | Maximum value of ``dt`` if ``fixed_dt`` is not 1                      |    Real     |  1.e14       |
+----------------------+-----------------------------------------------------------------------+-------------+--------------+
| tcoll_ratio          | DEM time step equals the min collision time divided by this value     |    Real     |   50.0       |
+----------------------+-----------------------------------------------------------------------+-------------+--------------+
| walltime_limit       | Runtime limit specified with format HH:MM:SS. When the runtime has    |    String   |   ""         |
|                      | almost reached the limit (approaching is computed by considering the  |             |              |
|                      | average runtime needed for each step) then the simulation ends and    |             |              |
|                      | a clean exit is performed                                             |             |              |
+----------------------+-----------------------------------------------------------------------+-------------+--------------+
| clean_exit           | This input represents the name of a file that, if found in the run    |    String   |   ""         |
|                      | folder, makes the code stop and perform a clean exit                  |             |              |
+----------------------+-----------------------------------------------------------------------+-------------+--------------+

In the case of unsteady flow, the simulation will stop when either the number of steps
reaches ``max_step`` or time reaches ``stop_time``.


The following inputs are defined using the ``mfix`` prefix and are only relevant if running a steady state simulation.

+-----------------------+-----------------------------------------------------------------------+-------------+------------+
| Key                   | Description                                                           |   Type      | Default    |
+=======================+=======================================================================+=============+============+
| steady_state          | Are we running a steady-state calculation?                            |   Int       | 0          |
+-----------------------+-----------------------------------------------------------------------+-------------+------------+
| steady_state_tol      | Tolerance for checking if we have reached steady state                |   Real      | None       |
|                       |                                                                       |             |            |
|                       | (Must be set if steady_state = 1)                                     |             |            |
+-----------------------+-----------------------------------------------------------------------+-------------+------------+
| steady_state_maxiter  | Maximum number of allowed iterations to converge to steady state      |   Int       | 100000000  |
+-----------------------+-----------------------------------------------------------------------+-------------+------------+



