Quaternion Module

The quaternion module handles orientation sampling for SO(3).

Generating Orientations

For 3D reconstruction, generate uniformly distributed quaternions:

from dragonfly.quaternion import Quaternion

quat = Quaternion(num_div=10)

For 2D reconstruction, generate in-plane rotations:

quat = Quaternion(num_rot=360, point_group='1')  # 360 angles, no symmetry, default
quat = Quaternion(num_rot=180, point_group='2')  # 180 angles, Friedel symmetry

The sampling in both cases above is 1 degree. The former should be used when the 2D class averages are expected to not be centrosymmetric due to Ewald sphere curvature.

Point Groups

'1' - No symmetry
'2' - Friedel symmetry (2-fold), for 2D
'A5' - Icosahedral symmetry
'S4' - Octahedral symmetry

Configuration

Quaternions can also be generated from a configuration file:

quat = Quaternion()
quat.from_config('config.ini', section_name='emc')

Module to generate and manipulate uniformly sampled 3D quaternions

class dragonfly.quaternion.Quaternion(int num_div=0, int num_rot=0, point_group='')

Bases: object

Class for generating and manipulating orientations for SO(3).

Supports 3D quaternion generation with various point group symmetries, as well as 2D in-plane rotation generation.

Parameters:

num_div (int) – Number of divisions for 3D sampling. Default 0.
num_rot (int) – Number of rotations for 2D sampling. Default 0.
point_group (str) – Point group symmetry (‘1’, ‘2’, ‘S4’, ‘A5’). Default ‘’.

Example

>>> quat = Quaternion()
>>> quat.generate_3d(10)
>>> quat = Quaternion(num_rot=36, point_group='1')

divide(self, rank, num_proc, num_modes=1, num_nonrot_modes=0)

Divide rotations among MPI processes.

Parameters:

rank (int) – MPI rank.
num_proc (int) – Total number of MPI processes.
num_modes (int) – Number of modes. Default 1.
num_nonrot_modes (int) – Non-rotating modes. Default 0.

Returns:

Number of rotations for this process.

Return type:

int

free(self): Free allocated quaternion memory.

from_config(self, config_fname, section_name='emc')

Load orientations from configuration file.

Parameters:

config_fname (str) – Path to configuration file.
section_name (str) – Section name. Default ‘emc’.

generate_2d(self, int num_rot, point_group)

Generate quaternions for in-plane rotations.

Parameters:

num_rot (int) – Number of rotational samples.
point_group (str) – N-fold rotational symmetry (‘1’, ‘2’, etc.).

generate_3d(self, int num_div)

Generate quaternions for SO(3) with uniform sampling.

Parameters:: num_div (int) – Number of rotational subdivisions.

icosahedral_flag: Whether using icosahedral symmetry.

num_div: Number of rotational subdivisions.

num_rot: Total number of rotations.

num_rot_p: Number of rotations for current MPI process.

octahedral_flag: Whether using octahedral symmetry.

parse(self, fname)

Load quaternions from HDF5 file.

Parameters:: fname (str) – Input file path.

quats: Quaternion array, shape (num_rot, 5).

reduce_icosahedral(self, return_sym=False)

Reduce to icosahedral point group subset.

Parameters:: return_sym (bool) – Return symmetry elements. Default False.
Returns:: Number of rotations or symmetry quaternions.
Return type:: int or numpy.ndarray

reduce_octahedral(self, return_sym=False)

Reduce to octahedral point group subset.

Parameters:: return_sym (bool) – Return symmetry elements. Default False.
Returns:: Number of rotations or symmetry quaternions.
Return type:: int or numpy.ndarray

reduced: Whether quaternions have been reduced to point group.

save(self, fname)

Save quaternions to HDF5 file.

Parameters:: fname (str) – Output file path.

voronoi_subset(self, int coarse_num_div)

Select subset using Voronoi cells.

Parameters:: coarse_num_div (int) – Coarse division level.
Returns:: Nearest coarse division indices.
Return type:: numpy.ndarray