e2cnn.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 instanciate equivariant neural network modules (see e2cnn.nn).

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

Contents

Abstract Group Space
Group Actions on the Plane

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\).

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)[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 e2cnn.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 – element of the fiber group

Returns

the transformed tensor

abstract build_kernel_basis(in_repr, out_repr, **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.

This method relies on the functionalities implemented in e2cnn.kernels and returns an instance of KernelBasis.

Parameters

in_repr (Representation) – the representation associated with the input field
out_repr (Representation) – the representation associated with the output field
**kwargs – additional keyword arguments for the equivariance contraint solver

Returns

a basis for space of equivariant convolutional kernels

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

See also

See e2cnn.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 e2cnn.group.Group.representations for more details

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

See also

e2cnn.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 e2cnn.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: e2cnn.group.representation.Representation: The regular representation of the fiber group of this space.

See also

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

Group Actions on the Plane 

class GeneralOnR2(fibergroup, name)[source]

Bases: e2cnn.gspaces.gspace.GSpace

Abstract class for the G-spaces which define the symmetries of the plane \(\R^2\).

Parameters

fibergroup (Group) – group of origin-preserving symmetries (fiber group)
name (str) – identification name

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^2\]

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

the analytical basis

build_diffop_basis(in_repr, out_repr, max_power, discretization, **kwargs)[source]

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

A \(G\)-equivariant PDO \(D(P)\) for a matrix of polynomials \(P\), mapping between an input field, transforming under \(\rho_\text{in}\) (in_repr), and an output field, transforming under \(\rho_\text{out}\) (out_repr), satisfies the following constraint:

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

for \(G \leq O(d)\).

A complete basis is obtained by combining certain PDOs with powers of the Laplacian operator. max_power describes the maximum power of the Laplacian to use when building the basis.

Note

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

Parameters

in_repr (Representation) – the input representation
out_repr (Representation) – the output representation
max_power (int) – the largest power of the Laplacian that will be used
discretization (DiscretizationArgs) – the parameters specifying a discretization procedure for PDOs
**kwargs – Group-specific keywords arguments for _basis_generator method

Returns

the analytical basis

Reflections and Rotations 

class FlipRot2dOnR2(N=None, maximum_frequency=None, axis=1.5707963267948966, fibergroup=None)[source]

Bases: e2cnn.gspaces.r2.general_r2.GeneralOnR2

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, the class models reflections and discrete rotations by angles multiple of \(\frac{2\pi}{N}\) (DihedralGroup). Otherwise, if N=-1, 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)
fibergroup (Group, optional) – use an already existing instance of the symmetry group. In that case only the parameter axis should be used.

Variables

~.axis (float) – Angle with respect to the horizontal axis which defines the reflection axis.

restrict(id)[source]

Build the GSpace associated with the subgroup of the current fiber group identified by the input id, which 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 (no reflections) or an angle indicating the axis of reflection. If the current fiber group is \(D_N\) (DihedralGroup), then \(M\) needs to divide \(N\) and \(k\) needs to be an integer in \(\{0, \dots, \frac{N}{M}-1\}\). Otherwise, \(M\) can be any positive integer while \(k\) needs to be a real number in \([0, \frac{2\pi}{M}]\).

Valid combinations are:

(None, \(1\)): restrict to no reflection and rotation symmetries
(None, \(M\)): restrict to only the \(M\) rotations generated by \(r_{2\pi/M}\).
(\(0\), \(1\)): restrict to only reflections \(\langle f \rangle\) around the same axis as in the current group
(\(0\), \(M\)): restrict to reflections and \(M\) rotations generated by \(r_{2\pi/M}\) and \(f\)

If the current fiber group is \(D_N\) (an instance of DihedralGroup):

(\(k\), \(M\)): restrict to reflections \(\langle r_{k\frac{2\pi}{N}} f \rangle\) around the axis of the current G-space rotated by \(k\frac{\pi}{N}\) and \(M\) rotations generated by \(r_{2\pi/M}\)

If the current fiber group is \(O(2)\) (an instance of O2):

(\(\theta\), \(M\)): restrict to reflections \(\langle r_{\theta} f \rangle\) around the axis of the current G-space rotated by \(\frac{\theta}{2}\) and \(M\) rotations generated by \(r_{2\pi/M}\)
(None, \(-1\)): restrict to all (continuous) rotations

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)

Rotations 

class Rot2dOnR2(N=None, maximum_frequency=None, fibergroup=None)[source]

Bases: e2cnn.gspaces.r2.general_r2.GeneralOnR2

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

If N > 1, the class models discrete rotations by angles which are multiple of \(\frac{2\pi}{N}\) (CyclicGroup). Otherwise, if N=-1, the class 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
fibergroup (Group, optional) – use an already existing instance of the symmetry group. In that case, the other parameters should not be provided.

restrict(id)[source]

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

id is a positive integer \(M\) indicating the number of rotations in the subgroup. If the current fiber group is \(C_N\) (CyclicGroup), then \(M\) needs to divide \(N\). Otherwise, \(M\) can be any positive integer.

Parameters

id (int) – the number \(M\) of rotations in 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)

Reflections 

class Flip2dOnR2(axis=1.5707963267948966, fibergroup=None)[source]

Bases: e2cnn.gspaces.r2.general_r2.GeneralOnR2

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\)).
fibergroup (Group, optional) – use an already existing instance of the symmetry group

Variables

~.axis (float) – Angle with respect to the horizontal axis which defines the reflection axis.

restrict(id)[source]

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

As the reflection group contains only two elements, it has only one subgroup: the trivial group. The only accepted input values are id=1 which returns an instance of TrivialOnR2 and id=2 which returns a new instance of the current group.

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)

Trivial Action 

class TrivialOnR2(fibergroup=None)[source]

Bases: e2cnn.gspaces.r2.general_r2.GeneralOnR2

Describes the plane \(\R^2\) without considering any origin-preserving symmetry. This is modeled by a 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.

Parameters: fibergroup (Group, optional) – use an already existing instance of the symmetry group. By default, it builds a new instance of the trivial group.

restrict(id)[source]

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

As the trivial group contains only one element, there are no other subgroups. The only accepted input value is id=1 and returns this same group. This functionality is implemented only for consistency with the other G-spaces.

Parameters

id (int) – the order 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)

e2cnn.gspaces

Abstract Group Space

Group Actions on the Plane

Reflections and Rotations

Rotations

Reflections

Trivial Action

Abstract Group Space 

Group Actions on the Plane 

Reflections and Rotations 

Rotations 

Reflections 

Trivial Action 