escnn.gspaces

This subpackage implements G-spaces as a user interface for defining spaces and their symmetries. The user typically instantiates a subclass of GSpace to specify the symmetries considered and uses it to instantiate equivariant neural network modules (see escnn.nn).

Generally, the user does not need to manually instantiate GSpace or its subclasses. Instead, we provide a few factory functions with simpler interfaces which can be used to directly instantiate the most commonly used symmetries.

This subpackage depends on escnn.group and escnn.kernels.

A point \(\bold{v} \in \R^n\) is parametrized using an \((X, Y, Z, \dots)\) convention, i.e. \(\bold{v} = (x, y, z, \dots)^T\). The representation escnn.gspaces.GSpace.basespace_action also assumes this convention.

However, when working with voxel data, the \((\cdots, -Z, -Y, X)\) convention is used. That means that, in a feature tensor of shape \((B, C, D_1, D_2, \cdots, D_{n-2}, D_{n-1}, D_n)\), the last dimension is the X axis but the \(i\)-th last dimension is the inverted \(i\)-th axis. Note that this is consistent with 2D images, where a \((-Y, X)\) convention is used.

This is especially relevant when transforming a GeometricTensor or when building convolutional filters in R3Conv which should be equivariant to subgroups of \(\O3\) (e.g. when choosing the rotation axis for rot2dOnR3()).

Note

Note that gspaces describing planar rotational symmetries (e.g. rot2dOnR2(), rot2dOnR3() or flipRot2dOnR2()) have an argument N which can be used to specify a discretization of the continuous rotational symmetry to integer multiples of \(\frac{2\pi}{N}\). However, this is generally not possible in 3D gspaces (e.g. rot3dOnR3()).

The reason why rot3dOnR3() (and similar gspaces) does not have an this argument is that, while in 2D there exists a discrete subgroup of rotations of any order N, this is not the case in 3D. Indeed, in 3D, the only discrete 3D rotational symmetry groups are the symmetries of the few platonic solids (the tetrahedron group, the octahedron group and the icosahedron group).

Recall that the factory functions listed here are just convenient shortcuts to create most gspaces with a simpler interface. Because a discrete rotation group of any order N can be generated in 2D, it is convenient to provide all these groups under the same interface in rot2dOnR2(). Conversely, since there are only a few options in 3D, we provide a different method for each of them (e.g. icoOnR3() or octaOnR3()).

Alternatively, it is always possible to leverage the restrict() method to generate smaller symmetries. For instance, one can build a gspace with all rotational symmetries (\(\SO3\)) with rot3dOnR3() and then restrict it to a particular subgroup (identified by a subgroup id sgid, see Subgroup Structure in SO3) of symmetries. The factory methods above are equivalent to this sequence of operations.

Instead, if you want to leverage a more generic discretisation of \(\SO3\) (or other groups) while trying to preserve the full rotational equivariance, we recommend choosing rot3dOnR3() and discretize the group only when using non-linearities within a neural network. This is done by using Fourier Transform-based non-linearities like FourierPointwise or FourierELU. In this case, the steerable features of a network are interpreted as the Fourier coefficients of a continuous feature over the full \(\SO3\) group (or another group of your choice); inside the non-linearity module, the continuous features are sampled on a finite number N of (uniformly spread) points (via an inverse Fourier Transform) and a non-linearity (like ReLU or ELU) is applied point-wise. Finally, this operation is followed by a (discretized) Fourier Transform to recover the coefficients of the new features. This strategy enables parameterizing convolution layers which are \(\SO3\) equivariant while leveraging an arbitrary discretization of the group when taking non-linearities. Note also that the N points used for discretization don’t have to form a subgroup and, therefore, are not limited to the choice of the platonic symmetry groups anymore. You can generate different grids discretizing \(\SO3\) (as well as other groups) by using the grid() method of each group.

Contents

Factory Methods
Abstract Group Space
Group Action (trivial) on single point
Group Actions on the Plane
Group Actions on the 3D Space

Factory Methods 

(trivial) action on single point 

no_base_space(G)[source]

Build the GSpace of the input group G acting on a single point space.

This simple gspace can be useful to describe the features of a G-equivariant MLP.

Parameters: G (Group) – a group

action on plane 

rot2dOnR2(N=- 1, maximum_frequency=6)[source]

Describes rotation symmetries of the plane \(\R^2\).

If N > 1, the gspace models discrete rotations by angles which are multiple of \(\frac{2\pi}{N}\) (CyclicGroup). Otherwise, if N=-1, the gspace models continuous planar rotations (SO2). In that case the parameter maximum_frequency is required to specify the maximum frequency of the irreps of SO2 (see its documentation for more details)

Parameters

N (int) – number of discrete rotations (integer greater than 1) or -1 for continuous rotations
maximum_frequency (int) – maximum frequency of SO2’s irreps if N = -1

flipRot2dOnR2(N=- 1, maximum_frequency=6, axis=1.5707963267948966)[source]

Describes reflectional and rotational symmetries of the plane \(\R^2\).

Reflections are applied with respect to the line through the origin with an angle axis degrees with respect to the X-axis.

If N > 1, this gspace models reflections and discrete rotations by angles multiple of \(\frac{2\pi}{N}\) (DihedralGroup). Otherwise, if N=-1 (by default), the class models reflections and continuous planar rotations (O2). In that case, the parameter maximum_frequency is required to specify the maximum frequency of the irreps of O2 (see its documentation for more details)

Note

All axes obtained from the axis defined by axis with a rotation in the symmetry group are equivalent. For instance, if N = 4, an axis \(\beta\) is equivalent to the axis \(\beta + \pi/2\). It follows that for N = -1, i.e. in case the symmetry group contains all continuous rotations, any reflection axis is theoretically equivalent. In practice, though, a basis for equivariant convolutional filter sampled on a grid is affected by the specific choice of the axis. In general, choosing an axis aligned with the grid (an horizontal or a vertical axis, i.e. \(0\) or \(\pi/2\)) is suggested.

Parameters

N (int) – number of discrete rotations (integer greater than 1) or -1 for continuous rotations
maximum_frequency (int) – maximum frequency of O2 ‘s irreps if N = -1
axis (float, optional) – the slope of the axis of the flip (in radians)

flip2dOnR2(axis=1.5707963267948966)[source]

Describes reflectional symmetries of the plane \(\R^2\).

Reflections are applied along the line through the origin with an angle axis degrees with respect to the X-axis.

Parameters: axis (float, optional) – the slope of the axis of the reflection (in radians). By default, the vertical axis is used (\(\pi/2\)).

trivialOnR2()[source]: Describes the plane \(\R^2\) without considering any origin-preserving symmetry. This is modeled by choosing trivial fiber group \(\{e\}\).

Note

This models the symmetries of conventional Convolutional Neural Networks which are not equivariant to origin preserving transformations such as rotations and reflections.

action on volume 

flipRot3dOnR3(maximum_frequency=2)[source]

Describes 3D rotation and inversion symmetries in the space \(\R^3\).

Todo

rename to invRot3dOnR3?

Parameters: maximum_frequency (int) – maximum frequency of O3’s irreps

rot3dOnR3(maximum_frequency=2)[source]

Describes 3D rotation symmetries in the space \(\R^3\).

Parameters: maximum_frequency (int) – maximum frequency of SO3’s irreps

fullIcoOnR3()[source]

icoOnR3()[source]: Describes 3D rotation symmetries of a Icosahedron (or Dodecahedron) in the space \(\R^3\)

fullOctaOnR3()[source]

octaOnR3()[source]: Describes 3D rotation symmetries of an Octahedron (or Cube) in the space \(\R^3\)

dihedralOnR3(n=- 1, axis=1.5707963267948966, adjoint=None, maximum_frequency=2)[source]

Describes 2D rotation symmetries along the \(Z\) axis in the space \(\R^3\) and \(\pi\) rotations along the axis in the \(XY\) plane, i.e. the rotations inside the plane \(XY\) and reflections around the axis.

The adjoint parameter can be a GroupElement of O3. If not None (which is equivalent to the identity), this specifies another \(\SO2\) subgroup of \(\O3\) which is adjoint to the \(\SO2\) subgroup of rotations around the \(Z\) axis. If adjoint is the group element \(A \in \O3\), the new subgroup would then represent rotations around the axis \(A^{-1} \cdot (0, 0, 1)^T\).

If N > 1, the gspace models discrete rotations by angles which are multiple of \(\frac{2\pi}{N}\) (CyclicGroup). Otherwise, if N=-1, the gspace models continuous planar rotations (SO2). In that case the parameter maximum_frequency is required to specify the maximum frequency of the irreps of SO2 (see its documentation for more details)

Parameters

N (int) – number of discrete rotations (integer greater than 1) or -1 for continuous rotations
adjoint (GroupElement, optional) – an element of \(\O3\)
maximum_frequency (int) – maximum frequency of SO2’s irreps if N = -1

rot2dOnR3(n=- 1, adjoint=None, maximum_frequency=2)[source]

Describes 2D rotation symmetries along the \(Z\) axis in the space \(\R^3\), i.e. the rotations inside the plane \(XY\).

adjoint is a GroupElement of O3. If not None (which is equivalent to the identity), this specifies another \(\SO2\) subgroup of \(\O3\) which is adjoint to the \(\SO2\) subgroup of rotations around the \(Z\) axis. If adjoint is the group element \(A \in \O3\), the new subgroup would then represent rotations around the axis \(A^{-1} \cdot (0, 0, 1)^T\).

If N > 1, the gspace models discrete rotations by angles which are multiple of \(\frac{2\pi}{N}\) (CyclicGroup). Otherwise, if N=-1, the gspace models continuous planar rotations (SO2). In that case the parameter maximum_frequency is required to specify the maximum frequency of the irreps of SO2 (see its documentation for more details)

Parameters

N (int) – number of discrete rotations (integer greater than 1) or -1 for continuous rotations
adjoint (GroupElement, optional) – an element of \(\O3\)
maximum_frequency (int) – maximum frequency of SO2’s irreps if N = -1

conicalOnR3(n=- 1, axis=1.5707963267948966, adjoint=None, maximum_frequency=2)[source]

fullCylindricalOnR3(n=- 1, axis=1.5707963267948966, adjoint=None, maximum_frequency=2)[source]

cylindricalOnR3(n=- 1, adjoint=None, maximum_frequency=2)[source]

mirOnR3(axis=1.5707963267948966, adjoint=None)[source]: Describes mirroring with respect to a plane in the space \(\R^3\).

Todo

Document what axis and adjoint describe or change parameters, just getting a \(\bold{v} \in \R^3\) vector in input which specifies the mirroring axis.

invOnR3()[source]

Describes the inversion symmetry of the space \(\R^3\).

An inversion flips the sign of all coordinates, mapping a vector \(\bold{v} \in \R^3\) to \(-\bold{v}\).

trivialOnR3()[source]: Describes the space \(\R^3\) without considering any origin-preserving symmetry. This is modeled by choosing trivial fiber group \(\{e\}\).

Note

This models the symmetries of conventional Convolutional Neural Networks which are not equivariant to origin preserving transformations such as rotations and reflections.

Abstract Group Space 

class GSpace(fibergroup, dimensionality, name)[source]

Abstract class for G-spaces.

A GSpace describes the space where a signal lives (e.g. \(\R^2\) for planar images) and its symmetries (e.g. rotations or reflections). As an Euclidean base space is assumed, a G-space is fully specified by the dimensionality of the space and a choice of origin-preserving symmetry group (fibergroup).

Note

Mathematically, this class describes a Principal Bundle \(\pi : (\R^D, +) \rtimes G \to \mathbb{R}^D, tg \mapsto tG\), with the Euclidean space \(\mathbb{R}^D\) (where \(D\) is the dimensionality) as base space and \(G\) as fiber group (fibergroup). For more details on this interpretation we refer to A General Theory of Equivariant CNNs On Homogeneous Spaces.

Parameters

fibergroup (Group) – the fiber group
dimensionality (int) – the dimensionality of the Euclidean space on which a signal is defined
name (str) – an identification name

Variables

~.fibergroup (Group) – the fiber group
~.dimensionality (int) – the dimensionality of the Euclidean space on which a signal is defined
~.name (str) – an identification name
~.basespace (str) – the name of the space whose symmetries are modeled. It is an Euclidean space \(\R^D\).

type(*representations)[source]: Shortcut to build a FieldType. This is equivalent to FieldType(gspace, representations).

abstract restrict(id)[source]

Build the GSpace associated with the subgroup of the current fiber group identified by the input id. This reduces the level of symmetries of the base space to be considered.

Check the restrict method’s documentation in the non-abstract subclass used for a description of the parameter id.

Parameters

id – id of the subgroup

Returns

a tuple containing

gspace: the restricted gspace

back_map: a function mapping an element of the subgroup to itself in the fiber group of the original space

subgroup_map: a function mapping an element of the fiber group of the original space to itself in the subgroup (returns None if the element is not in the subgroup)

featurefield_action(input, repr, element, order=2)[source]

This method implements the action of the symmetry group on a feature field defined over the basespace of this G-space. It includes both an action over the basespace (e.g. a rotation of the points on the plane) and a transformation of the channels by left-multiplying them with a representation of the fiber group.

The method takes as input a tensor (input), a representation (repr) and an element of the fiber group. The tensor input is the feature field to be transformed and needs to be compatible with this G-space and the representation (i.e. its number of channels equals the size of that representation). element needs to belong to the fiber group: check escnn.group.Group.is_element(). This method returns a transformed tensor through the action of element.

More precisely, given an input tensor, interpreted as an \(c\)-dimensional signal \(f: \R^D \to \mathbb{R}^c\) defined over the base space \(\R^D\), a representation \(\rho: G \to \mathbb{R}^{c \times c}\) of \(G\) and an element \(g \in G\) of the fiber group, the method returns the transformed signal \(f'\) defined as:

\[f'(x) := \rho(g) f(g^{-1} x)\]

Note

Mathematically, this method transforms the input with the induced representation from the input repr (\(\rho\)) of the symmetry group (\(G\)) to the total space (\(P\)), i.e. with \(Ind_{G}^{P} \rho\). For more details on this, see General E(2)-Equivariant Steerable CNNs or A General Theory of Equivariant CNNs On Homogeneous Spaces.

Parameters

input (ndarray) – input tensor
repr (Representation) – representation of the fiber group
element (GroupElement) – element of the fiber group

Returns

the transformed tensor

abstract property basespace_action: escnn.group.representation.Representation

Defines how the fiber group transforms the base space.

More precisely, this method defines how an element \(g \in G\) of the fiber group transforms a point \(x \in X \cong \R^d\) of the base space. This action is defined as a \(d\)-dimensional linear Representation of \(G\).

property irreps: List[escnn.group.irrep.IrreducibleRepresentation]: list containing all the already built irreducible representations of the fiber group of this space.

See also

See escnn.group.Group.irreps for more details

property representations: Dictionary containing all the already built representations of the fiber group of this space.

See also

See escnn.group.Group.representations for more details

property trivial_repr: escnn.group.representation.Representation: The trivial representation of the fiber group of this space.

See also

escnn.group.Group.trivial_representation

irrep(*id)[source]

Builds the irreducible representation (IrreducibleRepresentation) of the fiber group identified by the input arguments.

See also

This method is a wrapper for escnn.group.Group.irrep(). See its documentation for more details. Check the documentation of irrep() of the specific fiber group used for more information on the valid id.

Parameters: *id – parameters identifying the irrep.

property regular_repr: escnn.group.representation.Representation: The regular representation of the fiber group of this space.

See also

escnn.group.Group.regular_representation

quotient_repr(subgroup_id)[source]

Builds the quotient representation of the fiber group of this space with respect to the subgroup identified by subgroup_id.

Check the restrict() method’s documentation in the non-abstract subclass used for a description of the parameter subgroup_id.

See also

See escnn.group.Group.quotient_representation for more details on the representation.

Parameters: subgroup_id – identifier of the subgroup

induced_repr(subgroup_id, repr)[source]

Builds the induced representation of the fiber group of this space from the representation repr of the subgroup identified by subgroup_id.

Check the restrict() method’s documentation in the non-abstract subclass used for a description of the parameter subgroup_id.

See also

See escnn.group.Group.induced_representation for more details on the representation.

Parameters

subgroup_id – identifier of the subgroup
repr (Representation) – the representation of the subgroup to induce

property testing_elements

build_fiber_intertwiner_basis(in_repr, out_repr)[source]

Parameters

in_repr (Representation) – the input representation
out_repr (Representation) – the output representation

Returns

the analytical basis

build_kernel_basis(in_repr, out_repr, sigma, rings, **kwargs)[source]

Builds a basis for the space of the equivariant kernels with respect to the symmetries described by this GSpace.

A kernel \(\kappa\) equivariant to a group \(G\) needs to satisfy the following equivariance constraint:

\[\kappa(gx) = \rho_\text{out}(g) \kappa(x) \rho_\text{in}(g)^{-1} \qquad \forall g \in G, x \in \R^D\]

where \(\rho_\text{in}\) is in_repr while \(\rho_\text{out}\) is out_repr.

Because the equivariance constraints only restrict the angular part of the kernels, any radial profile is permitted. The basis for the radial profile used here contains rings with different radii (rings) associated with (possibly different) widths (sigma). A ring is implemented as a Gaussian function over the radial component, centered at one radius (see also GaussianRadialProfile).

Note

This method is a wrapper for the functions building the bases which are defined in escnn.kernels:

Parameters

in_repr (Representation) – the input representation
out_repr (Representation) – the output representation
sigma (list or float) – parameters controlling the width of each ring of the radial profile. If only one scalar is passed, it is used for all rings
rings (list) – radii of the rings defining the radial profile
**kwargs – Group-specific keywords arguments for _basis_generator method

Returns

an instance of KernelBasis representing the analytical basis

Group Action (trivial) on single point 

class GSpace0D(G)[source]

Bases: escnn.gspaces.gspace.GSpace

restrict(id)[source]

property basespace_action: escnn.group.representation.Representation

build_kernel_basis(in_repr, out_repr, **kwargs)[source]

Parameters

in_repr (Representation) – the input representation
out_repr (Representation) – the output representation
**kwargs – Group-specific keywords arguments for _basis_generator method

Returns

the analytical basis

Group Actions on the Plane 

class GSpace2D(sg_id, maximum_frequency=6)[source]

Bases: escnn.gspaces.gspace.GSpace

A GSpace tha describes the set (or subset) of reflectional and rotational symmetries of the 2D Euclidean Space \(\R^2\). The subset of symmetries is determined by the subgroup of \(\O2\) that is specified by sg_id (check the documentation of escnn.group.O2).

Parameters

sg_id (tuple) – The ID of the subgroup within the fiber group \(\O2\) that determines the reflectional and rotational symmetries to consider. For detailed documentation on the ID of each subgroup, refer to the documentation of escnn.group.O2
maximum_frequency (int) – Maximum frequency of the irreps to pre-instantiate, if the symmetry group (identified by sg_id) contains all continuous rotations.

Note

A point \(\bold{v} \in \R^2\) is parametrized using an \((X, Y)\) convention, i.e. \(\bold{v} = (x, y)^T\). The representation escnn.gspaces.GSpace2D.basespace_action also assumes this convention.

However, when working with data on a pixel grid, the usual \((-Y, X)\) convention is used. That means that, in a 4-dimensional feature tensor of shape (B, C, D1, D2), the last dimension is the X axis while the second last is the (inverted) Y axis. Note that this is consistent with 2D images, where a \((-Y, X)\) convention is used.

restrict(id)[source]

Build the GSpace associated with the subgroup of the current fiber group identified by the input id

Parameters

id (tuple) – the id of the subgroup

Returns

a tuple containing

gspace: the restricted gspace

back_map: a function mapping an element of the subgroup to itself in the fiber group of the original space

subgroup_map: a function mapping an element of the fiber group of the original space to itself in the subgroup (returns None if the element is not in the subgroup)

property rotations_order

property flips_order

property basespace_action: escnn.group.representation.Representation

Group Actions on the 3D Space 

class GSpace3D(sg_id, maximum_frequency=2)[source]

Bases: escnn.gspaces.gspace.GSpace

A GSpace tha describes the set (or subset) of reflectional and rotational symmetries of the 3D Euclidean Space \(\R^3\). The subset of symmetries is determined by the subgroup of \(\O3\) that is specified by sg_id (check the documentation of escnn.group.O3).

Parameters

sg_id (tuple) – The ID of the subgroup within the fiber group \(\O3\) that determines the reflectional and rotational symmetries to consider. For detailed documentation on the ID of each subgroup, refer to the documentation of escnn.group.O3
maximum_frequency (int) – Maximum frequency of the irreps to pre-instantiate, if the symmetry group (identified by sg_id) contains continuous rotations.

Note

A point \(\bold{v} \in \R^3\) is parametrized using an \((X, Y, Z)\) convention, i.e. \(\bold{v} = (x, y, z)^T\). The representation escnn.gspaces.GSpace3D.basespace_action also assumes this convention.

However, when working with voxel data, the \((-Z, -Y, X)\) convention is used. That means that, in a 5-dimensional feature tensor of shape (B, C, D1, D2, D3), the last dimension is the X axis, the second last the (inverted) Y axis and then the (inverted) Z axis. Note that this is consistent with 2D images, where a \((-Y, X)\) convention is used.

This is especially relevant when transforming a GeometricTensor or when building convolutional filters in R3Conv which should be equivariant to subgroups of \(\O3\) (e.g. when choosing the rotation axis for rot2dOnR3()).

restrict(id)[source]

Build the GSpace associated with the subgroup of the current fiber group identified by the input id

Parameters

id (tuple) – the id of the subgroup

Returns

a tuple containing

gspace: the restricted gspace

back_map: a function mapping an element of the subgroup to itself in the fiber group of the original space

subgroup_map: a function mapping an element of the fiber group of the original space to itself in the subgroup (returns None if the element is not in the subgroup)

property basespace_action: escnn.group.representation.Representation