Here we include automated documentation of the various classes.

Overview

paicos package

Subpackages

Submodules

paicos.misc module

paicos.orientation module

class paicos.orientation.Orientation(normal_vector=None, perp_vector1=None)

Bases: object

The Orientation class is used to define an orientation of e.g. an image. An instance of this class can be passed to an ImageCreator.

__init__(normal_vector=None, perp_vector1=None)
Parameters:

  • normal_vector – a vector which will be normal to the face of the image, i.e. the depth direction. You can e.g. pass the angular momentum vector of a galaxy for a face on projection.

  • perp_vector1 – a vector which will be parallel to the image plane. This will become the horizontal direction of your image. You can e.g. pass the angular momentum vector here for an edge-on projection.

It’s possible to supply both inputs, which then fully determines the orientation (the vertical direction of the image, perp_vector2, is automatically calculated).

property cartesian_unit_vectors

The x, y, and z unit vectors in the Orientation given in terms of their components in the original simulation coordinate system.

property copy

Returns a copy of the current Orientation instance.

property inverse_rotation_matrix

An inverse rotation matrix, which rotates from the Orientation system into a standard xyz coordinate system. We have the following properties:

np.matmul(inverse_rotation_matrix, perp_vector1) = [1, 0, 0] np.matmul(inverse_rotation_matrix, perp_vector2) = [0, 1, 0] np.matmul(inverse_rotation_matrix, normal_vector) = [0, 0, 1]

The use case for the inverse rotation matrix is to transform Arepo data into a coordinate system where the perp_vector1 direction is in the x-direction, the perp_vector2 direction is in the y-direction and the normal_vector is in the z-direction.

rotate_around_normal_vector(degrees=None, radians=None)

Rotates the orientation instance around its normal_vector.

For a projection image, this is the depth direction.

rotate_around_perp_vector1(degrees=None, radians=None)

Rotates the orientation instance around its perp_vector1.

For an image, this is the horizontal axis.

rotate_around_perp_vector2(degrees=None, radians=None)

Rotates the orientation instance around its perp_vector2.

For an image, this is the vertical axis.

rotate_around_x(degrees=None, radians=None)

Rotates the orientation instance around the ‘x’-coordinate axis

rotate_around_y(degrees=None, radians=None)

Rotates the orientation instance around the ‘y’-coordinate axis

rotate_around_z(degrees=None, radians=None)

Rotates the orientation instance around the ‘z’-coordinate axis

property rotation_matrix

This rotation matrix rotates the standard cartesian unit vectors:

ex = [1, 0, 0]
ey = [0, 1, 0]
ez = [0, 0, 1]

into the cartesian coordinate system defined by the three unit vectors:

perp_vector1
perp_vector2
normal_vector

which can also be accessed through the cartesian_unit_vectors method.

That is, the following equality holds:

perp_vector1 = np.matmul(rotation_matrix, [1, 0, 0])
perp_vector2 = np.matmul(rotation_matrix, [0, 1, 0])
normal_vector = np.matmul(rotation_matrix, [0, 0, 1])

paicos.paicos_user_settings_template module

paicos.settings module

paicos.unit_specifications module

paicos.units module

Defines small_a and small_h, conversion to Gauss and eV, and the PaicosQuantity and PaicosTimeSeries classes.

class paicos.units.PaicosQuantity(value, unit=None, dtype=None, copy=False, order=None, subok=False, ndmin=0, h=None, a=None, comoving_sim=None)

Bases: Quantity

PaicosQuantity is a subclass of the astropy Quantity class which represents a number with some associated unit.

This subclass in addition includes a and h factors used in the definition of comoving variables.

Parameters:

  • value (the numeric values of your data (similar to astropy Quantity)) –

  • a (the cosmological scale factor of your data) –

  • h (the reduced Hubble parameter, e.g. h = 0.7) –

  • unit (a string, e.g. g/cm^3 small_a^-3 small_h^2 or an astropy Unit) –

    The latter can be defined like this:

    from paicos import units as pu
from astropy import units as u
unit = u.g*u.cm**(-3)*small_a**(-3)*small_h**(2)

    The naming of small_a and small_h is to avoid conflict with the already existing ‘annum’ (i.e. a year) and ‘h’ (hour) units.

Methods/key properties

no_small_h

Returns a new comoving quantity where the h-factors have been removed and the numeric value adjusted accordingly.

to_physical

Returns a new object where both a and h factors have been removed, i.e. we have switched from comoving values to the physical value.

label

Returns a Latex label for use in plots.

Examples

Here is an example:

units = 'g cm^-3 small_a^-3 small_h^2'
A = PaicosQuantity(2, units, h=0.7, a=1/128)

# Create a new comoving quantity where the h-factors have been removed
B = A.no_small_h

# Create a new quantity where both a and h factor have been removed,
# i.e. we have switched from a comoving quantity to the physical value

C = A.to_physical
property a

The scale factor.

adjust_time(a=None, z=None)

Return a PaicosQuantity with its time (i.e. scale factor, a, and redshift, z, set to new values without changing the physical value of the quantity).

Note the difference between this method and the “adjust_time” method!

Use the “adjust_time” method if you want to keep the physical value fixed. Use the “set_time” method if you want to keep the comoving value fixed.

Both are illustrated in the example below:

For instance, we initialize a length of 100 comoving kpc (using a snap object with a = 1)

In [2]: L = 100 * snap.uq(‘kpc / small_a’)

…: L_fixed_physical = L.adjust_time(a=0.5) …: L_fixed_comoving = L.set_time(a=0.5)

In [3]: L_fixed_physical Out[3]: <PaicosQuantity 50. kpc / small_a>

In [4]: L_fixed_comoving Out[4]: <PaicosQuantity 100. kpc / small_a>

In [5]: L.to_physical Out[5]: <PaicosQuantity 100. kpc>

In [6]: L_fixed_physical.to_physical Out[6]: <PaicosQuantity 100. kpc>

In [7]: L_fixed_comoving.to_physical Out[7]: <PaicosQuantity 200. kpc>

age(reader_object)

The age of the universe in the simulation.

Requires a reader object as input (e.g. a snap, cat or other instance of Snapshot, Catalog or PaicosReader)

property arepo

Returns the quantity in Arepo code units.

property astro

Returns the quantity in typical units used in cosmological simulations

property astropy_quantity

Returns an astropy Quantity, i.e., the units are retained but we no longer have access to the information about the values of a and h.

property cgs

Returns a copy of the current PaicosQuantity instance with CGS units. The value of the resulting object will be scaled.

property comoving_sim

Whether the simulation had ComovingIntegrationOn

property copy

Returns a copy of the PaicosQuantity.

property h

The reduced Hubble parameter

label(variable='')

Return a Latex string for use in plots. The optional input variable could be the Latex symbol for the physical variable, for instance rho or nablatimesvec{v}.

lookback_time(reader_object)

The lookback time.

Requires a reader object as input (e.g. a snap, cat or other instance of Snapshot, Catalog or PaicosReader)

property no_small_h

Remove scaling with h, returning a quantity with adjusted values.

set_time(a=None, z=None)

Return a PaicosQuantity with its time (i.e. scale factor, a, and redshift, z, set to new values while changing the physical value of the quantity).

Note the difference between this method and the “adjust_time” method!

Use the “adjust_time” method if you want to keep the physical value fixed. Use the “set_time” method if you want to keep the comoving value fixed.

Both are illustrated in the example below:

For instance, we initialize a length of 100 comoving kpc (using a snap object with a = 1)

In [2]: L = 100 * snap.uq(‘kpc / small_a’)

…: L_fixed_physical = L.adjust_time(a=0.5) …: L_fixed_comoving = L.set_time(a=0.5)

In [3]: L_fixed_physical Out[3]: <PaicosQuantity 50. kpc / small_a>

In [4]: L_fixed_comoving Out[4]: <PaicosQuantity 100. kpc / small_a>

In [5]: L.to_physical Out[5]: <PaicosQuantity 100. kpc>

In [6]: L_fixed_physical.to_physical Out[6]: <PaicosQuantity 100. kpc>

In [7]: L_fixed_comoving.to_physical Out[7]: <PaicosQuantity 200. kpc>

property si

Returns a copy of the current PaicosQuantity instance with SI units. The value of the resulting object will be scaled.

property time

The time elapsed since the beginning of the simulation.

Only defined for non-comoving simulations.

to(unit, equivalencies=[], copy=True)

Convert to different units. Similar functionality to the astropy Quantity.to() method.

to_any(new_unit)

Convert quantity to any (possible) unit.

The .to method only allows converting standard physical units while the .to_comoving only allows modifying the a and h factors. This method allows changing the units in one go.

to_comoving(unit)

Returns a copy of the current PaicosQuantity instance with the a and h factors given by the input unit.

property to_physical

Returns a copy of the current PaicosQuantity instance with the a and h factors removed, i.e. transform from comoving to physical. The value of the resulting object is scaled accordingly.

property unit_quantity

Returns a new PaicosQuantity with the same units as the current PaicosQuantity and a numeric value of 1.

property uq

A short hand for the ‘unit_quantity’ method.

property z

The redshift.

class paicos.units.PaicosTimeSeries(value, unit=None, dtype=None, copy=True, order=None, subok=False, ndmin=0, h=None, a=None, comoving_sim=None)

Bases: PaicosQuantity

PaicosTimeSeries is a subclass of the PaicosQuantity and and shares many of the same methods.

The time series is very similar to the PaicosQuantity but the .a or .time properties now return arrays with same length as the object itself (.shape[0]).

property copy

Returns a copy of the PaicosTimeSeries.

to_comoving(unit)

Returns a copy of the current PaicosTimeSeries with the a and h factors given by the input unit.

property to_physical

Returns a copy of the current PaicosTimeSeries instance with the a and h factors removed, i.e. transform from comoving to physical. The value of the resulting object is scaled accordingly.

paicos.units.separate_units(unit)

Separates the standard physical units (u_unit) from the units involving a and h (pu_unit). That is:

u_unit, pu_unit = separate_units(unit)

where pu_unit contains small_a and small_h and u_unit contains everything else such that:

unit = u_unit * pu_unit

paicos.util module

Defines a few useful functions and most importantly, the low level hdf5 reader and writer. It also serves as a placeholder for variables that can be changed via user functions.

paicos.util.conditional_timer(func)
paicos.util.get_index_of_cubic_region(pos, center, widths, box)

Get a boolean array to the position array, pos, which are inside a cubic region.

Parameters:

  • pos (array) – position array with dimensions = (n, 3)

  • center (array with length 3) – The center of the box (x, y, z).

  • widths (array with length 3) – The widths of the box.

  • box (float) – The box size of the simulation (e.g. snap.box).

paicos.util.get_index_of_cubic_region_plus_thin_layer(pos, center, widths, thickness, box)

Get a boolean array to the position array, pos, which are inside a cubic region plus a thin layer with a cell-dependent thickness

Parameters:

  • pos (array) – position array with dimensions = (n, 3)

  • center (array with length 3) – The center of the box (x, y, z).

  • widths (array with length 3) – The widths of the box.

  • thickness (array) – Array with same length as the position array.

  • box (float) – The box size of the simulation (e.g. snap.box).

paicos.util.get_index_of_radial_range(pos, center, r_min, r_max)

Get a boolean array of positions, pos, which are inside the spherical shell with inner radius r_min and outer radius r_max, centered at center.

paicos.util.get_index_of_radial_range_plus_thin_layer(pos, center, r_min, r_max, thickness)

Get a boolean array for the positions, pos, which are inside the spherical shell with inner radius r_min and outer radius r_max, centered at center. The thickness array argument adds a variable thickness, e.g., the cell diameters, so that point close to the selection are also included.

paicos.util.get_index_of_rotated_cubic_region(pos, center, widths, box, orientation)

Get a boolean array to the position array, pos, which are inside a cubic region

Parameters:

  • pos (array) – position array with dimensions = (n, 3)

  • center (array with length 3) – The center of the box (x, y, z).

  • widths (array with length 3) – The widths of the box.

  • thickness (array) – Array with same length as the position array.

  • box (float) – The box size of the simulation (e.g. snap.box).

paicos.util.get_index_of_rotated_cubic_region_plus_thin_layer(pos, center, widths, thickness, box, orientation)

Get a boolean array to the position array, pos, which are inside a cubic region plus a thin layer with a cell-dependent thickness

Parameters:

  • pos (array) – position array with dimensions = (n, 3)

  • center (array with length 3) – The center of the box (x, y, z).

  • widths (array with length 3) – The widths of the box.

  • thickness (array) – Array with same length as the position array.

  • box (float) – The box size of the simulation (e.g. snap.box).

paicos.util.get_project_root_dir()

Returns the root directory of the local Paicos copy.

paicos.util.load_dataset(hdf5file, name, group=None)

Load dataset, returning a paicos quantity if the attributes contain units and units are enabled.

paicos.util.remove_astro_units(func)

This is a decorator function that takes in a function and returns a new function that removes any astro units from the function’s arguments and keyword arguments before calling the original function. The decorator checks if the argument or keyword argument has a ‘unit’ attribute and, if so, replaces it with its ‘value’ attribute. This is useful for functions that do not support astro units or need to work with raw values.

paicos.util.save_dataset(hdf5file, name, data=None, data_attrs={}, group=None, group_attrs={})

Create dataset in open hdf5file ( hdf5file = h5py.File(filename, ‘w’) ) If the data has units then they are saved as an attribute.

Module contents

HDF5 Readers

paicos.readers package

Submodules

paicos.readers.arepo_catalog module

This defines a reader for Arepo Friends-of-Friends (FoF) and subhalo catalog files

class paicos.readers.arepo_catalog.Catalog(basedir='.', snapnum=None, load_all=False, to_physical=False, subfind_catalog=True, readonly_first_file=False, verbose=False)

Bases: PaicosReader

This is a Python class for reading Arepo group and subhalo catalogs. The class is based on a script originally written by Ewald Puchwein, which has since then been modified and included in Paicos.

The class takes in the path of the directory containing the catalog, the catalog number, and an optional basename parameter, and uses this information to locate and open the catalog files. The class also loads the catalog’s header, parameters, and configuration. The class also includes methods to extract the redshift, scale factor, and other properties of the catalog.

Important methods and attributes:

cat = Catalog()

cat.Groupdict

Contains a dictionary of the FoF-catalog.

cat.Subdict

Contains a dictionary of the Subfind-catalog.

cat.Parametersdict

Contains information from the parameter file used in the simulation (e.g. param.txt).

cat.Configdict

Contains information from the Config file used in the simulation (e.g. Config.txt).

cat.Headerdict

Contains information about this particular catalog such as its time (e.g scale factor).

cat.zfloat

The redshift.

cat.hfloat

Reduced Hubble param (e.g. 0.67).

cat.agefloat

The age of the Universe (only for cosmological runs).

cat.lookback_timefloat

The age of the Universe (only for cosmological runs).

__init__(basedir='.', snapnum=None, load_all=False, to_physical=False, subfind_catalog=True, readonly_first_file=False, verbose=False)

Initializes the Catalog class.

Parameters:

  • basedir (str) – The path of the directory containing the catalogs (e.g. the ‘output’ folder).

  • snapnum (int) – The snapshot number.

  • load_all (bool) – Whether to immediately load all fields or not.

  • to_physical (bool) – whether to convert to physical unit upon loading the data. Default is False.

  • subfind_catalog (bool) – whether the simulation has subfind catalogs, when False the code will look for FoF-catalogs only.

  • readonly_first_file (bool) – when set to True the code will only read one catalog file (the first). This can significantly speed things up when one is only interested in the properties of the most massive groups in a simulation.

  • verbose (bool) – whether to print information, default is False.

load_all_data()

Calling this method simply loads all the data in the catalog.

save_new_catalog(basename, basedir=None, single_precision=False)

Save a new catalog containing only the currently loaded variables. Useful for reducing datasets to smaller sizes.

class paicos.readers.arepo_catalog.PaicosDict(cat, subfind_catalog=True)

Bases: dict

paicos.readers.arepo_snap module

This defines a reader for Arepo snapshot files

class paicos.readers.arepo_snap.Snapshot(basedir, snapnum=None, basename='snap', load_all=False, to_physical=False, load_catalog=None, subhalonum=None, fofnum=None, verbose=False)

Bases: PaicosReader

This is a Python class for reading Arepo snapshots, which are simulations of the evolution of the universe using a code called Arepo. The class is based on a script originally written by Ewald Puchwein, which has since then been modified and included in Paicos.

The class takes in the path of the directory containing the snapshot, the snapshot number, and an optional basename parameter, and uses this information to locate and open the snapshot files. The class also loads the snapshot’s header, parameters, and configuration, and uses them to create a converter object that can be used to convert units in the snapshot. The class also includes methods to extract the redshift, scale factor, and other properties of the snapshot, as well as the subfind catalog if present.

Important methods and attributes:

snap = Snapshot()

snap.Groupdict

Contains a dictionary of the FoF-catalog.

snap.Subdict

Contains a dictionary of the Subfind-catalog.

snap.Parametersdict

Contains information from the parameter file used in the simulation (e.g. param.txt).

snap.Configdict

Contains information from the Config file used in the simulation (e.g. Config.txt).

snap.Headerdict

Contains information about this particular catalog such as its time (e.g scale factor).

snap.zfloat

The redshift.

snap.hfloat

Reduced Hubble param (e.g. 0.67).

snap.agefloat

The age of the Universe (only for cosmological runs).

snap.lookback_timefloat

The age of the Universe (only for cosmological runs).

snap.timefloat

The time stamp of the snapshot (only for non-cosmological runs).

snap.box_sizearray with length 3

The dimensions of the simulation domain.

__init__(basedir, snapnum=None, basename='snap', load_all=False, to_physical=False, load_catalog=None, subhalonum=None, fofnum=None, verbose=False)

Initialize the Snapshot class.

Parameters:

  • basedir (str) – path of the directory containing the snapshot (e.g. the ‘output’ folder).

  • snapnum (int) – snapshot number.

  • basename (str) – name of the snapshot file, default is “snap”.

  • verbose (bool) – whether to print information about the snapshot, default is False.

  • no_snapdir (bool) – whether there is no snap directory, i.e., default is False.

  • load_catalog (bool) – whether to load the subfind catalog. The default None is internally changed to True for comoving simulations and to False for non-comoving simulations.

  • subhalonum (int) – optional parameter to only load a single subhalo.

  • fofnum (int) – optional parameter to only load a single FoF group.

center_of_mass(parttype=None)

Finds the center of mass for the entire snapshot.

parttype (default None):

If None, then all parttypes are included in the center-of-mass calculation. If e.g. parttype=0, then the center of mass of the gas is returned. if parttype=None, then the total center and a list of of the parttype centers are returned

This method can be used in combination with the select method to find the center of mass of a selection.

info(parttype, verbose=True)

This function provides information about the keys of a certain particle type in a snapshot.

Parameters:

  • (int) (partType) – An integer representing the particle type of interest, e.g. 0 for gas, 1 for DM etc.

  • (bool) (verbose) – A flag indicating whether or not to print the keys to the console. Defaults to True.

Returns:

If the requested PartType exists in the file, a list of keys for that PartType is returned, otherwise None.

Return type:

list or None

load_data(parttype, blockname, debug=False)

Load data from hdf5 file(s). Example usage:

snap = Snapshot(...)
snap.load_data(0, 'Density')

Note that subsequent calls does not reload the data. Reloading the data can be done explicitly:

snap.remove_data(0, 'Density')
snap.load_data(0, 'Density')
remove_data(parttype, blockname)

Remove data from object. Sometimes useful for for large datasets

save_new_snapshot(basename, basedir=None, single_precision=False)

Save a new snapshot containing the currently loaded (derived) variables. Useful for reducing datasets to smaller sizes.

select(selection_index, parttype=None)

Create a new snapshot object which will only contain cells with a selection_index.

Example use:

index = snap['0_Density'] > snap['0_Density'].unit_quantity*1e-6
selected_snap = snap.select(index, parttype=0)
total_angular_momentum(center, parttype=None)

Finds the total angular momentum for the entire snapshot.

center: the center around which to calculate the angular momentum

parttype (default None):

If None, then all parttypes are included in the calculation. If e.g. parttype=0, then total angular momentum of the gas is returned.

This method can be used in combination with the select method to find the total angular momentum of a selection.

paicos.readers.generic_snap module

class paicos.readers.generic_snap.GenericSnapshot(basedir='.', snapnum=None, basename='snap', basesubdir='snapdir', load_all=True, to_physical=False, only_init=False, verbose=False)

Bases: PaicosReader

This is a very simple Snapshot class, which was written for use with general data (e.g. if one wants to make images of Ramses simulations).

Detailed documentation/example usage remains to be written, so please create an issue if you have trouble getting this to work.

__init__(basedir='.', snapnum=None, basename='snap', basesubdir='snapdir', load_all=True, to_physical=False, only_init=False, verbose=False)

Please use see the docstring for the method ‘give_info’.

give_info(boxsize_in_code_units, time_in_code_units, snapnum=None, length_unit=None, time_unit=None, mass_unit=None, comoving_sim=False, hubble_param=1, redshift=0, Omega0=1, OmegaLambda=0, OmegaBaryon=1)
Parameters:

  • snapnum (int) – The snapshot number that you are analyzing

  • boxsize_in_code_units (float) – The box size of your simulation box, which is assumed to be cubic.

Optional parameters (needed when using units are enabled)

time_in_code_units : float

length_unitastropy unit

The code unit used in the simulation. For length e.g. 0.2 * u.Unit(‘kpc’)

time_unitastropy unit

The code unit used in the simulation. For time e.g. u.Unit(‘Myr’)

mass_unitastropy unit

The code unit used in the simulation. For mass e.g. u.Unit(‘Msun’)

set_data(data, key, unit=None)

Set data in the snapshot

Parameters:

  • data (numpy array) – For instance the density, temperature etc

  • key (str) – The dictionary key.

  • unit (astropy unit) – You only need to set this if you have units turned on.

set_positions(data, unit='arepo_length')

Use this to set the cell positions.

set_volumes(data, unit='arepo_length^3')

Use this to set the cell volumes.

paicos.readers.paicos_readers module

Defines the PaicosReader, Histogram2DReader and ImageReader which can be used to load derived variables.

class paicos.readers.paicos_readers.Histogram2DReader(basedir='.', snapnum=None, basename='2d_histogram')

Bases: PaicosReader

This is a subclass of the PaicosReader.

It reads the additional information stored by a Histogram2D instance and makes them accessible as attributes, i.e., colorlabel, normalize, logscale, hist2d, centers_x, centers_y.

__init__(basedir='.', snapnum=None, basename='2d_histogram')

See documentation for the PaicosReader.

Returns a dictionary with additional attributes.

class paicos.readers.paicos_readers.ImageReader(basedir='.', snapnum=None, basename='projection', load_all=True)

Bases: PaicosReader

This is a subclass of the PaicosReader.

It reads the additional information stored in image files and makes them accessible as attributes, i.e., extent, widths, center, direction and image_creator.

For projection files, it also tries to automatically get derived variables, e.g., if the hdf5 file contains

‘MagneticFieldSquaredTimesVolume’ and ‘Volume’

then it will automatically divide them to obtain the MagneticFieldSquared.

__init__(basedir='.', snapnum=None, basename='projection', load_all=True)

See documentation for the PaicosReader.

Returns a dictionary with additional attributes.

get_centered_image_coordinates()
get_derived_images()

Calculate images automatically for convenience, e.g., 0_MagneticFieldSquaredTimesVolume and 0_Volume are divided to obtain a 2D-array with 0_MagneticFieldSquared

get_image_coordinates()
class paicos.readers.paicos_readers.PaicosReader(basedir='.', snapnum=None, basename='snap', basesubdir='snapdir', load_all=True, to_physical=False, verbose=False)

Bases: dict

The PaicosReader can read any hdf5 file that contains the three groups: Header, Config and Parameters.

It uses these to automatically construct a variety quantities which become accessible as properties.

This class is subclassed by the Snapshot and Catalog classes.

__init__(basedir='.', snapnum=None, basename='snap', basesubdir='snapdir', load_all=True, to_physical=False, verbose=False)

Initialize the PaicosReader class.

Parameters:

  • basedir (str) – The path of the directory containing the hdf5 files (e.g. the ‘output’ folder).

  • snapnum (int) – e.g. the snapshot number

  • basename (str) – name of the file takes the form basename_{:03d}.hdf5 or basename_{:03d}.{}.hdf5. Default is snap.

  • basesubdir (str) – The name of the subfolder. Default is snapdir.

  • load_all (bool) – Whether to simply load all data, default is True.

  • to_physical (bool) – Whether to convert from comoving to physical variables upon load.

  • verbose (bool) – Whether to print information, default is False.

property a

The scale factor.

property age

The age of the universe in the simulation.

find_unit(name, field)

Find unit for a given quantity.

Parameters:

  • name – corresponds to a block name in Arepo snapshots, i.e., a key in one of the dictionaries defined in unit_specifications.py

  • field –

    the name of of one of the dictionaries defined in the unit specifications, e.g,:

    [‘default’, ‘voronoi_cells’, ‘dark_matter’, ‘stars’, ‘black_holes’, ‘groups’, ‘subhalos’]

get_adiabiatic_index()

Returns the adiabatic index

get_age(z)

Returns the age of the universe for a given redshift, z.

get_lookback_time(z)

Returns the lookback time for a given redshift, z.

get_paicos_quantity(data, name, field='default')

Convert some data to a PaicosQuantity.

Parameters:

  • data – typically some numpy array, integer or float

  • name – corresponds to a block name in Arepo snapshots, i.e., a key in one of the dictionaries defined in unit_specifications.py

  • field –

    the name of of one of the dictionaries defined in the unit specifications, e.g,:

    [‘default’, ‘voronoi_cells’, ‘dark_matter’, ‘stars’, ‘black_holes’, ‘groups’, ‘subhalos’]

Returns: A PaicosQuantity

property h

The reduced Hubble parameter

property length

The unit of length used in the simulation.

load_data(name, group=None)

Load data from a generic Paicos hdf5 file (written by a PaicosWriter instance).

The method requires that the data sets have a ‘unit’ attribute and hence does not work for Arepo hdf5 files. For this reason, this method is overloaded in the Snapshot and Catalog classes.

property lookback_time

The lookback time.

property mass

The unit of mass used in the simulation.

rho_crit(z)

Returns the physical critical density (no a or h factors)

property time

The time elapsed since the beginning of the simulation.

Only defined for non-comoving simulations.

unit_quantity(astropy_unit_str)

Returns a Paicos quantity with value 1 and any astropy unit.

uq(astropy_unit_str)

A short hand for the unit_quantity method.

property velocity

One of the units used for velocities in the simulation.

Note: The a and h-scalings are not the same for velocities in the halo catalogs and in the snapshots.

property z

The redshift.

Module contents

HDF5 Writers

paicos.writers package

Submodules

paicos.writers.arepo_image module

This defines a class for saving images as hdf5 files in a systematic way.

class paicos.writers.arepo_image.ArepoImage(image_creator, basedir, basename='projection', mode='w')

Bases: PaicosWriter

A derived data format for Arepo snapshots.

A common task is to reduce Arepo snapshots to 2D arrays (either slices or projections) which can plotted as images. The computation of the 2D arrays can be time-consuming for high-resolution simulations with large snapshots. The purpose of this class is to define a derived data format which can be used to store images for later plotting with matplotlib.

__init__(image_creator, basedir, basename='projection', mode='w')

Initialize an HDF5 file for storing an image.

This class is intended to be used with images created using a Paicos Projector or Slicer object, which can be passed as the image_creator input argument.

The image data, including ‘center’, ‘widths’, ‘extent’, and ‘direction’, will be extracted from the image_creator object and stored in the HDF5 file. The HDF5 file is created in the basedir folder, with the name basename_{:03d}.

The mode argument controls whether the file is opened in write mode (‘w’) or amend mode (‘a’). If mode is ‘w’, the file will be created at self.tmp_filename and the image information will be written to the file. Setting the mode to amend mode, ‘a’, allows to add new images to an already existing file.

Parameters:

  • image_creator (object) – A Paicos Projector or Slicer object used to create the image.

  • (file (basedir) – The folder where the image file should be saved.

  • basename (string) – The base name for the image file, which will be in the format basename_{:03d}. (default: “projection”).

  • mode (string) – The mode to open the file in, either ‘w’ for write mode or ‘a’ for append mode. (default: ‘w’).

finalize :

Changes the filename from a temporary one to the final one, e.g., from self.tmp_filename to self.filename.

save_image(name, data)

This method saves a 2D image to the hdf5 file.

paicos.writers.arepo_image.ImageWriter

alias of ArepoImage

paicos.writers.paicos_writer module

Defines hdf5 file writers that can be read with a PaicosReader instance.

class paicos.writers.paicos_writer.PaicosTimeSeriesWriter(reader_object, basedir, basename='paicos_time_series', add_snapnum=False, mode='w')

Bases: PaicosWriter

Similar to the standard PaicosWriter but here we ensure that the snapnum is not part of the resulting filename for the hdf5 file.

class paicos.writers.paicos_writer.PaicosWriter(reader_object, basedir, basename='paicos_file', add_snapnum=True, mode='w')

Bases: object

This class can be used for writing data to self-documenting hdf5 files.

It is the base class for the ArepoImage writer.

__init__(reader_object, basedir, basename='paicos_file', add_snapnum=True, mode='w')

The constructor for the PaicosWriter class.

Parameters:

  • reader_object (obj) – A PaicosReader object (or Snaphot or Catalog object).

  • basedir (file path) – The folder where the HDF5 file will be saved.

  • basename (str, optional) – Base name of the HDF5 file. Defaults to “paicos_file”.

  • add_snapnum (bool) –

    Whether to add the snapnum to the HDF5 filename.

    When True, the filename will be “basename_{:03d}.hdf5”, when False it will simply be “basename.hdf5” Defaults to True.

  • mode (string) – The mode to open the file in, either ‘w’ for write mode or ‘a’ for append mode. (default: ‘w’).

finalize()

Move from a temporary filename to the final filename.

write_data(name, data, data_attrs={}, group=None, group_attrs={})

Write a data set to the hdf5 file.

Parameters:

  • name (str) – Name of the data to be written.

  • data (obj) – The data to be written (e.g. PaicosQuantity, PaicosTimeSeries, Astropy Quantity, numpy array).

  • data_attrs (dict) –

    Dictionary of attributes for the data. E.g.:

    {'info': 'Here I have written some extra information about the data set'}

    Defaults to an empty dictionary.

  • group (str, optional) – Group in the HDF5 file where the data should be saved. Defaults to None in which case the data set is saved at the top level of the hdf5 file).

  • group_attrs (dict, optional) – Dictionary of attributes for the group. Defaults to an empty dictionary.

Module contents

Image creators (projectors and slicers)

paicos.image_creators package

Submodules

paicos.image_creators.gpu_ray_projector module

paicos.image_creators.gpu_sph_projector module

paicos.image_creators.image_creator module

This defines a base class for image creators (such as Projector and Slicer)

class paicos.image_creators.image_creator.ImageCreator(snap, center, widths, direction, npix=512, parttype=0)

Bases: object

This is a base class for creating images from a snapshot.

__init__(snap, center, widths, direction, npix=512, parttype=0)

Initialize the ImageCreator class. This method will be called by subclasses such as Projector or Slicer.

Parameters:

  • snap (object) – Snapshot object from which the image is created.

  • center – Center of the image (3D coordinates).

  • widths – Width of the image in each direction (3D coordinates)

  • direction (str, Orientation) – Direction of the image (‘x’, ‘y’, ‘z’) or an Orientation instance.

  • npix (int) – Number of pixels in the image (default is 512).

property area

The area of the image plane.

property area_per_pixel

The area per pixel of the image plane.

property center

Center of the image (3D coordinates).

property centered_extent

Same as ‘extent’ but centered on the center of the image.

property depth

The depth of the image.

do_unit_consistency_check()

This function is called inside image creators to ensure that length units are consistent.

double_resolution()

Calling this method doubles the pixel resolution of the image creator.

property extent

The extent of the image in the horizontal-vertical plane. The idea with this property is that it corresponds to the matplotlib imshow keyword argument ‘extent’. When using units, one has to remember to pass image_creator.extent.value rather than image_creator.extent.

half_resolution()

Calling this method halves the pixel resolution of the image creator.

property height

The vertical height of the image.

info()

Prints some information about the image creator instance. TODO: Add things like the number of cells/particles in the current instance.

move_center_along_normal_vector(shift)

Moves the center of the image along its depth direction. Value can be positive or negative and must have same units as the center.

(TODO: In principle we could just convert the distance to same units).

move_center_along_perp_vector1(shift)

Moves the center of the image along its horizontal direction. Value can be positive or negative and must have same units as the center.

(TODO: In principle we could just convert the distance to same units).

move_center_along_perp_vector2(shift)

Moves the center of the image along its vertical direction. Value can be positive or negative and must have same units as the center.

(TODO: In principle we could just convert the distance to same units).

property npix

The number of pixels along the horizontal direction of the image.

property npix_height

The number of pixels of an image in the vertical direction.

property npix_width

The number of pixels along the horizontal direction of the image.

property parttype

The parttype being imaged, e.g. parttype=0 are the Voronoi gas cells.

reset_center()

Resets the center of the image creator to the value it had at initialization.

property volume

The volume of the projection region (0 for slices).

property volume_per_pixel

The volume per pixel in the image.

property width

The horizontal width of the image.

property width_x

The x-component of .widths

property width_y

The y-component of .widths

property width_z

The z-component of .widths

property widths

Width of the image in each direction (3D coordinates).

property x_c

The x-component of .center

property y_c

The y-component of .center

property z_c

The z-component of .center

zoom(factor)

Calling this method zooms the view by the input factor, that is, the horizontal width and vertical height of the image creator is changed like this:

width = width / factor

height = height / factor

A factor less than one zooms out the view.

paicos.image_creators.image_creator_actions module

class paicos.image_creators.image_creator_actions.Actions(snapnum=None, image_creator=None, dry_run=True)

Bases: object

The purpose of this class is to simplify the steps that are usually involved in creating animations and/or interactive widgets.

This is very much work in progress and subject to change. Send Thomas an email if you would like a working example.

change_snapnum(snapnum)
create_log(outfolder='.', basename='image')
depth(arg)
double_resolution()
expand_log(zoom_max=1.02, max_angle=1, verbose=False, outfolder=None, basename=None)
half_resolution()
height(arg)
make_image_creator(snapnum)

TODO: Add example implementation in the docstring of of this method.

move_center(diff)
move_center_sim_coordinates(diff)
mylogger(string, line_ending='\n', mode='a', command=True)
property next_action
property previous_action
read_log(filename=None, outfolder='.', basename='image')
reset_center()
resume_from_image(filename, frame_num)
resume_from_waypoint(frame_num)
rotate_around_normal_vector(arg)
rotate_around_perp_vector1(arg)
rotate_around_perp_vector2(arg)
step(verbose=False)
width(arg)
zoom(factor)
paicos.image_creators.image_creator_actions.find_angle_subdivisions(angle, max_angle)
paicos.image_creators.image_creator_actions.find_zoom_sub_divisions(zoom, zoom_max)

paicos.image_creators.nested_projector module

Defines a class that creates an image of a given variable by projecting it onto a 2D plane using nested grids.

class paicos.image_creators.nested_projector.NestedProjector(snap, center, widths, direction, npix=512, nvol=8, factor=3, npix_min=128, verbose=False, make_snap_with_selection=True, store_subimages=False)

Bases: Projector

This class implements an SPH-like projection of gas variables using nested grids. It is a subclass of the Projector class, and inherits its properties. It has additional attributes for handling the nested grid projections, and additional methods for dealing with resolution, digitizing particles, and summing up the different resolutions of the images.

Please see also the Projector class.

__init__(snap, center, widths, direction, npix=512, nvol=8, factor=3, npix_min=128, verbose=False, make_snap_with_selection=True, store_subimages=False)

This is the constructor for the NestedProjector class. It initializes the properties inherited from the Projector class, as well as the properties specific to nested projections.

Parameters:

  • snap (Snapshot) – A snapshot object of Snapshot class from paicos package.

  • center (array) – Center of the region on which projection is to be done, e.g. center = [x_c, y_c, z_c].

  • widths (array) – Widths of the region on which projection is to be done, e.g.m widths=[width_x, width_y, width_z].

  • direction (str or Orientation) – Direction of the projection, e.g. ‘x’, ‘y’ or ‘z’, or its orientation (see Orientation class).

  • npix (int, optional) – Number of pixels in the horizontal direction of the image, by default 512.

  • nvol (int, optional) – Integer used to determine the smoothing length, by default 8

  • factor (int, optional) – Multiplicative factor in digitizing, defaults to 3.

  • npix_min (int, optional) – Minimum number of pixels, defaults to 128.

  • verbose (bool, optional) – Flag for verbosity, defaults to False.

  • make_snap_with_selection (bool, optional) – a boolean indicating if a new snapshot object should be made with the selected region, defaults to False.

  • store_subimages (bool, optional) – Flag for storing sub-images, which is useful mainly for testing purposes. Defaults to False.

paicos.image_creators.projector module

Defines a class that creates an image of a given variable by projecting it onto a 2D plane.

class paicos.image_creators.projector.Projector(snap, center, widths, direction, npix=512, parttype=0, nvol=8, make_snap_with_selection=True)

Bases: ImageCreator

A class that allows creating an image of a given variable by projecting it onto a 2D plane.

The Projector class is a subclass of the ImageCreator class. The Projector class creates an image of a given variable by projecting it onto a 2D plane.

It takes in several parameters such as a snapshot object, center and widths of the region, direction of projection, and various optional parameters for number of pixels, smoothing length.

__init__(snap, center, widths, direction, npix=512, parttype=0, nvol=8, make_snap_with_selection=True)

Initialize the Projector class.

Parameters:

  • snap (Snapshot) – A snapshot object of Snapshot class from paicos package.

  • center (numpy array) – Center of the region on which projection is to be done, e.g. center = [x_c, y_c, z_c].

  • widths (numpy array) – Widths of the region on which projection is to be done, e.g.m widths=[width_x, width_y, width_z].

  • direction (str, Orientation) – Direction of the projection, e.g. ‘x’, ‘y’ or ‘z’ or an Orientation instance.

  • npix (int, optional) – Number of pixels in the horizontal direction of the image, by default 512.

  • parttype (int, optional) – Number of the particle type to project, by default gas (PartType 0).

  • nvol (int, optional) – Integer used to determine the smoothing length, by default 8

project_variable(variable)

projects a given variable onto a 2D plane.

Parameters:

variable (str, array) – The variable to be projected, it can be passed as string or a 1d array.

Returns:

The image (2d array) of the projected variable.

Return type:

numpy array

paicos.image_creators.ray_projector module

paicos.image_creators.slicer module

paicos.image_creators.tree_projector module

Defines a class that creates an image of a given variable by projecting the Voronoi cells closest to the line of sight using a KDTree.

class paicos.image_creators.tree_projector.TreeProjector(snap, center, widths, direction, npix=512, npix_depth=None, parttype=0, make_snap_with_selection=False, tol=1, verbose=False, timing=False)

Bases: ImageCreator

This implements projection of gas variables by adding up several slices.

__init__(snap, center, widths, direction, npix=512, npix_depth=None, parttype=0, make_snap_with_selection=False, tol=1, verbose=False, timing=False)

Initialize the Slicer object.

Parameters:

  • snap (Snapshot) – A snapshot object of Snapshot class from paicos package.

  • center – Center of the region on which projection is to be done, e.g. center = [x_c, y_c, z_c].

  • widths – Widths of the region on which projection is to be done, e.g. widths=[width_x, width_y, width_z].

  • direction (str, Orientation) – Direction of the projection, e.g. ‘x’, ‘y’ or ‘z’, or an Orientation instance.

  • npix (int, optional) – Number of pixels in the horizontal direction of the image, by default 512.

  • parttype (int, optional) – The particle type to project, by default gas (PartType 0).

  • npix_depth (int, optional) – Number of pixels in the depth direction, by default set automatically based on the smallest cell sizes in the region and the tolerance parameter, tol (see below).

  • tol (float, optional) – Smaller values of tol adds more slices to the integration. Convergence is expected for tol ≤ 1 but you can experiment with higher values.

  • make_snap_with_selection (bool) – a boolean indicating if a new snapshot object should be made with the selected region, defaults to False.

project_variable(variable, additive=True, extrinsic=None, timing=False)

Project gas variable based on the Voronoi cells closest to each line of sight.

The behavior of this method depends on whether the variable to be projected is additive (extrinsic) or not (intrinsic). (see e.g. https://en.wikipedia.org/wiki/Intensive_and_extensive_properties).

For non-additive (intrinsic) properties, e.g. the density ρ, the returned projection, P, is

P = 1/L ∫ ρ dl ,

where L is the depth of the projection. That is, it is simply the mean of a number of slices.

For additive (extrinsic) properties, e.g. mass M, the returned projection is instead

P = 1 / dA ∫ dM

where dA is the area per pixel and dM is the mass inside a voxel.

Parameters:

  • variable (str, array) – The variable to be projected, it can be passed as string or a 1d array.

  • additive (bool) – A boolean indicating whether the variable to be projected is additive (e.g. Masses, Volumes) or not (e.g. Temperature, density). This parameter was previously named ‘extrinsic’.

  • Returns –

    projection2d arr

    A 2d array representing the projected gas variable.

    For non-additive (intrinsic) variables, the unit of the projection is identical to the unit of the input variable. For additive (extrinsic) variables, the projection unit is the input variable unit divided by area.

Examples

We can compute the projected density in two ways, using either additive or non-additive projetions. In both case, we first need to create a TreeProjector object:

tree_projector = pa.TreeProjector(snap, center, widths, 'z')

Method I (divide projected mass by projected volume):

tree_M = tree_projector.project_variable('0_Masses', additive=True)
tree_V = tree_projector.project_variable('0_Volume', additive=True)

tree_rho = tree_M / tree_V

Method II (directly project the density):

rho = tree_projector.project_variable('0_Density', additive=False)

Module contents

1D and 2D Histograms

paicos.histograms package

Submodules

paicos.histograms.histogram module

paicos.histograms.histogram2D module

Module contents