src.easycrystallography.Symmetry

Bonding

bond(r, bv, single_bond, sym_op, tol=1e-05)

generates all bonds that are symmetry equivalent to the given bond. The function uses the given space group operators and positions of magnetic atoms to return a list of equivalent bonds in a matrix. The function also checks the validity of the calculation by measuring the length of each equivalent bond using the given bv base and if the difference in length between equivalent bonds is larger than the tolerance throws a warning.

:param r: Positions of the magnetic atoms in lattice units stored in a matrix :type r: np.ndarray :param bv: Basis vectors that define the lattice, used for checking the bond length of equivalent bonds :type bv: np.ndarray :param single_bond: Vector that contains the starting bond with elements of [dl_a dl_b dl_c atom_1 atom_2], where dl is vector of lattice translation between the two atoms if they are not in the same unit cell in lattice units, atom_1 and atom_2 are indices of atoms in the list of positions stored in r. :type single_bond: np.ndarray :param sym_op: List of symmetry operations for the given spacegroup :type sym_op: list :param tol: Tolerance :type tol: float :return: :rtype:

cfloor(r0, tol)

Floor for atomic positions

floor(1-tol) == 1

:param r0: Matrix of positions :type r0: np.ndarray :param tol: Tolerance :type tol: float :return: Matrix r0 where values have been floored :rtype: np.ndarray

cmod(r, tol)

Modulus within tolerance

:param r: Matrix to be operated on :type r: np.ndarray :param tol: Tolerance :type tol: float :return: r with modulus applied :rtype: np.ndarray

generate_bonds(phase_obj, force_no_sym=False, max_distance=8, tol=1e-05, tol_dist=0.001, d_min=0.5, max_sym=None, magnetic_only=False)

generate_bonds generates all bonds up to a certain length between magnetic atoms. It also groups bonds based either on crystal symmetry or bond length (with tol_dist tolerance) is space group is not defined. Sorting bonds based on length can be forced by setting the forceNoSym parameter to true.

:param phase_obj: easyCore phase object for which you want the bonds to be found :type phase_obj: Phase :param force_no_sym: Do not try to work out symmetry equivalent bonds. :type force_no_sym: bool :param max_distance: Maximum distance between atoms for which you want to search for a bond :type max_distance: float :param tol: The tolerance for which we consider unit cells. :type tol: float :param tol_dist: Tolerance of distance, within two bonds are considered equivalent :type tol_dist: float :param d_min: The minimum bond length between atoms :type d_min: float :param max_sym: Return only the 0->max_sym symmetry unique bonds. :type max_sym: int :param magnetic_only: Search for bonds which are between magnetic atoms only. :type magnetic_only: bool :return: Structure containing bond information :rtype: Bonding

isnew(matrix_a, matrix_b, tol)

Selects the new vectors from B within the first unit cell.

Dimensions of A and B have to be [3 nA] and [3 nB] respectively. A vector in B is considered new, if d(mod(vA-vB,1))<tol.

:param matrix_a: First matrix :type matrix_a: np.ndarray :param matrix_b: Second matrix :type matrix_b: np.ndarray :param tol: Tolerance :type tol: float :return: Logical numpy array saying of the vector is new and a numpy array with the index :rtype: Tuple[np.ndarray, np.ndarray]

isnewUC(matrix_a, matrix_b, tol)

Selects the new vectors from B within the first unit cell.

Dimensions of A and B have to be [3 n_a] and [3 n_b] respectively. A vector in B is considered new, if d(mod(vA-vB,1))<tol.

:param matrix_a: First matrix :type matrix_a: np.ndarray :param matrix_b: Second matrix :type matrix_b: np.ndarray :param tol: Tolerance :type tol: float :return: Logical numpy array saying of the vector is new and a numpy array with the index :rtype: Tuple[np.ndarray, np.ndarray]

uniqueB(bond_matrix)

Given an array of bonds, which ones are unique. Bonds has the shape [dl, atom1, atom2]

:param bond_matrix: Array of bonds :type bond_matrix: np.ndarray :return: Logical array for if the corresponding bond is unique :rtype: np.ndarray

SymOp

SymmOp

Bases: ComponentSerializer

A symmetry operation in cartesian space. Consists of a rotation plus a translation. Implementation is as an affine transformation matrix of rank 4 for efficiency. Read: http://en.wikipedia.org/wiki/Affine_transformation. .. attribute:: affine_matrix A 4x4 numpy.array representing the symmetry operation.

inverse property

Returns inverse of transformation.

rotation_matrix: np.ndarray property

A 3x3 numpy.array representing the rotation matrix.

translation_vector property

A rank 1 numpy.array of dim 3 representing the translation vector.

__init__(affine_transformation_matrix, tol=0.01)

Initializes the SymmOp from a 4x4 affine transformation matrix. In general, this constructor should not be used unless you are transferring rotations. Use the static constructors instead to generate a SymmOp from proper rotations and translation. Args: affine_transformation_matrix (4x4 array): Representing an affine transformation. tol (float): Tolerance for determining if matrices are equal.

__mul__(other)

Returns a new SymmOp which is equivalent to apply the "other" SymmOp followed by this one.

apply_rotation_only(vector)

Vectors should only be operated by the rotation matrix and not the translation vector. Args: vector (3x1 array): A vector.

are_symmetrically_related(point_a, point_b, tol=0.001)

Checks if two points are symmetrically related. Args: point_a (3x1 array): First point. point_b (3x1 array): Second point. tol (float): Absolute tolerance for checking distance. Returns: True if self.operate(point_a) == point_b or vice versa.

as_xyz_string()

Returns a string of the form 'x, y, z', '-x, -y, z', '-y+1/2, x+1/2, z+1/2', etc. Only works for integer rotation matrices

from_axis_angle_and_translation(axis, angle, angle_in_radians=False, translation_vec=(0, 0, 0)) staticmethod

Generates a SymmOp for a rotation about a given axis plus translation. Args: axis: The axis of rotation in cartesian space. For example, [1, 0, 0] indicates rotation about x-axis. angle (float): Angle of rotation. angle_in_radians (bool): Set to True if angles are given in radians. Or else, units of degrees are assumed. translation_vec: A translation vector. Defaults to zero. Returns: SymmOp for a rotation about given axis and translation.

from_origin_axis_angle(origin, axis, angle, angle_in_radians=False) staticmethod

Generates a SymmOp for a rotation about a given axis through an origin. Args: origin (3x1 array): The origin which the axis passes through. axis (3x1 array): The axis of rotation in cartesian space. For example, [1, 0, 0]indicates rotation about x-axis. angle (float): Angle of rotation. angle_in_radians (bool): Set to True if angles are given in radians. Or else, units of degrees are assumed. Returns: SymmOp.

from_rotation_and_translation(rotation_matrix=((1, 0, 0), (0, 1, 0), (0, 0, 1)), translation_vec=(0, 0, 0), tol=0.1) staticmethod

Creates a symmetry operation from a rotation matrix and a translation vector. Args: rotation_matrix (3x3 array): Rotation matrix. translation_vec (3x1 array): Translation vector. tol (float): Tolerance to determine if rotation matrix is valid. Returns: SymmOp object

from_xyz_string(xyz_string) staticmethod

Parameters:

Name	Type	Description	Default
xyz_string	str	string of the form 'x, y, z', '-x, -y, z', '-2y+1/2, 3x+1/2, z-y+1/2', etc.	required

Returns: SymmOp

inversion(origin=(0, 0, 0)) staticmethod

Inversion symmetry operation about axis. Args: origin (3x1 array): Origin of the inversion operation. Defaults to [0, 0, 0]. Returns: SymmOp representing an inversion operation about the origin.

operate(point)

Apply the operation on a point. Args: point: Cartesian coordinate. Returns: Coordinates of point after operation.

operate_multi(points)

Apply the operation on a list of points. Args: points: List of Cartesian coordinates Returns: Numpy array of coordinates after operation

reflection(normal, origin=(0, 0, 0)) staticmethod

Returns reflection symmetry operation. Args: normal (3x1 array): Vector of the normal to the plane of reflection. origin (3x1 array): A point in which the mirror plane passes through. Returns: SymmOp for the reflection about the plane

roto_reflection(axis, angle, origin=(0, 0, 0)) staticmethod

Returns a roto-reflection symmetry operation Args: axis (3x1 array): Axis of rotation / mirror normal angle (float): Angle in degrees origin (3x1 array): Point left invariant by roto-reflection. Defaults to (0, 0, 0). Return: Roto-reflection operation

transform_tensor(tensor)

Applies rotation portion to a tensor. Note that tensor has to be in full form, not the Voigt form. Args: tensor (numpy array): a rank n tensor Returns: Transformed tensor.

groups

Defines SymmetryGroup parent class and PointGroup and SpaceGroup classes. Shyue Ping Ong thanks Marc De Graef for his generous sharing of his SpaceGroup data as published in his textbook "Structure of Materials".

PointGroup

Bases: SymmetryGroup

Class representing a Point Group, with generators and symmetry operations.

.. attribute:: symbol

Full International or Hermann-Mauguin Symbol.

.. attribute:: generators

List of generator matrices. Note that 3x3 matrices are used for Point
Groups.

.. attribute:: symmetry_ops

Full set of symmetry operations as matrices.

symmetry_ops property

:return: List of symmetry operations for SpaceGroup

__init__(int_symbol)

Initializes a Point Group from its international symbol.

Parameters:

Name	Type	Description	Default
int_symbol	str	International or Hermann-Mauguin Symbol.	required

get_orbit(p, tol=1e-05)

Returns the orbit for a point.

Parameters:

Name	Type	Description	Default
p		Point as a 3x1 array.	required
tol		Tolerance for determining if sites are the same. 1e-5 should be sufficient for most purposes. Set to 0 for exact matching (and also needed for symbolic orbits).	1e-05

Returns:

Type	Description
	([array]) Orbit for point.

SpaceGroup

Bases: SymmetryGroup

Class representing a SpaceGroup.

.. attribute:: symbol

Full International or Hermann-Mauguin Symbol.

.. attribute:: int_number

International number

.. attribute:: generators

List of generator matrices. Note that 4x4 matrices are used for Space
Groups.

.. attribute:: order

Order of Space Group

crystal_system property

:return: Crystal system for space group.

symmetry_ops property

Full set of symmetry operations as matrices. Lazily initialized as generation sometimes takes a bit of time.

__init__(int_symbol)

Initializes a Space Group from its full or abbreviated international symbol. Only standard settings are supported.

Parameters:

Name	Type	Description	Default
int_symbol	str	Full International (e.g., "P2/m2/m2/m") or Hermann-Mauguin Symbol ("Pmmm") or abbreviated symbol. The notation is a LaTeX-like string, with screw axes being represented by an underscore. For example, "P6_3/mmc". Alternative settings can be access by adding a ":identifier". For example, the hexagonal setting for rhombohedral cells can be accessed by adding a ":H", e.g., "R-3m:H". To find out all possible settings for a spacegroup, use the get_settings classmethod. Alternative origin choices can be indicated by a translation vector, e.g., 'Fm-3m(a-1/4,b-1/4,c-1/4)'.	required

from_int_number(int_number, hexagonal=True) classmethod

Obtains a SpaceGroup from its international number.

Parameters:

Name	Type	Description	Default
int_number	int	International number.	required
hexagonal	bool	For rhombohedral groups, whether to return the hexagonal setting (default) or rhombohedral setting.	True

Returns:

Type	Description
	(SpaceGroup)

get_orbit(p, tol=1e-05)

Returns the orbit for a point.

Parameters:

Name	Type	Description	Default
p		Point as a 3x1 array.	required
tol		Tolerance for determining if sites are the same. 1e-5 should be sufficient for most purposes. Set to 0 for exact matching (and also needed for symbolic orbits).	1e-05

Returns:

Type	Description
	([array]) Orbit for point.

get_settings(int_symbol) classmethod

Returns all the settings for a particular international symbol.

Parameters:

Name	Type	Description	Default
int_symbol	str	Full International (e.g., "P2/m2/m2/m") or Hermann-Mauguin Symbol ("Pmmm") or abbreviated symbol. The notation is a LaTeX-like string, with screw axes being represented by an underscore. For example, "P6_3/mmc".	required

is_compatible(lattice, tol=1e-05, angle_tol=5)

Checks whether a particular lattice is compatible with the conventional unit cell.

Parameters:

Name	Type	Description	Default
lattice	Lattice	A Lattice.	required
tol	float	The tolerance to check for equality of lengths.	1e-05
angle_tol	float	The tolerance to check for equality of angles in degrees.	5

is_subgroup(supergroup)

True if this space group is a subgroup of the supplied group.

Parameters:

Name	Type	Description	Default
group	Spacegroup	Supergroup to test.	required

Returns:

Type	Description
	True if this space group is a subgroup of the supplied group.

is_supergroup(subgroup)

True if this space group is a supergroup of the supplied group.

Parameters:

Name	Type	Description	Default
subgroup	Spacegroup	Subgroup to test.	required

Returns:

Type	Description
	True if this space group is a supergroup of the supplied group.

SymmetryGroup

Bases: Sequence

Abstract class representation a symmetry group.

symmetry_ops abstractmethod property

:return: List of symmetry operations

is_subgroup(supergroup)

True if this group is a subgroup of the supplied group.

Parameters:

Name	Type	Description	Default
supergroup	SymmetryGroup	Supergroup to test.	required

Returns:

Type	Description
	True if this group is a subgroup of the supplied group.

is_supergroup(subgroup)

True if this group is a supergroup of the supplied group.

Parameters:

Name	Type	Description	Default
subgroup	SymmetryGroup	Subgroup to test.	required

Returns:

Type	Description
	True if this group is a supergroup of the supplied group.

in_array_list(array_list, a, tol=1e-05)

Extremely efficient nd-array comparison using numpy's broadcasting. This function checks if a particular array a, is present in a list of arrays. It works for arrays of any size, e.g., even matrix searches.

Parameters:

Name	Type	Description	Default
array_list	[array]	A list of arrays to compare to.	required
a	array	The test array for comparison.	required
tol	float	The tolerance. Defaults to 1e-5. If 0, an exact match is done.	1e-05

Returns:

Type	Description
	(bool)

sg_symbol_from_int_number(int_number, hexagonal=True)

Obtains a SpaceGroup name from its international number.

Parameters:

Name	Type	Description	Default
int_number	int	International number.	required
hexagonal	bool	For rhombohedral groups, whether to return the hexagonal setting (default) or rhombohedral setting.	True

Returns:

Type	Description
	(str) Spacegroup symbol