Changes

Page history
Update 3.2 User interfaces authored by Udo Ziegler's avatar Udo Ziegler
Show whitespace changes
Inline Side-by-side
3-NIRVANA-user-guide/3.2-User-interfaces.md
View page @ a0540aaa
![logo_short_small](uploads/1e4ee858ca174663b210647640da0976/logo_short_small.png) `4` ![logo_short_small](uploads/1e4ee858ca174663b210647640da0976/logo_short_small.png) `4`
CONTENTS
[Overview](3.2-User-interfaces#overview)
[Specification of main simulation parameters](3.2-User-interfaces#specification-of-main-simulation-parameters)
[Defining initial conditions](3.2-User-interfaces#defining-initial-conditions)
[Defining boundary conditions](3.2-User-interfaces#defining-boundary-conditions)
[User-defined coefficients for dissipative processes](3.2-User-interfaces#user-defined-coefficients-for-dissipative-processes)
[User-defined coefficient for ambipolar diffusion](3.2-User-interfaces#user-defined-coefficient-for-ambipolar-diffusion)
[User-defined body force](3.2-User-interfaces#user-defined-body-force)
[User-defined cooling/heating function](3.2-User-interfaces#user-defined-cooling/heating-function)
[User-defined equation of state](3.2-User-interfaces#user-defined-equation-of-state)
[User-defined initial/restricted mesh refinement](3.2-User-interfaces#user-defined-initial/restricted-mesh-refinement)
[Specification of NCCM parameters](3.2-User-interfaces#specification-of-NCCM-parameters)
[User-controllable macros](3.2-User-interfaces#user-controllable-macros)
### Overview
User interfaces are certain code modules in order to generate and
customize a simulation problem. There are three different types of user
interfaces in NIRVANA:
\(1\) User interfaces which demand to add or modify code. These are
recognized by C files ending on `User.c`:
- `configUser.c` – definition of IC
- `bcrhoUser.c`,`bcmUser.c`,`bceUser.c`,`bcetUser.c`,
`bcbUser.c`,`bcnXUser.c`,`bcCUser.c`,`bctfUser.c` – user-defined BC
- `viscosityCoeffUser.c`,`conductionCoeffUser.c`,`diffusionCoeffUser.c`
– user-defined dissipation coefficients for fluid viscosity, thermal
conduction and magnetic diffusion
- `APdiffusionCoeffUser.c` – user-defined coefficient for ambipolar
diffusion
- `forceUser.c` – user-defined body force
- `sourceCoolingUser.c`,`sourceHeatingUser.c` – user-defined
cooling/heating function
- `eosTabPressureUser.c`,`eosTabTemperatureUser.c` – user-defined
pressure and temperature for a tabulated equation of state
- `initDomainUser.c`,`checkDomainUser.c` – user-defined initial- and
restricted mesh refinement
Defining interfaces requires some familiarity with NIRVANA and, in
particular, a basic understanding of its data structure. The defintion
of IC in `configUser.c` is the minimum necessary for a problem setup.
Sample `...User.c` files can be found in the various testproblems
subdirectories under top-level `/nirvana/testproblems`.
\(2\) User parameter files (suffix `.par`) which demand editing in order
to configure simulation properties:
- `nirvana.par` – specification of main simulation parameters
- `NCCM.par` – specification of NCCM parameters
Configuration of the main parameter file `nirvana.par` is the minimum
necessary for a problem setup.
\(3\) User header files ending on `User.h`:
- `nirvanaUser.h` – header file containing macros for
user-controllable, secondary simulation parameters
- `User.h` – freely available header file
### Specification of main simulation parameters
NIRVANA requires the parameter file `nirvana.par` as input. In this file
the user specifies main parameters which characterize the properties of
a simulation. Within `nirvana.par` parameters are grouped into blocks
with category names
- `SIMULATION I/O` – I/O-related parameter
- `GEOMETRY` – selection of the coordinate system
- `DOMAIN SETTINGS` – physical/numerical domain specifications
- `BOUNDARY CONDITIONS` – selection of boundary conditions
- `MESH REFINEMENT` – AMR-related parameters
- `USER-SPECIFIC PARAMETERS` – freely usuable parameter
- `SOLVER SPECIFICATIONS` – selection of solver options
- `PHYSICS SPECIFICATIONS` – selection of physics options
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. Text following
the `>`-character is ignored by the parser and serves for comments. For
example, the GEOMETRY section in `nirvana.par` looks like
>GEOMETRY ----------------------------------------------------------------------
CART 0.00e+00 0.00e+00 0.00e+00 >geometry:{CART,CYL,SPH},omega[0-2]
There is just one parameter line here containing 4 parameters: the first
specifies the type of coordinate system being `CART` for Cartesian and
the remaining three parameters give the vector components (doubles) of
the angular velocity vector of a rotating frame of reference with
respect to the inertial frame. It follows a comment after `>`.
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 `nirvana.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 `_C` defined in the header `nirvana.h`. A certain
variable `V` in `_C` is then addressed by `_C.V`, e.g., `_C.geometry`
for the type of coordinate system.
`SIMULATION I/O`:
>SIMULATION I/O ----------------------------------------------------------------
01 NEW ./MODLAST >mode:{NEW,RES,MOD,ANA},fname
02 100020 3.00e+00 >mod_max,time_max
03 0020 0200 91005 3.60e+03 >freq_{log,nir,ana},freq_walltime
- `01` (`mode`, `fname`)
- `mode` ({NEW,RES,MOD,ANA}): running mode of a simulation. Value
NEW starts a new simulation. Value RES restarts a simulation
from a snapshot with name specified by the parameter `fname`.
Value MOD is like RES but, in addition, allows a modification of
read-in simulation data by calling the user interface function
`modifyConfigUser()` before the simulation continues. Value ANA
reads data from a snapshot followed by a call of the user
interface function `analysisUser()` and exits thereafter. The
ANA mode is intended for a one-time user-specific analysis of
the snapshot data with full availability of all code
functionalities. In the modes RES, MOD and ANA all parameters
following `fname` in `nirvana.par` are ignored.
- `fname`: qualified name of the snapshot. The qualified name here
is the path relative to the `NIRVANA_RUN` directory as set in
the `runNIRVANA` (or `runNIRVANA_MPI.PBS`) script plus the
*base* container filename of the snapshot. The base container
filename is `NIR#` or `NIRLAST#` with `#`=`_C.model` but
excluding the dot and post-dot container id (cf.
\[here\](3.3-Output-data\#snapshot-files)).
- `02` (`_C.mod_max`, `_C.time_max`)
- `_C.mod_max`: maximum number of timestep cycles a simulation
should run. If the physical evolution time reaches the value
`_C.time_max` before `_C.mod_max` cycles are done the simulation
stops ahead of schedule.
- `_C.time_max`: maximum physical evolution time a simulation
should run. If `_C.mod_max` cycles are done before the physical
evolution time `_C.time_max` is reached the simulation stops
ahead of schedule.
- `03` (`_C.freq_log`, `_C.freq_nir`, `_C.freq_ana`,
`_C.freq_walltime`)
- `_C.freq_log`: interval in units of timestep cycles at which the
NIRVANA log file `nirvana.log` (cf.
\[here\](3.3-Output-data\#log-file)) and monitoring file
`nirvana.mon` (cf. \[here\](3.3-Output-data\#monitoring-file))
is updated.
- `_C.freq_nir`: interval in units of timestep cycles at which
NIRVANA snapshots (cf.
\[here\](3.3-Output-data\#snapshot-files)) are produced.
- `_C.freq_ana`: interval in units of timestep cycles at which the
user interface function `analysisUser()` is called for
user-specific analysis tasks (cf.
\[here\](3.5-Data-analysis\#runtime-data-analysis)).
- `_C.freq_walltime`: interval in seconds at which the special
snapshot `NIRLAST.#` (cf.
\[here\](3.3-Output-data\#snapshot-files)) is renewed
overwriting existing older files.
`GEOMETRY`:
>GEOMETRY ----------------------------------------------------------------------
01 CART 0.00e+00 0.00e+00 0.00e+00 >geometry,omega[0-2]
- `01` (`_C.geometry`, `_C.omega[0-2]`)
- `_C.geometry` ({CART,CYL,SPH}): choice of coordinate system
where CART=Cartesian, CYL=cylindrical and SPH=spherical.
- `_C.omega[0-2]`: components of the angular velocity vector of a
rotating frame of reference with respect to the inertial frame
(cf. physics guide
[Wiki](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/A-PhysicsGuide),
[PDF](https://gitlab.aip.de/ziegler/NIRVANA/doc/pdf/PhysicsGuide.pdf)).
In case of cylindrical- or spherical geometry only the first
component `_C.omega[0]` is accepted as relevant representing
rotation around the geometric axis.
`DOMAIN SETTINGS`:
>DOMAIN SETTINGS ---------------------------------------------------------------
01 0.000000e+00 6.280000e+00 0160 >lo[0],up[0],dim[0]
02 0.000000e+00 6.280000e+00 0160 >lo[1],up[1],dim[1]
03 0.000000e+00 1.000000e+00 0000 >lo[2],up[2],dim[2]
04 BLOCK 2 2 4 >partitioning_type:{SFC,BLOCK # # #}
- `01` (`_C.lo[0]`, `_C.up[0]`, `_C.dim[0]`)
- `_C.lo[0]`,\_C.up\[0\]: lower,upper *x*-coordinate of the
computational domain.
- `_C.dim[0]`: number of *base-level* grid points in
*x*-direction. `_C.dim[0]` must be an integral factor of 4 and
excludes ghost cells (which are automatically added).
- `02` (`_C.lo[1]`, `_C.up[1]`, `_C.dim[1]`)
- `_C.lo[1]`,`_C.up[1]`: lower,upper *y*-coordinate of the
computational domain. In case of spherical geometry (*y* ≡ *θ*)
`_C.lo[1]`,`_C.up[1]` have to be specified in units of *π*.
- `_C.dim[1]`: number of *base-level* grid points in
*y*-direction. `_C.dim[1]` must be a multiple factor of 4 and
excludes ghost cells (which are automatically added).
- `03` (`_C.lo[2]`, `_C.up[2]`, `_C.dim[2]`)
- `_C.lo[2]`,`_C.up[2]`: lower,upper *z*-coordinate of the
computational domain. In case of cylindrical- or spherical
geometry (*z* ≡ *ϕ*) `_C.lo[2]`,`_C.up[2]` have to be specified
in units of *π*.
- `_C.dim[2]`: number of *base-level* grid points in
*z*-direction. `_C.dim[2]` must be a multiple factor of 4 and
excludes ghost cells (which are automatically added). If
`_C.dim[2]`=0 the simulation is assumed 2D (e.g. axisymmetric in
case of cylindrical- or spherical coordinates).
- `04` (`_C.partitioning_type`, `_C.bnx`, `_C.bny`, `_C.bnz`)
- `_C.partitioning_type` ({SFC,BLOCK}): mesh partitioning type for
MPI simulations. The value SFC stands for a Space-Filling-Curve
domain decomposition and the value BLOCK for a rectangular
domain decomposition. Both decomposition types work for unigrid
simulations. For AMR simulations a specified value BLOCK is
ignored and a SFC-decomposition is automatically applied.
- `_C.bnx`,`_C.bny`,`_C.bnz`: number of domain subdivisions in
*x*, *y*, *z*-direction in case \_C.partitioning\_type=BLOCK.
Numbers must be chosen such that the grid dimension of
subdomains is a multiple factor of 4 in each coordinate
direction. Moreover, the total number of subdomains must equal
the number of MPI threads, i.e.
`_C.bnx`×`_C.bny`×`_C.bnz`=number of MPI threads.
<span id="PAR" label="PAR">\[PAR\]</span> `BOUNDARY CONDITIONS`:
>BOUNDARY CONDITIONS -----------------------------------------------------------
01 PPPPPP >bc[0-5]:{I,O,A,M,R,C,P,D,F,U}
- `01` (`_C.bc[0-5]`)
- `_C.bc[0-5]` ({I,O,A,M,R,C,P,D,F,U}): selection of boundary
conditions. The type of boundary condition at a physical domain
boundary is characterized by a single uppercase. Uppercases for
the domain boundaries are grouped in a 6-letters word with the
individual letters representing, from left to right, the
lower-*x* (`_C.bc[0]`), upper-*x* (`_C.bc[1]`), lower-*y*
(`_C.bc[2]`), upper-*y* (`_C.bc[3]`), lower-*z* (`_C.bc[4]`) and
upper-*z* (`_C.bc[5]`) domain boundary. Possible boundary
condition types are (*u*<sub>*i*/*o*</sub>: inner/outer-domain
boundary values of a variable *u*):
- `I`: inflow – fluid is allowed to flow inwards through the
corresponding domain boundary but not to flow outwards. This
means for the perpendicular velocity component
*u*<sub>*o*</sub> = ± sgn *u*<sub>*i*</sub> ⋅ *u*<sub>*i*</sub>
where the ’+’(’-’)-sign stands for a lower (upper) domain
boundary. Zero derivative,
*u*<sub>*o*</sub> = *u*<sub>*i*</sub>, is assumed for other
cell-centroid quantities except the total energy density.
The total energy density is set consistently under the
assumption of a zero derivative for the thermal energy
density. Zero derivative is assumed for the parallel
components of the magnetic field and the perpendicular
magnetic field component is obtained by a divergence-free
extrapolation.
- `O`: outflow – fluid is allowed to flow outwards through the
corresponding domain boundary but not to flow inwards. This
means for the perpendicular velocity component
*u*<sub>*o*</sub> = ∓ sgn *u*<sub>*i*</sub> ⋅ *u*<sub>*i*</sub>
where the ’+’(’-’)-sign stands for a lower (upper) domain
boundary. Other variables are likewise to I.
- `M`: mirror symmetry – reflecting conditions,
*u*<sub>*o*</sub> = − *u*<sub>*i*</sub>, for the
perpendicular components of velocity and magnetic field and
zero derivative for the other variables.
- `A`: antimirror symmetry – same as M for non-magnetic
variables. The magnetic field is forced to have dipole
parity with respect to the domain boundary. This means
*u*<sub>*o*</sub> = − *u*<sub>*i*</sub> for the parallel
magnetic field components and
*u*<sub>*o*</sub> = *u*<sub>*i*</sub> for the perpendicular
magnetic field component.
- `R`: reflection-on-axis (only of relevance in cylindrical
geometry for `_C.bc[2]` and in spherical geometry for
`_C.bc[2]`,`_C.bc[3]`) – reflecting conditions at the
geometric axis. Same as M except for the azimutal magnetic
field component for which
*u*<sub>*o*</sub> = − *u*<sub>*i*</sub>.
- `C`: reflection-at-center (only of relevance in spherical
geometry for `_C.bc[0]`) – reflecting conditions at the
coordinate origin. Same as M except for the non-radial
magnetic field components for which
*u*<sub>*o*</sub> = − *u*<sub>*i*</sub>.
- `P`: periodicity – periodic conditions for all variables.
- `D`: default – zero derivative in the non-magnetic variables
and perpendicular-to-boundary condition (pseudo-vacuum
condition) for the magnetic field.
- `F`: free boundary (for cylindrical/spherical geometry
including the geometric axis) – ’natural’ boundary
conditions at the geometric axis. Boundary values are not
set explictely but are implicitly given by *π*-shifted
values at the geometric axis. Relevant in cylindrical
geometry for `_C.bc[2]` and in spherical geometry for
`_C.bc[0]`,`_C.bc[2]`,`_C.bc[3]`.
*Note 1: If the geometric axis is actually not part of the
domain setting F-type BC mimicks a pseudo-axis.*
*Note 2: There are restrictions in using F-type BC
concerning MPI and AMR.*
- `U`: user-defined boundary conditions (cf.
\[here\](3.2-User-interfaces\#defining-boundary-conditions)).
`MESH REFINEMENT`:
>MESH REFINEMENT ---------------------------------------------------------------
01 0 2 >imr,amr
02 2.0e-01 4.0e-01 -4.0e-01 4.0e-01 2.0e-01 >amr_eps[0-4] / refinement thresholds
03 0.0e-00 1.0e-01 0.0e+00 1.0e-01 1.0e-02 >rhoref,vref,eref,Bref,Cref
04 0.7e+00 0.3e+00 >amr_{d1,exp}
05 2.0e-01 0.0e+00 -0.2e+00 >amr_{Jeans,dJeans,Field}
- `01` (`_C.imr`, `_C.amr`)
- `_C.imr` (≤`MAXLEVEL`): maximal requested refinement level in a
user-defined initially refined mesh (cf.
\[here\](3.2-User-interfaces\#user-defined-initial/restricted-mesh)).
`_C.imr` cannot be larger than the macro `MAXLEVEL` defined in
the header file `nirvanaUser.h`.
- `_C.amr` (≤`MAXLEVEL`): maximum allowed mesh refinement level in
a AMR simulations.
- `02` (`_C.amr_eps[0-4]`)
- `_C.amr_eps[0-4]` (typical range: \[0.1, 0.5\]): thresholds for
the mass density (`_C.amr_eps[0]`), momentum density
(`_C.amr_eps[1]`), energy density (`_C.amr_eps[2]`), magnetic
field strength (`_C.amr_eps[3]`) and tracer variables
(`_C.amr_eps[4]`) in the derivatives-based mesh refinement
criterion (cf.
\[here\](3.1-Code-basics\#adaptive-mesh-refinement)). A zero or
negative value means that the respective component is disabled
for a mesh refinement check.
- `03` (`_C.rhoref`, `_C.vref`, `_C.eref`, `_C.bref`, `_C.Cref`)
- `_C.rhoref`: absolute reference value for the mass density in
the derivatives-based mesh refinement criterion. Can be safely
set to zero.
- `_C.vref`: absolute reference value for the velocity in the
derivatives-based mesh refinement criterion. This value can be
typically chosen to be a small fraction of a characteristic
velocity appearing in the simulation problem.
- `_C.eref`: absolute reference value for the total energy density
in the derivatives-based mesh refinement criterion. Can be
safely set to zero.
- `_C.bref`: absolute reference value for the magnetic field in
the derivatives-based mesh refinement criterion. This value can
be typically chosen to be a small fraction of a characteristic
magnetic field strength appearing in the simulation problem.
- `_C.Cref`: absolute reference value for tracer variables in the
derivatives-based mesh refinement criterion. A typical value is
0.01.
- `04` (`_C.amr_d1`, `_C.amr_exp`)
- `_C.amr_d1` (\[0,1\]): tuning parameter in the derivatives-based
mesh refinement criterion controlling the transition between a
purely gradient-based (`_C.amr_d1=1`) and a purely
2nd-derivatives-based (`_C.amr_d1=0`) check.
- `_C.amr_exp` (\[0,2\]): tuning parameter in the
derivatives-based mesh refinement criterion controlling the
power-law dependence of mesh refinement on the grid spacing. A
value `_C.amr_exp>1` (`_C.amr_exp<1`) would mean that mesh
refinement becomes progressively more difficult (easier) with
increasing refinement level compared to the standard linear
dependence (`_C.amr_exp=1`).
- `05` (`_C.amr_Jeans`, `_C.amr_exp`, `_C.amr_Field`)
- `_C.amr_Jeans` (typical value: 0.2): threshold in the
Jeans-length-based mesh refinement criterion (cf.
\[here\](3.1-Code-basics\#adaptive-mesh-refinement)). The value
`_C.amr_Jeans` defines the fraction of local Jeans length to be
resolved by at least one grid cell. A zero or negative value
means that the Jeans-length-based criterion is disabled.
- `_C.amr_dJeans` ( ≥ 0): tuning parameter for the
Jeans-length-based mesh refinement criterion allowing a
systematic reduction of the Jeans threshold with increasing
refinement level *l* according to the expression `_C.amr_Jeans`
-*l*\*`_C.amr_dJeans`, i.e., the local Jeans length becomes
gradually higher resolved with incresing *l*.
*Note: Tuning of `_C.amr_dJeans` must be such that the actual
Jeans threshold does not become too small of even negative.*
- `_C.amr_Field` (typical value: 0.2): threshold in the
Field-length-based mesh refinement criterion (cf.
\[here\](3.1-Code-basics\#adaptive-mesh-refinement)). The value
`_C.amr_Field` defines the fraction of the local Field length to
be resolved by at least one grid cell. A zero or negative value
means that the Field-length-based criterion is disabled.
`USER-SPECIFIC PARAMETERS`:
>USER-SPECIFIC PARAMETERS ------------------------------------------------------
01 0.00000e+00 0.00000e+00 0.00000e+00 >param[0-2] /
02 0.00000e+00 0.00000e+00 0.00000e+00 >param[3-5] /
03 0.00000e+00 0.00000e+00 0.00000e+00 >param[6-8] /
04 0.00000e+00 0.00000e+00 0.00000e+00 >param[9-11] /
05 0.00000e+00 0.00000e+00 0.00000e+00 >param[12-14] /
06 0 0 0 0 0 0 0 0 >flag[0-7] /
- `01` (`_C.param[0-2]`)
`02` (`_C.param[3-5]`)
`03` (`_C.param[6-8]`)
`04` (`_C.param[9-11]`)
`05` (`_C.param[12-14]`)
- `_C.param[0-14]`: freely usable parameter of `double` type.
- `06` (`_C.flag[0-7]`)
- `_C.flag[0-7]`: freely usable parameter of `int` type.
`SOLVER SPECIFICATIONS`:
>SOLVER SPECIFICATIONS ---------------------------------------------------------
01 RK3 CU CCT 5.0e-01 >mhd_solver_{time,flux,ef},mhd_courant
02 STD 4.0e-01 >viscosity_{solver,courant}
03 STD 4.0e-01 >diffusion_{solver,courant}
04 STD 4.0e-01 >conduction_{solver,courant}
05 STD 4.0e-01 >APdiffusion_{solver,courant}
06 0.1 >heatloss_max_change
07 0.1 0.1 >reactions_max_change{X,T}
08 1. >dt0_reduce:{<=1.}
- `01` (`_C.mhd_solver_time`, `_C.mhd_solver_flux`,
`_C.mhd_solver_ef`, `_C.mhd_courant`)
- `_C.mhd_solver_time` ({RK2,RK3}): choice of time integrator for
the MHD part of PDEs.
- RK2: second-order Runge-Kutta scheme
- RK3: third-order, strong-stability-preserving Runge-Kutta
scheme
- `_C.mhd_solver_flux` ({CU,HLLD}): choice of the flux computation
method in the Finite-Volume (FV) scheme.
- CU: central-upwind scheme (equiv. to HLL in the current
implementation)
- HLLD: HLLD Riemann solver
- `_C.mhd_solver_ef` ({CT,CCT}): choice of method to compute
edge-centered electric field components in the
constrained-transport MHD solver.
- CT: flow-upwinded face-to-edge interpolation of the
face-centroid electric field fluxes obtained in the FV flux
computation part.
- CCT: 2D upwinding procedure based on a Hamilton-Jacobi-type
numerical technique (equiv. to genuinely 2D-HLL in the
current implementation).
- `_C.mhd_courant` (typical value: ≤ 0.5): CFL number in the
expression for the MHD timestep.
- `02` (`_C.viscosity_solver`, `_C.viscosity_courant`)
- `_C.viscosity_solver` ({STD,RKL}): choice of time integrator for
the fluid viscosity.
- STD: Runge-Kutta method as selected for the MHD integrator.
Coupling to the MHD integrator is unsplit.
- RKL: second-order, stabilized Runge-Kutta-Legendre method.
Coupling to the MHD integrator is via Strang-type splitting.
- `_C.viscosity_courant`: CFL-analog number in the expression for
the fluid viscosity timestep. A typical value in case of STD is
&lt; 0.5. Values much larger than 1 are possible in the case of
RKL.
- `03` (`_C.diffusion_solver`, `_C.diffusion_courant`)
- Analog to line `02` but for magnetic diffusion.
- `04` (`_C.conduction_solver`, `_C.conduction_courant`)
- Analog to line `02` but for thermal conduction.
- `05` (`_C.APdiffusion_solver`, `_C.APdiffusion_courant`)
- Analog to line `02` but for ambipolar diffusion.
- `06` (`_C.heatloss_max_change`)
- `_C.heatloss_max_change` (typical value: ≤ 0.1): maximal
allowed relative change in temperature due to the heatloss
source term.
- `07` (`_C.reactions_max_changeX`, `_C.reactions_max_changeT`)
- `_C.reactions_max_changeX` (typical value: ≤ 0.1): maximal
relative change of species number densities (or total number
density) in the time integration of the chemo-thermal rate
equations.
*Note: The macro `SXN` in module `solveNCCM.c` provides a linear
weight in applying the parameter `_C.reactions_max_change` to
individual number densities and to the total number density.*
- `_C.reactions_max_changeT` (typical value: ≤ 0.1): maximal
relative change of temperature in the time integration of the
chemo-thermal rate equations.
- `08` (`_C.dt0_reduce`)
- `_C.dt0_reduce`: reduction factor of the first timestep.
`PHYSICS SPECIFICATIONS`:
>PHYSICS SPECIFICATIONS --------------------------------------------------------
01 Y 7.94e+05 >mf,permeability_rel
02 N 0.00e+00 >viscosity{,_coeff}
03 N 0.00e+00 >diffusion{,_coeff}
04 N 0.00e+00 0.00e+00 0.00e+00 >conduction{,_coeff,_coeff_perp,_coeff_sat}
05 N 0.00e+00 >APdiffusion{,_coeff}
06 Y 0.05 >energy,energy_dual_sw:[0,1]
07 N >force
08 N >gravity
09 ADI 1.67e+00 1.00e+00 1.00e+00 >eos,gamma,poly_const,temperature
10 N >heatloss
11 0 >tracer
12 0 >testfields
13 N N N 1.00 0.00 >species,reac,energy_reaction,mmw,mean_ionization
- `01` (`_C.mf`, `_C.permeability_rel`)
- `_C.mf` ({Y,N}): option for activating magnetic fields. The
value Y enables the evolution of magnetic fields. The value N
refers to HD where the Lorentz force is dropped from the
momentum equation and the induction equation is not solved.
- `_C.permeability_rel`: relative magnetic permeability
*μ*<sub>*r**e**l*</sub>
( = *μ*/*μ*<sub>0</sub>, *μ*<sub>0</sub> = 4*π* ⋅ 10<sup> − 7</sup>`V` ⋅ `m`<sup> − 1</sup> ⋅ `A`<sup> − 1</sup> ⋅ `s`<sup> − 1</sup>).
*Note: The Gaussian unit system can be mimicked by choosing a
value
`_``C``.``p``e``r``m``e``a``b``i``l``i``t``y``_``r``e``l` = 10<sup>7</sup>
so that the magnetic permeability is *μ* = 4*π*.*
- `02` (`_C.viscosity`, `_C.viscosity_coeff`)
- `_C.viscosity` ({Y,N,U}): option for activating fluid viscosity.
The value Y enables the fluid viscosity term using a constant
*dynamic* viscosity coefficient as given by the parameter
`_C.viscosity_coeff` described next. The value U enables fluid
viscosity with a user-defined dynamic viscosity coefficient as
coded in the user interface `viscosityCoeffUser.c`. The value N
disables fluid viscosity.
- `_C.viscosity_coeff`: standard constant *dynamic* viscosity
coefficient.
- `03` (`_C.diffusion`, `_C.diffusion_coeff`)
- `_C.diffusion` ({Y,N,U}): option for activating magnetic
diffusion. The value Y enables the magnetic diffusion term using
a constant magnetic diffusion coefficient given by the parameter
`_C.diffusion_coeff` described next. The value U enables
magnetic diffusion with a user-defined magnetic diffusion
coefficient as coded in the user interface
**diffusionCoeffUser.c**. The value N disables magnetic
diffusion.
- `_C.diffusion_coeff`: standard constant magnetic diffusion
coefficient.
- `04` (`_C.conduction`, `_C.conduction_coeff`,
`_C.conduction_coeff_perp`, `_C.conduction_coeff_sat`)
- `_C.conduction` ({Y,N,U,S}): option for activating thermal
conduction. In the presence of magnetic fields the thermal
conduction is anisotropic with distinct conduction coefficients
parallel and perpendicular to the magnetic field. In HD thermal
conduction is assumed isotropic. The value Y enables the thermal
conduction term using a constant conduction coefficient given by
the parameter `_C.conduction_coeff` (and
`_C.conduction_coeff_perp` in the anisotropic case) described
next. The value U enables thermal conduction with a user-defined
conduction coefficient as coded in the user interface
**conductionCoeffUser.c**. The value S refers to the standard
Spitzer conductivity model (cf. physics guide
[Wiki](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/A-PhysicsGuide),
[PDF](https://gitlab.aip.de/ziegler/NIRVANA/doc/pdf/PhysicsGuide.pdf)).
The value N disables thermal conduction.
- `_C.conduction_coeff`: standard constant thermal conduction
coefficient (in the anisotropic case this is the parallel
coefficient).
- `_C.conduction_coeff_perp`: constant thermal conduction
coefficient perpendicular to the magnetic field (meaningless in
isotropic conduction).
- `_C.conduction_coeff_sat` (typical value: 0.3): parameter *Ψ* in
the saturation heat flux model of (cf. physics guide
[Wiki](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/C-NumericsGuide),
[PDF](https://gitlab.aip.de/ziegler/NIRVANA/doc/pdf/NumericsGuide.pdf)).
- `05` (`_C.APdiffusion`, `_C.APdiffusion_coeff`)
- `_C.APdiffusion` ({Y,N,U}): option for activating ambipolar
diffusion. The value Y enables the ambipolar diffusion term
using a constant ambipolar diffusion coefficient given by the
parameter `_C.APdiffusion_coeff` described next. The value U
enables ambipolar diffusion with a user-defined anbipolar
diffusion coefficient as coded in the user interface
**APdiffusionCoeffUser.c**. The value N disables ambipolar
diffusion.
- `_C.APdiffusion_coeff`: standard constant ambipolar diffusion
coefficient.
- `06` (`_C.energy`, `_C.energy_dual_sw`)
- `_C.energy` ({Y,N,DUAL}): option for activation of the energy
equation. The value Y means that the total energy equation is
solved in time with the gasdynamics equations. For value N no
energy equation is solved. The value DUAL enables a dual energy
formalism where both the total energy equation and the thermal
energy equation is solved simultaneously. This allows a more
robust computation of the pressure (in view of possitivity) in
regions of high Mach number and/or low plasma-*β*. Actually, the
thermal energy density (hence, the pressure) is computed from
the solution of the thermal energy equation if the
thermal-to-total energy density ratio falls below a certain
threshold (next parameter). Otherwise the thermal energy density
is computed from the solution of the total energy equation as
usual.
*Note 1: Disabling the energy equation is not consistent with
the use of an adiabatic EOS.*
*Note 2: The dual energy formalism violates the energy
conservation principle since syncronization steps between total
and thermal energy densities are necessary to maintain
consistency.*
- `_C.energy_dual_sw` (\[0, 1\]; typical value: 0.01): threshold
value for the thermal-to-total energy density ratio in the dual
energy formalism (when `_C.energy`=DUAL).
- `07` (`_C.force`)
- `_C.force` ({Y,N}): option for activating a body force term. The
value Y enables a body force in the momentum equation. The body
force has to be defined by the user in the user interface
`forceUser.c`. The value N disables body forces.
- `08` (`_C.gravity`)
- `_C.gravity` ({Y,N}): option for activating selfgravity. The
value Y enables selfgravity. A Poisson equation is solved for
the gravitational potential (cf. physics guide
[Wiki](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/C-NumericsGuide),
[PDF](https://gitlab.aip.de/ziegler/NIRVANA/doc/pdf/NumericsGuide.pdf)).
The value N disables selfgravity.
- `09` (`_C.eos`,`_C.gamma`,`_C.polytropic_constant`,`_C.temperature`)
- `_C.eos` ({ADIA,ISO,POLY,USER,TAB}): choice of the equation of
state. Possible values are:
- ADIA: adiabatic EOS. This choice requires specificiation of
the adiabatic index (parameter: `_C.gamma`).
- ISO: isothermal EOS. This choice requires specification of
the temperature (parameter: `_C.temperature`).
- POLY: polytropic EOS. This choice requires specification of
the polytropic exponent (parameter: `_C.gamma`) and
polytropic constant (parameter: `_C.polytropic_constant`).
- USER: user-defined analytic EOS. This choice requires the
specification of special macros (cf.
\[here\](3.2-User-interfaces\#user-defined-equation-of-state))
- TAB: user-defined tabulated EOS. This choice requires the
generation of look-up tables (cf.
\[here\](3.2-User-interfaces\#user-defined-equation-of-state)).
*Note: The choice of an isothermal EOS or polytropic EOS is not
compatible with solving for an energy equation.*
- `_C.gamma`: adiabatic index (polytropic exponent) in the
adiabatic (polytropic) EOS.
*Note: In a multi-species gas the adiabatic index is not a
freely selectable parameter but is approximated by the
expression*
*γ* = \[5(*n*<sub>*H*</sub>+*n*<sub>*H**e*</sub>+*n*<sub>*e*</sub>)+7*n*<sub>*H*<sub>2</sub></sub>\]/\[3(*n*<sub>*H*</sub>+*n*<sub>*H**e*</sub>+*n*<sub>*e*</sub>)+5*n*<sub>*H*<sub>2</sub></sub>\]
- `_C.polytropic_constant`: polytropic constant in the polytropic
EOS.
- `_C.temperature`: temperature in the isothermal EOS.
- `10` (`_C.heatloss`)
- `_C.heatloss` ({N,ISM,U}): option for activating an external
heatloss term (cooling/heating function) in the energy equation.
The value N disables the heatloss term. The value ISM enables
the heatloss term applying a predefined interstellar medium
cooling/heating function (cf. physics guide
[Wiki](https://gitlab.aip.de/ziegler/NIRVANA/-/wikis/A-PhysicsGuide),
[PDF](https://gitlab.aip.de/ziegler/NIRVANA/doc/pdf/PhysicsGuide.pdf)).
The value U enables the heatloss term assuming a user-defined
cooling/heating function coded in the interfaces
**sourceCoolingUser.c** for cooling and **sourceHeatingUser.c**
for heating (cf.
\[here\](3.2-User-interfaces\#user-defined-cooling/heating-function)).
- `11` (`_C.tracer`)
- `_C.tracer`: number of passive tracer variables to be
transported with the flow.
- `12` (`_C.testfields`)
- `_C.testfields`: number of testfield equations associated with
the code functionality TESTFIELDS.
- `13` (`NN`, `NN`, `_C.energy_reactions`, `_C.mean_molecular_weight`,
`_C.mean_ionization`)
- NN ({Y,N}): option for activating the multi-species framework.
The value Y enables the multi-species framework. In the
multi-species framework an advection equation is solved for each
specie defined in the `SPECIES` section of the user interface
`NCCM.par`. The value N refers to a standard single-component
gas.
- NN ({Y,N}): option for activating a chemical reaction network
between species. The value Y enables chemical reactions if the
multi-species framework is enabled. An advection-reaction
equation is solved for each specie defined in the `SPECIES`
section of the user interface `NCCM.par` subject to chemical
reactions as specified in the `REACTIONS` section of the same
file.
- `_C.energy_reactions` ({Y,N}): option for activating the thermal
processes implemented in the NCCM. The value Y enables thermal
processes if the multi-species framework and chemical reaction
network are both enabled. Thermal processes have to be selected
in the `THERMAL PROCESSES` section of `NCCM.par`.
- `_C.mean_molecular_weight`: mean molecular weight.
*Note: In a multi-species gas the mean molecular weight is not a
freely selectable parameter but computed selfconsistently from
the species composition.*
- `_C.mean_ionization`: mean ionization fraction.
*Note: In a multi-species gas the ionization fraction is not a
freely selectable parameter but computed selfconsistently from
the ionisation structure.*