Extending documentation

docs/glossary.rst

@@ -6,6 +6,17 @@ Glossary
 
 .. glossary::
 
+    Acceleration Structure
+        A general term for ray tracing data structures that are used to accelerate 
+        ray tracing operations by partitioning geometric primitives (i.e. faces/elements) 
+        in a way that allows for efficient traversal and intersection testing.
+
+    BLAS
+        Bottom-Level Acceleration Structure. A lower-level acceleration
+        structure, commonly a BVH, built over mesh primitives such as triangles.
+        In a two-level ray tracing acceleration structure, BLAS instances are
+        referenced by a :term:`TLAS`.
+
     BVH
         Bounding Volume hierarchy
 
@@ -29,40 +40,65 @@ Glossary
     `DAGMC <https://svalinn.github.io/DAGMC/index.html>`_
         Direct Accelerated Geometry Monte Carlo toolkit
 
-    FEA
-        Finite Element Analysis
+    `Double-Down <https://double-down.readthedocs.io/en/latest/>`_
+        A ray tracing extension for DAGMC that provides support for double-precision
+        ray tracing on CAD-based geometries using Intel Embree.
 
-    `MOAB <https://sigma.mcs.anl.gov/moab-library/>`_
-        Mesh-Oriented datABase
+    `DPRT <https://github.com/NVIDIA/deepeeRT>`_
+        DeePeeRT (Double Precision Ray Tracing Toolkit) - A "Basics-only" Ray Tracing Library
+        intended specifically for Double-Precision Ray Tracing being developed by NVIDIA.
 
-    `OpenMC <https://docs.openmc.org>`_
-        An open-source Monte Carlo code for neutron and photon transport.
+    `Embree <https://www.embree.org/>`_
+        A collection of high-performance CPU ray tracing kernels developed by Intel.
 
     EntitySet
         An arbitrary collection of entities in MOAB, including other
         `EntitySet`'s. Parent-child relationships between `EntitySet`'s can also
         be established. Synonymous with the term :term:`MeshSet`.
 
+    FEA
+        Finite Element Analysis
+
+    `GPRT <https://github.com/gprt-org/GPRT>`_
+        General Purpose Raytracing Toolkit - A vulkan based GPU accelerated ray tracing
+        library capable of both GPU software and hardware accelerated ray tracing.
+
+    `libMesh <https://libmesh.github.io/>`_
+        A C++ finite element library that provides a framework for the
+        development of parallel adaptive finite element methods.
+
     MeshSet
         A collection of entities in MOAB. Synonymous with :term:`EntitySet`.
 
-    Tag
-        A named data field that can be associated with entities in MOAB. Each
-        tag has an immutable data type. The size of the data can be fixed or
-        variable.
+    `MOAB <https://sigma.mcs.anl.gov/moab-library/>`_
+        Mesh-Oriented datABase
 
-    `GPRT <https://github.com/gprt-org/GPRT>`_
-        General Purpose Raytracing Toolkit
+    `OpenMC <https://docs.openmc.org>`_
+        An open-source Monte Carlo code for neutron and photon transport.
 
-    XDG
-        Accelerated Discretized Geometry
+    RT hardware acceleration
+        The use of specialized hardware, such as dedicated ray tracing cores,
+        avalaible on GPUs to signifciantly accelerate ray tracing operations.
+        Such hardware can perform ray-triangle intersections and BVH traversal
+        much faster than even GPU software implementations of ray tracing algorithms.
+        However, they are limited to single precision support and often require
+        vendor-specific APIs to target.
 
     subdomain
         A region of a mesh that is bounded by surfaces. In the context of XDG,
         a subdomain is a region of a mesh that is bounded by surfaces that are
         treated as interfaces between different materials. Also refferred to as
         a mesh block.
 
-    `libMesh <https://libmesh.github.io/>`_
-        A C++ finite element library that provides a framework for the
-        development of parallel adaptive finite element methods.
+    Tag
+        A named data field that can be associated with entities in MOAB. Each
+        tag has an immutable data type. The size of the data can be fixed or
+        variable.
+
+    TLAS
+        Top-Level Acceleration Structure. A higher-level acceleration structure
+        built over one or more :term:`BLAS` instances. A TLAS is used to cull
+        larger groups of geometry before traversing the lower-level structures.
+
+    XDG
+        Accelerated Discretized Geometry

docs/intro/index.rst

@@ -22,3 +22,4 @@ libraries include:
     - `MOAB <https://sigma.mcs.anl.gov/moab-library/>`_
     - `MFEM <https://mfem.org/>`_
 
+XDG is not a meshing library and as such does not provide any meshing capabilities.

docs/methods/acceleration_data_structures.rst

@@ -1,21 +1,70 @@
-
-
 Acceleration Data Structures
 ============================
 
-XDG relies primarily on the bounding volume hierarchy (BVH) data structure for
-accelerating ray tracing operations. The BVH is a hierarchical data structure that
-organizes primitives (mesh elements) in a scene into a tree of bounding volumes.
-The BVH is used to accelerate ray intersection tests by allowing the ray to
-quickly traverse the tree and only test intersections with primitives that are
-likely to be hit.
+Ray tracing against a mesh becomes expensive if every ray is tested against every
+primitive. A model with many triangles, tetrahedra, or other mesh elements needs
+an acceleration structure so most primitives can be rejected before the more
+expensive ray-primitive intersection tests are performed.
+
+XDG relies primarily on :term:`BVH`-based acceleration structures. In keeping
+with the XDG design philosophy (:ref:`design_philosophy`), these structures are
+built and traversed by the selected ray tracing backend, which is separable from
+the supported mesh backends. On CPUs, XDG currently relies on the :term:`Embree`
+ray tracing kernels for BVH construction and traversal.
+
+Axis-Aligned Bounding Boxes
+---------------------------
+
+The basic building block of these data structures is an axis-aligned bounding
+box (AABB). An AABB is a conservative box around a primitive or group of
+primitives, aligned with the coordinate axes. Ray-box intersection is much
+cheaper than ray-primitive intersection, so a ray that misses an AABB can skip
+everything inside it.
+
+.. figure:: ../assets/AABB.png
+   :alt: Axis-aligned bounding box around a primitive
+   :align: center
+   :width: 45%
+
+   Axis-aligned bounding boxes provide simple bounding volumes for ray
+   intersection tests.
+
+Bottom-Level Acceleration Structures
+------------------------------------
+
+A :term:`BLAS` is a lower-level acceleration structure built over the
+primitives of one piece of geometry. In practice, this is commonly a BVH:
+leaf nodes reference primitives, while internal nodes store AABBs that enclose
+their child nodes. Traversal starts at the root of the tree and only descends
+into child boxes that the ray intersects. The diagram below shows a simple BLAS
+with AABBs at each node and triangles at the leaves:
+
+.. figure:: ../assets/BLAS.png
+   :alt: Bottom-level acceleration structure diagram
+   :align: center
+   :width: 100%
+
+   A BLAS partitions geometry into a hierarchy of bounding volumes.
+
+Top-Level Acceleration Structures
+---------------------------------
+
+Many ray tracing libraries use a two-level acceleration structure made from a
+:term:`TLAS` and one or more :term:`BLAS`\s. The TLAS itself contains only
+references to these BLASs, which means individual BLASs can be used across
+multiple TLASs. Since they reference the whole data
+structure rather than individual mesh primitives, a ray can first traverse the
+TLAS and reject whole sections of geometry if it misses the associated BLAS. It
+then only traverses into the relevant BLASs that the ray intersects,
+making tree traversal more efficient after large regions have already been
+culled by TLAS traversal. The diagram below shows a simple TLAS with two BLASs:
 
-Based on the XDG design philosophy (see :ref:`design_philosophy`), the BVH is
-constructed by leveraging state-of-the-art ray tracing libraries. On CPUs, XDG
-relies on the Embree ray tracing kernels for BVH construction and traversal. On
-GPUs, XDG relies on :term:`GPRT` as a vendor-agnostic interface for ray tracing
-pipelines that can leverage the GPU's hardware acceleration for BVH construction
-or modern software-based implementations of BVH traversal.
+.. figure:: ../assets/TLAS-krhonos.png
+   :alt: Khronos top-level acceleration structure diagram
+   :align: center
+   :width: 100%
+
+   Khronos illustration of a TLAS over lower-level BLASs.
 
 Mixed Precision Ray Tracing
 ===========================
@@ -37,4 +86,106 @@ in terms of performance.
 .. [1] P. Shriwise, P. Wilson, A. Davis, P. Romano, "Hardware-Accelerated Ray
        Tracing of CAD-Based Geometry for Monte Carlo Radiation Transport," in
        *IEEE Computing in Science and Engineering*, vol. 24, no. 2, pp. 52-61,
-       February 2022, doi: 10.1109/MCSE.2022.3154656.
+       February 2022, doi: 10.1109/MCSE.2022.3154656.
+
+GPU-Accelerated Ray Tracing
+===========================
+
+Ray tracing as a technique is highly parallelizable and has been extensively
+optimized for GPU architectures in the context of graphics rendering. As a
+result, there is a rich ecosystem of GPU-accelerated software and even
+specialized hardware (see :term:`RT hardware acceleration`) for ray tracing
+operations. Historically, these capabilities have focused on single-precision
+support and have not typically been adopted in the scientific computing
+community.
+
+XDG is intended to support GPU acceleration and provide an interface for
+leveraging GPU-accelerated ray tracing in scientific computing applications.
+An explicit focus is being placed on vendor-agnostic GPU support to ensure that
+XDG can be used across a wide range of hardware platforms. Currently, initial
+scoping of the GPU API is underway with work being done to support :term:`GPRT`
+(General Purpose Ray Tracing Toolkit), a Vulkan-based GPU-only ray tracing
+library that is vendor-agnostic and built around the Vulkan API. Other GPU ray
+tracing libraries will also be explored in the future, with the eventual goal of
+providing complete feature parity between CPU and GPU backends of XDG.
+
+Backend Terminology Mapping
+---------------------------
+
+The BLAS/TLAS terminology is useful for describing the common two-level
+acceleration structure pattern, but XDG does not require every backend to expose
+explicit BLAS and TLAS objects. In XDG's Embree backend, ``RTCGeometry`` maps
+functionally to a BLAS and ``RTCScene`` maps functionally to a TLAS. Embree
+still builds the concrete acceleration structures internally when those objects
+are committed, and the current XDG Embree backend attaches geometries directly
+to scenes rather than using Embree instance geometries. Conceptually, the
+BLAS/TLAS terminology still applies, while a GPU library like GPRT represents
+the BLAS/TLAS and instancing model more explicitly.
+
+For :term:`surface tracking`, XDG traces against the boundary surfaces of a
+topological volume where each surface has its own BLAS:
+
+.. list-table:: Surface tracking acceleration structure mapping
+   :header-rows: 1
+   :widths: 24 38 38
+
+   * - Concept
+     - Embree
+     - GPRT
+   * - **TLAS**
+     - ``RTCScene`` containing ``RTCGeometry`` BLAS for each of the volume's
+       boundary surfaces
+     - ``GPRTAccel`` containing ``gprt::Instance`` objects for the
+       ``GPRTAccel`` BLASs of the volume's boundary surfaces
+   * - **BLAS**
+     - ``RTCGeometry`` with user-defined AABBs over surface primitives
+     - ``GPRTAccel`` created from a ``GPRTGeom`` with user-defined AABBs
+       over surface primitives
+   * - **Instancing**
+     - Not used currently; ``RTCGeometry`` objects are attached directly to
+       ``RTCScene`` objects
+     - ``gprt::Instance`` objects created from BLASs and used with the TLAS
+   * - **Topological volume**
+     - Per-volume ``RTCScene`` containing the boundary-surface geometries
+     - TLAS over the BLASs for the volume's boundary surfaces
+   * - **Topological surface**
+     - Cached ``RTCGeometry`` over the surface's triangle faces
+     - ``GPRTGeomOf<DPTriangleGeomData>`` and ``GPRTAccel`` BLAS over the
+       surface's triangle faces
+
+For :term:`volume tracking`, XDG traces against the volumetric elements inside a
+topological volume where each volume has exactly one BLAS containing all of its
+elements. In the current Embree backend this is a one-geometry-per-scene
+mapping. Volumetric tracking has not been implemented with GPRT yet, so the
+table below reflects the intended TLAS/BLAS mapping:
+
+.. list-table:: Volume tracking acceleration structure mapping
+   :header-rows: 1
+   :widths: 24 38 38
+
+   * - Concept
+     - Embree
+     - GPRT
+   * - **TLAS**
+     - ``RTCScene`` containing a single ``RTCGeometry`` for the volume's
+       elements
+     - ``GPRTAccel`` containing a ``gprt::Instance`` object for the
+       volume-element ``GPRTAccel`` BLAS
+   * - **BLAS**
+     - ``RTCGeometry`` with user-defined AABBs over volumetric elements
+     - ``GPRTAccel`` created from a ``GPRTGeom`` with user-defined AABBs
+       over volumetric elements
+   * - **Instancing**
+     - Not used currently; the volume ``RTCGeometry`` is attached directly to
+       the volume ``RTCScene``
+     - ``gprt::Instance`` object created from the volume-element BLAS and used
+       with the TLAS
+   * - **Topological volume**
+     - Per-volume ``RTCScene`` containing a single ``RTCGeometry`` for the
+       volume's elements
+     - TLAS over the volume-element BLAS instance
+   * - **Topological surface**
+     - Part of the topology, but not represented in this volume-element
+       BLAS/TLAS mapping
+     - Part of the topology, but not represented in the volume-element
+       BLAS/TLAS mapping

docs/methods/design_philosophy.rst

@@ -3,7 +3,20 @@
 XDG Design Philosophy
 =====================
 
-The primary design goals of XDG are centered on the following:
+The design of XDG has been largely influenced by the history of DAGMC's design. 
+XDG's design builds upon the success of DAGMC with an extensible design for multiple 
+ray tracers and mesh libraries. The XDG architecture diagram below shows how those 
+responsibilities are organized:
+
+.. figure:: ../assets/xdg_architecture.png
+   :alt: XDG architecture diagram
+   :align: center
+   :width: 100%
+
+   High-level XDG design architecture diagram
+
+
+The primary design goals of XDG are centered on the following core ideas:
 
 - **Mesh Library Abstraction**: all mesh-based operations in XDG are
   abstracted through a common interface, the ``MeshManagerInterface``. This
@@ -26,16 +39,16 @@ The primary design goals of XDG are centered on the following:
   core XDG codebase. This is important for one of XDG's primary goals: to
   support ray tracing on both CPUs and GPUs in a single binary.
 
-A live updated UML diagram of the current XDG class hierarchy is shown below:
+For historical context, DAGMC's design and its interaction with the subsequent
+:term:`double-down` extension help explain why XDG adopts these abstractions.
+That earlier design was more tightly coupled to :term:`MOAB`, and the ray tracing
+path through :term:`double-down` was less extensible being a direct interface only
+to the :term:`Embree` ray tracing kernels. The older DAGMC/double-down layout is 
+also shown below for comparison:
 
-.. raw:: html
+.. figure:: ../assets/dagmc_architecture_split.png
+   :alt: Historical DAGMC architecture diagram
+   :align: center
+   :width: 100%
 
-    <div style="max-width: 800px; margin: auto;">
-        <iframe 
-            src="https://viewer.diagrams.net/?tags=%7B%7D&lightbox=1&highlight=000000&edit=_blank&layers=1&nav=1&title=xdg-uml.drawio&dark=0#Uhttps%3A%2F%2Fdrive.google.com%2Fuc%3Fid%3D1jOOYsrMjI29D81mtemU_79hzjtlid_aa%26export%3Ddownload" 
-            width="100%" 
-            height="600" 
-            frameborder="0" 
-            style="border: 1px solid #ccc; border-radius: 6px;">
-        </iframe>
-    </div>
+   Historical DAGMC design architecture with the double-down ray tracing extension