Add additional documentation about fields (celeritas-project#1066)

* Improve field documentation

* Try reusing workflow code with `env`

* filter on label instead of branch name

* Fix documentation

* Fix names and address feedback

.github/workflows/doc.yml

@@ -7,6 +7,14 @@ concurrency:
   group: doc-${{github.ref}}-${{github.event.pull_request.number || github.run_number}}-${{github.workflow}}
   cancel-in-progress: true
 
+env:
+  celer_upload_doc:  >-
+    ${{  github.ref_name == 'develop'
+      || contains(github.ref_name, 'backports/')
+      || contains(github.head_ref, 'release-')
+      || contains(github.event.pull_request.labels.*.name, 'documentation')
+    }}
+
 jobs:
   dev:
     runs-on: ubuntu-latest
@@ -39,12 +47,7 @@ jobs:
         run: |
           ninja doxygen
       - name: Upload pages artifacts
-        if: >-
-          ${{  github.ref_name == 'develop'
-            || contains(github.ref_name, 'backports/')
-            || contains(github.head_ref, 'release-')
-            || contains(github.head_ref, 'doc-')
-          }}
+        if: ${{env.celer_upload_doc}}
         id: upload-pages-user
         uses: actions/upload-pages-artifact@v2
         with:
@@ -82,12 +85,7 @@ jobs:
         run: |
           ninja doc
       - name: Upload pages artifacts
-        if: >-
-          ${{  github.ref_name == 'develop'
-            || contains(github.ref_name, 'backports/')
-            || contains(github.head_ref, 'release-')
-            || contains(github.head_ref, 'doc-')
-          }}
+        if: ${{env.celer_upload_doc}}
         id: upload-pages-user
         uses: actions/upload-pages-artifact@v2
         with:

doc/main/api/accel.rst

@@ -28,7 +28,7 @@ provided.
 
 The SetupOptionsMessenger can be instantiated with a reference to a global
 SetupOptions instance in order to provide a Geant4 "UI" macro interface to an
-app's celeritas options.
+app's Celeritas options.
 
 .. doxygenclass:: celeritas::SetupOptionsMessenger
    :members: none
@@ -47,6 +47,8 @@ settings.
 
 .. doxygenclass:: celeritas::UniformAlongStepFactory
 
+.. doxygenclass:: celeritas::RZMapFieldAlongStepFactory
+
 Detailed interface
 ------------------
 
@@ -66,3 +68,17 @@ Interface utilities
 .. doxygenclass:: celeritas::ExceptionConverter
 
 .. doxygenclass:: celeritas::AlongStepFactoryInterface
+
+
+Classes usable by Geant4
+------------------------
+
+These utilities are based on Celeritas data structures and capabilities but are
+written to be usable both by the ``celer-g4`` app and potential other users.
+
+.. doxygenclass:: celeritas::GeantSimpleCalo
+
+.. doxygenclass:: celeritas::HepMC3PrimaryGenerator
+
+.. doxygenclass:: celeritas::RZMapMagneticField
+

doc/main/api/celeritas.rst

@@ -75,6 +75,52 @@ On-device access
 
 .. doxygenclass:: celeritas::PhysicsTrackView
 
+Propagation and magnetic field
+------------------------------
+
+The propagation interface is built on top of the geometry to allow both curved
+and straight-line movement. Field propagation is based on a composition of:
+
+Field
+  Maps a point in space and time to a field vector.
+Equation of motion
+  Calculates the path derivative of position and momentum given their current
+  state and the templated field.
+Integrator
+  Numerically integrates a new position/momentum state given the start,
+  path derivative, and step length.
+Driver
+  Integrate path segments that satisfy certain error conditions, solving for
+  the required segment length.
+Propagator
+  Given a maximum physics step, advance the geometry state and momentum along
+  the field lines, satisfying constraints (see :ref:`field driver
+  options<api_field_data>`) for the maximum geometry error.
+
+Propagation
+~~~~~~~~~~~
+
+.. doxygenclass:: celeritas::LinearPropagator
+
+.. doxygenclass:: celeritas::FieldPropagator
+
+.. doxygenfunction:: celeritas::make_mag_field_propagator
+
+.. _api_field_data:
+
+Field data input and options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. doxygenstruct:: celeritas::FieldDriverOptions
+
+Field data
+~~~~~~~~~~
+
+These classes correspond to JSON input files to the field setup.
+
+.. doxygenstruct:: celeritas::UniformFieldParams
+
+.. doxygenstruct:: celeritas::RZMapFieldInput
 
 .. _celeritas_random:
 

doc/main/usage.rst

@@ -83,8 +83,8 @@ library with a short standalone CMake project.
 Standalone simulation app (celer-sim)
 =====================================
 
-The ``celer-sim`` application is the primary means of running test problems for
-independent validation and performance analysis.
+The ``celer-sim`` application is the primary means of running EM test problems
+for independent validation and performance analysis.
 
 Usage::
 
@@ -139,10 +139,17 @@ Usage::
   celer-g4 {input}.json
            {commands}.mac
            --interactive
+           --dump-default
 
 Input
 -----
 
+Physics is set up using the top-level ``physics_option`` key in the JSON input,
+corresponding to :ref:`api_geant4_physics_options`. The magnetic field is
+specified with a combination of the ``field_type``, ``field``, and
+``field_file`` keys, and detailed field driver configuration options are set
+with ``field_options`` corresponding to the ``FieldOptions`` class in :ref:`api_field_data`.
+
 .. note:: The macro file usage is in the process of being replaced by JSON
    input for improved automation.
 

src/celeritas/field/DormandPrinceStepper.hh

@@ -57,6 +57,8 @@ namespace celeritas
      y_{n+1/2}   = y_n + (h/2) \Sigma_{n=1}^{7} c^{*}_i k_i
    \f]
  * with the coefficients \f$c^{*}\f$ taken from L. F. Shampine (1986).
+ *
+ * \todo Rename DormandPrinceIntegrator
  */
 template<class EquationT>
 class DormandPrinceStepper
@@ -93,7 +95,7 @@ CELER_FUNCTION DormandPrinceStepper(EquationT&&)->DormandPrinceStepper<EquationT
 // INLINE DEFINITIONS
 //---------------------------------------------------------------------------//
 /*!
- * Adaptive step size control for the DormandPrince RK5(4)7M method.
+ * Numerically integrate using the DormandPrince RK5(4)7M method.
  */
 template<class E>
 CELER_FUNCTION auto

src/celeritas/field/RZMapFieldInput.hh

@@ -25,7 +25,8 @@ namespace celeritas
  * The magnetic field is discretized at nodes on an R-Z grid, and each point
  * the field vector is approximated by a 2-D vector in R-Z. The input units of
  * this field are in *NATIVE UNITS* (gauss). An optional \c _units field in the
- * input can specify whether the input is in tesla or native units.
+ * input can specify whether the input is in tesla or native units, with
+ * allowable values of "T", "tesla", "gauss", or "native".
  *
  * The field values are all indexed with R having stride 1: [Z][R]
  */

src/celeritas/field/RungeKuttaStepper.hh

@@ -23,6 +23,26 @@ namespace celeritas
  * the truncation error, with fourth-order accuracy based on description in
  * Numerical Recipes in C, The Art of Scientific Computing, Sec. 16.2,
  * Adaptive Stepsize Control for Runge-Kutta.
+ *
+ * For a magnetic field equation \em f along a charged particle trajectory
+ * with state \em y, which includes position and momentum but may also include
+ * time and spin. For N-variables (\em i = 1, ... N), the right hand side of
+ * the equation
+ * \f[
+ *  \frac{\dif y_{i}}{\dif s} = f_i (s, y_{i})
+ * \f]
+ * and the fouth order Runge-Kutta solution for a given step size, \em h is
+ * \f[
+ *  y_{n+1} - y_{n} = h f(x_n, y_n) = \frac{h}{6} (k_1 + 2 k_2 + 2 k_3 + k_4)
+ * \f]
+ * which is the average slope at four different points,
+ * The truncation error is the difference of the final states of one full step
+ * (\em y1) and two half steps (\em y2)
+ * \f[
+ *  \Delta = y_2 - y_1, y(x+h) = y_2 + \frac{\Delta}{15} + \mathrm{O}(h^{6})
+ * \f]
+ *
+ * \todo Rename RungeKuttaIntegrator
  */
 template<class EquationT>
 class RungeKuttaStepper
@@ -65,25 +85,7 @@ CELER_FUNCTION RungeKuttaStepper(EquationT&&)->RungeKuttaStepper<EquationT>;
 // INLINE DEFINITIONS
 //---------------------------------------------------------------------------//
 /*!
- * Adaptive step size control.
- *
- * For a magnetic field equation \em f along a charged particle trajectory
- * with state \em y, which includes position and momentum but may also include
- * time and spin. For N-variables (\em i = 1, ... N), the right hand side of
- * the equation
- * \f[
- *  \frac{\dif y_{i}}{\dif s} = f_i (s, y_{i})
- * \f]
- * and the fouth order Runge-Kutta solution for a given step size, \em h is
- * \f[
- *  y_{n+1} - y_{n} = h f(x_n, y_n) = \frac{h}{6} (k_1 + 2 k_2 + 2 k_3 + k_4)
- * \f]
- * which is the average slope at four different points,
- * The truncation error is the difference of the final states of one full step
- * (\em y1) and two half steps (\em y2)
- * \f[
- *  \Delta = y_2 - y_1, y(x+h) = y_2 + \frac{\Delta}{15} + \mathrm{O}(h^{6})
- * \f]
+ * Numerically integrate and return the updated state with estimated error.
  */
 template<class E>
 CELER_FUNCTION auto

src/celeritas/field/UniformFieldData.hh

@@ -15,12 +15,14 @@
 namespace celeritas
 {
 //---------------------------------------------------------------------------//
-
+/*!
+ * Input data and options for a uniform field.
+ */
 struct UniformFieldParams
 {
     using Real3 = Array<real_type, 3>;
 
-    Real3 field{0, 0, 0};
+    Real3 field{0, 0, 0};  //!< Field strength (native units)
     FieldDriverOptions options;
 };