Make your own HDF5 formatted simulation data

SimSpin attempts to be agnostic to the type of simulation file input (as the aim is to produce a comparable data product for all simulations).

---

Currently, SimSpin has ability to support:

• Gadget2 simulation outputs written in binary class 1.
• Gadget2 simulation outputs written in HDF5.
• Galaxies cut from the EAGLE simulation and written to HDF5 using the read_eagle routines.
• Galaxies cut from the Magneticum simulation and written to HDF5 using the g3read routines.

The are two possible options available if you would like to use a different simulation output. Either raise an issue on GitHub using the button below, or read on to learn how to write your own HDF5 file.

Raise an issue Write your own HDF5

---

Write your own

Hierarchical Data Format version 5 files (or HDF5 files) are designed to store large amounts of data in a structured way. For astronomers, the format is very similar to FITS files.

A single file contains Groups and Datasets, as well as Metadata information that records details about each group or dataset. A Group is like a folder or directory. It can contain Datasets of arbitrary size, or other Groups.

For simulation outputs in HDF5 format, we have individual Groups for each particle type, as well as a Header that contains the metadata summary for the full file. For each particle type, we use the PartType definitions from Gadget (Springel, 2005), with each contained group listed here:

• Header
• PartType0 - gas,
• PartType1 - dark matter,
• PartType2 - N-body disk,
• PartType3 - N-body bulge,
• PartType4 - stars,
• PartType5 - boundary/black holes.

Within each of these groups, properties such as positions and velocities are stored for particles of that type. The specific properties contained depend on the type of simulation input. We provide examples here for a galaxy cut out from a hydrodynamical simulation and from an N-body simulation.

Hydrodynamic Example N-body Example

---

Hydrodynamical Simulations

Here we discuss the tables included for each particle type within an input hydrodynamical simulation HDF5 file.

The following simulations are already supported for automatic read in, with example files available within the R-package.

These files must contain the following groups:

• Header
• PartType0 (i.e. gas particles/cells)
• PartType4 (i.e. stellar particles)

Any additional groups (such as those describing the number of dark matter and black hole properties) will not be used within SimSpin at this time and as a result will be ignored if provided within the input simulation file.

If PartType0 or PartType4 are mising entirely from the file, it is assumed that there are no particles of this type within the simulation cut-out. If a Header is not provided, the code will return an error.

See example files for specific EAGLE, Magneticum and HorizonAGN formatting below.

EAGLE file Magneticum file HorizonAGN file

Header

The header for each hydrodynamic simulation contains atrributes that record the information necessary for SimSpin to distinguish the input simulation type. It also contains information about the properties of the simulation from which the galaxy has been extracted. In particular, there are a number of attribute elements that are important to include within the Header group:

Other properties are often included as default. These will be ignored by make_simspin_file, so can be left as is, or trimmed to reduce the HDF5 file size. Below we show examples of the header information for each of our example files within SimSpin.

¹ If RunLabel is missing from the header of the file, SimSpin will assume that the input file is an N-body simulation and look for stellar components in the bulge and disk Groups (PartType2 and PartType3). Ensure that a value is listed under this attribute if the underlying simulation is a hydrodynamical simulation with stellar particles listed in PartType4.

Attributes

Each property in the following PartType groups have associated attributes that define the units of that property. These allow you convert from co-moving properties output by the simulation into the physical cordinates in which we would like to work for individual galaxies. The following attributes are expected and used to convert the properties into CGS (centimeter-grams-seconds) units for SimSpin processing:

Using the following formula, we can then convert the values within the input file into CGS:

where a is the scale factor at the snapshot (i.e. a = 1/(1+z)), *h is the Hubble parameter, the simulation parameter is the value returned from that table for a given particle, and the physical parameter is the output value in CGS units. This is done automatically in the make_simspin_file function and so it is important that these attributes are listed against each table correctly.

If your parameters are already in physical units, these values can simply be set to:

• CGSConversionFactor = Constant required to convert into CGS units
• aexp-scale-exponent = 0
• h-scale-exponent = 0

It has been noticed that some IllustrisTNG has different names for these conversion factors. SimSpin will automatically accept either the default outputs from IllustrisTNG (a_scaling, h_scaling and to_cgs) or the named parameters above. The to_cgs factor output by IllustrisTNG is sometimes 0 within their HDF5 outputs. This will result in all values read in by SimSpin to become 0. To avoid this, SimSpin will take to_cgs = 0 and assume this indicates that the values are already in CGS units (i.e. CGSConversionFactor = 1).

This will then read simply within the current architecture of the code.

PartType0

This group contains a series of Datasets describing the gas particle/cell properties. Each of these Datasets should have the attributes described here.

For a mock observation to be constructed with SimSpin, the following Datasets will be used for processing. These Datasets will be in table format with shape described relative to the number of gas particles in that simulation file, N_gas.

Necessary Datasets for functionality are indicated by the ★ symbol. For Datasets without a ★, some may be required for cell-based codes and others for particle-based codes. These are further elaborated in the connected footnotes.

Further properties can be passed into SimSpin without error, but in the case that one of these necessary groups is missing the code will return an error.

¹ This element of the HDF5 file is a group ElementAbundance containing a further three groups (Carbon, Oxygen, and Hydrogen) that contain data tables.

² Some simulations use different default names for individual datasets. For EAGLE outputs, these Group names will be prefixed with the name “Smoothed” to indicate that the parameters have been smoothed across the SPH smoothing kernel volume, as this is suggested to be the more appropriate output value to use when working with EAGLE outputs as in Wiersma et al. 2009. In IllustrisTNG, these names will be prefixed with “GFM_”. SimSpin is equipped to interpret these fields as intended such that you can choose to use the default field names rather than the ones listed here.

³ For cell-based codes, the SmoothingLength value will not be present in output files. To approximate the variable smoothing of cells across the pixelated image, SimSpin will compute an equivalent SmoothingLength for cell-based codes using the Mass and Density fields.

⁴ For cell-based gas simulations, the temperature for each cell can be approximated using the InternalEnergy and ElectronAbundance properties. In this case, the Temperature Group is not required as long as the InternalEnergy and ElectronAbundance Groups are present. Equally, the ElectronAbundance Group is not required if Temperature is already present. We note here that caution should be taken when using output gas temperatures for the simulations as there are cooling floors employed in most hydrodynamical simulations that cause an artificial lower temperture limit. This is particularly important for low density and low temperature gas, as well as star-forming gas.

⁵ Gas within a simulation has a thermal contribution to the observable velocity dispersion that must be included to give a realistic representation of the true gas dispersion. To quantify the thermal contribution to this, we use \(\sigma_{\text{thermal}}^2 = P / \rho = u (1 - \gamma)\), where the thermal dispersion contribution can be computed using either the pressure and denisty, or the internal energy. For particles with temperature below the cooling floor of the simulation, this vlaue is fixed to an isotropic thermal value of 11 km/s.

PartType4

This group contains Datasets describing the stellar particle properties. Each of these Datasets should have the attributes described here.

These Datasets will be in table format with shape described relative to the number of gas particles in that simulation file, N_star. All listed Datasets in the table below are required for functionality.

Further properties can be passed into SimSpin without error, but in the case that one of these groups is missing the code will return an error.

¹ The Magneticum simulations give Metallicity as a table of raw metal masses rather than a metallicity in the form Z = M_Z / M_total. This is accounted for when read into SimSpin.

² In the case that StellarFormationTime is negative (as is used to denote stellar wind particles in IllustrisTNG), SimSpin will remove these rows in all Dataset tables.

---

N-body Simulations

SimSpin was originally designed to work with N-body models produced using Gadget2.

When using binary or HDF5 N-body outputs from Gadget2, SimSpin will work with the raw output simulation files without modification. We list the parameters recovered for each particle flavour below in case a user would like to apply SimSpin to non-Gadget N-body models. This is only described for HDF5 files, but for interested parties, the Gadget2 binary format is quite clearly deconstructed in the lines of code here.

Header

The Header block for output Gadget2 N-body models contain the following attributes, as listed in Table 4 of the User’s guide for GADGET-2:

Note that the RunLabel attribute is missing in this Header. This is used as an indication to SimSpin that the input HDF5 file is from an N-body code, rather than a hydrodynamical code. SimSpin then looks for Groups under the heading PartType2 and PartType3 for the stellar component of the galaxy.

PartType2

When run in N-body mode, the PartType2 Group is reserved for disk particles, i.e. particles initialised with disk-like distribution functions.

Within SimSpin, we assume that these particles trace a species of stars and will combine any particles in this group with any in PartType3 bulge stars to form the stellar component table for analysis.

Metallicities and ages are assigned to N-body disk particles in the make_simspin_file function seperately to the bulge particles. Hence, the necessary Datasets within the Group only include:

Further properties can be passed into SimSpin without error, but in the case that one of these groups is missing the code will return an error.

PartType3

When run in N-body mode, the PartType3 Group is reserved for bulge particles, i.e. particles initialised with bulge-like distribution functions.

Within SimSpin, we assume that these particles trace a species of stars and will combine any particles in this group with any in PartType2 disk stars to form the stellar component table for analysis.

Metallicities and ages are assigned to N-body bulge particles in the make_simspin_file function seperately to the disk particles. Hence, the necessary Datasets within the Group include only:

Further properties can be passed into SimSpin without error, but in the case that one of these groups is missing the code will return an error.

---

This concludes the description of input file types supported in SimSpin at the current time. Check back here in the future for further simulation support developments.

If you would like us to formally integrate your simulation format into SimSpin, please get in contact by raising an issue:

Raise an issue!

---