Changes

Page history
Update 4.2 User interfaces authored by Udo Ziegler's avatar Udo Ziegler
Show whitespace changes
Inline Side-by-side
4-CAIVS-user-guide/4.2-User-interfaces.md
View page @ 95c1df70
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