npsim

97.5% of first-parent commits in 12 months came from PRs and an active ruleset requires one approving review and a status check, but only 80% of merged PRs were reviewed, and administrators bypass the ruleset (PRs #84, #90, #92 merged without an approval).

Gaps to the next level

• Fewer than 90% of merged PRs are reviewed by someone other than the author.
• Ruleset bypass is set to "always" for organization admins, the admin role and one team.
• No CODEOWNERS file.

Actions

• medium S Remove the "always" bypass actors from the "Default" ruleset (or set them to pull-request-only) so every PR needs an approval.
• medium S Add .github/CODEOWNERS naming at least two reviewers for src/plugins/, src/python/, src/geocad/ and src/tools/.

linux-eic-shell.yml runs on every PR and push to main, builds with g++ and clang++, runs ctest, and runs npsim end-to-end on gun and DIS samples, but 86.8% of default-branch runs succeeded, and the only required check (build-artifacts-page) is skipped, which GitHub reports as success, when upstream jobs fail.

Gaps to the next level

• Default-branch success rate is below 90%.
• The required check build-artifacts-page is skipped (counted as passing) when build or simulation jobs fail, and the convert-to-step/dot jobs are not upstream of it.

Actions

• medium S Add an aggregating job with if: always() that fails when any of build, npsim-gun, npsim-dis, convert-to-step or convert-to-dot failed, and make it the required status check.

ctest runs five tests in CI, covering one helper in src/tools and the geocad STEP exporter, and CI runs npsim end-to-end with a capybara comparison to the previous main output; none of the six DDG4 plugins or the npsim.py front-end has a unit test.

Gaps to the next level

• No unit tests for EICInteractionVertexBoost, EICInteractionVertexSmear, Geant4TVEicParticleHandler, OpticalPhotonEfficiencyStackingAction or the VolumeDispatch plugins.
• The capybara comparison produces reports but does not fail CI on output differences.
• No coverage measurement.

Actions

• medium M Add ctest tests that run each DDG4 plugin through a minimal ddsim/npsim steering on a small test geometry and assert its effect (vertex shift, kept particles, photon suppression).

.clang-format exists but is not enforced, CodeQL default setup (extended suite) runs on PRs, and ASan/UBSan builds run in CI; -Wall -Wextra -Werror -pedantic applies only to non-Release builds while CI builds only Release.

Gaps to the next level

• clang-format is not checked in CI or pre-commit.
• CI compiles in Release, where -Werror is not set; the latest main build emits compiler warnings.

Actions

• medium S Add .pre-commit-config.yaml with clang-format (and ruff for src/python) and enable pre-commit.ci, or add a clang-format --dry-run --Werror CI job.
• medium S Add a RelWithDebInfo entry to the CI build matrix so -Wall -Wextra -Werror -pedantic applies in CI.

CMake builds separate plugin, geocad, tool and Python components with C++20 and exports NPDetTargets, but npsim.py hard-codes detector-specific settings (filters, actions, a DIRC quantum-efficiency table) after option parsing, so steering files cannot override them.

Gaps to the next level

• Detector configuration (RICH/DIRC filters, actions, QE curve) is compiled into npsim.py and overrides user steering.
• write_basic_package_version_file uses the undefined NPDet_VERSION, and project() declares 1.0.0 at release v1.9.0.

Actions

• medium M Move the DIRC QE table to the epic geometry (issue
• low S Set project(npsim VERSION ...) to the release version and use ${PROJECT_VERSION} in write_basic_package_version_file.

The README lists the tools and their origin but does not explain how to install, build or run npsim; usage is taught only in a separate EIC tutorial that the README does not link.

Gaps to the next level

• README has no installation, build or run instructions.
• No dependency list with versions and no quick-start example.

Actions

• high S Add README sections for using npsim in eic-shell, building from source (DD4hep >= 1.18, Geant4, ROOT, fmt, nlohmann_json, optional OpenCASCADE), and a one-command npsim --compactFile ... -G -N 10 quick start.
• high S Link the npsim simulation tutorial and document the options and defaults that npsim.py adds on top of ddsim.

Plugin headers carry Doxygen-style comments and Geant4TVEicParticleHandler.md documents one plugin in detail, but there is no generated API reference and no architecture overview.

Gaps to the next level

• No Doxygen configuration or generated API docs.
• No overview of how npsim.py, the DDG4 plugins, geocad and the tools relate.

Actions

• medium S Add a Doxyfile and publish the API docs to the existing GitHub Pages site from linux-eic-shell.yml.
• medium S Add docs/architecture.md describing the npsim front-end, each plugin's role in the DDG4 chain, and the geometry tools.

The eic organization PR and issue templates apply and .devcontainer/README.md gives container setup and a CMake build, but there is no CONTRIBUTING file covering tests, conventions or the PR process.

Gaps to the next level

• No CONTRIBUTING.md describing running ctest and the CI simulations, coding conventions (.clang-format) and the PR process.

Actions

• medium S Add CONTRIBUTING.md covering eic-shell/devcontainer setup, cmake/ctest, running clang-format, and PR review and capybara-report expectations.

Median first response to the six issues opened in 12 months was 27 days, no new issue is labeled, and 5 of 8 open issues are older than one year.

Gaps to the next level

• Median first response exceeds 14 days.
• More than half of open issues are older than one year (#1,
• Nine open PRs are older than 90 days.

Actions

• medium S Respond to
• medium S Review, merge or close the nine open PRs older than 90 days (including

Five authors committed in 24 months, but no institutional affiliation is recorded (0 identifiable email domains) and no PR from outside the maintainer group was merged in 12 months.

Gaps to the next level

• No external PRs merged in 12 months.
• Contributing institutions are not documented.

Actions

• medium S Add an AUTHORS or README contributors section with institutions, and review the open contributor PR

The top author wrote 73% of commits in 24 months, while four people review and two merge; no CODEOWNERS or maintainer list exists, and eic-spack names one maintainer.

Gaps to the next level

• Bus factor (50%) is 1.
• No CODEOWNERS or maintainer list naming at least two people.

Actions

• high S Add .github/CODEOWNERS with two owners per component and add a second maintainer to the eic-spack recipe.

Changes are discussed in public PRs and issues, but neither the README nor a CODEOWNERS file names maintainers, and there is no decision process, roadmap or milestone.

Gaps to the next level

• Maintainers are not identified in the repository.
• No documented decision process, maintainer path or owning ePIC group.

Actions

• high S Add a "Maintainers" README section naming the maintainers and the owning ePIC working group, and stating how decisions on npsim defaults are made.

The eic organization issue-template configuration links the ePIC Mattermost for questions, but no code of conduct applies to the repository or the organization.

Gaps to the next level

• No code of conduct with a reporting contact.

Actions

• high S Add CODE_OF_CONDUCT.md with a reporting contact, or link the ePIC collaboration code of conduct from the README.

The eic-spack recipe provides the latest release 1.9.0 and was updated on the release day of each of the last three releases, and eic-shell ships npsim (1.8.0).

Thirteen releases with generated notes appeared in 24 months, but no version scheme is documented, and the CMake project version is 1.0.0 at v1.9.0.

Gaps to the next level

• No documented version scheme; project version does not match tags.

Actions

• medium S State SemVer in the README and bump project(npsim VERSION ...) with each tag.

Only DD4hep has a minimum version (1.18); fmt, nlohmann_json, OpenCASCADE, ROOT and spdlog have none, clipp 1.2.3 (last released 2019) is vendored, and 43 action references are not SHA-pinned.

Gaps to the next level

• Most find_package calls have no minimum version.
• Vendored clipp 1.2.3 is unmaintained upstream while eic-shell ships CLI11.

Actions

• medium S Add VERSION arguments to the find_package calls for ROOT, fmt, nlohmann_json and OpenCASCADE.
• medium M Replace src/tools/include/clipp.h with find_package(CLI11) from eic-shell.

A devcontainer pins the eicweb/eic_ci:nightly image and CI sets --random.seed, but the image is an unversioned nightly, the repository documents no eic-shell release per npsim release, and recording of seeds and configuration in outputs is not documented.

Gaps to the next level

• No versioned environment (pinned eic-shell release) is documented for running npsim.
• No documentation of how seeds and steering configuration are recorded in output files.

Actions

• medium S Document in the README which eic-shell release ships each npsim release and how the seed and steering options are stored in the EDM4hep output metadata.

CI builds and runs ctest with GCC and Clang, no site paths appear in the code, and ePIC campaigns run npsim on distributed resources, but CI covers only Linux x86_64 and accelerator use is not addressed.

Gaps to the next level

• No aarch64 or macOS CI, although CMake contains Darwin handling.
• No statement on accelerator support.

Actions

• low S Add an ubuntu-24.04-arm build job using the arm64 eic-shell image, and state in the README that GPU offload is provided by Geant4 (not npsim) where applicable.

npsim is built on DD4hep DDSim/DDG4 and Geant4, the one copied DD4hep helper is justified in the source (not installed upstream), and npsim is itself the EIC-supported simulation front-end used by epic and EICrecon CI and ePIC campaigns.

npsim reads DD4hep compact XML and HepMC3 and writes EDM4hep through DD4hep's podio output; no data-model version is checked and no round-trip test exists in the repository.

Gaps to the next level

• No EDM4hep version check and no I/O round-trip test.

Actions

• medium S Add a CI step that opens the produced .edm4hep.root with uproot and checks the podio/EDM4hep version metadata and the expected collections.

CI builds, tests and runs npsim in eic_xl:nightly through eic/run-cvmfs-osg-eic-shell, and the devcontainer README documents building in the eic_ci image; no pinned stable eic-shell release is tested.

Gaps to the next level

• CI tests only the nightly image, not a pinned stable eic-shell release.

Actions

• medium S Add a platform-release matrix over a pinned eic_xl:<stable> and eic_xl:nightly in .github/workflows/linux-eic-shell.yml.

eic-shell ships npsim 1.8.0, CI builds every PR and push against the nightly stack, and the latest main build shows no DD4hep, Geant4 or ROOT deprecation warnings; ROOT and Python warnings were fixed in #57 and #85.

The repository has no LICENSE file and GitHub detects no license; issue #1 asking for one has been open since November 2022.

Gaps to the next level

• No license; the code is all rights reserved.

Actions

• high S Add a LICENSE file with an OSI-approved license compatible with DD4hep (LGPL-3.0) and the vendored MIT clipp, agreed by the copyright holders.

There is no CITATION.cff, Zenodo DOI, codemeta or author list.

Gaps to the next level

• No citation information or contributor list.

Actions

• high S Add CITATION.cff listing the contributors and enable the Zenodo-GitHub integration.

npsim ships in eic-shell and is the simulation step of ePIC production campaigns and of the epic and EICrecon CI, and npdet_to_step is used in epic CI.

A maintainer is identifiable through the eic-spack recipe, but the repository states no owning ePIC working group, institutional commitment or funding.

Gaps to the next level

• No maintenance responsibility within the EIC/ePIC structure is documented.

Actions

• medium S State in the README the ePIC working group responsible for npsim and the maintainers' institutions.