pythmpg.mpg_tools

Provide externally callable functions for querying magnetic point group properties corresponding to given Jahn symbols.

The two public functions are:

get_mpg_info

Return symmetry and classification information for each MPG.

get_num_indep

Return the number of independent tensor components for each combination of Jahn symbol and MPG.

Both functions are currently called from spreadsheet.py but are designed to be used flexibly for other purposes. This module also contains a number of internally called helper functions, with dependencies on modules mpg_dicts and pg_elements.

pythmpg.mpg_tools.get_mpg_info(mpg_list='All')

Return and basic information for a list of MPGs.

For each MPG, determines the group order and classification as ‘Grey’, ‘Black-White’, or ‘Colorless’, and reports the presence or absence of six key symmetries (P, T, PT, PR, TR, PTR).

Parameters:

mpg_list (list of str or 'All', optional) – MPG names to process. Pass 'All' (default) to process all 122 MPGs in mpg_dict.

Returns:

mpg_info_dict – Dictionary with the following keys, each mapping to a list whose entries correspond to the MPGs in mpg_list:

'bns'list of str

BNS serial number of each MPG.

'order'list of int

Number of elements (order) of each MPG.

'group_type'list of str

Classification as 'Grey', 'Black-White', or 'Colorless'.

'symm_info'list of list of bool

For each MPG, a 6-element list of booleans indicating presence of P, T, PT, PR, TR, and PTR symmetries.

Return type:

dict

pythmpg.mpg_tools.get_num_indep(jahn_list, mpg_list='All')

Return the number of independent tensor components for Jahn symbol / MPG pairs.

For each Jahn symbol, parses the symbol to obtain index-symmetrization instructions, constructs a basis of symmetrized orthonormal tensors, and then further reduces that basis under each MPG’s symmetry operations to count the remaining independent components.

Parameters:

• jahn_list (list of str) – Jahn symbols to process (may include leading 'a' or 'e' parity characters).

• mpg_list (list of str or 'All', optional) – MPG names to process. Pass 'All' (default) to process all 122 MPGs in mpg_dict.

Returns:

num_indep_dict – Maps each Jahn symbol (str) to a list of integers (one per MPG in mpg_list) giving the number of independent tensor components for that symbol and MPG combination.

Return type:

dict

pythmpg.mpg_tools.init_orth_list(rank)

Generate the primitive orthonormal basis of rank-rank tensors.

Creates one tensor for each possible index combination, with a single element equal to 1 and all others 0.

Parameters:

rank (int) – Rank of the tensors to generate.

Returns:

orth_list – List of 3**rank tensors, each of shape (3,) * rank.

Return type:

list of numpy.ndarray

pythmpg.mpg_tools.is_zero(t)

Test whether a numpy tensor has (approximately) zero Frobenius norm.

Parameters:

t (numpy.ndarray) – Input tensor.

Returns:

result – True if the Frobenius norm of t is less than 1e-8.

Return type:

bool

pythmpg.mpg_tools.norm(t)

Return the Frobenius norm of a numpy tensor.

Parameters:

t (numpy.ndarray) – Input tensor.

Returns:

result – Square root of the Frobenius inner product of t with itself.

Return type:

float

pythmpg.mpg_tools.permutation_sign(p)

Return the sign of a permutation.

Parameters:

p (sequence of int) – A permutation of integers.

Returns:

sign – +1 if the permutation is even, -1 if odd.

Return type:

int

pythmpg.mpg_tools.process_block(block, tensor)

Recursively apply Jahn-symbol symmetrization instructions to a tensor.

Uses the nested instruction block structure produced by parse_jahn_symbol to carry out symmetrization over tensor indices to arbitrary depth.

Parameters:

• block (tuple) – Parsed instruction block tuple of the form (code, obj_list) as returned by parse_jahn_symbol(). code is one of 'nosymm', 'symm', or 'asymm'; obj_list is a list of integer axis indices or nested sub-block tuples.

• tensor (numpy.ndarray) – Tensor to symmetrize.

Returns:

• axis_list (list of int) – Axes (consecutive integers) belonging to this block, for which symmetrization has been completed.

• tensor (numpy.ndarray) – Partially symmetrized tensor when called during inner recursion; fully symmetrized when called initially from get_num_indep().

pythmpg.mpg_tools.product(op1, op2)

Return the product of two MPG symmetry elements.

Each element is a 3-tuple (rot, p_space, p_time) where rot is the proper rotation name (str) and p_space, p_time are 0 or 1. The rotation part is looked up in the module-level table_dict; parities combine modulo 2.

Parameters:

• op1 (tuple) – First MPG operation as (rot, p_space, p_time).

• op2 (tuple) – Second MPG operation as (rot, p_space, p_time).

Returns:

result – Product MPG operation as (rot, p_space, p_time).

Return type:

tuple

pythmpg.mpg_tools.reduce_orth_list(orth_list_orig, R, order, parity)

Reduce an orthonormal tensor list by applying one MPG generator.

Symmetrize every tensor in the list under the full cycle of operations generated by R, then re-orthonormalize to obtain the independent tensors that are invariant under this generator.

Parameters:

• orth_list_orig (list of numpy.ndarray) – Orthonormal tensors surviving all previously applied generators.

• R (numpy.ndarray, shape (3, 3)) – Rotation matrix for the generator of a cyclic subgroup.

• order (int) – Order of the generator (R ** order == identity).

• parity (int) – Combined space/time parity for this generator (0 or 1); each application of R is multiplied by (-1)**parity.

Returns:

orth_list – Reduced, re-orthonormalized list of independent tensors.

Return type:

list of numpy.ndarray

pythmpg.mpg_tools.symmetrize_index_blocks(T, blocks, antisym=False)

Symmetrize or antisymmetrize a tensor over permutations of blocks of indices.

Averages over all permutations of the supplied index blocks, optionally weighted by the permutation sign for antisymmetrization. All blocks must contain the same number of indices.

Parameters:

• T (numpy.ndarray) – Tensor to be symmetrized.

• blocks (list of list of int) – Each inner list gives the axes belonging to one block. All inner lists must have the same length.

• antisym (bool, optional) – If True, antisymmetrize. Default is False.

Returns:

result – (Anti)-symmetrized tensor with the same shape as T.

Return type:

numpy.ndarray

pythmpg.mpg_tools.symmetrize_indices(T, indices, antisym=False)

Symmetrize or antisymmetrize a tensor over a list of indices.

Averages over all permutations of the specified axes, optionally weighted by the permutation sign for antisymmetrization.

Parameters:

• T (numpy.ndarray) – Tensor to be symmetrized.

• indices (list of int) – Axes over which to symmetrize.

• antisym (bool, optional) – If True, antisymmetrize (weight each permutation by its sign). Default is False.

Returns:

result – (Anti)-symmetrized tensor with the same shape as T.

Return type:

numpy.ndarray

pythmpg.mpg_tools.t_prod(t1, t2)

Return the Frobenius inner product of two numpy tensors.

Parameters:

• t1 (numpy.ndarray) – Tensors of identical shape.

• t2 (numpy.ndarray) – Tensors of identical shape.

Returns:

result – Sum of element-wise products of t1 and t2.

Return type:

float

pythmpg.mpg_tools.transform_tensors(tensor_array, R, parity)

Apply a rotation matrix to every axis of a collection of tensors.

Contracts R along each axis of tensor_array except the last (which indexes the collection), optionally multiplying by a parity sign.

Parameters:

• tensor_array (numpy.ndarray) – Stacked tensor collection; the last axis indexes individual tensors in the collection.

• R (numpy.ndarray, shape (3, 3)) – Symmetry operation (rotation matrix) to apply.

• parity (int) – If odd, multiplies the result by -1 after transformation.

Returns:

tensor_array – Transformed tensor collection with the same shape as the input.

Return type:

numpy.ndarray