Config Models

Bases: BaseComputationalConfig

Serialization of computational resources allocated for 2DTM.

NOTE: The field gpu_ids is not validated at instantiation past being one of the valid types. For example, if "cuda:0" is specified but no CUDA device is available, the instantiation will succeed, and only upon translating gpu_ids to a list of torch.device objects will an error be raised. This is done to allow for configuration files to be loaded without requiring the actual hardware to be present at the time of loading.

Attributes:

• gpu_ids (Optional[Union[int, list[int], str, list[str]]]) –

  Field which specifies which GPUs to use for computation. The following types of values are allowed: - A single integer, e.g. 0, which means to use GPU with ID 0. - A list of integers, e.g. [0, 2], which means to use GPUs with IDs 0 and 2. - A device specifier string, e.g. "cuda:0", which means to use GPU with ID 0. - A list of device specifier strings, e.g. ["cuda:0", "cuda:1"], which means to use GPUs with IDs 0 and 1. - The specific string "all" which means to use all available GPUs identified by torch.cuda.device_count(). - The specific string "cpu" which means to use CPU.

• num_cpus (int) –

  Total number of CPUs to use, defaults to 1.

• backend ((Literal['streamed', 'batched', 'zipfft'], optional)) –

  The cross-correlation backend to use for match template. Must be one of "streamed", "batched", or "zipfft". When "streamed", individual 2D cross-correlations are computed across multiple streams using PyTorch while with "batched", all the 2D cross-correlations are computed in a single batched call also with PyTorch. When "zipfft", the zipFFT library is used to compute the cross-correlations. Defaults to "streamed".

Bases: BaseComputationalConfig

Serialization of computational resources allocated for 2DTM.

NOTE: The field gpu_ids is not validated at instantiation past being one of the valid types. For example, if "cuda:0" is specified but no CUDA device is available, the instantiation will succeed, and only upon translating gpu_ids to a list of torch.device objects will an error be raised. This is done to allow for configuration files to be loaded without requiring the actual hardware to be present at the time of loading.

Attributes:

• gpu_ids (Optional[Union[int, list[int], str, list[str]]]) –

  Field which specifies which GPUs to use for computation. The following types of values are allowed: - A single integer, e.g. 0, which means to use GPU with ID 0. - A list of integers, e.g. [0, 2], which means to use GPUs with IDs 0 and 2. - A device specifier string, e.g. "cuda:0", which means to use GPU with ID 0. - A list of device specifier strings, e.g. ["cuda:0", "cuda:1"], which means to use GPUs with IDs 0 and 1. - The specific string "all" which means to use all available GPUs identified by torch.cuda.device_count(). - The specific string "cpu" which means to use CPU.

• num_cpus (int) –

  Total number of CPUs to use, defaults to 1.

• backend (Optional[str]) –

  The backend to use for match template. Must be "streamed" or "batched". Defaults to "streamed".

Bases: BaseModel2DTM

Class holding frequency and amplitude values for arbitrary curve filter.

Attributes:

• frequencies (list[float]) –

  List of spatial frequencies (in terms of Nyquist) for the corresponding amplitudes.

• amplitudes (list[float]) –

  List of amplitudes for the corresponding spatial frequencies.

calculate_arbitrary_curve_filter(output_shape: tuple[int, ...]) -> torch.Tensor

Bases: BaseModel2DTM

Configuration for the bandpass filter.

Attributes:

• enabled (bool) –

  If True, apply a bandpass filter to correlation during template matching. Default is False.

• low_freq_cutoff (Optional[float]) –

  Low pass filter cutoff frequency. Default is None, which is no low pass filter.

• high_freq_cutoff (Optional[float]) –

  High pass filter cutoff frequency. Default is None, which is no high pass filter.

• falloff (Optional[float]) –

  Falloff factor for bandpass filter. Default is 0.0, which is no falloff.

Methods:

• from_spatial_resolution –

  Helper method to instantiate a bandpass filter from spatial resolutions and a pixel size.

• calculate_bandpass_filter –

  Helper function for bandpass filter based on the desired output shape. This method returns a filter for a RFFT'd and unshifted (zero-frequency component at the top-left corner) image.

from_spatial_resolution(low_resolution: float, high_resolution: float, pixel_size: float, **kwargs: dict[str, Any]) -> BandpassFilterConfig

calculate_bandpass_filter(output_shape: tuple[int, ...]) -> torch.Tensor

Bases: BaseModel2DTM

Configuration for phase randomization filter.

NOTE: Something is not working with the underlying torch_fourier_filter code for phase randomization.

Attributes:

• enabled (bool) –

  If True, apply a phase randomization filter to the input image. Default is False.

• cuton (float) –

  Spatial resolution, in terms of Nyquist, above which to randomize the phase.

Methods:

• calculate_phase_randomization_filter –

  Helper function for the phase randomization filter based on the input reference image and held configuration parameters.

calculate_phase_randomization_filter(ref_img_rfft: Tensor) -> torch.Tensor

Bases: BaseModel2DTM

Configuration class for all preprocessing filters.

Attributes:

• whitening_filter_config (WhiteningFilterConfig) –

  Configuration for the whitening filter.

• bandpass_filter_config (BandpassFilterConfig) –

  Configuration for the bandpass filter.

• phase_randomization_filter_config (PhaseRandomizationFilterConfig) –

  Configuration for the phase randomization filter.

• arbitrary_curve_filter_config (ArbitraryCurveFilterConfig) –

  Configuration for the arbitrary curve filter.

Methods:

• combined_filter –

  Calculate and combine all Fourier filters into a single filter.

get_combined_filter(ref_img_rfft: Tensor, output_shape: tuple[int, ...], apply_random_dropout: bool = False) -> torch.Tensor

Bases: BaseModel2DTM

Configuration for the whitening filter.

Attributes:

• enabled (bool) –

  If True, apply a whitening filter to the input image and template projections. Default is True.

• num_freq_bins (Optional[int]) –

  Number of frequency bins (in 1D) to use when calculating the power spectrum. Default is None which automatically determines the number of bins based on the input image size.

• max_freq (Optional[float]) –

  Maximum frequency, in terms of Nyquist frequency, to use when calculating the whitening filter. Default is 0.5 with values pixels above 0.5 being set to 1.0 in the filter (i.e. no frequency scaling).

• do_power_spectrum (Optional[bool]) –

  If True, calculate the power spectral density from the power of the input image. Default is True. If False, then the power spectral density is calculated from the amplitude of the input image.

Methods:

• calculate_whitening_filter –

  Helper function for the whitening filter based on the input reference image and held configuration parameters.

calculate_whitening_filter(ref_img_rfft: Tensor, output_shape: tuple[int, ...] | None = None, output_rfft: bool = True, output_fftshift: bool = False) -> torch.Tensor

Bases: BaseModel2DTM

Serialization and validation of defocus search parameters for 2DTM.

Attributes:

• enabled (bool) –

  Whether to enable defocus search. Default is True.

• defocus_min (float) –

  Minimum searched defocus relative to average defocus ('defocus_u' and 'defocus_v' in OpticsGroup) of micrograph in units of Angstroms.

• defocus_max (float) –

  Maximum searched defocus relative to average defocus ('defocus_u' and 'defocus_v' in OpticsGroup) of micrograph in units of Angstroms.

• defocus_step (float) –

  Step size for defocus search in units of Angstroms.

• skip_enforce_zero (bool) –

  Whether to skip enforcing a zero value, by default False.

defocus_values: Tensor

Bases: BaseModel2DTM

Serialization and validation of movie parameters for 2DTM.

Attributes:

• enabled (bool) –

  Whether to enable movie configuration.

• movie_path (str) –

  Path to the movie file.

• deformation_field_path (str) –

  Path to the deformation field file.

• particle_shifts_path (str) –

  Path to the particle shifts CSV file. If provided, takes precedence over deformation_field_path. The CSV should have columns: particle_index, frame, y_shift, x_shift.

• pre_exposure (float) –

  Pre-exposure time in seconds.

• fluence_per_frame (float) –

  Dose per frame in electrons per pixel.

movie: Tensor | None

deformation_field: Tensor | None

Bases: BaseModel2DTM

Serialization and validation of constrained orientation parameters.

Attributes:

• enabled (bool) –

  Whether to enable constrained orientation search.

• phi_step (float) –

  Angular step size for phi in degrees. Must be greater than or equal to 0.

• theta_step (float) –

  Angular step size for theta in degrees. Must be greater than or equal to 0.

• psi_step (float) –

  Angular step size for psi in degrees. Must be greater than or equal to 0.

• rotation_axis_euler_angles (list[float]) –

  List of Euler angles (phi, theta, psi) for the rotation axis.

• phi_min (float) –

  Minimum value for the phi angle in degrees.

• phi_max (float) –

  Maximum value for the phi angle in degrees.

• theta_min (float) –

  Minimum value for the theta angle in degrees.

• theta_max (float) –

  Maximum value for the theta angle in degrees.

• psi_min (float) –

  Minimum value for the psi angle in degrees.

• psi_max (float) –

  Maximum value for the psi angle in degrees.

euler_angles_offsets: tuple[Tensor, Tensor]

Bases: BaseModel2DTM

Configuration for multiple orientation search ranges.

This class allows specifying multiple complete orientation search configurations and concatenates their Euler angles.

Attributes:

• orientation_configs (list[OrientationSearchConfig]) –

  List of orientation search configurations to combine.

euler_angles: Tensor

Bases: BaseModel2DTM

Serialization and validation of orientation search parameters for 2DTM.

The angles -- phi, theta, and psi -- represent Euler angles in the 'ZYZ' convention in units of degrees between 0 and 360 (for phi and psi) or between 0 and 180 (for theta).

This model effectively acts as a connector into the torch_so3.uniform_so3_sampling.get_uniform_euler_angles function from the torch-so3 package.

TODO: Implement indexing to get the i-th or range of orientations in the search space (need to be ordered).

Attributes:

• psi_step (float) –

  Angular step size for psi in degrees. Must be greater than 0.

• theta_step (float) –

  Angular step size for theta in degrees. Must be greater than 0.

• phi_min (float) –

  Minimum value for the phi angle in degrees.

• phi_max (float) –

  Maximum value for the phi angle in degrees.

• theta_min (float) –

  Minimum value for the theta angle in degrees.

• theta_max (float) –

  Maximum value for the theta angle in degrees.

• psi_min (float) –

  Minimum value for the psi angle in degrees.

• psi_max (float) –

  Maximum value for the psi angle in degrees.

• base_grid_method (str) –

  Method for sampling orientations. Default is 'uniform'. Currently only 'uniform' is supported.

• symmetry (str) –

  Symmetry group of the template. Default is 'C1'. Note that if symmetry is provided, then the angle min/max values must be all set to None (validation will set these automatically based on the symmetry group).

euler_angles: Tensor

validate_angle_ranges_and_symmetry() -> Self

Bases: BaseModel2DTM

Serialization and validation of orientation refinement parameters.

Angles will be sampled from [-coarse_step, coarse_step] in increments of 'fine_step' for the orientation refinement search.

Attributes:

• orientation_sampling_method (str) –

  Method for sampling orientations. Default is 'Hopf Fibration'. Currently only 'Hopf Fibration' is supported.

• template_symmetry (str) –

  Symmetry group of the template. Default is 'C1'. Currently only 'C1' is supported.

• phi_step_coarse (float) –

  Angular step size for phi in degrees for previous, coarse search. This corresponds to the 'OrientationSearchConfig.phi_step' value for the match template program. Must be greater than or equal to 0.

• phi_step_fine (float) –

  Angular step size for phi in degrees for current, fine search. Must be greater than or equal to 0.

• theta_step_coarse (float) –

  Angular step size for theta in degrees for previous, coarse search. This corresponds to the 'OrientationSearchConfig.theta_step' value for the match template program. Must be greater than or equal to 0.

• theta_step_fine (float) –

  Angular step size for theta in degrees for current, fine search. Must be greater than or equal to 0.

• psi_step_coarse (float) –

  Angular step size for psi in degrees for previous, coarse search. This corresponds to the 'OrientationSearchConfig.psi_step' value for the match template program. Must be greater than or equal to 0.

• psi_step_fine (float) –

  Angular step size for psi in degrees for current, fine search. Must be greater than or equal to 0.

euler_angles_offsets: Tensor

Bases: BaseModel2DTM

Serialization and validation of pixel size search parameters for 2DTM.

Attributes:

• enabled (bool) –

  Whether to enable pixel size search. Default is False.

• pixel_size_min (float) –

  Minimum searched pixel size in units of Angstroms.

• pixel_size_max (float) –

  Maximum searched pixel size in units of Angstroms.

• pixel_size_step (float) –

  Step size for pixel size search in units of Angstroms.

• skip_enforce_zero (bool) –

  Whether to skip enforcing a zero value, by default False.

pixel_size_values: Tensor