documentation tweaks

docs/source/conf.py

@@ -12,10 +12,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from nifty4 import *
 import sys
 import os
-
 import sphinx_rtd_theme
 
 
@@ -79,8 +77,8 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'NIFTy2go'
-copyright = u'2013-2017, Max-Planck-Society'
+project = u'NIFTy4'
+copyright = u'2013-2018, Max-Planck-Society'
 author = u'Theo Steininger / Martin Reinecke'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -177,7 +175,7 @@ html_logo = 'nifty_logo_white.png'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/source/index.rst

@@ -15,6 +15,14 @@ Documentation
 
 Welcome to NIFTy's documentation!
 
+Contents
+........
+
+.. toctree::
+   :maxdepth: 1
+
+   ift
+   start
 
 Indices and tables
 ..................

docs/source/start.rst

+.. _informal_label:
+
+First steps -- An informal introduction
+=======================================
+
+NIFTy4 Tutorial
+---------------
+
+.. currentmodule:: nifty4
+
+.. automodule:: nifty4
+
+NIFTy4 enables the programming of grid and resolution independent algorithms. In particular for signal inference algorithms, where a continuous signal field is to be recovered, this freedom is desirable. This is achieved with an object-oriented infrastructure that comprises, among others, abstract classes for :ref:`Spaces <spaces>`, :ref:`Fields <fields>`, and :ref:`Operators <operators>`. All those are covered in this tutorial.
+
+You should be able to import NIFTy4 like this after a successful `installation <install.html>`_.
+
+>>> import nifty4 as ift
+
+.. _spaces:
+
+Spaces
+......
+
+The very foundation of NIFTy4's framework are spaces, all of which are derived from the :py:class:`DomainObject` class.
+
+A space can be either unstructured or live on a geometrical manifold; the former case is supported by objects of type :py:class:`FieldArray`, while the latter must be derived from :py:class:`Space` (both of which are in turn derived from :py:class:`DomainObject`).
+Examples for structured spaces are
+
+- :py:class:`RGSpace` (an equidistant Cartesian grid with a user-definable number of dimensions),
+- :py:class:`GLSpace` (a Gauss-Legendre grid on the sphere), and
+- :py:class:`LMSpace` (a grid storing spherical harmonic coefficients).
+
+
+Domains
+-------
+
+A field can live on a single space, but it can also live on a product of spaces (or no space at all, in which case it is a scalar).
+The set of spaces on which a field lives is a called a _domain_ in NIFTy terminology; it is described by a :py:class:`DomainTuple` object.
+
+.. _fields:
+
+Fields
+------
+
+A field object is specified by
+
+- a domain in form of a :py:class:`DomainTuple` object
+- a data type (e.g. numpy.float64)
+- an array containing the actual values
+
+Fields support arithmetic operations, contractions, etc.
+
+.. _operators:
+
+Operators
+---------
+

nifty4/minimization/conjugate_gradient.py

@@ -31,7 +31,7 @@ class ConjugateGradient(Minimizer):
 
     Parameters
     ----------
-    controller : IterationController
+    controller : :py:class:`nifty4.IterationController`
         Object that decides when to terminate the minimization.
 
     References

nifty4/operators/fft_operator.py

@@ -28,9 +28,11 @@ class FFTOperator(LinearOperator):
     """Transforms between a pair of position and harmonic domains.
 
     Built-in domain pairs are
+
       - a harmonic and a non-harmonic RGSpace (with matching distances)
       - a HPSpace and a LMSpace
       - a GLSpace and a LMSpace
+
     Within a domain pair, both orderings are possible.
 
     The operator provides a "times" and an "adjoint_times" operation.

nifty4/spaces/power_space.py

@@ -24,6 +24,9 @@ from .. import dobj
 class PowerSpace(Space):
     """NIFTy class for spaces of power spectra.
 
+    A power space is the result of a projection of a harmonic space where
+    k-modes of equal length get mapped to one power index.
+
     Parameters
     ----------
     harmonic_partner : Space
@@ -41,11 +44,6 @@ class PowerSpace(Space):
             of the last bin, i.e. thee will be len(binbounds)+1 bins in total,
             with the first and last bins reaching to -+infinity, respectively.
         (default : None)
-
-    Notes
-    -----
-    A power space is the result of a projection of a harmonic space where
-    k-modes of equal length get mapped to one power index.
     """
 
     _powerIndexCache = {}
@@ -53,15 +51,16 @@ class PowerSpace(Space):
     @staticmethod
     def linear_binbounds(nbin, first_bound, last_bound):
         """
+        This will produce a binbounds array with nbin-1 entries with
+        binbounds[0]=first_bound and binbounds[-1]=last_bound and the remaining
+        values equidistantly spaced (in linear scale) between these two.
+
         nbin: integer
             the number of bins
         first_bound, last_bound: float
             the k values for the right boundary of the first bin and the left
             boundary of the last bin, respectively. They are given in length
             units of the harmonic partner space.
-        This will produce a binbounds array with nbin-1 entries with
-        binbounds[0]=first_bound and binbounds[-1]=last_bound and the remaining
-        values equidistantly spaced (in linear scale) between these two.
         """
         nbin = int(nbin)
         assert nbin >= 3, "nbin must be at least 3"
@@ -70,16 +69,17 @@ class PowerSpace(Space):
     @staticmethod
     def logarithmic_binbounds(nbin, first_bound, last_bound):
         """
+        This will produce a binbounds array with nbin-1 entries with
+        binbounds[0]=first_bound and binbounds[-1]=last_bound and the remaining
+        values equidistantly spaced (in natural logarithmic scale)
+        between these two.
+
         nbin: integer
             the number of bins
         first_bound, last_bound: float
             the k values for the right boundary of the first bin and the left
             boundary of the last bin, respectively. They are given in length
             units of the harmonic partner space.
-        This will produce a binbounds array with nbin-1 entries with
-        binbounds[0]=first_bound and binbounds[-1]=last_bound and the remaining
-        values equidistantly spaced (in natural logarithmic scale)
-        between these two.
         """
         nbin = int(nbin)
         assert nbin >= 3, "nbin must be at least 3"