add some documentation

doc/sphinx/src/databox.rst

@@ -22,17 +22,34 @@ To use databox, simply include the relevant header:
   The default type can be set to type ``float`` if the preprocessor
   macro ``SINGLE_PRECISION_ENABLED`` is defined.
 
- Any arithmetic type is supported, although the code has
-only been tested carefully with floating point numbers. To set
-``DataBox`` to a single type, you may wish to declare a type alias
-such as:
+Any arithmetic type is supported, although the code has only been
+tested carefully with floating point numbers. To set ``DataBox`` to a
+single type, you may wish to declare a type alias such as:
 
 .. code-block:: cpp
 
    using DataBox = Spiner::DataBox<double>
 
-In C++17 and later, you can also get the default type specialization
-by simply omitting the template arguments.
+Spiner is also templated on how the interpolation gridding works. This
+template parameter is called ``Grid_t``. The available options at this time are:
+
+* ``Spiner::RegularGrid1D<T>``
+* ``Spiner::PiecewiseGrid1D<T>``
+
+where here ``T`` is the arithmetic type as discussed above. The
+default type is ``RegularGrid1D``. You can further alias ``DataBox``
+as, for example:
+
+.. code-block:: cpp
+
+   using DataBox = Spiner::DataBox<double, Spiner::RegularGrid1D<double>>;
+
+More detail on the interpolation gridding is available below and in
+the interpolation section.
+
+.. note::
+   In C++17 and later, you can also get the default type specialization
+   by simply omitting the template arguments.
 
 .. note::
   In the function signatures below, GPU/performance portability
@@ -43,7 +60,7 @@ by simply omitting the template arguments.
    In the function signatures below, we will often refer to the type
    ``Real`` and the type ``T``. These are both references to the
    underlying templated arithmetic type.
-
+   
 Creating a ``DataBox``
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -307,9 +324,15 @@ a "type," represented as an ``enum class``, ``IndexType``. Currently
 the type can be either ``Interpolated`` or ``Indexed``. When a new
 ``DataBox`` is created, all dimensions are set to
 ``IndexType::Indexed``. A dimension can be set to ``Interpolated`` via
-the ``setRange`` method:
+the ``setRange`` method.
+
+.. cpp:function:: void DataBox::setRange(int i, Grid_t g);
+
+where here ``i`` is the dimension and ``g`` is the gridding object for
+this index. In the default setup, where grids are uniformly spaced
+(i.e., you use a ``RegularGrid1D``), this is:
 
-.. cpp:function:: void DataBox::setRange(int i, T min, T max, int N) const;
+.. cpp:function:: void DataBox::setRange(int i, T min, T max, int N);
    
 where here ``i`` is the dimension, ``min`` is the minimum value of the
 independent variable, ``max`` is the maximum value of the indpendent
@@ -319,19 +342,12 @@ dimension. (Here ``T`` is the underlying templated data type.)
 .. note::
   In these routines, the dimension is indexed from zero.
 
-This information can be recovered via the ``range`` getter method:
-
-.. cpp:function:: void DataBox::range(int i, T &min, T &max, T &dx, int &N) const;
-
-where here ``min``, ``max``, ``dx``, and ``N`` are filled with the values
-for a given dimension.
-
 .. note::
-  There is a lower-level object, ``RegularGrid1D``, which represents
-  these interpolation ranges internally. There are setter and getter
-  methods ``setRange`` and ``range`` that work with the
-  ``RegularGrid1D`` class directly. For more details, see the
-  relevant documentation.
+  There is a set of lower-level objects, ``RegularGrid1D``, and
+  ``PiecewiseGrid1D``, which represent these interpolation ranges
+  internally. There is a getter method ``range`` that works
+  with the underlying ``Grid_t`` class directly. For
+  more details, see the relevant documentation.
 
 It's often desirable to have multiple databoxes with the exact same
 shape and interpolation structure (i.e., independent variable

doc/sphinx/src/interpolation.rst

@@ -3,24 +3,39 @@
 Gridding for Interpolation
 ===========================
 
-Spiner performs interpolation on uniform, Cartesian-product
-grids. There is a lower-level object, ``RegularGrid1D`` which contains
-the metadata required for these operations. ``RegularGrid1D`` has a
-few useful userspace functions, which are described here.
+nSpiner performs interpolation on Cartesian-product
+grids. There are two lower-level objects:
 
-Like ``DataBox``, the ``RegularGrid1D`` object is templated on
+* ``RegularGrid1D``
+* ``PiecewiseGrid1D``
+
+These objects contain the metadata required for interpolation
+operations and have a few useful userspace functions, which are
+described here.
+
+Like ``DataBox``, these grid objects are templated on
 underlying data type, the default type being a ``Real`` as provided by
 ``ports-of-call``. You may wish to specialize to a specific type with
 a type alias such as:
 
 .. code-block:: cpp
 
    using RegularGrid1D = Spiner::RegularGrid1D<double>;
+   using PiecewiseGrid1D = Spiner::PiecewiseGrid1D<double>;
 
 .. note::
    In the function signature below we refer to ``T`` and ``Real`` as
    the underlying arithmetic data type.
 
+When constructing a ``DataBox``, you may wish to specify which
+interpolation object you are using. It is a template parameter.
+
+``RegularGrid1D``
+------------------
+
+We begin by discussing ``RegularGrid1D``, as the ``PiecewiseGrid1D``
+object is built on top of it.
+
 Construction
 ^^^^^^^^^^^^^
 
@@ -44,36 +59,120 @@ returns a "physical" position on the grid given an index ``i``.
 
 The function
 
-.. cpp:function:: int index(const T x) const;
+.. cpp:function:: int RegularGrid1D::index(const T x) const;
+
+returns the index on the grid of a "physical" value ``x``.
+
+The function
+
+.. cpp:function:: T RegularGrid1D::min() const;
+
+returns the minimum value on the independent variable grid.
+
+The function
+
+.. cpp:function:: T RegularGrid1D::max() const;
+
+returns the maximum value on the independent variable grid.
+
+The function
+
+.. cpp:function:: T RegularGrid1D::dx() const;
+
+returns the grid spacing for the independent variable.
+
+The function
+
+.. cpp:function:: int RegularGrid1D::nPoints() const;
+
+returns the number of points in the independent variable grid.
+
+The ``PiecewiseGrid1D``
+------------------------
+
+A ``PiecewiseGrid1D`` is a non-intersecting, contiguous, ordered
+collection ``RegularGrid1D`` s. It can be used to construct grids with
+non-uniform spacing, so long as the grid spacing is piecewise
+constant.
+
+The maximum number of ``RegularGrid1D``s that can be used to construct
+a ``PiecewiseGrid1D`` is a compile-time parameter (default is 5). You
+can specify a different value with, e.g.,
+
+.. code-block:: cpp
+
+   // Maximum number of "pieces" in a grid = 10
+   using PiecewiseGrid1D = Spiner::PiecewiseGrid1D<double, 10>;
+
+Constructiong a ``PiecewiseGrid1D``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``PiecewiseGrid1D`` is constructed from either a ``std::vector`` or
+a ``std::initializer_list`` of ``RegularGrid1D`` s. For example:
+
+.. code-block:: cpp
+
+   // Initialize the regular grids
+   // Note that the start and end points match
+   // for each consecutive pair of grids.
+   // g1 ends when g2 starts, etc.
+   Spiner::RegularGrid1D<double> g1(0, 0.25, 3);
+   Spiner::RegularGrid1D<double> g2(0.25, 0.75, 11);
+   Spiner::RegularGrid1D<double> g3(0.75, 1, 7);
+
+   // Build the piecewise grid. The double bracket notation
+   // is an "initalizer list" and is very convenient,
+   // as it is a C++ language feature.
+   Spiner::PiecewiseGrid1D<double> h = {{g1, g2, g3}};
+
+Default constructors and copy constructors are also provided.
+
+Index Mapping with ``PiecewiseGrid1D``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``PiecewiseGrid1D`` has all the same functionality as
+``RegularGrid1D``, but it automatically uses the relevant underlying
+grid spacing.
+
+The function
+
+.. cpp:function:: T PiecewiseGrid1D::x(const int i) const;
+
+returns a "physical" position on the grid given an index ``i``.
+
+The function
+
+.. cpp:function:: int PiecewiseGrid1D::index(const T x) const;
 
 returns the index on the grid of a "physical" value ``x``.
 
 The function
 
-.. cpp:function:: T min() const;
+.. cpp:function:: T PiecewiseGrid1D::min() const;
 
 returns the minimum value on the independent variable grid.
 
 The function
 
-.. cpp:function:: T max() const;
+.. cpp:function:: T PiecewiseGrid1D::max() const;
 
 returns the maximum value on the independent variable grid.
 
 The function
 
-.. cpp:function:: T dx() const;
+.. cpp:function:: T PiecewiseGrid1D::dx() const;
 
 returns the grid spacing for the independent variable.
 
 The function
 
-.. cpp:function:: int nPoints() const;
+.. cpp:function:: int PiecewiseGrid1D::nPoints() const;
 
 returns the number of points in the independent variable grid.
 
+
 Developer functionality
-^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------
 
 For developers, additional functionality is available. Please consult
 the code.

spiner/databox.hpp

@@ -295,8 +295,6 @@ class DataBox {
     return dataView_.GetSizeInBytes();
   }
   PORTABLE_INLINE_FUNCTION int dim(int i) const { return dataView_.GetDim(i); }
-  PORTABLE_INLINE_FUNCTION void range(int i, T &min, T &max, T &dx,
-                                      int &N) const;
   PORTABLE_INLINE_FUNCTION Grid_t range(int i) const;
   PORTABLE_INLINE_FUNCTION IndexType indexType(const int i) const {
     return indices_[i];
@@ -868,17 +866,6 @@ PORTABLE_INLINE_FUNCTION T DataBox<T, Grid_t, Concept>::max() const {
   return max;
 }
 
-template <typename T, typename Grid_t, typename Concept>
-PORTABLE_INLINE_FUNCTION void
-DataBox<T, Grid_t, Concept>::range(int i, T &min, T &max, T &dx, int &N) const {
-  assert(0 <= i && i < rank_);
-  assert(indices_[i] == IndexType::Interpolated);
-  min = grids_[i].min();
-  max = grids_[i].max();
-  dx = grids_[i].dx();
-  N = grids_[i].nPoints();
-}
-
 template <typename T, typename Grid_t, typename Concept>
 PORTABLE_INLINE_FUNCTION Grid_t
 DataBox<T, Grid_t, Concept>::range(int i) const {