e2cnn.diffops

This subpackage implements the complete analytical solutions of the equivariance constraints partial differential operators (PDOs) as described in Steerable Partial Differentail Operators for Equivariant Neural Network. The bases of equivariant PDOs 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 e2cnn.gspaces.

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

Note that discretization of the differential operators relies on the sympy and rbf packages. If these packages are not installed, an error will be thrown when trying to sample the operators.

Abstract Class

class DiffopBasis(coefficients, discretization=DiscretizationArgs(method='fd', smoothing=None, angle_offset=None, phi='ga'))[source]

Abstract class for implementing the basis of a space of differential operators. Such a space consists of \(c_\text{out} \times c_\text{in}\) matrices with partial differential operators as entries.

Parameters

  • coefficients (list) – a list of ndarrays. Each array describes one element of the basis and has shape (c_out, c_in, n + 1), where n is the derivative order of the entries of the matrix. PDOs are encoded as the coefficients of \(\frac{\partial^n}{\partial x^n}\), \(\frac{\partial^n}{\partial x^{n - 1}\partial y}\), …, \(\frac{\partial^n}{\partial y^n}\).

  • discretization (optional) – additional parameters specifying parameters for the discretization procedure. See DiscretizationArgs.

Variables

  • ~.coefficients (list) – an analytical description of the PDO basis elements, see above

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

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

  • ~.maximum_order (int) – the largest derivative order occuring in the basis

sample(points)[source]

Discretize the basis on a set of points. See sampled_masked() for details.

sample_masked(points, mask=None)[source]

Discretize the basis on a set of points.

Parameters

  • points (ndarray) – a 2 x N array with N points on which to discretize. If FD is used (default), this has to be a flattened version of a regular sorted grid (like you would get using np.meshgrid on ranges).

  • mask (ndarray, optional) – Boolean array of shape (dim, ), where dim is the number of basis elements. True for elements to discretize and False for elements to discard.

Returns

ndarray of with shape (C_out, C_in, num_basis_elements, n_in), where num_basis_elements are the number of elements after applying the mask, and n_in is the number of points.

pretty_print()[source]

Return a human-readable representation of all basis elements.

class DiscretizationArgs(method='fd', smoothing=None, angle_offset=None, phi='ga')[source]

Parameters specifying a discretization procedure for PDOs.

Variables

  • ~.method (str, optional) – the discretization method to use, either "rbffd", "fd" or "gauss".

  • ~.smoothing (float, optional) – smoothing is the standard deviation of the Gaussian used for discretization. Must be set if method="gauss", has no effect otherwise.

  • ~.angle_offset (float, optional) – if not None, rotate the PDOs by this many radians.

  • ~.phi (str, optional) – which RBF to use (only relevant for RBF-FD). Can be any of the abbreviations here.

method: str = 'fd'
smoothing: Optional[float] = None
angle_offset: Optional[float] = None
phi: str = 'ga'

PDO Bases

Tensor Product of Laplacian and angular PDOs

class TensorBasis(irreps_basis, in_repr, out_repr, max_power, discretization=DiscretizationArgs(method='fd', smoothing=None, angle_offset=None, phi='ga'), **kwargs)[source]

Bases: e2cnn.diffops.basis.DiffopBasis

Build the tensor product basis of two PDO bases over the plane. Given two bases \(A = \{a_i\}_i\) and \(B = \{b_j\}_j\), this basis is defined as

\[C = A \otimes B = \left\{ c_{i,j} := a_i \circ b_j \right\}_{i,j}.\]

The arguments are passed on to SteerableDiffopBasis and LaplaceProfile, see their documentation.

Variables

Laplacian Profile

class LaplaceProfile(max_power, discretization=DiscretizationArgs(method='fd', smoothing=None, angle_offset=None, phi='ga'))[source]

Bases: e2cnn.diffops.basis.DiffopBasis

Basis for rotationally invariant PDOs. Each basis element is defined as a power of a Laplacian.

In order to build a complete basis of PDOs, you should combine this basis with a basis which defines the angular profile through TensorBasis.

Parameters

  • max_power (int) – the maximum power of the Laplace operator that will be used. The maximum degree (as a differential operator) will be two times this maximum power.

  • discretization (DiscretizationArgs, optional) – additional parameters specifying parameters for the discretization procedure. See DiscretizationArgs.

General Steerable Basis for equivariant PDOs

class SteerableDiffopBasis(irreps_basis, in_repr, out_repr, discretization=DiscretizationArgs(method='fd', smoothing=None, angle_offset=None, phi='ga'), **kwargs)[source]

Bases: e2cnn.diffops.basis.DiffopBasis

Implements a general basis for the vector space of equivariant PDOs. 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}\).

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

This class solves the PDO constraint for two arbitrary representations by combining the solutions of the PDO 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 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, PDOs may be composed with any rotation and reflection invariant PDO without affecting equivariance. This class only implements a basis up to such invariant PDOs, which are given by polynomials in the Laplacian operator.

In order to build a complete basis of PDOs, you should combine this basis with LaplaceProfile) through TensorBasis.

Warning

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

Parameters

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

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

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

  • discretization (DiscretizationArgs, optional) – additional parameters specifying parameters for the discretization procedure. See DiscretizationArgs.

  • **kwargs – additional arguments used when instantiating irreps_basis

Bases for Group Actions on the Plane

The following factory functions provide an interface to build the bases for PDOs equivariant to groups acting on the two dimensional plane. The names of the functions follow this convention diffops_[G]_act_R[d], where \(G\) is the origin-preserving isometry group while \(\R^d\) is the space on which it acts. Here, \(d=2\) as we only consider the planar setting. In the language of Gauge Equivariant CNNs , the origin-preserving isometry \(G\) is called structure group (or, sometimes, gauge group).

Reflections and Continuous Rotations

diffops_O2_act_R2(in_repr, out_repr, max_power, axis=1.5707963267948966, discretization=DiscretizationArgs(method='fd', smoothing=None, angle_offset=None, phi='ga'))[source]

Builds a basis for PDOs 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 LaplaceProfile, which is the most general choice. max_power specifies the maximum power of the Laplacian. The maximum order of differential operators in the basis will be two times max_power plus the maximum order of the angular basis.

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

  • max_power (int) – maximum power of the Laplacian for the radial profile

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

  • discretization (DiscretizationArgs, optional) – additional parameters specifying parameters for the discretization procedure. See DiscretizationArgs.

Continuous Rotations

diffops_SO2_act_R2(in_repr, out_repr, max_power, discretization=DiscretizationArgs(method='fd', smoothing=None, angle_offset=None, phi='ga'))[source]

Builds a basis for PDOs 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 LaplaceProfile, which is the most general choice. max_power specifies the maximum power of the Laplacian. The maximum order of differential operators in the basis will be two times max_power plus the maximum order of the angular basis.

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

  • max_power (int) – maximum power of the Laplacian for the radial profile

  • discretization (DiscretizationArgs, optional) – additional parameters specifying parameters for the discretization procedure. See DiscretizationArgs.

Reflections and Discrete Rotations

diffops_DN_act_R2(in_repr, out_repr, max_power, axis=1.5707963267948966, max_frequency=None, max_offset=None, discretization=DiscretizationArgs(method='fd', smoothing=None, angle_offset=None, phi='ga'))[source]

Builds a basis for PDOs 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 LaplaceProfile, which is the most general choice. max_power specifies the maximum power of the Laplacian. The maximum order of differential operators in the basis will be two times max_power plus the maximum order of the angular basis.

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.

The analytical angular solutions of PDO 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. max_frequency and max_offset defines two ways to do so and therefore it is necessary to specify one of them. See diffops_CN_act_R2() for more details.

Either max_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

  • max_power (int) – maximum power of the Laplacian for the radial profile

  • max_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

  • discretization (DiscretizationArgs, optional) – additional parameters specifying parameters for the discretization procedure. See DiscretizationArgs.

Discrete Rotations

diffops_CN_act_R2(in_repr, out_repr, max_power, max_frequency=None, max_offset=None, discretization=DiscretizationArgs(method='fd', smoothing=None, angle_offset=None, phi='ga'))[source]

Builds a basis for PDOs 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 LaplaceProfile, which is the most general choice. max_power specifies the maximum power of the Laplacian. The maximum order of differential operators in the basis will be two times max_power plus the maximum order of the angular basis.

The analytical angular solutions of PDO constraints belong to an infinite dimensional space and so can be expressed in terms of infinitely many basis elements, each associated with one unique order. Because the kernels are then discretized on a finite number of points (e.g. the cells of a grid), only low-order solutions needs to be considered. This enables us to build a finite dimensional basis containing only a finite subset of all analytical solutions. max_frequency is an integer controlling the highest angular order sampled in the basis (named this way because of the analogy to frequencies for kernels). The maximum order of the complete PDO will be max_frequency + 2 * max_power.

Orders/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 order \(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 max_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

  • max_power (int) – maximum power of the Laplacian for the radial profile

  • max_frequency (int) – maximum frequency of the basis

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

  • discretization (DiscretizationArgs, optional) – additional parameters specifying parameters for the discretization procedure. See DiscretizationArgs.

Reflections

diffops_Flip_act_R2(in_repr, out_repr, max_power, axis=1.5707963267948966, max_frequency=None, max_offset=None, discretization=DiscretizationArgs(method='fd', smoothing=None, angle_offset=None, phi='ga'))[source]

Builds a basis for PDOs 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 LaplaceProfile, which is the most general choice. max_power specifies the maximum power of the Laplacian. The maximum order of differential operators in the basis will be two times max_power plus the maximum order of the angular basis.

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 PDO 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. max_frequency and max_offset defines two ways to do so and therefore it is necessary to specify one of them. See diffops_CN_act_R2() for more details.

Todo

remove max_offset as it is equivalent to max_frequency here

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

  • max_power (int) – the maximum power of Laplacians to use

  • axis (float) – angle defining the reflection axis

  • max_frequency (int) – maximum frequency of the basis

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

  • discretization (DiscretizationArgs, optional) – additional parameters specifying parameters for the discretization procedure. See DiscretizationArgs.

Trivial Action

diffops_Trivial_act_R2(in_repr, out_repr, max_power, max_frequency=None, max_offset=None, discretization=DiscretizationArgs(method='fd', smoothing=None, angle_offset=None, phi='ga'))[source]

Builds a basis for unconstrained PDOs.

This is equivalent to use diffops_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 LaplaceProfile, which is the most general choice. max_power specifies the maximum power of the Laplacian. The maximum order of differential operators in the basis will be two times max_power plus the maximum order of the angular basis.

The analytical angular solutions of PDO 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. max_frequency and max_offset defines two ways to do so and therefore it is necessary to specify one of them. See diffops_CN_act_R2() for more details.

Todo

remove max_offset as it is equivalent to max_frequency here

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

  • max_power (int) – maximum power of the Laplacian for the radial profile

  • axis (float) – angle defining the reflection axis

  • max_frequency (int) – maximum frequency of the basis

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

  • discretization (DiscretizationArgs, optional) – additional parameters specifying parameters for the discretization procedure. See DiscretizationArgs.

Utility functions

store_cache(path='./.e2cnn_cache/diffops.pickle')[source]

Cache PDO discretizations on disk. The cache can later be loaded using load_cache(). This will speed up network instantiation as long as the architecture does not change too much.

Parameters

path (str, optional) – the path to the file with discretizations.

load_cache(path='./.e2cnn_cache/diffops.pickle')[source]

Load cached PDO discretizations from disk. The cache should have been previously created using store_cache().

Parameters

path (str, optional) – the path to the file with discretizations.