escnn.kernels

This subpackage implements the complete analytical solutions of the equivariance constraints on the kernel space as explained in A Program to Build E(N)-Equivariant Steerable CNNs. The bases of equivariant kernels should be built through factory functions.

Typically, the user does not need to interact directly with this subpackage. Instead, we suggest to use the interface provided in escnn.gspaces.

This subpackage depends only on escnn.group.

Warning

This module has been largely refactored in version 1.0.0 and is not compatible with previous versions of the library. The interface of the other modules in not affected but some of the generated bases might be slightly different (e.g. basis elements being indexed in a different order). That means the weights trained using an older version of the library might not be compatible with newer instantiations of your models. For backward compatibility, we recommend using version 0.1.9 of the library.

Finally, note that a KernelBasis is a subclass of torch.nn.Module. As such, a KernelBasis can be treated as a PyTorch’s module, e.g. it can be moved to a CUDA enable device, the floating point precision of its parameters and buffers can be changed and its forward pass is generally differentiable.

Warning

Because non-zero circular and spherical harmonics are not well defined at the origin, the gradients of CircularShellsBasis and SphericalShellsBasis are difficult to compute. In 2D, the gradient at the origin of CircularShellsBasis is always zero (this could be solved in the most recent PyTorch versions by leveraging some complex powers). Instead, in 3D, SphericalShellsBasis should be able to compute reasonable estimates.

Generic Kernel Bases

KernelBasis

class KernelBasis(dim, shape)[source]

Bases: torch.nn.modules.module.Module, abc.ABC

Abstract class for implementing the basis of a kernel space. A kernel space is the space of functions in the form:

\[\mathcal{K} := \{ \kappa: X \to \mathbb{R}^{c_\text{out} \times c_\text{in}} \}\]

where \(X\) is the base space on which the kernel is defined. For instance, for planar images \(X = \R^2\).

One can also access the dimensionality dim of this basis via the len() method.

Parameters

  • dim (int) – the dimensionality of the basis \(|\mathcal{K}|\) (number of elements)

  • shape (tuple) – a tuple containing \(c_\text{out}\) and \(c_\text{in}\)

Variables

  • ~.dim (int) – the dimensionality of the basis \(|\mathcal{K}|\) (number of elements)

  • ~.shape (tuple) – a tuple containing \(c_\text{out}\) and \(c_\text{in}\)

abstract sample(points, out=None)[source]

Sample the continuous basis elements on discrete points in points. Optionally, store the resulting multidimentional array in out.

points must be an array of shape (N, D), where D is the dimensionality of the (parametrization of the) base space while N is the number of points.

Parameters

  • points (Tensor) – points where to evaluate the basis elements

  • out (Tensor, optional) – pre-existing array to use to store the output

Returns

the sampled basis

forward(points, out=None)[source]

Alias for sample().

AdjointBasis

class AdjointBasis(basis, adjoint)[source]

Bases: escnn.kernels.basis.KernelBasis

Transform the input basis by applying a change of basis adjoint on the points before sampling the basis.

Parameters

  • basis (KernelBasis) – a kernel basis

  • adjoint (ndarray) – an orthonormal matrix defining the change of basis on the base space

sample(points, out=None)[source]

Sample the continuous basis elements on the discrete set of points. Optionally, store the resulting multidimentional array in out.

points must be an array of shape (N, d), where N is the number of points and d their dimensionality.

Parameters

  • points (ndarray) – points where to evaluate the basis elements

  • out (ndarray, optional) – pre-existing array to use to store the output

Returns

the sampled basis

UnionBasis

class UnionBasis(bases_list)[source]

Bases: escnn.kernels.basis.KernelBasis

Construct the union of a list of bases. All bases must have the same shape; the resulting basis has dim equal to the sum of the dimensionalities of the individual bases.

EmptyBasisException

class EmptyBasisException[source]

Exception raised when a KernelBasis with no elements is built.

General Steerable Basis for equivariant kernels

The following classes implement the logic behind the kernel constraint solutions described in A Program to Build E(N)-Equivariant Steerable CNNs. SteerableKernelBasis solves the kernel constraint for a generic group and any pair of input and output representations by decomposing them into irreducible representations and, then, solving the simpler constraints on irreps independently, as described in General E(2)-Equivariant Steerable CNNs . IrrepBasis provides an interface for the methods which solve the kernel constraint for irreps. We implement two such methods, WignerEckartBasis and RestrictedWignerEckartBasis.

SteerableKernelBasis

class SteerableKernelBasis(basis, in_repr, out_repr, irreps_basis, **kwargs)[source]

Bases: escnn.kernels.basis.KernelBasis

Implements a general basis for the vector space of equivariant kernels over an Euclidean space \(X=\R^n\). A \(G\)-equivariant kernel \(\kappa\), 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:

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

As the kernel constraint is a linear constraint, the space of equivariant kernels is a vector subspace of the space of all convolutional kernels. It follows that any equivariant kernel can be expressed in terms of a basis of this space.

This class solves the kernel constraint for two arbitrary representations by combining the solutions of the kernel constraints associated to their IrreducibleRepresentation s. In order to do so, it relies on irreps_basis which solves individual irreps constraints. irreps_basis must be a class (subclass of IrrepsBasis) which builds a basis for equivariant kernels associated with irreducible representations when instantiated.

The groups \(G\) which are currently implemented are origin-preserving isometries (what are called structure groups, or sometimes gauge groups, in the language of Gauge Equivariant CNNs ). The origin-preserving isometries of \(\R^d\) are subgroups of \(O(d)\), i.e. reflections and rotations. Therefore, equivariance does not enforce any constraint on the radial component of the kernels. Hence, this class only implements a basis for the angular part of the kernels.

Warning

Typically, the user does not need to manually instantiate this class. Instead, we suggest to use the interface provided in escnn.gspaces.

Parameters

  • basis (SteerableFiltersBasis) – a steerable basis for scalar filters over the base space

  • in_repr (Representation) – Representation associated with the input feature field

  • out_repr (Representation) – Representation associated with the output feature field

  • irreps_basis (class) – class defining the irreps basis. This class is instantiated for each pair of irreps to solve all irreps constraints.

  • **kwargs – additional arguments used when instantiating irreps_basis

Variables
dim_harmonic(j)[source]

Number of kernel basis elements generated from elements of the steerable filter basis (self.basis) which transform according to the self.basis.group-irrep identified by j.

compute_harmonics(points)[source]

Pre-compute the sampled steerable filter basis over a set of point. This is an alias for self.basis.sample_as_dict(points).

See also

escnn.kernels.SteerableFiltersBasis.sample_as_dict().

sample(points, out=None)[source]

Sample the continuous basis elements on the discrete set of points in points. Optionally, store the resulting multidimentional array in out.

points must be an array of shape (N, d), where N is the number of points.

Parameters

  • points (Tensor) – points where to evaluate the basis elements

  • out (Tensor, optional) – pre-existing array to use to store the output

Returns

the sampled basis

sample_harmonics(points, out=None)[source]

Sample the continuous basis elements on the discrete set of points. Rather than using the points’ coordinates, the method directly takes in input the steerable basis elements sampled on this points using the method escnn.kernels.SteerableKernelBasis.compute_harmonics().

Similarly, rather than returning a single tensor containing all sampled basis elements, it groups basis elements by the G-irrep acting on them. The method returns a dictionary mapping each irrep’s id to a tensor of shape (N, m, o, i), where N is the number of points, m is the multiplicity of the irrep (see dim_harmonic()) and o, i is the number of input and output channels (see the shape attribute).

Optionally, store the resulting tensors in out, rather than allocating new memory.

Parameters

  • points (Tensor) – points where to evaluate the basis elements

  • out (Tensor, optional) – pre-existing array to use to store the output

Returns

the sampled basis

IrrepBasis

class IrrepBasis(basis, in_irrep, out_irrep, dim, harmonics=None)[source]

Bases: escnn.kernels.basis.KernelBasis

Abstract class for bases implementing the kernel constraint solutions associated to irreducible input and output representations.

Note

The steerable filter basis is not necessarily associated with the same group as in_irrep and out_irrep. For instance, RestrictedWignerEckartBasis uses a larger group to define basis. The attribute IrrepBasis.group, instead, refers to the equivariance group of this steerable kernel basis and is the same group of in_irrep and out_irrep. The irreps in the list harmonics refer to the group in the steerable filter basis, and not to IrrepBasis.group.

Parameters

  • basis (SteerableFiltersBasis) – the steerable basis used to parameterize scalar filters and generate the kernel solutions

  • in_irrep (IrreducibleRepresentation) – the input irrep

  • out_irrep (IrreducibleRepresentation) – the output irrep

  • dim (int) – the number of elements in the basis

  • harmonics (list, optional) – optionally, use only a subset of the steerable filters in basis. This list defines a subset of the group’s irreps and is used to select only the steerable basis filters which transform according to these irreps.

Variables
sample(points, out=None)[source]

Sample the continuous basis elements on the discrete set of points in points. Optionally, store the resulting multidimentional array in out.

points must be an array of shape (N, d), where N is the number of points and d is the dimensionality of the Euclidean space where filters are defined.

Parameters

  • points (Tensor) – points where to evaluate the basis elements

  • out (Tensor, optional) – pre-existing array to use to store the output

Returns

the sampled basis

abstract sample_harmonics(points, out=None)[source]

Sample the continuous basis elements on the discrete set of points. Rather than using the points’ coordinates, the method directly takes in input the steerable basis elements sampled on this points using the method escnn.kernels.SteerableFilterBasis.sample_as_dict() of self.basis.

Similarly, rather than returning a single tensor containing all sampled basis elements, it groups basis elements by the G-irrep acting on them. The method returns a dictionary mapping each irrep’s id to a tensor of shape (N, m, o, i), where N is the number of points, m is the multiplicity of the irrep (see dim_harmonic()) and o, i is the number of input and output channels (see the shape attribute).

Optionally, store the resulting tensors in out, rather than allocating new memory.

Parameters

  • points (Tensor) – points where to evaluate the basis elements

  • out (Tensor, optional) – pre-existing array to use to store the output

Returns

the sampled basis

abstract dim_harmonic(j)[source]

Number of kernel basis elements generated from elements of the steerable filter basis (self.basis) which transform according to the self.basis.group-irrep identified by j.

WignerEckartBasis

class WignerEckartBasis(basis, in_irrep, out_irrep)[source]

Bases: escnn.kernels.steerable_basis.IrrepBasis

Solves the kernel constraint for a pair of input and output \(G\)-irreps by using the Wigner-Eckart theorem described in Theorem 2.1 of A Program to Build E(N)-Equivariant Steerable CNNs (see also A Wigner-Eckart Theorem for Group Equivariant Convolution Kernels ). The method relies on a \(G\)-Steerable basis of scalar functions over the base space.

Parameters

RestrictedWignerEckartBasis

class RestrictedWignerEckartBasis(basis, sg_id, in_irrep, out_irrep)[source]

Bases: escnn.kernels.steerable_basis.IrrepBasis

Solves the kernel constraint for a pair of input and output \(G\)-irreps by using the Wigner-Eckart theorem described in Theorem 2.1 of A Program to Build E(N)-Equivariant Steerable CNNs. This method implicitly constructs the required \(G\)-steerable basis for scalar functions on the base space from a \(G'\)-steerable basis, with \(G' > G\) a larger group, according to Equation 5 from the same paper.

The equivariance group \(G < G'\) is identified by the input id sg_id.

Warning

Note that the group \(G'\) associated with basis is generally not the same as the group \(G\) associated with in_irrep and out_irrep and which the resulting kernel basis is equivariant to.

Parameters

Steerable Filter Bases

To solve the kernel constraint and generate a SteerableKernelBasis, one requires a steerable basis for scalar filters over the base space, as derived in A Program to Build E(N)-Equivariant Steerable CNNs. Different implementations and parameterizations of steerable convolutions effectively differ by the choice of steerable filter basis. The following classes implement different choices of SteerableFilterBasis.

SteerableFiltersBasis

class SteerableFiltersBasis(G, action, js)[source]

Bases: escnn.kernels.basis.KernelBasis

Abstract class for bases implementing a \(G\)-steerable basis for scalar filters over an Euclidean space \(\R^n\).

The action of G on the Euclidean space is given by the Representation action. The dimensionality of the Euclidean space is inferred by the size of the action.

A \(G\)-steerable basis provides an irreps-decomposition of the action of \(G\) on the vector space of square-integrable functions, i.e. \(L^2(\R^n)\). The input list js defines the order and the multiplicity of the G-irreps in this decomposition. More precisely, js is a list of tuples (irrep_id, multiplicity), where irrep_id is the id of an IrreducibleRepresentation.

The order of the basis elements sampled in sample() should be consistent with the order of the irreps in the list js.

Since this class only parameterizes scalar filters, SteerableFiltersBasis.shape = (1, 1).

Parameters

  • G (Group) – the symmetry group

  • action (Representation) – the representation of the action of G on the Euclidean space

  • js (list) – the multiplicity of each irrep in this basis.

Variables

  • ~.G (Group) – the symmetry group

  • ~.action (Representation) – the representation of the action of G on the Euclidean space

  • ~.js (list) – the multiplicity of each irrep in this basis.

property dimensionality: int

The dimensionality of the Euclidean space on which the scalar filters are defined.

abstract sample(points, out=None)[source]

Sample the continuous basis elements on the discrete set of points in points. Optionally, store the resulting multidimensional array in out.

points must be an array of shape (N, d), where N is the number of points and d is equal to dimensionality().

Parameters

  • points (Tensor) – points where to evaluate the basis elements

  • out (Tensor, optional) – pre-existing array to use to store the output

Returns

the sampled basis

sample_as_dict(points, out=None)[source]

Sample the continuous basis elements on the discrete set of points in points.

Rather than returning a single tensor containing all sampled basis elements, it groups basis elements by the G-irrep acting on them. Then, the method returns a dictionary mapping each irrep’s id to a tensor of shape (N, m, d), where m is the multiplicity of the irrep (as in the list js) and d is the size of the irrep.

points must be an array of shape (N, D), where N is the number of points and D is equal to dimensionality().

Optionally, store the resulting multidimentional array in out.

Parameters

  • points (Tensor) – points where to evaluate the basis elements

  • out (Tensor, optional) – pre-existing array to use to store the output

Returns

the sampled basis

dim_harmonic(j)[source]

Number of basis elements associated with the G-irrep with the id j. This is equal to the multiplicity of this irrep times its size, i.e. the number of subspaces transforming according to this irrep times the dimensionality of these subspaces.

multiplicity(j)[source]

The multiplicity of the G-irrep with the id j as defined in the list js.

PointBasis

class PointBasis(G)[source]

Bases: escnn.kernels.steerable_filters_basis.SteerableFiltersBasis

Basis for scalar functions over a “0-dimensional” Euclidean space, i.e. a space containing only a single point. This basis only contains the function associating the value \(1\) to this single point.

This basis is steerable for any group G, which acts on this point by mapping it to itself.

This class is useful to parameterize equivairant linear layers as a special case of steerable convolution layers in a neural network.

Warning

This class is implemented by using G.trivial_representation as action which, however, implies a 1-dimensional Euclidean space.

CircularShellsBasis

class CircularShellsBasis(L, radial, filter=None, axis=1.5707963267948966)[source]

Bases: escnn.kernels.steerable_filters_basis.SteerableFiltersBasis

Build the tensor product basis of a radial profile basis and a circular harmonics basis for kernels over the Euclidean space \(\R^2\).

The kernel space is spanned by an independent basis for each shell. The kernel space each shell is spanned by the circular harmonics of frequency up to L (an independent copy of each for each cell).

Given the bases \(A = \{a_j\}_j\) for the circular shells and \(D = \{d_r\}_r\) for the radial component (indexed by \(r \geq 0\), the radius different rings), this basis is defined as

\[C = \left\{c_{i,j}(\bold{p}) := d_r(||\bold{p}||) a_j(\hat{\bold{p}}) \right\}_{r, j}\]

where \((||\bold{p}||, \hat{\bold{p}})\) are the polar coordinates of the point \(\bold{p} \in \R^n\).

The radial component is parametrized using GaussianRadialProfile.

Parameters

  • L (int) – the maximum circular frequency

  • radial (GaussianRadialProfile) – the basis for the radial profile

  • filter (callable, optional) – function used to filter out some basis elements. It takes as input a dict describing a basis element and should return a boolean value indicating whether to keep (True) or discard (False) the element. By default (None), all basis elements are kept.

Variables
sample(points, out=None)[source]

Sample the continuous basis elements on a discrete set of points in the space \(\R^n\). Optionally, store the resulting multidimensional array in out.

points must be an array of shape (N, 2) containing N points in the space. Note that the points are specified in cartesian coordinates \((x, y, z, ...)\).

Parameters

  • points (Tensor) – points in the n-dimensional Euclidean space where to evaluate the basis elements

  • out (Tensor, optional) – pre-existing array to use to store the output

Returns

the sampled basis

SphericalShellsBasis

class SphericalShellsBasis(L, radial, filter=None)[source]

Bases: escnn.kernels.steerable_filters_basis.SteerableFiltersBasis

Build the tensor product basis of a radial profile basis and a spherical harmonics basis for kernels over the Euclidean space \(\R^3\).

The kernel space is spanned by an independent basis for each shell. The kernel space over each shell is spanned by the spherical harmonics of frequency up to L (an independent copy of each for each cell).

Given the bases \(A = \{a_j\}_j\) for the spherical shells and \(D = \{d_r\}_r\) for the radial component (indexed by \(r \geq 0\), the radius of each ring), this basis is defined as

\[C = \left\{c_{i,j}(\bold{p}) := d_r(||\bold{p}||) a_j(\hat{\bold{p}}) \right\}_{r, j}\]

where \((||\bold{p}||, \hat{\bold{p}})\) are the polar coordinates of the point \(\bold{p} \in \R^n\).

The radial component is parametrized using GaussianRadialProfile.

Parameters

  • L (int) – the maximum spherical frequency

  • radial (GaussianRadialProfile) – the basis for the radial profile

  • filter (callable, optional) – function used to filter out some basis elements. It takes as input a dict describing a basis element and should return a boolean value indicating whether to keep (True) or discard (False) the element. By default (None), all basis elements are kept.

Variables
sample(points, out=None)[source]

Sample the continuous basis elements on a discrete set of points in the space \(\R^n\). Optionally, store the resulting multidimensional array in out.

points must be an array of shape (N, 3) containing N points in the space. Note that the points are specified in cartesian coordinates \((x, y, z, ...)\).

Parameters

  • points (Tensor) – points in the n-dimensional Euclidean space where to evaluate the basis elements

  • out (Tensor, optional) – pre-existing array to use to store the output

Returns

the sampled basis

SparseOrbitBasis

class SparseOrbitBasis(X, action, root, sigma, harmonics=None, change_of_basis=None, attributes=None)[source]

Bases: escnn.kernels.steerable_filters_basis.SteerableFiltersBasis

Class which implements a steerable basis for scalar functions on an Euclidean space \(\R^n\) by considering a single orbit of the symmetry group \(G\) in \(\R^n\).

Indeed, an orbit \(\{g.x | g \in G\}\), with \(x \in \R^n\), is isomorphic to an homogeneous space `X` of \(G\). A steerable basis for scalar functions over an homogeneous space is given by the harmonic basis in HomSpace.

In this class, a steerable basis over \(\R^n\) is defined by embedding the finite number of points of a finite homogeneous space `X` into \(\R^n\) and then “diffusing” the harmonic basis defined over these points in the ambient space using a Gaussian kernel.

This class only supports finite homogeneous spaces generated by a finite symmetry group, i.e. not only \(X=G/H\) must have a finite number of elements but also \(G\) itself should.

The embedding of `X` into \(\R^n\) is defined via the point root, which defines the embedding of the coset \(eH\) associated with the identity, and the action of the group \(G\) on \(\R^n\). This implies that the action of any element of \(H\) should keep root fixed.

Parameters

  • X (HomSpace) – the homogeneous space isomorphic to the orbit in the Euclidean space

  • action (Representation) – the action of the group G on the Euclidean space

  • root (ndarray) – the embedding of the identity coset

  • sigma (float) – the standard deviation of the Gaussian kernel used to diffuse the harmonic basis in the ambient space.

  • harmonics (list, optional) – optionally, select only a subset of the harmonic functions. The list should contain the ids of group’s irreps which should be used to construct the harmonic basis. See also scalar_basis().

  • change_of_basis (ndarray, optional) – optionally, apply a transformation on the embedded points to construct a different basis. Equivalently, one can apply this change of basis to both root and action.

  • attributes (dict, optional) – additional attributes to describe the generated basis.

Variables

~.X (HomSpace) – the homogeneous space

sample(points, out=None)[source]

Sample the continuous basis elements on the discrete set of points in points. Optionally, store the resulting multidimentional array in out.

points must be an array of shape (N, d), where N is the number of points and d is the dimensionality() of the Euclidean space.

Parameters

  • points (Tensor) – points where to evaluate the basis elements

  • out (Tensor, optional) – pre-existing array to use to store the output

Returns

the sampled basis

SparseOrbitBasisWithIcosahedralSymmetry

class SparseOrbitBasisWithIcosahedralSymmetry(X, sigma, harmonics=None, change_of_basis=None, attributes=None)[source]

Bases: escnn.kernels.sparse_basis.SparseOrbitBasis

Given an homogeneous space X of the Icosahedral group, builds the SparseOrbitBasis with a root which generates an orbit isomorphic to X.

GaussianRadialProfile

class GaussianRadialProfile(radii, sigma)[source]

Bases: escnn.kernels.basis.KernelBasis

Basis for kernels defined over a radius in \(\R^+_0\).

Each basis element is defined as a Gaussian function. Different basis elements are centered at different radii (rings) and can possibly be associated with different widths (sigma).

More precisely, the following basis is implemented:

\[\mathcal{B} = \left\{ b_i (r) := \exp \left( \frac{ \left( r - r_i \right)^2}{2 \sigma_i^2} \right) \right\}_i\]

In order to build a complete basis of kernels, you should combine this basis with a basis which defines the angular profile, see for example SphericalShellsBasis or CircularShellsBasis.

Parameters

  • radii (list) – centers of each basis element. They should be different and spread to cover all domain of interest

  • sigma (list or float) – widths of each element. Can potentially be different.

sample(radii, out=None)[source]

Sample the continuous basis elements on the discrete set of radii in radii. Optionally, store the resulting multidimentional array in out.

radii must be an array of shape (N, 1), where N is the number of points.

Parameters

  • radii (Tensor) – radii where to evaluate the basis elements

  • out (Tensor, optional) – pre-existing array to use to store the output

Returns

the sampled basis

Generic Group acting on a single point

kernels_on_point(in_repr, out_repr)[source]
Parameters

  • in_repr (Representation) – the representation specifying the transformation of the input feature field

  • out_repr (Representation) – the representation specifying the transformation of the output feature field

Bases for Group Actions on the Plane

The following factory functions provide an interface to build the bases for kernels equivariant to groups acting on the two dimensional plane (\(d=2\)). The names of the functions follow this convention kernels_[G]_act_R[d], where \(G\) is the origin-preserving isometry group while \(\R^d\) is the space on which it acts, interpreted as the domain of the kernel \(\kappa: \R^d \to \R^{c_\text{out} \times c_\text{in}}\). In the language of Gauge Equivariant CNNs , the origin-preserving isometry \(G\) is called structure group (or, sometimes, gauge group).

R2: Reflections

kernels_Flip_act_R2(in_repr, out_repr, radii, sigma, axis=1.5707963267948966, maximum_frequency=None, adjoint=None, filter=None)[source]

Builds a basis for convolutional kernels equivariant to reflections. in_repr and out_repr need to be Representation s of CyclicGroup with N=2.

Because the equivariance constraints allow any choice of radial profile, we use a GaussianRadialProfile. radii specifies the radial distances at which the rings are centered while sigma contains the width of each of these rings (see GaussianRadialProfile).

The parameter axis is the angle in radians (with respect to the horizontal axis, rotating counter-clockwise) which defines the reflection axis.

The analytical angular solutions of kernel constraints belong to an infinite dimensional space and so can be expressed in terms of infinitely many basis elements. Only a finite subset can however be implemented. maximum_frequency defines the maximum frequency of a finite-dimensional bandlimited subspace and is therefore necessary to specify it. See kernels_CN_act_R2() for more details.

Parameters

  • in_repr (Representation) – the representation specifying the transformation of the input feature field

  • out_repr (Representation) – the representation specifying the transformation of the output feature field

  • radii (list) – radii of the rings defining the basis for the radial profile

  • sigma (list or float) – widths of the rings defining the basis for the radial profile

  • axis (float) – angle defining the reflection axis

  • maximum_frequency (int) – maximum frequency of the basis

  • adjoint (ndarray, optional) – instead of specifying a reflection axis, you can pass a 2x2 orthogonal matrix defining a change of basis on the base space

R2: Reflections and Discrete Rotations

kernels_DN_act_R2(in_repr, out_repr, radii, sigma, axis=1.5707963267948966, maximum_frequency=None, max_offset=None, adjoint=None, filter=None)[source]

Builds a basis for convolutional kernels equivariant to reflections and \(N\) discrete rotations, modeled by the group \(D_N\). in_repr and out_repr need to be Representation s of DihedralGroup.

Because the equivariance constraints allow any choice of radial profile, we use a GaussianRadialProfile. radii specifies the radial distances at which the rings are centered while sigma contains the width of each of these rings (see GaussianRadialProfile).

The parameter axis is the angle in radians (with respect to the horizontal axis, rotating counter-clockwise) which defines the reflection axis for the reflection element of the group.

Frequencies also appear in a basis with a period of \(N\), i.e. if the basis contains an element with frequency \(k\), then it also contains an element with frequency \(k + N\). In the analytical solutions shown in Table 12 here, each solution has a parameter \(t\) or \(\hat{t}\). max_offset defines the maximum absolute value of these two numbers.

Either maximum_frequency or max_offset must be specified.

Parameters

  • in_repr (Representation) – the representation specifying the transformation of the input feature field

  • out_repr (Representation) – the representation specifying the transformation of the output feature field

  • radii (list) – radii of the rings defining the basis for the radial profile

  • sigma (list or float) – widths of the rings defining the basis for the radial profile

  • maximum_frequency (int) – maximum frequency of the basis

  • max_offset (int) – maximum offset in the frequencies of the basis

  • axis (float) – angle defining the reflection axis

  • adjoint (ndarray, optional) – instead of specifying a reflection axis, you can pass a 2x2 orthogonal matrix defining a change of basis on the base space

R2: Reflections and Continuous Rotations

kernels_O2_act_R2(in_repr, out_repr, radii, sigma, maximum_frequency=None, axis=1.5707963267948966, adjoint=None, filter=None)[source]

Builds a basis for convolutional kernels equivariant to reflections and continuous rotations, modeled by the group \(O(2)\). in_repr and out_repr need to be Representation s of O2.

Because the equivariance constraints allow any choice of radial profile, we use a GaussianRadialProfile. radii specifies the radial distances at which the rings are centered while sigma contains the width of each of these rings (see GaussianRadialProfile).

Because \(O(2)\) contains all rotations, the reflection element of the group can be associated to any reflection axis. Reflections along other axes can be obtained by composition with rotations. However, a choice of this axis is required to align the basis with respect to the action of the group.

Parameters

  • in_repr (Representation) – the representation specifying the transformation of the input feature field

  • out_repr (Representation) – the representation specifying the transformation of the output feature field

  • radii (list) – radii of the rings defining the basis for the radial profile

  • sigma (list or float) – widths of the rings defining the basis for the radial profile

  • axis (float, optional) – angle of the axis of the reflection element

  • adjoint (ndarray, optional) – instead of specifying a reflection axis, you can pass a 2x2 orthogonal matrix defining a change of basis on the base space

R2: Trivial Action

kernels_Trivial_act_R2(in_repr, out_repr, radii, sigma, maximum_frequency=None, filter=None)[source]

Builds a basis for unconstrained convolutional kernels.

This is equivalent to use kernels_CN_act_R2() with an instance of CyclicGroup with N=1 (the trivial group \(C_1\)).

in_repr and out_repr need to be associated with an instance of CyclicGroup with N=1.

Because the equivariance constraints allow any choice of radial profile, we use a GaussianRadialProfile. radii specifies the radial distances at which the rings are centered while sigma contains the width of each of these rings (see GaussianRadialProfile).

The analytical angular solutions of kernel constraints belong to an infinite dimensional space and so can be expressed in terms of infinitely many basis elements. Only a finite subset can however be implemented. maximum_frequency defines the maximum frequency of a finite-dimensinal bandlimited subspace and is therefore necessary to specify it. See kernels_CN_act_R2() for more details.

Parameters

  • in_repr (Representation) – the representation specifying the transformation of the input feature field

  • out_repr (Representation) – the representation specifying the transformation of the output feature field

  • radii (list) – radii of the rings defining the basis for the radial profile

  • sigma (list or float) – widths of the rings defining the basis for the radial profile

  • axis (float) – angle defining the reflection axis

  • maximum_frequency (int) – maximum frequency of the basis

R2: Discrete Rotations

kernels_CN_act_R2(in_repr, out_repr, radii, sigma, maximum_frequency=None, max_offset=None, filter=None)[source]

Builds a basis for convolutional kernels equivariant to \(N\) discrete rotations, modeled by the group \(C_N\). in_repr and out_repr need to be Representation s of CyclicGroup.

Because the equivariance constraints allow any choice of radial profile, we use a GaussianRadialProfile. radii specifies the radial distances at which the rings are centered while sigma contains the width of each of these rings (see GaussianRadialProfile).

The analytical angular solutions of kernel constraints belong to an infinite dimensional space and so can be expressed in terms of infinitely many basis elements, each associated with one unique frequency. Because the kernels are then sampled on a finite number of points (e.g. the cells of a grid), only low-frequency solutions needs to be considered. This enables us to build a finite dimensional basis containing only a finite subset of all analytical solutions. maximum_frequency is an integer controlling the highest frequency sampled in the basis.

Frequencies also appear in a basis with a period of \(N\), i.e. if the basis contains an element with frequency \(k\), then it also contains an element with frequency \(k + N\). In the analytical solutions shown in Table 11 here, each solution has a parameter \(t\) or \(\hat{t}\). max_offset defines the maximum absolute value of these two numbers.

Either maximum_frequency or max_offset must be specified.

Parameters

  • in_repr (Representation) – the representation specifying the transformation of the input feature field

  • out_repr (Representation) – the representation specifying the transformation of the output feature field

  • radii (list) – radii of the rings defining the basis for the radial profile

  • sigma (list or float) – widths of the rings defining the basis for the radial profile

  • maximum_frequency (int) – maximum frequency of the basis

  • max_offset (int) – maximum offset in the frequencies of the basis

R2: Continuous Rotations

kernels_SO2_act_R2(in_repr, out_repr, radii, sigma, maximum_frequency=None, filter=None)[source]

Builds a basis for convolutional kernels equivariant to continuous rotations, modeled by the group \(SO(2)\). in_repr and out_repr need to be Representation s of SO2.

Because the equivariance constraints allow any choice of radial profile, we use a GaussianRadialProfile. radii specifies the radial distances at which the rings are centered while sigma contains the width of each of these rings (see GaussianRadialProfile).

Parameters

  • in_repr (Representation) – the representation specifying the transformation of the input feature field

  • out_repr (Representation) – the representation specifying the transformation of the output feature field

  • radii (list) – radii of the rings defining the basis for the radial profile

  • sigma (list or float) – widths of the rings defining the basis for the radial profile

R2: Generic Subgroups of Continuous Rotations

kernels_SO2_subgroup_act_R2(in_repr, out_repr, sg_id, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R2: Generic Subgroups of Continuous Rotations and Reflections

kernels_O2_subgroup_act_R2(in_repr, out_repr, sg_id, radii, sigma, maximum_frequency=5, axis=1.5707963267948966, adjoint=None, filter=None)[source]

Bases for Group Actions in 3D Space

The following factory functions provide an interface to build the bases for kernels equivariant to groups acting on the three dimensional Euclidean space (\(d=3\)). The names of the functions follow this convention kernels_[G]_act_R[d], where \(G\) is the origin-preserving isometry group while \(\R^d\) is the space on which it acts, interpreted as the domain of the kernel \(\kappa: \R^d \to \R^{c_\text{out} \times c_\text{in}}\). In the language of Gauge Equivariant CNNs , the origin-preserving isometry \(G\) is called structure group (or, sometimes, gauge group).

R3: Inversions and Continuous Rotations

kernels_O3_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=None, adjoint=None, filter=None)[source]

Builds a basis for convolutional kernels equivariant to reflections and continuous rotations, modeled by the group \(O(3)\). in_repr and out_repr need to be Representation s of O3.

Because the equivariance constraints allow any choice of radial profile, we use a GaussianRadialProfile. radii specifies the radial distances at which the rings are centered while sigma contains the width of each of these rings (see GaussianRadialProfile).

Because \(O(3)\) contains all rotations, the reflection element of the group can be associated to any reflection axis.

Parameters

  • in_repr (Representation) – the representation specifying the transformation of the input feature field

  • out_repr (Representation) – the representation specifying the transformation of the output feature field

  • radii (list) – radii of the rings defining the basis for the radial profile

  • sigma (list or float) – widths of the rings defining the basis for the radial profile

  • adjoint (ndarray, optional) – 3x3 orthogonal matrix defining a change of basis on the base space

R3: Continuous Rotations

kernels_SO3_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=None, adjoint=None, filter=None)[source]

Builds a basis for convolutional kernels equivariant to continuous rotations, modeled by the group \(SO(3)\). in_repr and out_repr need to be Representation s of SO3.

Because the equivariance constraints allow any choice of radial profile, we use a GaussianRadialProfile. radii specifies the radial distances at which the rings are centered while sigma contains the width of each of these rings (see GaussianRadialProfile).

Parameters

  • in_repr (Representation) – the representation specifying the transformation of the input feature field

  • out_repr (Representation) – the representation specifying the transformation of the output feature field

  • radii (list) – radii of the rings defining the basis for the radial profile

  • sigma (list or float) – widths of the rings defining the basis for the radial profile

  • adjoint (ndarray, optional) – 3x3 orthogonal matrix defining a change of basis on the base space

R3: Generic Subgroup of Continuous Rotations

kernels_SO3_subgroup_act_R3(in_repr, out_repr, sg_id, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R3: Generic Subgroup of Continuous Rotations and Inversions

kernels_O3_subgroup_act_R3(in_repr, out_repr, sg_id, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R3: Icosahedral symmetries

kernels_Ico_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R3: Octahedral symmetries

kernels_Octa_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R3: Tetrahedral symmetries

kernels_Tetra_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R3: Full Icosahedral symmetries

kernels_FullIco_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R3: Full Octahedral symmetries

kernels_FullOcta_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R3: Full Tetrahedral symmetries

kernels_FullTetra_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R3: Pyritohedral symmetries

kernels_Pyrito_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R3: Planar continuous Rotations

kernels_SO2_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R3: Planar discrete Rotations

kernels_CN_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, max_offset=None, adjoint=None, filter=None)[source]

R3: Continuous Cone Symmetries

kernels_O2_conical_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R3: Discrete Cone Symmetries

kernels_DN_conical_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, max_offset=None, adjoint=None, filter=None)[source]

R3: Continuous Dihedral Symmetries

kernels_O2_dihedral_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, adjoint=None, filter=None)[source]

R3: Discrete Dihedral Symmetries

kernels_DN_dihedral_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, max_offset=None, adjoint=None, filter=None)[source]

R3: Inversions

kernels_Inv_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, filter=None)[source]

R3: Trivial Action

kernels_Trivial_act_R3(in_repr, out_repr, radii, sigma, maximum_frequency=5, filter=None)[source]