Configuring pynbody

Pynbody uses a flexible configuration system through the standard Python ConfigParser class. The default configuration is stored in default_config.ini in the pynbody installation directory.

The options can be overriden by placing a .pynbodyrc file in your home directory, or a config.ini file in the installed package directory, and specifying different values for configuration parameters to be overriden. These files do not need to have every option, only the ones you want to change relative to the default_config.ini.

The configuration files set up basic things like particle family names, whether to use mutlithreading, default base units etc. The default configuration file is reproduced verbatim below for reference, allowing you to see what options can be changed.

Most of the options are explained in the file itself, and in order to use a different default, you simply override the option in .pynbodyrc. For example, to reduce the number of CPU cores that pynbody uses, the following can be placed in .pynbodyrc:

[general]

number_of_threads: 2

For more information on threading, see threading.

Some options can also be changed at runtime. You can check which ones with

In [1]: pynbody.config
Out[1]: 
{'centering-scheme': 'ssc',
 'snap-class-priority': ['RamsesSnap',
  'GrafICSnap',
  'NchiladaSnap',
  'GadgetSnap',
  'SwiftSnap',
  'EagleLikeHDFSnap',
  'GadgetHDFSnap',
  'SubFindHDFSnap',
  'TipsySnap',
  'AsciiSnap'],
 'halo-class-priority': ['HaloNumberCatalogue',
  'AmigaGrpCatalogue',
  'VelociraptorCatalogue',
  'SubFindHDFHaloCatalogue',
  'RockstarCatalogue',
  'AHFCatalogue',
  'SubfindCatalogue',
  'NewAdaptaHOPCatalogue',
  'AdaptaHOPCatalogue',
  'HOPCatalogue',
  'Gadget4SubfindHDFCatalogue',
  'ArepoSubfindHDFCatalogue',
  'TNGSubfindHDFCatalogue'],
 'default-cosmology': {'a': 1.0,
  'h': 0.6766,
  'ns': 0.9665,
  'running': 0.0,
  'omegaM0': 0.3111,
  'omegaL0': 0.6889,
  'omegaB0': 0.049,
  'sigma8': 0.8102},
 'sph': {'smooth-particles': 32, 'tree-leafsize': 16, 'Kernel': 'CubicSpline'},
 'threading': 'True',
 'number_of_threads': 2,
 'gravity_calculation_mode': 'direct',
 'disk-fit-function': 'expsech',
 'image-default-resolution': 1000}

For example, to change how many particles are being used to estimate sph kernel quantities, you can set

In [2]: pynbody.config['sph']['smooth-particles'] = 128

Default configuration

The default configuration file for pynbody is shown below.

# DO NOT alter this file directly
#
# If you want to override options, either create a local copy called
# config.ini in the directory where pynbody is installed, create a local
# copy called .pynbodyrc in your home directory, or a local copy called
# config.ini in the directory where you are running pynbody.

[general]
# When you call pynbody.load, it will by default try interpreting them as formats in
# the following order. You can override this ordering either as a configuration option, or
# by passing load(..., priority = [...]) at runtime (see documentation for pynbody.snapshot.load).
snap-class-priority: RamsesSnap, GrafICSnap, NchiladaSnap, GadgetSnap, SwiftSnap, EagleLikeHDFSnap, GadgetHDFSnap,
    SubFindHDFSnap, TipsySnap, AsciiSnap

# Similarly, when you call .halos() on a SimSnap, different readers are tried in succession,
# and the first that is able to produce a halo catalogue is used. The order can be changed
# here or by passing sim.halos(priority=[...]) at runtime (see documentation for SimSnap.halos).
halo-class-priority: HaloNumberCatalogue, AmigaGrpCatalogue, VelociraptorCatalogue, SubFindHDFHaloCatalogue,
    RockstarCatalogue, AHFCatalogue, SubfindCatalogue, NewAdaptaHOPCatalogue, AdaptaHOPCatalogue, HOPCatalogue,
    Gadget4SubfindHDFCatalogue, ArepoSubfindHDFCatalogue, TNGSubfindHDFCatalogue

centering-scheme: ssc

# Some routines log information which will appear if verbose is set to True
verbose: False

threading: True
number_of_threads: -1
# -1 above indicates to detect the number of processors

gravity_calculation_mode: direct

disk-fit-function: expsech

# number of points to use in cosmological function interpolations e.g. t->a transformations
cosmo-interpolation-points: 1000

# The default resolution for images. This is the number of pixels along the longest axis.
image-default-resolution: 1000

[families]
# This section defines the families in the format
#    main_name: alias1, alias2, ...
#
# To add your own families, just add lines like this to
# your own local copy.
#
# Note that the alias list can be blank, i.e. if you want
# no aliases for particle family 'main_name', write:
#   main_name:
#

dm: d, dark
star: stars, st, s
gas: g
neutrino: n, neu
bh:
debris:
gas_tracer:
dm_tracer:
star_tracer:
cloud_tracer:
debris_tracer:
cloud:

[sph]
# The number of particles to include in the SPH kernel:
smooth-particles: 32

# When building a KDTree, how many particles are in each leaf of the tree. This should have no
# effect on results, just a minor impact on performance. Roughly half the number of smoothing
# particles is probably optimal.
tree-leafsize: 16

#
Kernel: CubicSpline

# This switches on threading for rendering images. There is unlikely to be
# any reason you'd want to turn this off except for testing.
threaded-image: True

# This switches on an approximate rendering algorithm that
# slightly degrades quality but radically speeds things up (especially
# for projected images).
approximate-fast-images: True


[gadgethdf-type-mapping]
# GadgetHDF stores six different particle types (numbered 0 to 5). This specifies how they map
# onto pynbody particle types by default. To override, you can either make your own configuration
# file (see above), or use special arguments when loading the HDF file (see reference documentation
# for GadgetHDFSnap). Note that this mapping is also used for e.g. Arepo and Swift simulations which
# follow a very similar format.
gas: PartType0
dm: PartType1, PartType2, PartType3
star: PartType4
bh: PartType5

[gadgethdf-name-mapping]
# Specifies how names in the HDF file map to pynbody names
Coordinates: pos
Velocity: vel
Velocities: vel
ParticleIDs: iord
Masses: mass
Mass: mass
InternalEnergy: u
Temperature: temp
GFM_Metallicity: metals
Metallicity: metals
SmoothedMetallicity: smetals
Density: rho
SmoothingLength: smooth
StellarFormationTime: aform
GFM_StellarFormationTime: aform
Potential: phi
ElementAbundance/Iron: Fe
ElementAbundance/Silicon: Si
ElementAbundance/Magnesium: Mg
ElementAbundance/Oxygen: O
ElementAbundance/Neon: Ne
ElementAbundance/Hydrogen: H
ElementAbundance/Helium: He
ElementAbundance/Carbon: C
ElementAbundance/Nitrogen: N

[swift-name-mapping]
Coordinates: pos
Velocities: vel
FOFGroupIDs: grp
Masses: mass
Potentials: phi
Softenings: eps
ParticleIDs: iord
Densities: rho
InternalEnergies: u
Pressures: p
SmoothingLengths: smooth


[default-cosmology]
# These parameters are assumed by default if a file doesn't provide the cosmological information.
# From Planck 2018, https://arxiv.org/pdf/1807.06209, Table 2, last column; includes
# BAO and CMB data.
a: 1.0
h: 0.6766
ns: 0.9665
running: 0.0
omegaM0: 0.3111
omegaL0: 0.6889
omegaB0: 0.0490
# The above from omegaB0h^2 / h^2
sigma8: 0.8102

[default-array-dimensions]
# If the unit system of a file is known, pynbody can use the following dimensional information
# to infer the likely units. If specific unit information is available about a given array,
# that will override any dimensions given here.
pos: cm
vel: cm s^-1
eps: cm
phi: cm^2 s^-2
accg: cm s^-2
mass: kg
temp: K
Tinc: K
tempEff: K
rho: kg cm^-3
den: kg cm^-3
smooth: cm
tform: s
timeform: s
HI: 1
HeI: 1
HeII: 1
FeMassFrac: 1
OxMassFrac: 1
coolontime: s
p: Pa
u: km^2 s^-2
uHot: km^2 s^-2
massform: kg
massHot: kg
MassHot: kg

# ramses RT stores radiation density in flux units:
rad_0_rho: cm^-2 s^-1
rad_0_flux: cm^-2 s^-1

[tipsy]
# In the tipsy binary format, arrays are stored on disk without explicit information about their
# type. This specifies which binary files to be interpreted as integers as opposed to floating
# point.
binary-int-arrays: iord, igasorder, grp

[gadget-type-mapping]
# For non-HDF (i.e. old-style) gadget files, specifies the mapping from the gadget particle
# type (0->5) to pynbody families
gas: 0
dm: 1,5
star: 2,3,4

[gadget-name-mapping]
# Maps non-HDF (i.e. old-style) gadget block names to pynbody families
HSML: smooth
ID: iord

[gadget-1-blocks]
# The default block order for Gadget-1 files. Not all blocks need be present
blocks=HEAD,POS,VEL,ID,MASS,U,NH,NHE,HSML,SFR

[nchilada-name-mapping]
# this maps the nchilada XML names (not filenames) to pynbody names
position: pos
potential: phi
smoothlength: smooth2
temperature: temp
GasDensity: rho
timeform: tform

[ramses-name-mapping]
# For RAMSES format post November 2017: map the names in the part_file_descriptor.txt to pynbody names
position_x: x
position_y: y
position_z: z
velocity_x: vx
velocity_y: vy
velocity_z: vz
identity: iord
levelp: level
birth_time: tform

# map the names in the XXXX_file_descriptor.txt to pynbody names
density: rho
pressure: p
metallicity: metal

# for some reason sink particle masses are sometimes labelled msink
msink: mass


[ramses]
# For RAMSES format post November 2017: map the raw particle family ID to the pynbody family type

# families >0 in ascending order (1, 2,..)
# the last family in the list is also assigned to all other positive families
type-mapping-positive: dm, star, cloud, debris

# families ≤0 in descending order (i.e. 0, -1, -2,..)
# the last family in the list is also assigned to all other negative families
type-mapping-negative: gas_tracer, dm_tracer, star_tracer, cloud_tracer, debris_tracer

# family for the additional sink.csv file
type-sink: bh

# For the use of proper (if True) or conformal (if False) time when reading the age of star particles.
# Should be turned to True if the namelist flag use_proper_time is set to True
# or for radiative transfer simulations. By default, this will be guessed from the dataset, so is not set here.

# proper_time: False

# The default particle blocks for RAMSES files. Only used if the particle block names and type information are
# not given in the header_....txt file inside the output_.... folder.
particle-blocks=x,y,z,vx,vy,vz,mass,iord,level,tform,metal
particle-format=f8,f8,f8,f8,f8,f8,f8,i4,i4,f8,f8

# For old-style RAMSES format (up to November 2017)
# particle-distinguisher indicates the particle block which is non-zero for stars (0-based, so 9=age by default)
# More recent RAMSES outputs have a specific field that explicitly distinguishes different particle types
# so this is not used
particle-distinguisher=9,f8

# Hydro blocks for old-style files; only used if the file_descriptor.txt file doesn't specify the
# hydro blocks actually present in the file. The list here assumes 3D. Anything ending in z will
# be removed for 2D snapshots.
hydro-blocks=rho,vx,vy,vz,p,metal
gravity-blocks=phi,accg_x,accg_y,accg_z

# RT blocks where %d represents the waveband number. Even modern ramses files don't write out any
# names for the RT blocks, although they do store the number of wavebands, so pynbody can generate
# the right number of arrays
rt-blocks=rad_%d_rho,rad_%d_flux_x,rad_%d_flux_y,rad_%d_flux_z

# Ramses files are read in parallel by the specified number of reader processes. Note that
# the optimal number of readers probably depends on your disk performance rather than the number
# of CPUs.
#
# If parallel_read<=1, ramses files are read on the main process.
#
parallel-read=8

# specify the locations of RAMSES utilities -- obtain from
# https://bitbucket.org/rteyssie/ramses
# These utils were previously used to convert conformal times of star birth times into physical
# times; however, now, that can be done internally and this is largely retained for historical
# reasons.
ramses_utils = $HOME/ramses/utils/

# If True, use external part2birth utility (see above) to convert from conformal to physical time
# Otherwise, use pynbody's internal routines. This is retained for historical reproducibility
# but there is no reason to use it for new projects.
use_part2birth_by_default = False

[gadget-default-output]
# Very old gadget files have no block names to identify the fields that have been written to
# disk.  This determines which blocks to expect in such a file, the families for which they
# are defined, and the order in which they appear in the file.
all = pos, vel
gas = u, nh, nhe, smooth, sfr
# Any arrays not mentioned in the field ordering below will be
# tacked on the end of the file in an unspecified order
field-ordering = pos, vel, iord, mass, u, nh, nhe, smooth, sfr

[gadget-units]
# The default units for Gadget files. Note that Gadget-HDF files
# store unit information so this is only used for old-style
# Gadget binary files.
#
# Cosmological dependencies (a and h) will be stripped out for non-
# cosmological runs.
vel: km s^-1 a^1/2
pos: Mpc a h^-1
mass: 1e10 Msol h^-1

[camb]
# To use CAMB live (e.g. to generate consistent power spectra automatically) you will need
# to compile the default version of CAMB (ini-file driver) and set up the path to the
# executable. Download CAMB here: http://camb.info
path: /path/to/camb

[SubfindHDF]

FoF-ignore: SF, NSF, Stars
Sub-ignore: GrNr, FirstSubOfHalo, SubParentHalo, SubMostBoundID, InertiaTensor, SF, NSF, NsubPerHalo, Stars



[irreducible-units]
# This defines the irreducible units, which cannot be expressed in
# terms of anything more basic. We include in this cosmological
# quantities 'a' and 'h' which are typically substituted for numerical
# values at some point in the calculation.
names: m, s, kg, K, a, h, aform, rad

[named-units]
# The next section defines the named units which are derived from the
# above irreducible units. The file is processed sequentially so that
# later entries can refer to previous named units.

# Times - regard a year as the julian year 365.25 days, and a day as 86400 seconds, as per
# https://www.iau.org/publications/proceedings_rules/
yr: 31.5576e6 s
kyr: 1000 yr
Myr: 1000 kyr
Gyr: 1000 Myr
Hz: s^-1
kHz: 1e3 Hz
MHz: 1e6 Hz
GHz: 1e9 Hz
THz: 1e12 Hz

# Distances; see
angst: 1e-10 m
cm: 0.01 m
mm: 1e-3 m
nm: 1e-9 m
km: 1000 m
au: 1.495978707e11 m
pc: 3.0856775814913673e16 m
kpc: 1000 pc
Mpc: 1000 kpc
Gpc: 1000 Mpc

# Solid Angle
sr: rad^2
deg: 0.01745329251 rad
arcmin: 0.01666666666 deg
arcsec: 0.01666666666 arcmin

# Masses
# see https://iau-a3.gitlab.io/NSFA/NSFA_cbe.html#GMS2012
Msol: 1.98842e30 kg
g: 1.0e-3 kg

# proton/electron masses updated from https://physics.nist.gov/ in April 2024
m_p: 1.67262192369e-27 kg
m_e: 9.1093837015e-31 kg

# Forces
N: kg m s^-2
dyn: g cm s^-2

# Energies
J: N m
erg: 1.0e-7 J
eV: 1.602176634e-19 J
keV: 1000 eV
MeV: 1000 keV

# Power
W: J s^-1

# Flux
Jy: 1e-26 W m^-2 Hz^-1

# Pressures
Pa: J m^-3

# Redshift
(1+z): a^-1

# Helpful physical quantities
# updated from https://physics.nist.gov/ in April 2024
k: 1.380649e-23 J K^-1
c: 299792458 m s^-1
G: 6.67430e-11 m^3 kg^-1 s^-2
hP: 6.62607015e-34 m^2 kg s^-1

[units-latex]
# Latex code for typesetting named units.
Msol: M_{\odot}
m_p: m_p
m_e: m_e