escnn.group

This subpackage implements groups and group representations.

To avoid creating multiple redundant instances of the same group, we suggest using the factory functions in Factory Functions. These functions only build a single instance of each different group and return that instance on consecutive calls.

When building equivariant networks, it is not necessary to directly instantiate objects from this subpackage. Instead, we suggest using the interface provided in escnn.gspaces.

This subpackage is not dependent on the others and can be used alone to generate groups and compute their representations.

The main classes are Group, GroupElement and Representation. We provide a simple tools and interfaces for combining and generating new instances of these classes. For examples, group elements can be combined using the group operations (see GroupElement), representations can be restricted to a subgroup (restrict()), (often) induced to a larger group (induced_representation()), or combined via the direct-sum (direct_sum() or, simply, using the binary operator +) or the tensor-product (tensor()), while groups can be combined via the direct product (direct_product(), double_group() ) or generated via subgroup().

Factory Functions

SO(2)

so2_group(maximum_frequency=3)

Builds the group \(SO(2)\), i.e. the group of continuous planar rotations. Since the group has infinitely many irreducible representations, it is not possible to build all of them. Each irrep is associated to one unique frequency and the parameter maximum_frequency specifies the maximum frequency of the irreps to build. New irreps (associated to higher frequencies) can be manually created by calling the method escnn.group.SO2.irrep() (see the method’s documentation).

You should use this factory function to build an instance of escnn.group.SO2. Only one instance is built and, in case of multiple calls to this function, the same instance is returned. In case of multiple calls of this function with different parameters or in case new representations are built (eg. through the method escnn.group.SO2.irrep()), this unique instance is updated with the new representations and, therefore, all its references will see the new representations.

Parameters

maximum_frequency (int) – maximum frequency of the irreps

Returns

the group \(SO(2)\)

O(2)

o2_group(maximum_frequency=3)

Builds the group \(O(2)\), i.e. the group of continuous planar rotations and reflections. Since the group has infinitely many irreducible representations, it is not possible to build all of them. Each irrep is associated to one unique frequency and the parameter maximum_frequency specifies the maximum frequency of the irreps to build. New irreps (associated to higher frequencies) can be manually created by calling the method escnn.group.O2.irrep() (see the method’s documentation).

You should use this factory function to build an instance of escnn.group.O2. Only one instance is built and, in case of multiple calls to this function, the same instance is returned. In case of multiple calls of this function with different parameters or in case new representations are built (eg. through the method escnn.group.O2.irrep()), this unique instance is updated with the new representations and, therefore, all its references will see the new representations.

Parameters

maximum_frequency (int) – maximum frequency of the irreps

Returns

the group \(O(2)\)

Cyclic Group

cyclic_group(N)

Builds a cyclic group \(C_N\), i.e. the group of N discrete planar rotations.

You should use this factory function to build an instance of escnn.group.CyclicGroup. Only one instance is built and, in case of multiple calls to this function, the same instance is returned. In case of multiple calls of this function with different parameters or in case new representations are built (eg. through the method quotient_representation()), this unique instance is updated with the new representations and, therefore, all its references will see the new representations.

Parameters

N (int) – number of discrete rotations in the group

Returns

the cyclic group of order N

Dihedral Group

dihedral_group(N)

Builds a dihedral group \(D_{2N}\), i.e. the group of N discrete planar rotations and reflections.

You should use this factory function to build an instance of escnn.group.DihedralGroup. Only one instance is built and, in case of multiple calls to this function, the same instance is returned. In case of multiple calls of this function with different parameters or in case new representations are built (eg. through the method quotient_representation()), this unique instance is updated with the new representations and, therefore, all its references will see the new representations.

Parameters

N (int) – number of discrete rotations in the group

Returns

the dihedral group of order 2N

Trivial Group

trivial_group()

Builds the trivial group \(C_1\) which contains only the identity element \(e\).

You should use this factory function to build an instance of the trivial group. Only one instance is built and, in case of multiple calls to this function, the same instance is returned. In case of multiple calls of this function with different parameters or in case new representations are built, this unique instance is updated with the new representations and, therefore, all its references will see the new representations.

Returns

the trivial group

SO(3)

so3_group(maximum_frequency=2)

Builds the group \(SO(3)\), i.e. the group of continuous 3D rotations.

Parameters

maximum_frequency (int) – maximum frequency of the irreps

Returns

the group \(SO(3)\)

O(3)

o3_group(maximum_frequency=2)

Builds the group \(O(3)\), i.e. the group of continuous 3D rotations and reflections.

Parameters

maximum_frequency (int) – maximum frequency of the irreps

Returns

the group \(O(3)\)

Klein 4 Group

klein4_group()

Builds the group \(K_4 = C_2 \times C_2\). This group is most commonly associated with the symmetries of a rectangle. I.e. a group generated by two perpendicular reflection and a rotation of 180 degrees. The returned group instance has an additional 2D representation named "rectangle".

Returns

the group \(K_4\)

Octahedral Group

octa_group()

Builds the group \(O\), i.e. the group of symmetries of the cube or octahedron

Returns

the group \(O\)

Full Octahedral Group

full_octa_group()

Builds the group \(O_h = C_2 \times O\), i.e. the group of all symmetries of the cube or octahedron

Returns

the group \(O_h\)

Icosahedral Group

ico_group()

Builds the group \(I\), i.e. the group of symmetries of the icosahedron

Returns

the group \(I\)

Full Icosahedral Group

full_ico_group()

Builds the group \(I_h = C_2 \times I\), i.e. the group of all symmetries of the icosahedron

Returns

the group \(I\)

Cylinder Group

cylinder_group(maximum_frequency=3)

Builds the group \(C_2 \times SO(2)\), which contains continuous planar rotations (the \(SO(2)\) symmetry subgroup) and 3D inversions (the \(C_2\) subgroups).

Since the group has infinitely many irreducible representations, it is not possible to build all of them. Each irrep is associated to one unique frequency and the parameter maximum_frequency specifies the maximum frequency of the irreps to build. New irreps (associated to higher frequencies) can be manually created by calling the method irrep() (see the method’s documentation).

You should use this factory function to build an instance of of this group. Only one instance is built and, in case of multiple calls to this function, the same instance is returned. In case of multiple calls of this function with different parameters or in case new representations are built (eg. through the method irrep() of an instance of SO2), this unique instance is updated with the new representations and, therefore, all its references will see the new representations.

Parameters

maximum_frequency (int) – maximum frequency of the \(SO(2)\) irreps

Returns

the group \(C_2 \times O(2)\)

Full Cylinder Group

full_cylinder_group(maximum_frequency=3)

Builds the group \(C_2 \times O(2)\), i.e. the group of symmetries of a cylinder. It contains continuous planar rotations and planar reflections (the \(O(2)\) dihedral symmetry subgroup) and 3D inversions (the \(C_2\) subgroups). The group also includes the subgroup of mirroring with respect to a plane passing throgh the axis of the cylinder.

Since the group has infinitely many irreducible representations, it is not possible to build all of them. Each irrep is associated to one unique frequency and the parameter maximum_frequency specifies the maximum frequency of the irreps to build. New irreps (associated to higher frequencies) can be manually created by calling the method irrep() (see the method’s documentation).

You should use this factory function to build an instance of of this group. Only one instance is built and, in case of multiple calls to this function, the same instance is returned. In case of multiple calls of this function with different parameters or in case new representations are built (eg. through the method irrep() of an instance of O2), this unique instance is updated with the new representations and, therefore, all its references will see the new representations.

Parameters

maximum_frequency (int) – maximum frequency of the \(O(2)\) irreps

Returns

the group \(C_2 \times O(2)\)

Discrete Cylinder Group

cylinder_discrete_group(n)

Builds the group \(C_2 \times C_n\), which contains n discrete planar rotations (the \(C_n\) symmetry subgroup) and 3D inversions (the \(C_2\) subgroups).

You should use this factory function to build an instance of of this group. Only one instance is built and, in case of multiple calls to this function, the same instance is returned.

Parameters

n (int) – number of discrete rotations

Returns

the group \(C_2 \times C_n\)

Discrete Full Cylinder Group

full_cylinder_discrete_group(n)

Builds the group \(C_2 \times D_n\), i.e. a group of discrete symmetries of a cylinder. It contains n discrete planar rotations and planar reflections (the \(D_n\) dihedral symmetry subgroup) and 3D inversions (the \(C_2\) subgroups). The group also includes the subgroup of mirroring with respect to n planes passing through the axis of the cylinder.

You should use this factory function to build an instance of of this group. Only one instance is built and, in case of multiple calls to this function, the same instance is returned.

Parameters

n (int) – number of discrete rotations

Returns

the group \(C_2 \times D_n\)

Direct Product

direct_product(G1, G2, name=None)

Generates the direct product of the two input groups G1 and G2.

Parameters

• G1 (Group) – first group

• G2 (Group) – second group

• name (str, optional) – name assigned to the resulting group

Returns

an instance of DirectProductGroup

Double Group

double_group(G, name=None)

Generates the direct product of the input group G with itself.

Parameters

• G (Group) – the group

• name (str, optional) – name assigned to the resulting group

Returns

an instance of DoubleGroup

Group

class Group(name, continuous, abelian)

Abstract class defining the interface of a group.

A group is a set of group elements together with a binary operation satisfying a number of axioms.

In this library, this is implemented using this class Group and the class GroupElement.

One can retrieve or generate elements of a group by using, for instance, the properties or methods identity() , elements() or sample(). Each group may also have additional methods to generate its group elements. Additionally, one can use the method element() to generate a new group element.

The group algebra is directly implemented inside GroupElement such that one can combine group elements in a way that resamples mathematical expressions. In particular, the @ implements the binary product while ~ implements the group inverse. See GroupElement for more details.

Parameters

• name (str) – name identifying the group

• continuous (bool) – whether the group is non-finite or finite

• abelian (bool) – whether the group is abelian (commutative)

Variables

• ~.name (str) – Name identifying the group

• ~.continuous (bool) – Whether it is a non-finite or a finite group

• ~.abelian (bool) – Whether it is an abelian group (i.e. if the group law is commutative)

abstract property PARAM: str

abstract property PARAMETRIZATIONS: List[str]

order()

Returns the number of elements in this group if it is a finite group, otherwise -1 is returned

Returns

the size of the group or -1 if it is a continuous group

element(element, param=None)

Generate the element of the current group parametrized by element according to the parametrization param.

Each group supports a different set of parametrizations. By default, the parametrization escnn.group.Group.PARAM is used. The list of all available parametrizations of a group can be accessed through the property escnn.group.Group.PARAMETRIZATIONS.

Parameters

• element – values parametrizing a group element.

• param (str) – string identifying the parametrization to be used.

Returns

an instance of GroupElement

abstract property identity: escnn.group.group.GroupElement

The identity element of the group.

The identity element \(e\) satisfies the following property \(\forall\ g \in G,\ g \cdot e = e \cdot g= g\) .

abstract property elements: List[escnn.group.group.GroupElement]

If the group is finite (i.e. self.continuous = False), it is a list of all group elements. If the group is not finite, this property is None.

Returns

a list of GroupElement instances

abstract property subgroup_trivial_id

The subgroup id associated with the trivial subgroup containing only the identity element \({e}\). The id can be used in the method subgroup() to generate the subgroup.

abstract property subgroup_self_id

The subgroup id associated with the group itself. The id can be used in the method subgroup() to generate the subgroup.

abstract property generators: List[escnn.group.group.GroupElement]

If the group is finite (self.continuous = False), a list of group elements which can generate this group. Should raise a ValueError if the group is not finite.

Returns

a list of GroupElement instances

abstract sample()

Sample a random element of the group from a uniform distribution over the group.

Returns

GroupElement – the element sampled

grid(*args, **kwargs)

Method to generate collections fo points over the group. Each group should implement its own set of collections. Check the individual groups’ documentations for details about the supported arguments.

Returns

a list of GroupElement instances

subgroup(id)

Restrict the current group to the subgroup identified by the input id.

Parameters

id – the identifier of the subgroup

Returns

a tuple containing

• the subgroup,

• a function which maps an element of the subgroup to its inclusion in the original group and

• a function which maps an element of the original group to the corresponding element in the subgroup (returns None if the element is not contained in the subgroup)

irreps()

List containing all irreducible representations (IrreducibleRepresentation) currently instantiated for this group.

Returns

a list containing all irreducible representations built

property representations: Dict[str, escnn.group.representation.Representation]

Dictionary containing all representations (Representation) instantiated for this group.

Returns

a dictionary containing all representations built

abstract property trivial_representation: escnn.group.irrep.IrreducibleRepresentation

Builds the trivial representation of the group. The trivial representation is a 1-dimensional representation which maps any element to 1, i.e. \(\forall g \in G,\ \rho(g) = 1\).

Returns

the trivial representation of the group

abstract irrep(*id)

Builds the irreducible representation (IrreducibleRepresentation) of the group which is specified by the input arguments.

See also

Check the documentation of the specific group subclass used for more information on the valid id values.

Parameters

*id – parameters identifying the specific irrep.

Returns

the irrep built

property regular_representation: escnn.group.representation.Representation

Builds the regular representation of the group if the group has a finite number of elements; returns None otherwise.

The regular representation of a finite group \(G\) acts on a vector space \(\R^{|G|}\) by permuting its axes. Specifically, associating each axis \(e_g\) of \(\R^{|G|}\) to an element \(g \in G\), the representation of an element \(\tilde{g}\in G\) is a permutation matrix which maps \(e_g\) to \(e_{\tilde{g}g}\). For instance, the regular representation of the group \(C_4\) with elements \(\{r^k | k=0,\dots,3 \}\) is instantiated by:

\(g\)	\(e\)	\(r\)	\(r^2\)	\(r^3\)
\(\rho_\text{reg}^{C_4}(g)\)	\(\begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \\ \end{bmatrix}\)	\(\begin{bmatrix} 0 & 0 & 0 & 1 \\ 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ \end{bmatrix}\)	\(\begin{bmatrix} 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \\ 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ \end{bmatrix}\)	\(\begin{bmatrix} 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \\ 1 & 0 & 0 & 0 \\ \end{bmatrix}\)

A vector \(v=\sum_g v_g e_g\) in \(\R^{|G|}\) can be interpreted as a scalar function \(v:G \to \R,\, g \mapsto v_g\) on \(G\).

Returns

the regular representation of the group

quotient_representation(subgroup_id, representatives=None, name=None)

Builds the quotient representation of the group with respect to the subgroup identified by the input subgroup_id.

Similar to regular_representation(), the quotient representation \(\rho_\text{quot}^{G/H}\) of \(G\) w.r.t. a subgroup \(H\) acts on \(\R^{|G|/|H|}\) by permuting its axes. Labeling the axes by the cosets \(gH\) in the quotient space \(G/H\), it can be defined via its action \(\rho_\text{quot}^{G/H}(\tilde{g})e_{gH}=e_{\tilde{g}gH}\).

Regular and trivial representations are two specific cases of quotient representations obtained by choosing \(H=\{e\}\) or \(H=G\), respectively. Vectors in the representation space \(\R^{|G|/|H|}\) can be viewed as scalar functions on the quotient space \(G/H\).

The quotient representation \(\rho_\text{quot}^{G/H}\) can also be defined as the induced_representation() from the trivial representation of the subgroup \(H\).

Todo

docs for representatives

Parameters

• subgroup_id – identifier of the subgroup

• representatives (list, optional) –

• name (str, optional) – optionally, specify a custom name for this representation

Returns

the quotient representation of the group

induced_representation(subgroup_id, repr, representatives=None, name=None)

Builds the induced representation from the input representation repr of the subgroup identified by the input subgroup_id.

Todo

docs for representatives

Parameters

• subgroup_id – identifier of the subgroup

• repr (Representation) – the representation of the subgroup

• representatives (list, optional) –

• name (str, optional) – optionally, specify a custom name for this representation

Returns

the induced representation of the group

spectral_regular_representation(*irreps, name=None)

Finite dimensional invariant subspace of the regular representation containing only the irreps passed in input. The regular representation is expressed in the spectral basis, i.e. as a direct sum of irreps.

The optional parameter name is also used for caching purpose. Consecutive calls of this method using the same name will ignore the argument irreps and return the same instance of representation.

See also

escnn.group.HomSpace.induced_representation()

spectral_quotient_representation(subgroup_id, *irreps, name=None)

Finite dimensional invariant subspace of the quotient representation containing only the irreps passed in input. The quotient representation is expressed in the spectral basis, i.e. as a direct sum of irreps.

The optional parameter name is also used for caching purpose. Consecutive calls of this method using the same name will ignore the arguments subgroup_id and irreps and return the same instance of representation.

See also

escnn.group.HomSpace.induced_representation()

restrict_representation(id, repr)

Restrict the input Representation to the subgroup identified by id.

Any representation \(\rho : G \to \GL{\R^n}\) can be uniquely restricted to a representation of a subgroup \(H < G\) by restricting its domain of definition:

\[\Res{H}{G}(\rho): H \to \GL{{\R}^n},\ h \mapsto \rho\big|_H(h)\]

We recommend directly using the method escnn.group.Representation.restrict().

See also

Check the documentation of the method subgroup() of the group used to see the available subgroups and accepted ids.

Parameters

• id – identifier of the subgroup

• repr (Representation) – the representation to restrict

Returns

the restricted representation

homspace(id)

If \(G\) is the current group and id identifies the subgroup \(H\) (see subgroup()), this method generates the homogeneous space HomSpace \(X = G / H\).

Note

The generated instance of HomSpace is cached inside the instance of the current group such that repeated calls of this method using the same id return the same instance of HomSpace and no additional computations are required.

Returns

an instance of HomSpace

abstract testing_elements()

A finite number of group elements to use for testing.

get_irrep_id(psi)

GroupElement

class GroupElement(g, group, param=None)

Class implementing an element of a group.

Group elements can be combined the group operations like the group law or the inverse. In particular, one can combine two group elements through the group law using the operator @ or compute the inverse of an element using ~. For example

G = so3_group()
a = G.sample()
b = G.sample()

c = a @ b
a_ = ~a

e = G.identity

assert e == ~e
assert a == a @ e

Parameters

• g – values parametrizing the group element

• group (Group) – the group this element belongs to

• param (str) – the type of parametrization of g

Variables

~.group (Group) – the group it belongs to

property value

Returns the values of the internal parametrization of the group element. These values parametrize the group element according to the parametrization escnn.group.GroupElement.param.

property param: str

The type parametrization used internally to store this group element.

to(param)

Converts the current group element to the input parametrization param and returns the corresponding values.

Note

This method does not return an instance of GroupElement. This method does not affect the internal representation of the element, but just converts it to the input param and returns the converted values.

Groups

SO(2)

class SO2(maximum_frequency=6)

Bases: escnn.group.group.Group

Build an instance of the special orthogonal group \(SO(2)\) which contains continuous planar rotations.

A group element is a rotation \(r_\theta\) of \(\theta \in [0, 2\pi)\), with group law \(r_\alpha \cdot r_\beta = r_{\alpha + \beta}\).

Elements are implemented as floating point numbers \(\theta \in [0, 2\pi)\).

Note

Since the group has infinitely many irreducible representations, it is not possible to build all of them. Each irrep is associated to one unique frequency and the parameter maximum_frequency specifies the maximum frequency of the irreps to build. New irreps (associated to higher frequencies) can be manually created by calling the method irrep() (see the method’s documentation).

Subgroup Structure.

A subgroup of \(SO(2)\) is a cyclic group \(C_M\) with order \(M\) which is generated by \(r_{\frac{2\pi}{M}}\).

The id which identifies a subgroup is the integer \(M\) (the order of the subgroup).

Parameters

maximum_frequency (int, optional) – the maximum frequency to consider when building the irreps of the group

Variables

~.rotation_order (int) – this is equal to -1, which means the group contains an infinite number of rotations

grid(N, type='regular', seed=None)

Todo

Add documentation

testing_elements(n=52)

A finite number of group elements to use for testing.

bl_regular_representation(L)

Band-Limited regular representation up to frequency L (included).

Parameters

L (int) – max frequency

bl_irreps(L)

Returns a list containing the id of all irreps of frequency smaller or equal to L. This method is useful to easily specify the irreps to be used to instantiate certain objects, e.g. the Fourier based non-linearity FourierPointwise.

standard_representation()

Standard representation of \(\SO2\) as 2x2 rotation matrices

This is equivalent to self.irrep(1).

irrep(k)

Build the irrep with rotational frequency \(k\) of \(SO(2)\). Notice: the frequency has to be a non-negative integer.

Parameters

k (int) – the frequency of the irrep

Returns

the corresponding irrep

O(2)

class O2(maximum_frequency=6)

Bases: escnn.group.group.Group

Build an instance of the orthogonal group \(O(2)\) which contains reflections and continuous planar rotations.

Any group element is either a rotation \(r_{\theta}\) by an angle \(\theta \in [0, 2\pi)\) or a reflection \(f\) followed by a rotation, i.e. \(r_{\theta}f\). Two reflections gives the identity \(f \cdot f = e\) and a reflection commutes with a rotation by inverting it, i.e. \(r_\theta \cdot f = f \cdot r_{-\theta}\). A group element \(r_{\theta}f^j\) is implemented as a pair \((j, \theta)\) with \(j \in \{0, 1\}\) and \(\theta \in [0, 2\pi)\).

Note

Since the group has infinitely many irreducible representations, it is not possible to build all of them. Each irrep is associated to one unique integer frequency and the parameter maximum_frequency specifies the maximum frequency of the irreps to build. New irreps (associated to higher frequencies) can be manually created by calling the method irrep() (see the method’s documentation).

Subgroup Structure.

A subgroup of \(O(2)\) is identified by a tuple id \((\theta, M)\).

Here, \(M\) can be either a positive integer indicating the number of rotations in the subgroup or \(-1\), indicating that the subgroup contains all continuous rotations. \(\theta\) is either None or an angle in \([0, \frac{2\pi}{M})\). If \(\theta\) is None, the subgroup does not contain any reflections. Otherwise, the subgroup contains the reflection \(r_{\theta}f\) along the axis of the current group rotated by \(\frac{\theta}{2}\).

Valid combinations are:

• (None, \(M>0\)): restrict to the cyclic subgroup \(C_M\) generated by \(\langle r_{2\pi/M} \rangle\).

• (None, \(-1\)): restrict to the subgroup \(SO(2)\) containing only the rotations

• (\(\theta\), \(M>0\)): restrict to the dihedral subgroup \(D_{M}\) generated by \(\langle r_{2\pi/M}, r_{\theta} f \rangle\)

In particular:

• (\(0.\), \(1\)): restrict to the reflection group generated by \(\langle f \rangle\)

• (\(0.\), \(M\)): restrict to the dihedral subgroup \(D_{M}\) generated by \(\langle r_{2\pi/M}, f \rangle\)

• (None, \(1\)): restrict to the cyclic subgroup of order 1 containing only the identity

Parameters

maximum_frequency (int, optional) – the maximum frequency to consider when building the irreps of the group

Variables

• ~.reflection – the reflection element \((j, \theta) = (1, 0.)\)

• ~.rotation_order (int) – this is equal to -1, which means the group contains an infinite number of rotations

grid(N, type='regular', seed=None)

Todo

Add documentation

grid_so2(N, type='regular', seed=None)

Todo

Add documentation

testing_elements(n=52)

A finite number of group elements to use for testing.

bl_regular_representation(L)

Band-Limited regular representation up to frequency L (included).

Parameters

L (int) – max frequency

bl_quotient_representation(L, subgroup_id, name=None)

Band-Limited quotient representation up to frequency L (included).

The quotient representation corresponds to the action of the current group \(G\) on functions over the homogeneous space \(G/H\), where \(H\) is the subgroup of \(G\) identified by subgroup_id.

Parameters

• L (int) – max frequency

• subgroup_id – id identifying the subgroup H.

• name (str, optional) –

bl_irreps(L)

Returns a list containing the id of all irreps of (rotational) frequency smaller or equal to L. This method is useful to easily specify the irreps to be used to instantiate certain objects, e.g. the Fourier based non-linearity FourierPointwise.

standard_representation()

Standard representation of \(\O2\) as 2x2 rotation matrices

This is equivalent to self.irrep(1, 1).

irrep(j, k)

Build the irrep with reflection and rotation frequencies \(j\) (reflection) and \(k\) (rotation) of the current group. Notice: the frequencies has to be non-negative integers: \(j \in \{0, 1\}\) and \(k \in \mathbb{N}\)

Valid parameters are \((0, 0)\) and \((1, 0)\), \((1, 1)\), \((1, 2)\), \((1, 3)\), …

Parameters

• j (int) – the frequency of the reflection in the irrep

• k (int) – the frequency of the rotations in the irrep

Returns

the corresponding irrep

Cyclic Group

class CyclicGroup(N)

Bases: escnn.group.group.Group

Build an instance of the cyclic group \(C_N\) which contains \(N\) discrete planar rotations.

The group elements are \(\{e, r, r^2, r^3, \dots, r^{N-1}\}\), with group law \(r^a \cdot r^b = r^{\ a + b \!\! \mod \!\! N \ }\). The cyclic group \(C_N\) is isomorphic to the integers modulo N. For this reason, elements are stored as the integers between \(0\) and \(N-1\), where the \(k\)-th element can also be interpreted as the discrete rotation by \(k\frac{2\pi}{N}\).

Subgroup Structure.

A subgroup of \(C_N\) is another cyclic group \(C_M\) and is identified by an id containing the integer \(M\) (i.e. the order of the subgroup).

If the current group is \(C_N\), the subgroup is generated by \(r^{(N/M)}\). Notice that \(M\) has to divide the order \(N\) of the group.

Parameters

N (int) – order of the group

Variables

~.rotation_order (int) – the number of rotations, i.e. the order of the group

testing_elements()

A finite number of group elements to use for testing.

grid(type, N)

Todo

Add docs

irrep(k)

Build the irrep of frequency k of the current cyclic group. The frequency has to be a non-negative integer in \(\{0, \dots, \left \lfloor N/2 \right \rfloor \}\), where \(N\) is the order of the group.

Parameters

k (int) – the frequency of the representation

Returns

the corresponding irrep

bl_irreps(L)

Returns a list containing the id of all irreps of frequency smaller or equal to L. This method is useful to easily specify the irreps to be used to instantiate certain objects, e.g. the Fourier based non-linearity FourierPointwise.

Dihedral Group

class DihedralGroup(N)

Bases: escnn.group.group.Group

Build an instance of the dihedral group \(D_N\) which contains reflections and N discrete planar rotations. The order of the group \(D_N\) is \(2N\).

The group elements are \(\{e,\, r,\, r^2,\, r^3,\, \dots,\, r^{N-1},\, f,\, rf,\, r^2f,\, r^3f,\, \dots,\, r^{N-1}f\}\), so an element of this group is either a rotation \(r^k\) or a reflection \(r^kf\) along an axis.

Any group element is either a discrete rotation \(r^k\) by an angle \(k\frac{2\pi}{N}\) or a reflection \(f\) followed by a rotation, i.e. \(r^kf\). As in CyclicGroup, combination of rotations behaves like arithmetic modulo N, so \(r^a \cdot r^b = r^{\ a + b \!\! \mod \!\! N}\ \). Two reflections gives the identity \(f \cdot f = e\) and a reflection commutes with a rotation by inverting it, i.e. \(r^k \cdot f = f \cdot r^{-k}\).

A group element \(r^kf^j\) is implemented as a pair \((j, k)\) with \(j \in \{0, 1\}\) and and \(k \in \{0, \dots, N-1\}\).

Subgroup Structure.

A subgroup of \(D_{2N}\) is identified by a tuple id \((k, M)\).

Here, \(M\) is a positive integer indicating the number of discrete rotations in the subgroup while \(k\) is either None or an integer in \(\{0, \dots, \frac{N}{M}-1\}\). If \(k\) is None, the subgroup does not contain any reflections. Otherwise, the subgroup contains the reflection \(r^k f\) along the axis of the current group rotated by \(k\frac{\pi}{N}\). The order \(M\) has to divide the rotation order \(N\) of the current group (\(D_{2N}\)).

Valid combinations are:

• (None, \(M\)): restrict to the cyclic subgroup \(C_M\) generated by \(\langle r^{N/M} \rangle\).

• (\(k\), \(M\)): restrict to the dihedral subgroup \(D_{M}\) generated by \(\langle r^{N/M}, r^{k}f \rangle\)

In particular:

• (None, \(1\)): restrict to the cyclic subgroup of order 1 containing only the identity

• (\(0\), \(1\)): restrict to the reflection group generated by \(\langle f \rangle\)

• (\(0\), \(M\)): restrict to the dihedral subgroup \(D_{M}\) generated by \(\langle r^{N/M}, f \rangle\)

• (\(k\), \(1\)): restrict to the reflection group generated by \(\langle r^{k}f \rangle = \{e, r^{k}f\}\)

Parameters

N (int) – number of discrete rotations in the group

Variables

• ~.reflection – the reflection element

• ~.rotation_order (int) – the number of discrete rotations in this group (equal to the parameter N)

testing_elements()

A finite number of group elements to use for testing.

grid(type, N)

Todo

Add docs

bl_irreps(L)

Returns a list containing the id of all irreps of (rotational) frequency smaller or equal to L. This method is useful to easily specify the irreps to be used to instantiate certain objects, e.g. the Fourier based non-linearity FourierPointwise.

irrep(j, k)

Build the irrep with reflecion and rotation frequencies \(j\) (reflection) and \(k\) (rotation) of the current dihedral group. Note: the frequencies has to be non-negative integers, i.e. \(j \in [0, 1]\) and \(k \in \{0, \dots, \left\lfloor N/2 \right\rfloor \}\), where \(N\) is the rotational order of the group (the number of rotations, i.e. the half the group order).

If \(N\) is odd, valid parameters are \((0, 0)\), \((1, 0)\), \((1, 1)\) … \((1, \left\lfloor N/2 \right\rfloor)\). If \(N\) is even, the group also has the irrep \((0, N/2)\).

Parameters

• j (int) – the frequency of the reflections in the irrep

• k (int) – the frequency of the rotations in the irrep

Returns

the corresponding irrep

SO(3)

class SO3(maximum_frequency=2)

Bases: escnn.group.group.Group

Build an instance of the special orthogonal group \(SO(3)\) which contains continuous rotations in the space.

Subgroup Structure:

id[0]	id[1]	subgroup
‘so3’		\(SO(3)\) group itself
‘ico’		Icosahedral \(I\) subgroup
‘octa’		Octahedral \(O\) subgroup
‘tetra’		Tetrahedral \(T\) subgroup
False	-1	\(SO(2)\) subgroup of planar rotations around Z axis
False	N	\(C_N\) of N discrete planar rotations around Z axis
True (or float)	-1	dihedral \(O(2)\) subgroup of planar rotations around Z axis and out-of-plane \(\pi\) rotation around axis in the XY plane defined by id[1] / 2 (X axis by default)
True (or float)	N>1	dihedral \(D_N\) subgroup of N discrete planar rotations around Z axis and out-of-plane \(\pi\) rotation around axis in the XY plane defined by id[1] / 2 (X axis by default)
True (or float)	1	equivalent to (False, 2, adj)

Parameters

maximum_frequency (int, optional) – the maximum frequency to consider when building the irreps of the group

grid(type, *args, adj=None, parametrization='Q', **kwargs)

Method which builds different collections of elements of \(\SO3\).

Depending on the value of type, the method accept a different set of parameters using the args and the kwargs arguments:

• type = "rand". Generate N random uniformly distributed samples over the group. The method accepts an integer N and, optionally, a random seed seed (or an instance of numpy.random.RandomState).

• type = "thomson". Generate N samples distributed (approximately) uniformly over the group. The samples are obtained with a numerical method which tries to minimize a potential energy depending on the relative distance between the points. The first call of this method for a particular value of N might be slow due to this numerical method. However, the resulting set of points is cached on disk such that following calls will return the same result instantly.

• type = "thomson_cube". Generate 24*N samples with cubic (octahedral) symmetry, distributed (approximately) uniformly over the group. The samples are obtained with a numerical method which tries to minimize a potential energy depending on the relative distance between the points. The first call of this method for a particular value of N might be slow due to this numerical method. However, the resulting set of points is cached on disk such that following calls will return the same result instantly.

• type = "ico", "cube", "tetra". Generate respectively 60, 24 or 12 samples corresponding to the rotational symmetries of respectively the Icosahedron (or Dodecahedron), Octahedron (or Cube) or the Tetrahedron.

• type = "hopf". Generates about N points by creating a HEAPlix grid on the sphere and combining it with a regular grid over \(\SO2\) using Hopf fibration.

Todo

add reference to paper explaining Hopf fibration based grid

• type = "fibonacci". Generates about N points by creating a Fibonacci grid on the sphere and combining it with a regular grid over \(\SO2\) using Hopf fibration.

Parameters

• type (str) – string identifying the type of samples

• *args – arguments specific for the type of samples chosen

• adj (GroupElement, optional) – optionally, apply an adjoint transform to the sampled elements.

• parametrization (str, optional) –

• **kwargs – arguments specific for the type of samples chosen

Returns

a list of group elements

sphere_grid(type, *args, adj=None, **kwargs)

Method which builds different collections of points over the sphere.

Here, a sphere is interpreted as the quotient space \(\SO3 / \SO2\). The list returned by this method contains instances of GroupElement. These are elements of SO3 and should be interpreted as representatives of cosets in \(\SO3 / \SO2\).

Depending on the value of type, the method accept a different set of parameters using the args and the kwargs arguments:

• type = "rand". Generate N random uniformly distributed samples over the sphere. The method accepts an integer N and, optionally, a random seed seed (or an instance of numpy.random.RandomState).

• type = "thomson". Generate N samples distributed (approximately) uniformly over the sphere. The samples are obtained with a numerical method which tries to minimize a potential energy depending on the relative distance between the points. The first call of this method for a particular value of N might be slow due to this numerical method. However, the resulting set of points is cached on disk such that following calls will return the same result instantly.

• type = "thomson_cube". Generate 24*N samples with perfect cubic (octahedral) symmetry, distributed (approximately) uniformly over the shere. The samples are obtained with a numerical method which tries to minimize a potential energy depending on the relative distance between the points. The first call of this method for a particular value of N might be slow due to this numerical method. However, the resulting set of points is cached on disk such that following calls will return the same result instantly.

• type = "ico", "cube", "tetra". Return the orbit of the point \((0, 0, 1)\) under the action of the Icosahedral, Octahedral or Tetrahedral group. The resulting samples correspond to the corners, edges or faces of a Platonic solid.

Todo

add more types to support vertices, edges and faces for all solids. Currently, "ico" returns the centers of the 30 edges while "cube" returns the centers of its 6 faces

Warning

The naming convention might change in future to support faces/edges/vertices of the solids

• type = "healpix". Generates about N points using the HEAPlix grid on the sphere.

• type = "fibonacci". Generates N points using the Fibonacci grid on the sphere.

• type = "longlat". Generates an N by M grid over the sphere in the longitude (N) - latitude (M) coordinates.

Parameters

• type (str) – string identifying the type of samples

• *args – arguments specific for the type of samples chosen

• adj (GroupElement, optional) – optionally, apply an adjoint transform to the sampled elements.

• **kwargs – arguments specific for the type of samples chosen

Returns

a list of group elements

testing_elements(n=3)

A finite number of group elements to use for testing.

bl_regular_representation(L)

Band-Limited regular representation up to frequency L (included).

Parameters

L (int) – max frequency

bl_quotient_representation(L, subgroup_id)

Band-Limited quotient representation up to frequency L (included).

The quotient representation corresponds to the action of the current group \(G\) on functions over the homogeneous space \(G/H\), where \(H\) is the subgroup of \(G\) identified by subgroup_id.

Parameters

• L (int) – max frequency

• subgroup_id – id identifying the subgroup H.

bl_sphere_representation(L)

Representation of \(\SO3\) acting on functions on the sphere band-limited representation up to frequency L (included).

Parameters

L (int) – max frequency

bl_induced_representation(L, repr, subgroup_id)

Band-Limited induced representation from the input representation repr up to frequency L (included).

Parameters

• L (int) – max frequency

• repr (IrreducibleRepresentation) – the representation of the subgroup

• subgroup_id – id identifying the subgroup H.

bl_irreps(L)

Returns a list containing the id of all irreps of frequency smaller or equal to L. This method is useful to easily specify the irreps to be used to instantiate certain objects, e.g. the Fourier based non-linearity FourierPointwise.

standard_representation()

Standard representation of \(\SO3\) as 3x3 rotation matrices

irrep(l)

Build the irrep with rotational frequency \(l\) of \(SO(3)\). Notice: the frequency has to be a non-negative integer.

Parameters

l (int) – the frequency of the irrep

Returns

the corresponding irrep

O(3)

class O3(maximum_frequency=3)

Bases: escnn.group.group.Group

Build an instance of the orthogonal group \(O(3)\) which contains reflections and continuous 3D rotations.

Subgroup structure:

id[0]	id[1]	id[2]	subgroup
False	‘so3’		\(SO(3)\) subgroup (equivalent to just id = “so3”)
	‘ico’		Icosahedral \(I\) subgroup
	‘octa’		Octahedral \(O\) subgroup
	‘tetra’		Tetrahedral \(T\) subgroup
	False	-1	\(SO(2)\) subgroup of planar rotations around Z axis
	False	N	\(C_N\) of N discrete planar rotations around Z axis
	True (or float)	-1	dihedral \(O(2)\) subgroup of planar rotations around Z axis and out-of-plane \(\pi\) rotation around axis in the XY plane defined by id[1]/2 (X axis by default)
	True (or float)	N>1	dihedral \(D_N\) subgroup of N discrete planar rotations around Z axis and out-of-plane \(\pi\) rotation around axis in the XY plane defined by id[1]/2 (X axis by default)
	True (or float)	1	equivalent to (False, False, 2, adj)
‘fulltetra’			\(T_d \cong O\) full isometry group tetrahedron
True	‘so3’		\(O(3)\) itself (equivalent to just id = “o3”)
	‘ico’		Icosahedral \(I_h \cong I \times C_2\) subgroup
	‘octa’		Octahedral \(O_h \cong O \times C_2\) subgroup
	‘tetra’		Tetrahedral \(T_h \cong T \times C_2\) subgroup
	False	-1	\(SO(2) \times C_2\) subgroup of planar rotations around Z axis and inversions
	False	N>1	\(C_N \times C_2\) of N discrete planar rotations around Z axis and inversions
	False	1	\(C_2\) subgroup inversions
	True (or float)	-1	\(O(2) \times C_2\) subgroup of planar rotations around Z axis, out-of-plane \(\pi\) rotation around axis in the XY plane defined by id[1]/2 (X axis by default) and inversions
	True (or float)	N>1	\(D_N \times C_2\) subgroup of N discrete planar rotations around Z axis, out-of-plane \(\pi\) rotation around axis in the XY plane defined by id[1]/2 (X axis by default) and inversions
	True (or float)	1	equivalent to (True, False, 2, adj)
‘cone’	-1		conic subgroup \(O(2)\)
	N>1		conic subgroup of N discrete rotations \(D_N\)
	1		subgroup \(C_2\) of mirroring with respect to a plane passing through the X axis
	float	-1	conic subgroup \(O(2)\) with reflection along the id[1]/2 axis in the XY plane. Equivalent to (‘cone’, -1, adj)
	float	N>1	conic subgroup of N discrete rotations \(D_N\) along the id[1]/2 axis in the XY plane. Equivalent to (‘cone’, N, adj)
	float	1	subgroup \(C_2\) of mirroring with respect to the plane passing through the id[1]/2 axis in the XY plane. Equivalent to (‘cone’, 1, adj)

Warning

For some subgroups, `id[1]` expects either a boolean or a floating point value. In this case, `id[1] = 0` might be mistakenly interpreted as `False` rather than `0.0`, so one should pay attention to use `0.` rather than `0`.

Parameters

maximum_frequency (int, optional) – the maximum frequency to consider when building the irreps of the group

property inversion: escnn.group.group.GroupElement

The inversion element of \(\O3\).

grid(type, *args, adj=array([0., 0., 0., 1.]), parametrization='Q', **kwargs)

Method which builds different collections of elements of \(\O3\).

Depending on the value of type, the method accept a different set of parameters using the args and the kwargs arguments:

• type = "rand". Generate N random uniformly distributed samples over the group. The method accepts an integer N and, optionally, a random seed seed (or an instance of numpy.random.RandomState).

Other options generate grids over \(\SO3\) (see escnn.group.SO3.grid()) and then repeat it twice, by combining each \(\SO3\) element with both the identity and the inversion elements of \(\O3\).

• type = "thomson". Generate N samples distributed (approximately) uniformly over \(\SO3\)

• type = "ico", "cube", "tetra". Generate respectively 60, 24 or 12 samples over \(\SO3\).

• type = "hopf". Generates about N points on \(\SO3\).

• type = "fibonacci". Generates about N points on \(\SO3\).

See also

escnn.group.SO3.grid()

Parameters

• type (str) – string identifying the type of samples

• *args – arguments specific for the type of samples chosen

• adj (GroupElement, optional) – optionally, apply an adjoint transform to the sampled elements.

• parametrization (str, optional) –

• **kwargs – arguments specific for the type of samples chosen

Returns

a list of group elements

grid_so3(type, *args, adj=array([0., 0., 0., 1.]), parametrization='Q', **kwargs)

Method which builds different collections of elements of the \(\SO3\) subgroup of \(\O3\). This method is equivalent to escnn.group.SO3.grid(), but the \(\SO3\) elements will be embedded in \(\O3\).

Parameters

• type (str) – string identifying the type of samples

• *args – arguments specific for the type of samples chosen

• adj (GroupElement, optional) – optionally, apply an adjoint transform to the sampled elements.

• parametrization (str, optional) –

• **kwargs – arguments specific for the type of samples chosen

Returns

a list of group elements

sphere_grid(type, *args, adj=None, **kwargs)

Method which builds different collections of points over the sphere.

Here, a sphere is interpreted as the quotient space \(\O3 / \O2\) (where \(\O2\) is the “cone” subgroup identified by the id `('cone', -1)`). The list returned by this method contains instances of GroupElement. These are elements of O3 and should be interpreted as representatives of cosets in \(\O3 / \O2\).

Depending on the value of type, the method accept a different set of parameters using the args and the kwargs arguments:

• type = "rand". Generate N random uniformly distributed samples over the sphere. The method accepts an integer N and, optionally, a random seed seed (or an instance of numpy.random.RandomState).

• type = "thomson". Generate N samples distributed (approximately) uniformly over the sphere. The samples are obtained with a numerical method which tries to minimize a potential energy depending on the relative distance between the points. The first call of this method for a particular value of N might be slow due to this numerical method. However, the resulting set of points is cached on disk such that following calls will return the same result instantly.

• type = "thomson_cube". Generate 24*N samples with perfect cubic (octahedral) symmetry, distributed (approximately) uniformly over the shere. The samples are obtained with a numerical method which tries to minimize a potential energy depending on the relative distance between the points. The first call of this method for a particular value of N might be slow due to this numerical method. However, the resulting set of points is cached on disk such that following calls will return the same result instantly.

• type = "ico", "cube", "tetra". Return the orbit of the point \((0, 0, 1)\) under the action of the Icosahedral, Octahedral or Tetrahedral group. The resulting samples correspond to the corners, edges or faces of a Platonic solid.

Todo

add more types to support vertices, edges and faces for all solids. Currently, "ico" returns the centers of the 30 edges while "cube" returns the centers of its 6 faces

Warning

The naming convention might change in future to support faces/edges/vertices of the solids

Note

type = "tetra" does not have inversion symmetry but mirror symmetries (see Symmetries of the Tetrahedron)

• type = "healpix". Generates about N points using the HEAPlix grid on the sphere.

• type = "fibonacci". Generates N points using the Fibonacci grid on the sphere.

• type = "longlat". Generates an N by M grid over the sphere in the longitude (N) - latitude (M) coordinates.

Parameters

• type (str) – string identifying the type of samples

• *args – arguments specific for the type of samples chosen

• adj (GroupElement, optional) – optionally, apply an adjoint transform to the sampled elements.

• **kwargs – arguments specific for the type of samples chosen

Returns

a list of group elements

testing_elements(n=3)

A finite number of group elements to use for testing.

standard_representation()

Standard representation of \(\O3\) as 3x3 rotation matrices

bl_regular_representation(L)

Band-Limited regular representation up to frequency L (included).

Parameters

L (int) – max frequency

bl_quotient_representation(L, subgroup_id)

Band-Limited quotient representation up to frequency L (included).

The quotient representation corresponds to the action of the current group \(G\) on functions over the homogeneous space \(G/H\), where \(H\) is the subgroup of \(G\) identified by subgroup_id.

Parameters

• L (int) – max frequency

• subgroup_id – id identifying the subgroup H.

bl_sphere_representation(L)

Representation of \(\O3\) acting on functions on the sphere band-limited representation up to frequency L (included).

Parameters

L (int) – max frequency

bl_irreps(L)

Returns a list containing the id of all irreps of (rotational) frequency smaller or equal to L. This method is useful to easily specify the irreps to be used to instantiate certain objects, e.g. the Fourier based non-linearity FourierPointwise.

irrep(j, l)

Build the irrep with reflection and rotation frequencies \(j\) (reflection) and \(l\) (rotation) of the current group.

Parameters

• j (int) – the frequency of the reflection in the irrep

• l (int) – the frequency of the rotations in the irrep

Returns

the corresponding irrep

Icosahedral Group

class Icosahedral

Bases: escnn.group.group.Group

Subgroup Structure:

id[0]	id[1]	subgroup
‘ico’		The Icosahedral \(I\) group itself
‘tetra’		Tetrahedral \(T\) subgroup
False	N = 1, 2, 3, 5	\(C_N\) of N discrete planar rotations
True	N = 2, 3, 5	dihedral \(D_N\) subgroup of N discrete planar rotations and out-of-plane \(\pi\) rotation
True	1	equivalent to (False, 2, adj)

testing_elements()

A finite number of group elements to use for testing.

property standard_representation: escnn.group.representation.Representation

Restriction of the standard representation of SO(3) as 3x3 rotation matrices

bl_irreps(L)

Returns a list containing the id of all irreps of frequency smaller or equal to L. This method is useful to easily specify the irreps to be used to instantiate certain objects, e.g. the Fourier based non-linearity FourierPointwise.

bl_regular_representation(L)

Band-Limited regular representation up to frequency L (included).

Parameters

L (int) – max frequency

irrep(l)

Build the irrep of \(I\) identified by the non-negative integer \(l\). For \(l = 0, 1, 2\), the irrep is equivalent to the Wigner D matrix of the same frequency \(l\). For \(l=3\), the 7-dimensional Wigner D matrix is decomposed in a 3-dimensional and a 4-dimensional irrep, here identified respectively by \(l=3\) and \(l=4\).

Parameters

l (int) – identifier of the irrep

Returns

the corresponding irrep

Octahedral Group

class Octahedral

Bases: escnn.group.group.Group

Subgroup Structure:

id[0]	id[1]	subgroup
‘octa’		The Octahedral \(O\) group itself
‘tetra’		Tetrahedral \(T\) subgroup
False	N = 1, 2, 3, 4	\(C_N\) of N discrete planar rotations
True	N = 2, 3, 4	dihedral \(D_N\) subgroup of N discrete planar rotations and out-of-plane \(\pi\) rotation
True	1	equivalent to (False, 2, adj)

testing_elements()

A finite number of group elements to use for testing.

property standard_representation: escnn.group.representation.Representation

Restriction of the standard representation of SO(3) as 3x3 rotation matrices

irrep(l)

Build the irrep of \(O\) identified by the integer \(l\). For \(l = 0, 1\), the irrep is equivalent to the Wigner D matrix of the same frequency \(l\). For \(l=2\), the 5-dimensional Wigner D matrix is decomposed in a 3-dimensional and a 2-dimensional irreps, here identified respectively by \(l=-1\) and \(l=2\). For \(l=3\), the 7-dimensional Wigner D matrix is decomposed in a 1-dimensional irrep and the two previous 3-dimensional irreps, here identified respectively by \(l=3\) and \(l=1, -1\).

Parameters

l (int) – identifier of the irrep

Returns

the corresponding irrep

Direct Product Group

class DirectProductGroup(G1, G2, name=None, **groups_keys)

Bases: escnn.group.group.Group

Class defining the direct product of two groups.

Warning

This class should not be directly instantiated to ensure caching is performed correclty. You should instead use the function direct_product().

Warning

This class does not support all possible subgroups of the direct product! For \(G = G_1 \times G_2\), only subgroups of the form \(H = H_1 \times H_2\) with \(H_1 < G_1\) and \(H_2 < G_2\) are supported.

A subgroup id is a tuple containing a pair (id1, id2), where id1 identifies a subgroup of \(G_1\) while id2 identifies a subgroup of \(G_2\). See the documentation of the two groups used for more details about their subgroup structures.

In case either \(H_1\) or \(H_2\) is the trivial subgroup (containing only the identity), the subgroup returned is just an instance of the other one and not of DirectProductGroup.

Parameters

• G1 (Group) – first group

• G2 (Group) – second group

• name (str, optional) – name assigned to the resulting group

• groups_keys – additional keywords argument used for identifying the groups and perform caching

Variables

• ~.G1 (Group) – the first group

• ~.G2 (Group) – the second group

property subgroup_trivial_id

The subgroup id associated with the trivial subgroup containing only the identity element \({e}\). The id can be used in the method subgroup() to generate the subgroup.

property subgroup_self_id

The subgroup id associated with the group itself. The id can be used in the method subgroup() to generate the subgroup.

property subgroup1_id

The subgroup id associated with \(G1\).

property subgroup2_id

The subgroup id associated with \(G2\).

grid(type=None, N=None, **kwargs)

Todo

Write documentation

if type = “rand”, generates N random samples otherwise split the keywords between the two groups (check if they start with “G1_” or “G2_”) and generate the direct product of the two sets

property trivial_representation: escnn.group.irrep.IrreducibleRepresentation

Builds the trivial representation of the group. The trivial representation is a 1-dimensional representation which maps any element to 1, i.e. \(\forall g \in G,\ \rho(g) = 1\).

Returns

the trivial representation of the group

irrep(id1, id2, i=0)

Builds the irreducible representation (IrreducibleRepresentation) of the group which is specified by the input arguments.

See also

Check the documentation of the specific group subclass used for more information on the valid id values.

Parameters

*id – parameters identifying the specific irrep.

Returns

the irrep built

testing_elements()

A finite number of group elements to use for testing.

Double Group

class DoubleGroup(G, name=None, **group_keys)

Bases: escnn.group.directproduct.DirectProductGroup

Class defining the direct product of a group with itself.

This is a special case (a subclass) of DirectProductGroup. DirectProductGroup can not automatically support all possible subgroups and, in particular, it does not support the diagonal subgroup of \(G \times G\) which is isomorphic to \(G\). This subclass supports this special subgroup, which is identified by the id “diagonal”. See also subgroup_diagonal_id().

Warning

This class should not be directly instantiated to ensure caching is performed correclty. You should instead use the function double_group().

Warning

This class does not support all possible subgroups of the direct product! If \(G = G_1 \times G_1\), only the diagonal subgroup isomorphic to \(G_1\) and the subgroups of the form \(H = H_1 \times H_2\) with \(H_1 < G_1\) and \(H_2 < G_2\) are supported.

A subgroup id is a tuple containing a pair (id1, id2), where id1 identifies a subgroup of \(G_1\) while id2 identifies a subgroup of \(G_2\). See the documentation of the two groups used for more details about their subgroup structures.

In case either \(H_1\) or \(H_2\) is the trivial subgroup (containing only the identity), the subgroup returned is just an instance of the other one and not of DirectProductGroup.

Parameters

• G1 (Group) – first group

• G2 (Group) – second group

• name (str, optional) – name assigned to the resulting group

• groups_keys – additional keywords argument used for identifying the groups and perform caching

Variables

• ~.G1 (Group) – the first group

• ~.G2 (Group) – the second group

property subgroup_diagonal_id

The subgroup id associated with the diagonal group. This is the subgroup containing elements in the form \((g, g)\) for \(g \in G\) and is isomorphic to \(G\) itself. The id can be used in the method subgroup() to generate the subgroup.

Homogeneous Space

class HomSpace(G, sgid)

Bases: object

Class defining an homogeneous space, i.e. the quotient space \(X \cong G / H\) generated by a group \(G\) and a subgroup \(H<G\), called the stabilizer subgroup.

As a quotient space, the homogeneous space is defined as the set

\[X \cong G / H = \{gH \ | g \in G \}\]

where \(gH = \{gh | h \in H\}\) is a coset.

A classical example is given by the sphere \(S^2\), which can be interpreted as the quotient space \(S^2 \cong \SO3 / \SO2\), where \(\SO3\) is the group of all 3D rotations and \(\SO2\) here represents the subgroup of all planar rotations around the Z axis.

This class is useful to generate bases for the space of functions or vector fields (Mackey functions) over the homogeneous space \(X\cong G / H\).

Parameters

• G (Group) – the symmetry group of the space

• sgid (tuple) – the id of the stabilizer subgroup

basis(g, rho, psi)

Let rho be an irrep of \(G\) and psi an irrep of \(H\). This method generates a basis for the subspace of psi-vector fields over \(X\cong G/H\) which transforms under rho and samples its elements on the input \(g \in G\).

Note

Note that a psi-vector field \(f\) is interpreted as a Mackey function, i.e. as a map \(f: G \to \R^{\text{dim}_\psi}\), rather than \(f: X \to \R^{\text{dim}_\psi}\). Indeed, this function takes an element \(g\in G\) in input. This function can be composed with a choice of section \(\gamma: X \to G\) to obtain a vector field over X.

Let \(m\) be the multiplicity of \(\rho\), i.e. the number of subspaces which transform according to rho and \(\text{dim}_\rho\) the dimensionality of the \(G\)-irrep rho, Then, the space is \(\text{dim}_\rho \times m\) dimensional and this method generates \(\text{dim}_\rho \times m\) basis functions over \(G\).

However, this method returns an array of shape \(\text{dim}_\rho \times m \times \text{dim}_\psi\), where \(\text{dim}_\psi\) is the dimensionality of the \(H\)-irrep psi. Any slice along the last dimension of size \(\text{dim}_\psi\), returns a valid \(\text{dim}_\rho \times m\) dimensional basis.

The redundant elements along the last dimension can be used to express the \(H\)-equivariance property of the Mackey functions in a convenient way. A Mackey function \(f\) satisfies the following constraint

\[f(g h) = \psi(h^{-1}) f(g)\]

In the basis generated by this method, this action translates in the following property. A left multiplication by \(\rho(ghg^{-1})\) along the first dimension is equivalent to a right multiplication by \(\psi(h)\) along the last dimension. In other words:

B = self.basis(g, rho, psi)
Bh = np.einsum('ijp,pq->ijq', B, psi(h))
hB = np.einsum('oi,ijp->ojp', rho(g) @ rho.restrict(self.sgid)(h) @ rho(g).T, B)
assert np.allclose(Bh, hB)

Parameters

• g (GroupElement) – the group element where to sample the elements of the basis

• rho (IrreducibleRepresentation) – an irrep of G (or its id)

• psi (IrreducibleRepresentation) – an irrep of H (or its id)

Returns

an array of shape \(\text{dim}_\rho \times m \times \text{dim}_\psi\) representing the basis elements sampled on g

dimension_basis(rho, psi)

Return the tuple \((\text{dim}_\rho, m, \text{dim}_\psi)\), i.e. the shape of the array returned by basis().

Parameters

• rho (IrreducibleRepresentation) – an irrep of G (or its id)

• psi (IrreducibleRepresentation) – an irrep of H (or its id)

scalar_basis(g, rho)

Let rho be an irrep of \(G\). This method generates a basis for the subspace of scalar fields over \(X\cong G/H\) which transforms under rho and samples its elements on the input \(g \in G\).

Note

Note that a scalar field \(f\) is interpreted as a Mackey function, i.e. as a map \(f: G \to \R\), rather than \(f: X \to \R\). Indeed, this function takes an element \(g\in G\) in input. Since this function is constant along each coset \(gH\), it can be composed with a choice of section \(\gamma: X \to G\) to obtain a scalar field over X.

Let \(m\) be the multiplicity of \(\rho\), i.e. the number of subspaces which transform according to rho and \(\text{dim}_\rho\) the dimensionality of the \(G\)-irrep rho, Then, the space is \(\text{dim}_\rho \times m\) dimensional and this method generates \(\text{dim}_\rho \times m\) basis functions over \(G\).

See also

This method is equivalent to escnn.group.HomSpace.basis() with psi = H.trivial_representation and flattening the last dimensionsion of the returned array (since the trivial representation is one dimensional).

Parameters

• g (GroupElement) – the group element where to sample the elements of the basis

• rho (IrreducibleRepresentation) – an irrep of G (or its id)

Returns

an array of shape \(\text{dim}_\rho \times m\) representing the basis elements sampled on g

induced_representation(psi=None, irreps=None, name=None)

Representation acting on the finite dimensional invariant subspace of the induced representation containing only the irreps passed in input. The induced representation is expressed in the spectral basis, i.e. as a direct sum of irreps.

The optional parameter name is also used for caching purpose. Consecutive calls of this method using the same name will ignore the arguments psi and irreps and return the same instance of representation.

Note

If irreps does not contain sufficiently many irreps, the space might be 0-dimensional. In this case, this method returns None.

complete_basis(g, psi=None, irreps=None, name=None)

Let psi an irrep of \(H\). This method generates a basis for a subspace of psi-vector fields over \(X\cong G/H\) and samples its elements on the input \(g \in G\). In particular, the method consider the union of all subspaces according to any irrep \(\rho\) of \(G\) in the input list irreps.

The parameters psi, irreps and name are used to construct the corresponding representation by using the method induced_representation(). See that method’s documentation. In particular, consecutive calls of this method with the same name parameter ignores the other two arguments and use the same cached representation.

Note

If irreps does not contain sufficiently many irreps, the space might be 0-dimensional. In this case, this method returns an empty array with shape 0.

See also

This method is equivalent to escnn.group.HomSpace.basis(), called with rho being each irrep in irreps. The resulting arrays are then properly reshaped and stacked.

Parameters

• g (GroupElement) – the group element where to sample the elements of the basis

• psi (IrreducibleRepresentation) – an irrep of H (or its id)

• irreps (list) – a list of irreps of G

• name (str) – name of the induced representation of psi (used for caching)

Returns

an array of size equal to the size of the representation generated by induced_representation() using the same arguments.

Representations

Representation

class Representation(group, name, irreps, change_of_basis, supported_nonlinearities=[], representation=None, character=None, change_of_basis_inv=None, **kwargs)

Class used to describe a group representation.

A (real) representation \(\rho\) of a group \(G\) on a vector space \(V=\mathbb{R}^n\) is a map (a homomorphism) from the group elements to invertible matrices of shape \(n \times n\), i.e.:

\[\rho : G \to \GL{V}\]

such that the group composition is modeled by a matrix multiplication:

\[\rho(g_1 g_2) = \rho(g_1) \rho(g_2) \qquad \forall \ g_1, g_2 \in G \ .\]

Any representation (of a compact group) can be decomposed into the direct sum of smaller, irreducible representations (irreps) of the group up to a change of basis:

\[\forall \ g \in G, \ \rho(g) = Q \left( \bigoplus\nolimits_{i \in I} \psi_i(g) \right) Q^{-1} \ .\]

Here \(I\) is an index set over the irreps of the group \(G\) which are contained in the representation \(\rho\).

This property enables one to study a representation by its irreps and it is used here to work with arbitrary representations.

escnn.group.Representation.change_of_basis contains the change of basis matrix \(Q\) while escnn.group.Representation.irreps is an ordered list containing the names of the irreps \(\psi_i\) indexed by the index set \(I\).

A Representation instance can be used to describe a feature field in a feature map. It is the building block to build the representation of a feature map, by “stacking” multiple representations (taking their direct sum).

Note

In most of the cases, it should not be necessary to manually instantiate this class. Indeed, the user can build the most common representations or some custom representations via the following methods and functions:

• escnn.group.Group.irrep(),

• escnn.group.Group.regular_representation(),

• escnn.group.Group.quotient_representation(),

• escnn.group.Group.induced_representation(),

• escnn.group.Group.restrict_representation(),

• escnn.group.Representation.tensor(),

• escnn.group.directsum(),

• escnn.group.change_basis()

Additionally, the direct sum of two representations can be quickly generated using the binary operator +, see __add__().

If representation is None (default), it is automatically inferred by evaluating each irrep, stacking their results (through direct sum) and then applying the changes of basis. Warning: the representation of an element is built at run-time every time this object is called (through __call__), so this approach might become computationally expensive with large representations.

Analogously, if the character of the representation is None (default), it is automatically inferred evaluating representation and computing its trace.

Note

It is assumed that both representation and character expect input group elements in the default parametrization of group, i.e. escnn.group.Group.PARAM.

Todo

improve the interface for “supported non-linearities” and write somewhere the available options

Parameters

• group (Group) – the group to be represented.

• name (str) – an identification name for this representation.

• irreps (list) – a list of irreps’ ids. Each id is a tuple representing one of the irreps of the group (see escnn.group.Group.irreps and escnn.group.IrreducibleRepresentation.id).

• change_of_basis (ndarray, optional) – the matrix which transforms the direct sum of the irreps in this representation. By default (None), the identity is assumed.

• supported_nonlinearities (list or set, optional) – a list or set of nonlinearity types supported by this representation.

• representation (dict or callable, optional) – a callable implementing this representation or a dict mapping each group element to its representation.

• character (callable or dict, optional) – a callable returning the character of this representation for an input element or a dict mapping each group element to its character.

• change_of_basis_inv (ndarray, optional) – the inverse of the change_of_basis matrix; if not provided (None), it is computed from change_of_basis.

• **kwargs – custom attributes the user can set and, then, access from the dictionary in escnn.group.Representation.attributes

Variables

• ~.group (Group) – The group which is being represented.

• ~.name (str) – A string identifying this representation.

• ~.size (int) – Dimensionality of the vector space of this representation. In practice, this is the size of the matrices this representation maps the group elements to.

• ~.change_of_basis (ndarray) – Change of basis matrix for the irreps decomposition.

• ~.change_of_basis_inv (ndarray) – Inverse of the change of basis matrix for the irreps decomposition.

• ~.representation (callable) – Method implementing the map from group elements to their representation matrix.

• ~.supported_nonlinearities (set) – A set of strings identifying the non linearities types supported by this representation.

• ~.irreps (list) – List of irreps into which this representation decomposes.

• ~.attributes (dict) – Custom attributes set when creating the instance of this class.

• ~.irreducible (bool) – Whether this is an irreducible representation or not (i.e. if it can’t be decomposed into further invariant subspaces).

character(e)

The character of a finite-dimensional real representation is a function mapping a group element to the trace of its representation:

\[\chi_\rho: G \to \mathbb{C}, \ \ g \mapsto \chi_\rho(g) := \operatorname{tr}(\rho(g))\]

It is useful to perform the irreps decomposition of a representation using Character Theory.

Parameters

e (GroupElement) – an element of the group of this representation

Returns

the character of the element

is_trivial()

Whether this representation is trivial or not.

Returns

if the representation is trivial

contains_trivial()

Whether this representation contains the trivial representation among its irreps. This is an alias for:

any(self.group.irreps[irr].is_trivial() for irr in self.irreps)

Returns

if it contains the trivial representation

restrict(id)

Restrict the current representation to the subgroup identified by id. Check the documentation of the subgroup() method in the underlying group to see the available subgroups and accepted ids.

Note

This operation is cached. Multiple calls using the same subgroup id will return the same instance instead of computing a new restriction.

Parameters

id – identifier of the subgroup

Returns

the restricted representation

__call__(element)

An instance of this class can be called and it implements the mapping from an element of a group to its representation.

This is equivalent to calling escnn.group.Representation.representation(), though __call__ first checks element is a valid input (i.e. an element of the group). It is recommended to use this call.

Parameters

element (GroupElement) – an element of the group

Returns

A matrix representing the input element

__add__(other)

Compute the direct sum of two representations of a group.

The two representations need to belong to the same group.

Parameters

other (Representation) – another representation

Returns

the direct sum

tensor(other)

Compute the tensor product representation of the current representation and the input representaton.

endomorphism_basis()

Compute a basis for the space of endomorphism of this representation from the endomorphism spaces of the irreps contained in this representation.

Warning

This basis might become quite big for large representations and, therefore, this method might get computationally expensive. In practice, we recommend using this method only to generate the basis for small representations (e.g. for irreps). This basis is generated and stored more efficiently in the escnn.nn package, when parameterizing neural network modules; e.g. see BlocksBasisExpansion.

multiplicity(irrep)

Returns the multiplicity of the irrep in the current representation.

Irreducible Representation

class IrreducibleRepresentation(group, id, name, representation, size, type, supported_nonlinearities, character=None, **kwargs)

Bases: escnn.group.representation.Representation

Describes an “irreducible representation” (irrep). It is a subclass of a Representation.

Irreducible representations are the building blocks into which any other representation decomposes under a change of basis. Indeed, any Representation is internally decomposed into a direct sum of irreps.

Parameters

• group (Group) – the group which is being represented

• id (tuple) – args to generate this irrep using group.irrep(*id)

• name (str) – an identification name for this representation

• representation (dict or callable) – a callable implementing this representation or a dict mapping each group element to its representation.

• size (int) – the size of the vector space where this representation is defined (i.e. the size of the matrices)

• type (str) – type of the irrep. It needs to be one of R, C or H, which represent respectively real, complex and quaternionic types. NOTE: this parameter substitutes the old sum_of_squares_constituents from e2cnn.

• supported_nonlinearities (list) – list of nonlinearitiy types supported by this representation.

• character (callable or dict, optional) – a callable returning the character of this representation for an input element or a dict mapping each group element to its character.

• **kwargs – custom attributes the user can set and, then, access from the dictionary in escnn.group.Representation.attributes

Variables

• ~.id (tuple) – tuple which identifies this irrep; it can be used to generate this irrep as group.irrep(*id)

• ~.sum_of_squares_constituents (int) –

  the sum of the squares of the multiplicities of pairwise distinct irreducible constituents of the character of this representation over a non-splitting field (see Character Orthogonality Theorem over general fields). This attribute is fully determined by the irrep’s type as:

  type	sum_of_squares_constituents
  ’R’	1
  ’C’	2
  ’H’	4

Utility Functions

change_basis(repr, change_of_basis, name, supported_nonlinearities=None)

Build a new representation from an already existing one by applying a change of basis. In other words, if \(\rho(\cdot)\) is the representation and \(Q\) the change of basis in input, the resulting representation will evaluate to \(Q \rho(\cdot) Q^{-1}\).

Notice that the change of basis \(Q\) has to be invertible.

Parameters

• repr (Representation) – the input representation

• change_of_basis (ndarray) – the change of basis to apply

• name (str, optional) – the name to use to identify the new representation

• supported_nonlinearities (list, optional) – a list containing the ids of the supported non-linearities for the new representation

Returns

the new representation

directsum(reprs, change_of_basis=None, name=None)

Compute the direct sum of a list of representations of a group.

The direct sum of two representations is defined as follow:

\[\begin{split}\rho_1(g) \oplus \rho_2(g) = \begin{bmatrix} \rho_1(g) & 0 \\ 0 & \rho_2(g) \end{bmatrix}\end{split}\]

This can be generalized to multiple representations as:

\[\begin{split}\bigoplus_{i=1}^I \rho_i(g) = (\rho_1(g) \oplus (\rho_2(g) \oplus (\rho_3(g) \oplus \dots = \begin{bmatrix} \rho_1(g) & 0 & \dots & 0 \\ 0 & \rho_2(g) & \dots & \vdots \\ \vdots & \vdots & \ddots & 0 \\ 0 & \dots & 0 & \rho_I(g) \\ \end{bmatrix}\end{split}\]

Note

All the input representations need to belong to the same group.

Parameters

• reprs (list) – the list of representations to sum.

• change_of_basis (ndarray, optional) – an invertible square matrix to use as change of basis after computing the direct sum. By default (None), an identity matrix is used, such that only the direct sum is evaluated.

• name (str, optional) – a name for the new representation.

Returns

the direct sum

disentangle(repr)

If possible, disentangle the input representation by decomposing it into the direct sum of smaller representations and a change of basis acting as a permutation matrix.

This method is useful to decompose a feature vector transforming with a complex representation into multiple feature vectors which transform independently with simpler representations.

Note that this method only decomposes a representation by applying a permutation of axes. A more general decomposition using any invertible matrix is possible but is just a decomposition into irreducible representations (see Representation). However, since the choice of change of basis is relevant for the kind of operations which can be performed (e.g. non-linearities), it is often not desirable to discard any change of basis and completely disentangle a representation.

Considering only change of basis matrices which are permutation matrices is sometimes more useful. For instance, the restriction of the regular representation of a group to a subgroup results in a representation containing multiple regular representations of the subgroup (one for each coset). However, depending on how the original representation is built, the restricted representation might not be block-diagonal and, so, the subgroup’s regular representations might not be clearly separated.

For example, this happens when restricting the regular representation of \(\D3\)

\(g\)	\(e\)	\(r\)	\(r^2\)	\(f\)	\(rf\)	\(r^2f\)
\(\rho_\text{reg}^{\D3}(g)\)	\(\begin{bmatrix} 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 \end{bmatrix}\)	\(\begin{bmatrix} 0 & 0 & 1 & 0 & 0 & 0 \\ 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 \\ 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 1 & 0 \end{bmatrix}\)	\(\begin{bmatrix} 0 & 1 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 \\ 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 \\ 0 & 0 & 0 & 1 & 0 & 0 \end{bmatrix}\)	\(\begin{bmatrix} 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 \\ 0 & 0 & 0 & 0 & 1 & 0 \\ 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 \end{bmatrix}\)	\(\begin{bmatrix} 0 & 0 & 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 \\ 0 & 1 & 0 & 0 & 0 & 0 \\ 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 \end{bmatrix}\)	\(\begin{bmatrix} 0 & 0 & 0 & 0 & 0 & 1 \\ 0 & 0 & 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 \\ 1 & 0 & 0 & 0 & 0 & 0 \end{bmatrix}\)

to the reflection group \(\C2\)

\(g\)	\(e\)	\(f\)
\(\Res{\C2}{\D3} \rho_\text{reg}^{\D3}(g)\)	\(\begin{bmatrix} 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 \end{bmatrix}\)	\(\begin{bmatrix} 0 & 0 & 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 1 \\ 0 & 0 & 0 & 0 & 1 & 0 \\ 1 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 & 0 & 0 \end{bmatrix}\)

Indeed, in \(\Res{\C2}{\D3} \rho_\text{reg}^{\D3}(g)\) the three pairs of entries (1, 4), (2, 6) and (3, 5) never mix with each other but only permute internally. Moreover, each pair transform according to the regular representation of \(\C2\). Through a permutation of the entries, it is possible to make all the entries belonging to the same pair contiguous. This this reshuffled representation is then equal to \(\rho_\text{reg}^{\C2} \oplus \rho_\text{reg}^{\C2} \oplus \rho_\text{reg}^{\C2}\). Though theoretically equivalent, an implementation of this representation where the entries are contiguous is convenient when computing functions over single fields like batch normalization.

Notice that applying the change of basis returned to the input representation (e.g. through escnn.group.change_basis()) will result in a representation containing the direct sum of the representations in the list returned.

See also

directsum(), change_basis()

Parameters

repr (Representation) – the input representation to disentangle

Returns

a tuple containing

• change of basis: a (square) permutation matrix of the size of the input representation

• representation: the list of representations the input one is decomposed into

homomorphism_space(rho1, rho2)

Compute a basis for the space of homomorphisms from rho1 to rho2.

Warning

This basis might become quite big for large representations and, therefore, this method might get computationally expensive. In practice, we recommend using this method only to generate the basis for small representations (e.g. for irreps). This basis is generated and stored more efficiently in the escnn.nn package, when parameterizing neural network modules; e.g. see BlocksBasisExpansion.

Subpackages

• escnn.group.utils