About

Subsweep is a code for postprocessing of astrophysical simulations using the sweep method for radiative transfer.

Installation

The rust nightly toolchain is required to install subsweep.

rustup default nightly

With the nightly toolchain, subsweep can be compiled via cargo

cargo build --release

To run the test suite:

cargo test

For production runs, building with LTO enabled is recommended (compilation can take a long time).

cargo build --release-lto

General Usage

Subsweep takes output from cosmological simulations (Currently only read-in of Arepo output is supported, but extensions are straightforward) and performs radiative transfer coupled with radiation chemistry. This process works as follows:

1. The initial conditions (simulation output of coordinates, densities, temperatures and chemical composition) are read. This also includes the source terms for radiative transfer.
2. Domain decomposition of the loaded particles from the ICs.
3. If desired, temperatures and chemical composition will be remapped from the output of a previous subsweep run (useful for chained runs).
4. A voronoi grid over the particles is either constructed or read from a grid file. In the latter case, the grid file can be generated by running Arepo using the sweep-write-grid branch. Whether the grid is constructed or read is determined by the simulation parameters.
5. Using the grid, radiative transfer and chemistry updates are performed until the desired final time. Output snapshots are written at regular intervals.

Parameters

Subsweep requires a single parameter file in yaml format (called params.yml unless explicitly specified otherwise). An example parameter consists of individual sections and might read as follows:

box_size: 4000 kpc h^-1 a^-1
postprocess:
  initial_fraction_ionized_hydrogen: 1e-10
  sources: !from_ics
    escape_fraction: 0.01
  grid: !construct
  remap_from: ../0/output/snapshots
sweep:
  directions: 84
  num_timestep_levels: 4
  significant_rate_threshold: 1.0e-5 s^-1
  timestep_safety_factor: 0.1
  check_deadlock: false
  max_timestep: 1 Myr
  periodic: true
output:
  time_between_snapshots: 1 Myr
  handle_existing_output: delete
input:
  paths:
  - ics/snap_0.1.hdf5
  - ics/snap_0.2.hdf5
  - ics/snap_0.3.hdf5
simulation:
  final_time: 5.0 kyr
cosmology:
  a: 0.3781
  h: 0.6774
  params:
    omega_lambda: 0.6911
    omega_0: 0.308983

• box_size: Specifies the size of the simulation box. Accepted units are either a length (for non-comoving runs) or a comoving length (length times h^-1 a^-1) for runs in which the original simulation is comoving and should be rescaled according to the cosmology.
• postprocess:
• • initial_fraction_ionized_hydrogen: Initial ionization fraction which is set for every particle. Only useful when not remapping from a previous output.
• • sources: How the source terms should be determined. For non-test runs, the only relevant option is !from_ics, in which case the escape_fraction parameter specifies a factor by which the computed source terms should be multiply for account for unresolved overdensities surrounding the sources.
• • grid: either !construct if the grid should be constructed or !read GRID_FILE if the grid should be read from GRID_FILE
• • remap_from: If given, specifies a file or a folder (in which case all the hdf5 files in the folder are used) from which to remap temperatures and ionization fractions.
• sweep:
• • directions: The number of directions to use. More means higher angular resolution at the cost of memory and runtime. Supported values: 1, 16, 21, 32, 64, 84
• • num_timestep_levels: How many levels of substepping to use. If 1, sweeps and chemistry updates are always done at level 0, using the max_timestep (the chemistry will internally substep if required). If n > 1, particles will be distributed onto the available levels i=0..n-1 according to their desired timesteps. The timestep of level i is given by max_timestep * 2^-i. The desired timestep is computed as the minimum of the timescales at which the 1. ionization fraction, 2. temperature and 3. photon rates change.
• • significant_rate_threshold: The minimum number of photons per second which will be treated as non-zero. A non-zero value (~1.0e-5 / s) is recommended for performance reasons.
• • timestep_safety_factor: The ratio of desired timestep to computed timescale at which the fastest changing quantity changes. Smaller values mean more accurate results but come at the cost of performance since more particles will move to lower timesteps.
• • check_deadlock: Defaults to false. If true, check for deadlocks before sweeping. This is mostly meant for debugging.
• • max_timestep: The maximum sweep timestep (i.e. the timestep that level 0 particles will be updated with).
• • periodic: Whether periodic boundary conditions are enabled. If true, fluxes leaving the box on one side will re-enter on the other. In the current code, this is not done iteratively but fluxes from previous timesteps are used as inputs to the next one, which usually gives good convergence to a periodic result.
• output:
• • time_between_snapshots: The simulated time between two snapshots. Should be commensurate with max_timestep if regular snapshots are desired.
• • handle_existing_output: What to do if the output folder already exists (which happens when re-running a simulation in the same folder). Options: panic, overwrite, delete. For large runs, panic is recommended, to avoid accidental deletion.
• • time_first_snapshot [Optional]: The simulated time at which to output the first snapshot. If left out, begin writing snapshots immediately.
• • output_dir [Optional]: The name output folder. Defaults to "output".
• • snapshots_dir [Optional]: The name of the snapshot folder within the output folder. Defaults to "snapshots".
• • time_series_dir [Optional]: The name of the time series folder within the output folder. Defaults to "time_series".
• • performance_data_filename [Optional]: The name of the file to which performance data, such as total runtime and runtime of individual parts of the code should be written. Defaults to performancy.yml.
• • used_parameters_filename [Optional]: The name of the file in the output folder into which the used parameters are written. Defaults to params.yml.
• • fields [Optional]: Which fields to include in the snapshots. Defaults to all. Alternatively, specify a list of field names, for example: ["position", "ionized_hydrogen_fraction"]
• • snapshot_padding [Optional]: Determines to how many digits the snapshot numbers should be zero-padded.
• input:
• • paths: A list of files from which to read the initial conditions.
• simulation:
• • final_time: The time at which the simulation should be stopped. If not specified, run indefinitely.
• cosmology: The cosmology to use when re-scaling quantities in the ICS. Defaults to present time (a = 1). If cosmological runs are used, specify a (scale factor) and h (hubble parameter in units of 100 km / s / Mpc). If remapping is performed, the cosmological parameters omega_lambda and omega are required as well.