Add release notes and update documentation

Author: sethrj

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+    # You can also specify other tool versions:
+    # nodejs: "16"
+    # rust: "1.55"
+    # golang: "1.17"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: doc/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+formats:
+   - pdf

CONTRIBUTING.rst

@@ -10,7 +10,31 @@ developed primarily by a group of U.S. Department of Energy subcontractors, our
 goal is to increase community involvement and integration over time. We welcome
 your contributions!
 
-.. note:: This document is a work in progress.
+
+Copyright
+---------
+
+All submissions to the Celeritas project are automatically licensed under the
+terms of [the project copyright](COPYRIGHT) as formalized by the [GitHub terms
+of service](https://docs.github.com/en/github/site-policy/github-terms-of-service#6-contributions-under-repository-license).
+
+
+Development prerequisites
+-------------------------
+
+To meet the :ref:`formatting` requirements described in the development guide,
+make sure that `clang-format`_ is installed on your development
+Run ``scripts/dev/install-commit-hooks.sh`` to to install a git post-commit hook
+that will amend each commit with clang-format updates if necessary.
+
+A mostly consistent set of decorations (separators, Doxygen comment structure,
+etc.) are used throughout the code, so try to make new files look like existing
+ones. Use the ``celeritas-gen.py`` script (in the ``scripts/dev`` directory) to
+generate skeletons for new files, and use existing source code as a guide to
+how to structure the decorations.
+
+.. _clang-format: https://clang.llvm.org/docs/ClangFormat.html
+
 
 Pull request process
 --------------------
@@ -48,11 +72,12 @@ For example, some of the configurations currently fail due to disk space issues.
 Since there are few enough merge requests these days, only Maintainers may
 commit a merge.
 
+
 Ownership and Authorship
 ------------------------
 
-The person who writes a line of code is its author. However, Celeritas is a
-collaborative project with collective ownership: as much as possible, there
-should be a shared responsibility for the code. If the code is reviewed
-according to the guidelines above, at least two people should always be
-comfortable modifying any piece of code.
+The person who writes a line of code is its author but not its owner.
+Celeritas is a collaborative project with collective ownership: as much as
+possible, there should be a shared responsibility for the code.
+If the code is reviewed according to the guidelines above, at least two people
+should always be comfortable modifying any piece of code.

README.md

@@ -4,29 +4,13 @@ The Celeritas project implements HEP detector physics on GPU accelerator
 hardware with the ultimate goal of supporting the massive computational
 requirements of LHC-HL upgrade.
 
-# Installation and development
+# Installation
 
-This project requires external dependencies to build with full functionality.
-However, any combination of these requirements can be omitted to enable
-limited development on personal machines with fewer available components.
-
-- [CUDA](https://developer.nvidia.com/cuda-toolkit): on-device computation
-- an MPI implementation (such as [Open MPI](https://www.open-mpi.org)): distributed-memory parallelism
-- [ROOT](https://root.cern): I/O
-- [nljson](https://github.com/nlohmann/json): simple text-based I/O for
-  diagnostics and program setup
-- [VecGeom](https://gitlab.cern.ch/VecGeom/VecGeom): on-device navigation of GDML-defined detector geometry
-- [Geant4](https://geant4.web.cern.ch/support/download): preprocessing physics data for a problem input
-- [G4EMLOW](https://geant4.web.cern.ch/support/download): EM physics model data
-- [HepMC3](http://hepmc.web.cern.ch/hepmc/): Event input
-- [SWIG](http://swig.org): limited set of Python wrappers for analyzing input
-  data
-
-Build/test dependencies are:
-
-- [CMake](https://cmake.org): build system
-- [clang-format](https://clang.llvm.org/docs/ClangFormat.html): formatting enforcement
-- [GoogleTest](https://github.com/google/googletest): test harness
+This project requires external dependencies such as CUDA to build with full
+functionality.  However, any combination of these requirements can be omitted
+to enable limited development on personal machines with fewer available
+components. See [the infrastructure documentation](doc/infrastructure.rst) for
+details on installing.
 
 ## Installing with Spack
 
@@ -35,32 +19,19 @@ includes numerous scientific packages, including those used in HEP. An included
 Spack "environment" (at `scripts/dev/env/celeritas-{platform}.yaml`) defines
 the required prerequisites for this project.
 
-The script at `scripts/dev/install-spack.sh` provides a "one-button solution"
-to installing and activating the Spack prerequisites for building Celeritas.
-Alternatively, you can manually perform the following steps:
-- Clone Spack following its [getting started instructions](https://spack.readthedocs.io/en/latest/getting_started.html)
-- Add CUDA to your `$SPACK_ROOT/etc/spack/packages.yaml` file
-- Run `spack env create celeritas scripts/dev/env/celeritas-linux.yaml` (or
-  replace `linux` with `darwin` if running on a mac); then `spack -e
-  celeritas concretize` and `spack -e celeritas install`
-- Run and add to your startup environment profile `spack env activate
-  celeritas`
-- Configure Celeritas by creating a build directory and running CMake (or
-  `ccmake` for an interactive prompt for configuring options).
+- Clone Spack following its [getting started instructions][1]
+- To install with CUDA, run `spack external find cuda` and
+  `spack install celeritas +cuda cuda_arch=<ARCH>`, where `<ARCH>` is the
+  numeric portion of the [CUDA architecture flags][2]
 
-An example file for a `packages.yaml` that defines an externally installed CUDA
-on a system with an NVIDIA GPU that has architecture capability 3.5 is thus:
-```yaml
-packages:
-  cuda:
-    paths:
-      [email protected]: /usr/local/cuda-10.2
-    buildable: False
-  all:
-    variants: cuda_arch=35
-```
+[1](https://spack.readthedocs.io/en/latest/getting_started.html)
+[2](https://arnon.dk/matching-sm-architectures-arch-and-gencode-for-various-nvidia-cards/)
 
-## Configuring and building Celeritas
+## Configuring and building Celeritas manually
+
+The spack environment at [dev/scripts.yaml](dev/scripts.yaml) lists the full
+dependencies used by the CI for building, testing, and documenting. Install
+those dependencies via spack or independently, then configure Celeritas.
 
 To configure Celeritas, assuming the dependencies you want are located in the
 `CMAKE_PREFIX_PATH` search path, and other environment variables such as `CXX`
@@ -71,57 +42,16 @@ $ cd build && cmake ..
 $ make
 ```
 
-Ideally you will build Celeritas with all dependencies to gain the full
-functionality of the code, but there are circumstances in which you may not
-have all the dependencies or features available. By default, the CMake code in
-Celeritas queries available packages and sets several `CELERITAS_USE_{package}`
-options based on what it finds, so you have a good chance of successfully
-configuring Celeritas on the first go. Two optional components,
-`CELERITAS_BUILD_<DEMOS|TESTS>`, will error in the configure if their required
-components are missing, but they will update the CMake cache variable so that
-the next configure will succeed (but with that component disabled).
-
-For a slightly more advanced but potentially simpler setup, you can use the
-CMake presets provided by Celeritas via the `CMakePresets.json` file for CMake
-3.21 and higher:
-```console
-$ cmake --preset=default
-```
-The three main options are "minimal", "default", and "full", which all set
-different expectations for available dependencies.
-
-If you want to add your own set of custom options and flags, create a
-`CMakeUserPresets.json` file or, if you are a developer, create a preset at
-`scripts/cmake-presets/${HOSTNAME%%.*}.json` and call `scripts/build.sh
-{preset}` to create the symlink, configure the preset, build, and test. See
-[the scripts readme](scripts/README.md) for more details.
-
-If your CMake version is too old, you may get an unhelpful message:
-```
-CMake Error: Could not read presets from celeritas: Unrecognized "version" field
-```
-which is just a poor way of saying the version in the `CMakePresets.json` file
-is newer than that version knows how to handle.
-
-## Commit hooks
-
-Run `scripts/dev/install-commit-hooks.sh` to install a git post-commit hook
-that will amend each commit with clang-format updates if necessary.
-
-## Contributing
-
-See the [development wiki
-page](https://github.com/celeritas-project/celeritas/wiki/Development) for
-guidelines and best practices for code in the project.
+# Development
 
-The [code design
-page](https://github.com/celeritas-project/celeritas/wiki/Code-design) outlines
-the basic physics design philosophy and classes, and [the layout of some
-algorithms and
-classes](https://github.com/celeritas-project/celeritas-docs/tree/master/graphs)
-are available on the `celeritas-docs` repo.
+See the [contribution guide](CONTRIBUTING.rst) for the contribution process,
+and [the development guidelines](doc/appendices/development.rst) for further
+details on coding in Celeritas.
 
-All submissions to the Celeritas project are automatically licensed under the
-terms of [the project copyright](COPYRIGHT) as formalized by the [GitHub terms
-of service](https://docs.github.com/en/github/site-policy/github-terms-of-service#6-contributions-under-repository-license).
+# Documentation
 
+The full code documentation (including API descriptions) is available by
+setting the `CELERITAS_BUILD_DOCS=ON` configuration option. A mostly complete
+version of the [Celeritas
+documentation](https://celeritas.readthedocs.io/en/latest/) is hosted on
+`readthedocs.io`.

doc/appendices/development.rst

@@ -8,9 +8,18 @@
 Development Guide
 *****************
 
+The agility, extensibility, and performance of Celeritas depend strongly on
+software infrastructure and best practices. This appendix describes how to
+modify and extend the codebase.
+
+.. include:: ../../CONTRIBUTING.rst
+
+
+Code development guidelines
+===========================
+
+These are a list of recommendations when writing new code.
 
-Guiding principles
-==================
 
 Maximize encapsulation
 ----------------------
@@ -43,7 +52,7 @@ Applications:
 Examples:
 
 - Random number sampling: write a unit sphere sampling functor instead of
-  replicating a polar-to-cartesian transform in a thousand places.
+  replicating a polar-to-Cartesian transform in a thousand places.
 - Cell IDs: Opaque IDs add type safety so that you can't accidentally convert a
   cell identifier into a double or switch a cell and material ID. It also makes
   code more readable of course.
@@ -52,23 +61,27 @@ Examples:
 Maximize code reuse
 -------------------
 
-No explanation needed.
+Duplicating code means potentially duplicating bugs, duplicating the amount of
+work needed when refactoring, and missing optimizations.
 
 
 Minimize compile time
 ---------------------
 
 Code performance is important but so is developer time. When possible,
 minimize the amount of code touched by NVCC. (NVCC's error output is also
-rudimentary compared to modern clang/gcc, so that's another reason to prefer
+rudimentary compared to modern clang/GCC, so that's another reason to prefer
 them compiling your code.)
 
+
 Prefer single-state classes
 ---------------------------
 
 As much as possible, make classes "complete" and valid after calling the
-constructor. Don't have a series of functions that have to be called in a
-specific order to put the class in a workable state.  (And when it is not possible,  code must be put in place to automatically detect (and warn the developer) if the specific order is not respected).
+constructor. Try to avoid "finalize" functions that have to be called in a
+specific order to put the class in a workable state. If a finalize function
+*is* used, implement assertions to detect and warn the developer if the
+required order is not respected.
 
 When a class has a single function (especially if you name that function
 ``operator()``), its usage is obvious. The reader also doesn't have to know
@@ -78,6 +91,7 @@ When you have a class that needs a lot of data to start in a valid state, use a
 ``struct`` of intuitive objects to pass the data to the class's constructor.
 The constructor can do any necessary validation on the input data.
 
+
 Learn from the pros
 -------------------
 
@@ -97,9 +111,9 @@ Test thoroughly
 Functions should use programmatic assertions whenever assumptions are made:
 
 - Use the ``CELER_EXPECT(x)`` assertion macro to test preconditions about
-  incoming data or initial internal states
+  incoming data or initial internal states.
 - Use ``CELER_ASSERT(x)`` to express an assumption internal to a function (e.g.,
-  "this index is not out of range of the array")
+  "this index is not out of range of the array").
 - Use ``CELER_ENSURE(x)`` to mark expectations about data being returned from a
   function and side effects resulting from the function.
 
@@ -118,6 +132,7 @@ Implementation detail classes (in the ``celeritas::detail`` namespace, in
 testing the detail classes is a good way to simplify edge case testing compared
 to testing the higher-level code.
 
+
 Style guidelines
 ================
 
@@ -132,6 +147,8 @@ became the style standard for the GPU-enabled Monte Carlo code `Shift`_.
 .. _Tom Evans: https://github.com/tmdelellis
 .. _Shift: https://doi.org/10.1016/j.anucene.2019.01.012
 
+.. _formatting:
+
 Formatting
 ----------
 
@@ -141,11 +158,15 @@ code windows to be open side-by-side. Generally, statements longer than 80
 columns should be broken into sub-expressions for improved readability anyway
 -- the ``auto`` keyword can help a lot with this.
 
+Run ``scripts/dev/install-commit-hooks.sh`` to to install a git post-commit hook
+that will amend each commit with clang-format updates if necessary.
+
 There's a certain amount of decorations (separators, Doxygen comment structure,
 etc.) that is standard throughout the code. Use the ``celeritas-gen.py`` script
 (in the ``scripts/dev`` directory) to generate skeletons for new files, and use
 existing source code as a guide to how to structure the decorations.
 
+
 Symbol names
 ------------
 
@@ -161,14 +182,15 @@ verb. For example::
    ModelEvaluator evaluate_something(parameters...);
    auto result = evaluate_something(arguments...);
 
-There are many opportunities to use `OpaqueId` in GPU code to indicate
+There are many opportunities to use ``OpaqueId`` in GPU code to indicate
 indexing into particular vectors. To maintain consistency, we let an
-index into a vector of `Foo` have a corresponding OpaqueId type::
+index into a vector of ``Foo`` have a corresponding ``OpaqueId``  type::
 
     using FooId = OpaqueId<Foo>;
 
-and ideally be defined either immediately after `Foo` or in a `Types.hh` file.
-Some OpaqueId types may have only a "symbolic" corresponding type, in which case
+and ideally be defined either immediately after ``Foo`` or in a
+:file:`Types.hh` file.  Some ``OpaqueId`` types may have only a "symbolic"
+corresponding type, in which case
 a tag struct can be be defined inline::
 
    using BarId = OpaqueId<struct Bar>;
@@ -208,6 +230,7 @@ Some files have special extensions:
 - ``.test.cc`` are unit test executables corresponding to the main ``.cc``
   file. These should only be in the main ``/test`` directory.
 
+
 Device compilation
 ------------------
 
@@ -260,6 +283,7 @@ Use scoped enumerations (``enum class``) where possible (named like classes) so
 their values can safely be named like member variables (lowercase with
 underscores).
 
+
 Function arguments and return values
 ------------------------------------
 
@@ -321,6 +345,7 @@ with the standard library. (It's also possible to have ``template <typename``
 where ``typename`` *doesn't* mean a class: namely,
 ``template <typename U::value_type Value>``.)
 
+
 Data management
 ===============
 
@@ -378,7 +403,3 @@ View
    mass of a particle (constant, set by the model) and the speed (variable,
    depends on particle track state).
 
-
-.. include:: ../../CONTRIBUTING.rst
-
-