.. _knowledge_base_timeStepping:

:ref:`timeStepping <timeSteppingParameters>`
=============================================

:code:`timeStepSize`
---------------------

:code:`timeStepSize` prescribes the size of each physical time step.
For steady case, there is only one physical time step with :code:`timeStepSize` = :math:`\infty`.

For unsteady cases, there are two typical ways for determining the :code:`timeStepSize`:

- Based on an expected :ref:`vortex shedding frequency <vortex_shedding_freq>` 
- Based on the desired :ref:`angle of rotation per step <rot_angle_per_step>`

.. _vortex_shedding_freq:

Vortex Shedding Frequency
^^^^^^^^^^^^^^^^^^^^^^^^^^

The vortex shedding frequency can be estimated by:

.. math::

    f = \frac{St \cdot U_\infty}{D }


where :math:`U_\infty` is the freestream speed,
:math:`D` is the characteristic length, for example the mean aerodynamic chord,
and :math:`St` is the `Strouhal Number <https://en.wikipedia.org/wiki/Strouhal_number>`_. An approximation of :math:`St = 0.2` is typically appropriate for most CFD applications.

Typically, the physical time step size :math:`\Delta t` is set as:

.. math::

    \Delta t = \frac{1}{100} \cdot \frac{1}{f}

Note that the nondimensional :code:`timeStepSize` in Flow360.json should be:

.. math::

    \text{timeStepSize} = \Delta t \cdot \frac{C_\infty}{L_\text{gridUnit}}

Here is an :ref:`example <nondim_timeStepSize>` showing how to convert the physical time step size to nondimensional :code:`timeStepSize`.

.. _rot_angle_per_step:

Angle of Rotation per Step 
^^^^^^^^^^^^^^^^^^^^^^^^^^^

If there is a transient BET Line or a sliding interface modeled, then the :code:`timeStepSize` can be calculated from the desired angle of rotation in each physical step.

.. table:: Recommended angle of rotation per step for different scenarios.
   :widths: 50 40

   +------------------------------------------------------+---------------------------------+
   | Scenario                                             | Angle per :code:`timeStepSize`  |
   +======================================================+=================================+
   | Transient BETDisks (i.e., BET Line)                  | 6 deg/step                      |
   +------------------------------------------------------+---------------------------------+
   | | Rotor in sliding interface, phase-I:               | 6 deg/step                      |
   | | Initializing the flow-field with 1st-order solver  |                                 |
   +------------------------------------------------------+---------------------------------+
   | | Rotor in sliding interface, phase-II:              | 6 deg/step                      |
   | | Initializing the flow-field with 2nd-order solver  |                                 |
   +------------------------------------------------------+---------------------------------+
   | | Rotor in sliding interface, phase-III:             | 3 deg/step                      |
   | | Collecting the data with 2nd-order solver          |                                 |
   +------------------------------------------------------+---------------------------------+
   | Strong blade-vortex interaction (hover/descent)      | 1-2 deg/step                    |
   +------------------------------------------------------+---------------------------------+
   | Generating high-quality time-resolved animation      | 0.5-1 deg/step                  |
   +------------------------------------------------------+---------------------------------+

For more information about 1st versus 2nd order solution, see :ref:`orderOfAccuracy <knowledge_base_orderOfAccuracy>`. 
Once the angle per step is determined, then the :code:`timeStepSize` can be calculated:

.. math::

   \text{timeStepSize} = \frac{\theta}{\Delta t} \cdot \frac{\pi}{180} \cdot \frac{1}{\text{omegaRadians}}

where :math:`\theta` is the angle of rotation in degrees. Note that the :code:`omegaRadians` here is the nondimensional rotation speed,
which can be :ref:`easily converted from RPM <non_dim_omega>`.

.. _knowledge_base_maxPseudoSteps:

:code:`maxPseudoSteps`
-----------------------

- For steady cases, :code:`maxPseudoSteps` is typically 5K~10K. If the nonlinear residuals and/or the forces and moments are still changing, the user can always fork the completed case and let it run more pseudo steps.
- For unsteady time-accurate cases, :code:`maxPseudoSteps` is typically slightly larger than :code:`rampSteps` so the :code:`final` CFL can be achieved. As shown in the examples below, when :code:`rampSteps` = 10 then :code:`maxPseudoSteps` should be set to 12. If :code:`rampSteps` = 33 then :code:`maxPseudoSteps` should be set to 35.


Example :code:`timeStepping` for the 1st-order unsteady cases
  .. code-block:: javascript

    "maxPseudoSteps" : 12,
    "CFL" : {
        "initial" : 1,
        "final" : 1000,
        "rampSteps" : 10
    }

Example :code:`timeStepping` for the 2nd-order unsteady cases
  .. code-block:: javascript

    "maxPseudoSteps" : 35,
    "CFL" : {
        "initial" : 1,
        "final" : 1e+7,
        "rampSteps" : 33
    }

For more information about 1st versus 2nd order solution, see :ref:`orderOfAccuracy <knowledge_base_orderOfAccuracy>`.
The CFL number will be discussed in the following subsection.

.. _knowledge_base_CFL:

:code:`CFL`
------------

The CFL number determines the pseudo step size in each physical step.
The table below shows how to ramp up the CFL number for steady and unsteady cases.

.. list-table:: Recommended CFL ramp up for steady and unsteady cases.
   :widths: 42 5 22 22 5
   :header-rows: 1

   * - Example
     - Type
     - :code:`initial`
     - :code:`final`
     - :code:`rampSteps`
   * - Simple wing or fuselage, mostly attached linear flow
     - Steady
     - 5 
     - 200
     - 100
   * - Full aircraft with nonlinear flow, some separation, simple actuator/BET disks

     - Steady
     - 1
     - 100~150
     - 1K~2K
   * - Full aircraft near onset of stall, large-scale separation, challenging actuator/BET disks

     - Steady
     - 0.1~1
     - 10~50
     - 3K~5K
   * - Forked/child case
     - Steady
     - parent :code:`final` CFL
     - parent :code:`final` CFL
     - 1
   * - Rotor in sliding interface, 1st-order solver
     - Unsteady
     - 1
     - 1000
     - ~10
   * - Rotor in sliding interface, 2nd-order solver
     - Unsteady
     - 1
     - 1e+5~1e+7
     - 30~50

#. For steady cases, :code:`initial` CFL < 1, :code:`final` CFL < 100, :code:`rampSteps` > 3K are considered as conservative. Such conservative values are only recommended for challenging cases.
#. For unsteady cases, it is typically recommended to let the nonlinear residuals drop 2~3 orders of magnitude in each physical step. That is why higher :code:`final` CFL and more aggressive CFL ramping values are suggested.

#. For unsteady cases running 2nd-order solver, :code:`final` CFL < 1e+5, :code:`rampSteps` > 50 are considered as conservative. Decreasing :code:`rampSteps` and :code:`maxPseudoSteps` within each physical step will decrease the overall cost and runtime. For more information about 1st versus 2nd order solutions, see :ref:`orderOfAccuracy <knowledge_base_orderOfAccuracy>`.

..
  Once we have the debug divergence subsection done, add a link to that section
  I think some hand drawn schematic illustrating the residual patterns could be very helpful