Skip to content

Commit 2660f1b

Browse files
hweifluidshweifluids
committed
add details of vtk
1 parent 53244e3 commit 2660f1b

3 files changed

Lines changed: 301 additions & 7 deletions

File tree

‎source/4_input.rst‎

Lines changed: 152 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,155 @@
33
Input Data Files
44
=====================
55

6-
This page describes the input file
6+
This page describes what constitutes a qualified velocity-field input for the current native
7+
solver. In both GUI and command-line workflows, the solver reads a folder of time-ordered
8+
legacy ``.vtk`` files given by ``vtk_folder`` in :ref:`inputdeck`.
9+
Each file represents one time frame of the same flow field, and the whole folder is interpreted as
10+
one temporal sequence.
11+
12+
13+
Supported File Type
14+
-------------------
15+
16+
The current native solver scans only files whose extension is ``.vtk``.
17+
These files are loaded through VTK's legacy-data reader. As a consequence:
18+
19+
- legacy VTK ``.vtk`` is the supported input container for the solver;
20+
- ASCII and binary legacy files are both acceptable as long as VTK can parse them;
21+
- XML VTK files such as ``.vts`` or ``.vti`` are not used as solver input in the current mainline,
22+
even though they may be viewable elsewhere.
23+
24+
25+
Folder-Based Time Sequence
26+
--------------------------
27+
28+
The solver treats the input as a folder-level sequence rather than a single file:
29+
30+
- only regular ``.vtk`` files in ``vtk_folder`` are considered;
31+
- subfolders are not scanned recursively;
32+
- files are sorted by the last integer appearing in the filename;
33+
- this sorted order defines the frame index used by ``T_range``.
34+
35+
For this reason, filenames such as
36+
``frame_00000.vtk``, ``frame_00001.vtk``, ``frame_00002.vtk`` are strongly recommended.
37+
Missing frame numbers are allowed, but the ordering still follows the extracted integer tags.
38+
If a filename contains more than one integer group, the last one is the one used for sorting.
39+
40+
41+
Structured Spatial Layout
42+
-------------------------
43+
44+
The native solver assumes that every frame lies on one structured tensor-product lattice in
45+
:math:`x`, :math:`y`, and :math:`z`.
46+
In practice, the most reliable qualified inputs are legacy VTK files whose dataset is either
47+
``RECTILINEAR_GRID`` or ``STRUCTURED_GRID``.
48+
49+
For a sequence to be qualified:
50+
51+
- all frames must describe the same spatial grid;
52+
- the point count must remain identical across all frames;
53+
- the coordinate axes must be consistent from frame to frame;
54+
- each point must be mappable to one unique lattice index :math:`(i,j,k)`.
55+
56+
For ``RECTILINEAR_GRID``, the solver takes the axes directly from
57+
``X_COORDINATES``, ``Y_COORDINATES``, and ``Z_COORDINATES``.
58+
For other structured datasets, the solver reconstructs the axes from the point coordinates.
59+
Therefore, even when ``STRUCTURED_GRID`` is used, the point coordinates should still lie on
60+
separable :math:`x`, :math:`y`, :math:`z` axes.
61+
General unstructured meshes are not qualified input for the present solver.
62+
63+
64+
Velocity Arrays
65+
---------------
66+
67+
Velocity must be stored in ``POINT_DATA``.
68+
Arrays provided only in ``CELL_DATA`` are not sufficient for the current solver.
69+
70+
The parser currently accepts any of the following point-data conventions:
71+
72+
- three scalar arrays named ``u``, ``v``, ``w``;
73+
- three scalar arrays named ``U``, ``V``, ``W``;
74+
- three scalar arrays named ``Ux``, ``Uy``, ``Uz``;
75+
- three scalar arrays named ``Vx``, ``Vy``, ``Vz``;
76+
- two scalar arrays named ``u`` and ``v``;
77+
- two scalar arrays named ``U`` and ``V``;
78+
- two scalar arrays named ``Ux`` and ``Uy``;
79+
- two scalar arrays named ``Vx`` and ``Vy``;
80+
- one vector array named ``U``, ``V``, ``Velocity``, ``velocity``, ``Vel``, ``vel``, ``data``,
81+
or ``Data`` with at least two components.
82+
83+
If only two components are present, the solver fills the third component with zero and therefore
84+
treats the input as quasi-two-dimensional.
85+
All frames in the sequence should use the same array naming convention.
86+
87+
88+
Minimal Qualified Skeleton
89+
--------------------------
90+
91+
A minimal qualified legacy-VTK frame may look conceptually like this:
92+
93+
.. code-block:: text
94+
95+
# vtk DataFile Version 5.1
96+
velocity frame
97+
BINARY
98+
DATASET RECTILINEAR_GRID
99+
DIMENSIONS Nx Ny Nz
100+
X_COORDINATES Nx double
101+
...
102+
Y_COORDINATES Ny double
103+
...
104+
Z_COORDINATES Nz double
105+
...
106+
POINT_DATA Nx*Ny*Nz
107+
VECTORS Velocity double
108+
...
109+
110+
An equally acceptable scalar-array variant is:
111+
112+
.. code-block:: text
113+
114+
POINT_DATA Nx*Ny*Nz
115+
SCALARS u double
116+
LOOKUP_TABLE default
117+
...
118+
SCALARS v double
119+
LOOKUP_TABLE default
120+
...
121+
SCALARS w double
122+
LOOKUP_TABLE default
123+
...
124+
125+
The exact numeric precision is not prescribed here, but the data must be readable by VTK and the
126+
point-data array lengths must match the total number of grid points.
127+
128+
129+
Two-Dimensional and Thin-Slab Data
130+
----------------------------------
131+
132+
The current native solver can also work with quasi-two-dimensional inputs.
133+
In that case:
134+
135+
- the :math:`x` and :math:`y` directions must still contain at least two grid points;
136+
- the :math:`z` direction may be a single layer or a very thin slab;
137+
- the third velocity component may be omitted if the input follows one of the accepted
138+
two-component conventions above.
139+
140+
This is useful for planar velocity fields embedded in a three-dimensional file format.
141+
142+
143+
Practical Checklist
144+
-------------------
145+
146+
Before launching the solver, it is recommended to confirm the following:
147+
148+
- ``vtk_folder`` points to a directory, not to a single file;
149+
- the directory contains only the intended ``.vtk`` time frames, or at least no unrelated
150+
``.vtk`` files whose filename numbers would disturb the ordering;
151+
- all frames share one structured grid and one consistent point-data layout;
152+
- velocity is stored in ``POINT_DATA``;
153+
- the sorted sequence is long enough for the requested ``T_range``.
154+
155+
If ``auto_wall = 1``, the solver uses the outer coordinates of the input grid as the seeding bounds.
156+
If ``auto_wall = 0``, the wall ranges in the ``.par`` file must instead define the computational
157+
domain explicitly.

‎source/6_inputdeck.rst‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ Input and Range Control
3535
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
3636
| ``z`` | Number of Lagrangian seed points in Z direction | ``<int>`` | |
3737
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
38-
| ``T_range`` | Time range [``T_start``, ``T_end``] in frames | ``[<float>, <float>]`` | ``T_end`` no larger than ``N_frames``. |
38+
| ``T_range`` | Time range [``T_start``, ``T_end``] in frames | ``[<float>, <float>]`` | Sorted ``.vtk`` frames; zero-based inclusive indices; ``T_end`` clamped to the last frame. |
3939
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
4040
| ``dt`` | Time step for particle advection in frames | ``<float>`` | |
4141
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
@@ -77,8 +77,6 @@ Numerical Methods
7777
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
7878
| | | ``WENO`` | Weighted Essentially Non-Oscillatory (WENO) scheme with shockwave capture capability. |
7979
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
80-
| | | ``tricubicFL`` | ``I.P.`` The high-performance 3D tricubic interpolation method by [Lekien2005]_. |
81-
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
8280
| ``grad_order`` | Method of gradient discretization | (``2``) | 2nd-order central difference. |
8381
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
8482
| | | ``4`` | ``I.P.`` 4th-order central difference. |
@@ -87,7 +85,7 @@ Numerical Methods
8785
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
8886
| | | ``100`` | ``I.P.`` Global Fast Fourier Transform (FFT) with finite order. Compute extremely intensive! |
8987
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
90-
| ``eigen_method`` | Max eigenvalue of C-G tensor | (``eigmax_sym3``) | Closed-form cubic eigenvalue solver for symmetric 3×3 matrices (noniterative solver). |
88+
| ``Eigen_method`` | Max eigenvalue of C-G tensor | (``eigmax_sym3``) | Closed-form cubic eigenvalue solver for symmetric 3×3 matrices (noniterative solver). |
9189
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+
9290
| | | ``jacobi`` | ``I.P.`` Jacobi eigenvalue algorithm (iterative). |
9391
+-------------------+------------------------------------------------------+-------------------------+---------------------------------------------------------------------------------------------------------+

‎source/7_command.rst‎

Lines changed: 147 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,150 @@
33
Command-Line Mode (Commands)
44
============================
55

6-
This page describes how to perform FTLE computation under command mode via terminal and save results to standard ``.vts`` (Visualization Toolbox Structured data) files,
7-
which is a variation of ``.vtk`` format and supported by official ``.vtk`` API and many other post-processing platforms like ``ParaView``.
6+
Command-line mode runs the native CUDA solver without the GUI.
7+
It is the recommended workflow for batch jobs, remote execution, scheduler submission, and any
8+
reproducible run driven by a checked-in ``.par`` file.
9+
The solver reads one parameter file, loads the velocity sequence described there, computes the
10+
requested FTLE fields, and writes VTK output to ``output_dir``.
11+
12+
13+
Basic Invocation
14+
----------------
15+
16+
The current native solver supports one explicit command-line option:
17+
18+
.. code-block:: text
19+
20+
streamcenterplus_cuda --par <path-to-par-file>
21+
22+
In the repository workflow, the preferred entry point on Windows is the helper script:
23+
24+
.. code-block:: powershell
25+
26+
.\CUDAsolvers\V2603\run.ps1 --par C:\path\to\case.par
27+
28+
On Linux, the same wrapper can be used through PowerShell:
29+
30+
.. code-block:: bash
31+
32+
pwsh ./CUDAsolvers/V2603/run.ps1 --par /path/to/case.par
33+
34+
If your runtime environment is already configured, the built binary may also be launched directly.
35+
The wrapper script remains the safer option because it resolves the newest packaged solver and adds
36+
the required runtime-library paths automatically.
37+
38+
39+
Default Behavior
40+
----------------
41+
42+
If ``--par`` is omitted, the solver looks for ``default.par`` in the current working directory and
43+
prints a warning before proceeding.
44+
This behavior is mainly useful for quick local tests.
45+
For production or shared workflows, an explicit ``--par`` path is strongly preferred.
46+
47+
The command-line solver does not currently expose ad hoc overrides for individual numerical
48+
parameters.
49+
In other words, all run settings are expected to come from the ``.par`` file described in
50+
:ref:`inputdeck`.
51+
52+
53+
Parameter File Advice
54+
---------------------
55+
56+
The ``.par`` file is a plain text file using ``key = value`` lines, with ``#`` available for full-line
57+
or inline comments.
58+
For command-line use, the following practices are recommended:
59+
60+
- prefer absolute paths for ``vtk_folder`` and ``output_dir``;
61+
- keep one ``.par`` file per case or per numerical setup;
62+
- use the folder structure and qualified VTK format described in :ref:`input`;
63+
- keep filenames stable so reruns remain reproducible.
64+
65+
Absolute paths are recommended because the native solver uses the paths as written.
66+
It does not reinterpret them relative to the ``.par`` file location.
67+
68+
69+
Example Run
70+
-----------
71+
72+
Assuming a valid input folder and a parameter file, a typical Windows command is:
73+
74+
.. code-block:: powershell
75+
76+
.\CUDAsolvers\V2603\run.ps1 --par C:\1_Development\Streamcenter+\CUDAsolvers\V2603\tools\case.par
77+
78+
During execution, the solver prints the resolved parameters, reports the number of detected VTK
79+
frames, performs forward FTLE assembly, and optionally performs backward FTLE assembly when
80+
``if_backward = 1``.
81+
Progress messages are written to the terminal throughout loading, advection, FTLE assembly, and
82+
saving.
83+
84+
85+
Output Files
86+
------------
87+
88+
The command-line solver writes structured VTK results into ``output_dir``.
89+
90+
For steady mode, namely ``dyn_mode = 0``, the output base name is
91+
``FTLE3D_NbCU`` and the solver writes:
92+
93+
- ``FTLE3D_NbCU.vts``.
94+
95+
For dynamic mode, namely ``dyn_mode = 1``, the solver writes one ``.vts`` file per valid sliding
96+
window:
97+
98+
- ``FTLE3D_NbCU_00001.vts``,
99+
- ``FTLE3D_NbCU_00002.vts``,
100+
- and so forth.
101+
102+
If at least one dynamic window is produced, the solver also writes
103+
``FTLE3D_NbCU_dynamic.pvd`` as a collection file for time-series loading.
104+
105+
Within each ``.vts`` output, the point-data arrays are:
106+
107+
- ``FTLE_forward`` always;
108+
- ``FTLE_backward`` only when ``if_backward = 1``.
109+
110+
111+
Indexing and Frame Selection
112+
----------------------------
113+
114+
The frame range is controlled by ``T_range`` in the ``.par`` file.
115+
Its indices are applied to the input sequence after the ``.vtk`` filenames have been sorted as
116+
described in :ref:`input`.
117+
118+
The current native solver:
119+
120+
- uses zero-based frame indexing internally;
121+
- treats the selected range as inclusive on both ends;
122+
- clamps the requested end index to the last available frame.
123+
124+
Therefore, if a folder contains :math:`N` sorted frames, the last valid explicit frame index is
125+
:math:`N-1`.
126+
127+
128+
Important Notes
129+
---------------
130+
131+
- ``if_visual = 1`` is intentionally ignored in the command-line solver; interactive visualization
132+
belongs to the GUI workflow.
133+
- In dynamic mode, ``win_size`` and ``win_step`` are required. Omitting either one causes the run
134+
to stop with an error.
135+
- The command-line solver currently reads legacy ``.vtk`` input only. Result files are written as
136+
``.vts`` and, for dynamic mode, also ``.pvd``.
137+
- A nonzero exit code indicates a fatal error such as a missing VTK folder, absent velocity arrays,
138+
or an invalid parameter combination.
139+
140+
141+
When to Prefer Command-Line Mode
142+
--------------------------------
143+
144+
Command-line mode is preferable when:
145+
146+
- the run should be launched on a workstation or server without opening the GUI;
147+
- one wants a reproducible case definition in a small text ``.par`` file;
148+
- the same case must be repeated under several numerical settings;
149+
- the solver is called from scripts, job schedulers, or automated regression checks.
150+
151+
For interactive inspection of results, however, the GUI and external post-processing tools such as
152+
``ParaView`` remain more convenient than the terminal itself.

0 commit comments

Comments
 (0)