Changes

Page history
version 4.2 authored by Udo Ziegler's avatar Udo Ziegler
Hide whitespace changes
Inline Side-by-side
4-CAIVS-user-guide/4.2-User-interfaces.md
View page @ f7e3cede
![logo_short_small](uploads/1e4ee858ca174663b210647640da0976/logo_short_small.png) `4.1` ## User interfaces
CONTENTS: CONTENTS:
[Specification of parameters](4.2-User-interfaces#specification-of-parameters)
[User-defined variables](4.2-User-interfaces#user-defined-variables)
[Modification of input data](4.2-User-interfaces#modification-of-input-data)
There are 3 user interfaces: [Specification of parameters](#specification-of-parameters)
- `caivs.par` – specification of CAIVS parameters [User-defined variables](#user-defined-variables)
- `variablesUser.c` – definition of user variables [Modification of input data](#modification-of-input-data)
- `modifyDataUser.c` - modification of input data There are 3 user interfaces to CAIVS:
- `caivs.par` -- serves to specify conversion parameters
- `variablesUser.c` -- serves to define user variables
- `modifyDataUser.c` -- serves to modify input data before conversion
### Specification of parameters ### Specification of parameters
CAIVS requires the parameter file `caivs.par` as input. In this file the The parameter file `caivs.par` controlls how NIRVANA input data is
user specifies which and how data is converted in which output format. converted into CAIVS output data. Parameters are categorized into the 4
Within `caivs.par` parameters are grouped into the sections sections:
- **DATA INPUT** – specification of input data - **DATA INPUT** -- specification of input data
- **DATA EXPORT** – specification of export format - **DATA EXPORT** -- specification of export format
- **MESH TRANSFORMER** – mesh transformation options - **MESH TRANSFORMER** -- mesh transformation options
- **VARIABLES** – selection of variables to be converted - **VARIABLES** -- selection of variables to be converted
A parameter section starts with its category name preceded by the A parameter section in `caivs.par` starts with its category name
`>`-character. The associated parameters follow in lines where a line preceded by the `>`-character. Parameters follow in lines where each
can contain more than one parameter. Parameters are separated by white line may contain more than one parameter. Parameters in a line are
spaces and it can be numbers, single characters or words. The separated by white spaces. Parameters can be numbers, single characters
`>`-character and text thereafter is ignored by the parser and serves or words. The `>`-character hereafter and following text serve as
for comments. For example, the DATA INPUT section in `caivs.par` looks comments and is ignored by the file parser.
like
All parameters are described in detail in the following. On referencing
>DATA INPUT -------------------------------------------------------------------- purposes parameter lines are marked here with a 2-digit running number.
/work2/ziegler/viz/ >data_dir Actually, lines are not numbered in `caivs.par`. Parameter names are in
0001471 000000 >datafile_{number,sequence} round brackets after the line number. Most parameters are subsumed in a
0 >data_modify:{0,1} 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.,
There are 3 parameter lines here containing, from top to bottom, 1 parameter `_CC.data_dir`. For some parameters their valid range of values are
(`/work2/ziegler/viz/`), 2 parameters (`0001471` and `000000`) and given either in form of a set {} of possible values or a numeric range.
1 parameter (`0`), respectively.
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**:
...@@ -67,37 +55,36 @@ uniform grid. ...@@ -67,37 +55,36 @@ uniform grid.
- `01` (`_CC.data_dir`) - `01` (`_CC.data_dir`)
- `_CC.data_dir`: directory of input data (where NIRVANA snapshot - `_CC.data_dir`: directory of input data
files reside).
- `02` (`_CC.datafile_number`, `_CC.datafile_sequence`) - `02` (`_CC.datafile_number`, `_CC.datafile_sequence`)
- `_CC.datafile_number`: cycle number (NIRVANA parameter: - `_CC.datafile_number`: timestep number (NIRVANA parameter:
`_C.mod`) in the base filename of the NIRVANA snapshot to be `_C.mod`) in the filename of the NIRVANA snapshot. Recall that
converted first. Recall that NIRVANA snapshot files are named NIRVANA snapshot files are named `NIR#.#` where the pre-dot-`#`
`NIR#.#` where the pre-dot-`#` equals `_C.mod`, i.e., the base equals `_C.mod`, i.e., the base filename of a snapshot is given
filename of a snapshot is given by `NIR#` (cf. [NIRVANA: by `NIR#` (cf. [NIRVANA: Snapshot
Snapshot
files](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/3-NIRVANA-user-guide/3.3-Output-data#snapshot-files)) files](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/3-NIRVANA-user-guide/3.3-Output-data#snapshot-files))
*Note: CAIVS automatically recognises the number of data *Note: A NIRVANA snapshot may be distributed among several
containers of a snapshot. The user just has to take care that container files (the post-dot-`#` in `NIR#.#` is the container
all snapshot files belonging to a snapshot lie in the input number). This is automatically recognises by CAIVS but the user
directory.* has to take care that all container files belonging to a
snapshot are in the input directory.*
- `_CC.datafile_sequence`: timestep cycle number increment in case - `_CC.datafile_sequence`: cycle number for a snapshot sequence.
of a snapshot sequence. If this parameter is chosen non-zero, If this parameter is chosen non-zero, CAIVS converts a sequence
CAIVS tries to convert a sequence of snapshots with cycle number of snapshots with timestep numbers successively increased by
successively increased in the base filename by value value `_CC.datafile_sequence` starting with
`_CC.datafile_sequence` starting with cycle number given by `_CC.datafile_number`. The sequence stops if filenames are not
`_CC.datafile_number`. existing.
- `03` (`_CC.data_modify`) - `03` (`_CC.data_modify`)
- `_CC.data_modify` ({0,1}): option to allow a modification of - `_CC.data_modify` ({0,1}): allows a modification of NIRVANA
NIRVANA input data. If set to 1, the user interface input data if set to 1. The user interface
[modifyDataUser.c](4.2-User-interfaces#modification-of-input-data) [`modifyDataUser.c`](#modification-of-input-data). is called
is called prior to data export which permits to manipulate physical prior to data export which permits to manipulate physical
variables. variables.
**DATA EXPORT**: **DATA EXPORT**:
...@@ -110,13 +97,13 @@ uniform grid. ...@@ -110,13 +97,13 @@ uniform grid.
- `01` (`_CC.export_dir`) - `01` (`_CC.export_dir`)
- `_CC.export_dir`: directory of output data. Usually, this is the - `_CC.export_dir`: directory of output data. Can be set the same
same as the directory for the input data. as the input data directory.
- `02` (`_CC.format`, `_CC.filenumber`) - `02` (`_CC.format`, `_CC.filenumber`)
- `_CC.format` ({NIR,SILO,CSV,HDF,RAW}): output data format. Possible - `_CC.format` ({NIR,SILO,CSV,HDF,RAW}): output data format.
values are Possible values are
- NIR: CAIVS native format - NIR: CAIVS native format
...@@ -129,21 +116,23 @@ uniform grid. ...@@ -129,21 +116,23 @@ uniform grid.
- RAW: raw arrays format - RAW: raw arrays format
- `_CC.filenumber`: number of the (first) output file. In case of - `_CC.filenumber`: number of the (first) output file. In case of
a snapshot sequence the output file number is incremented by one a single snapshot to be converted it makes sense to set this
from snapshot to snapshot. value equal to `_CC.datafile_number`. In case of a snapshot
sequence the output file number is incremented by 1 from
snapshot to snapshot.
- `03` (`_CC.precision`) - `03` (`_CC.precision`)
- `_CC.precision` (\[2,8\]): numerical precision of output data. - `_CC.precision` (\[2,8\]): numerical precision of output data.
In case of the CSV output format `_CC.precision` gives the In case of the CSV format `_CC.precision` gives the number of
number of decimal places of issued values. For all other formats decimal places. For all other formats output data is assumed of
output data is assumed of type `float` (`double`) if type `float` (`double`) if `_CC.precision`$\le 4$
`_CC.precision`≤4 (`_CC.precision`>4). (`_CC.precision`$>4$).
- `04` (`_CC.vars_files`) - `04` (`_CC.vars_files`)
- `_CC.vars_files` ({0,1}): option to enable/disable a separate - `_CC.vars_files` ({0,1}): writes separate output file for each
output file for each selected variable. selected variable if set to 1.
**MESH TRANSFORMER**: **MESH TRANSFORMER**:
...@@ -156,73 +145,72 @@ uniform grid. ...@@ -156,73 +145,72 @@ uniform grid.
06 0 >cell_centering:{0,1} 06 0 >cell_centering:{0,1}
07 0 >grid_overlap:{0,1} 07 0 >grid_overlap:{0,1}
08 1 1 >coord_transform:{0,1},vector_transform:{0,1} 08 1 1 >coord_transform:{0,1},vector_transform:{0,1}
09 1 1. >coord_local:{0,1},coord_unit 09 0 1. >coord_local:{0,1},coord_unit
- `01` (`_CC.max_level`) - `01` (`_CC.max_level`)
- `_CC.max_level`: maximum refinement level to be considerd in the - `_CC.max_level`: maximum refinement level to be taken into
conversion process. If an input mesh has a higher refinement account in the conversion. If an input mesh has a higher
level than the specified value `_CC.max_level` all higher levels refinement level than the specified value `_CC.max_level` all
are ignored. higher levels are rejected.
- `02` (`_CC.subrange[0]`, `_CC.rangemin[0]`,`_CC.rangmax[0]`) - `02` (`_CC.subrange[0]`, `_CC.rangemin[0]`,`_CC.rangmax[0]`)
- `_CC.subrange[0]` ({0,1}): option to select a subrange in - `_CC.subrange[0]` ({0,1}): selects a subdomain in $x$-direction
*x*-direction. A value 0 stands for the full *x*-range of the if set to 1. The range is given by the following parameters
computational domain. In this case the following parameters `_CC.rangemin[0]` and `_CC.rangemax[0]`.
`_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.rangemin[0]`: lower $x$-coordinate of subdomain.
- `_CC.rangemax[0]`: upper *x*-coordinate of subdomain. - `_CC.rangemax[0]`: upper $x$-coordinate of subdomain.
- `03` (`_CC.subrange[1]`, `_CC.rangemin[1]`,`_CC.rangmax[1]`) - `03` (`_CC.subrange[1]`, `_CC.rangemin[1]`,`_CC.rangmax[1]`)
- `_CC.subrange[1]` ({0,1}): same as `_CC.subrange[0]` but for the - `_CC.subrange[1]` ({0,1}): same as `_CC.subrange[0]` but for the
*y*-direction. $y$-direction.
- `_CC.rangemin[1]`: same as `_CC.rangemin[0]` but for the - `_CC.rangemin[1]`: same as `_CC.rangemin[0]` but for the
*y*-direction. In case of spherical geometry (*y*≡*θ*) the $y$-direction. In case of spherical geometry ($y\equiv\theta$)
value must be given in units of *π*. the value must be specified in units of $\pi$.
- `_CC.rangemax[1]`: same as `_CC.rangemax[0]` but for the - `_CC.rangemax[1]`: same as `_CC.rangemax[0]` but for the
*y*-direction. In case of spherical geometry (*y*≡*θ*) the $y$-direction. In case of spherical geometry ($y\equiv\theta$)
value must be given in units of *π*. the value must be specified in units of $\pi$.
- `04` (`_CC.subrange[2]`, `_CC.rangemin[2]`,`_CC.rangmax[2]`) - `04` (`_CC.subrange[2]`, `_CC.rangemin[2]`,`_CC.rangmax[2]`)
- `_CC.subrange[2]` ({0,1}): same as `_CC.subrange[0]` but for the - `_CC.subrange[2]` ({0,1}): same as `_CC.subrange[0]` but for the
*z*-direction. $z$-direction.
- `_CC.rangemin[2]`: same as `_CC.rangemin[0]` but for the - `_CC.rangemin[2]`: same as `_CC.rangemin[0]` but for the
*z*-direction. In case of cylindrical- or spherical geometry $z$-direction. In case of cylindrical- or spherical geometry
(*z*≡*ϕ*) the value must be given in units of *π*. ($z\equiv\phi$) the value must be specified in units of $\pi$.
- `_CC.rangemax[2]`: same as `_CC.rangemax[0]` but for the - `_CC.rangemax[2]`: same as `_CC.rangemax[0]` but for the
*z*-direction. In case of cylindrical- or spherical geometry $z$-direction. In case of cylindrical- or spherical geometry
(*z*≡*ϕ*) the value must be given in units of *π*. ($z\equiv\phi$) the value must be specified in units of $\pi$.
*Note: The values specified by `_CC.rangemin[]` and `_CC.rangemax[]` *Important: The values specified by `_CC.rangemin[]` and
are only (good) approximations to the actual determined output `_CC.rangemax[]` only determine the size of subdomain approximately.
domain size.* The actual size of output domain is fine-tuned by the algorithm.*
- `05` (`_CC.make_unigrid`) - `05` (`_CC.make_unigrid`)
- `_CC.make_unigrid` ({0,1}: option to transform the input mesh - `_CC.make_unigrid` ({0,1}: transforms the input mesh onto a
onto a uniform grid. A value 1 transforms an adaptive mesh onto uniform grid if set to 1. If the input mesh is an adaptive mesh
a finest-level uniform grid but limited by the parameter the uniform grid resolution corresponds to the finest refinement
`_CC.max_level`. If the input mesh is already an unigrid no level of the adaptive mesh but limited by the parameter
transformation takes place. `_CC.max_level`. No transformation takes place if the input mesh
is a uniform grid.
*Note: An unigrid created out of a highly refined input mesh may *Important: A uniform grid created out of a highly refined input
become too large to be represented in memory!* mesh may become too large in size to be represented in memory.*
- `06` (`_CC.cell_centering`) - `06` (`_CC.cell_centering`)
- `_CC.cell_centering` ({0,1}): option to output cell-centered - `_CC.cell_centering` ({0,1}): cell-centers variables in output
variables data. By default (value 0), variables in exported data if set to 1. By default (value 0), all exported variables
formats are node-centered. are node-centered.
- `07` (`_CC.grid_overlap`) - `07` (`_CC.grid_overlap`)
...@@ -230,20 +218,20 @@ uniform grid. ...@@ -230,20 +218,20 @@ uniform grid.
- `08` (`_CC.coord_transform`,`_CC.vector_transform`) - `08` (`_CC.coord_transform`,`_CC.vector_transform`)
- `_CC.coord_transform` ({0,1}): option to transform a - `_CC.coord_transform` ({0,1}): transforms a
cylindrical/spherical input mesh into a irregular (hexahedral) cylindrical/spherical input mesh into a hexahedral (in 3D)
Cartesian output mesh. By default (value 0), no transformation Cartesian output mesh if set to 1.
takes place.
- `_CC.vector_transform` ({0,1}): option to transform - `_CC.vector_transform` ({0,1,2,3,4}): transforms a
cylindrical/spherical vector components into Cartesian cylindrical/spherical vector into a Cartesian vector if set to
components. By default (value=0), vector components are not 1, respectively $>1$. If set to 2 (3,4) the first (second,third)
transformed. vector component of the input vector field is set to zero before
the transformation.
- `09` (`_CC.coord_local`,`_CC.coord_unit`) - `09` (`_CC.coord_local`,`_CC.coord_unit`)
- `_CC.coord_local` ({0,1}): option to shift the coordinate origin - `_CC.coord_local` ({0,1}): shifts the coordinate origin to the
to the middle of selected spatial domain. center of the (selected) spatial domain if set to 1.
- `_CC.coord_unit`: length scaling factor for coordinates. - `_CC.coord_unit`: length scaling factor for coordinates.
...@@ -264,81 +252,79 @@ uniform grid. ...@@ -264,81 +252,79 @@ uniform grid.
- `01` (`_CC.comp[0]`) - `01` (`_CC.comp[0]`)
- `_CC.comp[0]` ({0,1}): option to select the logarithm of mass - `_CC.comp[0]` ({0,1}): selects the logarithm of mass density,
density, log 𝜚, for conversion. $\log\varrho$, for output if set to 1.
- `02` (`_CC.comp[1]`) - `02` (`_CC.comp[1]`)
- `_CC.comp[1]` ({0,1}): option to select the gas velocity, **v**, - `_CC.comp[1]` ({0,1}): selects the gas velocity, $\mathbf{v}$,
for conversion. for output if set to 1.
- `03` (`_CC.comp[2]`) - `03` (`_CC.comp[2]`)
- `_CC.comp[2]` ({0,1}): option to select the logarithm of - `_CC.comp[2]` ({0,1}): selects the logarithm of pressure,
pressure, log *p*, for conversion. $\log p$, for output if set to 1.
- `04` (`_CC.comp[3]`) - `04` (`_CC.comp[3]`)
- `_CC.comp[3]` ({0,1}): option to select the logarithm of - `_CC.comp[3]` ({0,1}): selects the logarithm of temperature,
temperature, log *T*, for conversion. $\log T$, for output if set to 1.
- `05` (`_CC.comp[4]`, `_CC.species_min`,`_CC.species_max`) - `05` (`_CC.comp[4]`, `_CC.species_min`,`_CC.species_max`)
- `_CC.comp[4]` ({0,1}): option to select the logarithm of species - `_CC.comp[4]` ({0,1}): selects the logarithm of species number
number densities, log *n*<sub>*s*</sub>, for conversion. densities, $\log n_\ms$, for output if set to 1. Species
numbered `_CC.species_min` to `_CC.species_max` are considered.
- `_CC.species_min` (≥1): lower range value of species for - `_CC.species_min` ($\ge 1$): lower species index
conversion.
- `_CC.species_max` - `_CC.species_max` ($\ge\mathtt{\_CC.species\_min}$): upper
(≥`_CC.species_min`): upper range species index
value of species for conversion.
- `06` (`_CC.comp[5]`) - `06` (`_CC.comp[5]`)
- `_CC.comp[5]` ({0,1}): option to select tracer variables, - `_CC.comp[5]` ({0,1}): selects tracer variables, $C_\mc$, for
*C*<sub>*c*</sub>, for conversion. A value 1 selects all tracer output if set to 1. Selection of individual tracers is not
variables at the same time. possible.
- `07` (`_CC.comp[6]`) - `07` (`_CC.comp[6]`)
- `_CC.comp[6]` ({0,1}): option to select the gravitational - `_CC.comp[6]` ({0,1}): selects the gravitational potential,
potential, *Φ*, for conversion. $\Phi$, for output if set to 1.
- `08` (`_CC.comp[7]`) - `08` (`_CC.comp[7]`)
- `_CC.comp[7]` ({0,1}): option to select the magnetic field, - `_CC.comp[7]` ({0,1}): selects the magnetic field, $\mathbf{B}$,
**B**, for conversion. for output if set to 1.
- `09` (`_CC.comp[8]`) - `09` (`_CC.comp[8]`)
- `_CC.comp[8]` ({0,1}): option to select the logarithm of the - `_CC.comp[8]` ({0,1}): selects the logarithm of the electron
electron number density, log *n*<sub>*e*</sub>, for conversion. number density, $\log n_e$, for output if set to 1.
- `10` (`_CC.comp[9]`) - `10` (`_CC.comp[9]`)
- `_CC.comp[9]` ({0,1}): option to select the testfields - `_CC.comp[9]` ({0,1}): selects testfields fluctuations,
fluctuations, **b**<sub>*t*</sub>, for conversion. $\mathbf{b}_\mt$, for output if set to 1.
- `11` (`_CC.comp[10]`) - `11` (`_CC.comp[10]`)
- `_CC.comp[10]`: number of user-defined variables to select for - `_CC.comp[10]`: sets the number of user-defined variables for
conversion. A value 0 means that no user variable has been output. If set to 0 user variables are ignored.
defined.
### User-defined variables ### User-defined variables
The module `variablesUser.c` serves as template for the definition of The module `variablesUser.c` serves as template for the definition of
user variables to be converted into the specified output format. user variables with help of the function `variablesUser()`:
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); variablesUser(g,v,ivar);
The user must assign the `v`-array for the full `g`-index range and for Function arguments are a superblock pointer `g`, the array pointer `v`
each variable index `ivar`, whence code like of type `double***` representing a user variable and a variables index
`ivar`. The user must assign the `v`-array for the full `g`-index range
and for each variable indexed by `ivar`. Here is an example code
defining the kinetic energy density derived from the input density and
momentum as the first user variable:
switch(ivar) /* ONE CASE STATEMENT PER USER VARIABLE */ switch(ivar) /* ONE CASE STATEMENT PER USER VARIABLE */
{ {
...@@ -363,95 +349,81 @@ each variable index `ivar`, whence code like ...@@ -363,95 +349,81 @@ each variable index `ivar`, whence code like
. .
} }
must be added in `variablesUser.c`. The function is called by CAIVS for The variables index `ivar` may run from 1 to the requested number of
the variable index `ivar` running from 1 to `_CC.comp[10]` where the user variables selected for output by the parameter `_CC.comp[10]` in
parameter `_CC.comp[10]` stores the number of user variables as the parameter file `caivs.par`.
specified in the parameter file `caivs.par` under category VARIABLES.
The superblock `g` resembles a NIRVANA superblock except that it has
The superblock `g` represents a somewhat modified NIRVANA superblock only one ghost cell per coordinate direction side. Otherwise, like in
with a reduced number of one ghost cell per side per coordinate NIRVANA, `g` contains structural superblock information (grid dimension,
direction. `g` contains all the NIRVANA primary physical variables which spatial coordinates, etc.) as well as holds data arrays for the
were simulation-relevant plus additional thermodynamic variables. following physical variables:
Here is the list of possibly imported physical variables: `g->` variable
----------------------- ----------------------------------------------------------------------
| `g->` | variable | `rho[iz][iy][ix]` mass density $\varrho$
|:----------------------|:-----------------------------------------------------------------------------------------| `mx[iz][iy][ix]` $x$-momentum density $m_x$
| `rho[iz][iy][ix]` | mass density 𝜚 | `my[iz][iy][ix]` $y$-momentum density $m_y$
| `mx[iz][iy][ix]` | *x*-momentum density *m*<sub>*x*</sub> | `mz[iz][iy][ix]` (canonical) $z$-momentum density $m_z$
| `my[iz][iy][ix]` | *y*-momentum density *m*<sub>*y*</sub> | `e[iz][iy][ix]` total energy density $e$ (if energy equation)
| `mz[iz][iy][ix]` | (canonical) *z*-momentum density *m*<sub>*z*</sub> | `bx[iz][iy][ix]` magnetic field component $B_x$ (if MHD)
| `e[iz][iy][ix]` | total energy density *e* (if energy equation) | `by[iz][iy][ix]` magnetic field component $B_y$ (if MHD)
| `bx[iz][iy][ix]` | magnetic field component *B*<sub>*x*</sub> (if MHD) | `bz[iz][iy][ix]` magnetic field component $B_z$ (if MHD)
| `by[iz][iy][ix]` | magnetic field component *B*<sub>*y*</sub> (if MHD) | `phi[iz][iy][ix]` gravitational potential $\Phi$ (if selfgravity)
| `bz[iz][iy][ix]` | magnetic field component *B*<sub>*z*</sub> (if MHD) | `nX[is][iz][iy][ix]` species number densities $n_\ms$ (if species)
| `phi[iz][iy][ix]` | gravitational potential *Φ* (if selfgravity) | `C[ic][iz][iy][ix]` tracer variables $C_\mc$ (if tracer)
| `nX[is][iz][iy][ix]` | species number densities *n*<sub>*s*</sub> (if species) | `tfx[it][iz][iy][ix]` $x$-component ${b_x}_\mt$ of testfields fluctuations (if testfields)
| `C[ic][iz][iy][ix]` | tracer variables *C*<sub>*c*</sub> (if tracer) | `tfy[it][iz][iy][ix]` $y$-component ${b_y}_\mt$ of testfields fluctuations (if testfields)
| `tfx[it][iz][iy][ix]` | *x*-component *b*<sub>*x*</sub><sub>*t*</sub> of testfields fluctuations (if testfields) | `tfz[it][iz][iy][ix]` $z$-component ${b_z}_\mt$ of testfields fluctuations (if testfields)
| `tfy[it][iz][iy][ix]` | *y*-component *b*<sub>*y*</sub><sub>*t*</sub> of testfields fluctuations (if testfields) | `p[iz][iy][ix]` thermal pressure $p$
| `tfz[it][iz][iy][ix]` | *z*-component *b*<sub>*z*</sub><sub>*t*</sub> of testfields fluctuations (if testfields) | `T[iz][iy][ix]` temperature $T$
| `p[iz][iy][ix]` | thermal pressure *p* | `et[iz][iy][ix]` thermal energy density $\varepsilon$ (if dual energy mode)
| `T[iz][iy][ix]` | temperature *T* | `ne[iz][iy][ix]` electron number density $n_e$
| `et[iz][iy][ix]` | thermal energy density *ε* (if dual energy mode) |
| `ne[iz][iy][ix]` | electron number density *n*<sub>*e*</sub> | index meaning range
------- ----------------------------------- ------------------------
The array indices have the meaning and ranges as cataloged in the `ix` superblock-index in $x$-direction 0\...`g->nx`
following table `iy` superblock-index in $y$-direction 0\...`g->ny`
`iz` superblock-index in $z$-direction 0\...`g->nz`
| index | meaning | range | `is` species counter 0\...`_C.species`-1
|:------|:----------------------------------------|:----------------------| `ic` tracers counter 0\...`_C.tracer`-1
| `ix` | `g`-index in *x*-direction | 0...`g->nx` | `it` testfield fluctuations counter 0\...`_C.testfields`-1
| `iy` | `g`-index in *y*-direction | 0...`g->ny` |
| `iz` | `g`-index in *z*-direction | 0...`g->nz` | `_C.species`, `_C.tracer` and `_C.testfields` are NIRVANA parameters
| `is` | species counter | 0...`_C.species`-1 | (cf. [NIRVANA: Specification of main
| `ic` | tracers counter | 0...`_C.tracer`-1 | parameters](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/3-NIRVANA-user-guide/3.2-User-interfaces#specification-of-main-simulation-parameters))
| `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 simulation parameters](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/3-NIRVANA-user-guide/3.2-User-interfaces#specification-of-main-simulation-parameters))
storing the number of species, number of tracers and number of storing the number of species, number of tracers and number of
testfields, respectively. testfields, respectively.
*Note 1: The magnetic field components and testfields fluctuations Note that the imported variables share the same grid cell centering as
components are represented at cell-face-centroid coordinates whereas all in NIRVANA, i.e, the magnetic field components and testfields
other variables listed in the table are given at cell-centroid positions fluctuations components are face-centered whereas all other variables
(cf. [NIRVANA: Mesh data listed in the table above are cell-centroid (cf. [NIRVANA: Mesh data
structure](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/3-NIRVANA-user-guide/3.1-Code-basics#mesh-data-structure))* structure](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/3-NIRVANA-user-guide/3.1-Code-basics#mesh-data-structure))
The imported variables can be used to derive user variables as in the *Important: If user variables involve derivatives of input variables,
`case 1:` example above. CAIVS assumes that user variables are e.g. the flow vorticiy $\nabla\times (\mathbf{m}/\varrho)$, one-sided
cell-averaged quantities, i.e., that it are represented at cell-centroid discretization formulae or extrapolation techniques may be needed to
coordinates like the mass density, for instance. accurately compute derivatives at `g`-boundaries.*
*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.*
### Modification of input data ### Modification of input data
The module `modifyDataUser.c` serves as template for a user-controlled The module `modifyDataUser.c` serves as template for a user-controlled
modification of input data before it is exported to one of the CAIVS output modification of input data before before conversion. This is done by
data formats. The function is only called when parameter `_CC.data_modify` coding the function
is set to 1 in the user interface
[caivs.par](4.2-User-interfaces#specification-of-parameters).
In the call of `modifyDataUser()` the function argument is a superblock
pointer `g`:
modifyDataUser(g); modifyDataUser(g);
For comments on `g` and the list of available physical variables which has a superblock pointer `g` as argument. This function is called
see the previous paragragh when parameter `_CC.data_modify` has been set to 1 (cf. [Specification
[User-defined variables](4.2-User-interfaces#user-defined-variables). of parameters](#specification-of-parameters)).
To give an example, the following code fragment adds a background dipole magnetic field Here is an example code fragment which adds a background dipole magnetic
(taken from NIRVANA testproblem `MHD/problem30`) field (taken from NIRVANA testproblem MHD/problem30) to the imported
to the imported magnetic field: magnetic field:
int ix,iy,iz; int ix,iy,iz;
double B0eq,rE,r,r2,r3; double B0eq,rE,r,r2,r3;
/* MAGNETIC FIELD INCREASED BY BACKGROUND MAGNETIC FIELD TO VISUALIZE THE /* MAGNETIC FIELD INCREASED BY BACKGROUND MAGNETIC FIELD TO VISUALIZE THE
...@@ -483,6 +455,14 @@ to the imported magnetic field: ...@@ -483,6 +455,14 @@ to the imported magnetic field:
g->by[iz][iy][ix]+=B0eq*r3*(3.*g->zc[iy]/r2*g->y[iy]); g->by[iz][iy][ix]+=B0eq*r3*(3.*g->zc[iy]/r2*g->y[iy]);
} }
&nbsp; /* ADD B0 Z-COMPONENT */
for(iz=0; iz<=g->nz; iz++)
for(iy=0; iy<=g->ny; iy++)
for(ix=0; ix<=g->nx; ix++)
{
r2=g->xc[ix]*g->xc[ix]+g->yc[iy]*g->yc[iy]+g->z[iz]*g->z[iz];
r=sqrt(r2);
r3=pow(rE/r,3.);
PREV: [4.1 Purpose](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/4-CAIVS-user-guide/4.1-Purpose) &nbsp; &nbsp; &nbsp; NEXT: [4.3 Log file](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/4-CAIVS-user-guide/4.3-Log-file) g->bz[iz][iy][ix]+=B0eq*r3*(3.*g->z[iz]*g->z[iz]/r2-1);
}