The Case Input File (<case>.inp) and points.dat

A Rocflu case is described by <case>.inp (this page), <case>.bc (Boundary Conditions), the grid (<case>.hyb.asc) and, with particles, points.dat. Before a run, ./rocflu.sh validate checks the input file, the .bc file and points.dat; ./rocflu.sh run does this first and stops before building anything if it finds a problem.

The template used by the regression tests, tests/templates/rectshktb.inp, is a complete, working example.

How Rocflu Reads the File

# PICL
USED             1 ! comment
QSFORCE          3
#

• A section starts at a line that is exactly # NAME (one space, no other text; #PICL or # PICL extra is not recognised) and ends at the next line that starts with #. Sections Rocflu does not know are skipped.
• A key must start in the first column: a line with a space before the key is ignored. The value follows the key; anything after it (usually a ! comment) is ignored. Lines starting with ! are comments.
• A key that is not given keeps its default (below). A key given twice: the first one counts.
• Keys may come in any order within a section. The key must be followed by a space or a tab.
• Flags are whole numbers; Rocflu rounds other values silently (2.6 becomes 3).
• Rocflu silently ignores a key it does not know, so a typo (QSFLUC 1) turns a model off.

The validator reports all of these (with the line number), so they need not be remembered.

Gas-Side Sections

Only the keys in the test template are listed; the readers (libfloflu/Read*Section.F90) accept more.

# PICL: The Particles

Defaults are those of libflu/RFLU_InitGlobal.F90. A key that belongs to a model that is off (e.g. KSP without collisions) is not read and may stay in the file with any value.

The filter width of the particle projection is not an input: it is twice the largest cell length around the particles. ./rocflu.sh run builds only the particle data the models that are on need (libpicl/user_files/ppiclf_slots.txt, see Getting Started).

Models That Need Other Models

With USED 1, these combinations are rejected:

Other sections, with USED 1: RKSCHEME 2 in # TIMESTEP, VISCOSITY in # VISCMODEL, no AXIFLAG 1 in # NUMERICS.

points.dat: The Particles' Initial State

points.dat (this name, in the case directory) lists the particles:

! optional comment lines, at the top only
3
1.0e-3  2.0e-3  3.0e-3    0.0  0.0  0.0    1.0e-4
4.0e-3  5.0e-3  6.0e-3   10.0  0.0  0.0    1.0e-4
...

The first line after the comments is the number of particles; then one line per particle: position x y z [m], initial velocity vx vy vz [m/s] (0 0 0 for a particle at rest) and diameter dp [m], all seven on every line. Density, specific heat and initial temperature are the same for every particle (DENSITY, SPECIFICHEAT, TEMP in # PICL).

Older forms are no longer read: a material name in the first column (removed with # MATERIAL for particles), and x y z dp [u v w] (diameter before the velocity). The validator and rflump both stop on them.

Output and Restarts

rflump writes its results as raw dumps in restart_data/, at step 0 (the particles), every WRITIME and the end of the run:

• fluid_<step>_<region>.dat: the gas state of a region as it is in memory (real cells, double precision), with particles also the particle volume fraction and the gas-density gradient, with PSEUDOTURB the pseudo-turbulence fields, and the face states of the non-reflecting (NSCBC) boundaries. rfluinit writes step 0.
• particles_<step>.dat: every particle (state, properties, IDs, random-stream state, viscous-unsteady history), the fields projected to the fluid cells, the bins and the list of output fields.

Layouts: modflu/RFLU_ModRestartData.F90. A file is written as .tmp and renamed when it is complete. The same files are what a restart reads and what the post program converts (./rocflu.sh post, see Running a Simulation), so results can be looked at during a run or after it stopped.

Starting a run (START_STEP in # TIMESTEP): 0 (default) is a new run from rfluinit's step 0; it removes what an earlier run in the directory left (dumps after step 0, the old-style output). -1 restarts from the latest step with every dump, N from step N; dumps after the start step are removed. A restart needs the same number of ranks and the same particle physics as the run that wrote the dump, and continues it exactly: the results are the same, to the last bit, as a run that never stopped (checked by the suite's restart test).

The old-style output (SOL_*, PARAVIEW_*, par*.vtu, bin*.vtu, patch coefficients) is written only with OLD_OUTPUT_WRT 1 in # POST; the suite keeps it on in a few cases to check that it agrees with the dumps and the post program. Without particles its Velocity and Energy fields hold the momentum and the energy per volume; the post program writes velocity and energy per mass.

The Case Validator

./rocflu.sh validate /path/to/case/<case>.inp
python3 utilities/scripts/case_validator.py /path/to/case/<case>.inp      # the same

utilities/scripts/case_validator.py reads the input file the way Rocflu does and prints every problem at once, with the file and line, then exits with status 1 (0 when the case is fine). ./rocflu.sh run runs it before building, and the regression suite runs it on every case. It checks:

• # PICL: unknown keys (with the closest known key as a hint), removed keys, keys after a space, keys given twice, keys Rocflu would read as another key;
• flags that are not whole numbers or outside the values in the table above; TEMP, DENSITY, SPECIFICHEAT > 0; NEIGHBORWIDTH ≥ 0; with collisions KSP > 0 and 0 < EREST ≤ 1; with viscous-unsteady VUSTEPS ≥ 1;
• the combinations above, and the gas-side settings particles need;
• # SPECIES USED 1, GASMODEL 3-7 and # MATERIAL sections: species transport is disabled for now;
• the case directory: points.dat is present and in the format above (the count matches the lines, dp > 0); no filein.vtk (particle walls come from PARTWALL 1 in the .bc file); no par00002.vtu from an earlier run (it would start a particle restart, which is not available yet);
• the .bc file: every rule of Boundary Conditions (sections, keys, values, required keys, every grid patch once, periodic pairs, order 1 where boundary gradients are needed). The patch count comes from the grid (<case>.hyb.asc, GRIDSRC 0); without it, patches 1 to the highest one used must all be there;
• every particle inside the fluid domain, taken as the box around the grid's vertices (<case>.hyb.asc, GRIDSRC 0; about a second for a million vertices). In a domain that is not a box, a particle can be inside the box but outside the grid.

Without particles (USED 0 or no # PICL), only the keys of # PICL are checked.

The validator mirrors rocpicl/PICL_ReadPiclSection.F90 (keys and their order), libflu/RFLU_InitGlobal.F90 (defaults) and modflu/RFLU_ModReadBcInputFile.F90 (the .bc sections and keys): change it with them. Its tests need no cluster: python3 tests/test_case_validator.py.

Removed Keys