pyxtal.symmetry module

Module for storing & accessing symmetry group information, including

• Group class

• Wyckoff_Position class.

• Hall class

class pyxtal.symmetry.Group(group, dim=3, use_hall=False, style='pyxtal', quick=False)

Bases: object

Class for storing a set of Wyckoff positions for a symmetry group. See the documentation for details about settings.

Examples

>>> from pyxtal.symmetry import Group
>>> g = Group(64)
>>> g
-- Spacegroup --# 64 (Cmce)--
16g site symm: 1
8f  site symm: m..
8e  site symm: .2.
8d  site symm: 2..
8c  site symm: -1
4b  site symm: 2/m..
4a  site symm: 2/m..

One can access data such as symbol, number and Wyckoff_positions:

>>> g.symbol
'Cmce'
>>> g.number
64
>>> g.Wyckoff_positions[0]
Wyckoff position 16g in space group 64 with site symmetry 1
x, y, z
-x, -y+1/2, z+1/2
-x, y+1/2, -z+1/2
x, -y, -z
-x, -y, -z
x, y+1/2, -z+1/2
x, -y+1/2, z+1/2
-x, y, z
x+1/2, y+1/2, z
-x+1/2, -y+1, z+1/2
-x+1/2, y+1, -z+1/2
x+1/2, -y+1/2, -z
-x+1/2, -y+1/2, -z
x+1/2, y+1, -z+1/2
x+1/2, -y+1, z+1/2
-x+1/2, y+1/2, z

We also provide several utilities functions, e.g., one can search the possible wyckoff_combinations by a formula:

>>> g.list_wyckoff_combinations([4, 2])
([], [], [])
>>> g.list_wyckoff_combinations([4, 8])
([[['4a'], ['8c']],
[['4a'], ['8d']],
[['4a'], ['8e']],
[['4a'], ['8f']],
[['4b'], ['8c']],
[['4b'], ['8d']],
[['4b'], ['8e']],
[['4b'], ['8f']]],
[False, True, True, True, False, True, True, True],
[[[6], [4]], [[6], [3]], [[6], [2]], [[6], [1]],
[[5], [4]], [[5], [3]], [[5], [2]], [[5], [1]]]
)

Or search the subgroup information:

>>> g.get_max_t_subgroup()['subgroup']
[12, 14, 15, 20, 36, 39, 41]

Or check if a given composition is compatible with Wyckoff positions:

>>> g = Group(225)
>>> g.check_compatible([64, 28, 24])
(True, True)

Or check the possible transition paths to a given supergroup:

>>> g = Group(59)
>>> g.search_supergroup_paths(139, 2)
[[71, 139], [129, 139], [137, 139]]

Parameters:

• group – The group symbol or international number

• (int (dim) – 3): The periodic dimension of the group

• default – 3): The periodic dimension of the group

• (bool (quick) – False): Whether or not use the hall number

• default – False): Whether or not use the hall number

• (str (style) – pyxtal): The choice of hall number (pyxtal/spglib)

• default – pyxtal): The choice of hall number (pyxtal/spglib)

• (bool – False): Whether or not ignore the wyckoff information

• default – False): Whether or not ignore the wyckoff information

add_k_transitions(path, n=1)

Adds additional k transitions to a subgroup path. ONLY n = 1 is supported for now. It will return viable additions in front of each group in the path.

Parameters:

• path – a single result of search_subgroup_paths function

• n – number of extra k transitions to add to the given path

Returns:

a list of maximal subgroup chains with extra k type transitions

cellsize()

Returns the number of duplicate atoms in the conventional lattice (in contrast to the primitive cell). Based on the type of cell centering (P, A, C, I, R, or F)

check_compatible(numIons, verbose=False)

Checks if the number of atoms is compatible with the Wyckoff positions. Considers the number of degrees of freedom for each Wyckoff position, and makes sure at least one valid combination of WP’s exists.

Parameters:

• numIons – list of integers

• verbose – bool, whether to print the process

Returns:

True/False has_freedom: True/False

Return type:

Compatible

check_hkl_in_list(hkl, hkl_list)

Check if a given hkl is in the list of hkls considering symmetry.

Parameters:

• hkl (tuple) – The hkl tuple to check

• hkl_list (list) – List of hkl tuples to check against

Returns:

True if hkl is in hkl_list, False otherwise

Return type:

bool

generate_hkl_guesses(h_max=2, k_max=None, l_max=None, max_square=12, total_square=100, max_size=2000000, reduce=True, verbose=False)

Generate reasonable hkl indices within a cutoff for different crystal systems. This function considers the extinction conditions to limit the hkls.

Parameters:

• h_max – maximum absolute value for h

• l_max – maximum absolute value for k

• k_max – maximum absolute value for l

• max_square – maximum h^2 + k^2 + l^2

• max_size – maximum number of guesses to return

• reduce – whether or not reduce the number of guesses

• verbose – whether or not print the possible hkls

generate_possible_hkls(h_max, k_max=None, l_max=None, max_square=12)

Generate reasonable hkl indices within a cutoff for different crystal systems. This function considers the extinction conditions to limit the hkls.

Parameters:

max_h – maximum absolute value for h, k, l

get_ASU()

Get the asymmetric unit for the space group.

Returns:

A list of inequalities defining the asymmetric unit.

Return type:

list

get_ASU_instance()

Get the asymmetric unit (ASU) for the space group. Available methods for ASU construction include: - project_to_asu(coord): Project a given coordinate to the ASU. - is_valid(coord): Check if a given coordinate is within the ASU.

get_alternatives()

Get the alternative settings as a dictionary

get_ferroelectric_groups()

Return the list of possible ferroelectric point groups

get_free_axis()

Get the free axis that can perform continus translation

get_index_by_letter(letter)

Get the wp object by the letter.

get_lattice_dof()

Compute the degree of freedom for the lattice

get_lattice_id()

Compute the id for the lattice.

Returns:

Encoded lattice id

• 0: triclinic-P

• 1: monoclinic-P

• 2: monoclinic-C

• 3: orthorhombic-P

• 4: orthorhombic-A

• 5: orthorhombic-B

• 6: orthorhombic-C

• 7: orthorhombic-I

• 8: orthorhombic-F

• 9: tetragonal-P

• 10: tetragonal-I

• 11: hexagonal-P

• 12: hexagonal-R

• 13: cubic-P

• 14: cubic-I

• 15: cubic-F

Return type:

id (int)

get_max_k_subgroup()

get_max_subgroup(H)

Returns the dicts for both t and k subgroup according the to trail group H

Parameters:

H (int) – 1-230

get_max_subgroup_numbers(max_cell=9)

Returns the minimal supergroups as a dictionary

get_max_t_subgroup()

get_min_supergroup(group_type='t', G=None)

Returns the minimal supergroups as a dictionary

get_orders()

Get possible Wyckoff position orders based on the composition and Z range.

get_reflection_conditions()

Get the reflection conditions for the space group.

Returns:

A dictionary with keys as (h, k, l) tuples and values as booleans indicating if the reflection is allowed.

Return type:

dict

get_site_dof(sites)

Compute the degree of freedom for each site.

Parameters:

sites (list) – List of site labels, e.g. [‘4a’, ‘8b’] or [‘a’, ‘b’]

Returns:

Array of degrees of freedom for each site

Return type:

numpy.ndarray

get_spg_representation()

Get the one-hot encoding of the space group. (lattice_id, symmetry_matrix)

Returns:

an integer between 0 and 13 one_hot: a (15, 26) numpy (0, 1) array

Return type:

id

get_spg_symmetry_object()

Generate the symmetry table for the given space group. It only supports space group now!

get_splitters_from_relation(struc, relation)

Get the valid symmetry relations for a structure to its supergroup e.g.,

Parameters:

• struc (-) – pyxtal structure

• group_type (-) – t or k

Returns:

list of valid transitions

get_splitters_from_structure(struc, group_type='t')

Get the valid symmetry relations for a structure to its supergroup e.g.,

Parameters:

• struc (-) – pyxtal structure

• group_type (-) – t or k

Returns:

list of valid transitions [(id, ([‘4a’], [‘4b’], [[‘4a’], [‘4c’]])]

get_subgroup_composition(ids, g_types=['t', 'k'], max_atoms=100, max_wps=20, verbose=False)

Get the composition of the subgroup Wyckoff positions.

Parameters:

• ids (list, optional) – Nested list of Wyckoff position indices [[0]].

• verbose (bool) – Whether to print debug information.

• g_types (list) – List of subgroup types to consider (‘t’ for translationengleiche, ‘k’ for klassengleiche).

• max_atoms (int) – Maximum number of atoms to consider for subgroup search.

Returns:

List of multiplicities of the Wyckoff positions.

Return type:

list

get_symmetry_directions()

Table 2.1.3.1 from International Tables for Crystallography (2016). Vol. A, Chapter 2.1, pp. 142-174. including Primary, secondary and Tertiary

get_valid_solutions(solutions)

Check if the solutions are valid. A special WP such as (0,0,0) cannot be occupied twice.

Parameters:

solutions – list of solutions about the distibution of WP sites

Returns:

the filtered solutions that are vaild

get_wp_by_letter(letter)

Get the wp object by the letter.

get_wp_list(reverse=False)

Get the reversed list of wps

get_wyckoff_position(index)

Returns a single Wyckoff_position object.

Parameters:

index – the index of the Wyckoff position within the group.

Returns: a Wyckoff_position object

get_wyckoff_position_from_xyz(xyz, decimals=4)

Returns a single Wyckoff_position object.

Parameters:

xyz – a trial [x, y, z] coordinate

Returns: a Wyckoff_position object

is_valid_combination(sites)

Check if the solutions are valid. A special WP with zero freedom (0,0,0) cannot be occupied twice.

Parameters:

sites – list, e.g. [‘4a’, ‘8b’] or [‘a’, ‘b’]

Returns:

True or False

is_valid_hkl(h, k, l)

Check if the given (h, k, l) is allowed by the space group symmetry.

Parameters:

• h (int) – Miller index h

• k (int) – Miller index k

• l (int) – Miller index l

Returns:

True if (h, k, l) is allowed, False otherwise

Return type:

bool

classmethod list_groups(dim=3)

Function for quick print of groups and symbols.

Parameters:

• group – the group symbol or international number

• dim – the periodic dimension of the group

list_wyckoff_combinations(numIons, quick=False, numWp=(None, None), Nmax=10000000)

List all possible wyckoff combinations for the given formula. Note this is really designed for a light weight calculation. If the solution space is big, set quick as True.

Parameters:

• numIons (list) – [12, 8]

• quick (Boolean) – quickly generate some solutions

• numWp (tuple) – (min_wp, max_wp)

• Nmax – maximumly allowed combinations

Returns:

list of possible sites has_freedom: list of boolean numbers indices: list of wp indices

Return type:

Combinations

path_to_general_wp(index=1, max_steps=1)

Find the path to transform the special wp into general site

Parameters:

• index – the index of starting wp

• max_steps – the number of steps to search

Returns:

a list of (g_types, subgroup_id, spg_number, wp_list (optional))

path_to_subgroup(H)

For a given a path, extract the

a list of (g_types, subgroup_id, spg_number, wp_list (optional))

path_to_zp2()

Find a path to split general wp to zp=2.

reduce_hkl_guesses(hkls)

Reduce the hkl guesses by removing duplicates based on canonical forms.

Parameters:

hkls (list) – np.ndarray of hkl guesses tuples

Returns:

Reduced hkls

Return type:

list

search_subgroup_paths(G, max_layer=5)

Search paths to transit to subgroup H. if - path1 is a>>e - path2 is a>>b>>c>>e path 2 will not be counted since path 1 exists

Parameters:

• G – final subgroup number

• max_layer – the number of supergroup calculations needed.

Returns:

list of possible paths ordered from H to G

search_supergroup_paths(H, max_layer=5)

Search paths to transit to super group H. if - path1 is a>>e - path2 is a>>b>>c>>e path 2 will not be counted since path 1 exists

Parameters:

• H – final supergroup number

• max_layer – the number of supergroup calculations needed.

Returns:

list of possible paths ordered from G to H

short_path_to_general_wp(index=1, t_only=False)

u Find a short path to turn the spcical wp to general position

Parameters:

• index – index of the wp

• t_only – only consider t_spliting

class pyxtal.symmetry.Hall(spgnum, style='pyxtal', permutation=False)

Bases: object

Class for conversion between Hall and standard spacegroups http://cci.lbl.gov/sginfo/itvb_2001_table_a1427_hall_symbols.html

Parameters:

• spg_num – interger number between 1 and 230

• style – spglib or pyxtal

• permutation – allow permutation or not

class pyxtal.symmetry.SymmetryData

Bases: object

get_generator_lg()

get_generator_pg()

get_generator_rg()

get_generator_sg()

get_hall_table()

classmethod get_k_subgroup()

get_symmetry_lg()

get_symmetry_pg()

get_symmetry_rg()

get_symmetry_sg()

classmethod get_t_subgroup()

get_wyckoff_lg()

get_wyckoff_pg()

get_wyckoff_rg()

get_wyckoff_sg()

class pyxtal.symmetry.Wyckoff_position

Bases: object

Class for a single Wyckoff position within a symmetry group

Examples

>>> from pyxtal.symmetry import Wyckoff_position as wp
>>> wp.from_group_and_index(19, 0)
Wyckoff position 4a in space group 19 with site symmetry 1
x, y, z
-x+1/2, -y, z+1/2
-x, y+1/2, -z+1/2
x+1/2, -y+1/2, -z

apply_ops(pt)

Apply symmetry operation

are_equivalent_pts(pt1, pt2, cell=None, tol=0.05)

Check if two pts are equivalent

copy()

Simply copy the structure

distance_check(pt, lattice, tol)

Given a list of fractional coordinates, merges them within a given tolerance, and checks if the merged coordinates satisfy a Wyckoff position.

Parameters:

• pt – the originl point (3-vector)

• lattice – a 3x3 matrix representing the unit cell

• tol – the cutoff distance for merging coordinates

Returns:

True or False

equivalent_set(index)

Transform the wp to another equivalent set. Needs to update both wp and positions

Parameters:

transformation – index

classmethod from_dict(dictionary)

Constructs a Wyckoff_position object using a dictionary.

from_discrete_grid(xyz, N_grids=50)

A function to convert from a discrete grid to (x, y, z)

classmethod from_group_and_index(group, index, dim=3, use_hall=False, style='pyxtal', wyckoffs=None)

Creates a Wyckoff_position using the space group number and index

Parameters:

• group – the international number of the symmetry group

• index – the index of the Wyckoff position within the group.

• dim – the periodic dimension of the crystal

• (default (style) – False): whether or not use the hall number

• (default – pyxtal): ‘pyxtal’ or ‘spglib’ for hall number

classmethod from_group_and_letter(group, letter, dim=3, style='pyxtal', hn=None)

Creates a Wyckoff_position using the space group number and index

Parameters:

• group – the international number of the symmetry group

• letter – e.g. 4a

• dim – the periodic dimension of the crystal

• style – ‘pyxtal’ or spglib, differing in the choice of origin

• hn – hall_number

from_index_quick(wyckoffs, index, P=None, P1=None)

A short cut to create the WP object from a given index ignore the site symmetry and generators Mainly used for the update function

Parameters:

• wyckoffs – wyckoff position

• index – index of wp

• P – transformation matrix (rot + trans)

classmethod from_symops(ops, G)

search Wyckoff Position by symmetry operations

Parameters:

• ops – a list of symmetry operations

• G – the Group object

Returns:

Wyckoff_position

classmethod from_symops_wo_group(ops)

search Wyckoff Position by symmetry operations Now only supports space group symmetry Assuming general position only

Parameters:

ops – a list of symmetry operations

Returns:

Wyckoff_position

gen_pos()

Returns the general Wyckoff position

get_all_positions(pos)

return the list of position from any single coordinate from wp. The position does not have to be the 1st number in the wp list

>>> from pyxtal.symmetry import Group
>>> wp2 = Group(62)[-1]
>>> wp2
Wyckoff position 4a in space group 62 with site symmetry -1
0, 0, 0
1/2, 0, 1/2
0, 1/2, 0
1/2, 1/2, 1/2
>>> wp2.get_all_positions([1/2, 1/2, 1/2])
array([[0. , 0. , 0. ],
       [0.5, 0. , 0.5],
       [0. , 0.5, 0. ],
       [0.5, 0.5, 0.5]])

get_dof()

Simply return the degree of freedom

get_euclidean_generator(cell, idx=0)

return the symmetry operation object at the Euclidean space

Parameters:

• cell – 3*3 cell matrix

• idx – the index of wp generator

Returns:

pymatgen SymmOp object

get_euclidean_ops()

return the symmetry operation object at the Euclidean space

Returns:

list of pymatgen SymmOp object

get_euclidean_symmetries(idx=0)

return the symmetry operation object at the Euclidean space

Returns:

list of pymatgen SymmOp object

get_free_xyzs(pos, perturb=False, eps=0.1, random_state: int | None | Generator = None)

return the free xyz paramters from the given xyz position

Parameters:

• pos (array) – a 3-array to describe x, y, z

• perturb (bool) – whether or not apply perturbation

• eps (float) – the magnitude of perturbations

Returns:

free xyz array

get_frozen_axis()

get_hm_number(tol=1e-05)

get_hm_symbol()

Get Hermann-Mauguin symbol

get_label()

get the string like 4a

get_ops_from_transformation()

Get symmetry operation from the generators

get_position_from_free_xyzs(xyz)

generate the full xyz position from the free xyzs

get_site_symm_ops(idx=0)

get_site_symm_wo_translation()

get_site_symmetry(idx=0)

get_site_symmetry_object(idx=0)

has_equivalent_ops(wp2, tol=0.001)

check if two wps are equivalent

Parameters:

wp2 – wp object or list of operations

is_pure_translation(id)

Check if the operation is equivalent to pure translation

is_standard_setting()

Check if the symmetry operation follows the standard setting

classmethod load_dict(dicts)

merge(pt, lattice, tol, orientations=None, group=None)

Given a list of fractional coordinates, merges them within a given tolerance, and checks if the merged coordinates satisfy a Wyckoff position.

Parameters:

• pt – the originl point (3-vector)

• lattice – a 3x3 matrix representing the unit cell

• tol – the cutoff distance for merging coordinates

• orientations – the valid orientations for a given molecule.

Returns:

3-vector after merge wp: a Wyckoff_position object, If no match, returns False. valid_ori: the valid orientations after merge

Return type:

pt

print_ops(ops=None)

process_ops()

handle some annoying cases e.g., in I2, [‘1/2, y, 1/2’, ‘0, y+1/2, 0’] can be transfered to [‘0, y, 0’, ‘1/2, y+1/2, 1/2’]

project(point, cell=None, PBC=None, id=0)

Given a 3-vector and a Wyckoff position operator, returns the projection onto the axis, plane, or point.

>>> wp.project_point([0,0.3,0.1],
array([0. , 0.3, 0.1])

Parameters:

• point – a 3-vector (numeric list, tuple, or array)

• cell – 3x3 matrix describing the unit cell vectors

• PBC – A periodic boundary condition list, where 1 means periodic, 0 means not periodic. Ex: [1,1,1] -> full 3d periodicity, [0,0,1] -> 1d periodicity along the z axis

Returns:

a transformed 3-vector (numpy array)

save_dict()

search_all_generators(pos, ops=None, tol=0.01)

search generator for a special Wyckoff position

Parameters:

• pos – initial xyz position

• ops – list of symops

• tol – tolerance

Returns:

the position that matchs the standard setting

Return type:

pos1

search_generator(pos, ops=None, tol=0.01, symmetrize=False)

search generator for a special Wyckoff position

Parameters:

• pos – initial xyz position

• ops – list of symops

• tol – tolerance

• symmetrize (bool) – apply symmetrization

Returns:

the position that matchs the standard setting

Return type:

pos1

search_generator_dist(pt, lattice=None, group=None)

For a given special wp, (e.g., [(x, 0, 1/4), (0, x, 1/4)]), return the first position and distance

Parameters:

• pt – 1*3 vector

• lattice – 3*3 matrix

Returns:

the best matched pt diff: numerical difference

Return type:

pt

set_euclidean()

For the hexagonal groups, need to consider the euclidean conversion

set_generators()

set up generators, useful for many things

set_ops()

short_distances(pt, lattice, tol)

Given a list of fractional coordinates, merges them within a given tolerance, and checks if the merged coordinates satisfy a Wyckoff position.

Parameters:

• pt – the originl point (3-vector)

• lattice – a 3x3 matrix representing the unit cell

• tol – the cutoff distance for merging coordinates

Returns:

a list of short distances

swap_axis(swap_id)

swap the axis may result in a new wp

to_discrete_grid(xyz, N_grids=50)

A function to convert (x, y, z) to a discrete grid

transform_from_matrices(trans)

Parameters:

trans – a list of transformation matrices

transform_from_matrix(trans=None, reset=True, update=False)

Transform the symmetry operation according to cell transformation. Mostly needed when optimizing the lattice

update()

update the spacegroup information if needed

update_hall(hall_numbers=None)

update the Hall number when the symmetry operation changes

Parameters:

hall_numbers – a list of numbers for consideration

update_index()

Check if needs to update the index due to lattice transformation

pyxtal.symmetry.abc2matrix(abc)

Convert the ABC string representation to an affine matrix.

Parameters:

abc (str) – String representation in formats like: - ‘a, b, c’ - ‘a+c, b, c’ - ‘a+1/4, b+1/4, c’

Returns:

Contains:

• 3x3 rotation matrix

• 3-element translation vector

Return type:

tuple

Examples

>>> abc2matrix('a+1/4, b+1/4, c')
(array([[1., 0., 0.],
        [0., 1., 0.],
        [0., 0., 1.]]), array([0.25, 0.25, 0.  ]))

pyxtal.symmetry.are_equivalent_ops(op1, op2, tol=0.01)

check if two ops are equivalent, assuming the same ordering

pyxtal.symmetry.check_symmetry_and_dim(number, dim=3)

Check if it is a valid number for the given symmetry

Parameters:

• number – int

• dim – 0, 1, 2, 3

pyxtal.symmetry.check_wyckoff_position(points, group, tol=0.001)

Given a list of points, returns a single index of a matching Wyckoff position in the space group. Checks the site symmetry of each supplied point against the site symmetry for each point in the Wyckoff position. Also returns a point which can be used to generate the rest using the Wyckoff position operators.

Parameters:

• points – a list of 3d coordinates or SymmOps to check

• group – a Group object

• tol – the max distance between equivalent points

Returns:

index is a single index for the Wyckoff position within the sg. If no matching WP is found, returns False. point is a coordinate taken from the list points. When plugged into the Wyckoff position, it will generate all the other points.

Return type:

index, p

pyxtal.symmetry.choose_wyckoff(G, number=None, site=None, dim=3, random_state: int | None | Generator = None)

Choose a Wyckoff position based on needed atoms in unit cell.

Parameters:

• G – Group object.

• number – Number of atoms still needed in the unit cell.

• site – Optional pre-assigned Wyckoff sites (e.g., “4a”).

• dim – Dimension of the space group (default 3).

• random_state – Random number generator or seed for reproducibility.

Rules:

1. Uses pre-assigned list if provided

2. New position multiplicity must be <= number of needed atoms

3. Prefers positions with higher multiplicity

Returns:

Selected Wyckoff_position object or False if none found.

pyxtal.symmetry.choose_wyckoff_mol(G: Group, number: int, site: str | None, orientations: list[list[list]], gen_site: bool = True, dim: int = 3, random_state: int | None | Generator = None) → Wyckoff_position | bool

Choose a Wyckoff position to fill based on the current number of molecules needed to be placed within a unit cell.

Rules:

• The new position’s multiplicity is equal/less than (number).

• We prefer positions with large multiplicity.

• The site must admit valid orientations for the desired molecule.

Parameters:

• G – A pyxtal.symmetry.Group object.

• number – The number of molecules still needed in the unit cell.

• site – The specific Wyckoff site to use (if any).

• orientations – The valid orientations for a given molecule.

• gen_site – If True, consider only general Wyckoff positions.

• dim – Dimension of the space group.

• random_state – Seed for random number generation.

Returns:

Wyckoff position if found, False otherwise.

pyxtal.symmetry.find_axis_order(axis, directions)

pyxtal.symmetry.generate_possible_hkls(bravais, h_max=50, k_max=50, l_max=50)

Generate reasonable hkl indices within a cutoff for different crystal systems.

Parameters:

• bravrais – bravais lattice type (1-15)

• h_max – maximum absolute value for h

• k_max – maximum absolute value for k

• l_max – maximum absolute value for l

• level – level of indexing (0 for triclinic; 1 for monoclinic; 2 for orthorhombic or higher)

pyxtal.symmetry.get_all_polar_space_groups()

pyxtal.symmetry.get_bravais_lattice(spg)

1: Triclinic-P 2: Monoclinic-P 3: Monoclinic-C 4: Orthorhombic-P 5: Orthorhombic-A 6: Orthorhombic-C 7: Orthorhombic-I 8: Orthorhombic-F 9: Tetragonal-P 10: Tetragonal-I 11: Hexagonal-P 12: Rhombohedral-R 13: Cubic-P 14: Cubic-I 15: Cubic-F

pyxtal.symmetry.get_canonical_hkl(h, k, l, spg)

Get the canonical form of hkl for each crystal system to remove symmetry equivalents

pyxtal.symmetry.get_canonical_hkl_series(hkl_series, spg)

Get canonical forms for a series of hkls ensuring consistent permutation order. Apply the same permutation to ALL hkls in the series.

Parameters:

• hkl_series – list of (h, k, l) tuples

• spg – space group number

Returns:

canonical_series as a tuple (hashable)

Return type:

tuple

pyxtal.symmetry.get_close_packed_groups(pg)

List the close packed groups based on the molecular symmetry.

Compiled from AIK Book, Table 2 P34.

Parameters:

pg (str) – Point group symbol.

Returns:

List of space group numbers, or None if not found.

Return type:

list or None

pyxtal.symmetry.get_generators(num, dim=3)

Returns a list of Wyckoff generators for a given group.

• 1st index: index of WP in sg (0 is the WP with largest multiplicity)

• 2nd index: a generator for the WP

This function is useful for rotating molecules based on Wyckoff position, since special Wyckoff positions only encode positional information, but not information about the orientation. The generators for each Wyckoff position form a subset of the spacegroup’s general Wyckoff position.

Parameters:

• num – the international spacegroup number

• dim – dimension

Returns:

a 2d list of symmop objects [[wp0], [wp1], … ]

pyxtal.symmetry.get_lattice_type(bravais)

Get the lattice type string from bravais lattice number.

pyxtal.symmetry.get_pbc_and_lattice(number, dim)

pyxtal.symmetry.get_point_group(number)

Parse the point group symmetry info from space group.

According to http://img.chem.ucl.ac.uk/sgp/misc/pointgrp.htm, among 32 point groups and 230 space groups, there are:

• 10 polar point groups (68 space groups):

  1, 2, m, mm2, 3, 3m, 4, 4mm, 6, 6mm

• 11 centrosymmetric point groups (92 space groups):

  -1, 2/m, mmm, 4/m, 4/mmm, -3, -3m, 6/m, 6/mmm, m-3, m-3m

• 11 enantiomorphic point groups (65 space groups):

  1, 2, 222, 4, 422, 3, 32, 6, 622, 23, 432

Parameters:

number (int) – Space group number between 1-230

Returns:

(point_group_symbol, point_group_number, is_polar,

has_inversion, is_enantiomorphic)

Return type:

tuple

pyxtal.symmetry.get_symbol_and_number(input_group, dim=3)

Function for quick conversion between symbols and numbers.

Parameters:

• input_group – the group symbol or international number

• dim – the periodic dimension of the group

pyxtal.symmetry.get_symmetry_directions(lattice_type, symbol='P', unique_axis='b')

Get the symmetry directions

pyxtal.symmetry.get_symmetry_from_ops(ops, tol=1e-05)

get the hall number from symmetry operations.

Parameters:

• ops – tuple of (rotation, translation) or list of strings

• tol – tolerance

pyxtal.symmetry.get_wyckoff_symmetry(num, dim=3)

Returns a list of site symmetry for a given group.

• 1st index: index of WP in sg (0 is the WP with largest multiplicity)

• 2nd index: a point within the WP

• 3rd index: a site symmetry SymmOp of the point

Parameters:

• sg – the international spacegroup number

• dim – 0, 1, 2, 3

Returns:

a 3d list of SymmOp objects representing the site symmetry of each point in each Wyckoff position

pyxtal.symmetry.get_wyckoffs(num, organized=False, dim=3)

Returns a list of Wyckoff positions for a given group. Has option to organize the list based on multiplicity (this is used for random_crystal.wyckoffs)

For an unorganized list:

• 1st index: index of WP in sg (0 is the WP with largest multiplicity)

• 2nd index: a SymmOp object in the WP

For an organized list:

• 1st index: specifies multiplicity (0 is the largest multiplicity)

• 2nd index: a WP within the group of equal multiplicity.

• 3nd index: a SymmOp object within the Wyckoff position

You may switch between organized and unorganized lists using the methods i_from_jk and jk_from_i. For example, if a Wyckoff position is the [i] entry in an unorganized list, it will be the [j][k] entry in an organized list.

Parameters:

• num – the international group number

• dim – dimension [0, 1, 2, 3]

• organized – whether or not to organize the list based on multiplicity

Returns:

a list of Wyckoff positions, each of which is a list of SymmOp’s

pyxtal.symmetry.identity_ops(op)

check if the operation is the identity.

pyxtal.symmetry.index_from_letter(letter, group, dim=3)

Given the Wyckoff letter, returns the index of a Wyckoff position.

Parameters:

• letter – The wyckoff letter

• group – an unorganized Wyckoff position array or Group object (preferred)

• dim – the periodicity dimension of the symmetry group.

Returns:

a single index specifying the location of the Wyckoff position.

pyxtal.symmetry.is_hkl_allowed(h, k, l, spg)

Check if hkl is allowed based on systematic absences for the given space group.

Symmetry Element | Affected Reflection | Condition for Reflection to Be Present ——————————|---------------------|—————————————- Lattice Centering:

primitive lattice (P) | hkl | always present body-centered lattice (I) | hkl | h + k + l = even end-centered lattice (A) | hkl | k + l = even end-centered lattice (B) | hkl | h + l = even end-centered lattice (C) | hkl | h + k = even face-centered lattice (F) | hkl | h, k, l all odd or all even

Screw Axes:

2-fold screw, 21 || a | h00 | h = even 4-fold screw, 42 || a | h00 | h = even 6-fold screw, 63 || c | 00l | l divisible by 3 3-fold screw, 31 or 32 || c | 00l | l divisible by 3 6-fold screw, 62 or 64 || a | h00 | h divisible by 4 4-fold screw, 41 or 43 || a | h00 | h divisible by 4 6-fold screw, 61 or 65 || c | 00l | l divisible by 6

Glide Plane Perpendicular to the B-axis:

a glide | h0l | h = even c glide | h0l | l = even n glide | h0l | h + l = even d glide | h0l | h + l divisible by 4

pyxtal.symmetry.is_hkl_allowed_by_bravais(h, k, l, bravais)

Check if hkl is allowed based on systematic absences for the given space group.

Symmetry Element | Affected Reflection | Condition for Reflection to Be Present ——————————|---------------------|—————————————- Lattice Centering:

primitive lattice (P) | hkl | always present body-centered lattice (I) | hkl | h + k + l = even end-centered lattice (A) | hkl | k + l = even end-centered lattice (B) | hkl | h + l = even end-centered lattice (C) | hkl | h + k = even face-centered lattice (F) | hkl | h, k, l all odd or all even r-centered lattice (R) | hkl | h-k-l % 3

pyxtal.symmetry.jk_from_i(i, olist)

Given an organized list (Wyckoff positions or orientations), determine the two indices which correspond to a single index for an unorganized list.

Used mainly for organized Wyckoff position lists, but can be used for other lists organized in a similar way

Parameters:

• i – a single index corresponding to the item’s location in the unorganized list

• olist – the organized list

Returns:

two indices corresponding to the item’s location in the

organized list

Return type:

[j, k]

pyxtal.symmetry.letter_from_index(index, group, dim=3)

Given a Wyckoff position’s index within a spacegroup, return its number and letter e.g. ‘4a’

Parameters:

• index – WP’s index (0 is the general position)

• group – an unorganized Wyckoff position array or Group object (preferred)

• dim – the periodicity dimension of the symmetry group.

Returns:

the Wyckoff letter corresponding to the Wyckoff position (for example, for position 4a, the function would return ‘a’)

pyxtal.symmetry.op_transform(ops, affine_matrix)

Transform a symmetry operation using affine matrix multiplication.

Example

>>> x, y, z -> x+1/2, y+1/2, z
>>> 0, 1/2, z -> 1/2, 0, z

Parameters:

• ops – A SymmOp object representing the symmetry operation to transform

• affine_matrix – 4x4 affine transformation matrix

Returns:

The transformed symmetry operation

Return type:

SymmOp

pyxtal.symmetry.op_translation(op, tran)

Modify a symmetry operation by adding a translation vector.

Parameters:

• op (SymmOp) – The input symmetry operation to be modified

• tran (array_like) – The translation vector to be added (3D vector)

Returns:

A new symmetry operation with the translation added. Note: If a row in the operation matrix has non-zero rotation/mirror components, the translation component for that row will be set to 0.

Return type:

SymmOp

Examples

>>> op = SymmOp([[1,0,0,0], [0,1,0,0.5], [0,0,1,0.5], [0,0,0,1]])
>>> tran = [0, 0.5, 0]
>>> new_op = op_translation(op, tran)

pyxtal.symmetry.organized_wyckoffs(group)

Takes a Group object or unorganized list of Wyckoff positions and returns a 2D list of Wyckoff positions organized by multiplicity.

Parameters:

group – a pyxtal.symmetry.Group object

Returns:

a 2D list of Wyckoff_position objects if group is a Group object. a 3D list of SymmOp objects if group is a 2D list of SymmOps

pyxtal.symmetry.para2ferro(pg)

88 potential paraelectric-to-ferroelectric phase transitions https://journals.aps.org/prb/abstract/10.1103/PhysRevB.2.754 https://pubs.rsc.org/en/content/articlelanding/2016/cs/c5cs00308c

Parameters:

group (paraelectric point)

Returns:

list of ferroelectric point groups

pyxtal.symmetry.rf(package_name, resource_path)

pyxtal.symmetry.search_cloest_wp(G, wp, op, pos)

For a given position, search for the cloest wp which satisfies the desired symmetry relation, e.g., for pos (0.1, 0.12, 0.2) and op (x, x, z) the closest match is (0.11, 0.11, 0.2)

Parameters:

• G – space group number

• wp – Wyckoff object

• op – symmetry operation belonging to wp

• pos – initial xyz position

Returns:

the position that matchs symmetry operation

Return type:

pos1

pyxtal.symmetry.site_symm(point, gen_pos, tol=0.001, lattice=None, PBC=None)

Given a point and a general Wyckoff position, return the list of symmetry operations leaving the point (coordinate or SymmOp) invariant. The returned SymmOps are a subset of the general position. The site symmetry can be used for determining the Wyckoff position for a set of points, or for determining the valid orientations of a molecule within a given Wyckoff position.

Parameters:

• point – a 1x3 coordinate or SymmOp object to find the symmetry of. If a SymmOp is given, the returned symmetries must also preserve the point’s orientaion

• gen_pos – the general position of the spacegroup. Can be a Wyckoff_position object or list of SymmOp objects.

• tol – the numberical tolerance for determining equivalent positions and orientations.

• lattice – a 3x3 matrix representing the lattice vectors of the unit cell

• PBC – A periodic boundary condition list, 1 means periodic, 0 means not periodic. Ex: [1,1,1] -> full 3d periodicity, [0,0,1] -> periodicity along the z axis. Need not be defined here if gen_pos is a Wyckoff_position object.

Returns:

a list of SymmOp objects which leave the given point invariant

class pyxtal.symmetry.site_symmetry(ops, lattice_type, Bravis, number, wp_id=0, parse_trans=False)

Bases: object

Derive the site symmetry group from symmetry operations site-symmetry group is indicated by an oriented symbol, which is a variation of the Hermann-Mauguin point-group symbol that provides information about the orientation of the symmetry elements. The constituents of the oriented symbol are ordered according to the symmetry directions of the corresponding crystal lattice (primary, secondary and tertiary)

Parameters:

• ops – a list of SymmOp objects representing the site symmetry

• lattice_type (str) – e.g., ‘cubic’

• Bravis (str) – ‘P’, ‘R’, ‘A’, ‘B’, ‘C’, ‘F’, ‘I’

• number (int) – space group number

• parse_trans (bool) – do space group or site

Returns:

a string representing the site symmetry (e.g., 2mm)

correct_matrix(matrix)

get_highest_symmetry(row)

get_name()

ref_symmetry(symbols, reference)

set_full_hm_symbols(tables)

Set the full hm symbols for each axis

Parameters:

tables – sorted table with (list of symmetry elements, symbols, order)

Returns:

a list of symmetry elements on {primary, secondary, tertiery} directions

set_short_symbols()

Set short symbols from the Full symbols

set_table(skip=False)

Get the complete table representation.

Parameters:

skip (bool) – whether or not skip 1 or -1 symmetry

Returns:

sorted table with (list of symmetry elements, symbols, order)

to_beautiful_matrix_representation(skip=True)

A shortcut to check the representation

Parameters:

skip (bool) – whether or not skip 1 or -1 symmetry

to_matrix_representation(verbose=False)

To create a binary matrix to represent the symmetry elements on each axis Translation is also counted here.

to_one_hot(verbose=False)

unique_symmetry(symbols, symmetry)

pyxtal.symmetry.swap_xyz_ops(ops, permutation)

Change the symmetry operation by swaping the axes.

Parameters:

• ops – SymmOp object

• permutation – list, e.g. [0, 1, 2]

Returns:

the new xyz string after transformation

pyxtal.symmetry.swap_xyz_string(xyzs, permutation)

Permutate the xyz string operation.

Parameters:

• xyzs – e.g. [‘x’, ‘y+1/2’, ‘-z’]

• permuation – list, e.g., [0, 2, 1]

Returns:

The new xyz string after transformation.

pyxtal.symmetry.symmetry_element_from_axis(axis)

Given an axis, returns a SymmOp representing a symmetry element on the axis. For example, the symmetry element for the vector (0,0,2) would be (0,0,z).

Parameters:

axis – a 3-vector representing the symmetry element

Returns:

a SymmOp object of form (ax, bx, cx), (ay, by, cy), or (az, bz, cz)

pyxtal.symmetry.transform_ops(ops, P, P1)

Transformation according to the P and P1 operations.

Parameters:

• ops – list of symmtry ops

• P – transformation

• P1 – inverse transformation

pyxtal.symmetry.trim_ops(ops)

Convert the operation to the simplest form. For example:

• x+1/8, y+1/8, z+1/8 -> x, y, z

• 1/8, y+1/8, -y+1/8 -> 1/8, y, -y+1/4

Parameters:

ops (list) – List of symmetry operations

Returns:

List of simplified symmetry operations

Return type:

list