Sfrhist config and output file format

This page documents the keywords recognized by sfrhist and the format of the output fits file. (The output file description is currently quite out of date. If you notice discrepancies, please update this file.)

Sfrhist calculates the SEDs of the stellar and black hole sources and generates the adaptive mesh refinement grid structure. Sfrhist takes a configuration filename as its only argument. The configuration file consists of keyword-value pairs which are used to control the behavior of the program. String values are shell-expanded, so environment variables like $HOME and ~ can be used.

Typically one should keep keywords that do not change from snapshot to snapshot in a general "stub" file (e.g., sfrhist.stub). Each snapshot should have a configuration file (e.g., sfrhist_001.config) that contains the simulation-specific parameters and use the line

include\_file    sfrhist.stub

to include all keywords in the stub file. An example sfrhist config file is

include\_file      sfrhist.stub
snapshot\_file   snapshot\_001
output\_file       sfrhist\_001.fits

Config keywords

The basic keywords for loading the snapshot data (with example values) are:

• snapshot_file snapshot_000

  The name of the snapshot file to process. This can either be a Gadget "type 1" snapshot, a Gadget HDF5 (if it ends with .hdf5 and Sunrise was compiled with HDF5 support), or if nbodycod=pkdgrav, a Gasoline snapshot in TIPSY format.

• output_file grid_000.fits

  The output file, containing the SEDs and the grid data.

• nbodycod GADGET # we are working with GADGET snapshots

  Specifies which nbody code was used to generate the snapshots. This is how sfrhist knows where to find different pieces of information. Supported alternatives are: GADGET, pkdgrav, arepo, and yt (this means loading an output from YT, which can be used to load snapshots from both Enzo and ART).

• load_gas
• load_disk
• load_bulge
• load_nstar
• load_dm
• load_bh

  These keywords all default to true and can be used to prevent any of the species of particles for being loaded. Tipsy files only have gas and nstar particles. Note that load_dm can presumably safely be set to false always, since it has no function in this context. (However, this doesn't work if you also specify the ic_ keywords below. Then all particles must be loaded or the code will crash.)

• simparfile Z2m2x-n6.txt / GADGET parameter file

  Specifies the name of the file containing the nbody simulation parameters. This keyword is only required if you are loading a GADGET or Arepo snapshot, in which case it will read the necessary quantities like the simulation units and gravitational softening lengths from this file.

• UnitLength_in_cm
• UnitMass_in_g
• UnitVelocity_in_cm

  These keywords describe the conversion from snapshot units to physical units. For GADGET files, they are taken from the parameter file. For TIPSY files, they must be specified in the config file.

• snaptime

  When reading TIPSY files, the time of the snapshot (in internal simulation units) must be supplied with this keyword, because those files do not contain a physical time.

• comoving_units false

  If the lengths in the input file are in comoving units, this keyword must be set to true, and for GADGET files the expansion factor must be supplied with the "expansion_factor" keyword. (This used to be called "expansion" when reading TIPSY files, but was changed to this more descriptive name.) Note that GADGET simulations that were run with ComovingIntegrationOn in addition must have the snapshot time and formation times of stellar particles converted to time in snapshot units, because Sunrise does not contain code for calculating cosmology.

• h-inverse_units false

  If the snapshot quantities are in h^-1 units, then this keyword must be set to true. This effectively means that the length, mass and time units are divided by h0, so the physical quantities become bigger. This only applies to GADGET files, and then the value of h0 in the snapshot file is used. All Sunrise output quantities are in physical units.

Keywords describing the stellar population SED library

• stellarmodelfile ~patrik/dust_data/stellarmodel/Patrik-imfKroupa-Zmulti-ml.fits

  The file containing the stellar model (generated by convertstellarmodel).

• mappings_sed_file

  The file containing the SEDs of the MAPPINGS models describing the star-forming regions (ie young stars).

• mappings_pdr_fraction
• mappings_mcl

  Parameters of the mappings models, see JGC10 or Groves et al. 2008.

• use_mappings_seds

  If false, the SEDs will be resampled onto the MAPPINGS wavelength grid, but only the stellar model SEDs will be used. This is handy if you want to generate a completely dust-free spectrum with the same wavelength grid as the dust runs. (Note that in this case, it doesn't really make sense to run any scatter rays, since then you have an inconsistent model that has diffuse dust but not in the star-forming regions.)

• mappings_pdr_file

  Specifies the name of a file that contains the sizes of the HII regions. Setting this makes sfrhist print a bunch of diagnostic info about the sizes and masses enclosed (see discussion in Section 2.3 of Jonsson, Groves & Cox 2010)

• cluster_mappings_particles

  If true, and mappings_pdr_file is specified, this will perform a clustering analysis of the mappings particles so that particles whose PDRs overlap will be treated as one large stellar cluster. This somewhat alleviates the concern about having many overlapping, technically independent HII regions in regions of high SFR, but has not been extensively tested. Note that this will have no effect on mappings particles which are already saturated (have the maximum compactness parameter of the Groves models). Look for warnings about this in the sfrhist output.

• min_wavelength/max_wavelength

  These define the wavelength range of the SEDs. Useful if you want to do a small wavelength range with very high resolution, for example, because some significant components of the memory required and size of output FITS files scale with number of wavelengths.

Keywords describing SF history and metallicity for preexisting stars

In GADGET, there are "bulge" and "disk" stars that are present at the start of the simulation, so they don't have formation times or metallicities. These keywords describe the assumptions sfrhist uses to calculate the SED's of these particles. GASOLINE has only one kind of star particle, so the following is not applicable in that case.

While it's possible to assign initial metallicities to the gas particles, that was not done in the majority of the simulations processed with Sunrise. Hence, the metallicity distribution of the initial gas particles must be defined in sfrhist, and because the metallicities of the formed star particles is derived from the gas particles from which they are spawned, we must trace the ID of the parent gas particle. Furthermore, we want to assign a radially varying metallicity, so sfrhist must be able to deduce the radius of the particles in the initial snapshot. For this to be possible, the t=0 snapshot files of the individual galaxies from which the merger simulation is constructed must be specified. Note: This file can not be the Gadget "initial conditions" file, it needs to be the actual t=0 snapshot file saved when running Gadget on the isolated galaxy. Sfrhist will crash if you ask it to read the actual ic file.

• ic_file<i>

  These keywords specify the snapshot file from which the merger simulation was assembled (or, if there's only one galaxy, that galaxy). The number of particles in the merger snapshot must be at least as large as the sum of the numbers of particles in the specified initial commission snapshots specifies, their ID numbers must be consecutive, and any extra particles not associated with any initial galaxy must come at the end.

For each galaxy component specified above, the following keywords specify the star formation history and metallicity :

• (disk/bulge)popmode<i>

  The star formation history to be used for calculating the SED of the disk/bulge stars. Depending on which mode is chosen, further keywords are necessary to specify the SF history:

  • "constant": a constant star formation rate for a specified amount of time.
    • (disk/bulge)popage<i>: The age of the oldest stars in the population. The ages are randomly drawn from a uniform distribution between simulation time zero and this value.
  • "instantaneous": an instantaneous burst.
    • (disk/bulge)popage<i>: The age of the population (at simulation time zero.)
  • "exponential": an exponentially declining (or increasing) star-formation rate.
    • (disk/bulge)popage<i>: The age of the oldest stars, before which the star-formation rate is assumed to have been zero.
    • (disk/bulge)poptau<i>: The exponential timescale of the star-formation rate. A negative value specifies that the star-formation rate increased up to the simulation start time.
  • "absent": The particles are not included as sources.

• stellar_min_age

• stellar_max_age

  These keywords make it possible to only include particles with an age within a specified interval.

• central_metallicity<i>

  The central metallicity. Applies to both gas particles and bulge/disk stars.

• metallicity_gradient<i>

  The metallicity gradient (in dex/length unit). Negative means metallicity decreases with radius. Applies to both gas particles and bulge/disk stars.

Note: If you wish to use a set of standard initial conditions for many Sunrise runs, you can include the above parameters in separate files (e.g., gal1-b3) and simply include that file in the configuration file by

include_file <path>gal1-b3

You would need a separate file for each progenitor (e.g., gal<i>-b3), where the keywords are numbered appropriately.

Grid creation keywords

Important: Incorrect settings of these parameters can lead to incorrect outputs due to insufficent resolution. Read ConvergenceTests for more information.

These keywords specify the grid creation. (In v2, they were parameters to makegrid.)

• grid_min -100. -100 -100 / kpc
• grid_max 100. 100 100 / kpc
• grid_n (OBSOLETE) 10 10 10 /

  These keywords specify the dimensions of the base grid, which will extend from grid_min to grid_max. Snapshot information outside of this range will be discarded. NOTE: As of v4, the grid is a true octree, which means it always starts with one root cell. This root cell, defined by grid_min and grid_max, must be a cube. Previous versions used a Cartesian base grid with grid_n cells, but this is no longer supported. This also means that if you previously used a grid_n>1, you now have to increase your maxlevel to get the equivalent grid resolution.

• use_grid_emission

  If this is true, the emission of the particles is put in the grid, but if it is false the particles emit directly.

• gas_tolerance 1e100 / .md sigma gas/average gas allowed
• L_bol_tolerance 1e100 / .md sigma L/average L allowed
• metal_tolerance 0.1 / .md sigma metals/average metals allowed

  These three specify the fractional tolerance below which a grid of sub cells will be unified into one larger cell. The number is (standard deviation of quantity in all the top-level sub cells that would be incorporated into one cell)/(average quantity over same cells). Note that the definition is such that if you don't want to use this kind of refinement, you should set them to a large number (e.g., 1e100). (Note that before r2259 (on Google Code) this kind of refinement was turned off by setting the tolerances to 0.)

• n_rays_estimated 10000000 / .md Est. # of rays for tolerance

  The fractional criterion above will keep refining cells that have very little gas or luminosity as long as the fractional non uniformity is large. This is a waste of grid cells as for any finite number of rays, there is a certain threshold below which no rays will be emitted or scattered. This keyword provides a guideline to the program for calculating that threshold. (See J06 for details.)

• opacity 3e-5 / [kpc^2/M_sun] for guessing scatterings

  In order to provide an estimate for how many rays will scatter in a cell, the program needs to know an opacity which translates column density of metals into optical depth. The number 3e-5 is takes from the WD01 dust model. (Assuming 40% of metals are in dust, 1 Msun/kpc^2 of metals will translate to a V-band optical depth of about 3e-5.) Note that this and other keywords here pertain only to the making of the grid, the actual dust parameters are set in mcrx. At this point there is no dust model specified, so specifying these simple scalings is necessary.

• gas_metallicity 0

  The opacity keyword refers to the opacity of metals. If you want to refine also based on gas density then you need to set this keyword. Is normally not used any more. Note that setting this only concerns how gas density is used when refining based on optical depth, it does not actually assign metallicity to gas. That function can be accomplished by the mcrx keyword "dust_to_gas_ratio".

• tau_tolerance 1 / .md

  This is yet another kind of grid tolerance. This specifies the maximum optical depth allowed through a grid cell. The rationale here is that as long as a cell is optically thin, it should have similar dust temperature (barring an intrinsically nonuniform radiation field across the cell, for example due to a nearby point source). Thus we want to limit the optical depth to be below some value. The optical depth is calculated using the opacity and gas metallicity keywords above. (Note that since the opacity specified above typically refers to the V-band opacity, the cells can be optically thick in the UV even if tau_tolerance is ~1.)

• size_factor 2

  This is a fudge factor which is used to specify that it is pointless to create grid cells smaller than this fudge factor times the radius of the smallest particle in the region, as there is no information on smaller scales.

• max_level 11

  This keyword provides an upper limit on how many levels of refinement the grid can have.

• work_chunk_levels 5

  This is a parameter specifying that the work chunks that are distributed among the threads should not contain more than this number of refinement levels. Omitting this parameter will cause horrible load unbalance since then the work chunks will be cells of the base grid which are often very large and will have the majority of the particles in a galaxy in one of them. This value can be as big as you can make it until the runtime for sfrhist starts going up.

• mcrx_data_dir /home/patrik/sunrise/src/

  This specifies the directory containing the interpolator file for mapping the mass of a spherical particle into a cubic cell. This file is in the /src subdirectory when you check it out with svn.

Optional keywords

• runname Sbc11i4-u4/set5as

  This keyword has no function within Sunrise, but I use it to specify a unique identifier for the Gadget simulation and the Sunrise parameter set used. Since it gets copied to the "SFRHIST" HDU, it's then used by my postprocessing software to keep track of the runs, for the navigation on the simulation web site, etc. Since it has to be updated manually, the danger is that you forget...

• translate_origin 1.2 3.4 -5.6

  Translates the origin of the coordinate system in the snapshot to the specified point (ie subtracts this vector from all particle positions).

• center_galaxies

  Translates the origin to the average of the centers of all defined galaxy compontents. This is useful to try to get them all in the camera.

• center_galaxy 0

  Translates the origin to the center of the specified galaxy component. (The component must be specified with an initial snapshot.) Specifying a negative number centers on galaxies which are not part of any component.

• star_radius_factor

  The radius of the stellar particles are set to the gravitational softening length multiplied by this factor.

• ic_directory

  The directory containing the initial conditions files, if they are not in the simulation directory. (This is needed to find the xxx.parameters file which contains the initial conditions parameters.)

• n_threads 16

  The number of threads over which the convolution loop calculation will be distributed. The default value is 1.

• use_counters false

  Specifies whether counters should print to standard out. This is nice if you are running interactively, but makes log files messy for batch jobs. Default is true.

• use_hpm true

  Specifies whether the HPM Toolkit should be used for performance analysis. Default is false.

• save_cellcodes false

  If this is set to true, the Hilbert codes and positions of the cells will be written to the GRIDSTRUCTURE HDU. This makes it possible to figure out the position and size of a cell without needing to replicate the Hilbert ordering, so if you are interested in the grid quantities, you probably want to set this to true.

• bolometric_dump_file

  The name of a file to which information about the particles (position, size, bolometric luminosity, etc.) will be written. Default is not to dump.

• integrated_dump_file

  The name of a file to which the integrated SED of the object will be written, as (lambda, L_lambda) pairs. Default is not to dump.

• dump_grid_structure

  This keyword specifies a filename to which the coordinates of the corners of all the grid cells will be written. This can be used to generate an image of the grid. (This file can be VERY large.) Default is not to dump.

Output file format

The output file is a FITS file. In order to propagate all the necessary input information, it contains a copy of all the HDU's in the input snapshot file except the "OBJECTi" HDU's.

pHDU

The pHDU has the following keywords set:

• FILETYPE "SNAPSHOT"

  The file contains a simulation snapshot.

• DATATYPE "GRID"

  The data is on a grid (as opposed to a particle set).

• GRIDCODE "MAKEGRID"

  Specifies the code which was used to generate the grid, as well as the HDU in which the configuration for the grid generation can be found. Currently, only MAKEGRID is used here.

HDU "MAKEGRID" (or whatever is a specified by GRIDCODE)

This HDU contains the keywords in the input configuration file.

HDU "GRIDSTRUCTURE"

This HDU contains the structure of the octree itself, but no cell data. It is a binary table describing the cells as they are encountered in a depth-first traversal of the octree. It has the following columns (note that unless save_cellcodes is set to true, only the first field is present):

• structure bool

  A true means the cell is refined (and consequently, its octant 0 child is the next entry)

• level uint8

  The refinement level of the cell.

• code uint64

  The integer cell code. If interpreted as an octal number with level digits, it encodes the octants that must be descended from the root node to get to this cell.

• qpos uint32*3

  This is a vector column with 3 32-bit integers encoding the cell position. For a level-n cell, this number is always between 0 and 2^n-1, so the physical 3D position (of the low corner of the cell) can be calculated as qpos/(1<<level).

The HDU also contains the following keywords:

• LENGTHUNIT string

  The length unit in which the grid dimensions are given.

• MINX/Y/Z float

  The lower end of the region the grid is covering.

• MAXX/Y/Z float

  The upper end of the region the grid is covering.

• SUBDIVTP string

  Indicates that type of grid subdivision used. With the v4+, this is always "OCTREE".

The traversal order used in the "structure" column is the same as that used by the grid class iterators, which traverses the tree in Hilbert order. (It's possible to switch this to the old "C-style" ordering by changing one line of code, but that will break the MPI domain decomposition.) The Hilbert order is complicated since each recursion level reorients the octants to create a continuous curve. The order is based on the algorithm described in "Vertex-Labeling Algorithms for the Hilbert Spacelling Curve", Bartholdi & Goldsman, 2000, and the implementation is in the file hilbert.h in libPJutil. The traversal is "depth-first", i.e. if a cell has a "T" is in the structure column, the next row refers to its octant-0 sub-cell.

HDU "GRIDDATA"

This HDU contains the cell data. The ordering is the same as in the GRIDSTRUCTURE HDU. It is a binary table containing the following columns:

• mass_gas double

  The gas mass in the grid cell

• mass_metals double

  The metal mass in the grid cell

• L_bol double

  The bolometric luminosity in the cell

• SFR double

  The star formation rate in the cell

• cell_volume double

  The volume of the cell

• L_lambda n*float

  The SED in the cell. (May be log of values.)

The HDU also contains the following keywords:

• L_bol_tot float

  The total bolometric luminosity in the grid.

• M_g_tot float

  The total gas mass in the grid.

• M_metals_tot float

  The total mass of metals in the grid.

• SFR_tot float

  The total star formation rate in the grid.

The HDU may also contain the keyword "logflux", which if true indicates that the values in the L_lambda column is actually the log10 of the actual values. (The point of this is that the value will fit in a float, whereas the actual luminosity may be a number outside the float range.)

HDU "SFRHIST" (or whatever is indicated by SFRCODE)

This HDU contains the parameters passed to sfrhist in the configuration file, as well as these keywords:

• SNAPTIME float

  The simulation time of this snapshot.

• SNAPFILE string

  The snapshot filename

HDU "GADGET" (or whatever is indicated by NBODYCOD)

This HDU contains the keywords in the GADGET parameter file, as specified by the configuration file keyword "simparfile".

HDU "MERGER" (if object is a merger)

This HDU contains the merger information from the parameter file used to build the initial conditions for the simulation. (The name of this file is given by the keyword "InitCondFile" in the GADGET HDU, with a ".parameters" suffix.)

HDU('s) "OBJECTi-PARAMETERS"

These HDU's (with i going from 1 to NOBJECT) contain the information about the i'th object, from the parameter file used to build the initial conditions for the simulation.

HDU "PARTICLEDATA"

Binary table containing the data for stellar particles. Contains the following columns:

• ID integer The ID number of the particle
• position 3*double The particle position
• velocity 3*double The particle velocity
• mass double The mass of the particle
• radius double The current particle radius
• metallicity double The particle metallicity
• formation_time double The formation time of the particle
• age double The age of the particle
• parent_ID integer The ID number of the gas particle the star was created from (if applicable)
• creation_mass double The ZAMS mass the star particle was created with (the same as 'mass' unless star particles recycle gas)
• L_lambda n*float The particle SED (may be log of the value)
• L_bol double The particle bolometric luminosity

The HDU also contains the following keywords:

• M_G_TOT float

  The total gas mass of the object.

• L_bol_new float

  The total bolometric luminosity of new stars in this object.

• SFR_tot float

  The total star formation rate of the object.

• M_TOT float

  The total mass (stellar + gas) of the object.

• L_bol_disk float

  The bolometric luminosity of the "disk" (pre-existing population) in the object.

• L_bol_tot float

  The total bolometric luminosity of the object. The HDU may also contain the keyword "logflux", which if true indicates that the values in the L_lambda column is actually the log10 of the actual values. (The point of this is that the value will fit in a float, whereas the actual luminosity may be a number outside the float range.)

Additional HDU's

The HDU's "STELLARMODEL" and "LAMBDA" are copied from the stellar model file (as specified by the configuration keyword "stellarmodelfile") into the output file.