|
|
x
|
|
|
[4_User-interfaces.md](uploads/23a354e7856192485824dfe08732aad0/4_User-interfaces.md) |
|
|
\ No newline at end of file |
|
|
|
|
|
CONTENTS:
|
|
|
|
|
|
[Specification of parameters](4.2-User-interfaces#specification-of-parameters)
|
|
|
|
|
|
[User-defined variables](4.2-User-interfaces#user-defined-variables)
|
|
|
|
|
|
There are two user interfaces:
|
|
|
|
|
|
- `caivs.par` – specification of CAIVS parameters
|
|
|
|
|
|
- `variablesUser.c` – definition of user variables
|
|
|
|
|
|
### Specification of parameters
|
|
|
|
|
|
CAIVS requires the parameter file `caivs.par` as input. In this file the
|
|
|
user specifies which and how data is converted in which output format.
|
|
|
Within `caivs.par` parameters are grouped into the sections
|
|
|
|
|
|
- **DATA INPUT** – specification of input data
|
|
|
|
|
|
- **DATA EXPORT** – specification of export format
|
|
|
|
|
|
- **MESH TRANSFORMER** – mesh transformation options
|
|
|
|
|
|
- **VARIABLES** – selection of variables to be converted
|
|
|
|
|
|
A parameter section starts with its category name preceded by the
|
|
|
`>`-character. The associated parameters follow in lines where a line
|
|
|
can contain more than one parameter. Parameters are separated by white
|
|
|
spaces and it can be numbers, single characters or words. The
|
|
|
`>`-character and text thereafter is ignored by the parser and serves
|
|
|
for comments. For example, the DATA INPUT section in `caivs.par` looks
|
|
|
like
|
|
|
|
|
|
>DATA INPUT --------------------------------------------------------------------
|
|
|
/work2/ziegler/viz/ >data_dir
|
|
|
0001471 000000 >datafile_{number,sequence}
|
|
|
|
|
|
There are two parameter lines here containing 1 (`/work2/ziegler/viz/`)
|
|
|
respective 2 (`0001471` and 000000) parameters.
|
|
|
|
|
|
A complete list of parameters for each category is presented next.
|
|
|
Parameter lines are marked with a 2-digit running number for a clear
|
|
|
reference (Lines are actually not numbered in `caivs.par`). Parameter
|
|
|
explanations follow the pattern ’line\# (parameter names within the line
|
|
|
from left to right)’ plus a description of each parameter appearing in a
|
|
|
line. For some parameters their valid range of values are given in round
|
|
|
brackets after the parameter’s name either in form of a set {} or a
|
|
|
numeric range. For some parameters typically used values are given.
|
|
|
Technically, most of the parameters are collected in a global structure
|
|
|
variable named `_CC` defined in the header `caivs.h`. A certain
|
|
|
parameter `V` in `_CC` is then addressed by `_CC.V`, e.g.,
|
|
|
`_CC.make_unigrid` for the option to transform an adaptive grid onto a
|
|
|
uniform grid.
|
|
|
|
|
|
**DATA INPUT**:
|
|
|
|
|
|
>DATA INPUT --------------------------------------------------------------------
|
|
|
01 /work2/ziegler/viz/ >data_dir
|
|
|
02 0001471 000000 >datafile_{number,sequence}
|
|
|
|
|
|
- `01` (`_CC.data_dir`)
|
|
|
|
|
|
- `_CC.data_dir`: directory of input data (NIRVANA snapshot
|
|
|
files).
|
|
|
|
|
|
- `02` (`_CC.datafile_number`, `_CC.datafile_sequence`)
|
|
|
|
|
|
- `_CC.datafile_number`: cycle number (NIRVANA parameter:
|
|
|
`_C.mod`) in the base filename of the NIRVANA snapshot to be
|
|
|
converted first. Recall that NIRVANA snapshot files are named
|
|
|
`NIR#.#` where the pre-dot-`#` equals `_C.mod`, i.e., the base
|
|
|
filename of a snapshot is given by `NIR#` (cf. [NIRVANA:
|
|
|
Snapshot
|
|
|
files](3-NIRVANA-user-guide/3.3-Output-data#snapshot-files))
|
|
|
|
|
|
*Note: CAIVS automatically recognises the number of data
|
|
|
containers of a snapshot. The user just has to take care that
|
|
|
all snapshot files belonging to a snapshot lie in the input
|
|
|
directory.*
|
|
|
|
|
|
- `_CC.datafile_sequence`: timestep cycle number increment in case
|
|
|
of a snapshot sequence. If this parameter is chosen non-zero,
|
|
|
CAIVS tries to convert a sequence of snapshots with cycle number
|
|
|
successively increased in the base filename by value
|
|
|
`_CC.datafile_sequence` starting with cycle number given by
|
|
|
`_CC.datafile_number`.
|
|
|
|
|
|
**DATA EXPORT**:
|
|
|
|
|
|
>DATA EXPORT -------------------------------------------------------------------
|
|
|
01 /work2/ziegler/viz/ >export_dir
|
|
|
02 NIR 0001471 >format:{NIR,SILO,CSV,HDF},filenumber
|
|
|
03 4 >precision:[2,8]
|
|
|
04 0 >vars_files:{0,1}
|
|
|
|
|
|
- `01` (`_CC.export_dir`)
|
|
|
|
|
|
- `_CC.export_dir`: directory of output data. Usually, this is the
|
|
|
same as the directory for the input data.
|
|
|
|
|
|
- `02` (`_CC.format`, `_CC.filenumber`)
|
|
|
|
|
|
- `_CC.format` ({NIR,SILO,CSV,HDF}): output data format. Possible
|
|
|
values are
|
|
|
|
|
|
- NIR: CAIVS native format
|
|
|
|
|
|
- SILO: Silo format
|
|
|
|
|
|
- CSV: Comma-Separated-Variable-like format
|
|
|
|
|
|
- HDF: HDF5 format
|
|
|
|
|
|
- `_CC.filenumber`: number of the (first) output file. In case of
|
|
|
a snapshot sequence the output file number is incremented by one
|
|
|
from snapshot to snapshot.
|
|
|
|
|
|
- `03` (`_CC.precision`)
|
|
|
|
|
|
- `_CC.precision` (\[2,8\]): numerical precision of output data.
|
|
|
In case of the CSV output format `_CC.precision` gives the
|
|
|
number of decimal places of issued values. For all other formats
|
|
|
output data is assumed of type `float` (`double`) if
|
|
|
`_CC.precision` ≤ 4 (`_CC.precision` > 4).
|
|
|
|
|
|
- `04` (`_CC.vars_files`)
|
|
|
|
|
|
- `_CC.vars_files` ({0,1}): option to enable/disable a separate
|
|
|
output file for each selected variable.
|
|
|
|
|
|
**MESH TRANSFORMER**:
|
|
|
|
|
|
>MESH TRANSFORMER --------------------------------------------------------------
|
|
|
01 24 >max_level
|
|
|
02 0 2.220464e+17 2.220487e+17 >subrange[0]:{0,1},rangemin[0],rangemax[0]
|
|
|
03 0 1.191100e+15 1.193400e+15 >subrange[1]:{0,1},rangemin[1],rangemax[1]
|
|
|
04 0 -5.000000e-02 5.000000e-02 >subrange[2]:{0,1},rangemin[2],rangemax[2]
|
|
|
05 1 >make_unigrid:{0,1}
|
|
|
06 0 >cell_centering:{0,1}
|
|
|
07 0 >grid_overlap:{0,1}
|
|
|
08 1 1 >coord_transform:{0,1},vector_transform:{0,1}
|
|
|
|
|
|
- `01` (`_CC.max_level`)
|
|
|
|
|
|
- `_CC.max_level`: maximum refinement level to be considerd in the
|
|
|
conversion process. If an input mesh has a higher refinement
|
|
|
level than the specified value `_CC.max_level` all higher levels
|
|
|
are ignored.
|
|
|
|
|
|
- `02` (`_CC.subrange[0]`, `_CC.rangemin[0]`,`_CC.rangmax[0]`)
|
|
|
|
|
|
- `_CC.subrange[0]` ({0,1}): option to select a subrange in
|
|
|
*x*-direction. A value 0 stands for the full *x*-range of the
|
|
|
computational domain. In this case the following parameters
|
|
|
`_CC.rangemin[0]` and `_CC.rangemax[0]` have no meaning. A value
|
|
|
1 stands for a subrange in *x*-direction.
|
|
|
|
|
|
- `_CC.rangemin[0]`: lower *x*-coordinate of subdomain.
|
|
|
|
|
|
- `_CC.rangemax[0]`: upper *x*-coordinate of subdomain.
|
|
|
|
|
|
- `03` (`_CC.subrange[1]`, `_CC.rangemin[1]`,`_CC.rangmax[1]`)
|
|
|
|
|
|
- `_CC.subrange[1]` ({0,1}): same as `_CC.subrange[0]` but for the
|
|
|
*y*-direction.
|
|
|
|
|
|
- `_CC.rangemin[1]`: same as `_CC.rangemin[0]` but for the
|
|
|
*y*-direction. In case of spherical geometry (*y* ≡ *θ*) the
|
|
|
value must be given in units of *π*.
|
|
|
|
|
|
- `_CC.rangemax[1]`: same as `_CC.rangemax[0]` but for the
|
|
|
*y*-direction. In case of spherical geometry (*y* ≡ *θ*) the
|
|
|
value must be given in units of *π*.
|
|
|
|
|
|
- `04` (`_CC.subrange[2]`, `_CC.rangemin[2]`,`_CC.rangmax[2]`)
|
|
|
|
|
|
- `_CC.subrange[2]` ({0,1}): same as `_CC.subrange[0]` but for the
|
|
|
*z*-direction.
|
|
|
|
|
|
- `_CC.rangemin[2]`: same as `_CC.rangemin[0]` but for the
|
|
|
*z*-direction. In case of cylindrical- or spherical geometry
|
|
|
(*z* ≡ *ϕ*) the value must be given in units of *π*.
|
|
|
|
|
|
- `_CC.rangemax[2]`: same as `_CC.rangemax[0]` but for the
|
|
|
*z*-direction. In case of cylindrical- or spherical geometry
|
|
|
(*z* ≡ *ϕ*) the value must be given in units of *π*.
|
|
|
|
|
|
*Note: The values specified by `_CC.rangemin[]` and `_CC.rangemax[]`
|
|
|
are only (good) approximations to the actual determined output
|
|
|
domain size.*
|
|
|
|
|
|
- `05` (`_CC.make_unigrid`)
|
|
|
|
|
|
- `_CC.make_unigrid` ({0,1}: option to transform the input mesh
|
|
|
onto a uniform grid. A value 1 transforms an adaptive mesh onto
|
|
|
a finest-level uniform grid but limited by the parameter
|
|
|
`_CC.max_level`. If the input mesh is already an unigrid no
|
|
|
transformation takes place.
|
|
|
|
|
|
*Note: An unigrid created out of a highly refined input mesh may
|
|
|
become too large to be represented in memory!*
|
|
|
|
|
|
- `06` (`_CC.cell_centering`)
|
|
|
|
|
|
- `_CC.cell_centering` ({0,1}): option to output cell-centered
|
|
|
variables data. By default (value 0), variables in exported
|
|
|
formats are node-centered.
|
|
|
|
|
|
- `07` (`_CC.grid_overlap`)
|
|
|
|
|
|
- `_CC.grid_overlap` ({0,1}): *currently not used.*
|
|
|
|
|
|
- `08` (`_CC.coord_transform`,`_CC.vector_transform`)
|
|
|
|
|
|
- `_CC.coord_transform` ({0,1}): option to transform a
|
|
|
cylindrical/spherical input mesh into a irregular (hexahedral)
|
|
|
Cartesian output mesh. By default (value 0), no transformation
|
|
|
takes place.
|
|
|
|
|
|
- `_CC.vector_transform` ({0,1}): option to transform
|
|
|
cylindrical/spherical vector components into Cartesian
|
|
|
components. By default (value=0), vector components are not
|
|
|
transformed.
|
|
|
|
|
|
**VARIABLES**:
|
|
|
|
|
|
>VARIABLES ---------------------------------------------------------------------
|
|
|
01 1 >log_density:{0,1}
|
|
|
02 1 >velocity:{0,1}
|
|
|
03 1 >log_pressure:{0,1}
|
|
|
04 1 >log_temperature:{0,1}
|
|
|
05 1 1 999 >log_nX:{0,1},species_min,species_max
|
|
|
06 1 >tracer:{0,1}
|
|
|
07 1 >gravity_potential:{0,1}
|
|
|
08 1 >magnetic_field:{0,1}
|
|
|
09 1 >log_eDensity:{0,1}
|
|
|
10 1 >testfields:{0,1}
|
|
|
11 0 >#user_variables
|
|
|
|
|
|
- `01` (`_CC.comp[0]`)
|
|
|
|
|
|
- `_CC.comp[0]` ({0,1}): option to select the logarithm of mass
|
|
|
density, log 𝜚, for conversion.
|
|
|
|
|
|
- `02` (`_CC.comp[1]`)
|
|
|
|
|
|
- `_CC.comp[1]` ({0,1}): option to select the gas velocity, **v**,
|
|
|
for conversion.
|
|
|
|
|
|
- `03` (`_CC.comp[2]`)
|
|
|
|
|
|
- `_CC.comp[2]` ({0,1}): option to select the logarithm of
|
|
|
pressure, log *p*, for conversion.
|
|
|
|
|
|
- `04` (`_CC.comp[3]`)
|
|
|
|
|
|
- `_CC.comp[3]` ({0,1}): option to select the logarithm of
|
|
|
temperature, log *T*, for conversion.
|
|
|
|
|
|
- `05` (`_CC.comp[4]`, `_CC.species_min`,`_CC.species_max`)
|
|
|
|
|
|
- `_CC.comp[4]` ({0,1}): option to select the logarithm of species
|
|
|
number densities, log *n*<sub>*s*</sub>, for conversion.
|
|
|
|
|
|
- `_CC.species_min` ( ≥ 1): lower range value of species for
|
|
|
conversion.
|
|
|
|
|
|
- `_CC.species_max`
|
|
|
(≥`_``CC.species_min`): upper range
|
|
|
value of species for conversion.
|
|
|
|
|
|
- `06` (`_CC.comp[5]`)
|
|
|
|
|
|
- `_CC.comp[5]` ({0,1}): option to select tracer variables,
|
|
|
*C*<sub>*c*</sub>, for conversion. A value 1 selects all tracer
|
|
|
variables at the same time.
|
|
|
|
|
|
- `07` (`_CC.comp[6]`)
|
|
|
|
|
|
- `_CC.comp[6]` ({0,1}): option to select the gravitational
|
|
|
potential, *Φ*, for conversion.
|
|
|
|
|
|
- `08` (`_CC.comp[7]`)
|
|
|
|
|
|
- `_CC.comp[7]` ({0,1}): option to select the magnetic field,
|
|
|
**B**, for conversion.
|
|
|
|
|
|
- `09` (`_CC.comp[8]`)
|
|
|
|
|
|
- `_CC.comp[8]` ({0,1}): option to select the logarithm of the
|
|
|
electron number density, log *n*<sub>*e*</sub>, for conversion.
|
|
|
|
|
|
- `10` (`_CC.comp[9]`)
|
|
|
|
|
|
- `_CC.comp[9]` ({0,1}): option to select the testfields
|
|
|
fluctuations, **b**<sub>*t*</sub>, for conversion.
|
|
|
|
|
|
- `11` (`_CC.comp[10]`)
|
|
|
|
|
|
- `_CC.comp[10]`: number of user-defined variables to select for
|
|
|
conversion. A value 0 means that no user variable has been
|
|
|
defined.
|
|
|
|
|
|
### User-defined variables
|
|
|
|
|
|
The module `variablesUser.c` serves as template for the definition of
|
|
|
user variables to be converted into the specified output format.
|
|
|
|
|
|
In the call of `variablesUser()` the function arguments are a superblock
|
|
|
pointer `g`, the array pointer `v` of type `double***` representing the
|
|
|
user variable and the variable index `ivar`:
|
|
|
|
|
|
variablesUser(g,v,ivar);
|
|
|
|
|
|
The user must assign the `v`-array for the full `g`-index range and for
|
|
|
each variable index `ivar`, whence code like
|
|
|
|
|
|
switch(ivar) /* ONE CASE STATEMENT PER USER VARIABLE */
|
|
|
{
|
|
|
case 1: /* USER VARIABLE #1 */
|
|
|
/* EXAMPLE: KINETIC ENERGY DENSITY */
|
|
|
for(iz=0; iz<=g->nz; iz++)
|
|
|
for(iy=0; iy<=g->ny; iy++)
|
|
|
for(ix=0; ix<=g->nx; ix++)
|
|
|
{
|
|
|
v[iz][iy][ix]=0.5*(g->mx[iz][iy][ix]*g->mx[iz][iy][ix]
|
|
|
+g->my[iz][iy][ix]*g->my[iz][iy][ix]
|
|
|
+g->mz[iz][iy][ix]*g->mz[iz][iy][ix])
|
|
|
/g->rho[iz][iy][ix];
|
|
|
}
|
|
|
break;
|
|
|
|
|
|
case 2: /* USER VARIABLE #2 */
|
|
|
...
|
|
|
break;
|
|
|
.
|
|
|
.
|
|
|
.
|
|
|
}
|
|
|
|
|
|
must be added in `variablesUser.c`. The function is called by CAIVS for
|
|
|
the variable index `ivar` running from 1 to `_CC.comp[10]` where the
|
|
|
parameter `_CC.comp[10]` stores the number of user variables as
|
|
|
specified in the parameter file `caivs.par` under category VARIABLES.
|
|
|
|
|
|
The superblock `g` represents a somewhat modified NIRVANA superblock
|
|
|
with a reduced number of one ghost cell per side per coordinate
|
|
|
direction. `g` contains all the NIRVANA primary physical variables which
|
|
|
were simulation-relevant plus additional thermodynamic variables.
|
|
|
|
|
|
Here is the list of possibly imported physical variables:
|
|
|
|
|
|
| `g->` | variable |
|
|
|
|:----------------------|:-----------------------------------------------------------------------------------------|
|
|
|
| `rho[iz][iy][ix]` | mass density 𝜚 |
|
|
|
| `mx[iz][iy][ix]` | *x*-momentum density *m*<sub>*x*</sub> |
|
|
|
| `my[iz][iy][ix]` | *y*-momentum density *m*<sub>*y*</sub> |
|
|
|
| `mz[iz][iy][ix]` | (canonical) *z*-momentum density *m*<sub>*z*</sub> |
|
|
|
| `e[iz][iy][ix]` | total energy density *e* (if energy equation) |
|
|
|
| `bx[iz][iy][ix]` | magnetic field component *B*<sub>*x*</sub> (if MHD) |
|
|
|
| `by[iz][iy][ix]` | magnetic field component *B*<sub>*y*</sub> (if MHD) |
|
|
|
| `bz[iz][iy][ix]` | magnetic field component *B*<sub>*z*</sub> (if MHD) |
|
|
|
| `phi[iz][iy][ix]` | gravitational potential *Φ* (if selfgravity) |
|
|
|
| `nX[is][iz][iy][ix]` | species number densities *n*<sub>*s*</sub> (if species) |
|
|
|
| `C[ic][iz][iy][ix]` | tracer variables *C*<sub>*c*</sub> (if tracer) |
|
|
|
| `tfx[it][iz][iy][ix]` | *x*-component *b*<sub>*x*</sub><sub>*t*</sub> of testfields fluctuations (if testfields) |
|
|
|
| `tfy[it][iz][iy][ix]` | *y*-component *b*<sub>*y*</sub><sub>*t*</sub> of testfields fluctuations (if testfields) |
|
|
|
| `tfz[it][iz][iy][ix]` | *z*-component *b*<sub>*z*</sub><sub>*t*</sub> of testfields fluctuations (if testfields) |
|
|
|
| `p[iz][iy][ix]` | thermal pressure *p* |
|
|
|
| `T[iz][iy][ix]` | temperature *T* |
|
|
|
| `et[iz][iy][ix]` | thermal energy density *ε* (if dual energy mode) |
|
|
|
| `ne[iz][iy][ix]` | electron number density *n*<sub>*e*</sub> |
|
|
|
|
|
|
The array indices have the meaning and ranges as cataloged in the
|
|
|
following table
|
|
|
|
|
|
| index | meaning | range |
|
|
|
|:------|:----------------------------------------|:----------------------|
|
|
|
| `ix` | `g`-index in *x*-direction | 0...`g->nx` |
|
|
|
| `iy` | `g`-index in *y*-direction | 0...`g->ny` |
|
|
|
| `iz` | `g`-index in *z*-direction | 0...`g->nz` |
|
|
|
| `is` | species counter | 0...`_C.species`-1 |
|
|
|
| `ic` | tracers counter | 0...`_C.tracer`-1 |
|
|
|
| `it` | testfield fluctuation variables counter | 0...`_C.testfields`-1 |
|
|
|
|
|
|
where `_C.species`, `_C.tracer` and `_C.testfields` are NIRVANA
|
|
|
parameters (cf. [NIRVANA: Specification of main
|
|
|
parameters](3-NIRVANA-user-guide/3.2-User-interfaces#specification-of-main-parameters))
|
|
|
storing the number of species, number of tracers and number of
|
|
|
testfields, respectively.
|
|
|
|
|
|
*Note 1: The magnetic field components and testfields fluctuations
|
|
|
components are represented at cell-face-centroid coordinates whereas all
|
|
|
other variables listed in the table are given at cell-centroid positions
|
|
|
(cf. [NIRVANA: Mesh data
|
|
|
structure](3-NIRVANA-user-guide/3.1-Code-basics#mesh-data-structure))*
|
|
|
|
|
|
The imported variables can be used to derive user variables as in the
|
|
|
`case 1:` example above. CAIVS assumes that user variables are
|
|
|
cell-averaged quantities, i.e., that it are represented at cell-centroid
|
|
|
coordinates like the mass density, for instance.
|
|
|
|
|
|
*Note 2: If user variables involve derivatives of input variables, e.g.
|
|
|
the flow vorticiy ∇ × (**m**/𝜚), one-sided discretization formulas or
|
|
|
extrapolation techniques may be needed to accurately compute derivatives
|
|
|
at `g` boundary cells.* |
|
|
\ No newline at end of file |