.. _inputdeck:

Input Deck for Solver Parameters
================================

This section details the solver parameters in the structured input deck (``.par`` file), which is finally read by the main solver.
In GUI mode, it is also the only purpose for the preprocessor to write out, and serves as the mid-file format for GUI resolve.
It includes the path pointing to data, indicates the path to save results, and determines the modes and numerical methods for the solver.
In other words, if the data is placed properly, this ``.par`` is the only input file by the solver.


Input and Range Control
---------------------------------

+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| Key               | Description                                          | Value(s)                | Explaination                                                                                            |
+===================+======================================================+=========================+=========================================================================================================+
| ``vtk_folder``    | Path to folder containing VTK input data             | ``<string>``            |                                                                                                         |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``output_dir``    | Path to directory for saving results                 | ``<string>``            |                                                                                                         |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``auto_wall``     | Flag for automatic wall detection                    | ``0``                   | Manually indicate computation bounds.                                                                   |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | (``1``)                 | Auto detect bounds from input mesh.                                                                     |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``wall_xrange``   | X-direction wall bounds [xmin, xmax]                 | ``[<float>, <float>]``  | Dimensionalized coordinates bounds.                                                                     |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``wall_yrange``   | Y-direction wall bounds [ymin, ymax]                 | ``[<float>, <float>]``  |                                                                                                         |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``wall_zrange``   | Z-direction wall bounds [zmin, zmax]                 | ``[<float>, <float>]``  |                                                                                                         |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``x``             | Number of Lagrangian seed points in X direction      | ``<int>``               |                                                                                                         |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``y``             | Number of Lagrangian seed points in Y direction      | ``<int>``               |                                                                                                         |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``z``             | Number of Lagrangian seed points in Z direction      | ``<int>``               |                                                                                                         |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``T_range``       | Time range [``T_start``, ``T_end``] in frames        | ``[<float>, <float>]``  | ``T_end`` no larger than ``N_frames``.                                                                  |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``dt``            | Time step for particle advection in frames           | ``<float>``             |                                                                                                         |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``physical_dt``   | Physical time step between two input frames          | ``<float>``             | Perform physical advection.                                                                             |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+

Numerical Methods
---------------------------------


+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| Key               | Description                                          | Value(s)                | Explaination                                                                                            |
+===================+======================================================+=========================+=========================================================================================================+
| ``if_backward``   | Backward integration flag                            | ``0``                   | Only compute forward advection (repelling LCS structures).                                              |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | (``1``)                 | Compute in both side (both repelling and attracting structures).                                        |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``wall_treatment``| Wall-treatment strategy                              | (``clamp``)             | Out-of-bounds points take nearest velocity. Applicable to subdomains from larger ones.                  |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``dirichlet``           | Simple and fast BC treatment, zeroing the boundary values. Introduces artifical shear.                  |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``reflect``             | Reflect the particles back to the computational domain. Likely a non-shear wall BC.                     |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``periodic``            | Wrap around to the opposite side. Applicable to fully-developed subdomains and periodic flows.          |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``advc_method``   | Lagrangian advection scheme                          | (``Euler``)             | Simple and fast Euler stepping with :math:`O(h^1)` error.                                               |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``RK2``                 | Runge–Kutta 2 with :math:`O(h^2)` error.                                                                |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``RK4``                 | Runge–Kutta 4 with :math:`O(h^4)` error.                                                                |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``RK6``                 | Runge–Kutta 6 with :math:`O(h^6)` error.                                                                |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``interp_method`` | Interpolation method for velocity                    | ``trilinear``           | Simple and fast triliear interpolation method. Very fast on GPUs.                                       |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | (``tricubic``)          | Catmull–Rom 3D convolution kernel for tricubic interpolation.                                           |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``hermite``             |                                                                                                         |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``WENO``                | Weighted Essentially Non-Oscillatory (WENO) scheme with shockwave capture capability.                   |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``tricubicFL``          | ``I.P.`` The high-performance 3D tricubic interpolation method by [Lekien2005]_.                        |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``grad_order``    | Method of gradient discretization                    | (``2``)                 | 2nd-order central difference.                                                                           |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``4``                   | ``I.P.`` 4th-order central difference.                                                                  |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``6``                   | ``I.P.`` 6th-order central difference.                                                                  |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``100``                 | ``I.P.`` Global Fast Fourier Transform (FFT) with finite order. Compute extremely intensive!            |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``eigen_method``  | Max eigenvalue of C-G tensor                         | (``eigmax_sym3``)       | Closed-form cubic eigenvalue solver for symmetric 3×3 matrices (noniterative solver).                   |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``jacobi``              | ``I.P.`` Jacobi eigenvalue algorithm (iterative).                                                       |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+


Dynamic LCS Window
---------------------------------

+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| Key               | Description                                          | Value(s)                | Explaination                                                                                            |
+===================+======================================================+=========================+=========================================================================================================+
| ``dyn_mode``      | Dynamic LCS mode selector                            | (``0``)                 | Treat this input as a steady whole, generating still results. See :ref:`steady`.                        |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
|                   |                                                      | ``1``                   | Dynamic LCS computation based on sliding window method. See :ref:`unsteady`.                            |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``win_size``      | Window size for dynamic LCS                          | ``<float>``             | The window size in frames for each batch of computation. Available under ``dyn_mode=1``.                |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| ``win_step``      | Window step for dynamic LCS                          | ``<float>``             | Stepping in frames. Better smaller than ``win_size/2`` for capturing dynamic patterns.                  |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+

Utilizations
-------------------

+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
| Key               | Description                                          | Value(s)                | Explaination                                                                                            |
+===================+======================================================+=========================+=========================================================================================================+
| ``if_visual``     | Glace visualization enabler                          | ``0`` / ``1``           | Take a pop-up glance on FTLE coutours after computation for check with a rudimentary appearance.        |
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+