updated docs for gspace. Fix #28

docs/source/api/escnn.gspaces.rst

@@ -9,6 +9,9 @@ This subpackage implements G-spaces as a user interface for defining spaces and
 The user typically instantiates a subclass of :class:`~escnn.gspaces.GSpace` to specify the symmetries considered and uses
 it to instantiate equivariant neural network modules (see :doc:`escnn.nn`).
 
+Generally, the user does not need to manually instantiate :class:`~escnn.gspaces.GSpace` or its subclasses.
+Instead, we provide a few :ref:`factory functions <factory-functions-gspaces>` with simpler interfaces which can be
+used to directly instantiate the most commonly used symmetries.
 
 This subpackage depends on :doc:`escnn.group` and :doc:`escnn.kernels`.
 
@@ -28,11 +31,59 @@ convolutional filters in :class:`~escnn.nn.R3Conv` which should be equivariant t
 (e.g. when choosing the rotation axis for :func:`~escnn.gspaces.rot2dOnR3`).
 
 
+
+.. note::
+    Note that gspaces describing planar rotational symmetries (e.g. :func:`~escnn.gspaces.rot2dOnR2`,
+    :func:`~escnn.gspaces.rot2dOnR3` or :func:`~escnn.gspaces.flipRot2dOnR2`) have an argument `N` which can be used to
+    specify a discretization of the continuous rotational symmetry to integer multiples of :math:`\frac{2\pi}{N}`.
+    However, this is generally not possible in 3D gspaces (e.g. :func:`~escnn.gspaces.rot3dOnR3`).
+
+    The reason why :func:`~escnn.gspaces.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 :ref:`factory functions <factory-functions-gspaces>` 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 :func:`~escnn.gspaces.rot2dOnR2`.
+    Conversely, since there are only a few options in 3D, we provide a different method for each of them
+    (e.g. :func:`~escnn.gspaces.icoOnR3` or :func:`~escnn.gspaces.octaOnR3`).
+
+    Alternatively, it is always possible to leverage the :meth:`~escnn.gspaces.GSpace.restrict` method to generate
+    smaller symmetries.
+    For instance, one can build a gspace with all rotational symmetries (:math:`\SO3`) with
+    :func:`~escnn.gspaces.rot3dOnR3` and then restrict it to a particular subgroup (identified by a subgroup id `sgid`,
+    see Subgroup Structure in :class:`~escnn.group.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 :math:`\SO3` (or other groups) while trying
+    to **preserve the full rotational equivariance**, we recommend choosing :func:`~escnn.gspaces.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 :class:`~escnn.nn.FourierPointwise` or
+    :class:`~escnn.nn.FourierELU`.
+    In this case, the steerable features of a network are interpreted as the Fourier coefficients of a continuous
+    feature over the full :math:`\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 :math:`\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 :math:`\SO3` (as well as other groups) by using the
+    :meth:`~escnn.group.Group.grid` method of each group.
+
+
+
 .. contents:: Contents
     :local:
     :backlinks: top
 
 
+.. _factory-functions-gspaces:
+
 Factory Methods
 ---------------
 

escnn/gspaces/gspace.py

@@ -91,9 +91,9 @@ def __init__(self, fibergroup: escnn.group.Group, dimensionality: int, name: str
         self._fields_intertwiners_basis_memory_fiber_basis = dict()
 
     def type(self, *representations: escnn.group.Representation) -> escnn.nn.FieldType:
-        f"""
+        r"""
             Shortcut to build a :class:`~escnn.nn.FieldType`.
-            This is equivalent to ```FieldType(gspace, representations)```.
+            This is equivalent to ``FieldType(gspace, representations)``.
         """
         return escnn.nn.FieldType(self, representations)