5. Description of the parameters in PION parameter files

PION is controlled mainly by a parameter file that sets what kind of initial conditions to set up, what equations to use, the properties of the computational grid, source terms such as stellar wind, and numerical parameters specifying the integration scheme. The parameter file is ASCII text and each line should contain a key and its value, separated by whitespace. String values should be input as normal text, floating-point numbers in format 1.2345 or 1.2345e-67 (PION defaults to run in double precision). Unless otherwise stated, physical quantities should be input in CGS units, magnetic field in Gauss. Comment lines that begin with # are ignored. Some parameters are required and some are optional; for optional parameters PION will fall back to default values for any parameters that are not given. The parameters are described in more detail below.

5.1. Initial Conditions Generator

There are a number of different problems that can be set up with PION, with source files located in source/ics/. The parameter ics determines which problem is set up, with the following options:

Problem (key value)	Location of source file	Brief description
`1Dto2D`	`read_1Dto2D.cpp`	Read 1D snapshot and map to 2D or 3D grid
`Advection`	`basic_tests.cpp`	Sets up advection of an overdense clump
`BlastWave`	`blast_wave.cpp`	Set up supernova blastwave problems
`DivBPeak`	`basic_tests.cpp`	Sets up a uniform medium with a peak in \(\nabla\cdot\mathbf{B}\)
`DoubleMachRef`	`basic_tests.cpp`	The Double Mach-Reflection test
`FieldLoop`	`basic_tests.cpp`	Advection of a magnetic field loop
`Jet`	`jet.cpp`	Sets up 2D axisymmetric jet or 3D jet
`KelvinHelmholtz`	`basic_tests.cpp`	Set up Kelvin-Helmholtz instability test
`LaserAblationAxi`	`laser_ablation.cpp`	Set up a HEDP laser ablation test calc
`LiskaWendroffImplosion`	`basic_tests.cpp`	The Liska and Wendroff implosion test
`OrszagTang`	`basic_tests.cpp`	The 2D Orszag-Tang Vortex test
`PE_MC_FN` or `PE_MC_FM`	`photoevaporating_multiclumps.cpp`	Set up photoevaporation of dense clouds
`PhotoEvaporatingClump`	`photoevaporating_clump.cpp`	Sets up photoevaporation of dense cloud
`PhotEvap_RandomClumps`	`photoevaporating_random_clumps.cpp`	Set up photoevaporation of randomly placed dense clouds
`RadiativeShock`	`radiative_shock.cpp`	Sets up 1D or 2D radiative shock test
`ShockCloud`	`shock_cloud.cpp`	Set up shock-cloud interaction problems
`Uniform`	`basic_tests.cpp`	Sets up a uniform medium

Each of these types of initial-condition generator has some distinct parameters that should be set in the parameter file (discussed in more detail below).

5.2. General Parameters

5.2.1. Integration Scheme

Some required parameters set the coordinate system, equations to be solved, accuracy of the solution, etc.

Parameter	Type	Units	Description
`ndim`	integer	none	Number of spatial dimensions to simulate
`coordinates`	string	none	Geometry. 1D: spherical, 2D: cylindrical/cartesian, 3D: cartesian
`eqn`	string	none	System of equations to solve: euler, mhd, glm-mhd
`GAMMA`	double	none	adiabatic index of the gas (usually 5/3=1.66666666666667)
`solver`	integer	none	Which flux solver to use (see above for options)
`OrderOfAccSpace`	integer	none	spatial order of accuracy: 1 = piecewise constant; 2 = piecewise linear
`OrderOfAccTime`	integer	none	temporal order of accurasy: 1 = 1st order piecewise constant; 2 = 2nd order, piecewise linear
`CFL`	double	none	Courant-Friedrichs-Lewy number (<1 1D, <0.5 2D, <0.33 3D)
`ArtificialViscosity`	integer	none	0=no AV, 1=Falle+(1998) AV, 3=Sanders+(1998) H-correction H-correction only works with some solvers.
`EtaViscosity`	double	none	Viscosity parameter for Falle+(1998) AV, in range [0,1], default value is 0.15.

There are three different types of equations that can be set up:

Euler equations: the inviscid equations of hydrodynamics.
Ideal MHD equations: magnetohydrodynamics, only usable in 1D because there is no scheme for dealing with DivB errors.
GLM-MHD equations: magnetohydrodynamics plus the Dedner et al. (2002) divergence cleaning mechanism for mitigating DivB errors.

There are a number of different flux solvers that can be used, with different levels of robustness and accuracy:

Available solvers:

Euler: 0 = Lax-Friedrichs, 1 = linear, 2 = exact (slow), 3 = linear+exact hybrid, 4 = Roe conserved variables, 6 = Flux-vector splitting, 8 = HLL, 9 = Roe+HLL hybrid)
MHD: 0 = Lax-Friedrichs, 1 = linear, 4 = Roe conserved variables, 7 = HLLD+HLL hybrid, 8 = HLL

Notes:

Recommended solver for the Euler equations is 9, and for the MHD equations is 7.
GAMMA should be in the range (1,2)
Spatial and temporal order of accuracy may both be set to 1 or 2, but they should be the same as each other. 2nd-order scheme is better.
The CFL parameter for an unsplit scheme should be <1/ndim
Cartesian coordinate system is available in 1D,2D,3D.
Cylindrical coordinates are only available in 2D \((z,R)\) with rotational symmetry in \(\theta\) direction. The radial coordinate (y axis) should begin at \(R=0\) and use an axisymmetric boundary condition.
Spherical coordinate system is only available in 1D, radial coordinate, with reflection symmetry at \(r=0\).

5.2.2. Computational Grid

The PION computational grid is a uniform rectilinear grid in 1, 2 or 3 spatial dimensions. Static mesh-refinement (nested grids) is implemented for the case where each refinement level has the same shape and number of cells as the coarser level above it, but the spatial resolution is a factor of 2 higher and so the grid covers 1/2 of the domain of the coarser grid in each dimension. The focus of the nested grid can be at the centre of the domain, the negative boundary or the positive boundary for each dimension. The number of refinement levels is in principle unlimited, but snapshots can only be written every coarse timestep and this imposes a practical limit: for 10 grid levels there are 512 finest-level timesteps per coarsest-level step, and one may wish to save a snapshot at least this often. The coarsest level is denoted level 0, and each refined level has a higher level number.

The parameters are:

Parameter	Type	Units	Description
`NGridX`	integer	none	Number of grid points in \(\hat{x}\)-direction
`NGridY`	integer	none	Number of grid points in \(\hat{y}\)-direction
`NGridZ`	integer	none	Number of grid points in \(\hat{z}\)-direction
`Xmin`	double	cm	negative boundary in \(\hat{x}\)-direction (level 0)
`Ymin`	double	cm	negative boundary in \(\hat{y}\)-direction (level 0)
`Zmin`	double	cm	negative boundary in \(\hat{z}\)-direction (level 0)
`Xmax`	double	cm	positive boundary in \(\hat{x}\)-direction (level 0)
`Ymax`	double	cm	positive boundary in \(\hat{y}\)-direction (level 0)
`Zmax`	double	cm	positive boundary in \(\hat{z}\)-direction (level 0)
`grid_nlevels`	integer	none	Number of grid levels for static mesh-refinement (>=1)
`grid_aspect_ratio_XX`	integer	none	Aspect ratio of grid in each dimension
`grid_aspect_ratio_YY`	integer	none	Aspect ratio of grid in each dimension
`grid_aspect_ratio_ZZ`	integer	none	Aspect ratio of grid in each dimension
`NG_centre_XX`	double	cm	focus of nested grid refinement in X
`NG_centre_YY`	double	cm	focus of nested grid refinement in Y
`NG_centre_ZZ`	double	cm	focus of nested grid refinement in Z
`NG_refine_XX`	integer	none	refine in x-direction? (1==yes)
`NG_refine_YY`	integer	none	refine in y-direction? (1==yes)
`NG_refine_ZZ`	integer	none	refine in z-direction? (1==yes)

5.2.3. Boundary Conditions

parameter name	type	description
`BC_XN`	string	boundary condition for negative x-direction
`BC_XP`	string	boundary condition for positive x-direction
`BC_YN`	string	boundary condition for negative y-direction
`BC_YP`	string	boundary condition for positive y-direction
`BC_ZN`	string	boundary condition for negative z-direction
`BC_ZP`	string	boundary condition for positive z-direction
`BC_Ninternal`	integer	Number of internal boundary regions (stellar wind)
`BC_INTERNAL_000`	string	type of 1st internal boundary region (if `BC_Ninternal` >0)

The possible values for the boundary conditions are listed in Boundary Conditions.

5.2.4. Units

PION uses CGS units by default. There are parameters to set up a system of units, but currently they do not do anything. Internally PION solves the MHD equations in units such that factors of \(4\pi\) do not appear, but these are rescaled by \(\sqrt{4\pi}\) on reading from and writing to snapshots, and so the snapshots have magnetic field units of Gauss.

parameter name	type	value
units	string	cgs
rhoval	double	1.0
lenval	double	1.0
velval	double	1.0
magval	double	1.0

5.3. Source terms

5.3.1. Radiation sources

The parameter RT_Nsources is an integer setting the number of radiation sources. Each source i, numbered from 0, has parameters of the form RT_[name]_[i] that describe the radiation field emitted.

parameter key	value type	description
`RT_position_[i]_[n]`	double	position of source along axis `n` (cm). Value >1e100 (or <-1e100) implies a source at infinity.
`RT_src_type_[i]`	integer	1=point source (tested), 2=diffuse radiation (untested)
`RT_at_infty_[i]`	integer	1: source is at infinity, 0: point source obeying inverse square law
`RT_update___[i]`	integer	1: use C2-ray update (Mellema+2006); 2: use Mackey(2012) update; 2 is recommended - 1 may be broken.
`RT_effect___[i]`	integer	1: UV heating, 2: monochromatic photoionizing field, 3: multifrequency photoionization (switch to 5 in next release UPDATE CODES!).
`RT_Tau_src__[i]`	integer	set to 10 so that the opacity in a cell is calculated by the microphysics module. Other options are being deprecated.
`RT_Tau_var__[i]`	integer	unused if `RT_Tau_src` is set to 10. Other options deprecated.
`RT_Nbins____[i]`	integer	Number of energy bins for radiation field (set to 1 unless using MPv10)
`RT_EVO_FILE_[i]`	string	“NONE”: constant wind, or name of text file containing time evolution information.
`RT_strength_[i]`	double	luminosity in erg/s for multi-frequency source, or in photons/s for monochromatic source. For a source at infinity this is the incident flux (erg/cm2/s or photons/cm2/s). Not used for evolving source.
`RT_Rstar____[i]`	double	Stellar radius in `R_sun`. Not used for evolving source.
`RT_Tstar____[i]`	double	Stellar effective temperature in K. Not used for evolving source.

5.3.2. Stellar Winds

The parameter WIND_NSRC is an integer setting the number of stellar-wind sources. These are implemented as a spherical boundary region in which the fluid quantities are set according to the wind parameters for each source.

Stellar winds in PION are implemented in 3 modules: a constant wind, an evolving wind, and a latitude-dependent wind. The parameter file for a constant wind has a number of parameters that should be set, quoted below with the expected units. They are stored in these units in the SWP struct of type stellarwind_params.

Parameter	Description	Units/values
`WIND_[i]_pos[n]`	Star position \(n\in[0,1,2]\)	cm
`WIND_[i]_velocity[n]`	Star velocity \(n\in[0,1,2]\)	cm/s (if moving) default is 0
`WIND_[i]_radius`	Radius of wind injection region	cm
`WIND_[i]_type`	[Constant, evolving, latitude dependent]	[0,1,2]
`WIND_[i]_mdot`	Mass-loss rate from star (dot{M})	\(\mathrm{M_{\odot}\,yr}^{-1}\)
`WIND_[i]_vinf`	Terminal velocity of wind	\(\mathrm{km\,s}^{-1}\)
`WIND_[i]_vrot`	Equatorial rotation velocity	\(\mathrm{km\,s}^{-1}\)
`WIND_[i]_temp`	Effective Temperature of star, \(T_\mathrm{eff}\)	K
`WIND_[i]_Rstr`	Radius of star	cm
`WIND_[i]_Bstr`	Strength of surface magnetic field	Gauss
`WIND_[i]_TR[n]`	Value of tracer \(n\) in wind	Usually \(\in [0,1]\)
`WIND_[i]_evofile`	Text file with data for evolving wind	Default is NOFILE
`WIND_[i]_t_offset`	offset of sim time from evolution time	Default is 0.0
`WIND_[i]_t_scalefac`	scaling simulation time to evolution time	Default is 1.0
`WIND_[i]_updatefreq`	How often to update the wind	seconds
`WIND_[i]_enhance_mdot`	ad-hoc flag to increase \(\dot{M}\)	Default is 0
`WIND_[i]_moving`	is star moving? yes==1, no==0	Default is 0
`WIND_[i]_acceleration`	is wind accelerated? yes==1, no==0	Default is 0 (inject at v_inf)

For constant winds, these data are stored in the global struct SWP, defined in pion/source/constants.h, using these units. In simulation snapshots they also have the same units. The evolving wind file should have all units in CGS.

5.3.3. Jet inflow

There is an untested module for injecting protostellar jets along the symmetry axis in 2D cylindrical simulations, or along the positive x-axis in 3D Cartesian simulations. The parameter N_JET takes an integer argument for the number of jet sources. The module worked in 2010 when it was used for testing v.1.0 of PION, but has not been used since then. If you want to know more about this, especially what extra parameters you need to include, take a look at source/ics/jet.cpp (and probably modify the source code for your needs).

5.4. Types of initial conditions that have been programmed

5.4.1. Uniform

This sets up uniform initial conditions throughout the domain in the standard mode, but it can also be used to set up a spherically symmetric medium with a constant density core and a power-lsw density profile outside the core. One may add random adiabatic noise to this initial condition by setting the parameter noise to a value between 0 and 1 (this is the fractional level of the noise with respect to background density). Parameters:

parameter key	type	description
`UNIFORM_ambRO`	double	gas density (g/cm3)
`UNIFORM_ambPG`	double	gas pressure (dyne/cm2)
`UNIFORM_ambVX`	double	x-velocity (cm/s)
`UNIFORM_ambVY`	double	y-velocity (cm/s)
`UNIFORM_ambVZ`	double	z-velocity (cm/s)
`UNIFORM_ambBX`	double	magnetic field BX (Gauss)
`UNIFORM_ambBY`	double	magnetic field BY (Gauss)
`UNIFORM_ambBZ`	double	magnetic field BZ (Gauss)
`UNIFORM_ambTR[N]`	double	initial value of tracer `N`
`UNIFORM_radial_slope`	double	If non-zero, this is the power-law slope of density with radius (spherically symmetric)
`UNIFORM_core_radius`	double	constant-density core radius for case with power-law density
`UNIFORM_radial_velocity`	double	expansion/contraction velocity w.r.t. origin
`UNIFORM_core_centre_XX`	double	x position of core centre
`UNIFORM_core_centre_YY`	double	y position of core centre
`UNIFORM_core_centre_ZZ`	double	z position of core centre

5.4.2. ShockCloud

Sets up a shock-cloud test problem

5.4.3. RadiativeShock

Sets up a radiative shock test, with a flow hitting a reflecting boundary.

5.4.4. PhotEvap_RandomClumps

Sets up a simulation with randomly placed clumps on a uniform ISM

5.4.5. PhotoEvaporatingClump

Sets up a simulation of a single dense clump evaporated by an ionizing radiation field.

5.4.6. PE_MC_FN or PE_MC_FM

Sets up a simulation with a fixed number of random clumps or a fixed total mass in random clumps

5.4.7. BlastWave

Sets up a blastwave test problem

5.4.8. Advection

Sets up an advection test on a periodic domain

5.4.9. DoubleMachRef

Sets up the double Mach reflection test problem.

5.4.10. OrszagTang

Sets up the Orzsag-Tang Vortex test problem

5.4.11. LiskaWendroffImplosion

Sets up the Liska and Wendroff implosion test problem.

5.4.12. KelvinHelmholtz

Sets up a KH instability test problem.

5.4.13. FieldLoop

Sets up the field-loop advection test.

5.4.14. DivBPeak

Sets up the test of how the code can deal with a peak in divB

5.4.15. Others

Not yet documented.