pressomancy.analysis package

Submodules

pressomancy.analysis.data_analysis module

class pressomancy.analysis.data_analysis.H5DataSelector(h5_file, particle_group, ts_slice=None, pt_slice=None)

Bases: object

A simplified interface to access simulation data stored in an HDF5 file. The H5DataSelector maintains internal slice information for timesteps (axis 0) and particles (axis 1) and supports chaining via its accessor properties:

• .timestep: Provides an interface for slicing/iterating over timesteps.

• .particles: Provides an interface for slicing/iterating over particles.

Usage Examples:

# Slice timesteps 10 to 20 (inclusive of the start, exclusive of the stop) time_subset = data.timestep[10:20]

# Slice particles 0 to 100 particle_subset = data.particles[:100]

# Chain slicing: sub = data.timestep[:5].particles[0:10]

# Retrieve property data (e.g., positions): pos = data.pos # This calls get_property(“pos”)

# Retrieve saved frame counters and physical times: step = data.step time = data.time

# Connectivity-based particle selection: filament_particles = data.select_particles_by_object(“Filament”, connectivity_value=0) monomer_subset = filament_particles.particles[10:20].timestep[5]

# Predicate-based particle selection: final_type = data.select_particles_by_object(

“Filament”, connectivity_value=0, predicate=lambda subset: subset.type == 1,

)

Notes:

• Direct indexing on a top-level H5DataSelector is disallowed to ensure explicit axis selection. Use the accessor properties (.timestep or .particles) for slicing.

• .timestep[…] slices by frame index on axis 0. It does not query the stored HDF5 step or time datasets.

• .step and .time read from the particle group’s pos/step and pos/time datasets. These are treated as the canonical particle timeline; the writer stores the same step/time values for every particle property in a frame.

• Iteration and len() are only defined on the accessor objects.

• Connectivity predicates are evaluated on the current H5DataSelector view. They select particles, not timesteps: the returned selector preserves the current timestep slice and only narrows the particle slice.

Raises:

• ValueError if the dimensions of the stored property datasets are inconsistent.

get_box()

Return fixed-box metadata for the current particle group.

get_child_ids(parent_key, child_key, parent_id)

Retrieve a sorted list of child object IDs connected to a given parent_id.

This method first attempts to obtain the connectivity map relating the parent and child objects. If the connectivity map is not found (i.e., None), a warning is issued and None is returned. Otherwise, it filters the connectivity entries to select rows with the matching parent_id, extracts the corresponding child IDs, converts them to integers, sorts them, and returns the resulting list.

Parameters:

• parent_key (str) – Name of the parent object type.

• child_key (str) – Name of the child object type.

• parent_id (int) – The identifier for the parent object.

Returns:

A sorted list of child object IDs connected to the given parent_id. Returns None if the connectivity map is missing.

Return type:

List[int] or None

get_connectivity_map(parent_key, child_key)

Retrieve the connectivity map between parent and child objects from the HDF5 file.

This method constructs a dataset path based on the particle group and the specified parent and child keys, then attempts to retrieve an array of [parent_id, child_id] pairs from the HDF5 connectivity group. If the dataset is not found, a warning is issued and None is returned.

Parameters:

• parent_key (str) – Name of the parent object type (e.g. “Filament”).

• child_key (str) – Name of the child object type (e.g. “Quadriplex”).

Returns:

An array containing [parent_id, child_id] pairs if the connectivity map exists; otherwise, None.

Return type:

ndarray of shape (N, 2) or None

get_connectivity_values(object_name, predicate=None, fast=False)

Return object IDs present in ParticleHandle_to_<object_name>.

When a predicate is provided, each candidate object ID is first mapped to the particle indices of the current particle group. This keeps the returned per-object subset aligned with particles/<particle_group> even when ParticleHandle_to_<object_name> is not in that particle group’s storage order.

Connectivity IDs are static. The predicate is therefore an object-ID filter: it may inspect particle properties on the per-object subset, but it must return one scalar truth value for the candidate object ID. If it inspects time-dependent arrays, reduce them explicitly with any, all, or an explicit timestep selection.

Parameters:

• object_name (str) – Name of the connected object type (e.g. “Filament”).

• predicate (callable, optional) – Function that accepts a per-object H5DataSelector subset and returns True when that object ID should be kept. The subset is provided only for inspection and preserves the current selector’s timestep slice.

• fast (bool, optional) – If True, assume the predicate is prefix-monotone over the sorted object IDs and use a divide-and-conquer search for the cutoff.

Returns:

Array of object IDs.

Return type:

ndarray of shape (N,)

get_parent_ids(parent_key, child_key, child_id)

Return a sorted list of parent object IDs connected to a given child_id.

Parameters:

• parent_key (str) – Name of the parent object type.

• child_key (str) – Name of the child object type.

• child_id (int) – The who_am_i identifier of the child object.

Returns:

Sorted list of parent who_am_i IDs that link to the child.

Return type:

List[int]

get_property(prop)

Retrieve data for a given property from the HDF5 dataset applying the current slices.

Parameters:

prop (str) – The property name (e.g., ‘pos’, ‘f’).

Returns:

The dataset with the applied timestep and particle slices.

Return type:

ndarray

property particles

Accessor for slicing/iterating over the particle axis.

Returns:

An accessor object for particle operations.

Return type:

ParticleAccessor

Usage:

# Slicing particles 0 to 100: data.particles[0:100]

# Iterating over each particle in a slice: for p in data.particles[20:30]:

process(p)

sanity_check(metadata, particle_group)

Ensures that all properties in a given particle group have consistent timestep and particle dimensions.

Parameters:

• metadata (dict) – The hierarchical dictionary of the HDF5 structure.

• particle_group (str) – The name of the particle group.

Returns:

(timesteps, particles) common to all valid ‘value’ datasets.

Return type:

tuple

Raises:

ValueError – If the particle group is not found or dimensions are inconsistent.

select_particles_by_object(object_name, connectivity_value, predicate=None)

Select particles belonging to one or more connected object IDs.

The connectivity table stores particle handles, so this method maps those handles back to indices in particles/<particle_group> before composing a new particle slice. The current timestep slice is preserved.

A predicate can further narrow the selected particles. It is evaluated on the current H5DataSelector subset, not on individual particle objects. Predicate masks select particles only:

• a 1D mask must have shape (n_particles,);

• a 2D mask must have shape (n_timesteps, n_particles) and is reduced with all over the current timestep context.

This means predicate=lambda subset: subset.type == value keeps particles matching the value at every timestep in the current view, while predicate=lambda subset: subset.timestep[-1].type == value classifies particles by the last timestep of the current view and then returns those particles across the original timestep slice.

Parameters:

• object_name (str) – Name of the connectivity object (e.g., “Filament”).

• connectivity_value (int or float or array-like) – Object ID value or values to match in the connectivity map.

• predicate (callable, optional) – Function taking an H5DataSelector and returning a particle mask as described above.

Returns:

A new selector with the same timestep slice and the particle slice set to the selected particle indices.

Return type:

H5DataSelector

property step

Return saved frame counters from the particle group’s canonical pos/step dataset.

property time

Return saved physical times from the particle group’s canonical pos/time dataset.

property timestep

Accessor for slicing/iterating over the timestep axis.

Returns:

An accessor object for timestep operations.

Return type:

TimestepAccessor

Usage:

# Slicing timesteps 10 to 20: data.timestep[10:20]

# Iterating over each timestep in a slice: for t in data.timestep[5:10]:

process(t)

class pressomancy.analysis.data_analysis.H5ObservableSelector(h5_file, observable_name, ts_slice=None)

Bases: object

A simplified interface to access observable data stored in an HDF5 file.

The selector maintains internal slice information for the timestep axis only and exposes direct access to the stored step, time, and value datasets under /observables/<name>.

sanity_check(metadata, observable_name)

property step

property time

property timestep

property value

class pressomancy.analysis.data_analysis.ParticleAccessor(sim_data)

Bases: object

An accessor for slicing and iterating over particles of a H5DataSelector.

It composes new particle indices with any existing slice and enables iteration where each iteration yields a H5DataSelector corresponding to a single particle index.

class pressomancy.analysis.data_analysis.TimestepAccessor(sim_data)

Bases: object

An accessor for slicing and iterating over timesteps of an HDF5 selector.

It composes new timestep slices with any existing slice and delegates selector reconstruction to the parent selector.