e2cnn.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 e2cnn.gspaces.

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

Contents

Groups
Representations
- Representation
- Irreducible Representation
Utility Functions
Subpackages

Groups 

Group 

class Group(name, continuous, abelian)[source]

Abstract class defining the interface of a group.

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)
~.identity – Identity element of the group. The identity element \(e\) satisfies the following property \(\forall\ g \in G,\ g \cdot e = e \cdot g= g\)

order()[source]

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

abstract combine(e1, e2)[source]

Method that returns the combination of two group elements according to the group law.

Parameters

e1 – an element of the group
e2 – another element of the group

Returns

the group element \(e_1 \cdot e_2\)

abstract inverse(element)[source]

Method that returns the inverse in the group of the element given as input

Parameters: element – an element of the group
Returns: its inverse

abstract is_element(element)[source]

Check whether the input is an element of this group or not.

Parameters: element – input object to test
Returns: if the input is an element of the group

abstract equal(e1, e2)[source]

Method that checks whether the two inputs are the same element of the group.

This is especially useful for continuous groups with periodicity; see for instance e2cnn.group.SO2.equal().

Parameters

e1 – an element of the group
e2 – another element of the group

Returns

if they are equal

abstract subgroup(id)[source]

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)

property irreps: Dict[str, e2cnn.group.irrep.IrreducibleRepresentation]

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

Returns: a dictionary containing all irreducible representations built

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

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

Returns: a dictionary containing all representations built

abstract property trivial_representation: e2cnn.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)[source]

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

O(2)

class O2(maximum_frequency)[source]

Bases: e2cnn.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).

Parameters: maximum_frequency (int) – the maximum frequency to consider when building the irreps of the group
Variables: ~.reflection – the reflection element \((j, \theta) = (1, 0.)\)

inverse(element)[source]

Return the inverse element of the input element. Given the element \(r_\theta f^j\) as a pair \((j, \theta)\), the method returns \(r_{-\theta}\) (as \((0, -\theta)\)) if \(f = 0\) and \(r_\theta f\) (as \((1, \theta)\)) otherwise.

Parameters: element (tuple) – a group element \(r_{\theta}f^j\) a pair \((j, \theta)\)
Returns: its inverse

combine(e1, e2)[source]

Return the combination of the two input elements. Given two input element \(r_\alpha f^a\) and \(r_\beta f^b\), the method returns \(r_\alpha f^a \cdot r_\beta f^b\).

Parameters

e1 (tuple) – a group element \(r_\alpha f^a\) as a pair \((a, \alpha)\)
e2 (tuple) – another element \(r_\beta f^b\) as a pair \((b, \beta)\)

Returns

their combination \(r_\alpha f^a \cdot r_\beta f^b\)

equal(e1, e2)[source]

Check if the two input values corresponds to the same element.

See e2cnn.group.SO2.equal() for more details.

Parameters

e1 (tuple) – an element
e2 (tuple) – another element

Returns

whether they are the same element

testing_elements()[source]: A finite number of group elements to use for testing.

subgroup(id)[source]

Restrict the current group \(O(2)\) to the subgroup identified by the input id, where id is a tuple \((\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

id (tuple) – the identification 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)

irrep(j, k)[source]

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

SO(2)

class SO2(maximum_frequency)[source]

Bases: e2cnn.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).

Args:
maximum_frequency (int): the maximum frequency to consider when building the irreps of the group

inverse(element)[source]

Return the inverse element of the input element: given an angle, the method returns its opposite

Parameters: element (float) – an angle \(\theta\)
Returns: its opposite \(-\theta \mod 2\pi\)

combine(e1, e2)[source]

Return the sum of the two input elements: given two angles, the method returns their sum

Parameters

e1 (float) – an angle \(\alpha\)
e2 (float) – another angle \(\beta\)

Returns

their sum \((\alpha + \beta) \mod 2\pi\)

equal(e1, e2)[source]

Check if the two input values corresponds to the same element, i.e. the same angle.

The method accounts for a small absolute and relative tollerance and for the cyclicity of the the angles, i.e. the fact that \(0 + \epsilon \simeq 2\pi - \epsilon\) for small \(\epsilon\)

Parameters

e1 (float) – an angle \(\alpha\)
e2 (float) – another angle \(\beta\)

Returns

whether the two angles are the same, i.e. if \(\beta \simeq \alpha \mod 2\pi\)

testing_elements()[source]: A finite number of group elements to use for testing.

subgroup(id)[source]

Restrict the current group to the cyclic subgroup \(C_M\) with order \(M\) which is generated by \(r_{\frac{2\pi}{M}}\).

The method takes as input the integer \(M\) identifying of the subgroup to build (the order of the subgroup).

Parameters

id (int) – the integer \(M\) identifying 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)

irrep(k)[source]

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

Cyclic Group 

class CyclicGroup(N)[source]

Bases: e2cnn.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}\).

Parameters: N (int) – order of the group

inverse(element)[source]

Return the inverse element \(r^{-j \mod N}\) of the input element \(r^j\), specified by the input integer \(j\) (element)

Parameters: element (int) – a group element \(r^j\)
Returns: its opposite \(r^{-j \mod N}\)

combine(e1, e2)[source]

Return the composition of the two input elements. Given two integers \(a\) and \(b\) representing the elements \(r^a\) and \(r^b\), the method returns the integer \(a + b \mod N\) representing the element \(r^{a + b \mod N}\).

Parameters

e1 (int) – a group element \(r^a\)
e2 (int) – another group element \(r^a\)

Returns

their composition \(r^{a+b \mod N}\)

equal(e1, e2)[source]

Check if the two input values corresponds to the same element.

Parameters

e1 (int) – an element
e2 (int) – another element

Returns

whether they are the same element

testing_elements()[source]: A finite number of group elements to use for testing.

subgroup(id)[source]

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

The method takes as input the integer \(M\) identifying of the subgroup to build (the order of the subgroup)

Parameters

id (int) – the integer \(M\) identifying 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)

irrep(k)[source]

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

Dihedral Group 

class DihedralGroup(N)[source]

Bases: e2cnn.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\}\).

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)

inverse(element)[source]

Returns the inverse element of the input element. Given the element \(r^kf^j\) as a pair \((j, k)\), the method returns \(r^{-k}\) (as \((0, -k)\)) if \(f = 0\) and \(fr^{-k}=r^kf\) (as \((1, k)\)) otherwise.

Parameters: element (tuple) – a group element \(r^kf^j\) as a pair \((j, k)\)
Returns: its inverse

combine(e1, e2)[source]

Return the combination of the two input elements. Given two input element \(r^af^b\) and \(r^cf^d\), the method returns \(r^af^b \cdot r^cf^d\).

Parameters

e1 (tuple) – a group element \(r^af^b\) as a pair \((b, a)\)
e2 (tuple) – another element \(r^cf^d\) as a pair \((d, c)\)

Returns

their combination \(r^af^b \cdot r^cf^d\)

equal(e1, e2)[source]

Check if the two input values corresponds to the same element.

Parameters

e1 (tuple) – an element
e2 (tuple) – another element

Returns

whether they are the same element

testing_elements()[source]: A finite number of group elements to use for testing.

subgroup(id)[source]

Restrict the current group \(D_{2N}\) to the subgroup identified by the input id, where id is a tuple \((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

id (tuple) – the identification 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)

irrep(j, k)[source]

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

Factory Functions 

so2_group(maximum_frequency=10)[source]

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 e2cnn.group.SO2.irrep() (see the method’s documentation).

You should use this factory function to build an instance of e2cnn.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 e2cnn.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)\)

o2_group(maximum_frequency=10)[source]

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 e2cnn.group.O2.irrep() (see the method’s documentation).

You should use this factory function to build an instance of e2cnn.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 e2cnn.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(N)[source]

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 e2cnn.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(N)[source]

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 e2cnn.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()[source]

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

Representations 

Representation 

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

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.

e2cnn.group.Representation.change_of_basis contains the change of basis matrix \(Q\) while e2cnn.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:

e2cnn.group.Group.irrep(),
e2cnn.group.Group.regular_representation(),
e2cnn.group.Group.quotient_representation(),
e2cnn.group.Group.induced_representation(),
e2cnn.group.Group.restrict_representation(),
e2cnn.group.directsum(),
e2cnn.group.change_basis()

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__) and 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.

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 strings. Each string represents the name of one of the irreps of the group (see e2cnn.group.Group.irreps).
change_of_basis (ndarray) – the matrix which transforms the direct sum of the irreps in this representation.
supported_nonlinearities (list or set) – a list or set of nonlinearity types supported by this representation.
representation (dict or callable, optional) – a callable implementing this representation or a dictionary mapping each of the group’s elements to its representation.
character (callable or dict, optional) – a callable returning the character of this representation for an input element or a dictionary mapping each 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 e2cnn.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)[source]

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 – an element of the group of this representation
Returns: the character of the element

is_trivial()[source]

Whether this representation is trivial or not.

Returns: if the representation is trivial

contains_trivial()[source]

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)[source]

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.

Parameters: id – identifier of the subgroup
Returns: the restricted representation

__call__(element)[source]

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 e2cnn.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 – an element of the group
Returns: A matrix representing the input element

__add__(other)[source]

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

Irreducible Representation 

class IrreducibleRepresentation(group, name, representation, size, sum_of_squares_constituents, supported_nonlinearities, character=None, **kwargs)[source]

Bases: e2cnn.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
name (str) – an identification name for this representation
representation (dict or callable) – a callable implementing this representation or a dictionary mapping each of the group’s elements to its representation.
size (int) – the size of the vector space where this representation is defined (i.e. the size of the matrices)
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
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 dictionary mapping each element to its character.
**kwargs – custom attributes the user can set and, then, access from the dictionary in e2cnn.group.Representation.attributes

Variables

~IrreducibleRepresentation.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)

Utility Functions 

change_basis(repr, change_of_basis, name, supported_nonlinearities=None)[source]

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)[source]

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)[source]

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 transforms 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 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 e2cnn.group.change_basis()) will result in a representation containing the direct sum of the representations in the list returned.

Subpackages 

e2cnn.group.utils