equitorch.irreps

Provides classes and functions for O(3) and SO(3) irreducible representations (irreps).

class equitorch.irreps.Irrep(l: int, p: Literal['e', 'o'] | int | None = None)

class equitorch.irreps.Irrep(lp: str | Tuple[int, Literal['e', 'o'] | int | None])

Bases: object

An irreducible representation (irrep) of O(3) (when parity is 'e' or 'o') or SO(3) (when the parity is None) group.

An Irrep can be created with the following ways:

>>> Irrep(2, 'e')   # O(3) irrep l=2 with even parity
2e
>>> Irrep("3o")     # O(3) irrep l=3 with odd parity
3o
>>> Irrep(1)        # SO(3) vector irrep (p=None)
1
>>> Irrep((2, -1))  # Using numeric parity values
2o

l

Rotation order/degree.

Type:

int

p

Parity component (-1, +1, or 0 for None).

Type:

int

dim

Dimensionality of the irrep (\(2l + 1\)).

Type:

int

property dim

equitorch.irreps.parse_irreps(str_irreps: str) → List[Tuple[Irrep, int]]

Parse an irreducible representation string and return a list of (Irrep, multiplicity).

Parameters:

str_irreps (str) – The string representation of irreps.

Returns:

A list of (Irrep, multiplicity) pairs.

Return type:

list[tuple[Irrep, int]]

Example

>>> parse_irreps('6x0+1+2e+5x2o+3x3e')
[(0, 6), (1, 1), (2e, 1), (2o, 5), (3e, 3)]

equitorch.irreps.show_irreps(list_irreps: List[Tuple[Irrep, int]]) → str

Convert a list of (Irrep, multiplicity) to string representation.

equitorch.irreps.check_irreps(irreps: str | Tuple | List | Irrep | Irreps) → Irreps

Ensure the input is an Irreps object.

equitorch.irreps.has_path(irrep_out: Irrep, irrep_1: Irrep, irrep_2: Irrep = None) → bool

Check if a tensor product path exists.

Parameters:

• irrep_out (Irrep) – The output irrep.

• irrep_1 (Irrep) – The first input irrep.

• irrep_2 (Irrep, optional) – The second input irrep. Defaults to None.

Returns:

True if the path exists, False otherwise.

Return type:

bool

class equitorch.irreps.Irreps(irreps: str | Tuple | List | Irrep | Irreps)

Bases: object

Collection of irreducible representations with multiplicities.

An Irreps can be created with the following ways:

>>> Irreps("6x0 + 1 + 2e + 5x2o")  # Explicit O(3) irreps
Irreps(6x0+1+2e+5x2o)
>>> Irreps((0, 3))                 # SO(3) irreps of l=0 to 3
Irreps(0+1+2+3)
>>> Irreps([0, "1e", "2o"])        # Mixed SO(3) and O(3) irreps
Irreps(0+1e+2o)
>>> Irreps("1e")                   # Single irrep
Irreps(1e)

irrep_groups

List of irrep-multiplicity pairs.

Type:

list[tuple[Irrep, int]]

static spherical_harmonics(max_degree: int, parity_even_degree: Literal['e', 'o'] | None = 'e') → Irreps

Generate irreps with alternating parities based on degree.

Parameters:

• max_degree (int) – Maximum degree (\(l\)) of the irreps to generate.

• parity_even_degree (str, optional) – Parity to assign to even degrees. Can be ‘e’ or ‘o’. Defaults to ‘e’.

Returns:

Irreps with alternating parities from \(l=0\) to \(l= ext{max_degree}\).

Return type:

Irreps

Examples

>>> Irreps.spherical_harmonics(2, 'e')
Irreps(0e+1o+2e)
>>> Irreps.spherical_harmonics(3, 'o')
Irreps(0o+1e+2o+3e)

static both_parities(max_degree: int, min_degree: int = 0) → Irreps

Generate irreps with both parities (even and odd) for each degree in a range.

For each degree \(l\) from min_degree to max_degree (inclusive), this method creates two irreps: one with even parity (e) and one with odd parity (o). This is useful when you need to consider both possible parities for each degree in a specified range.

Parameters:

• max_degree (int) – Maximum degree (\(l\)) of the irreps to generate.

• min_degree (int, optional) – Minimum degree (\(l\)) to start from. Defaults to 0.

Returns:

Irreps containing both even and odd parity versions for each degree from \(l= ext{min_degree}\) to \(l= ext{max_degree}\).

Return type:

Irreps

Examples

>>> Irreps.both_parities(1)
Irreps(0e+0o+1e+1o)
>>> Irreps.both_parities(2, min_degree=1)
Irreps(1e+1o+2e+2o)
>>> Irreps.both_parities(3, min_degree=2)
Irreps(2e+2o+3e+3o)

irrep_groups: List[Tuple[Irrep, int]]

sorted(by: callable = None) → Irreps

Returns a new Irreps instance with sorted irrep_groups.

The default sorting key orders irreps by their degree (\(l\)), parity (None < ‘e’ < ‘o’), and multiplicity. This ensures a consistent and intuitive ordering.

Parameters:

by (callable, optional) – A function to use for sorting. Defaults to None.

Returns:

A new sorted Irreps instance.

Return type:

Irreps

Examples

>>> Irreps("0e+0o+0").sorted()
Irreps(0+0e+0o)
>>> Irreps("3x0e+0e").sorted()
Irreps(0e+3x0e)

merged() → Irreps

Returns a new Irreps instance with consecutive identical irreps merged. Preserves the original order and only merges adjacent duplicates.

Returns:

A new Irreps instance with merged consecutive irreps.

Return type:

Irreps

Examples

>>> Irreps("0e+0e+1o+2e+2e+2e").merged()
Irreps(2x0e+1o+3x2e)
>>> Irreps("0+0e+1o+0e+0e").merged()  # Non-consecutive 0e are not merged
Irreps(0e+1o+2x0e)

simplified() → Irreps

Returns a new Irreps instance with merged multiplicities of identical irreps.

Combines all occurrences of the same irrep into a single entry with summed multiplicities. The result is sorted to maintain a consistent order.

Returns:

A new simplified and sorted Irreps instance.

Return type:

Irreps

Examples

>>> Irreps("0o+3x0o+0e+3x1+3x2e+4x1").simplified()
Irreps(0e+4x0o+7x1+3x2e)

eliminate_parity(simplified: bool = False) → Irreps

Converts O(3) irreducible representations to SO(3) by eliminating parities.

This method transforms the irreps list by setting the parity to 0 for all representations, projecting them from the O(3) group to the SO(3) group.

Parameters:

simplified (bool, optional) – If True, simplify the resulting Irreps. Defaults to False.

Returns:

New set of irreducible representations in SO(3) format where all parities are 0.

Return type:

Irreps

Example

>>> Irreps("4x0o+4x0e+4x1o+4x1e").eliminate_parity()
Irreps(4x0+4x0+4x1+4x1)
>>> Irreps("4x0o+4x0e+4x1o+4x1e").eliminate_parity(simplified=True)
Irreps(8x0+8x1)

short_repr()

isomorphic_to(other)

Returns if self and other are two isomorphic Irreps, that is, they are equals after simplification.

Parameters:

other (Irreps or convertible) – Representation to compare against

Returns:

True if both representations have identical components after simplification

Return type:

bool

Examples

>>> Irreps("0e+0e+1o").isomorphic_to("1x1o+2x0e")
True

property l_max

property dim

Total dimensionality of the representation space.

Calculated as sum of (irrep dimension × multiplicity) for all components

Examples

>>> Irreps("2x0e + 3x1o").dim  # 2 * 1 + 3 * 3
11

dims()

Generator yielding dimensionality of each irrep in expanded sequence.

Yields:

int – Dimension of each individual irrep instance

Examples

>>> list(Irreps("2x0+2x0e+3x1o+2").dims())
[1, 1, 1, 1, 3, 3, 3, 5]

channels_divided(mul: int)

Divide all multiplicities by an integer factor.

Parameters:

mul (int) – The integer factor to divide all multiplicities by. Must exactly divide all current multiplicities.

Returns:

New Irreps with all multiplicities divided by mul

Return type:

Irreps

Raises:

AssertionError – If any multiplicity is not divisible by mul

Examples

>>> Irreps("4x0e + 6x1o").channels_divided(2)
Irreps(2x0e+3x1o)

channels_multiplied(mul: int)

Multiply all multiplicities by an integer factor.

Parameters:

mul (int) – The integer factor to multiply all multiplicities by

Returns:

New Irreps with all multiplicities multiplied by mul

Return type:

Irreps

Examples

>>> Irreps("2x0e + 3x1o").channels_multiplied(2)
Irreps(4x0e+6x1o)

max_channels()

Compute the greatest common divisor (GCD) of all multiplicities in the Irreps.

This represents the largest integer factor by which all multiplicities can be divided while remaining integers.

Returns:

The GCD of all multiplicities in the representation

Return type:

int

Examples

>>> Irreps("128x0e + 64x1o + 32x2e").max_channels()
32
>>> Irreps("3x0 + 5x1 + 7x2").max_channels()
1

squeeze_max_channels()

Simplify the representation by dividing all multiplicities by their GCD and return both the simplified representation and the GCD factor.

Returns:

A tuple containing: - The simplified Irreps with multiplicities divided by their GCD - The max channels that was divided out

Return type:

tuple[Irreps, int]

Examples

>>> Irreps("128x0e + 64x1o + 32x2e").squeeze_max_channels()
(Irreps(4x0e+2x1o+2e), 32)
>>> Irreps("3x0 + 5x1 + 7x2").squeeze_max_channels()
(Irreps(3x0+5x1+7x2), 1)

Notes

This is useful when you need both the simplified representation and the scaling factor that was removed from the multiplicities.

equitorch.irreps.unique_irreps(irreps)

Identify unique irreducible representations (irreps) in a given Irreps object and provide a mapping from each unique irrep to the indices of its occurrences in the original Irreps object.

Parameters:

irreps (Irreps) – An Irreps object containing a collection of irreducible representations.

Returns:

A tuple containing: - uniqued_irreps (Irreps): An Irreps object containing only the unique irreps

from the input, maintaining the order of first appearance.

• unique_mapping (dict[Irrep, list[int]]): A dictionary where keys are the unique Irrep objects and values are lists of indices indicating where each unique irrep appeared in the original irreps sequence.

Return type:

tuple[Irreps, dict[Irrep, list[int]]]

Examples

>>> irreps_obj = Irreps("0+0e+1o+0e+0e")
>>> uniqued, mapping = unique_irreps(irreps_obj)
>>> print(uniqued)
Irreps(0+0e+1o)
>>> print(mapping)
{0: [0], 0e: [1, 3, 4], 1o: [2]}

>>> irreps_obj_2 = Irreps("2x1e+0o+1e")
>>> uniqued_2, mapping_2 = unique_irreps(irreps_obj_2)
>>> print(uniqued_2)
Irreps(1e+0o)
>>> print(mapping_2)
{1e: [0, 1, 3], 0o: [2]}

equitorch.irreps.irrep_segments(irreps)

Compute segment boundaries for the irreps.

Parameters:

irreps (Irreps-like) – Input irreps, can be any object that can be parsed to an Irreps.

Returns:

1D tensor of integers where the i-th element represents the starting index of the i-th irrep’s block. The last element is the total dimension of all irreps combined.

Return type:

torch.Tensor

Examples

>>> irrep_segments(Irreps("1o"))
[0, 3]
>>> irrep_segments(Irreps((0,4)))
[0, 1, 4, 9, 16, 25]
>>> irrep_segments("0+2x1e+3x2e+4")
[0, 1, 4, 7, 12, 17, 22, 31]

equitorch.irreps.irrep_indices(irreps)

Generate the mapping of the tensor indices to their corresponding irrep indices.

Parameters:

irreps (Irreps-like) – Input irreps, can be any object that can be parsed to an Irreps.

Returns:

1D tensor where each element indicates the index of the irrep (in the input list) that the corresponding element belongs to.

Return type:

torch.Tensor

Examples

>>> irrep_indices(Irreps("1o"))
tensor([0, 0, 0])
>>> irrep_indices(Irreps((0,3)))
tensor([0, 1, 1, 1, 2, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3])
>>> irrep_indices("0+2x1e+2e")
tensor([0, 1, 1, 1, 2, 2, 2, 3, 3, 3, 3, 3])

equitorch.irreps.irrep_degrees(irreps)

equitorch.irreps.element_degrees(irreps)

equitorch.irreps.element_orders(irreps)