Changes

Page history
version 4.2 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 @ f7e3cede
![logo_short_small](uploads/1e4ee858ca174663b210647640da0976/logo_short_small.png) `4.1`
## User interfaces
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
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
The parameter file `caivs.par` controlls how NIRVANA input data is
converted into CAIVS output data. Parameters are categorized into the 4
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
`>`-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
A parameter section in `caivs.par` starts with its category name
preceded by the `>`-character. Parameters follow in lines where each
line may contain more than one parameter. Parameters in a line are
separated by white spaces. Parameters can be numbers, single characters
or words. The `>`-character hereafter and following text serve as
comments and is ignored by the file parser.
>DATA INPUT --------------------------------------------------------------------
/work2/ziegler/viz/ >data_dir
0001471 000000 >datafile_{number,sequence}
0 >data_modify:{0,1}
There are 3 parameter lines here containing, from top to bottom, 1 parameter
(`/work2/ziegler/viz/`), 2 parameters (`0001471` and `000000`) and
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.
All parameters are described in detail in the following. On referencing
purposes parameter lines are marked here with a 2-digit running number.
Actually, lines are not numbered in `caivs.par`. Parameter names are in
round brackets after the line number. Most parameters are subsumed 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.data_dir`. For some parameters their valid range of values are
given either in form of a set {} of possible values or a numeric range.
**DATA INPUT**:
......@@ -67,37 +55,36 @@ uniform grid.
- `01` (`_CC.data_dir`)
- `_CC.data_dir`: directory of input data (where NIRVANA snapshot
files reside).
- `_CC.data_dir`: directory of input data
- `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
- `_CC.datafile_number`: timestep number (NIRVANA parameter:
`_C.mod`) in the filename of the NIRVANA snapshot. 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](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
containers of a snapshot. The user just has to take care that
all snapshot files belonging to a snapshot lie in the input
directory.*
*Note: A NIRVANA snapshot may be distributed among several
container files (the post-dot-`#` in `NIR#.#` is the container
number). This is automatically recognises by CAIVS but the user
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
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`.
- `_CC.datafile_sequence`: cycle number for a snapshot sequence.
If this parameter is chosen non-zero, CAIVS converts a sequence
of snapshots with timestep numbers successively increased by
value `_CC.datafile_sequence` starting with
`_CC.datafile_number`. The sequence stops if filenames are not
existing.
- `03` (`_CC.data_modify`)
- `_CC.data_modify` ({0,1}): option to allow a modification of
NIRVANA input data. If set to 1, the user interface
[modifyDataUser.c](4.2-User-interfaces#modification-of-input-data)
is called prior to data export which permits to manipulate physical
- `_CC.data_modify` ({0,1}): allows a modification of NIRVANA
input data if set to 1. The user interface
[`modifyDataUser.c`](#modification-of-input-data). is called
prior to data export which permits to manipulate physical
variables.
**DATA EXPORT**:
......@@ -110,13 +97,13 @@ uniform grid.
- `01` (`_CC.export_dir`)
- `_CC.export_dir`: directory of output data. Usually, this is the
same as the directory for the input data.
- `_CC.export_dir`: directory of output data. Can be set the same
as the input data directory.
- `02` (`_CC.format`, `_CC.filenumber`)
- `_CC.format` ({NIR,SILO,CSV,HDF,RAW}): output data format. Possible
values are
- `_CC.format` ({NIR,SILO,CSV,HDF,RAW}): output data format.
Possible values are
- NIR: CAIVS native format
......@@ -129,21 +116,23 @@ uniform grid.
- RAW: raw arrays 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.
a single snapshot to be converted it makes sense to set this
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`)
- `_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).
In case of the CSV format `_CC.precision` gives the number of
decimal places. For all other formats output data is assumed of
type `float` (`double`) if `_CC.precision`$\le 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.
- `_CC.vars_files` ({0,1}): writes separate output file for each
selected variable if set to 1.
**MESH TRANSFORMER**:
......@@ -156,73 +145,72 @@ uniform grid.
06 0 >cell_centering:{0,1}
07 0 >grid_overlap:{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`)
- `_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.
- `_CC.max_level`: maximum refinement level to be taken into
account in the conversion. If an input mesh has a higher
refinement level than the specified value `_CC.max_level` all
higher levels are rejected.
- `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.subrange[0]` ({0,1}): selects a subdomain in $x$-direction
if set to 1. The range is given by the following parameters
`_CC.rangemin[0]` and `_CC.rangemax[0]`.
- `_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]`)
- `_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
*y*-direction. In case of spherical geometry (*y*≡*θ*) the
value must be given in units of *π*.
$y$-direction. In case of spherical geometry ($y\equiv\theta$)
the value must be specified in units of $\pi$.
- `_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 *π*.
$y$-direction. In case of spherical geometry ($y\equiv\theta$)
the value must be specified in units of $\pi$.
- `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.
$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 *π*.
$z$-direction. In case of cylindrical- or spherical geometry
($z\equiv\phi$) the value must be specified in units of $\pi$.
- `_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 *π*.
$z$-direction. In case of cylindrical- or spherical geometry
($z\equiv\phi$) the value must be specified in units of $\pi$.
*Note: The values specified by `_CC.rangemin[]` and `_CC.rangemax[]`
are only (good) approximations to the actual determined output
domain size.*
*Important: The values specified by `_CC.rangemin[]` and
`_CC.rangemax[]` only determine the size of subdomain approximately.
The actual size of output domain is fine-tuned by the algorithm.*
- `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.
- `_CC.make_unigrid` ({0,1}: transforms the input mesh onto a
uniform grid if set to 1. If the input mesh is an adaptive mesh
the uniform grid resolution corresponds to the finest refinement
level of the adaptive mesh but limited by the parameter
`_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
become too large to be represented in memory!*
*Important: A uniform grid created out of a highly refined input
mesh may become too large in size 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.
- `_CC.cell_centering` ({0,1}): cell-centers variables in output
data if set to 1. By default (value 0), all exported variables
are node-centered.
- `07` (`_CC.grid_overlap`)
......@@ -230,20 +218,20 @@ uniform grid.
- `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.coord_transform` ({0,1}): transforms a
cylindrical/spherical input mesh into a hexahedral (in 3D)
Cartesian output mesh if set to 1.
- `_CC.vector_transform` ({0,1}): option to transform
cylindrical/spherical vector components into Cartesian
components. By default (value=0), vector components are not
transformed.
- `_CC.vector_transform` ({0,1,2,3,4}): transforms a
cylindrical/spherical vector into a Cartesian vector if set to
1, respectively $>1$. If set to 2 (3,4) the first (second,third)
vector component of the input vector field is set to zero before
the transformation.
- `09` (`_CC.coord_local`,`_CC.coord_unit`)
- `_CC.coord_local` ({0,1}): option to shift the coordinate origin
to the middle of selected spatial domain.
- `_CC.coord_local` ({0,1}): shifts the coordinate origin to the
center of the (selected) spatial domain if set to 1.
- `_CC.coord_unit`: length scaling factor for coordinates.
......@@ -264,81 +252,79 @@ uniform grid.
- `01` (`_CC.comp[0]`)
- `_CC.comp[0]` ({0,1}): option to select the logarithm of mass
density, log 𝜚, for conversion.
- `_CC.comp[0]` ({0,1}): selects the logarithm of mass density,
$\log\varrho$, for output if set to 1.
- `02` (`_CC.comp[1]`)
- `_CC.comp[1]` ({0,1}): option to select the gas velocity, **v**,
for conversion.
- `_CC.comp[1]` ({0,1}): selects the gas velocity, $\mathbf{v}$,
for output if set to 1.
- `03` (`_CC.comp[2]`)
- `_CC.comp[2]` ({0,1}): option to select the logarithm of
pressure, log *p*, for conversion.
- `_CC.comp[2]` ({0,1}): selects the logarithm of pressure,
$\log p$, for output if set to 1.
- `04` (`_CC.comp[3]`)
- `_CC.comp[3]` ({0,1}): option to select the logarithm of
temperature, log *T*, for conversion.
- `_CC.comp[3]` ({0,1}): selects the logarithm of temperature,
$\log T$, for output if set to 1.
- `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.comp[4]` ({0,1}): selects the logarithm of species number
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
conversion.
- `_CC.species_min` ($\ge 1$): lower species index
- `_CC.species_max`
(≥`_CC.species_min`): upper range
value of species for conversion.
- `_CC.species_max` ($\ge\mathtt{\_CC.species\_min}$): upper
species index
- `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.
- `_CC.comp[5]` ({0,1}): selects tracer variables, $C_\mc$, for
output if set to 1. Selection of individual tracers is not
possible.
- `07` (`_CC.comp[6]`)
- `_CC.comp[6]` ({0,1}): option to select the gravitational
potential, *Φ*, for conversion.
- `_CC.comp[6]` ({0,1}): selects the gravitational potential,
$\Phi$, for output if set to 1.
- `08` (`_CC.comp[7]`)
- `_CC.comp[7]` ({0,1}): option to select the magnetic field,
**B**, for conversion.
- `_CC.comp[7]` ({0,1}): selects the magnetic field, $\mathbf{B}$,
for output if set to 1.
- `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.
- `_CC.comp[8]` ({0,1}): selects the logarithm of the electron
number density, $\log n_e$, for output if set to 1.
- `10` (`_CC.comp[9]`)
- `_CC.comp[9]` ({0,1}): option to select the testfields
fluctuations, **b**<sub>*t*</sub>, for conversion.
- `_CC.comp[9]` ({0,1}): selects testfields fluctuations,
$\mathbf{b}_\mt$, for output if set to 1.
- `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.
- `_CC.comp[10]`: sets the number of user-defined variables for
output. If set to 0 user variables are ignored.
### 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`:
user variables with help of the function `variablesUser()`:
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
Function arguments are a superblock pointer `g`, the array pointer `v`
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 */
{
......@@ -363,92 +349,78 @@ each variable index `ivar`, whence code like
.
}
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 simulation parameters](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/3-NIRVANA-user-guide/3.2-User-interfaces#specification-of-main-simulation-parameters))
The variables index `ivar` may run from 1 to the requested number of
user variables selected for output by the parameter `_CC.comp[10]` in
the parameter file `caivs.par`.
The superblock `g` resembles a NIRVANA superblock except that it has
only one ghost cell per coordinate direction side. Otherwise, like in
NIRVANA, `g` contains structural superblock information (grid dimension,
spatial coordinates, etc.) as well as holds data arrays for the
following physical variables:
`g->` variable
----------------------- ----------------------------------------------------------------------
`rho[iz][iy][ix]` mass density $\varrho$
`mx[iz][iy][ix]` $x$-momentum density $m_x$
`my[iz][iy][ix]` $y$-momentum density $m_y$
`mz[iz][iy][ix]` (canonical) $z$-momentum density $m_z$
`e[iz][iy][ix]` total energy density $e$ (if energy equation)
`bx[iz][iy][ix]` magnetic field component $B_x$ (if MHD)
`by[iz][iy][ix]` magnetic field component $B_y$ (if MHD)
`bz[iz][iy][ix]` magnetic field component $B_z$ (if MHD)
`phi[iz][iy][ix]` gravitational potential $\Phi$ (if selfgravity)
`nX[is][iz][iy][ix]` species number densities $n_\ms$ (if species)
`C[ic][iz][iy][ix]` tracer variables $C_\mc$ (if tracer)
`tfx[it][iz][iy][ix]` $x$-component ${b_x}_\mt$ of testfields fluctuations (if testfields)
`tfy[it][iz][iy][ix]` $y$-component ${b_y}_\mt$ of testfields fluctuations (if testfields)
`tfz[it][iz][iy][ix]` $z$-component ${b_z}_\mt$ 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 $\varepsilon$ (if dual energy mode)
`ne[iz][iy][ix]` electron number density $n_e$
index meaning range
------- ----------------------------------- ------------------------
`ix` superblock-index in $x$-direction 0\...`g->nx`
`iy` superblock-index in $y$-direction 0\...`g->ny`
`iz` superblock-index in $z$-direction 0\...`g->nz`
`is` species counter 0\...`_C.species`-1
`ic` tracers counter 0\...`_C.tracer`-1
`it` testfield fluctuations counter 0\...`_C.testfields`-1
`_C.species`, `_C.tracer` and `_C.testfields` are NIRVANA parameters
(cf. [NIRVANA: Specification of main
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
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](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
`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 that the imported variables share the same grid cell centering as
in NIRVANA, i.e, the magnetic field components and testfields
fluctuations components are face-centered whereas all other variables
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))
*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.*
*Important: If user variables involve derivatives of input variables,
e.g. the flow vorticiy $\nabla\times (\mathbf{m}/\varrho)$, one-sided
discretization formulae or extrapolation techniques may be needed to
accurately compute derivatives at `g`-boundaries.*
### Modification of input data
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
data formats. The function is only called when parameter `_CC.data_modify`
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`:
modification of input data before before conversion. This is done by
coding the function
modifyDataUser(g);
For comments on `g` and the list of available physical variables
see the previous paragragh
[User-defined variables](4.2-User-interfaces#user-defined-variables).
which has a superblock pointer `g` as argument. This function is called
when parameter `_CC.data_modify` has been set to 1 (cf. [Specification
of parameters](#specification-of-parameters)).
To give an example, the following code fragment adds a background dipole magnetic field
(taken from NIRVANA testproblem `MHD/problem30`)
to the imported magnetic field:
Here is an example code fragment which adds a background dipole magnetic
field (taken from NIRVANA testproblem MHD/problem30) to the imported
magnetic field:
int ix,iy,iz;
double B0eq,rE,r,r2,r3;
......@@ -483,6 +455,14 @@ to the imported magnetic field:
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);
}