Reconstruction API

Reconstructor

class cryoPARES.reconstruction.reconstructor.Reconstructor(symmetry, correct_ctf=<autoCLI_config.config_param.CONFIG_PARAM object>, eps=<autoCLI_config.config_param.CONFIG_PARAM object>, min_denominator_value=<autoCLI_config.config_param.CONFIG_PARAM object>, weight_with_confidence=<autoCLI_config.config_param.CONFIG_PARAM object>, *args, **kwargs)

Bases: Module

Parameters:

• symmetry (str)

• correct_ctf (bool)

• eps (float)

• min_denominator_value (float)

• weight_with_confidence (bool)

__init__(symmetry, correct_ctf=<autoCLI_config.config_param.CONFIG_PARAM object>, eps=<autoCLI_config.config_param.CONFIG_PARAM object>, min_denominator_value=<autoCLI_config.config_param.CONFIG_PARAM object>, weight_with_confidence=<autoCLI_config.config_param.CONFIG_PARAM object>, *args, **kwargs)

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Parameters:

• symmetry (str)

• correct_ctf (bool)

• eps (float)

• min_denominator_value (float)

• weight_with_confidence (bool)

get_device()

move_buffers_to_share_mem()

get_buffers()

zero_buffers()

set_metadata_from_particles(particlesDataset)

Parameters:

particlesDataset (ReconstructionParticlesDataset)

backproject_particles(particles_star_fname, particles_dir=None, batch_size=1, num_dataworkers=0, use_only_n_first_batches=None, subset_idxs=None, halfmap_subset=None)

Parameters:

• particles_star_fname (PathLike | str)

• particles_dir (PathLike | str | None)

static get_sincsq(shape, device, eps=0.001)

Separable de-apodization for trilinear gridding: PSF(z,y,x) = sinc^2(z) * sinc^2(y) * sinc^2(x), evaluated on the voxel grid.

torch.sinc(x) = sin(pi*x)/(pi*x). We use centered voxel coordinates normalized by the length in each axis so the arguments live roughly in [-0.5, 0.5]; add a floor to avoid division blow-ups.

static get_soft_mask(shape, device, radius_pix=-1.0, edge_width=3)

Create a soft spherical mask with cosine falloff, matching RELION behavior.

Implements RELION’s softMaskOutsideMap logic: - If radius_pix < 0: automatically set to box_size/2 (RELION default) - Raised cosine falloff with width=edge_width pixels

Parameters:

• shape – (D, H, W) volume shape

• device – torch device

• radius_pix – mask radius in pixels. If negative, defaults to box_size/2 (RELION: -1)

• edge_width – width of cosine falloff edge in pixels (RELION default: 3)

Returns:

(D, H, W) soft mask with values in [0, 1]

Return type:

mask

static compute_radial_average(weights_3d, device)

Compute radial average of weights in 3D rfft Fourier space.

Matches RELION’s approach for frequency-adaptive regularization: - Bins weights by radial distance (frequency shell) - Computes average weight per shell - Returns a 3D array where each voxel contains its shell’s average

This is used for division-by-zero protection without dampening well-sampled regions (unlike constant eps).

Parameters:

• weights_3d – (D, H, W_rfft) weight tensor in rfft format

• device – torch device

Returns:

(D, H, W_rfft) tensor where each voxel = average of its frequency shell

Return type:

radial_avg

generate_volume(fname=None, overwrite_fname=True, device='cpu', apply_soft_mask=True, mask_radius_pix=-1.0, mask_edge_width=3)

Parameters:

• fname (PathLike | str | None)

• overwrite_fname (bool)

• device (str | None)

• apply_soft_mask (bool)

• mask_radius_pix (float)

• mask_edge_width (int)

class cryoPARES.reconstruction.reconstructor.ReconstructionParticlesDataset(particles_star_fname, particles_dir=None, correct_ctf=True, subset_idxs=None, halfmap_subset=None, return_confidence=False)

Bases: Dataset

Parameters:

• particles_star_fname (PathLike | str)

• particles_dir (PathLike | str | None)

• correct_ctf (bool)

• return_confidence (bool)

__init__(particles_star_fname, particles_dir=None, correct_ctf=True, subset_idxs=None, halfmap_subset=None, return_confidence=False)

Parameters:

• particles_star_fname (PathLike | str)

• particles_dir (PathLike | str | None)

• correct_ctf (bool)

• return_confidence (bool)

property sampling_rate

property particle_shape

property particles

cryoPARES.reconstruction.reconstructor.reconstruct_starfile(particles_star_fname, symmetry, output_fname, particles_dir=None, num_dataworkers=1, batch_size=128, use_cuda=True, correct_ctf=<autoCLI_config.config_param.CONFIG_PARAM object>, eps=<autoCLI_config.config_param.CONFIG_PARAM object>, min_denominator_value=None, use_only_n_first_batches=None, float32_matmul_precision=<autoCLI_config.config_param.CONFIG_PARAM object>, weight_with_confidence=<autoCLI_config.config_param.CONFIG_PARAM object>, halfmap_subset=None, apply_soft_mask=<autoCLI_config.config_param.CONFIG_PARAM object>, mask_radius_pix=<autoCLI_config.config_param.CONFIG_PARAM object>, mask_edge_width=<autoCLI_config.config_param.CONFIG_PARAM object>)

Parameters:

• particles_star_fname (str) – The particles to reconstruct

• symmetry (str) – The symmetry of the volume (e.g. C1, D2, …)

• output_fname (str) – The name of the output filename (star)

• particles_dir (Optional[str]) – The particles directory (root of the starfile fnames)

• num_dataworkers (int) – Num workers for data loading

• batch_size (int) – The number of particles to be simultaneously backprojected

• use_cuda (bool) – if NOT, it will not use cuda devices

• correct_ctf (bool) – if NOT, it will not correct CTF

• eps (float) – The regularization constant (ideally, this is 1/SNR)

• min_denominator_value (Optional[float]) – Used to prevent division by 0. By default is 0.1*eps

• use_only_n_first_batches (Optional[int]) – Use only the n first batches to reconstruct

• float32_matmul_precision (Optional[str]) – Set it to high or medium for speed up at a precision cost

• weight_with_confidence (bool) – If True, read and apply per-particle confidence. If False (default), do NOT fetch/pass confidence (zero overhead).

• halfmap_subset (Optional[Literal['1', '2']]) – The random subset of particles to use

• apply_soft_mask (bool) – Apply soft spherical masking after reconstruction to reduce edge artifacts (RELION-style)

• mask_radius_pix (float) – Radius for soft mask in pixels. If negative, defaults to box_size/2 (RELION default: -1)

• mask_edge_width (int) – Width of cosine falloff edge in pixels (RELION default: 3)

Reconstructor Class

class cryoPARES.reconstruction.reconstructor.Reconstructor(symmetry, correct_ctf=<autoCLI_config.config_param.CONFIG_PARAM object>, eps=<autoCLI_config.config_param.CONFIG_PARAM object>, min_denominator_value=<autoCLI_config.config_param.CONFIG_PARAM object>, weight_with_confidence=<autoCLI_config.config_param.CONFIG_PARAM object>, *args, **kwargs)

Bases: Module

Parameters:

• symmetry (str)

• correct_ctf (bool)

• eps (float)

• min_denominator_value (float)

• weight_with_confidence (bool)

__init__(symmetry, correct_ctf=<autoCLI_config.config_param.CONFIG_PARAM object>, eps=<autoCLI_config.config_param.CONFIG_PARAM object>, min_denominator_value=<autoCLI_config.config_param.CONFIG_PARAM object>, weight_with_confidence=<autoCLI_config.config_param.CONFIG_PARAM object>, *args, **kwargs)

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Parameters:

• symmetry (str)

• correct_ctf (bool)

• eps (float)

• min_denominator_value (float)

• weight_with_confidence (bool)

get_device()

move_buffers_to_share_mem()

get_buffers()

zero_buffers()

set_metadata_from_particles(particlesDataset)

Parameters:

particlesDataset (ReconstructionParticlesDataset)

backproject_particles(particles_star_fname, particles_dir=None, batch_size=1, num_dataworkers=0, use_only_n_first_batches=None, subset_idxs=None, halfmap_subset=None)

Parameters:

• particles_star_fname (PathLike | str)

• particles_dir (PathLike | str | None)

static get_sincsq(shape, device, eps=0.001)

Separable de-apodization for trilinear gridding: PSF(z,y,x) = sinc^2(z) * sinc^2(y) * sinc^2(x), evaluated on the voxel grid.

torch.sinc(x) = sin(pi*x)/(pi*x). We use centered voxel coordinates normalized by the length in each axis so the arguments live roughly in [-0.5, 0.5]; add a floor to avoid division blow-ups.

static get_soft_mask(shape, device, radius_pix=-1.0, edge_width=3)

Create a soft spherical mask with cosine falloff, matching RELION behavior.

Implements RELION’s softMaskOutsideMap logic: - If radius_pix < 0: automatically set to box_size/2 (RELION default) - Raised cosine falloff with width=edge_width pixels

Parameters:

• shape – (D, H, W) volume shape

• device – torch device

• radius_pix – mask radius in pixels. If negative, defaults to box_size/2 (RELION: -1)

• edge_width – width of cosine falloff edge in pixels (RELION default: 3)

Returns:

(D, H, W) soft mask with values in [0, 1]

Return type:

mask

static compute_radial_average(weights_3d, device)

Compute radial average of weights in 3D rfft Fourier space.

Matches RELION’s approach for frequency-adaptive regularization: - Bins weights by radial distance (frequency shell) - Computes average weight per shell - Returns a 3D array where each voxel contains its shell’s average

This is used for division-by-zero protection without dampening well-sampled regions (unlike constant eps).

Parameters:

• weights_3d – (D, H, W_rfft) weight tensor in rfft format

• device – torch device

Returns:

(D, H, W_rfft) tensor where each voxel = average of its frequency shell

Return type:

radial_avg

generate_volume(fname=None, overwrite_fname=True, device='cpu', apply_soft_mask=True, mask_radius_pix=-1.0, mask_edge_width=3)

Parameters:

• fname (PathLike | str | None)

• overwrite_fname (bool)

• device (str | None)

• apply_soft_mask (bool)

• mask_radius_pix (float)

• mask_edge_width (int)

Command-Line Interface

cryoPARES.reconstruction.reconstruct.worker(worker_id, *args, **kwargs)

cryoPARES.reconstruction.reconstruct.create_shared_tensor(shape, dtype=torch.float32, ctx=None)

Create a shared memory tensor

cryoPARES.reconstruction.reconstruct.reconstruct_starfile(particles_star_fname, symmetry, output_fname, particles_dir=None, n_jobs=1, num_dataworkers=1, batch_size=128, use_cuda=True, correct_ctf=<autoCLI_config.config_param.CONFIG_PARAM object>, eps=<autoCLI_config.config_param.CONFIG_PARAM object>, min_denominator_value=<autoCLI_config.config_param.CONFIG_PARAM object>, use_only_n_first_batches=None, float32_matmul_precision=<autoCLI_config.config_param.CONFIG_PARAM object>, weight_with_confidence=<autoCLI_config.config_param.CONFIG_PARAM object>, halfmap_subset=None, apply_soft_mask=<autoCLI_config.config_param.CONFIG_PARAM object>, mask_radius_pix=<autoCLI_config.config_param.CONFIG_PARAM object>, mask_edge_width=<autoCLI_config.config_param.CONFIG_PARAM object>)

Reconstruct a 3D volume from particle images with known poses.

Parameters:

• particles_star_fname (str) – Path to input STAR file with particle metadata and poses to reconstruct

• symmetry (str) – Point group symmetry of the volume for reconstruction (e.g., C1, D2, I, O, T)

• output_fname (str) – Path for output reconstructed 3D volume (.mrc file)

• particles_dir (Optional[str]) – Root directory for particle image paths. If provided, overrides paths in the .star file

• n_jobs (int) – Number of parallel worker processes for distributed reconstruction

• num_dataworkers (int) – Number of CPU workers per PyTorch DataLoader for data loading

• batch_size (int) – Number of particles to backproject simultaneously per job

• use_cuda (bool) – Enable GPU acceleration for reconstruction. If False, runs on CPU only

• correct_ctf (bool) – Apply CTF correction during reconstruction

• eps (float) – Regularization mode and strength. Sign selects mode: eps >= 0 uses Tikhonov regularization, eps < 0 uses RELION-style radial averaging. Magnitude sets scale: for Tikhonov, eps is the regularization constant (ideally 1/SNR); for radial averaging, abs(eps) is the divisor for radial weights (RELION uses 1000). Recommended: -1000 for radial averaging, 1e-3 for Tikhonov

• min_denominator_value (float) – Minimum denominator threshold for numerical stability (prevents division by zero). Applied as final safety clamp regardless of regularization mode. RELION uses 1e-6

• use_only_n_first_batches (Optional[int]) – Reconstruct using only first N batches (for testing or quick validation)

• float32_matmul_precision (Optional[str]) – PyTorch float32 matrix multiplication precision mode (“highest”, “high”, or “medium”)

• weight_with_confidence (bool) – Apply per-particle confidence weighting during backprojection. If True, particles with higher confidence contribute more to reconstruction. It reads the confidence from the metadata label “rlnParticleFigureOfMerit”

• halfmap_subset (Optional[Literal['1', '2']]) – Select half-map subset (1 or 2) for half-map reconstruction and validation

• apply_soft_mask (bool) – Apply soft spherical masking after reconstruction to reduce edge artifacts (RELION-style)

• mask_radius_pix (float) – Radius for soft mask in pixels. If negative, defaults to box_size/2

• mask_edge_width (int) – Width of cosine falloff edge in pixels

cryoPARES.reconstruction.reconstruct.main()