From 94391ef312fd8ac34e4653390cbee9ab05db00ca Mon Sep 17 00:00:00 2001 From: "Seth R. Johnson" Date: Mon, 27 Nov 2023 19:51:09 -0500 Subject: [PATCH] Release v0.4.0 (#1031) * Add pull request template and document labels * Add pull request template for releases * Fix documentation * Update latex pdf header to include institutions * Move rst file locations * Add release documentation --- .github/pull_request_template.md | 26 ++ .github/pull_request_template.release.md | 26 ++ CONTRIBUTING.rst | 7 +- doc/CMakeLists.txt | 4 +- doc/_static/ornltm-header-celeritas.tex | 58 +++- .../administration.rst | 119 ++++++++- doc/{appendices => appendix}/development.rst | 0 doc/{appendices => appendix}/license.rst | 0 .../release-history.rst | 1 + .../release-history/v0.1.rst | 0 .../release-history/v0.2.rst | 0 .../release-history/v0.3.rst | 0 doc/appendix/release-history/v0.4.rst | 250 ++++++++++++++++++ doc/conf.py | 9 +- doc/index.rst | 24 +- doc/{ => main}/acknowledgments.rst | 0 doc/{ => main}/api.rst | 0 doc/{ => main}/api/accel.rst | 0 doc/{ => main}/api/celeritas.rst | 0 doc/{ => main}/api/corecel.rst | 0 doc/{ => main}/api/orange.rst | 0 doc/{ => main}/examples.rst | 0 doc/{ => main}/examples/geant4.rst | 6 +- doc/{ => main}/examples/minimal.rst | 6 +- doc/{ => main}/installation.rst | 2 +- doc/{ => main}/introduction.rst | 0 doc/{ => main}/overview.rst | 0 doc/{ => main}/references.rst | 2 +- doc/{ => main}/usage.rst | 0 29 files changed, 489 insertions(+), 51 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 .github/pull_request_template.release.md rename doc/{appendices => appendix}/administration.rst (76%) rename doc/{appendices => appendix}/development.rst (100%) rename doc/{appendices => appendix}/license.rst (100%) rename doc/{appendices => appendix}/release-history.rst (92%) rename doc/{appendices => appendix}/release-history/v0.1.rst (100%) rename doc/{appendices => appendix}/release-history/v0.2.rst (100%) rename doc/{appendices => appendix}/release-history/v0.3.rst (100%) create mode 100644 doc/appendix/release-history/v0.4.rst rename doc/{ => main}/acknowledgments.rst (100%) rename doc/{ => main}/api.rst (100%) rename doc/{ => main}/api/accel.rst (100%) rename doc/{ => main}/api/celeritas.rst (100%) rename doc/{ => main}/api/corecel.rst (100%) rename doc/{ => main}/api/orange.rst (100%) rename doc/{ => main}/examples.rst (100%) rename doc/{ => main}/examples/geant4.rst (88%) rename doc/{ => main}/examples/minimal.rst (82%) rename doc/{ => main}/installation.rst (99%) rename doc/{ => main}/introduction.rst (100%) rename doc/{ => main}/overview.rst (100%) rename doc/{ => main}/references.rst (91%) rename doc/{ => main}/usage.rst (100%) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..0c01ae05a0 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,26 @@ +**Please read, follow, and delete this text** + +# Title + +Should be an imperative statement (title-cased first word, +no trailing punctuation) summarizing its effect on the user. For example: + - Implement the FooBar model *[enhancement, physics]* + - Handle errors in track initialization *[enhancement, orange]* + - Fix sampling of low-energy Celeritons *[bug, physics]* + - Refactor code in preparation for new tracker type *[minor, orange]* + - Add CI support for multiple Geant4 versions *[enhancement, documentation]* + +# Description + +The description should summarize or enumerate the main changes in the pull +request. Illustrative images are recommended if possible! + +# Labels + +If you're a core developer, add one of each label: + +- Change type: {bug, documentation, enhancement, minor} +- Category: {app, core, external, field, orange, performance, physics, + user} + +See [https://github.com/celeritas-project/celeritas/blob/develop/doc/appendices/administration.rst#review-process](review process) for descriptions of the labels and requirements. diff --git a/.github/pull_request_template.release.md b/.github/pull_request_template.release.md new file mode 100644 index 0000000000..2cfa35f3b9 --- /dev/null +++ b/.github/pull_request_template.release.md @@ -0,0 +1,26 @@ + + +**Release branches must be named `release-vX.Y.Z`** + +## Pre-merge checklist + +- [ ] Ensure all CI jobs on develop pass +- [ ] Tag the develop branch with ``vX.Y.Z-rc.N`` where N starts with 1, and increment for every time you return to this step due to new pull requests. +- [ ] Run performance regression tests on Summit, Crusher/Frontier, and an additional machine with debug assertions enabled (e.g., Wildstyle). +- [ ] Update documentation with release notes from all pull requests newly included in the release. +- [ ] Ensure the code documentation builds with as few warnings as possible in the `doc` workflow on the CI. + +## Post-merge checklist + +- [ ] If releasing a backported version branch, cherry-pick this documentation commit into the backport branch. +- [ ] Use the [GitHub interface](https://github.com/celeritas-project/celeritas/releases/new) to create a new release with the documentation update that was just added. + +## Post-release checklist + +- [ ] Save the ``tar.gz`` and attach to the release, because the hash changes if the git "describe" function returns a different result for the release tag's hash (e.g., if a collaborative branch on the main repository points to that commit). +- [ ] Pull locally (make sure to use the ``--tags`` option) and build PDF user documentation for the release. Ensure breathe is activated (so the API is listed) and that the version is embedded correctly. +- [ ] Update the Spack recipe for Celeritas with the new version and sha256 value (either manually or using ``spack checksum``) and submit a [pull request to the Spack project](https://github.com/spack/spack/pull). +- [ ] Mark the GitHub [release milestone](https://github.com/celeritas-project/celeritas/milestones) as completed. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 09f1d586cd..00d43dd1b8 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -74,11 +74,8 @@ and :ref:`style ` guidelines have been followed for all new code and code changes. Ensure the use of the correct formatting as well as the addition of documentation and unit tests for new code and bug fixes. -All tests must pass on the CI runner before a PR can be merged. (Exceptions -will be made if any failures are clearly unrelated to the changes and enough -tests and/or configuration are passing to show that the new code is working. -For example, some of the configurations have a tendency to fail due to disk -space issues.) It's best to test locally first before submitting your pull +All tests must pass on the CI runner before a PR can be merged. It's best to +test locally first before submitting your pull request, and keep in mind that the multiple configurations on the CI (different dependency versions, different features) may reveal failures that your local testing might have missed. diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 1a323750d8..582ca5181e 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -232,8 +232,8 @@ celeritas_build_sphinx(latex "${_doc_tex}") if(Sphinx_FOUND) # Download ornltm class ExternalProject_Add(ornltm - GIT_REPOSITORY https://code.ornl.gov/s3j/ornltm.git - GIT_TAG 05a4b22f104abd53ac7cae72fe03768710b56b86 + GIT_REPOSITORY https://code.ornl.gov/sethrj/ornltm.git + GIT_TAG c9d2ddcce2bfc8d7d51db8f4a131d71883f46528 CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND "" diff --git a/doc/_static/ornltm-header-celeritas.tex b/doc/_static/ornltm-header-celeritas.tex index 355a17bb1b..bf16d567ee 100644 --- a/doc/_static/ornltm-header-celeritas.tex +++ b/doc/_static/ornltm-header-celeritas.tex @@ -1,19 +1,53 @@ \documentclass{ornltm} -\author{Seth R.~Johnson -\and Philippe Canal (FNAL) -\and Julien Esseiva (LBNL) -\and Thomas M.~Evans -\and Soon Yung Jun (FNAL) -\and Guilherme Lima (FNAL) -\and Amanda Lund (ANL) -\and Paul Romano (ANL) -\and Stefano C.~Tognini -\and Ben Morgan (Univeristy of Warwick) +\author{% + Seth R.~Johnson\affilnum{1}% + %% + \and + Elliott Biondo\affilnum{1} + %% + \and + Julien Esseiva\affilnum{4} + %% + \and + Soon Yung Jun\affilnum{2} + %% + \and + Guilherme Lima\affilnum{2} + %% + \and + Amanda Lund\affilnum{3} + %% + \and + Ben Morgan\affilnum{5} + %% + \and + Stefano C.~Tognini\affilnum{1} + %% + \and + Philippe Canal\affilnum{2} + %% + \and + Marcel Demarteau\affilnum{1} + %% + \and + Thomas Evans\affilnum{1} + %% + \and + Paul Romano\affilnum{3} +}% + +\affiliation{% + \affilnum{1}Oak Ridge National Laboratory, Oak Ridge, TN, USA \\ + \affilnum{2}Fermi National Accelerator Laboratory, Batavia, IL, USA \\ + \affilnum{3}Argonne National Laboratory, Lemont, IL, USA \\ + \affilnum{4}Lawrence Berkeley National Laboratory, Berkeley, CA, USA \\ + \affilnum{5}University of Warwick, Coventry, United Kingdom% } + \title{Celeritas User Manual} -\date{Jul.~2023} -\reportnum{ORNL/TM-2023/XXXX} +\date{Jan.~2024} +\reportnum{ORNL/TM-2024/XXXX} \reportdraft \division{Computational Sciences and Engineering Division} diff --git a/doc/appendices/administration.rst b/doc/appendix/administration.rst similarity index 76% rename from doc/appendices/administration.rst rename to doc/appendix/administration.rst index 22ee5721a5..3f59e356bb 100644 --- a/doc/appendices/administration.rst +++ b/doc/appendix/administration.rst @@ -98,8 +98,8 @@ increasing the `bus factor`_. .. _bus factor: https://en.wikipedia.org/wiki/Bus_factor -Review process --------------- +Reviewing pull requests +----------------------- Each pull request must be reviewed by at least one member of the :ref:`core team ` who is knowledgeable about @@ -132,14 +132,110 @@ followed in the new code. Balance the desire for readability with the need to avoid bikeshedding_ by asking yourself whether your requests are substantive enough to merit a new pull request. Perfect is the enemy of good. +Check that the title meets the requirements below, that the description is +adequate, and that the appropriate labels are set. + By the time you've finished the code review, you should understand the code well enough to maintain it (by extension or modification) in the future. .. _bikeshedding: https://thedecisionlab.com/biases/bikeshedding +PR titles +^^^^^^^^^ + +The title should be an imperative statement (title-cased first word, +no trailing punctuation) summarizing its effect on the user. For example: + + - Implement the FooBar model *[enhancement, physics]* + - Handle errors in track initialization *[enhancement, orange]* + - Fix sampling of low-energy Celeritons *[bug, physics]* + - Refactor code in preparation for new tracker type *[minor, orange]* + - Add CI support for multiple Geant4 versions *[enhancement, documentation]* + +Avoid tags in the title. + +PR description +^^^^^^^^^^^^^^ + +The description should summarize or enumerate the main changes in the pull +request. Illustrative images are recommended if possible! + +Label descriptions +^^^^^^^^^^^^^^^^^^ + +The labels_ used in Celeritas GitHub pull requests and issues have specific +meanings. There should be one "change type" and one "category" selected. A few +special labels ("backport", "performance") can also be added when appropriate. + +Change type +""""""""""" + +The change types are used to categorize changes in the release notes. If a pull +request seems like it should have multiple change types, it should probably be +broken up into multiple pull requests. + +Bug + Report or fix an error that a user could encounter. + +Documentation + Add new tests, documentation, or personal user presets *without* any changes + in the library or applications. + +Enhancement + Request or add something new to the code. + +Minor + Refactor code or make small changes that should be effectively invisible to + users and probably not reported. + +Category +"""""""" -Merge process -------------- +These should be fixes, changes, or enhancements to support... + +App + front end applications (``celer-g4`` and ``celer-sim``). + +Core + core infrastructure such as platform portability. + +External + integration with external libraries such as Geant4, VecGeom, and ROOT. + +Field + magnetic field propagation, linear propagation, and safety distance + calculation. + +ORANGE + the Celeritas geometry library for GPU tracking. + +Performance + performance optimization on GPU and CPU. + +Physics + particles, processes, and stepping algorithms. + +User + hits and track diagnostics (i.e., extracting data from tracks running on the + GPU). + + +.. _labels: https://github.com/celeritas-project/celeritas/labels + +Merging +------- + +The GitHub settings for Celeritas currently require that before merging: + +1. The branch must be up-to-date with upstream develop. This ensures that + there are no failures from "implicit" conflicts (where no code actually + generates a git conflict, but some new requirement or change upstream + has not been implemented in the new branch). An "Update branch" button is + available on the pull request page to ensure this requirement is met. +2. The GitHub Action CI checks must pass. There are a small matrix of core + combinations that cover most potential build issues. These do not *execute* + GPU code but they will build it and ensure that the tests pass when + the Celeritas device capability is disabled. Celeritas uses the "squash and merge" process to ensure continuity of the code history and provide easy bisecting because all commits pass all tests. @@ -147,7 +243,11 @@ Squashing eliminates the potential of broken commits and relieves developers of the burden of worrying about clean commit messages within a branch. Since there are few enough merge requests these days, only :ref:`maintainers -` may commit a merge. +` may commit a merge. When merging, check that the commit title matches +the issue title (it may be inconsistent if the branch has only a single +commit), and that the "co-author" tags at the bottom of the commit message +accurately reflect contributions (co-authorship may be erroneously attributed +for a simple merging of the main branch into the development branch). Releases @@ -175,6 +275,9 @@ other major code changes. Release process --------------- +.. ***NOTE*** when changing this section, make sure + ``.github/pull_request_template.release`` is also updated. + Releases can be created from the primary "develop" branch (major, minor, patch) or a "backport" branch (minor, patch). The following process must be followed (and may need iteration to converge) for @@ -193,9 +296,9 @@ each release. `helper notebook`_ in the Celeritas documents repository to automate this. 4. Tag the branch on your fork with ``vX.Y.Z-rc.N`` where N starts with 1, and increment for every time you return to this step due to new pull requests. -5. Run regression tests on Summit (for performance testing), Crusher (for HIP - testing), and an additional machine with debug assertions enabled (e.g., - Wildstyle). +5. Run performance regression tests on Summit (for performance testing), + Crusher/Frontier (for HIP testing), and an additional machine with debug + assertions enabled (e.g., Wildstyle). 6. [TODO: define high-level validation tests like `geant-val`_ and a test matrix correlating capability areas (code files/directories changed) to test names.] Rerun and perform a cursory check on all validation tests that diff --git a/doc/appendices/development.rst b/doc/appendix/development.rst similarity index 100% rename from doc/appendices/development.rst rename to doc/appendix/development.rst diff --git a/doc/appendices/license.rst b/doc/appendix/license.rst similarity index 100% rename from doc/appendices/license.rst rename to doc/appendix/license.rst diff --git a/doc/appendices/release-history.rst b/doc/appendix/release-history.rst similarity index 92% rename from doc/appendices/release-history.rst rename to doc/appendix/release-history.rst index 01ce10b217..5577a5f484 100644 --- a/doc/appendices/release-history.rst +++ b/doc/appendix/release-history.rst @@ -12,6 +12,7 @@ Release History :maxdepth: 2 :caption: Appendices + release-history/v0.4.rst release-history/v0.3.rst release-history/v0.2.rst release-history/v0.1.rst diff --git a/doc/appendices/release-history/v0.1.rst b/doc/appendix/release-history/v0.1.rst similarity index 100% rename from doc/appendices/release-history/v0.1.rst rename to doc/appendix/release-history/v0.1.rst diff --git a/doc/appendices/release-history/v0.2.rst b/doc/appendix/release-history/v0.2.rst similarity index 100% rename from doc/appendices/release-history/v0.2.rst rename to doc/appendix/release-history/v0.2.rst diff --git a/doc/appendices/release-history/v0.3.rst b/doc/appendix/release-history/v0.3.rst similarity index 100% rename from doc/appendices/release-history/v0.3.rst rename to doc/appendix/release-history/v0.3.rst diff --git a/doc/appendix/release-history/v0.4.rst b/doc/appendix/release-history/v0.4.rst new file mode 100644 index 0000000000..bc95821603 --- /dev/null +++ b/doc/appendix/release-history/v0.4.rst @@ -0,0 +1,250 @@ +.. Copyright 2023 UT-Battelle, LLC, and other Celeritas developers. +.. See the doc/COPYRIGHT file for details. +.. SPDX-License-Identifier: CC-BY-4.0 + + +.. _release_v0.4.0: + +Version 0.4.0 +============= + +*Released 2023/11/27* + +Version 0.4.0 is a major update to Celeritas that focuses on performance and +integration with Geant4. It also contains major improvements to the ORANGE +navigation engine. + +This is the first version of ORANGE that supports GPU neutron transport in SCALE. +It is also the first version to fully support integration into ATLAS FullSimLight +and CMSSW. + +Key enhancements compared to version 0.3.2 are: + +- Addition of the single Coulomb scattering process and Wentzel model +- Major performance improvements when running Celeritas to accelerate + multithreaded Geant4 +- Major performance improvements when using ORANGE +- A new ``G4VFastSimulationModel`` interface to Celeritas for offloading tracks + with Geant4 11.1 +- Experimental support for surface-based VecGeom +- Experimental support for Windows and for single-precision arithmetic + +Key changes are: + +- The interface for ``celer-g4`` now takes JSON input and writes JSON output, + as the app is to be less of an example and more of a Celeritas front end to + Geant4 with support for offloading. +- The hit output from ``celer-g4`` has been rewritten so that it can be opened + in downstream applications that have ``celeritas`` in their library path. + + +New features +------------ + +* Launch kernels only with active tracks using "action range" *(@esseivaju, #765)* +* Add utility for constructing SD "force_volumes" option *(@sethrj, #825)* +* Add scoped NVTX ranges for improved profiling *(@esseivaju, #827)* +* Add isotope data to ``MaterialParams`` *(@stognini, #831)* +* Add ``ScopedProfiling`` to device actions *(@esseivaju, #836)* +* Gather and set more Step/Track attributes when calling sensitive detectors *(@sethrj, #839)* +* Add isotope selector *(@stognini, #843)* +* Add a HepMC3 event writer *(@sethrj, #851)* +* Add option to disable Celeritas offloading in celer-g4 *(@amandalund, #860)* +* Add option to dump offloaded tracks as an event file *(@sethrj, #854)* +* Expose SDSetupOptions "enabled" flag in SetupOptionsMessenger *(@drbenmorgan, #859)* +* Add track step counter to celer-g4 *(@amandalund, #862)* +* Define arithmetic operators for Array *(@sethrj, #868)* +* Support Geant4@10.5 *(@sethrj, #869)* +* Add ``__launch_bounds__`` to kernels based on Executor properties *(@esseivaju, #853)* +* Add option to use RZ magnetic field and along step action in the celer-g4 application *(@whokion, #874)* +* Add basic field driver option support to RZ map field *(@sethrj, #880)* +* Implement BIH tree *(@elliottbiondo, #849)* +* Implement new matrix utilities for ORANGE *(@sethrj, #885)* +* Implement remaining quadric surfaces *(@sethrj, #867)* +* Add Wentzel single Coulomb scattering model *(@hhollenb, #861)* +* Accelerate ORANGE track initialization with Bounding Interval Hierarchy *(@elliottbiondo, #881)* +* Implement GPU-compatible transformations with ORANGE *(@sethrj, #872)* +* Add e-/e+ single Coulomb scattering process *(@hhollenb, #899)* +* Add JSON input and more control options to celer-g4 *(@amandalund, #890)* +* Implement surface promotion in ORANGE *(@sethrj, #893)* +* Refactor StepLimit to SoA *(@esseivaju, #901)* +* Implement surface translation and transformation *(@sethrj, #887)* +* Add more bounding box utilities *(@sethrj, #889)* +* Add surface "variant" class for host processing *(@sethrj, #895)* +* Add ROOT-based event exporter *(@stognini, #900)* +* Use radix sort for ordering tracks *(@esseivaju, #903)* +* Implement chained transformations/translations *(@sethrj, #897)* +* Connect ROOT event writer to accel and reader to celer-sim *(@sethrj, #904)* +* Define CELER_ASSUME for simpler always-on compiler assumptions *(@sethrj, #905)* +* Implement surface simplification *(@sethrj, #894)* +* Accelerate ORANGE boundary crossing with BIH *(@elliottbiondo, #909)* +* Add bounding box transformation *(@sethrj, #906)* +* Add surface clipping helper class *(@sethrj, #896)* +* Add option to generate primaries without an event file in celer-g4 *(@amandalund, #914)* +* Automatically calculate ORANGE universe depth *(@elliottbiondo, #915)* +* Use par_nosync execution policy to execute thrust algorithms *(@esseivaju, #908)* +* Implement generic transforms in multi-universe ORANGE *(@sethrj, #917)* +* Implement CSG tree simplification in ORANGE *(@sethrj, #923)* +* Add Windows support *(@sethrj, #930)* +* Add soft equivalence for quadric surfaces *(@sethrj, #933)* +* Add pinned allocator and asynchronous memory operations *(@esseivaju, #910)* +* Add option to disable SD hit collection in celer-g4 *(@amandalund, #943)* +* Define unified tolerances class for ORANGE *(@sethrj, #941)* +* Add timers to celer-g4 *(@amandalund, #944)* +* Implement asynchronous ``DeviceAllocation`` *(@esseivaju, #953)* +* Support energy loss fluctuations in uniform field along-step *(@amandalund, #954)* +* Add collection builder that deduplicates on insertion *(@sethrj, #955)* +* Improve CPU along-step performance *(@amandalund, #961)* +* Implement TrackerVisitor for multiply-dispatched tracker types *(@elliottbiondo, #959)* +* Deduplicate ORANGE geometry on insertion *(@sethrj, #956)* +* Implement CSG tree simplification algorithms *(@sethrj, #939)* +* Improve JSON conversion for bounding box edge cases *(@sethrj, #962)* +* Add unified memory support *(@esseivaju, #965)* +* Implement ScopedProfiling for HIP/ROCM *(@esseivaju, #970)* +* Enable tracking through rectangular arrays *(@elliottbiondo, #973)* +* Export ORANGE input from JSON and add full support for transforms *(@sethrj, #976)* +* Improve Quantity for field conversions and non-real_type use cases *(@sethrj, #987)* +* Adapt to the new BVH navigator from VecGeom *(@mrguilima, #978)* +* Implement concrete G4VFastSimulationModel for offload to Celeritas *(@drbenmorgan, #992)* +* Add compile-time support for single-precision Celeritas *(@sethrj, #988)* +* Implement LdgIterator abstraction *(@esseivaju, #996)* +* Use LdgIterator in Collection and Span *(@esseivaju, #1000)* +* Add ORANGE surface construction components *(@sethrj, #1001)* +* Allow ``celer-g4`` hit output to be opened in downstream ROOT *(@stognini, #999)* +* Add environment variable to disable ROOT and update celer-g4 input *(@sethrj, #1011)* +* Refactor ParticleState and ParticleParams to SoA *(@esseivaju, #1012)* +* Use Celeritas error and output handling in celer-g4 app *(@sethrj, #1013)* +* Add support for VecGeom surface model *(@mrguilima, #1016)* +* Add G4SD "simple calorimeter" that outputs to JSON *(@sethrj, #1014)* +* Optimize data access through ORANGE visitors *(@esseivaju, #1018)* +* Add multithread exception support and logging to Geant4 app *(@sethrj, #1026)* + +Reviewers: @sethrj *(38)*, @elliottbiondo *(19)*, @amandalund *(16)*, @whokion *(5)*, @stognini *(2)*, @hhollenb *(1)*, @drbenmorgan *(1)*, @esseivaju *(1)*, @pcanal *(1)* + +Bug fixes +--------- + +* Fix errors when building and loading Celeritas through CMSSW *(@sethrj, #821)* +* Divide initializer capacity by number of streams in celer-sim *(@amandalund, #824)* +* Fix build errors from Geant4@10 *(@drbenmorgan, #830)* +* Fix default ``combined_brems`` option to work with multiple-element materials *(@sethrj, #837)* +* Fix app/demo-geo-check test failure when using MPI *(@stognini, #838)* +* Unify convergence criteria in field driver *(@sethrj, #829)* +* Fix minor issues with exceptions *(@sethrj, #846)* +* Fix linking errors with CUDA+VecGeom caused by #847 *(@pcanal, #856)* +* Fix inconsistencies in Geant4-to-VecGeom boolean conversion *(@sethrj, #857)* +* Fix HepMC3 reading of vertices and status codes *(@sethrj, #863)* +* Restore "small step updates momentum" condition (part of #875) in field propagator *(@sethrj, #882)* +* Fix sampling of secondary gamma energies in EPlusGGInteractor *(@whokion, #888)* +* Fix multi-level ORANGE direction change *(@tmdelellis, #912)* +* Fix unit conversion errors when reading from event file *(@amandalund, #916)* +* Fix Seltzer-Berger max xs for positrons *(@amandalund, #922)* +* Fix Geant4 step limiter when ionization is disabled *(@amandalund, #920)* +* Fix resetting of CUDA streams when running through accel *(@sethrj, #927)* +* Fix uniform field unit conversion *(@amandalund, #931)* +* Correctly map HepMC3 events to Geant4 events *(@sethrj, #938)* +* Improve and fix Geant4 volume conversion on boundaries *(@sethrj, #936)* +* Fix ORANGE multi-level surface crossing *(@tmdelellis, #929)* +* Fix ORANGE bounding box bumping to be consistent with tracking tolerances *(@sethrj, #940)* +* Fix Geant4 field construction in celer-g4 *(@amandalund, #942)* +* Fix accumulated action times in celer-sim *(@amandalund, #951)* +* Fix using ORANGE geometry with pointer-appended GDML *(@sethrj, #960)* +* Fix performance regression on HIP *(@sethrj, #968)* +* Fix uninitialized memory access in ``TrackInitParams`` *(@amandalund, #974)* +* Run "warmup step" to hide once-off overhead from total run time *(@sethrj, #985)* +* Fix linking to CUDA toolkit when using VecGeom *(@esseivaju, #989)* + +Reviewers: @sethrj *(15)*, @amandalund *(9)*, @esseivaju *(4)*, @whokion *(2)*, @mrguilima *(1)*, @stognini *(1)*, @tmdelellis *(1)* + +Documentation improvements +-------------------------- + +* Document how to link loadable shared libraries with Celeritas *(@drbenmorgan, #842)* +* Extend geometry robustness testing *(@sethrj, #858)* +* Release v0.3.1 *(@sethrj, #876)* +* Fix density correction calculation in Seltzer-Berger test *(@amandalund, #921)* +* Release v0.3.2 *(@sethrj, #925)* +* Update roles to distinguish "core advisor" *(@sethrj, #947)* +* Add environment scripts for exalearn4 *(@esseivaju, #971)* +* Stop previous builds when new changes are pushed *(@aprokop, #997)* +* Fix test build with single precision and disable failing tests *(@sethrj, #998)* +* Add Orange Shift tracking flow control test *(@tmdelellis, #1003)* +* Use consistent energy intervals for model applicability and selection *(@amandalund, #1015)* +* Update cmake presets for Zeus *(@esseivaju, #1028)* + +Reviewers: @sethrj *(7)*, @amandalund *(4)*, @paulromano *(1)*, @pcanal *(1)*, @stognini *(1)* + +Minor internal changes +---------------------- + +* Add field template deduction and parameterized test *(@sethrj, #820)* +* Update CI to VecGeom 1.2.3 *(@sethrj, #819)* +* Improve logger construction and add test helper class *(@sethrj, #826)* +* Hotfix: fix warning when building with Geant4@11 *(@sethrj, #833)* +* Remove variadic templating from track executor *(@sethrj, #832)* +* Refactor hit manager SD mapping *(@sethrj, #835)* +* Apply C++ core guidelines for copy/move assignment/construction *(@esseivaju, #834)* +* Add ``screening_factor`` to ``ImportEmParameters`` *(@stognini, #840)* +* cmake-rdc: add support for MODULE library. *(@pcanal, #848)* +* Add some quality-of-life CMake defaults *(@sethrj, #847)* +* Require semicolon for statement-like CELER_X_COPY_MOVE macros *(@sethrj, #855)* +* Hotfix: fix duplicate HepMC3 symbols by creating a wrapper function *(@sethrj, #865)* +* Fix large function warnings by disabling device debug code by default *(@sethrj, #866)* +* Add PolyEvaluator deduction guides *(@hhollenb, #871)* +* Add thread-safe assertion to RootStepWriter *(@stognini, #873)* +* Export full Celeritas version string as well as defaulted CMake variables *(@sethrj, #870)* +* Reuse chord length between successive field advances *(@sethrj, #875)* +* Improve polynomial deduction guide *(@sethrj, #878)* +* Validate ``KernelParamCalculator`` block size using CUDA/HIP function attributes *(@esseivaju, #877)* +* Refactor and extend BoundingBox *(@elliottbiondo, #879)* +* Allow downstream packages to find a newer version of Celeritas *(@sethrj, #884)* +* Hotfix: fix missing include from #849 *(@stognini, #898)* +* Refactor event IO test for reusability *(@sethrj, #902)* +* Hardcode ``PrimaryGenerator`` RNG engine and inherit from ``EventReaderInterface`` *(@amandalund, #913)* +* Define variant helpers and refactor surface type dispatch *(@sethrj, #911)* +* Use trailing underscore for "sentinel" classes in OpaqueId *(@sethrj, #919)* +* Bikeshedding changes to BIH *(@sethrj, #918)* +* Hotfix: fix crash when running celer-g4 without cuda *(@sethrj, #928)* +* Rewrite soft equality for simplicity *(@sethrj, #932)* +* Optimize ORANGE surface intersection testing *(@sethrj, #934)* +* Hotfix: warning in ipow template instantiation *(@sethrj, #937)* +* Update documentation and precalculate Wenzel nuclear form factor constants *(@sethrj, #926)* +* Use async allocation for temporary track sorting storage. *(@esseivaju, #946)* +* Fix build errors on macOS *(@stognini, #950)* +* Add defaults and runtime checking to primary generator *(@sethrj, #957)* +* Simplify nearly-zero surface displacements to zero *(@sethrj, #945)* +* Avoid maybe_unused attribute because of old GCC *(@sethrj, #952)* +* Fix ORANGE rectangular array construction from SCALE *(@elliottbiondo, #958)* +* Fix build errors in SCALE CI *(@sethrj, #963)* +* Add option to disable track count output in celer-sim *(@amandalund, #964)* +* Hotfix: windows build error and missing bbox construction *(@sethrj, #966)* +* Hotfix: build errors due to ``if constexpr`` on NVCC < 11.5 *(@sethrj, #969)* +* Reorganize JSON input and unit test for ORANGE *(@sethrj, #972)* +* Improve inlining and warning messages for scoped profiling *(@sethrj, #975)* +* Drop trailing underscores for private functions and leading ``this->`` for private data *(@sethrj, #980)* +* Support HIP 5.1.0 and add Frontier build scripts *(@sethrj, #981)* +* Add more profiling ranges and fix return code checks *(@sethrj, #982)* +* Refactor surface input with vector of variants *(@sethrj, #924)* +* Improve performance with lower launch bounds *(@sethrj, #984)* +* Refactor universe insertion and add universe accessors to orange params *(@sethrj, #977)* +* Unify names for celer-sim and celer-g4 input *(@amandalund, #993)* +* Use fused multiply-add to improve performance and numerical accuracy *(@sethrj, #995)* +* Support device-specific launch bounds *(@esseivaju, #986)* +* Make boundary distance persistent to improve Shift performance *(@sethrj, #1002)* +* Fix exception handling flags for Windows MSVC builds *(@sethrj, #1005)* +* Optimize ORANGE surface crossings and checks *(@sethrj, #1004)* +* Refactor detector construction and SharedParams output *(@sethrj, #1007)* +* Add GitHub actions to CI *(@sethrj, #1020)* +* Fix unchecked merge train wreck *(@sethrj, #1021)* +* Refactor vecgeom setup in preparation for surface support *(@sethrj, #1017)* +* Fix CI for "push" events *(@sethrj, #1022)* +* Use default field driver options in celer-g4 test *(@amandalund, #1024)* +* Fix duplicate libvecgeom.a in some components' build *(@mrguilima, #1027)* +* Simplify data access for host collections *(@esseivaju, #1029)* +* Update Celeritas CMake defaults and add documentation build *(@sethrj, #1030)* +* Hotfix: CUDA 12.3.52 build error *(@sethrj, #1033)* +* Add preflight github action *(@sethrj, #1032)* + +Reviewers: @amandalund *(19)*, @sethrj *(18)*, @pcanal *(13)*, @elliottbiondo *(8)*, @esseivaju *(7)*, @drbenmorgan *(3)*, @hhollenb *(3)*, @whokion *(1)*, @tmdelellis *(1)*, @mrguilima *(1)* + +**Full Changelog**: https://github.com/celeritas-project/celeritas/compare/v0.3.0...v0.4.0 diff --git a/doc/conf.py b/doc/conf.py index d239f2668d..eb497b8b84 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -19,14 +19,15 @@ # Remaining core team in alphabetical order 'Philippe Canal', 'Julien Esseiva', - 'Tom Evans', 'Soon Yung Jun', 'Guilherme Lima', 'Amanda Lund', - 'Paul Romano', - 'Stefano C Tognini', - # Notable contributors to code and documenation 'Ben Morgan' + 'Stefano C Tognini', + # Core advisors + 'Thomas M Evans', + 'Marcel Demarteau', + 'Paul Romano', ] author = " and ".join(all_authors) copyright = '{:%Y}, UT–Battelle/ORNL and Celeritas team'.format( diff --git a/doc/index.rst b/doc/index.rst index 7ffc2d5894..73fa6c51df 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -44,14 +44,14 @@ simulations of the CMS and ATLAS detectors. :maxdepth: 2 :caption: Contents - introduction.rst - overview.rst - installation.rst - usage.rst - api.rst - examples.rst - references.rst - acknowledgments.rst + main/introduction.rst + main/overview.rst + main/installation.rst + main/usage.rst + main/api.rst + main/examples.rst + main/references.rst + main/acknowledgments.rst .. *************************************************************************** .. APPENDICES @@ -65,7 +65,7 @@ simulations of the CMS and ATLAS detectors. :maxdepth: 2 :caption: Appendices - appendices/release-history.rst - appendices/development.rst - appendices/administration.rst - appendices/license.rst + appendix/release-history.rst + appendix/development.rst + appendix/administration.rst + appendix/license.rst diff --git a/doc/acknowledgments.rst b/doc/main/acknowledgments.rst similarity index 100% rename from doc/acknowledgments.rst rename to doc/main/acknowledgments.rst diff --git a/doc/api.rst b/doc/main/api.rst similarity index 100% rename from doc/api.rst rename to doc/main/api.rst diff --git a/doc/api/accel.rst b/doc/main/api/accel.rst similarity index 100% rename from doc/api/accel.rst rename to doc/main/api/accel.rst diff --git a/doc/api/celeritas.rst b/doc/main/api/celeritas.rst similarity index 100% rename from doc/api/celeritas.rst rename to doc/main/api/celeritas.rst diff --git a/doc/api/corecel.rst b/doc/main/api/corecel.rst similarity index 100% rename from doc/api/corecel.rst rename to doc/main/api/corecel.rst diff --git a/doc/api/orange.rst b/doc/main/api/orange.rst similarity index 100% rename from doc/api/orange.rst rename to doc/main/api/orange.rst diff --git a/doc/examples.rst b/doc/main/examples.rst similarity index 100% rename from doc/examples.rst rename to doc/main/examples.rst diff --git a/doc/examples/geant4.rst b/doc/main/examples/geant4.rst similarity index 88% rename from doc/examples/geant4.rst rename to doc/main/examples/geant4.rst index 3c442e7362..337a8f74c2 100644 --- a/doc/examples/geant4.rst +++ b/doc/main/examples/geant4.rst @@ -23,7 +23,7 @@ methods needed to integrate into a Geant4 application's UserActions or other use CMake infrastructure -------------------- -.. literalinclude:: ../../example/accel/CMakeLists.txt +.. literalinclude:: ../../../example/accel/CMakeLists.txt :language: cmake :start-at: project( :end-before: END EXAMPLE CODE @@ -38,11 +38,11 @@ frameworks or other apps that use a task-based runner. Offload using a concrete G4UserTrackingAction --------------------------------------------- -.. literalinclude:: ../../example/accel/simple-offload.cc +.. literalinclude:: ../../../example/accel/simple-offload.cc :start-at: #include Offload using a concrete G4VFastSimulationModel ----------------------------------------------- -.. literalinclude:: ../../example/accel/fastsim-offload.cc +.. literalinclude:: ../../../example/accel/fastsim-offload.cc :start-at: #include diff --git a/doc/examples/minimal.rst b/doc/main/examples/minimal.rst similarity index 82% rename from doc/examples/minimal.rst rename to doc/main/examples/minimal.rst index d80bac8241..79f6dc5c03 100644 --- a/doc/examples/minimal.rst +++ b/doc/main/examples/minimal.rst @@ -16,7 +16,7 @@ CMake infrastructure A three-line helper script ``FindCeleritas.cmake`` gives more verbose loading messages when using Celeritas externally. -.. literalinclude:: ../../example/FindCeleritas.cmake +.. literalinclude:: ../../../example/FindCeleritas.cmake :language: cmake :start-at: find_package( @@ -24,13 +24,13 @@ The CMake code itself is straightforward, though note the use of ``celeritas_target_link_libraries`` instead of ``target_link_libraries`` to support CUDA RDC, which is required by VecGeom. -.. literalinclude:: ../../example/minimal/CMakeLists.txt +.. literalinclude:: ../../../example/minimal/CMakeLists.txt :language: cmake :start-at: project( Main executable --------------- -.. literalinclude:: ../../example/minimal/minimal.cc +.. literalinclude:: ../../../example/minimal/minimal.cc :start-at: #include diff --git a/doc/installation.rst b/doc/main/installation.rst similarity index 99% rename from doc/installation.rst rename to doc/main/installation.rst index 9402b5e0c2..681b2982ee 100644 --- a/doc/installation.rst +++ b/doc/main/installation.rst @@ -108,7 +108,7 @@ dependencies: The current Spack environment for full-featured development is: -.. literalinclude:: ../scripts/spack.yaml +.. literalinclude:: ../../scripts/spack.yaml :language: yaml With this environment (with CUDA enabled), all Celeritas tests should be diff --git a/doc/introduction.rst b/doc/main/introduction.rst similarity index 100% rename from doc/introduction.rst rename to doc/main/introduction.rst diff --git a/doc/overview.rst b/doc/main/overview.rst similarity index 100% rename from doc/overview.rst rename to doc/main/overview.rst diff --git a/doc/references.rst b/doc/main/references.rst similarity index 91% rename from doc/references.rst rename to doc/main/references.rst index 67ae6bb87f..f50404693d 100644 --- a/doc/references.rst +++ b/doc/main/references.rst @@ -15,6 +15,6 @@ References .. _sphinxbib: https://pypi.org/project/sphinxcontrib-bibtex/ -.. bibliography:: _static/references.bib +.. bibliography:: ../_static/references.bib :all: diff --git a/doc/usage.rst b/doc/main/usage.rst similarity index 100% rename from doc/usage.rst rename to doc/main/usage.rst