diff --git a/docs/assets/AABB.png b/docs/assets/AABB.png new file mode 100644 index 00000000..b27dacf3 Binary files /dev/null and b/docs/assets/AABB.png differ diff --git a/docs/assets/BLAS.png b/docs/assets/BLAS.png new file mode 100644 index 00000000..f6e8dd67 Binary files /dev/null and b/docs/assets/BLAS.png differ diff --git a/docs/assets/TLAS-krhonos.png b/docs/assets/TLAS-krhonos.png new file mode 100644 index 00000000..b4f85fb5 Binary files /dev/null and b/docs/assets/TLAS-krhonos.png differ diff --git a/docs/assets/dagmc_architecture_split.png b/docs/assets/dagmc_architecture_split.png new file mode 100644 index 00000000..6a43dec5 Binary files /dev/null and b/docs/assets/dagmc_architecture_split.png differ diff --git a/docs/assets/xdg_architecture.png b/docs/assets/xdg_architecture.png new file mode 100644 index 00000000..980b8062 Binary files /dev/null and b/docs/assets/xdg_architecture.png differ diff --git a/docs/glossary.rst b/docs/glossary.rst index 461eff91..110eeff2 100644 --- a/docs/glossary.rst +++ b/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,33 +40,49 @@ Glossary `DAGMC `_ Direct Accelerated Geometry Monte Carlo toolkit - FEA - Finite Element Analysis + `Double-Down `_ + A ray tracing extension for DAGMC that provides support for double-precision + ray tracing on CAD-based geometries using Intel Embree. - `MOAB `_ - Mesh-Oriented datABase + `DPRT `_ + DeePeeRT (Double Precision Ray Tracing Toolkit) - A "Basics-only" Ray Tracing Library + intended specifically for Double-Precision Ray Tracing being developed by NVIDIA. - `OpenMC `_ - An open-source Monte Carlo code for neutron and photon transport. + `Embree `_ + 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 `_ + General Purpose Raytracing Toolkit - A vulkan based GPU accelerated ray tracing + library capable of both GPU software and hardware accelerated ray tracing. + + `libMesh `_ + 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 `_ + Mesh-Oriented datABase - `GPRT `_ - General Purpose Raytracing Toolkit + `OpenMC `_ + 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, @@ -63,6 +90,15 @@ Glossary treated as interfaces between different materials. Also refferred to as a mesh block. - `libMesh `_ - 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 diff --git a/docs/intro/index.rst b/docs/intro/index.rst index 1c5d34d8..4d882f44 100644 --- a/docs/intro/index.rst +++ b/docs/intro/index.rst @@ -22,3 +22,4 @@ libraries include: - `MOAB `_ - `MFEM `_ +XDG is not a meshing library and as such does not provide any meshing capabilities. \ No newline at end of file diff --git a/docs/methods/acceleration_data_structures.rst b/docs/methods/acceleration_data_structures.rst index 1ab2ce2d..fefd54ff 100644 --- a/docs/methods/acceleration_data_structures.rst +++ b/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. \ No newline at end of file + 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`` 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 diff --git a/docs/methods/design_philosophy.rst b/docs/methods/design_philosophy.rst index a6494577..e570f913 100644 --- a/docs/methods/design_philosophy.rst +++ b/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% -
- -
+ Historical DAGMC design architecture with the double-down ray tracing extension