Finish documentation for gradient testing (for now)

Author: max-veit

Diff for: docs/Doxyfile.in

@@ -792,7 +792,7 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 ## this is for read the docs, which builds in-place
-INPUT                  = @CMAKE_SOURCE_DIR@/src @CMAKE_SOURCE_DIR@/bindings @CMAKE_CURRENT_BINARY_DIR@
+INPUT                  = @CMAKE_SOURCE_DIR@/src @CMAKE_SOURCE_DIR@/tests @CMAKE_SOURCE_DIR@/bindings @CMAKE_CURRENT_BINARY_DIR@
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

Diff for: docs/source/reference/cpp.rst

@@ -51,12 +51,14 @@ Math utilities (namespace :cpp:class:`rascal::math`)
 Gradient tests (developer)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. cpp:namespace:: rascal
+
 All representations in libRascal should implement, or plan to implement,
 gradients (derivatives w.r.t. the Cartesian positions of all the atoms) so that
 they can be used to run dynamics.  This is often a complex and error-prone task,
 so a finite-difference gradient checker is provided to check the gradients of
-any representation calculator -- or any math function in general -- and ensure
-that the analytical and finite-difference gradients match up.
+any representation calculator -- or any mathematical function in general -- and
+ensure that the analytical and finite-difference gradients match up.
 
 To check the gradient of a new representation calculator, it should suffice to
 use the classes RepresentationManagerGradientCalculator (to provide the function
@@ -67,13 +69,44 @@ below, excerpted from :file:`tests/test_calculator.cc`:
 .. literalinclude:: ../../../tests/test_calculator.cc
    :language: cpp
    :lines: 430-436, 441-444
-   :dedent: 2
+   :dedent: 4
+
+where :cpp:var:`representations.back()` is a
+:cpp:class:`RepresentationCalculator`,
+:cpp:var:`manager` is a :cpp:class:`StructureManager`, and
+:cpp:var:`structures.back()` is the :cpp:class:`AtomicStructure` associated with
+that manager.
+
+A more detailed documentation of these two classes follows:
+
+.. doxygenclass:: rascal::RepresentationManagerGradientCalculator
+   :project: rascal
+   :members:
+
+.. doxygenclass:: rascal::RepresentationManagerGradientFixture
+   :project: rascal
+   :members:
+
+For testing the gradient of arbitrary functions :math:`f: \mathbb{R}^m
+\rightarrow \mathbb{R}^n`, the function :cpp:func:`test_gradients` is
+provided:
+
+.. doxygenfunction:: test_gradients
+   :project: rascal
+
+An example generalized gradient test fixture is provided by
+:cpp:class:`GradientTestFixture`:
 
+.. doxygenclass:: rascal::GradientTestFixture
+   :project: rascal
+   :members:
 
 Index
 ~~~~~
 
  .. doxygennamespace:: rascal
     :project: rascal
     :members:
+    :outline:
+    :no-link:
 

Diff for: tests/test_adaptor_center_contribution.cc

@@ -1,5 +1,5 @@
 /**
- * file   test_adaptor_center_contribution.cc
+ * @file   test_adaptor_center_contribution.cc
  *
  * @author Felix Musil <[email protected]>
  *

Diff for: tests/test_calculator.cc

@@ -1,5 +1,5 @@
 /**
- * file   test_calculator.cc
+ * @file   test_calculator.cc
  *
  * @author Musil Felix <[email protected]>
  *

Diff for: tests/test_calculator.hh

@@ -820,8 +820,8 @@ namespace rascal {
   /**
    * Test fixture holding the gradient calculator and structure manager
    *
-   * Holds data (i.e. function values, gradient directions) and iterates through
-   * the list of centers
+   * Holds data (function values, gradient directions, verbosity) and iterates
+   * through the list of centers
    */
   template <typename RepCalculator_t, class StructureManager_t>
   class RepresentationManagerGradientFixture : public GradientTestFixture {
@@ -833,6 +833,16 @@ namespace rascal {
 
     static const size_t n_arguments = 3;
 
+    /**
+     * Initialize a gradient test fixture
+     *
+     * @param filename JSON file holding gradient test parameters, format
+     *                 documented in GradientTestFixture
+     *
+     * @param structure StructureManager on which to test
+     *
+     * @param calc RepresentationCalculator whose gradient is being tested
+     */
     RepresentationManagerGradientFixture(
         std::string filename, std::shared_ptr<StructureManager_t> structure,
         Calculator_t & calc)

Diff for: tests/test_kernels.cc

@@ -1,5 +1,5 @@
 /**
- * file test_kernels.cc
+ * @file test_kernels.cc
  *
  * @author Felix Musil <[email protected]>
  *

Diff for: tests/test_kernels.hh

@@ -1,5 +1,5 @@
 /**
- * file test_kernels.hh
+ * @file test_kernels.hh
  *
  * @author Felix Musil <[email protected]>
  *

Diff for: tests/test_manager_collection.cc

@@ -1,5 +1,5 @@
 /**
- * file test_manager_collection.cc
+ * @file test_manager_collection.cc
  *
  * @author Felix Musil <[email protected]>
  *

Diff for: tests/test_manager_collection.hh

@@ -1,5 +1,5 @@
 /**
- * file test_manager_collection.hh
+ * @file test_manager_collection.hh
  *
  * @author Felix Musil <[email protected]>
  *

Diff for: tests/test_math.hh

@@ -148,7 +148,7 @@ namespace rascal {
   };
 
   /**
-   * Fixture for testing a the gradient of a real function of N real arguments
+   * Fixture for testing the gradient of a real function of N real arguments
    *
    * (Verifies that the gradient is the same as the converged value of the
    * finite-difference approximation along the given directions)
@@ -166,6 +166,9 @@ namespace rascal {
    * @param displacement_directions List of vectors along which to displace the
    *                                inputs, in case "direction_mode" is
    *                                "Provided".
+   *
+   * @param verbosity Level of verbosity to use when printing test info, as
+   *        string ("NORMAL", "INFO", or "DEBUG")
    */
   class GradientTestFixture {
    public:
@@ -222,10 +225,14 @@ namespace rascal {
       return directions;
     }
 
+    /** Levels of verbosity for the gradient test */
     enum struct VerbosityValue {
-      NORMAL = 0,  // Print nothing
-      INFO = 10,   // Print one line of info for each gradient step
-      DEBUG = 20   // Print as much as possible
+      /** Print nothing */
+      NORMAL = 0,
+      /** Print one line of info for each gradient step */
+      INFO = 10,
+      /** Print as much as possible */
+      DEBUG = 20
     };
 
     static VerbosityValue get_verbosity(json & input_data) {
@@ -304,18 +311,18 @@ namespace rascal {
    * The function_calculator object may be of any type, as long as it provides
    * two functions, f() and grad_f(), to calculate the function and its gradient
    * (derivative for functions with one input, Jacobian for functions with
-   * multiple outputs -- the output dimension is expected to correspond to
+   * multiple outputs - the output dimension is expected to correspond to
    * columns).  Both functions must accept an Eigen::Vector, corresponding to
    * the function input, of dimension determined in the data file (read by
    * GradientTestFixture).  This function additionally guarantees that f() will
    * be called before grad_f() with the same input.
    *
-   * If the functions f() and grad_f() are designed to accept fixed-size vectors
-   * (i.e. if the size of the argument is known at compile time), be sure to
-   * define, in the FunctionProvider class, a
-   * `constexpr static size_t n_arguments` member with the size of the argument
-   * vector.  This will ensure that the gradient tester uses the corresponding
-   * fixed-size Eigen vectors/matrices as inputs.
+   * @note If the functions f() and grad_f() are designed to accept fixed-size
+   * vectors (i.e. if the size of the argument is known at compile time), be
+   * sure to define, in the FunctionProvider class, a `constexpr static size_t
+   * n_arguments` member with the size of the argument vector.  This will ensure
+   * that the gradient tester uses the corresponding fixed-size Eigen
+   * vectors/matrices as inputs.
    */
   template <typename FunctionProvider_t, typename TestFixture_t>
   void test_gradients(FunctionProvider_t function_calculator,

Diff for: tests/test_math_gauss_legendre.cc

@@ -1,5 +1,5 @@
 /**
- * file   test_math_gauss_legendre.cc
+ * @file   test_math_gauss_legendre.cc
  *
  * @author  Felix Musil <[email protected]>
  *

Diff for: tests/test_math_modified_bessel_first_kind.cc

@@ -1,5 +1,5 @@
 /**
- * file   test_math_modified_bessel_first_kind.cc
+ * @file   test_math_modified_bessel_first_kind.cc
  *
  * @author  Felix Musil <[email protected]>
  *

Diff for: tests/test_math_spherical_harmonics.cc

@@ -1,5 +1,5 @@
 /**
- * file   test_math_spherical_harmonics.cc
+ * @file   test_math_spherical_harmonics.cc
  *
  * @section LICENSE
  *

Diff for: tests/test_properties.cc

@@ -1,5 +1,5 @@
 /**
- * file   test_properties.cc
+ * @file   test_properties.cc
  *
  * @author Till Junge <[email protected]>
  *

Diff for: tests/test_species_manager.cc

@@ -1,5 +1,5 @@
 /**
- * file    test_species_manager.cc
+ * @file    test_species_manager.cc
  *
  * @author Markus Stricker <[email protected]>
  * @author Till Junge <[email protected]>