parameter_description.rst

File format and basic information

The parameter file uses a format similar to the YAML format but reduced to only the elements required for the SWIFT parameters. Options are given by a name followed by a column and the value of the parameter:

ICs:        santa_barbara.hdf5
dt_max:     1.5
shift:      [2., 4., 5.]

Comments can be inserted anywhere and start with a hash:

# Description of the physics
viscosity_alpha:     2.0
dt_max:              1.5     # seconds

A typical SWIFT parameter file is split into multiple sections that may or may not be present depending on the different configuration options. The sections start with a label and can contain any number of parameters:

Cosmology:    # Planck13
  Omega_m:        0.307
  Omega_lambda:   0.693
  Omega_b:        0.0455
  h:              0.6777
  a_begin:        0.0078125     # z = 127

The options can be integer values, floating point numbers, characters or strings. If SWIFT expects a number and string is given, an error will be raised. The code can also read an array of values:

shift:  [2., 4., 5.]

Some options in the parameter file are optional and when not provided, SWIFT will run with the default value. However, if a compulsory parameter is missing an error will be raised at start-up.

Finally, SWIFT outputs two YAML files at the start of a run. The first one used_parameters.yml contains all the parameters that were used for this run, including all the optional parameters left unspecified with their default values. This file can be used to start an exact copy of the run. The second file, unused_parameters.yml contains all the values that were not read from the parameter file. This can be used to simplify the parameter file or check that nothing important was ignored (for instance because the code is not configured to use some options).

The rest of this page describes all the SWIFT parameters, split by section. A list of all the possible parameters is kept in the file examples/parameter_examples.yml.

Internal Unit System

The InternalUnitSystem section describes the units used internally by the code. This is the system of units in which all the equations are solved. All physical constants are converted to this system and if the ICs use a different system (see the snapshots' ref:ICs_units_label section of the documentation) the particle quantities will be converted when read in.

The system of units is described using the value of the 5 basic units of any system with respect to the CGS system. Instead of using a unit of time we use a unit of velocity as this is more intuitive. Users hence need to provide:

• a unit of length: UnitLength_in_cgs,
• a unit of mass: UnitMass_in_cgs,
• a unit of velocity UnitVelocity_in_cgs,
• a unit of electric current UnitCurrent_in_cgs,
• a unit of temperature UnitTemp_in_cgs.

All these need to be expressed with respect to their cgs counter-part (i.e. cm, g, cm/s, A and K). Recall that there are no h-factors in any of SWIFT's quantities; we, for instance, use cm and not cm/h.

For instance to use the commonly adopted system of 10^10 Msun as a unit for mass, mega-parsec as a unit of length and km/s as a unit of speed, we would use:

# Common unit system for cosmo sims
InternalUnitSystem:
  UnitMass_in_cgs:     1.98848e43    # 10^10 M_sun in grams
  UnitLength_in_cgs:   3.08567758e24 # 1 Mpc in centimeters
  UnitVelocity_in_cgs: 1e5           # 1 km/s in centimeters per second
  UnitCurrent_in_cgs:  1             # 1 Ampere
  UnitTemp_in_cgs:     1             # 1 Kelvin

Note that there are currently no variables in any of the SWIFT physics schemes that make use of the unit of electric current. There is also no incentive to use anything else than Kelvin but that makes the whole system consistent with any possible unit system.

If one is interested in using the more humorous FFF unit system one would use

# FFF unit system
InternalUnitSystem:
  UnitMass_in_cgs:     40823.3133  # 1 Firkin (fir) in grams
  UnitLength_in_cgs:   20116.8     # 1 Furlong (fur) in cm
  UnitVelocity_in_cgs: 0.01663095  # 1 Furlong (fur) per Fortnight (ftn) in cm/s
  UnitCurrent_in_cgs:  1           # 1 Ampere
  UnitTemp_in_cgs:     1           # 1 Kelvin

The value of the physical constants in this system is left as an exercise for the reader [1].

Cosmology

When running a cosmological simulation, the section Cosmology sets the values of the cosmological model. The expanded \Lambda\rm{CDM} parameters governing the background evolution of the Universe need to be specified here. These are:

• The reduced Hubble constant: h: h,
• The matter density parameter \Omega_m: Omega_m,
• The cosmological constant density parameter \Omega_\Lambda: Omega_lambda,
• The baryon density parameter \Omega_b: Omega_b,
• The radiation density parameter \Omega_r: Omega_r.

The last parameter can be omitted and will default to \Omega_r = 0. Note that SWIFT will verify on start-up that the matter content of the initial conditions matches the cosmology specified in this section.

This section also specifies the start and end of the simulation expressed in terms of scale-factors. The two parameters are:

• Initial scale-factor: a_begin,
• Final scale-factor: a_end.

Two additional optional parameters can be used to change the equation of state of dark energy w(a). We use the evolution law w(a) = w_0 + w_a (1 - a). The two parameters in the YAML file are:

• The z=0 dark energy equation of state parameter w_0: w_0
• The dark energy equation of state evolution parameter w_a: w_a

If unspecified these parameters default to the default \Lambda\rm{CDM} values of w_0 = -1 and w_a = 0.

For a Planck+13 cosmological model (ignoring radiation density as is commonly done) and running from z=127 to z=0, one would hence use the following parameters:

Cosmology:
  a_begin:        0.0078125     # z = 127
  a_end:          1.0           # z = 0
  h:              0.6777
  Omega_m:        0.307
  Omega_lambda:   0.693
  Omega_b:        0.0482519
  Omega_r:        0.            # (Optional)
  w_0:            -1.0          # (Optional)
  w_a:            0.            # (Optional)

When running a non-cosmological simulation (i.e. without the -c run-time flag) this section of the YAML file is entirely ignored.

Gravity

The behaviour of the self-gravity solver can be modified by the parameters provided in the Gravity section. The theory document puts these parameters into the context of the equations being solved. We give a brief overview here.

• The Plummer-equivalent co-moving softening length used for all dark matter particles \epsilon_{\rm com,DM}: comoving_DM_softening,
• The Plummer-equivalent co-moving softening length used for all baryon particles (gas, stars, BHs) \epsilon_{\rm com,bar}: comoving_baryon_softening,
• The Plummer-equivalent maximal physical softening length used for all dark matter particles \epsilon_{\rm max,DM}: max_physical_DM_softening,
• The Plummer-equivalent maximal physical softening length used for all baryon particles (gas, stars, BHs) \epsilon_{\rm max,bar}: max_physical_baryon_softening,

At any redshift z, the Plummer-equivalent softening length used by the code will be \epsilon=\min(\epsilon_{max}, \frac{\epsilon_{com}}{z+1}). The same calculation is performed independently for the dark matter and baryon particles. All the softening quantities are expressed in internal units. Calculations that only involve DM or baryons can leave the unused quantities out of the parameter file. For non-cosmological runs, only the physical softening lengths need to be supplied.

In case of zoom simulations, the softening of the additional, more massive, background particles is specified via the parameter softening_ratio_background. Since these particles will typically have different masses to degrade the resolution away from the zoom region, the particles won't have a single softening value. Instead, we specify the fraction of the mean inter-particle separation to use. The code will then derive the softening length of each particle assuming the mean density of the Universe. That is \epsilon_{\rm background} = f\sqrt[3]{\frac{m}{\Omega_m\rho_{\rm crit}}}, where f is the user-defined value (typically of order 0.05).

The accuracy of the gravity calculation is governed by the following two parameters:

• The opening angle (multipole acceptance criterion) used in the FMM \theta: theta,
• The time-step size pre-factor \eta: eta,

The time-step of a given particle is given by \Delta t = \sqrt{2\eta\epsilon_i/|\overrightarrow{a}_i|}, where \overrightarrow{a}_i is the particle's acceleration and \epsilon_i its (spline) softening length. Power et al. (2003) recommend using \eta=0.025.

The last tree-related parameter is

• The tree rebuild frequency: rebuild_frequency.

The tree rebuild frequency is an optional parameter defaulting to 0.01. It is used to trigger the re-construction of the tree every time a fraction of the particles have been integrated (kicked) forward in time.

Simulations using periodic boundary conditions use additional parameters for the Particle-Mesh part of the calculation. The last five are optional:

• The number cells along each axis of the mesh N: mesh_side_length,
• The mesh smoothing scale in units of the mesh cell-size a_{\rm smooth}: a_smooth (default: 1.25),
• The scale above which the short-range forces are assumed to be 0 (in units of the mesh cell-size multiplied by a_{\rm smooth}) r_{\rm cut,max}: r_cut_max (default: 4.5),
• The scale below which the short-range forces are assumed to be exactly Newtonian (in units of the mesh cell-size multiplied by a_{\rm smooth}) r_{\rm cut,min}: r_cut_min (default: 0.1),
• Whether or not to dither the particles randomly at each tree rebuild: dithering (default: 1),
• The magnitude of each component of the dithering vector to use in units of the top-level cell sizes: dithering_ratio (default: 1.0).

For most runs, the default values can be used. Only the number of cells along each axis needs to be specified. The mesh dithering is only used for simulations using periodic boundary conditions and in the absence of an external potential. At each tree rebuild time, all the particles are moved by a random vector (the same for all particles) and the periodic BCs are then applied. This reduces the correlation of erros across time. The remaining three values are best described in the context of the full set of equations in the theory documents.

As a summary, here are the values used for the EAGLE 100^3~{\rm Mpc}^3 simulation:

# Parameters for the self-gravity scheme for the EAGLE-100 box
Gravity:
  eta:                    0.025
  theta:                  0.6
  mesh_side_length:       512
  comoving_DM_softening:         0.0026994  # 0.7 proper kpc at z=2.8.
  max_physical_DM_softening:     0.0007     # 0.7 proper kpc
  comoving_baryon_softening:     0.0026994  # 0.7 proper kpc at z=2.8.
  max_physical_baryon_softening: 0.0007     # 0.7 proper kpc
  rebuild_frequency:      0.01   # Default optional value
  a_smooth:          1.25        # Default optional value
  r_cut_max:         4.5         # Default optional value
  r_cut_min:         0.1         # Default optional value
  dithering:         1           # Default optional value
  dithering_ratio:   1.0         # Default optional value

SPH

The SPH section is used to set parameters that describe the SPH calculations. There are some scheme-specific values that are detailed in the :ref:`hydro` section. The common parameters are detailed below.

In all cases, users have to specify two values:

• The smoothing length in terms of mean inter-particle separation: resolution_eta
• The CFL condition that enters the time-step calculation: CFL_condition

These quantities are dimensionless. The first, resolution_eta, specifies how smooth the simulation should be, and is used here instead of the number of neighbours to smooth over as this also takes into account non-uniform particle distributions. A value of 1.2348 gives approximately 48 neighbours in 3D with the cubic spline kernel. More information on the choices behind these parameters can be found in Dehnen & Aly 2012.

The second quantity, the CFL condition, specifies how accurate the time integration should be and enters as a pre-factor into the hydrodynamics time-step calculation. This factor should be strictly bounded by 0 and 1, and typically takes a value of 0.1 for SPH calculations.

The next set of parameters deal with the calculation of the smoothing lengths directly and are all optional:

• Whether to use or not the mass-weighted definition of the SPH number of neighbours: use_mass_weighted_num_ngb (Default: 0)
• The (relative) tolerance to converge smoothing lengths within: h_tolerance (Default: 1e-4)
• The maximal smoothing length in internal units: h_max (Default: FLT_MAX)
• The minimal allowed smoothing length in terms of the gravitational softening: h_min_ratio (Default: 0.0, i.e. no minimum)
• The maximal (relative) allowed change in volume over one time-step: max_volume_change (Default: 1.4)
• The maximal number of iterations allowed to converge the smoothing lengths: max_ghost_iterations (Default: 30)

These parameters all set the accuracy of the smoothing lengths in various ways. The first one specified what definition of the local number density of particles to use. By default, we use

n_i = \sum_j W(\|\mathbf{r}_i - \mathbf{r}_j\|, h_i)

but switching on the use_mass_weighted_num_ngb flag changes the defintion to:

n_i = \frac{\rho_i}{m_i}

where the density has been computed in the traditional SPH way (i.e. \rho_i = \sum_j m_j W(\|\mathbf{r}_i - \mathbf{r}_j\|, h_i)). Note that in the case where all the particles in the simulation have the same mass, the two definitions lead to the same number density value.

We dot not recommend using this alternative neighbour number definition in production runs. It is mainly provided for backward compatibility with earlier simulations.

The second one, the relative tolerance for the smoothing length, specifies the convergence criteria for the smoothing length when using the Newton-Raphson scheme. This works with the maximal number of iterations, max_ghost_iterations (so called because the smoothing length calculation occurs in the ghost task), to ensure that the values of the smoothing lengths are consistent with the local number density. We solve:

(\eta \gamma)^{n_D} = n_i

with \gamma the ratio of smoothing length to kernel support (this is fixed for a given kernel shape), n_D the number of spatial dimensions, \eta the value of resolution_eta, and n_i the local number density. We adapt the value of the smoothing length, h, to be consistent with the number density.

The maximal smoothing length, by default, is set to FLT_MAX, and if set prevents the smoothing length from going beyond h_max (in internal units) during the run, irrespective of the above equation. The minimal smoothing length is set in terms of the gravitational softening, h_min_ratio, to prevent the smoothing length from going below this value in dense environments. This will lead to smoothing over more particles than specified by \eta.

The final set of parameters in this section determine the initial and minimum temperatures of the particles.

• The initial temperature of all particles: initial_temperature (Default: InternalEnergy from the initial conditions)
• The minimal temperature of any particle: minimal_temperature (Default: 0)
• The mass fraction of hydrogen used to set the initial temperature: H_mass_fraction (Default: 0.755)
• The ionization temperature (from neutral to ionized) for primordial gas, again used in this conversion: H_ionization_temperature (Default: 1e4)

These parameters, if not present, are set to the default values. The initial temperature is used, along with the hydrogen mass fraction and ionization temperature, to set the initial internal energy per unit mass (or entropy per unit mass) of the particles.

Throughout the run, if the temperature of a particle drops below minimal_temperature, the particle has energy added to it such that it remains at that temperature. The run is not terminated prematurely. The temperatures specified in this section are in internal units.

The full section to start a typical cosmological run would be:

SPH:
  resolution_eta:           1.2
  CFL_condition:            0.1
  h_tolerance:              1e-4
  h_min_ratio:              0.1
  initial_temperature:      273
  minimal_temperature:      100
  H_mass_fraction:          0.755
  H_ionization_temperature: 1e4

Stars

The Stars section is used to set parameters that describe the Stars calculations when doing feedback or enrichment. Note that if stars only act gravitationally (i.e. SWIFT is run without --feedback) no parameters in this section are used.

The first four parameters are related to the neighbour search:

• The (relative) tolerance to converge smoothing lengths within: h_tolerance (Default: same as SPH scheme)
• The maximal smoothing length in internal units: h_max (Default: same as SPH scheme)
• The minimal allowed smoothing length in terms of the gravitational softening: h_min_ratio (Default: same as SPH scheme)
• The maximal (relative) allowed change in volume over one time-step: max_volume_change (Default: same as SPH scheme)

These four parameters are optional and will default to their SPH equivalent if left unspecified. That is the value specified by the user in that section or the default SPH value if left unspecified there as well.

The two remaining parameters can be used to overwrite the birth time (or scale-factor) of the stars that were read from the ICs. This can be useful to start a simulation with stars already of a given age. The parameters are:

• Whether or not to overwrite anything: overwrite_birth_time (Default: 0)
• The value to use: birth_time

If the birth time is set to -1 then the stars will never enter any feedback or enrichment loop. When these values are not specified, SWIFT will start and use the birth times specified in the ICs. If no values are given in the ICs, the stars' birth times will be zeroed, which can cause issues depending on the type of run performed.

Time Integration

The TimeIntegration section is used to set some general parameters related to time integration. In all cases, users have to provide a minimal and maximal time-step size:

• Maximal time-step size: dt_max
• Minimal time-step size: dt_min

These quantities are expressed in internal units. All particles will have their time-step limited by the maximal value on top of all the other criteria that may apply to them (gravity acceleration, Courant condition, etc.). If a particle demands a time-step size smaller than the minimum, SWIFT will abort with an error message. This is a safe-guard against simulations that would never complete due to the number of steps to run being too large. Note that in cosmological runs, the meaning of these variables changes slightly. They do not correspond to differences in time but in logarithm of the scale-factor. For these runs, the simulation progresses in jumps of \Delta\log(a). dt_max is then the maximally allowed change in \Delta\log(a) allowed for any particle in the simulation. This behaviour mimics the variables of the smae name in the Gadget code.

When running a non-cosmological simulation, the user also has to provide the time of the start and the time of the end of the simulation:

• Start time: time_begin
• End time: time_end

Both are expressed in internal units. The start time is typically set to 0 but SWIFT can handle any value here. For cosmological runs, these values are ignored and the start- and end-points of the runs are specified by the start and end scale-factors in the cosmology section of the parameter file.

Additionally, when running a cosmological volume, advanced users can specify the value of the dimensionless pre-factor entering the time-step condition linked with the motion of particles with respect to the background expansion and mesh size. See the theory document for the exact equations. Note that we explicitly ignore the Header/Time attribute in initial conditions files, and only read the start and end times or scale factors from the parameter file.

• Dimensionless pre-factor of the maximal allowed displacement: max_dt_RMS_factor (default: 0.25)

This value rarely needs altering.

A full time-step section for a non-cosmological run would be:

TimeIntegration:
  time_begin:   0    # Start time in internal units.
  time_end:     10.  # End time in internal units.
  dt_max:       1e-2
  dt_min:       1e-6

Whilst for a cosmological run, one would need:

TimeIntegration:
  dt_max:            1e-4
  dt_min:            1e-10
  max_dt_RMS_factor: 0.25     # Default optional value

Initial Conditions

The InitialConditions section of the parameter file contains all the options related to the initial conditions. The main two parameters are

• The name of the initial conditions file: file_name,
• Whether the problem uses periodic boundary conditions or not: periodic.

The file path is relative to where the code is being executed. These parameters can be complemented by some optional values to drive some specific behaviour of the code.

• Whether to generate gas particles from the DM particles: generate_gas_in_ics (default: 0),
• Whether to activate an additional clean-up of the SPH smoothing lengths: cleanup_smoothing_lengths (default: 0)

The procedure used to generate gas particles from the DM ones is outlined in the theory documents and is too long for a full description here. The cleaning of the smoothing lengths is an expensive operation but can be necessary in the cases where the initial conditions are of poor quality and the values of the smoothing lengths are far from the values they should have.

When starting from initial conditions created for Gadget, some additional flags can be used to convert the values from h-full to h-free and remove the additional \sqrt{a} in the velocities:

• Whether to re-scale all the fields to remove powers of h from the quantities: cleanup_h_factors (default: 0),
• Whether to re-scale the velocities to remove the \sqrt{a} assumed by Gadget : cleanup_velocity_factors (default: 0).

The h-factors are self-consistently removed according to their units and this is applied to all the quantities irrespective of particle types. The correct power of h is always calculated for each quantity.

Finally, SWIFT also offers these options:

• A factor to re-scale all the smoothing-lengths by a fixed amount: smoothing_length_scaling (default: 1.),
• A shift to apply to all the particles: shift (default: [0.0,0.0,0.0]),
• Whether to replicate the box along each axis: replicate (default: 1).

The shift is expressed in internal units. The option to replicate the box is especially useful for weak-scaling tests. When set to an integer >1, the box size is multiplied by this integer along each axis and the particles are duplicated and shifted such as to create exact copies of the simulation volume.

The full section to start a DM+hydro run from Gadget DM-only ICs would be:

InitialConditions:
  file_name:  my_ics.hdf5
  periodic:                    1
  cleanup_h_factors:           1
  cleanup_velocity_factors:    1
  generate_gas_in_ics:         1
  cleanup_smoothing_lengths:   1