Reference on kuibit.cactus_grid_functions

The cactus_grid module provides functions to load grid function in Cactus formats.

There are multiple classes defined in this module:

  • :py:class`~.GridFunctionsDir` interfaces with SimDir and organizes the grid functions by dimensionality. This is a dictionary-like object with keys the possible dimensions (e.g., x, yz, xyz).

  • :py:class`~.AllGridFunctions` takes all the files in SimDir and sort them according the different grid functions they contain.

  • There are three :py:class`~.OneGridFunction` classes, one for HDF5 files, one for ASCII files, and one for OpenPMD files. They describe one single grid function and they contains the files associated to that grid function. Both the classes are derived from the same abstract base class :py:class`~.OneGridFunctionBase`, which implements the shared methods.

These are hierarchical classes, one containing the others, so one typically ends up with a series of brackets to access the actual data. For example, if sim is a SimDir, sim.gf.xy['rho_b'][0] is rho_b at iteration 0 on the equatorial plane represented as HierarchicalGridData.

class kuibit.cactus_grid_functions.AllGridFunctions(allfiles, dimension, num_ghost=None)[source]

Helper class to read various types of grid data in a list of files and properly order them. The core of this object is the _vars dictionary which contains the location of all the files for a specific variable and reduction.

AllGridFunction is a dictionary-like object with keys the various variables and values BaseOneGridFunction (or derived).

You can access data with the bracket operator or as attributes of the fields attribute.

Not intended for direct initialization.

Variables:

  • dimension – Dimension associated to this object (e.g. (0, 1) would be the xy plane).

  • num_ghost – Number of ghost zones in each dimension.

Constructor.

Parameters:

  • allfiles (list) – List of all the files.

  • dimension (tuple) – Dimension associated to this object.

  • num_ghost (list or tuple of the same length as the number of dimension) – Number of ghost zones in the data for each dimension. This is used only for ASCII data.

property allfiles

Return a set of all the files that have variables of the given dimension

Returns:

Collection of all the unique files with variables of this dimension.

Return type:

set

get(key, default=None)[source]

Return variable key.

Parameters:

  • key (str) – Variable to read.

  • default (anything) – Value to return is variable is not available.

keys()[source]

Return the list of all the available variables.

property num_ghost

Return the number of ghost zones along each direction.

Returns:

Number of ghost zones along each direction.

Return type:

1d NumPy array

total_filesize(unit='MB')[source]

Return the total size of the files with this dimension. Available units B, KB, MB and GB (in power of 1024 bytes).

Parameters:

unit (str among: B, KB, MB, GB.) – Unit to use (in powers of 1024 bytes).

Returns:

Total size of all the files associated with this dimension.

Return type:

float

class kuibit.cactus_grid_functions.BaseOneGridFunction(allfiles, var_name)[source]

Abstract class that implements capabilities to handle grid functions.

This class is the parent class of OneGridFunctionASCII and OneGridFunctionH5. BaseOneGridFunction implements most methods, except the readers.

The derived classes have to specify:

  • How to read a file, populating the self.alldata dictionary (method _parse_file).

  • How to populate the last level of self.alldata by returning a UniformGridData for a given iteration and component (method _read_componenent_as_uniform_grid)

  • How to associate an iteration with a time (method time_at_iteration).

The simplest way to access data at a given iteration as HierarchicalGridData is using the [] notation.

Variables:

  • allfiles – Paths of files associated to the variable.

  • alldata – Dictionary that organizes files and iterations available.

  • restarts_data – How iterations are distributed across files.

  • var_name – Variable name.

Constructor.

Parameters:

  • allfiles (list of str) – Paths of files associated to the variable.

  • var_name (str) – Variable name.

property available_iterations

Return the available iterations.

Returns:

List with all the available iterations.

Return type:

list

property available_times

Return the available times.

Returns:

List with all the available times.

Return type:

list

get_iteration(iteration, default=None)[source]

Return the data at the given iteration as a HierarchicalGridData. If the iteration is not available, return default.

Parameters:

  • iteration (int) – Iteration.

  • default (anything) – What to return if iteration is not available.

Returns:

Variable at the given iteration as a HierarchicalGridData.

Return type:

HierarchicalGridData

get_time(time, default=None)[source]

Return the data at the given time as a HierarchicalGridData. If the time is not available, return default.

Parameters:

  • iteration (int) – Iteration.

  • default (anything) – What to return if time is not available.

Returns:

Variable at the given time as a HierarchicalGridData.

Return type:

HierarchicalGridData

iteration_at_time(time)[source]

Return the iteration that corresponds to the given time.

Parameters:

time (float) – Time.

Returns:

Iteration corresponding to the given time.

Return type:

int

property iterations

Return the available iterations.

Returns:

List with all the available iterations.

Return type:

list

property max_iteration

Return the maximum available iteration in the all the files.

Returns:

Latest iteration available.

Return type:

int

property min_iteration

Return the minimum available iteration in the all the files.

Returns:

First iteration available.

Return type:

int

read_on_grid(iteration, grid, resample=False)[source]

Read an iteration and resample the output on the specified grid.

Warning: this can be computationally expensive!

Parameters:

  • iteration (time) – requested iteration

  • grid (UniformGrid) –

  • resample (bool) – Whether to use multilinear interpolation

property restarts

Return a list of tuples of the form (iteration_min, iteration_max, paths) with the minimum iterations and maximum iterations in each file associated to this variable. paths is a list of all the files with same min_iteration and max_iteration (as when we have 3d xyz_file files).

Returns:

List of tuples with first iteration, last iteration, and path for every file in self.allfiles.

Return type:

list of tuple (int, int, list of str)

abstract time_at_iteration(iteration)[source]

Return the time at a given iteration.

Parameters:

iteration (int) – Iteration.

Returns:

Time.

Return type:

float

property times

Return the available times.

Returns:

List with all the available times.

Return type:

list

total_filesize(unit='MB')[source]

Return the total size of the files with this variable. Available units B, KB, MB and GB (in power of 1024 bytes).

Parameters:

unit (str among: B, KB, MB, GB.) – Unit to use (in powers of 1024 bytes).

Returns:

Total size of the files associated to this variable.

Return type:

float

class kuibit.cactus_grid_functions.GridFunctionsDir(sd)[source]

This class provides access to all grid data.

This includes 1D-3D data in HDF5 and ASCII formats. Data of the required dimensionality is read from any format available (HDF5 preferred over ASCII). If you need lower dimensional data, read the higher dimensional one and slice the data.

Variables:

  • x – Access to 1D data along x-axis.

  • y – Access to 1D data along y-axis.

  • z – Access to 1D data along z-axis.

  • xy – Access to 2D data along xy-plane.

  • xz – Access to 2D data along xz-plane.

  • yz – Access to 2D data along yz-plane.

  • xyz – Access to 3D data.

Constructor.

Parameters:

sd (SimDir) – Simulation directory.

total_filesize(unit='MB')[source]

Return the total size of the grid data files. Available units B, KB, MB and GB (in power of 1024 bytes).

Parameters:

unit (str among: B, KB, MB, GB.) – Unit to use (in powers of 1024 bytes).

Returns:

Total size of the grid data files.

Return type:

float

class kuibit.cactus_grid_functions.OneGridFunctionASCII(allfiles, var_name, num_ghost=None)[source]

Read grid data produced by CarpetASCII.

This class is derived from BaseOneGridFunction and implements the reading facilities.

OneGridFunctionASCII can read 1D, 2D, and 3D ASCII files, even when they are compressed with bzip2 or gzip.

ASCII files do not contain information about the ghost zones, but this can be set “by hand”.

Constructor.

Parameters:

  • allfiles (list of str) – Paths of files associated to the variable.

  • var_name (str) – Variable name.

  • num_ghost (1d NumPy array) – Number of ghost zones in each direction.

time_at_iteration(iteration)[source]

Return the time at a given iteration.

Parameters:

iteration (int) – Iteration.

Returns:

Time at given iteration.

Return type:

float

class kuibit.cactus_grid_functions.OneGridFunctionH5(allfiles, var_name, dimension)[source]

Read grid data produced by CarpetHDF5 files.

This class is derived from BaseOneGridFunction and implements the reading facilities.

Constructor.

Parameters:

  • allfiles (list of str) – Paths of files associated to the variable.

  • var_name (str) – Variable name.

clear_cache()[source]

Remove all the cached entries.

Every time a component is read, OneGridFunctionsH5 caches its value (reading can be expensive). In certain cases, this can lead to an explosion in the size of this object. For example, when reading several iterations to make a movie. This method removes all the cached entries, keeping the size of the object under control.

time_at_iteration(iteration)[source]

Return the time corresponding to the provided iteration.

Parameters:

iteration (int) – Iteration.

Returns:

Time corresponding to iteration.

Return type:

float

class kuibit.cactus_grid_functions.OneGridFunctionOpenPMD(allfiles, var_name, dimension, mesh_basename)[source]

Read grid data produced by CarpetOpenPMD files.

This class is derived from BaseOneGridFunction and implements the reading facilities.

Constructor.

Parameters:

  • allfiles (list of str) – Paths of files associated to the variable.

  • var_name (str) – Variable name.

  • mesh_basename (str) – Basename of the OpenPMD mesh. Typically, <thornname>_<groupname>

clear_cache()[source]

Remove all the cached entries.

Every time a component is read, OneGridFunctionsH5 caches its value (reading can be expensive). In certain cases, this can lead to an explosion in the size of this object. For example, when reading several iterations to make a movie. This method removes all the cached entries, keeping the size of the object under control.

time_at_iteration(iteration)[source]

Return the time corresponding to the provided iteration.

Parameters:

iteration (int) – Iteration.

Returns:

Time corresponding to iteration.

Return type:

float

kuibit.cactus_grid_functions.openpmd_series(path)[source]

Context manager to read an OpenPMD file.

Parameters:

path (str) – Path of the file.