Output

This page describes Cholla data, and contains some brief examples of plotting, etc. The first part deals with finite-volume data (average values in a cell represented on a grid), the second part deals with particle outputs (i.e. star or dark matter particles).

By default, Cholla outputs files in the hdf5 format. A single hdf5 file will generally correspond to a single snapshot from a simulation (or a subset of the simulation domain for an MPI simulation). Information in the file is split between "attributes", which are header variables that describe the data, and "datasets", which hold the values of the simulation data itself.

Attributes

The following attributes are attached to all Cholla outputs:

• 'gamma', the ratio of specific heats that the simulation was run with
• 't', the time of the snapshot, in code units (usually kyr)
• 'dims', a three dimensional attribute that gives the number of cells in the x, y, and z directions
• 'n_step', the simulation step when the data was output

Additional attributes that are attached to newer Cholla outputs include:

• 'dx', a three dimensional attribute that gives the x, y, and z dimensions of a cell, in code units,

and a series of "unit" attributes, that provide the conversion between whatever units the code was run in and cgs:

• 'length_unit'
• 'time_unit'
• 'mass_unit'
• 'density_unit'
• 'velocity_unit'
• 'energy_unit'

So, for example, if the code was run with a mass unit of one solar mass and a length unit of one kpc, and you have read the density into an array called 'd', multiplying d by the density unit would convert the density array to g/cm^3.

Datasets

Datasets contain the different fields that are evolved by the simulation. They are 1, 2, or 3 dimensional arrays, corresponding to the dimensionality of the simulation (and specified by the nx, ny, nz attributes, as described above). The following are the conserved variable fields that are always outputs for a hydrodynamic simulation (all output in code units):

• 'density', the mass density in each cell (i.e. M_sun / kpc^3)
• 'momentum_x', the x-momentum density
• 'momentum_y', the y-momentum density
• 'momentum_z', the z-momentum density
• 'Energy', the total energy density

If Cholla is run with the dual energy flag ('DE'), the thermal energy field will also be present:

• 'GasEnergy', the thermal energy density, equivalent to the total energy density minus the kinetic energy density.

If Cholla is run with the passive scalar flag ('SCALAR'), a number of scalar fields may also be present, e.g.:

• 'scalar0', the value of the first passive scalar.

If Cholla is run with 'DUST':

• 'dust_density', the dust density in code units (M_sun / kpc^3)

Slices, Projections, and Rotated Projections

For 3D simulations, Cholla can also be run with flags to output slices and projections of the data. (This can be useful for larges simulations if saving the full dataset is too costly to achieve a high time resolution for snapshots.) The relevant make flags are 'SLICES', 'PROJECTIONS', and 'ROTATED_PROJECTIONS'. All produce hdf5 files similar to full grid outputs, with the same header attributes. Datasets present in slices include all the conserved variables, as well as the thermal energy density and scalars, if the simulation was run with them. Three slices will be output: 'xy' slices (a slice along the z-midplane), 'xz' slices (and a slice along the y midplane), and 'yz' slices (a slice along the x midplane). Datasets in the hdf5 file are named according to which direction the slice was made. For example, datasets in a 'slice_xy' file will include:

• 'd_xy', the mass density in cells along the z-midplane of the simulation
• 'mx_xy'
• 'my_xy'
• 'mz_xy'
• 'E_xy'
• 'GE_xy' (if DE is on)
• 'scalar_xy' (if SCALAR is on)

Projections are similar to slices in that they are 2 dimensional datasets, but are integrated along the relevant direction. Currently, Cholla outputs density projections, and density-weighted temperature projections (density times temperature for a given cell). Both are output in code units. So, for example, if the code was run with density units of M_sun/kpc^3, a density projection output will have units of M_sun / kpc^2 and a temperature projection will have units of M_sun K / kpc^2. The PROJECTIONS flag outputs xy and xz projections (integrated along the z and y axes, respectively). Datasets are called:

• 'd_xy'
• 'T_xy'
• 'd_xz'
• 'T_xz'
• 'd_dust_xy', (if 'DUST' was used)
• 'd_dust_xz', (if 'DUST' was used)

Rotated projections are similar, but are integrated along an axis specified by the input parameter file (see the relevant wiki page for details).

Particle data

TODO

Concatenation scripts

Under python_scripts are a variety of scripts useful for concatenating multi-rank inputs into a single file.

The following are provided as scripts with a CLI or they can be imported as a module and used in other python programs

• concat_2d_data.py, for concatenating 2D datasets such as slices, projections, and rotated projections
• concat_3d_data.py, for concatenating 3D datasets
• concat_particles.py, for concatenating particle datasets

CLI Usage

The CLI for all the scripts is similar and details can be found when passing the --help option to the script. In general you need to tell the script which directory to read files from (the -s/--source-directory flag), where to write the concatenated files (the -o/--output-directory flag), how many ranks were used (the -n/--num-processes flag), and which outputs to concatenate (the -c/--concat-outputs flag). The -c flag accepts a couple of different input formats, it can be a single number (e.g. 8), a range (e.g. 2-9), or a list (e.g. [1,2,3]); ranges are inclusive.

Example

./concat_3d_data.py -s /PATH/TO/SOURCE/DIRECTORY/ -o /PATH/TO/DESTINATION/DIRECTORY/ -n 8  -c 0-10

Import Usage

The scripts above contain three public functions, concat_2d_dataset, concat_3d_dataset, and concat_particles_dataset. These functions will each concatenate a single output time of a 2D, 3D or particle dataset respectively and can be imported into another python program assuming the scripts are in your python path. Generally the easiest way to import this script is to add the python_scripts directory to your python path in your script like this:

import sys
sys.path.append('/PATH/TO/CHOLLA/python_scripts')
import concat_3d_data