Generic Convenience Modules

bridge

The bridge module has tools for connecting different outputs. For instance, it’s possible to take a subview (e.g. a halo) from one snapshot and ‘push’ it into the other. This is especially useful if the two snapshots are different time outputs of the same simulation.

Once connected, bridge called on a specific subset of particles in output1 will trace these particles back (or forward) to the output2, enabling observing a change in their properties, such as position, temperature, etc.

For a tutorial on how to use the bridge module to trace the particles in your simulation, see the bridge tutorial.

class pynbody.bridge.Bridge(start, end)[source]

Generic Bridge class

is_same(i1, i2)[source]

Returns true if the particle i1 in the start point is the same as the particle i2 in the end point.

match_catalog(min_index=1, max_index=30, threshold=0.5, groups_1=None, groups_2=None, use_family=None)[source]

Given a Halos object groups_1, a Halos object groups_2 and a Bridge object connecting the two parent simulations, this identifies the most likely ID’s in groups_2 of the objects specified in groups_1.

If groups_1 and groups_2 are not specified, they are automatically obtained using the SimSnap.halos method.

Parameters min_index and max_index are the minimum and maximum halo numbers to be matched (in both ends of the bridge). If max_index is too large, the catalogue matching can take prohibitively long (it scales as max_index^2).

This routine currently uses particle number as a proxy for mass, so that the main simulation data does not need to be loaded.

If b links snapshot f1 (high redshift) to f2 (low redshift) and we set

cat = b.match_catalog()

then cat is now a numpy index array such that f1.halos()[i] is the major progenitor for f2.halos()[cat[i]], assuming cat[i] is positive.

cat[0:min_index+1] is set to -2. Halos which cannot be matched because they have too few particles in common give the result -1. This is determined by the given threshold fraction of particles in common (by default, 50%).

If use_family is specified, only particles from that family are cross-matched. This can be useful e.g. if matching between two different simulations where the relationship between DM particles is known, but perhaps the relationship between star particles is random.

fuzzy_match_catalog(min_index=1, max_index=30, threshold=0.01, groups_1=None, groups_2=None, use_family=None, only_family=None)[source]

fuzzy_match_catalog returns, for each halo in groups_1, a list of possible identifications in groups_2, along with the fraction of particles in common between the two.

Normally, match_catalog is simpler to use, but this routine offers greater flexibility for advanced users. The first entry for each halo corresponds to the output from match_catalog.

If no identification is found, the entry is the empty list [].

catalog_transfer_matrix(min_index=1, max_index=30, groups_1=None, groups_2=None, use_family=None, only_family=None)[source]

Return a max_index x max_index matrix with the number of particles transferred from the row group in groups_1 to the column group in groups_2.

Normally, match_catalog (or fuzzy_match_catalog) are easier to use, but this routine provides the maximal information.

class pynbody.bridge.OrderBridge(start, end, order_array='iord', monotonic=True)[source]

An OrderBridge uses integer arrays in two simulations (start,end) where particles i_start and i_end are defined to be the same if and only if start[order_array][i_start] == start[order_array][i_end].

If monotonic is True, order_array must be monotonically increasing in both ends of the bridge (and this is not checked for you). If monotonic is False, the bridging is slower but this is the failsafe option.

pynbody.bridge.bridge_factory(a, b)[source]

Create a bridge connecting the two specified snapshots. For more information see bridge-tutorial.

filt

Defines and implements ‘filters’ which allow abstract subsets of data to be specified.

See the filter tutorial for some sample usage.

class pynbody.filt.Sphere(radius, cen=(0, 0, 0))[source]

Return particles that are within radius of the point cen.

class pynbody.filt.Cuboid(x1, y1=None, z1=None, x2=None, y2=None, z2=None)[source]

Create a cube with specified edge coordinates. If any of the cube coordinates x1, y1, z1, x2, y2, z2 are not specified they are determined as y1=x1; z1=x1; x2=-x1; y2=-y1; z2=-z1.

class pynbody.filt.Disc(radius, height, cen=(0, 0, 0))[source]

Return particles that are within a disc of extent radius and thickness height centered on cen.

class pynbody.filt.BandPass(prop, min, max)[source]

Return particles whose property prop is within min and max, which can be specified as unit strings.

class pynbody.filt.HighPass(prop, min)[source]

Return particles whose property prop exceeds min, which can be specified as a unit string.

class pynbody.filt.LowPass(prop, max)[source]

Return particles whose property prop is less than max, which can be specified as a unit string.

pynbody.filt.Annulus(r1, r2, cen=(0, 0, 0))[source]

Convenience function that returns a filter which selects particles in between two spheres specified by radii r1 and r2 centered on cen.

pynbody.filt.SolarNeighborhood(r1=Unit("5.00e+00 kpc"), r2=Unit("1.00e+01 kpc"), height=Unit("2.00e+00 kpc"), cen=(0, 0, 0))[source]

Convenience function that returns a filter which selects particles in a disc between radii r1 and r2 and thickness height.

halo

Implements halo catalogue functions. If you have a supported halo catalogue on disk or a halo finder installed and correctly configured, you can access a halo catalogue through f.halos() where f is a SimSnap.

See the halo tutorial for some examples.

class pynbody.halo.Halo(halo_id, halo_catalogue, *args)[source]

Generic class representing a halo.

is_subhalo(otherhalo)[source]

Convenience function that calls the corresponding function in a halo catalogue.

class pynbody.halo.HaloCatalogue(sim)[source]

Generic halo catalogue object.

is_subhalo(childid, parentid)[source]

Checks whether the specified ‘childid’ halo is a subhalo of ‘parentid’ halo.

get_group_array()[source]

Return an array with an integer for each particle in the simulation indicating which halo that particle is associated with. If there are multiple levels (i.e. subhalos), the number returned corresponds to the lowest level, i.e. the smallest subhalo.

class pynbody.halo.RockstarIntermediateCatalogue(sim, sort=True, correct=False)[source]

Reader for Rockstar intermediate catalogues as generated by Michael Tremmel’s tool

load_copy(i)[source]

Load a fresh SimSnap with only the particles in halo i

class pynbody.halo.RockstarCatalogueOneCpu(sim, dummy=False, filename=None)[source]

Class to handle catalogues produced by Rockstar

load_copy(i)[source]

Load a fresh SimSnap with only the particles in halo i

make_grp()[source]

Creates a ‘grp’ array which labels each particle according to its parent halo.

writestat(outfile=None, hubble=None)[source]

write a condensed skid.stat style ascii file from ahf_halos file. header + 1 halo per line. should reproduce `Alyson’s idl script’ except does not do last 2 columns (Is it a satellite?) and (Is central halo is `false’ly split?). output units are set to Mpc Msun, km/s.

user can specify own hubble constant hubble=(H0/(100 km/s/Mpc)), ignoring the snaphot arg for hubble constant (which sometimes has a large roundoff error).

writetipsy(outfile=None, hubble=None)[source]

write halos to tipsy file (write as stars) from ahf_halos file. returns a shapshot where each halo is a star particle.

user can specify own hubble constant hubble=(H0/(100 km/s/Mpc)), ignoring the snaphot arg for hubble constant (which sometimes has a large roundoff error).

class pynbody.halo.AHFCatalogue(sim, make_grp=None, dummy=False, use_iord=None, ahf_basename=None)[source]

Class to handle catalogues produced by Amiga Halo Finder (AHF).

make_grp(name='grp')[source]

Creates a ‘grp’ array which labels each particle according to its parent halo.

load_copy(i)[source]

Load the a fresh SimSnap with only the particle in halo i

writegrp(grpoutfile=False)[source]

simply write a skid style .grp file from ahf_particles file. header = total number of particles, then each line is the halo id for each particle (0 means free).

writestat(snapshot, halos, statoutfile, hubble=None)[source]

write a condensed skid.stat style ascii file from ahf_halos file. header + 1 halo per line. should reproduce `Alyson’s idl script’ except does not do last 2 columns (Is it a satellite?) and (Is central halo is `false’ly split?). output units are set to Mpc Msun, km/s.

user can specify own hubble constant hubble=(H0/(100 km/s/Mpc)), ignoring the snaphot arg for hubble constant (which sometimes has a large roundoff error).

writetipsy(snapshot, halos, tipsyoutfile, hubble=None)[source]

write halos to tipsy file (write as stars) from ahf_halos file. returns a shapshot where each halo is a star particle.

user can specify own hubble constant hubble=(H0/(100 km/s/Mpc)), ignoring the snaphot arg for hubble constant (which sometimes has a large roundoff error).

writehalos(snapshot, halos, hubble=None, outfile=None)[source]

Write the (ahf) halo catalog to disk. This is really a wrapper that calls writegrp, writetipsy, writestat. Writes .amiga.grp file (ascii group ids), .amiga.stat file (ascii halo catalog) and .amiga.gtp file (tipsy halo catalog). default outfile base simulation is same as snapshot s. function returns simsnap of halo catalog.

class pynbody.halo.GrpCatalogue(sim, array='grp')[source]

A generic catalogue using a .grp file to specify which particles belong to which group.

precalculate()[source]

Speed up future operations by precalculating the indices for all halos in one operation. This is slow compared to getting a single halo, however.

class pynbody.halo.SubfindCatalogue(sim, subs=False, order=True, make_grp=None, v=False)[source]

Class to handle catalogues produced by the SubFind halo finder. Can import FoF groups (default) or subhalos (by setting subs=True). Groups are sorted by mass (descending), most massive group is halo[0]. Subhalos within each group are also sorted by mass. IDs within groups are sorted by binding energy, UNLESS the IDs in the snapshots are not ordered starting from 0. In that case, setting order=False will generate the correct halo catalogue but the ordering by binding energy within each halo will be lost. Additional properties calculated by SubFind can be accessed via e.g. ‘halo[0].properties’. make_grp=True generates a particle array with the Fof group number, and -1 if the particles is not in a group. *This will take some time! v=True enables a crude progress report.

make_grp(name='grp', v=False)[source]

#Creates a ‘grp’ array which labels each particle according to #its parent halo. This can take quite some time! Option: v=True prints out ‘progress’ in terms of total number of groups. #

class pynbody.halo.SubFindHDFHaloCatalogue(sim)[source]

Gadget’s SubFind Halo catalogue – used in concert with SubFindHDFSnap

class pynbody.halo.SubFindFOFGroup(group_id, *args)[source]

SubFind FOF group class

class pynbody.halo.SubFindHDFSubhaloCatalogue(group_id, group_catalogue)[source]

Gadget’s SubFind HDF Subhalo catalogue.

Initialized with the parent FOF group catalogue and created automatically when an fof group is created

class pynbody.halo.SubFindHDFSubHalo(halo_id, group_id, *args)[source]

SubFind subhalo class

sph

pynbody SPH rendering module.

This module encompasses Kernel objects, which return C fragments from which a final C code to perform the rendering is derived.

For most users, the function of interest will be render_image().

pynbody.sph.render_spherical_image(snap, qty='rho', nside=8, distance=10.0, kernel=<pynbody.sph.Kernel object at 0x10840ddd0>, kstep=0.5, denoise=None, out_units=None, threaded=None)[source]

Render an SPH image on a spherical surface. Requires healpy libraries.

Keyword arguments:

qty (‘rho’): The name of the simulation array to render

nside (8): The healpix nside resolution to use (must be power of 2)

distance (10.0): The distance of the shell (for 3D kernels) or maximum distance
of the skewers (2D kernels)

kernel: The Kernel object to use (defaults to 3D spline kernel)

kstep (0.5): The sampling distance when projecting onto the spherical surface in units of the
smoothing length
denoise (False): if True, divide through by an estimate of the discreteness noise.
The returned image is then not strictly an SPH estimate, but this option can be useful to reduce noise.
threaded: if False, render on a single core. Otherwise, the number of threads to use.
Defaults to a value specified in your configuration files. Currently multi-threaded rendering is slower than single-threaded because healpy does not release the gil.
pynbody.sph.render_image(snap, qty='rho', x2=100, nx=500, y2=None, ny=None, x1=None, y1=None, z_plane=0.0, out_units=None, xy_units=None, kernel=<pynbody.sph.Kernel object at 0x10840de90>, z_camera=None, smooth='smooth', smooth_in_pixels=False, force_quiet=False, approximate_fast=True, threaded=None, denoise=None)[source]

Render an SPH image using a typical (mass/rho)-weighted ‘scatter’ scheme.

Keyword arguments:

qty (‘rho’): The name of the array within the simulation to render

x2 (100.0): The x-coordinate of the right edge of the image

nx (500): The number of pixels wide to make the image

y2: The y-coordinate of the upper edge of the image (default x2,
or if ny is specified, x2*ny/nx)

ny (nx): The number of pixels tall to make the image

x1 (-x2): The x-coordinate of the left edge of the image

y1 (-y2): The y-coordinate of the lower edge of the image

z_plane (0.0): The z-coordinate of the plane of the image

out_units (no conversion): The units to convert the output image into

xy_units: The units for the x and y axes

kernel: The Kernel object to use (default Kernel(), a 3D spline kernel)

z_camera: If this is set, a perspective image is rendered,

assuming the kernel is suitable (i.e. is a projecting kernel). The camera is at the specified z coordinate looking towards -ve z, and each pixel represents a line-of-sight radially outwards from the camera. The width then specifies the width of the image in the z=0 plane. Particles too close to the camera are also excluded.

smooth: The name of the array which contains the smoothing lengths
(default ‘smooth’)
smooth_in_pixels: If True, the smoothing array contains the smoothing
length in image pixels, rather than in real distance units (default False)
approximate_fast: if True, render high smoothing length particles at
progressively lower resolution, resample and sum
denoise: if True, divide through by an estimate of the discreteness noise.
The returned image is then not strictly an SPH estimate, but this option can be useful to reduce noise especially when rendering AMR grids which often introduce problematic edge effects.

verbose: if True, all text output suppressed

threaded: if False (or None), render on a single core. Otherwise,
the number of threads to use (defaults to a value specified in your configuration files).
pynbody.sph.to_3d_grid(snap, qty='rho', nx=None, ny=None, nz=None, x2=None, out_units=None, xy_units=None, kernel=<pynbody.sph.Kernel object at 0x10840ded0>, smooth='smooth', approximate_fast=True, threaded=None, snap_slice=None, denoise=None)[source]

Project SPH onto a grid using a typical (mass/rho)-weighted ‘scatter’ scheme.

Keyword arguments:

qty (‘rho’): The name of the array within the simulation to render

nx (x2-x1 / soft): The number of pixels wide to make the grid

ny (nx): The number of pixels tall to make the grid

nz (nx): The number of pixels deep to make the grid

out_units (no conversion): The units to convert the output grid into

xy_units: The units for the x and y axes

kernel: The Kernel object to use (default Kernel(), a 3D spline kernel)

smooth: The name of the array which contains the smoothing lengths
(default ‘smooth’)
denoise: if True, divide through by an estimate of the discreteness noise.
The returned image is then not strictly an SPH estimate, but this option can be useful to reduce noise especially when rendering AMR grids which often introduce problematic edge effects.
pynbody.sph.spectra(snap, qty='rho', x1=0.0, y1=0.0, v2=400, nvel=200, v1=None, element='H', ion='I', xy_units=Unit("kpc"), vel_units=Unit("km s**-1"), smooth='smooth', __threaded=False)[source]

Render an SPH spectrum using a (mass/rho)-weighted ‘scatter’ scheme of all the particles that have a smoothing length within 2 h_sm of the position.

Keyword arguments:

qty (‘rho’): The name of the array within the simulation to render

x1 (0.0): The x-coordinate of the line of sight.

y1 (0.0): The y-coordinate of the line of sight.

v1 (-400.0): The minimum velocity of the spectrum

v2 (400.0): The maximum velocity of the spectrum

nvel (500): The number of resolution elements in spectrum

xy_units (‘kpc’): The units for the x and y axes

smooth: The name of the array which contains the smoothing lengths
(default ‘smooth’)