Utilities API

Checkpoint Management

CheckpointReader

Helper class to read from either a directory or a ZIP archive checkpoint. Provides unified interface for file access.

class cryoPARES.utils.checkpointReader.CheckpointReader(checkpoint_path)

Bases: object

Helper class to read from either a directory or a ZIP archive checkpoint. Provides unified interface for file access.

Parameters:

checkpoint_path (str)

__init__(checkpoint_path)

Initialize checkpoint reader.

Parameters:

checkpoint_path (str) – Path to checkpoint directory or ZIP file

close()

Clean up resources.

exists(relative_path)

Check if a file exists in the checkpoint.

Return type:

bool

Parameters:

relative_path (str)

read_bytes(relative_path)

Read file as bytes.

Return type:

bytes

Parameters:

relative_path (str)

read_text(relative_path)

Read file as text.

Return type:

str

Parameters:

relative_path (str)

load_torch(relative_path, **kwargs)

Load PyTorch model/tensor from checkpoint.

Parameters:

relative_path (str)

load_jit(relative_path)

Load TorchScript model from checkpoint.

Parameters:

relative_path (str)

get_real_path(relative_path)

Get real filesystem path. For ZIP, extracts to temp directory. Use this only when absolutely necessary (e.g., for mrcfile which needs real paths).

Parameters:

relative_path (str) – Path relative to checkpoint root

Return type:

str

Returns:

Absolute filesystem path

glob(pattern)

Find files matching pattern (relative paths).

Parameters:

pattern (str) – Glob pattern (e.g., “configs_*.yml”)

Return type:

List[str]

Returns:

List of matching file paths (relative to checkpoint root)

Checkpoint Utils

cryoPARES.utils.checkpointUtils.get_best_checkpoint(checkpoint_dir, best_is_less=True)

Get the best checkpoint from a directory.

Parameters: checkpoint_dir (str): Path to the directory containing the checkp Returns: str: The path to the best checkpoint.

cryoPARES.utils.checkpointUtils.increment_generic(generic_string, pattern, count_group_idx)

cryoPARES.utils.checkpointUtils.increment_version(fname_string, path_basename='(.*version_)(\\d+)$', extension=None)

cryoPARES.utils.checkpointUtils.find_last_version(rootdir, count_group_idx=1, path_pattern='(.*version_)(\\d+)$', dir_only=False)

cryoPARES.utils.checkpointUtils.get_version_to_use(rootdir, basename, path_pattern='(.*version_)(\\d+)$', extension=None, dir_only=False)

cryoPARES.utils.checkpointUtils.tmpdir(tmp_path)

cryoPARES.utils.checkpointUtils.test_increment_version()

cryoPARES.utils.checkpointUtils.test_find_last_version_directories(tmpdir)

cryoPARES.utils.checkpointUtils.test_find_last_version_files(tmpdir)

cryoPARES.utils.checkpointUtils.test_find_last_version_mixed(tmpdir)

cryoPARES.utils.checkpointUtils.test_find_last_version_empty(tmpdir)

cryoPARES.utils.checkpointUtils.test_get_version_to_use_existing_file(tmpdir)

cryoPARES.utils.checkpointUtils.test_get_version_to_use_existing_dir(tmpdir)

cryoPARES.utils.checkpointUtils.test_get_version_to_use_empty(tmpdir)

cryoPARES.utils.checkpointUtils.test_custom_pattern_with_dir(tmpdir)

cryoPARES.utils.checkpointUtils.test_get_version_to_use_custom_pattern_empty(tmpdir)

Path Utilities

cryoPARES.utils.paths.find_configs_root()

Find the project configs root by looking for constants.py

Return type:

Path

cryoPARES.utils.paths.find_project_root()

Find the project root by looking for pyproject.toml

Return type:

Path

cryoPARES.utils.paths.get_most_recent_file(folder_path, template)

Finds the most recent file in a directory that matches a given template.

Parameters:

• folder_path (str) – The path to the directory to search.

• template (str) – The filename pattern to match (e.g., ‘file_*.txt’).

Return type:

str | None

Returns:

The path to the most recent file, or None if no matching files are found.

cryoPARES.utils.paths.convert_config_args_to_absolute_paths(config_args)

Convert any relative YAML file paths in config_args to absolute paths.

This is important for subprocess propagation, where relative paths may be resolved relative to a different working directory.

Parameters:

config_args – List of config strings (e.g., [‘config.yaml’, ‘train.n_epochs=100’])

Returns:

List of config strings with YAML file paths converted to absolute paths, or None if config_args is None

PyTorch Utilities

cryoPARES.utils.torchUtils.data_to_numpy(x)

cryoPARES.utils.torchUtils.accelerator_selector(use_cuda=True, n_gpus_torch=None, n_cpus_torch=None)

Reconstruction Utilities

cryoPARES.utils.reconstructionUtils.get_mrc_metadata(mrc_fname)

Read MRC file metadata without loading the full volume data.

Parameters:

mrc_fname (str) – Path to the MRC file

Return type:

Tuple[Tuple[int, int, int], float]

Returns:

Tuple of (shape, sampling_rate) where shape is (nx, ny, nz) and sampling_rate is in Angstroms/pixel

Raises:

• FileNotFoundError – If the file does not exist

• ValueError – If the file is not a valid MRC file

cryoPARES.utils.reconstructionUtils.get_vol(vol, pixel_size, device='cpu')

Return type:

Tuple[Tensor, float]

Parameters:

• vol (PathLike | str | Tensor | ndarray)

• pixel_size (float | None)

• device (device | str)

cryoPARES.utils.reconstructionUtils.write_vol(vol, fname, pixel_size, overwrite=True)

Parameters:

vol (tensor)

cryoPARES.utils.reconstructionUtils.get_rotmat(degAngles, convention='ZYZ', device='cpu')

Parameters:

convention (str)

Geometry Utilities

Angle Conversions

cryoPARES.geometry.convert_angles.euler_angles_to_matrix(euler_angles, convention)

Convert rotations given as Euler angles in radians to rotation matrices.

Parameters:

• euler_angles (Tensor) – Euler angles in radians as tensor of shape (…, 3).

• convention (str) – Convention string of three uppercase letters from {“X”, “Y”, and “Z”}.

Return type:

Tensor

Returns:

Rotation matrices as tensor of shape (…, 3, 3).

cryoPARES.geometry.convert_angles.matrix_to_euler_angles(matrix, convention)

Convert rotations given as rotation matrices to Euler angles in radians.

Parameters:

• matrix (Tensor) – Rotation matrices as tensor of shape (…, 3, 3).

• convention (str) – Convention string of three uppercase letters.

Return type:

Tensor

Returns:

Euler angles in radians as tensor of shape (…, 3).

Angle Metrics

cryoPARES.geometry.metrics_angles.rotation_magnitude(rot)

Compute rotation magnitude in radians.

Parameters:

rot – tensor of shape (…,3,3)

Returns:

The rotation magnitude in radians

cryoPARES.geometry.metrics_angles.nearest_rotmat_idx(src, targets)

Return index of target that is nearest to each element in src.

Uses negative trace of the dot product to avoid arccos operation.

Parameters:

• src – tensor of shape (B, 3, 3)

• targets – tensor of shape (…, 3, 3)

Returns:

• dot_trace: The value of the trace of the selected nearest rotmat idxs

• idxs: The idxs of the nearest rotation matrices

cryoPARES.geometry.metrics_angles.rotation_error_rads(rotA, rotB)

Compute rotation error in radians between two rotation matrices.

Parameters:

• rotA – tensor of shape (…,3,3). Rotation matrix

• rotB – tensor of shape (…,3,3). Rotation matrix

Returns:

rotation error in radians, tensor of shape (…)

cryoPARES.geometry.metrics_angles.rotation_error_with_sym(rotA, rotB, symmetry=None)

Compute rotation error in radians between two rotation matrices with symmetry.

Parameters:

• rotA – tensor of shape (…,3,3). Rotation matrix

• rotB – tensor of shape (…,3,3). Rotation matrix

• symmetry – string or None. Symmetry group (e.g., ‘I’, ‘O’, ‘T’, ‘D7’, etc.) If None, computes standard rotation error without symmetry

Returns:

rotation error in radians, tensor of shape (…)

cryoPARES.geometry.metrics_angles.mean_rot_matrix(rotMatrices, dim, weights=None, compute_dispersion=True)

Parameters:

• rotMatrices (Tensor) – (…, 3,3)

• dim (int)

• weights (Optional[Tensor]) – (…)

• compute_dispersion (bool)

Returns:

Symmetry

Grid Utilities

cryoPARES.geometry.grids.hp_order_to_degs(hp_order)

cryoPARES.geometry.grids.pick_hp_order(grid_resolution_degs)