From 409676dbc62b4182e33a02e189501015c6366415 Mon Sep 17 00:00:00 2001 From: Pierre Granger Date: Fri, 6 Nov 2026 11:02:40 +0100 Subject: [PATCH] Tests that survive expected SPINE changes, and the CAFMaker contracts A SPINE tag that only relabels the version, adds fields or enum members, or removes a field no CAFMaker reads now passes every test once its fixtures are written. A change to what the CAFMakers rely on fails a new ctest entry of its own, spine_reader_contracts. - tests/test_contracts.cpp (new): one row per model field a CAFMaker reads (228: class, field, unit, default as JSON, readers), from the scan of the ND, SBN and FD ports and SPINE 1.4.0's schema. For each class it walks golden_members.inc and compares the unit and the member of a default object; a row whose field or class the model no longer has fails. It also checks every member of ParticleShape, ParticlePID and NuCurrentType by name. ctest runs the "contract*" cases as spine_reader_contracts, and spine_reader_tests excludes them. - tests/test_golden.cpp: column_problems() compares the model with the columns of each current fixture except current_v2_fixed_only: full files have every field, lite files every field but the lite_skip ones (both ways), no column is outside the model, element kinds agree. Width differences are printed only. Its own test case doctors a copy of current_v1's reco_particles, with the column picked at run time. - tests/member_compare.hpp (new): equal_member() from the golden test, plus nan_equal(), member_json() and all_nan(). - tests/test_model.cpp: no field counts, LAST_FIELD table, class list, literal schema version, defaults, units, flags, references, enum member counts or enum values. The structure check runs for every class, and the field-name check for every field (through golden_members.inc). The assign test compares with default objects. The scheme-table check only requires each scheme to select a generated table or none. The doc check is dropped: SPINE may add a field without a docstring. - tests/test_reader.cpp, check_spine_dump.cmake, test_core_real.cpp: the completeness checks on frozen and real files, the summary line, the enum numbers in the mismatch text and the field count come from the model. - tools/release/scan_consumer_fields.py (new): lists the model fields one CAFMaker build reads, by compiling its sources with -fsyntax-only against headers whose members and Field enumerators are marked [[deprecated]] (make -n -B or compile_commands.json; --setup and --wrap for the SL7 container). --contracts lists the fields read that have no row. - Docs: tools/release/EGM.md (new); the model EGM files lose the version and field counts; README, root and tools EGM, tools/gen/README.md describe the new entry and when a contract row changes. --- EGM.md | 22 +- README.md | 11 +- include/spine/model/EGM.md | 35 +- src/model/EGM.md | 12 +- tests/CMakeLists.txt | 9 +- tests/check_spine_dump.cmake | 3 +- tests/golden_members.inc | 3 +- tests/member_compare.hpp | 109 +++++++ tests/test_contracts.cpp | 410 ++++++++++++++++++++++++ tests/test_core_real.cpp | 6 +- tests/test_golden.cpp | 203 +++++++++--- tests/test_model.cpp | 439 +++++--------------------- tests/test_reader.cpp | 57 ++-- tools/EGM.md | 22 +- tools/fixtures/EGM.md | 3 +- tools/fixtures/make_member_list.py | 9 +- tools/gen/README.md | 13 +- tools/release/EGM.md | 102 ++++++ tools/release/scan_consumer_fields.py | 414 ++++++++++++++++++++++++ 19 files changed, 1408 insertions(+), 474 deletions(-) create mode 100644 tests/member_compare.hpp create mode 100644 tests/test_contracts.cpp create mode 100644 tools/release/EGM.md create mode 100755 tools/release/scan_consumer_fields.py diff --git a/EGM.md b/EGM.md index 1b24963..06e0ca7 100644 --- a/EGM.md +++ b/EGM.md @@ -22,11 +22,11 @@ SPINE HDF5 file ``` The model is generated at build-maintenance time, not at configure time: -`tools/gen/dump_schema.py` (imports SPINE at a tag) -> `schema/spine-1.4.0.json` -> +`tools/gen/dump_schema.py` (imports SPINE at a tag) -> `schema/spine-.json` -> `tools/gen/generate.py` -> `include/spine/model/`, `include/spine/model.hpp`, `src/model/`. The root folder holds no source files: only `CMakeLists.txt`, `cmake/SpineReaderConfig.cmake.in`, -`schema/spine-1.4.0.json`, `README.md`, `EGM.md`, `LICENSE`, `.gitignore` and the GitHub Actions +`schema/spine-.json`, `README.md`, `EGM.md`, `LICENSE`, `.gitignore` and the GitHub Actions workflow `.github/workflows/ci.yml` (documented in [./ci/EGM.md](./ci/EGM.md)). Build and packaging (`CMakeLists.txt`): @@ -53,7 +53,7 @@ Build and packaging (`CMakeLists.txt`): - [./include/spine/EGM.md](./include/spine/EGM.md) - `Reader`, `ReaderOptions`, `Event`, `Match`, `SchemaReport`/`ProductReport`, descriptors, `Object`, `spine::Error`, `spine::version()`. - - [./include/spine/model/EGM.md](./include/spine/model/EGM.md) - Generated SPINE 1.4.0 + - [./include/spine/model/EGM.md](./include/spine/model/EGM.md) - Generated SPINE classes (`RecoParticle`, `TruthParticle`, `RecoInteraction`, `TruthInteraction`, `RunInfo`, `Trigger`, `ImageMeta3D`, `Flash`, `CRTHit`, `FlashHypothesis`) and enums. Do not edit. - [./include/spine/detail/EGM.md](./include/spine/detail/EGM.md) - `ColumnBuffer` and @@ -75,6 +75,9 @@ Build and packaging (`CMakeLists.txt`): - [./tools/fixtures/EGM.md](./tools/fixtures/EGM.md) - Golden test files written by SPINE's own writer (the `current_*` set by any tag, the frozen cases by old releases), plus their expected JSON, `manifest.json` and `tests/golden_members.inc`. + - [./tools/release/EGM.md](./tools/release/EGM.md) - Release tooling: + `scan_consumer_fields.py` (the model fields a CAFMaker build reads, against the contract + table of `tests/test_contracts.cpp`). - examples: [./examples/EGM.md](./examples/EGM.md) - The `spine-dump` command-line tool. - ci: [./ci/EGM.md](./ci/EGM.md) - the GitHub Actions workflow and `github-ci.sh` (HDF5 1.14 and 1.12 from LCG views on CVMFS), `check_tag_version.sh` (release tag against @@ -113,8 +116,10 @@ Build and packaging (`CMakeLists.txt`): - Temporarily changes HDF5's library-global automatic error printing (`h5::ErrorSilencer`), restoring it afterwards. - Developer tools only: `tools/gen` rewrites the generated model; `tools/fixtures` clones SPINE - commits and rewrites `tests/data/fixtures/` (cases and manifest) and `tests/golden_members.inc`; `ci/` scripts - create `build-ci/`, `build-asan/`, `build-tsan/` and `build-sl7/`. + commits and rewrites `tests/data/fixtures/` (cases and manifest) and `tests/golden_members.inc`; + `tools/release/scan_consumer_fields.py` runs a CAFMaker's compile commands with + `-fsyntax-only` in a work folder; `ci/` scripts create `build-ci/`, `build-asan/`, + `build-tsan/` and `build-sl7/`. - CI: the GitHub Actions workflow builds and tests on GitHub's hosted runners, with read-only access to the repository and no secrets. @@ -122,11 +127,12 @@ Build and packaging (`CMakeLists.txt`): - Run (EL9, after `source /cvmfs/sft.cern.ch/lcg/views/LCG_110/x86_64-el9-gcc13-opt/setup.sh`): `cmake -S . -B build && cmake --build build -j8 && ctest --test-dir build --output-on-failure` -- The ctest entries include `spine_reader_tests` (unit tests), `spine_reader_generated_model` +- The ctest entries include `spine_reader_tests` (unit tests), `spine_reader_contracts` (what + the CAFMakers rely on: `tests/test_contracts.cpp`), `spine_reader_generated_model` (`tools/gen/generate.py --check`), `spine_reader_golden_members`, `spine_dump_output`, and `spine_reader_real_files` (skipped unless `SPINE_READER_REAL_FILES` names a directory). -- `spine_reader_tests` excludes the `real files*` test cases, which `spine_reader_real_files` - runs. `spine_reader_generated_model` and `spine_reader_golden_members` are registered only +- `spine_reader_tests` excludes the `real files*` and `contract*` test cases, which + `spine_reader_real_files` and `spine_reader_contracts` run. `spine_reader_generated_model` and `spine_reader_golden_members` are registered only when CMake finds Python 3 (with `SPINE_READER_REQUIRE_PYTHON=ON`, a missing Python fails the configuration), and `spine_dump_output` only when the tools are built. - CI: `.github/workflows/ci.yml` runs `ci/github-ci.sh` with HDF5 1.14 (LCG_110, Ubuntu 24.04) diff --git a/README.md b/README.md index de0c9c0..fa4c845 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,7 @@ Status: under construction. | `src/model/` | Generated field tables. Do not edit by hand. | | `tools/gen/` | Generator: dumps SPINE `FieldMetadata` to `schema/` and writes the model. | | `tools/fixtures/` | Writes the test files in `tests/data/` with SPINE's own writer, plus expected values. | +| `tools/release/` | Tooling for following SPINE releases: `scan_consumer_fields.py` lists the model fields a CAFMaker build reads. | | `tests/` | doctest unit tests (`test_*.cpp`). | ## Build @@ -49,12 +50,18 @@ cmake -S . -B build && cmake --build build -j8 && ctest --test-dir build --outpu | ctest entry | What it does | | --- | --- | -| `spine_reader_tests` | The doctest unit tests (`tests/test_*.cpp`), a few seconds. | +| `spine_reader_tests` | The doctest unit tests (`tests/test_*.cpp`), a few seconds. They hold for any SPINE tag once its fixtures are written: the golden test checks the model's fields against the columns of the current fixtures. | +| `spine_reader_contracts` | What the CAFMakers rely on (`tests/test_contracts.cpp`): the unit and default of each model field a CAFMaker reads, and the enum values they use. A failure means the SPINE change is reviewed with the CAFMaker maintainers before a release. | | `spine_reader_real_files` | Reads every `*.h5` in `$SPINE_READER_REAL_FILES` (or `-DSPINE_READER_REAL_FILES=dir`). Without a directory it reports **Skipped**, never Passed. | | `spine_reader_generated_model` | `tools/gen/generate.py --check`: the generated model is what the committed SPINE schema produces. | -| `spine_reader_golden_members` | `tests/golden_members.inc` (the member list `test_golden.cpp` compares object by object) is current. | +| `spine_reader_golden_members` | `tests/golden_members.inc` (the member list that `test_golden.cpp` compares object by object, and that `test_model.cpp` and `test_contracts.cpp` walk) is current. | | `spine_dump_output` | `spine-dump` prints what it should for the Reader test files. | +When a CAFMaker starts reading a model field, add its row to the contract table. +`tools/release/scan_consumer_fields.py --contracts tests/test_contracts.cpp`, run on that +CAFMaker's build in its own environment, lists the fields it reads that have no row +([tools/release/EGM.md](tools/release/EGM.md)). + The test files in `tests/data/` come with the scripts that write them: `core/make_edge_cases.py`, `core/make_audit_cases.py`, `core/make_expected.py`, `reader/make_reader_cases.py` (SPINE's own writer) and `tools/fixtures/` (golden fixtures). `ci/sl7-ups.sh` builds with the SL7 UPS toolchain diff --git a/include/spine/model/EGM.md b/include/spine/model/EGM.md index 5a9e381..a195110 100644 --- a/include/spine/model/EGM.md +++ b/include/spine/model/EGM.md @@ -3,9 +3,9 @@ ## Overview **Generated code. Do not edit the headers here by hand.** Every `.hpp` in this directory is -written by `tools/gen/generate.py` from the SPINE schema dump `schema/spine-1.4.0.json`. Each -file starts with the banner `// GENERATED from SPINE 1.4.0 by tools/gen/generate.py. Do not -edit.` To change the model, update the schema dump and run +written by `tools/gen/generate.py` from the one committed SPINE schema dump, +`schema/spine-.json`. Each file starts with the banner `// GENERATED from SPINE + by tools/gen/generate.py. Do not edit.` To change the model, update the schema dump and run `python3 tools/gen/generate.py` from the repository root. `--check` writes nothing and exits 1 if the files on disk differ from what it would generate. The generator also writes the matching field tables and `descriptor()` definitions in `src/model/*.cpp` and @@ -15,21 +15,26 @@ The generator deletes only stale `.hpp`/`.cpp` files in this directory and in `s this `EGM.md` is safe from regeneration. The headers hold the C++ mirror of SPINE's output object model: one plain struct per SPINE -class, plus SPINE's enumerations. +class, plus SPINE's enumerations. The classes, their fields and the fields' order, types, +units and defaults all come from the schema, so they follow SPINE's tag. The golden test +(`tests/test_golden.cpp`) checks the fields against the columns of the current fixtures, which +that tag writes; `tests/test_contracts.cpp` checks the units and defaults of the fields the +CAFMakers read. ## Interface -- Class structs (namespace `spine`), each `struct X : Object` with N public data members: - - `reco_particle.hpp`: `RecoParticle` (55 fields) - - `truth_particle.hpp`: `TruthParticle` (98 fields) - - `reco_interaction.hpp`: `RecoInteraction` (40 fields) - - `truth_interaction.hpp`: `TruthInteraction` (79 fields) - - `run_info.hpp`: `RunInfo` (3 fields: `run`, `subrun`, `event`) - - `trigger.hpp`: `Trigger` (6 fields) - - `image_meta3d.hpp`: `ImageMeta3D` (4 fields) - - `flash.hpp`: `Flash` (14 fields) - - `crt_hit.hpp`: `CRTHit` (14 fields) - - `flash_hypothesis.hpp`: `FlashHypothesis` (8 fields) +- Class structs (namespace `spine`), each `struct X : Object` with N public data members, + one per field of the class in the schema (`X::kNumFields` is N): + - `reco_particle.hpp`: `RecoParticle` + - `truth_particle.hpp`: `TruthParticle` + - `reco_interaction.hpp`: `RecoInteraction` + - `truth_interaction.hpp`: `TruthInteraction` + - `run_info.hpp`: `RunInfo` (`run`, `subrun`, `event`) + - `trigger.hpp`: `Trigger` + - `image_meta3d.hpp`: `ImageMeta3D` + - `flash.hpp`: `Flash` + - `crt_hit.hpp`: `CRTHit` + - `flash_hypothesis.hpp`: `FlashHypothesis` - Every class struct has: - `enum class Field : std::uint16_t`, one enumerator per member, in the order SPINE's HDF5 writer stores them. diff --git a/src/model/EGM.md b/src/model/EGM.md index dab3eb0..39a4e27 100644 --- a/src/model/EGM.md +++ b/src/model/EGM.md @@ -4,7 +4,7 @@ Generated field tables for the SPINE object model. **Every `.cpp` and `.hpp` file in this directory is generated by `tools/gen/generate.py` from the committed SPINE schema -(`schema/spine-.json`; currently SPINE 1.4.0). Do not edit them by hand.** To +(the one `schema/spine-.json`). Do not edit them by hand.** To change them, regenerate with `python3 tools/gen/generate.py`. The generator deletes only stale `.hpp` and `.cpp` files here, so this `EGM.md` is safe. @@ -27,8 +27,8 @@ Each class source defines the `FieldDescriptor` table and the `ClassDescriptor` - `flags` (`FieldFlag` bits such as `kIndex`, `kCategorical`, `kPosition`, `kVector`); - `units`, `enumeration`, `reference`, `reference_space`, `doc`; - the `&detail::assign<&Class::member>` setter. - - Each `ClassDescriptor` is `{"", kFields, std::size(kFields), "1.4.0"}`. The last - entry is the schema version, which the Reader reports as `model_version`. + - Each `ClassDescriptor` is `{"", kFields, std::size(kFields), ""}`. The last + entry is the schema's SPINE version, which the Reader reports as `model_version`. - `enums.cpp` - `EnumDescriptor`s: `kParticleShapeEnum`, `kParticlePIDEnum`, `kNuCurrentTypeEnum`, `kNuInteractionSchemeEnum`, and the per-generator interaction-type enums (LArSoft, Genie, @@ -58,7 +58,8 @@ Each class source defines the `FieldDescriptor` table and the `ClassDescriptor` - SPINE enums must have `std::int64_t` as underlying type. - The enumeration and assign pointers are not checked at compile time (that is not a constant expression under `-fsanitize=undefined`). `tests/test_model.cpp` checks them at - run time. + run time. The tables themselves are SPINE's: the golden test checks them against the current + fixtures' columns, and `tests/test_contracts.cpp` the units and defaults the CAFMakers read. - The descriptors are `constexpr` and `const` static data. They are read-only and safe to share across threads. @@ -73,4 +74,5 @@ Each class source defines the `FieldDescriptor` table and the `ClassDescriptor` `source /cvmfs/sft.cern.ch/lcg/views/LCG_110/x86_64-el9-gcc13-opt/setup.sh && cmake -S . -B build && cmake --build build -j8 && ctest --test-dir build --output-on-failure` - Regenerate: `python3 tools/gen/generate.py`. Check without writing: `python3 tools/gen/generate.py --check`. -- Main unit tests: `tests/test_model.cpp`, `tests/test_descriptor.cpp`. +- Main unit tests: `tests/test_model.cpp`, `tests/test_descriptor.cpp`, `tests/test_golden.cpp` + and `tests/test_contracts.cpp` (ctest entry `spine_reader_contracts`). diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 0d6ca15..909f8e8 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -10,8 +10,13 @@ target_include_directories(spine_reader_tests PRIVATE target_compile_definitions(spine_reader_tests PRIVATE SPINE_READER_TEST_DATA="${CMAKE_CURRENT_SOURCE_DIR}/data") -# The unit tests. The real-file test is left to its own entry below. -add_test(NAME spine_reader_tests COMMAND spine_reader_tests "--test-case-exclude=real files*") +# The unit tests. The real-file test and the consumer contracts are left to their own entries. +add_test(NAME spine_reader_tests COMMAND spine_reader_tests + "--test-case-exclude=real files*,contract*") + +# What the CAFMakers rely on (test_contracts.cpp): the units and defaults of the fields they read, +# and the enum values. A failure means the SPINE change is reviewed with the CAFMaker maintainers. +add_test(NAME spine_reader_contracts COMMAND spine_reader_tests "--test-case=contract*") # Real SPINE output. Point SPINE_READER_REAL_FILES (a CMake variable, or an environment variable # when ctest runs) at a directory of *.h5 files. Without it this entry reports "Skipped" instead diff --git a/tests/check_spine_dump.cmake b/tests/check_spine_dump.cmake index c60a316..e75b75e 100644 --- a/tests/check_spine_dump.cmake +++ b/tests/check_spine_dump.cmake @@ -44,7 +44,8 @@ endif() set(read_by "; read by spine-reader ${READER_VERSION} (model from SPINE ${MODEL_VERSION})") expect_in("${text}" "${A}\n SPINE 1.4.0, format_version 1 (V1)${read_by}") expect_in("${text}" "${B}\n SPINE 1.4.0, format_version 2 (V2Products)${read_by}") -expect_in("${text}" "meta [Meta]: all model fields read") +# only the prefix: fields SPINE adds later are missing from this frozen file +expect_in("${text}" "\n meta [Meta]: ") expect_in("${text}" "index: array product") string(CONCAT first_event "6 events\n" diff --git a/tests/golden_members.inc b/tests/golden_members.inc index cf36bd3..1d28ef6 100644 --- a/tests/golden_members.inc +++ b/tests/golden_members.inc @@ -1,5 +1,6 @@ // GENERATED from schema/spine-1.4.0.json by tools/fixtures/make_member_list.py. Do not edit. -// The members of each model class, in SPINE's order, for tests/test_golden.cpp. +// The members of each model class, in SPINE's order, for tests/test_golden.cpp, +// tests/test_model.cpp and tests/test_contracts.cpp. #define GOLDEN_MEMBERS_RecoParticle(X) \ X(is_truth) X(units) X(id) X(is_contained) X(is_time_contained) X(is_cathode_crosser) \ diff --git a/tests/member_compare.hpp b/tests/member_compare.hpp new file mode 100644 index 0000000..53fa3b9 --- /dev/null +++ b/tests/member_compare.hpp @@ -0,0 +1,109 @@ +// Comparisons of model members, shared by test_golden.cpp, test_model.cpp, test_reader.cpp and +// test_contracts.cpp. +// +// * equal_member(value, json): a member against a decoded fixture value or a JSON default, as the +// fixture tooling and the contract table write them ("nan", "inf" and "-inf" for floats). +// * nan_equal(a, b): two members of the same type, NaN equal to NaN. Tests of other behaviour +// compare with a default-constructed object through it, never with a literal default. +// * member_json(value): the JSON form equal_member() reads, for messages. +// * all_nan(values): every element is NaN. + +#pragma once + +#include + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace spine_test { + +template +struct is_std_array : std::false_type {}; +template +struct is_std_array> : std::true_type {}; +template +struct is_std_vector : std::false_type {}; +template +struct is_std_vector> : std::true_type {}; + +/// True if `value` is what `want` holds. Floats compare as the member's own type: the fixture +/// stores the exact double of a float32, and a float64 column read into a float member is rounded +/// to float. +template +bool equal_member(const M& value, const nlohmann::json& want) { + if constexpr (std::is_same_v) { + return want.is_string() && want.get() == value; + } else if constexpr (std::is_same_v) { + if (want.is_boolean()) return want.get() == value; + return want.is_number() && (want.get() != 0) == value; + } else if constexpr (std::is_enum_v) { + return want.is_number_integer() && want.get() == static_cast(value); + } else if constexpr (std::is_floating_point_v) { + if (want.is_string()) { + const std::string text = want.get(); + if (text == "nan") return std::isnan(value); + if (text == "inf") return std::isinf(value) && value > 0; + if (text == "-inf") return std::isinf(value) && value < 0; + return false; + } + return want.is_number() && static_cast(want.get()) == value; + } else if constexpr (std::is_arithmetic_v) { + return want.is_number_integer() && static_cast(want.get()) == value; + } else { + static_assert(is_std_array::value || is_std_vector::value, "unsupported member"); + if (!want.is_array() || want.size() != value.size()) return false; + for (std::size_t i = 0; i < value.size(); ++i) { + if (!equal_member(value[i], want[i])) return false; + } + return true; + } +} + +/// a == b, element by element for arrays and vectors, with NaN equal to NaN. +template +bool nan_equal(const M& a, const M& b) { + if constexpr (std::is_floating_point_v) { + return (std::isnan(a) && std::isnan(b)) || a == b; + } else if constexpr (is_std_array::value || is_std_vector::value) { + if (a.size() != b.size()) return false; + for (std::size_t i = 0; i < a.size(); ++i) { + if (!nan_equal(a[i], b[i])) return false; + } + return true; + } else { + return a == b; + } +} + +/// The JSON form of a member that equal_member() accepts, for failure messages. +template +nlohmann::json member_json(const M& value) { + if constexpr (std::is_same_v || std::is_same_v) { + return value; + } else if constexpr (std::is_enum_v) { + return static_cast(value); + } else if constexpr (std::is_floating_point_v) { + if (std::isnan(value)) return "nan"; + if (std::isinf(value)) return value > 0 ? "inf" : "-inf"; + return static_cast(value); + } else if constexpr (std::is_arithmetic_v) { + return static_cast(value); + } else { + nlohmann::json values = nlohmann::json::array(); + for (const auto& v : value) values.push_back(member_json(v)); + return values; + } +} + +template +bool all_nan(const A& values) { + return std::all_of(values.begin(), values.end(), [](auto v) { return std::isnan(v); }); +} + +} // namespace spine_test diff --git a/tests/test_contracts.cpp b/tests/test_contracts.cpp new file mode 100644 index 0000000..0d19a18 --- /dev/null +++ b/tests/test_contracts.cpp @@ -0,0 +1,410 @@ +// Consumer contracts: what the CAFMakers rely on. A failure means a maintainer reviews the SPINE +// change with the CAFMaker maintainers before a release. +// +// kFields has one row per model field a CAFMaker reads: class, field, unit, the default as a JSON +// literal (as tools/fixtures writes values: floats "nan", "inf" and "-inf"), and the CAFMakers +// that read it. The rows were written once, from a scan of the ND, SBN and FD ports on +// 2026-11-05 (DUNE/ND_CAFMaker#213, justinjmueller/sbn_ml_cafmaker#8, DUNE/dune_ml_cafmaker#1) and +// the units and defaults of SPINE 1.4.0: 228 fields. After that a row changes only by hand: add +// one when a CAFMaker starts reading a field +// (tools/release/scan_consumer_fields.py lists the fields a CAFMaker build reads that have no +// row), and edit one only after talking to the CAFMaker maintainers. +// +// Every test case name starts with "contract: ". ctest runs them as their own entry, +// spine_reader_contracts. + +#include +#include + +#include +#include +#include +#include +#include +#include +#include + +#include + +#include "golden_members.inc" +#include "member_compare.hpp" + +namespace { + +using nlohmann::json; + +// std::string_view, not const char*: doctest prints a char pointer as an address. +struct FieldContract { + std::string_view class_name; + std::string_view field; + std::string_view unit; ///< the descriptor's units; "" for none + std::string_view default_json; ///< the member of a default-constructed object + std::string_view readers; ///< the CAFMakers that read it +}; + +// One row per field: {"Class", "field", "unit", R"(default)", "readers"}, with the class and the +// field on the row's first line. scan_consumer_fields.py --contracts reads them from there. +const FieldContract kFields[] = { + // RecoParticle + {"RecoParticle", "is_truth", "", R"(false)", "SBN"}, + {"RecoParticle", "id", "", R"(-1)", "ND SBN"}, + {"RecoParticle", "is_contained", "", R"(false)", "ND SBN FD"}, + {"RecoParticle", "is_time_contained", "", R"(false)", "SBN"}, + {"RecoParticle", "is_cathode_crosser", "", R"(false)", "SBN"}, + {"RecoParticle", "is_matched", "", R"(false)", "SBN"}, + {"RecoParticle", "cathode_offset", "cm", R"("nan")", "SBN"}, + {"RecoParticle", "match_ids", "", R"([])", "ND SBN FD"}, + {"RecoParticle", "match_overlaps", "", R"([])", "ND SBN FD"}, + {"RecoParticle", "interaction_id", "", R"(-1)", "ND SBN"}, + {"RecoParticle", "chi2_pid", "", R"(-1)", "SBN"}, + {"RecoParticle", "is_primary", "", R"(false)", "ND SBN FD"}, + {"RecoParticle", "is_valid", "", R"(true)", "SBN"}, + {"RecoParticle", "length", "instance", R"("nan")", "SBN"}, + {"RecoParticle", "calo_ke", "MeV", R"("nan")", "ND SBN"}, + {"RecoParticle", "csda_ke", "MeV", R"("nan")", "ND SBN"}, + {"RecoParticle", "mcs_ke", "MeV", R"("nan")", "ND SBN"}, + {"RecoParticle", "shape", "", R"(-1)", "ND SBN"}, + {"RecoParticle", "pid", "", R"(-1)", "SBN"}, + {"RecoParticle", "fragment_ids", "instance", R"([])", "SBN"}, + {"RecoParticle", "start_point", "instance", R"(["nan", "nan", "nan"])", "ND SBN FD"}, + {"RecoParticle", "end_point", "instance", R"(["nan", "nan", "nan"])", "ND SBN FD"}, + {"RecoParticle", "chi2_per_pid", "", R"(["nan", "nan", "nan", "nan", "nan", "nan"])", "SBN"}, + {"RecoParticle", "csda_ke_per_pid", "MeV", + R"(["nan", "nan", "nan", "nan", "nan", "nan"])", "SBN"}, + {"RecoParticle", "mcs_ke_per_pid", "MeV", + R"(["nan", "nan", "nan", "nan", "nan", "nan"])", "SBN"}, + {"RecoParticle", "start_dedx", "MeV/cm", R"("nan")", "SBN"}, + {"RecoParticle", "vertex_distance", "instance", R"("nan")", "SBN"}, + {"RecoParticle", "start_straightness", "", R"("nan")", "SBN"}, + {"RecoParticle", "directional_spread", "", R"("nan")", "SBN"}, + {"RecoParticle", "axial_spread", "", R"("nan")", "SBN"}, + {"RecoParticle", "start_dir", "", R"(["nan", "nan", "nan"])", "ND SBN"}, + {"RecoParticle", "end_dir", "", R"(["nan", "nan", "nan"])", "ND SBN"}, + {"RecoParticle", "pid_scores", "", R"(["nan", "nan", "nan", "nan", "nan", "nan"])", "SBN"}, + {"RecoParticle", "primary_scores", "", R"(["nan", "nan"])", "SBN"}, + {"RecoParticle", "ppn_ids", "", R"([])", "SBN"}, + {"RecoParticle", "pdg_code", "", R"(0)", "ND SBN FD"}, + {"RecoParticle", "mass", "MeV/c^2", R"("nan")", "ND SBN"}, + {"RecoParticle", "ke", "MeV", R"("nan")", "SBN FD"}, + {"RecoParticle", "momentum", "MeV/c", R"(["nan", "nan", "nan"])", "ND SBN FD"}, + {"RecoParticle", "p", "MeV/c", R"("nan")", "SBN"}, + {"RecoParticle", "num_fragments", "", R"(0)", "SBN"}, + {"RecoParticle", "size", "", R"(0)", "SBN"}, + {"RecoParticle", "depositions_sum", "", R"(0.0)", "SBN"}, + {"RecoParticle", "module_ids", "", R"([])", "SBN"}, + + // TruthParticle + {"TruthParticle", "orig_id", "", R"(-1)", "SBN"}, + {"TruthParticle", "is_truth", "", R"(true)", "SBN"}, + {"TruthParticle", "id", "", R"(-1)", "ND SBN FD"}, + {"TruthParticle", "is_contained", "", R"(false)", "SBN"}, + {"TruthParticle", "is_time_contained", "", R"(false)", "SBN"}, + {"TruthParticle", "is_cathode_crosser", "", R"(false)", "SBN"}, + {"TruthParticle", "is_matched", "", R"(false)", "SBN"}, + {"TruthParticle", "cathode_offset", "cm", R"("nan")", "SBN"}, + {"TruthParticle", "match_ids", "", R"([])", "SBN"}, + {"TruthParticle", "match_overlaps", "", R"([])", "SBN"}, + {"TruthParticle", "interaction_id", "", R"(-1)", "ND SBN FD"}, + {"TruthParticle", "is_primary", "", R"(false)", "ND SBN"}, + {"TruthParticle", "is_valid", "", R"(true)", "SBN"}, + {"TruthParticle", "length", "instance", R"("nan")", "SBN"}, + {"TruthParticle", "calo_ke", "MeV", R"("nan")", "SBN"}, + {"TruthParticle", "csda_ke", "MeV", R"("nan")", "SBN"}, + {"TruthParticle", "mcs_ke", "MeV", R"("nan")", "SBN"}, + {"TruthParticle", "shape", "", R"(-1)", "SBN"}, + {"TruthParticle", "pid", "", R"(-1)", "SBN"}, + {"TruthParticle", "fragment_ids", "instance", R"([])", "SBN"}, + {"TruthParticle", "start_point", "instance", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "end_point", "instance", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "csda_ke_per_pid", "MeV", + R"(["nan", "nan", "nan", "nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "mcs_ke_per_pid", "MeV", + R"(["nan", "nan", "nan", "nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "parent_id", "", R"(-1)", "SBN"}, + {"TruthParticle", "group_id", "", R"(-1)", "SBN"}, + {"TruthParticle", "nu_id", "", R"(-1)", "SBN"}, + {"TruthParticle", "children_id", "", R"([])", "SBN"}, + {"TruthParticle", "mct_index", "", R"(-1)", "SBN"}, + {"TruthParticle", "mcst_index", "", R"(-1)", "SBN"}, + {"TruthParticle", "group_primary", "", R"(-1)", "SBN"}, + {"TruthParticle", "interaction_primary", "", R"(-1)", "SBN"}, + {"TruthParticle", "track_id", "", R"(-1)", "ND SBN FD"}, + {"TruthParticle", "parent_track_id", "", R"(-1)", "SBN"}, + {"TruthParticle", "ancestor_track_id", "", R"(-1)", "SBN"}, + {"TruthParticle", "pdg_code", "", R"(0)", "ND SBN FD"}, + {"TruthParticle", "parent_pdg_code", "", R"(0)", "SBN"}, + {"TruthParticle", "ancestor_pdg_code", "", R"(0)", "SBN"}, + {"TruthParticle", "num_voxels", "", R"(-1)", "SBN"}, + {"TruthParticle", "t", "ns", R"("nan")", "SBN"}, + {"TruthParticle", "end_t", "ns", R"("nan")", "SBN"}, + {"TruthParticle", "parent_t", "ns", R"("nan")", "SBN"}, + {"TruthParticle", "ancestor_t", "ns", R"("nan")", "SBN"}, + {"TruthParticle", "energy_init", "MeV", R"("nan")", "ND SBN FD"}, + {"TruthParticle", "energy_deposit", "MeV", R"("nan")", "SBN"}, + {"TruthParticle", "distance_travel", "cm", R"("nan")", "SBN"}, + {"TruthParticle", "creation_process", "", R"("")", "SBN"}, + {"TruthParticle", "parent_creation_process", "", R"("")", "SBN"}, + {"TruthParticle", "ancestor_creation_process", "", R"("")", "SBN"}, + {"TruthParticle", "position", "instance", R"(["nan", "nan", "nan"])", "ND SBN FD"}, + {"TruthParticle", "end_position", "instance", R"(["nan", "nan", "nan"])", "ND SBN FD"}, + {"TruthParticle", "parent_position", "instance", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "ancestor_position", "instance", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "first_step", "instance", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "last_step", "instance", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "momentum", "MeV/c", R"(["nan", "nan", "nan"])", "ND SBN FD"}, + {"TruthParticle", "end_momentum", "MeV/c", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "orig_interaction_id", "", R"(-1)", "ND SBN"}, + {"TruthParticle", "orig_parent_id", "", R"(-1)", "SBN"}, + {"TruthParticle", "orig_group_id", "", R"(-1)", "SBN"}, + {"TruthParticle", "reco_length", "", R"("nan")", "SBN"}, + {"TruthParticle", "orig_children_id", "", R"([])", "SBN"}, + {"TruthParticle", "children_counts", "", R"([])", "SBN"}, + {"TruthParticle", "reco_start_dir", "", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "reco_end_dir", "", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "start_dir", "", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "end_dir", "", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "ke", "MeV", R"("nan")", "SBN"}, + {"TruthParticle", "reco_ke", "MeV", R"("nan")", "SBN"}, + {"TruthParticle", "reco_momentum", "MeV/c", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthParticle", "p", "MeV/c", R"("nan")", "SBN"}, + {"TruthParticle", "end_p", "MeV/c", R"("nan")", "SBN"}, + {"TruthParticle", "mass", "MeV/c^2", R"("nan")", "SBN"}, + {"TruthParticle", "num_fragments", "", R"(0)", "SBN"}, + {"TruthParticle", "size", "", R"(0)", "SBN"}, + {"TruthParticle", "depositions_sum", "", R"(0.0)", "SBN"}, + {"TruthParticle", "depositions_q_sum", "", R"(0.0)", "SBN"}, + {"TruthParticle", "module_ids", "", R"([])", "SBN"}, + {"TruthParticle", "size_adapt", "", R"(0)", "SBN"}, + {"TruthParticle", "size_g4", "", R"(0)", "SBN"}, + {"TruthParticle", "depositions_adapt_sum", "", R"(0.0)", "SBN"}, + {"TruthParticle", "depositions_adapt_q_sum", "", R"(0.0)", "SBN"}, + {"TruthParticle", "depositions_g4_sum", "", R"(0.0)", "SBN"}, + + // RecoInteraction + {"RecoInteraction", "is_truth", "", R"(false)", "SBN"}, + {"RecoInteraction", "id", "", R"(-1)", "ND SBN FD"}, + {"RecoInteraction", "is_contained", "", R"(false)", "SBN"}, + {"RecoInteraction", "is_time_contained", "", R"(false)", "SBN"}, + {"RecoInteraction", "is_cathode_crosser", "", R"(false)", "SBN"}, + {"RecoInteraction", "is_matched", "", R"(false)", "SBN"}, + {"RecoInteraction", "cathode_offset", "cm", R"("nan")", "SBN"}, + {"RecoInteraction", "match_ids", "", R"([])", "ND SBN FD"}, + {"RecoInteraction", "match_overlaps", "", R"([])", "ND SBN FD"}, + {"RecoInteraction", "is_fiducial", "", R"(false)", "SBN"}, + {"RecoInteraction", "is_flash_matched", "", R"(false)", "SBN"}, + {"RecoInteraction", "flash_total_pe", "", R"("nan")", "ND SBN"}, + {"RecoInteraction", "flash_hypo_pe", "", R"("nan")", "ND SBN"}, + {"RecoInteraction", "particle_ids", "", R"([])", "SBN FD"}, + {"RecoInteraction", "vertex", "instance", R"(["nan", "nan", "nan"])", "ND SBN FD"}, + {"RecoInteraction", "flash_ids", "", R"([])", "SBN"}, + {"RecoInteraction", "flash_volume_ids", "", R"([])", "SBN"}, + {"RecoInteraction", "flash_times", "us", R"([])", "SBN"}, + {"RecoInteraction", "flash_scores", "", R"([])", "SBN"}, + {"RecoInteraction", "primary_particle_ids", "", R"([])", "SBN"}, + {"RecoInteraction", "num_particles", "", R"(0)", "SBN"}, + {"RecoInteraction", "num_primary_particles", "", R"(0)", "SBN"}, + {"RecoInteraction", "particle_counts", "", R"([0, 0, 0, 0, 0, 0])", "SBN"}, + {"RecoInteraction", "primary_particle_counts", "", R"([0, 0, 0, 0, 0, 0])", "SBN"}, + {"RecoInteraction", "topology", "", R"("")", "SBN"}, + {"RecoInteraction", "size", "", R"(0)", "SBN"}, + {"RecoInteraction", "depositions_sum", "", R"(0.0)", "SBN"}, + {"RecoInteraction", "module_ids", "", R"([])", "SBN"}, + + // TruthInteraction + {"TruthInteraction", "orig_id", "", R"(-1)", "ND SBN"}, + {"TruthInteraction", "is_truth", "", R"(true)", "SBN"}, + {"TruthInteraction", "id", "", R"(-1)", "ND SBN FD"}, + {"TruthInteraction", "is_contained", "", R"(false)", "SBN"}, + {"TruthInteraction", "is_time_contained", "", R"(false)", "SBN"}, + {"TruthInteraction", "is_cathode_crosser", "", R"(false)", "SBN"}, + {"TruthInteraction", "is_matched", "", R"(false)", "SBN"}, + {"TruthInteraction", "cathode_offset", "cm", R"("nan")", "SBN"}, + {"TruthInteraction", "match_ids", "", R"([])", "SBN"}, + {"TruthInteraction", "match_overlaps", "", R"([])", "SBN"}, + {"TruthInteraction", "is_fiducial", "", R"(false)", "SBN"}, + {"TruthInteraction", "is_flash_matched", "", R"(false)", "SBN"}, + {"TruthInteraction", "flash_total_pe", "", R"("nan")", "SBN"}, + {"TruthInteraction", "flash_hypo_pe", "", R"("nan")", "SBN"}, + {"TruthInteraction", "particle_ids", "", R"([])", "SBN FD"}, + {"TruthInteraction", "vertex", "instance", R"(["nan", "nan", "nan"])", "SBN FD"}, + {"TruthInteraction", "flash_ids", "", R"([])", "SBN"}, + {"TruthInteraction", "flash_volume_ids", "", R"([])", "SBN"}, + {"TruthInteraction", "flash_times", "us", R"([])", "SBN"}, + {"TruthInteraction", "flash_scores", "", R"([])", "SBN"}, + {"TruthInteraction", "current_type", "", R"(-1)", "SBN"}, + {"TruthInteraction", "interaction_mode", "", R"(-1)", "SBN"}, + {"TruthInteraction", "interaction_type", "", R"(-1)", "SBN"}, + {"TruthInteraction", "mct_index", "", R"(-1)", "SBN"}, + {"TruthInteraction", "track_id", "", R"(-1)", "SBN"}, + {"TruthInteraction", "lepton_track_id", "", R"(-1)", "SBN"}, + {"TruthInteraction", "pdg_code", "", R"(0)", "SBN FD"}, + {"TruthInteraction", "lepton_pdg_code", "", R"(0)", "SBN"}, + {"TruthInteraction", "target", "", R"(0)", "SBN"}, + {"TruthInteraction", "nucleon", "", R"(0)", "SBN"}, + {"TruthInteraction", "quark", "", R"(0)", "SBN"}, + {"TruthInteraction", "energy_init", "GeV", R"("nan")", "SBN FD"}, + {"TruthInteraction", "hadronic_invariant_mass", "GeV/c^2", R"("nan")", "SBN"}, + {"TruthInteraction", "momentum_transfer", "(GeV/c)^2", R"("nan")", "SBN"}, + {"TruthInteraction", "momentum_transfer_mag", "GeV/c", R"("nan")", "SBN"}, + {"TruthInteraction", "energy_transfer", "GeV", R"("nan")", "SBN"}, + {"TruthInteraction", "lepton_p", "GeV/c", R"("nan")", "SBN"}, + {"TruthInteraction", "distance_travel", "instance", R"("nan")", "SBN"}, + {"TruthInteraction", "theta", "rad", R"("nan")", "SBN"}, + {"TruthInteraction", "bjorken_x", "", R"("nan")", "SBN"}, + {"TruthInteraction", "inelasticity", "", R"("nan")", "SBN"}, + {"TruthInteraction", "creation_process", "", R"("")", "SBN"}, + {"TruthInteraction", "position", "instance", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthInteraction", "momentum", "MeV/c", R"(["nan", "nan", "nan"])", "SBN FD"}, + {"TruthInteraction", "nu_id", "", R"(-1)", "SBN"}, + {"TruthInteraction", "reco_vertex", "instance", R"(["nan", "nan", "nan"])", "SBN"}, + {"TruthInteraction", "primary_particle_ids", "", R"([])", "SBN"}, + {"TruthInteraction", "num_particles", "", R"(0)", "SBN"}, + {"TruthInteraction", "num_primary_particles", "", R"(0)", "SBN"}, + {"TruthInteraction", "particle_counts", "", R"([0, 0, 0, 0, 0, 0])", "SBN"}, + {"TruthInteraction", "primary_particle_counts", "", R"([0, 0, 0, 0, 0, 0])", "SBN"}, + {"TruthInteraction", "topology", "", R"("")", "SBN"}, + {"TruthInteraction", "size", "", R"(0)", "SBN"}, + {"TruthInteraction", "depositions_sum", "", R"(0.0)", "SBN"}, + {"TruthInteraction", "depositions_q_sum", "", R"(0.0)", "SBN"}, + {"TruthInteraction", "module_ids", "", R"([])", "SBN"}, + {"TruthInteraction", "size_adapt", "", R"(0)", "SBN"}, + {"TruthInteraction", "size_g4", "", R"(0)", "SBN"}, + {"TruthInteraction", "depositions_adapt_sum", "", R"(0.0)", "SBN"}, + {"TruthInteraction", "depositions_adapt_q_sum", "", R"(0.0)", "SBN"}, + {"TruthInteraction", "depositions_g4_sum", "", R"(0.0)", "SBN"}, + + // RunInfo + {"RunInfo", "run", "", R"(-1)", "ND SBN FD"}, + {"RunInfo", "subrun", "", R"(-1)", "ND SBN FD"}, + {"RunInfo", "event", "", R"(-1)", "ND SBN FD"}, + + // Trigger + {"Trigger", "id", "", R"(-1)", "ND"}, + {"Trigger", "type", "", R"(-1)", "ND"}, + {"Trigger", "time_s", "s", R"(-1)", "ND"}, + {"Trigger", "time_ns", "ns", R"(-1)", "ND"}, + + // Flash + {"Flash", "id", "", R"(-1)", "ND"}, + {"Flash", "volume_id", "", R"(-1)", "ND"}, + {"Flash", "time", "us", R"("nan")", "ND"}, + {"Flash", "time_width", "us", R"("nan")", "ND"}, + {"Flash", "total_pe", "", R"("nan")", "ND"}, +}; + +/// The classes of kFields, in table order. +std::vector table_classes() { + std::vector classes; + for (const FieldContract& row : kFields) { + if (classes.empty() || classes.back() != row.class_name) { + classes.emplace_back(row.class_name); + } + } + return classes; +} + +/// Checks the row of one member, if it has one, and records that the row was seen. +template +void check_member(const spine::ClassDescriptor& d, std::string_view name, const M& value, + std::set& seen) { + for (const FieldContract& row : kFields) { + if (d.name != row.class_name || name != row.field) continue; + seen.insert(&row); + INFO(row.class_name << "." << row.field << ", read by " << row.readers); + const spine::FieldDescriptor* field = d.find(name); + REQUIRE(field != nullptr); + CHECK_MESSAGE(field->units == row.unit, "unit: the model has '" << field->units + << "', the contract '" + << row.unit << "'"); + CHECK_MESSAGE(spine_test::equal_member(value, json::parse(std::string(row.default_json))), + "default: the model has " << spine_test::member_json(value).dump() + << ", the contract " << row.default_json); + } +} + +using ClassCheck = void (*)(std::set&); + +/// For each model class, a function that checks the rows of its members. +const std::map& class_checks() { +#define CONTRACT_MEMBER(name) check_member(d, #name, object.name, seen); +#define CONTRACT_CLASS(Class) \ + {#Class, [](std::set& seen) { \ + const spine::Class object{}; \ + const spine::ClassDescriptor& d = spine::Class::descriptor(); \ + GOLDEN_MEMBERS_##Class(CONTRACT_MEMBER) \ + }}, + static const std::map checks = { + SPINE_READER_FOR_EACH_CLASS(CONTRACT_CLASS)}; +#undef CONTRACT_CLASS +#undef CONTRACT_MEMBER + return checks; +} + +struct MemberContract { + std::string_view name; + std::int64_t value; +}; + +/// Every listed member is in the enum, with that value. Members SPINE adds are not a change. +void check_members(const spine::EnumDescriptor& d, std::initializer_list members) { + INFO(d.name); + for (const MemberContract& m : members) { + INFO(m.name); + const spine::EnumMember* found = nullptr; + for (std::size_t i = 0; i < d.size; ++i) { + if (d.members[i].name == m.name) found = &d.members[i]; + } + CHECK_MESSAGE(found != nullptr, "not in the model"); + if (found != nullptr) CHECK(found->value == m.value); + } +} + +} // namespace + +TEST_CASE("contract: every class a CAFMaker reads is in the model") { + for (const std::string& name : table_classes()) { + CHECK_MESSAGE(class_checks().count(name) == 1, + name << ": in the contract table, not in the model"); + } +} + +TEST_CASE("contract: the fields the CAFMakers read keep their units and defaults") { + std::set seen; + for (const std::string& name : table_classes()) { + const auto check = class_checks().find(name); + if (check != class_checks().end()) check->second(seen); + } + // a row whose field the model no longer has + for (const FieldContract& row : kFields) { + if (seen.count(&row) == 0 && class_checks().count(std::string(row.class_name)) == 1) { + FAIL_CHECK(row.class_name << "." << row.field << ": listed for " << row.readers + << ", not in the model"); + } + } +} + +TEST_CASE("contract: the enum values the CAFMakers rely on") { + // ND compares shape with ParticleShape::TRACK and SHOWER, and current_type with + // NuCurrentType::CC and NC. SBN stores the numbers of shape, pid, chi2_pid and current_type in + // its CAF. No CAFMaker reads interaction_scheme or uses the interaction tables: SBN stores + // interaction_mode and interaction_type as SPINE's numbers. + check_members(spine::enum_descriptor(), + {{"UNKNOWN", -1}, + {"SHOWER", 0}, + {"TRACK", 1}, + {"MICHEL", 2}, + {"DELTA", 3}, + {"LOWE", 4}, + {"GHOST", 5}, + {"LARCV_UNKNOWN", 6}}); + check_members(spine::enum_descriptor(), + {{"UNKNOWN", -1}, + {"PHOTON", 0}, + {"ELECTRON", 1}, + {"MUON", 2}, + {"PION", 3}, + {"PROTON", 4}, + {"KAON", 5}}); + check_members(spine::enum_descriptor(), + {{"UNKNOWN", -1}, {"CC", 0}, {"NC", 1}}); +} diff --git a/tests/test_core_real.cpp b/tests/test_core_real.cpp index 008438b..fea8fe7 100644 --- a/tests/test_core_real.cpp +++ b/tests/test_core_real.cpp @@ -151,7 +151,11 @@ TEST_CASE("real files: through the Reader, the relations SPINE guarantees hold" for (const ProductReport& product : report.products) { INFO("product " << product.product << "\n" << report.summary()); CHECK(product.mismatched.empty()); // the file and the model agree on every shared column - CHECK(product.missing.empty()); + // a file of the model's SPINE release has every model field; an older one lacks the fields + // SPINE added since + if (report.spine_version == SPINE_READER_MODEL_SPINE_VERSION) { + CHECK(product.missing.empty()); + } } for (std::uint64_t e = 0; e < reader.num_events(); ++e) { diff --git a/tests/test_golden.cpp b/tests/test_golden.cpp index 5337234..58ab8c0 100644 --- a/tests/test_golden.cpp +++ b/tests/test_golden.cpp @@ -4,7 +4,9 @@ // // The cases are the *.expected.json files of the directory: the current set (current_*, written // by the model's SPINE tag) and the frozen cases (written by older releases, never rewritten). -// tools/fixtures/make_fixtures.py writes them. +// tools/fixtures/make_fixtures.py writes them. The current set is also checked against the model +// column by column (column_problems), so a field SPINE adds, removes or retypes shows here once +// the new tag's fixtures are in place. #include #include @@ -19,7 +21,6 @@ #include #include #include -#include #include #include @@ -28,6 +29,7 @@ #include #include "core/source.hpp" +#include "member_compare.hpp" namespace { @@ -269,46 +271,7 @@ namespace { // Model objects against the decoded fixture, member by member (golden_members.inc lists them) // --------------------------------------------------------------------------------------------- -template -struct is_std_array : std::false_type {}; -template -struct is_std_array> : std::true_type {}; -template -struct is_std_vector : std::false_type {}; -template -struct is_std_vector> : std::true_type {}; - -/// True if `value` is what the fixture holds. Floats compare as the member's own type: the -/// fixture stores the exact double of a float32, and a float64 column read into a float member -/// is rounded to float. -template -bool equal_member(const M& value, const json& want) { - if constexpr (std::is_same_v) { - return want.is_string() && want.get() == value; - } else if constexpr (std::is_same_v) { - return want.is_boolean() ? want.get() == value : (want.get() != 0) == value; - } else if constexpr (std::is_enum_v) { - return want.is_number_integer() && want.get() == static_cast(value); - } else if constexpr (std::is_floating_point_v) { - if (want.is_string()) { - const std::string text = want.get(); - if (text == "nan") return std::isnan(value); - if (text == "inf") return std::isinf(value) && value > 0; - if (text == "-inf") return std::isinf(value) && value < 0; - return false; - } - return want.is_number() && static_cast(want.get()) == value; - } else if constexpr (std::is_arithmetic_v) { - return want.is_number_integer() && static_cast(want.get()) == value; - } else { - static_assert(is_std_array::value || is_std_vector::value, "unsupported member"); - if (!want.is_array() || want.size() != value.size()) return false; - for (std::size_t i = 0; i < value.size(); ++i) { - if (!equal_member(value[i], want[i])) return false; - } - return true; - } -} +using spine_test::equal_member; #include "golden_members.inc" @@ -364,13 +327,78 @@ const json* by_id(const json& rows, std::int64_t id) { return nullptr; } +// --------------------------------------------------------------------------------------------- +// The model against the columns of the current set +// --------------------------------------------------------------------------------------------- + +/// How a product was written: every field, or SPINE's lite mode (which drops the lite_skip ones). +enum class Role { Full, Lite }; + +struct ColumnCheck { + std::vector problems; ///< each one fails the golden test + std::vector notes; ///< width differences: printed, never a failure +}; + +/// bool, integer, float or string, from a type name ("float32", "uint8", ...) of either side. +std::string kind_of(const std::string& type) { + if (type == "bool" || type == "string") return type; + if (type.rfind("int", 0) == 0 || type.rfind("uint", 0) == 0) return "integer"; + if (type.rfind("float", 0) == 0) return "float"; + return "unknown type " + type; +} + +/// What differs between the fields of `d` and the decoded columns of `product`, a product of a +/// current fixture written in `role`: +/// * a full product has a column for every field, and a lite one for every field that is not +/// lite_skip, and no column for a lite_skip field; +/// * no column is outside the model; +/// * each field has the element kind of its column. SPINE's writer picks float widths from the +/// first object's Python value, so widths are only notes. +/// Field order is not compared: binding is by name. +ColumnCheck column_problems(const spine::ClassDescriptor& d, const json& product, Role role) { + ColumnCheck out; + const json& columns = product["columns"]; + for (std::size_t i = 0; i < d.num_fields; ++i) { + const spine::FieldDescriptor& f = d.fields[i]; + const std::string name(f.name); + const bool lite_skip = (f.flags & spine::kLiteSkip) != 0; + if (!columns.contains(name)) { + if (!(role == Role::Lite && lite_skip)) out.problems.push_back(name + ": no column"); + continue; + } + if (role == Role::Lite && lite_skip) { + out.problems.push_back(name + ": lite_skip in the model, but the lite file has the column"); + } + const std::string model_type(spine::to_string(f.type)); + const std::string file_type = columns[name]["type"].get(); + if (kind_of(model_type) != kind_of(file_type)) { + out.problems.push_back(name + ": the model stores " + model_type + ", the file " + file_type); + } else if (model_type != file_type) { + out.notes.push_back(name + ": the model stores " + model_type + ", the file " + file_type); + } + } + for (const auto& [column, unused] : columns.items()) { + if (d.find(column) == nullptr) { + out.problems.push_back(column + ": a column the model does not have"); + } + } + return out; +} + } // namespace TEST_CASE("the reader fills every member of every model object as the fixtures say") { std::size_t objects_checked = 0; - for (const std::string& name : complete_cases()) { + std::map> width_notes; // note -> the cases that have it + std::set checked_classes; // the classes compared with a current fixture's columns + for (const Case& c : all_cases()) { + if (!c.complete) continue; + const std::string& name = c.name; INFO("fixture " << name); const json want = expected(name); + // current_v2_fixed_only holds a subset of the columns by design + const bool check_columns = c.current && name != "current_v2_fixed_only"; + const Role role = want["writer"]["lite"].get() ? Role::Lite : Role::Full; spine::Reader reader(fixture(name, ".h5")); REQUIRE(reader.num_events() == want["num_events"].get()); REQUIRE(reader.num_files() == 1); @@ -409,6 +437,17 @@ TEST_CASE("the reader fills every member of every model object as the fixtures s CHECK(std::set(found->extra.begin(), found->extra.end()) == want_extra); CHECK(found->mismatched.empty()); CHECK(found->complete() == want_missing.empty()); // extra columns do not count + + if (check_columns) { + const ColumnCheck columns = column_problems(cls, product, role); + for (const std::string& problem : columns.problems) { + FAIL_CHECK(cls.name << "." << problem); + } + for (const std::string& note : columns.notes) { + width_notes[std::string(cls.name) + "." + note].insert(name); + } + checked_classes.insert(std::string(cls.name)); + } } CHECK(report.products.size() == reported); @@ -429,6 +468,84 @@ TEST_CASE("the reader fills every member of every model object as the fixtures s } } CHECK(objects_checked > 300); // the loops above are not empty (about 50 objects per fixture) + + CHECK_FALSE(checked_classes.empty()); + for (const auto& [note, cases] : width_notes) { + std::string where; + for (const std::string& name : cases) where += (where.empty() ? "" : ", ") + name; + MESSAGE("width differs (not a failure): " << note << " (" << where << ")"); + } + for (const auto& [class_name, tools] : class_tools()) { + if (checked_classes.count(class_name) == 0) { + MESSAGE("not checked against a file: " << class_name << " (no current fixture writes it)"); + } + } +} + +TEST_CASE("column_problems reports what differs between the model and a product's columns") { + const json want = expected("current_v1"); + const json& product = want["products"]["reco_particles"]; + const spine::ClassDescriptor& d = + *class_tools().at(product["class_name"].get()).descriptor; + REQUIRE(column_problems(d, product, Role::Full).problems.empty()); + + // A column picked at run time, so that no SPINE change of one field breaks this test: the first + // model field that has a column and is not lite_skip. + std::string picked; + std::vector lite_skip; + for (std::size_t i = 0; i < d.num_fields; ++i) { + const std::string name(d.fields[i].name); + if ((d.fields[i].flags & spine::kLiteSkip) != 0) { + lite_skip.push_back(name); + } else if (picked.empty() && product["columns"].contains(name)) { + picked = name; + } + } + REQUIRE_FALSE(picked.empty()); + INFO("column " << picked); + + // removed: reported, and nothing else + json removed = product; + removed["columns"].erase(picked); + CHECK(column_problems(d, removed, Role::Full).problems == + std::vector{picked + ": no column"}); + + // a column the model does not have + std::string unknown = "not_a_model_field"; + while (d.find(unknown) != nullptr) unknown += "_"; + json extra = product; + extra["columns"][unknown] = product["columns"][picked]; + CHECK(column_problems(d, extra, Role::Full).problems == + std::vector{unknown + ": a column the model does not have"}); + + // another kind of element is a problem; another width of the same kind is a note + const std::string model_type(spine::to_string(d.find(picked)->type)); + json retyped = product; + retyped["columns"][picked]["type"] = model_type == "string" ? "int64" : "string"; + CHECK(column_problems(d, retyped, Role::Full).problems.size() == 1); + if (kind_of(model_type) == "integer" || kind_of(model_type) == "float") { + json widened = product; + widened["columns"][picked]["type"] = kind_of(model_type) == "float" + ? (model_type == "float32" ? "float64" : "float32") + : (model_type == "int8" ? "int16" : "int8"); + const ColumnCheck widths = column_problems(d, widened, Role::Full); + CHECK(widths.problems.empty()); + CHECK(widths.notes.size() == 1); + } + + // a lite product: the lite_skip fields are missing, both ways + if (lite_skip.empty()) { + MESSAGE("no lite_skip field in " << d.name << ": the lite checks are not exercised"); + } else { + CHECK(column_problems(d, product, Role::Lite).problems.size() == lite_skip.size()); + json lite = product; + for (const std::string& name : lite_skip) lite["columns"].erase(name); + CHECK(column_problems(d, lite, Role::Lite).problems.empty()); + CHECK(column_problems(d, lite, Role::Full).problems.size() == lite_skip.size()); + lite["columns"].erase(picked); + CHECK(column_problems(d, lite, Role::Lite).problems == + std::vector{picked + ": no column"}); + } } namespace { diff --git a/tests/test_model.cpp b/tests/test_model.cpp index 4bbb5b6..81c8cda 100644 --- a/tests/test_model.cpp +++ b/tests/test_model.cpp @@ -1,8 +1,7 @@ -// Tests of the generated model (include/spine/model, src/model). -// -// The expected default values were printed from SPINE v1.4.0 itself: -// RecoParticle() ... FlashHypothesis() default-constructed, then getattr(obj, name). -// Enumerator counts and values are those of spine.constants.enums at the same release. +// Tests of the generated model (include/spine/model, src/model): the structure every generated +// class has, the C++ types of the members, the assign pointers and the enum descriptors. They hold +// for any SPINE tag. The units, defaults and enum values the CAFMakers rely on are checked by +// test_contracts.cpp, and the fields against the fixtures' columns by test_golden.cpp. // Standard and POSIX headers come first on purpose: any macro they define (NULL, EOF, DOMAIN, // OVERFLOW, errno, major, ...) must not collide with an identifier of the model headers. @@ -38,20 +37,19 @@ #include +#include "golden_members.inc" +#include "member_compare.hpp" + namespace { using spine::ScalarType; +using spine_test::nan_equal; namespace detail = spine::detail; // --------------------------------------------------------------------------------------------- // Helpers // --------------------------------------------------------------------------------------------- -template -bool all_nan(const A& values) { - return std::all_of(values.begin(), values.end(), [](auto v) { return std::isnan(v); }); -} - template detail::ColumnBuffer fixed_column(ScalarType type, std::size_t count, const std::vector& values) { @@ -70,37 +68,14 @@ std::size_t index_of(const spine::ClassDescriptor& d, std::string_view name) { return d.index_of(*f); } -/// The last enumerator of each class's Field enum. -template -struct Last; -#define LAST_FIELD(Class, field) \ - template <> \ - struct Last { \ - static constexpr spine::Class::Field value = spine::Class::Field::field; \ - } -LAST_FIELD(RecoParticle, module_ids); -LAST_FIELD(TruthParticle, depositions_g4_sum); -LAST_FIELD(RecoInteraction, module_ids); -LAST_FIELD(TruthInteraction, depositions_g4_sum); -LAST_FIELD(RunInfo, event); -LAST_FIELD(Trigger, beam_time_ns); -LAST_FIELD(ImageMeta3D, count); -LAST_FIELD(Flash, width); -LAST_FIELD(CRTHit, time); -LAST_FIELD(FlashHypothesis, total_pe); -#undef LAST_FIELD - /// Structure every generated class must have, whatever SPINE release it comes from. template -void check_structure(std::string_view name, std::size_t expected_fields) { +void check_structure(std::string_view name) { const spine::ClassDescriptor& d = C::descriptor(); INFO(name); CHECK(d.name == name); CHECK(d.schema_version == SPINE_READER_MODEL_SPINE_VERSION); - CHECK(d.schema_version == "1.4.0"); - CHECK(C::kNumFields == expected_fields); CHECK(d.num_fields == C::kNumFields); - CHECK(static_cast(Last::value) + 1 == d.num_fields); CHECK(&C::descriptor() == &d); // one descriptor per class std::set names; @@ -110,7 +85,6 @@ void check_structure(std::string_view name, std::size_t expected_fields) { CHECK(names.insert(f.name).second); // unique CHECK(f.assign != nullptr); // assignable CHECK(!f.name.empty()); - CHECK(!f.doc.empty()); // every SPINE field is documented CHECK(d.find(f.name) == &f); // find() and index_of() agree CHECK(d.index_of(f) == i); if (f.variable) { @@ -131,10 +105,10 @@ void check_structure(std::string_view name, std::size_t expected_fields) { CHECK_FALSE(object.has(static_cast(i))); } std::bitset mask; - mask.set(static_cast(Last::value)); + mask.set(C::kNumFields - 1); mask.set(0); detail::ObjectAccess::set_present(object, mask); - CHECK(object.has(Last::value)); + CHECK(object.has(static_cast(C::kNumFields - 1))); CHECK(object.has(static_cast(0))); if (C::kNumFields > 2) CHECK_FALSE(object.has(static_cast(1))); } @@ -145,60 +119,45 @@ void check_structure(std::string_view name, std::size_t expected_fields) { // Inventory and structure // --------------------------------------------------------------------------------------------- -TEST_CASE("model: SPINE_READER_FOR_EACH_CLASS lists every class once, in dump order") { +TEST_CASE("model: SPINE_READER_FOR_EACH_CLASS lists every class once") { std::vector names; #define COLLECT(Class) names.push_back(#Class); SPINE_READER_FOR_EACH_CLASS(COLLECT) #undef COLLECT - const std::vector expected = { - "RecoParticle", "TruthParticle", "RecoInteraction", "TruthInteraction", "RunInfo", - "Trigger", "ImageMeta3D", "Flash", "CRTHit", "FlashHypothesis"}; - CHECK(names == expected); + CHECK_FALSE(names.empty()); + CHECK(std::set(names.begin(), names.end()).size() == names.size()); // Each name in the macro is a class whose descriptor carries that name. std::vector described; #define DESCRIBE(Class) described.push_back(spine::Class::descriptor().name); SPINE_READER_FOR_EACH_CLASS(DESCRIBE) #undef DESCRIBE - CHECK(described == expected); + CHECK(described == names); } -TEST_CASE("model: field counts and descriptor structure of every class") { - check_structure("RecoParticle", 55); - check_structure("TruthParticle", 98); - check_structure("RecoInteraction", 40); - check_structure("TruthInteraction", 79); - check_structure("RunInfo", 3); - check_structure("Trigger", 6); - check_structure("ImageMeta3D", 4); - check_structure("Flash", 14); - check_structure("CRTHit", 14); - check_structure("FlashHypothesis", 8); +TEST_CASE("model: descriptor structure of every class") { +#define CHECK_STRUCTURE(Class) check_structure(#Class); + SPINE_READER_FOR_EACH_CLASS(CHECK_STRUCTURE) +#undef CHECK_STRUCTURE } -TEST_CASE("model: field i has the name of enumerator i") { - using spine::RecoParticle; - const auto& d = RecoParticle::descriptor(); - CHECK(d.fields[static_cast(RecoParticle::Field::is_truth)].name == "is_truth"); - CHECK(d.fields[static_cast(RecoParticle::Field::units)].name == "units"); - CHECK(d.fields[static_cast(RecoParticle::Field::start_point)].name == "start_point"); - CHECK(d.fields[static_cast(RecoParticle::Field::pdg_code)].name == "pdg_code"); - CHECK(d.fields[static_cast(RecoParticle::Field::module_ids)].name == "module_ids"); - CHECK(static_cast(RecoParticle::Field::is_truth) == 0); - CHECK(static_cast(RecoParticle::Field::module_ids) == 54); - - using spine::TruthInteraction; - const auto& t = TruthInteraction::descriptor(); - CHECK(t.fields[static_cast(TruthInteraction::Field::interaction_scheme)].name == - "interaction_scheme"); - CHECK(t.fields[static_cast(TruthInteraction::Field::time)].name == "time"); - CHECK(t.fields[static_cast(TruthInteraction::Field::dir)].name == "dir"); - - using spine::RunInfo; - CHECK(RunInfo::descriptor().fields[0].name == "run"); - CHECK(RunInfo::descriptor().fields[1].name == "subrun"); - CHECK(RunInfo::descriptor().fields[2].name == "event"); - CHECK(static_cast(RunInfo::Field::event) == 2); +TEST_CASE("model: field i has the name of enumerator i, for every field of every class") { + // golden_members.inc lists every member of every class, from the schema +#define CHECK_FIELD_NAME(member) \ + CHECK(d.fields[static_cast(Cls::Field::member)].name == #member); \ + ++listed; +#define CHECK_CLASS_FIELD_NAMES(Class) \ + { \ + using Cls = spine::Class; \ + const spine::ClassDescriptor& d = Cls::descriptor(); \ + INFO(#Class); \ + std::size_t listed = 0; \ + GOLDEN_MEMBERS_##Class(CHECK_FIELD_NAME) \ + CHECK(listed == Cls::kNumFields); \ + } + SPINE_READER_FOR_EACH_CLASS(CHECK_CLASS_FIELD_NAMES) +#undef CHECK_CLASS_FIELD_NAMES +#undef CHECK_FIELD_NAME } // --------------------------------------------------------------------------------------------- @@ -270,56 +229,11 @@ TEST_CASE("model: C++ types follow SPINE's declared types") { CHECK(spine::ImageMeta3D::descriptor().find("count")->type == ScalarType::Int64); } -TEST_CASE("model: descriptors carry SPINE's flags, units, references and enums") { +TEST_CASE("model: enum-typed fields point at the generated EnumDescriptors") { using spine::RecoParticle; using spine::TruthInteraction; - using spine::TruthParticle; const auto& rp = RecoParticle::descriptor(); - - const auto* id = rp.find("id"); - CHECK((id->flags & spine::kIndex) != 0); - CHECK(id->reference == "object"); - CHECK(id->reference_space == "same"); - CHECK(rp.find("interaction_id")->reference == "interaction"); - CHECK(rp.find("match_ids")->reference == "object"); - CHECK(rp.find("match_ids")->reference_space == "opposite"); - CHECK(rp.find("crt_ids")->reference == "crthit"); - CHECK(rp.find("crt_ids")->reference_space == "external"); - - CHECK(rp.find("calo_ke")->units == "MeV"); - CHECK(rp.find("crt_times")->units == "us"); - CHECK(rp.find("start_point")->units == "instance"); - CHECK((rp.find("start_point")->flags & spine::kPosition) != 0); - CHECK((rp.find("start_dir")->flags & spine::kVector) != 0); - CHECK(rp.find("momentum")->units == "MeV/c"); - CHECK(rp.find("mass")->units == "MeV/c^2"); - CHECK(rp.find("id")->units.empty()); - - // Derived fields (SPINE stored_property) and fields dropped from lite files. - for (const char* name : {"pdg_code", "mass", "ke", "momentum", "p", "num_fragments", "size", - "depositions_sum", "best_match_id", "module_ids"}) { - INFO(name); - CHECK(rp.find(name)->derived()); - } - for (const char* name : {"id", "units", "shape", "start_point", "match_ids", "index"}) { - INFO(name); - CHECK_FALSE(rp.find(name)->derived()); - } - CHECK((rp.find("index")->flags & spine::kLiteSkip) != 0); - CHECK((rp.find("orig_index")->flags & spine::kLiteSkip) != 0); - CHECK((rp.find("match_ids")->flags & spine::kLiteSkip) == 0); - CHECK((TruthParticle::descriptor().find("index_g4")->flags & spine::kLiteSkip) != 0); - CHECK((rp.find("pdg_code")->flags & spine::kPdg) != 0); - CHECK((rp.find("pdg_code")->flags & spine::kCategorical) != 0); - const auto& ti = TruthInteraction::descriptor(); - CHECK((ti.find("quark")->flags & spine::kPdgMinusOneValid) != 0); - CHECK((ti.find("target")->flags & spine::kPdgMinusOneValid) == 0); - CHECK(ti.find("energy_init")->units == "GeV"); - CHECK(TruthParticle::descriptor().find("energy_init")->units == "MeV"); - CHECK((spine::RecoInteraction::descriptor().find("topology")->flags & spine::kDerived) != 0); - - // Enum-typed fields point at the generated EnumDescriptors. CHECK(rp.find("shape")->enumeration == &spine::enum_descriptor()); CHECK(rp.find("pid")->enumeration == &spine::enum_descriptor()); CHECK(rp.find("chi2_pid")->enumeration == &spine::enum_descriptor()); @@ -328,178 +242,6 @@ TEST_CASE("model: descriptors carry SPINE's flags, units, references and enums") CHECK(rp.find("is_valid")->enumeration == nullptr); // bool, never an enum } -// --------------------------------------------------------------------------------------------- -// Defaults against SPINE (values printed from default-constructed SPINE objects) -// --------------------------------------------------------------------------------------------- - -TEST_CASE("defaults: RecoParticle") { - spine::RecoParticle p; - CHECK(p.id == -1); - CHECK(p.units == "cm"); - CHECK_FALSE(p.is_truth); - CHECK(p.is_valid); // True in SPINE, unlike the other bools - CHECK_FALSE(p.is_primary); - CHECK(std::isnan(p.cathode_offset)); - CHECK(std::isnan(p.length)); - CHECK(all_nan(p.start_point)); - CHECK(all_nan(p.chi2_per_pid)); - CHECK(p.pid == spine::ParticlePID::UNKNOWN); - CHECK(p.shape == spine::ParticleShape::UNKNOWN); - CHECK(p.chi2_pid == spine::ParticlePID::UNKNOWN); - CHECK(p.match_ids.empty()); - CHECK(p.match_overlaps.empty()); - CHECK(p.interaction_id == -1); - // derived: value of the property on a default object - CHECK(p.pdg_code == 0); - CHECK(std::isnan(p.mass)); - CHECK(std::isnan(p.p)); - CHECK(p.size == 0); - CHECK(p.depositions_sum == 0.0); - CHECK(p.best_match_id == -1); - CHECK(p.best_match_overlap == -1.0); - CHECK(p.num_fragments == 0); - CHECK(p.module_ids.empty()); - CHECK(std::isnan(p.vertex_distance)); -} - -TEST_CASE("defaults: TruthParticle") { - spine::TruthParticle p; - CHECK(p.id == -1); - CHECK(p.parent_id == -1); - CHECK(p.pdg_code == 0); // INVALID_PDG - CHECK(std::isnan(p.t)); - CHECK(all_nan(p.momentum)); - CHECK(all_nan(p.position)); - CHECK(p.creation_process.empty()); - CHECK(p.children_id.empty()); - CHECK(p.units == "cm"); - CHECK(std::isnan(p.mass)); - CHECK(p.shape == spine::ParticleShape::UNKNOWN); - CHECK(p.pid == spine::ParticlePID::UNKNOWN); - CHECK(std::isnan(p.energy_init)); - CHECK(p.num_voxels == -1); - CHECK(p.orig_id == -1); - CHECK(p.is_truth); - CHECK(p.orig_children_id.empty()); - CHECK(std::isnan(p.reco_length)); - CHECK(all_nan(p.reco_start_dir)); - CHECK(all_nan(p.start_dir)); - CHECK(std::isnan(p.ke)); - CHECK(p.size == 0); -} - -TEST_CASE("defaults: RecoInteraction") { - spine::RecoInteraction i; - CHECK(i.id == -1); - CHECK_FALSE(i.is_fiducial); - CHECK(std::isnan(i.flash_total_pe)); - CHECK(all_nan(i.vertex)); - CHECK(i.particle_counts == std::array{0, 0, 0, 0, 0, 0}); - CHECK(i.primary_particle_counts == std::array{0, 0, 0, 0, 0, 0}); - CHECK(i.topology.empty()); - CHECK(i.num_particles == 0); - CHECK(i.units == "cm"); - CHECK_FALSE(i.is_truth); - CHECK(all_nan(i.dir)); - CHECK_FALSE(i.is_crt_matched); - CHECK(i.flash_ids.empty()); - CHECK(i.size == 0); - CHECK(i.best_match_overlap == -1.0); -} - -TEST_CASE("defaults: TruthInteraction") { - spine::TruthInteraction i; - CHECK(i.id == -1); - CHECK(i.nu_id == -1); - CHECK(i.interaction_scheme == spine::NuInteractionScheme::UNKNOWN); - CHECK(i.current_type == spine::NuCurrentType::UNKNOWN); - CHECK(i.interaction_mode == -1); - CHECK(i.interaction_type == -1); - CHECK(std::isnan(i.energy_init)); - CHECK(i.pdg_code == 0); - CHECK(i.quark == 0); - CHECK(i.target == 0); - CHECK(all_nan(i.dir)); - CHECK(all_nan(i.position)); - CHECK(all_nan(i.momentum)); - CHECK(std::isnan(i.time)); - CHECK(i.creation_process.empty()); - CHECK(i.units == "cm"); - CHECK(i.is_truth); - CHECK(i.track_id == -1); - CHECK(all_nan(i.vertex)); - CHECK(all_nan(i.reco_vertex)); - CHECK(i.topology.empty()); - CHECK(i.particle_counts == std::array{0, 0, 0, 0, 0, 0}); - CHECK(std::isnan(i.t)); - CHECK(std::isnan(i.lepton_p)); -} - -TEST_CASE("defaults: RunInfo, Trigger, ImageMeta3D") { - spine::RunInfo r; - CHECK(r.run == -1); - CHECK(r.subrun == -1); - CHECK(r.event == -1); - - spine::Trigger t; - CHECK(t.id == -1); - CHECK(t.type == -1); - CHECK(t.time_s == -1); - CHECK(t.time_ns == -1); - CHECK(t.beam_time_s == -1); - CHECK(t.beam_time_ns == -1); - - spine::ImageMeta3D m; - CHECK(all_nan(m.lower)); - CHECK(all_nan(m.upper)); - CHECK(all_nan(m.size)); - CHECK(m.count == std::array{-1, -1, -1}); -} - -TEST_CASE("defaults: Flash, CRTHit, FlashHypothesis") { - spine::Flash f; - CHECK(f.units == "cm"); - CHECK(f.id == -1); - CHECK(f.volume_id == -1); - CHECK(f.frame == -1); - CHECK(f.on_beam_time == -1); - CHECK_FALSE(f.in_beam_frame); - CHECK(std::isnan(f.time)); - CHECK(std::isnan(f.time_width)); - CHECK(std::isnan(f.time_abs)); - CHECK(std::isnan(f.total_pe)); - CHECK(std::isnan(f.fast_to_total)); - CHECK(f.pe_per_ch.empty()); - CHECK(all_nan(f.center)); - CHECK(all_nan(f.width)); - - spine::CRTHit c; - CHECK(c.units == "cm"); - CHECK(c.id == -1); - CHECK(c.plane == -1); - CHECK(c.ts0_s == -1); - CHECK(std::isnan(c.ts0_ns)); - CHECK(std::isnan(c.ts0_s_corr)); - CHECK(std::isnan(c.ts0_ns_corr)); - CHECK(std::isnan(c.ts1_ns)); - CHECK(std::isnan(c.total_pe)); - CHECK(c.tagger.empty()); - CHECK(c.feb_id.empty()); - CHECK(all_nan(c.center)); - CHECK(all_nan(c.width)); - CHECK(std::isnan(c.time)); - - spine::FlashHypothesis h; - CHECK(h.id == -1); - CHECK(h.interaction_id == -1); - CHECK(h.volume_id == -1); - CHECK(std::isnan(h.score)); - CHECK_FALSE(h.is_truth); - CHECK(h.flash_ids.empty()); - CHECK(h.pe_per_ch.empty()); - CHECK(h.total_pe == 0.0); -} - // --------------------------------------------------------------------------------------------- // Assign pointers reach the right members // --------------------------------------------------------------------------------------------- @@ -510,15 +252,16 @@ TEST_CASE("assign: table rows write the member of their own name") { auto ids = fixed_column(ScalarType::Int64, 1, {41, 42}); d.fields[index_of(d, "id")].assign(&p, ids, 1); - CHECK(p.id == 42); - CHECK(p.interaction_id == -1); // the neighbour is untouched + CHECK(p.interaction_id == spine::RecoParticle{}.interaction_id); // the neighbour is untouched - auto shapes = fixed_column(ScalarType::Int64, 1, {1}); + const auto track = static_cast(spine::ParticleShape::TRACK); + auto shapes = fixed_column(ScalarType::Int64, 1, {track}); d.fields[index_of(d, "shape")].assign(&p, shapes, 0); CHECK(p.shape == spine::ParticleShape::TRACK); - CHECK(p.pid == spine::ParticlePID::UNKNOWN); + CHECK(p.pid == spine::RecoParticle{}.pid); - auto pids = fixed_column(ScalarType::Int64, 1, {2}); + const auto muon = static_cast(spine::ParticlePID::MUON); + auto pids = fixed_column(ScalarType::Int64, 1, {muon}); d.fields[index_of(d, "pid")].assign(&p, pids, 0); CHECK(p.pid == spine::ParticlePID::MUON); @@ -529,7 +272,7 @@ TEST_CASE("assign: table rows write the member of their own name") { auto start = fixed_column(ScalarType::Float64, 3, {1.5, 2.5, 3.5}); d.fields[index_of(d, "start_point")].assign(&p, start, 0); CHECK(p.start_point == std::array{1.5f, 2.5f, 3.5f}); - CHECK(all_nan(p.end_point)); + CHECK(nan_equal(p.end_point, spine::RecoParticle{}.end_point)); auto matches = fixed_column(ScalarType::Int32, 1, {7, 8, 9}); matches.variable = true; @@ -553,8 +296,8 @@ TEST_CASE("assign: table rows write the member of their own name") { auto run_numbers = fixed_column(ScalarType::Int64, 1, {9001}); spine::RunInfo::descriptor().find("subrun")->assign(&run, run_numbers, 0); CHECK(run.subrun == 9001); - CHECK(run.run == -1); - CHECK(run.event == -1); + CHECK(run.run == spine::RunInfo{}.run); + CHECK(run.event == spine::RunInfo{}.event); spine::CRTHit hit; auto feb = fixed_column(ScalarType::UInt8, 1, {0xAB, 0xCD}); @@ -572,11 +315,11 @@ TEST_CASE("assign: table rows write the member of their own name") { namespace { template -void check_enum(std::string_view spine_name, std::size_t members) { +void check_enum(std::string_view spine_name) { const spine::EnumDescriptor& d = spine::enum_descriptor(); INFO(spine_name); CHECK(d.name == spine_name); - CHECK(d.size == members); + CHECK(d.size > 0); std::set names; std::set values; for (std::size_t i = 0; i < d.size; ++i) { @@ -600,38 +343,21 @@ void check_enum(std::string_view spine_name, std::size_t members) { } // namespace -TEST_CASE("enums: every EnumDescriptor round-trips and matches SPINE's member counts") { +TEST_CASE("enums: every EnumDescriptor round-trips") { using namespace spine; - check_enum("ParticleShape", 8); - check_enum("ParticlePID", 7); - check_enum("NuCurrentType", 3); - check_enum("NuInteractionScheme", 6); - check_enum("LArSoftNuInteractionType", 63); - check_enum("GenieNuInteractionType", 23); - check_enum("GiBUUNuInteractionType", 20); - check_enum("NuWroNuInteractionType", 11); - check_enum("NeutNuInteractionType", 56); + check_enum("ParticleShape"); + check_enum("ParticlePID"); + check_enum("NuCurrentType"); + check_enum("NuInteractionScheme"); + check_enum("LArSoftNuInteractionType"); + check_enum("GenieNuInteractionType"); + check_enum("GiBUUNuInteractionType"); + check_enum("NuWroNuInteractionType"); + check_enum("NeutNuInteractionType"); } -TEST_CASE("enums: values and names are SPINE's") { +TEST_CASE("enums: reserved names are renamed, and Shape is ParticleShape") { using namespace spine; - CHECK(static_cast(ParticleShape::UNKNOWN) == -1); - CHECK(static_cast(ParticleShape::SHOWER) == 0); - CHECK(static_cast(ParticleShape::TRACK) == 1); - CHECK(static_cast(ParticleShape::LOWE) == 4); - CHECK(static_cast(ParticleShape::LARCV_UNKNOWN) == 6); - CHECK(to_string(ParticleShape::MICHEL) == "MICHEL"); - CHECK(static_cast(ParticlePID::PROTON) == 4); - CHECK(to_string(ParticlePID::KAON) == "KAON"); - CHECK(static_cast(NuCurrentType::NC) == 1); - CHECK(static_cast(NuInteractionScheme::NEUT) == 4); - CHECK(to_string(NuInteractionScheme::GIBUU) == "GIBUU"); - CHECK(static_cast(LArSoftNuInteractionType::MEC2P2H) == 1100); - CHECK(static_cast(GenieNuInteractionType::UNKNOWN) == -100); - CHECK(static_cast(GiBUUNuInteractionType::NC_DIS) == 650); - CHECK(static_cast(NuWroNuInteractionType::CCHYPERON) == 100); - CHECK(static_cast(NeutNuInteractionType::NC_DIS_NUBAR) == 675); - // NULL is a macro: the enumerator is renamed, the descriptor keeps SPINE's spelling. CHECK(static_cast(GenieNuInteractionType::NULL_) == 0); CHECK(to_string(GenieNuInteractionType::NULL_) == "NULL"); @@ -641,31 +367,26 @@ TEST_CASE("enums: values and names are SPINE's") { CHECK(Shape::TRACK == ParticleShape::TRACK); } -TEST_CASE("enums: interaction_mode and interaction_type tables depend on the scheme") { +TEST_CASE("enums: the interaction tables of every scheme are generated descriptors") { + // Which table a scheme selects is SPINE's choice and may change; that each scheme selects one + // of the generated tables or none, and that a value outside the enum selects none, does not. using namespace spine; - // interaction_mode: GIBUU, NUWRO and NEUT fall back to the GENIE table in SPINE. - CHECK(interaction_mode_enum(NuInteractionScheme::LARSOFT) == - &enum_descriptor()); - CHECK(interaction_mode_enum(NuInteractionScheme::GENIE) == - &enum_descriptor()); - CHECK(interaction_mode_enum(NuInteractionScheme::GIBUU) == - &enum_descriptor()); - CHECK(interaction_mode_enum(NuInteractionScheme::NUWRO) == - &enum_descriptor()); - CHECK(interaction_mode_enum(NuInteractionScheme::NEUT) == - &enum_descriptor()); - CHECK(interaction_mode_enum(NuInteractionScheme::UNKNOWN) == nullptr); - - CHECK(interaction_type_enum(NuInteractionScheme::LARSOFT) == - &enum_descriptor()); - CHECK(interaction_type_enum(NuInteractionScheme::GENIE) == - &enum_descriptor()); - CHECK(interaction_type_enum(NuInteractionScheme::GIBUU) == - &enum_descriptor()); - CHECK(interaction_type_enum(NuInteractionScheme::NUWRO) == - &enum_descriptor()); - CHECK(interaction_type_enum(NuInteractionScheme::NEUT) == - &enum_descriptor()); - CHECK(interaction_type_enum(NuInteractionScheme::UNKNOWN) == nullptr); - CHECK(interaction_type_enum(static_cast(77)) == nullptr); + const std::set tables = { + &enum_descriptor(), &enum_descriptor(), + &enum_descriptor(), &enum_descriptor(), + &enum_descriptor()}; + const EnumDescriptor& schemes = enum_descriptor(); + std::int64_t outside = 0; + for (std::size_t i = 0; i < schemes.size; ++i) { + const EnumMember& m = schemes.members[i]; + INFO(m.name); + const auto scheme = static_cast(m.value); + for (const EnumDescriptor* table : + {interaction_mode_enum(scheme), interaction_type_enum(scheme)}) { + CHECK((table == nullptr || tables.count(table) == 1)); + } + outside = std::max(outside, m.value + 1); + } + CHECK(interaction_mode_enum(static_cast(outside)) == nullptr); + CHECK(interaction_type_enum(static_cast(outside)) == nullptr); } diff --git a/tests/test_reader.cpp b/tests/test_reader.cpp index 3be1874..7c1f29d 100644 --- a/tests/test_reader.cpp +++ b/tests/test_reader.cpp @@ -23,6 +23,7 @@ #include #include #include +#include #include #include @@ -36,6 +37,7 @@ #include #include "core/source.hpp" +#include "member_compare.hpp" #ifndef SPINE_READER_TEST_DATA #error "SPINE_READER_TEST_DATA is set by tests/CMakeLists.txt" @@ -92,14 +94,7 @@ using Overlaps = std::vector; constexpr float kNaN = std::numeric_limits::quiet_NaN(); /// Same values, with NaN equal to NaN. -bool same_overlaps(const Overlaps& a, const Overlaps& b) { - if (a.size() != b.size()) return false; - for (std::size_t i = 0; i < a.size(); ++i) { - if (std::isnan(a[i]) != std::isnan(b[i])) return false; - if (!std::isnan(a[i]) && a[i] != b[i]) return false; - } - return true; -} +bool same_overlaps(const Overlaps& a, const Overlaps& b) { return spine_test::nan_equal(a, b); } } // namespace @@ -502,7 +497,14 @@ TEST_CASE("the old class name Meta is read as ImageMeta3D") { [](const ProductReport& p) { return p.product == "meta"; }); REQUIRE(meta != report.products.end()); CHECK(meta->class_name == "Meta"); // as the file spells it - CHECK(meta->complete()); + // every column binds; fields SPINE adds later are missing from this frozen file, not these + CHECK(meta->mismatched.empty()); + CHECK(meta->extra.empty()); + for (std::string_view field : {"lower", "upper", "size", "count"}) { + CHECK_MESSAGE(std::find(meta->missing.begin(), meta->missing.end(), field) == + meta->missing.end(), + field); + } CHECK(std::none_of(report.skipped.begin(), report.skipped.end(), [](const std::string& s) { return contains(s, "meta"); })); REQUIRE(reader.event(0).meta() != nullptr); @@ -561,7 +563,14 @@ TEST_CASE("non-object products and products of unknown classes are listed as not " (model from SPINE " + SPINE_READER_MODEL_SPINE_VERSION + ")\n"; const std::string summary = report.summary(); CHECK(contains(summary, three_files()[0] + "\n SPINE 1.4.0, format_version 1 (V1)" + read_by)); - CHECK(contains(summary, "\n reco_particles [RecoParticle]: all model fields read\n")); + // a model with fields this frozen file lacks says so instead + const auto reco = + std::find_if(report.products.begin(), report.products.end(), + [](const ProductReport& p) { return p.product == "reco_particles"; }); + REQUIRE(reco != report.products.end()); + CHECK(contains(summary, std::string("\n reco_particles [RecoParticle]: ") + + (reco->complete() ? "all model fields read\n" + : "some model fields missing"))); const std::string tail = " not read:\n index: array product\n"; REQUIRE(summary.size() > tail.size()); CHECK(summary.compare(summary.size() - tail.size(), tail.size(), tail) == 0); @@ -604,10 +613,11 @@ TEST_CASE("strict mode refuses a product that lacks model fields, and only then" } } - // strict only looks at the products it was asked to read + // strict only looks at the products it was asked to read: a lite file lacks fields in other + // products, never in run_info ReaderOptions only_runs = strict; only_runs.products = {"run_info"}; - CHECK_NOTHROW(Reader(fixture_file("v0.11.1_v1.h5"), only_runs)); + CHECK_NOTHROW(Reader(fixture_file("current_v1_lite.h5"), only_runs)); } TEST_CASE("incomplete files are refused unless ReaderOptions::allow_incomplete") { @@ -669,13 +679,15 @@ TEST_CASE("a product with every kind of difference binds as the report says") { CHECK(p.product == "reco_particles"); CHECK(p.class_name == "RecoParticle"); CHECK_FALSE(p.complete()); + const std::string model_shower = std::to_string(static_cast(ParticleShape::SHOWER)); + const std::string model_track = std::to_string(static_cast(ParticleShape::TRACK)); CHECK(p.mismatched == std::vector{"shape: enum numbering differs: file SHOWER=1 and TRACK=0, " - "model SHOWER=0 and TRACK=1", + "model SHOWER=" + model_shower + " and TRACK=" + model_track, "start_point: file float64[4] vs model float32[3]"}); CHECK(p.extra == std::vector{"brand_new"}); - // 55 fields; 5 bound, 2 mismatched - CHECK(p.missing.size() == 55 - 5 - 2); + // 5 bound, 2 mismatched + CHECK(p.missing.size() == RecoParticle::kNumFields - 5 - 2); CHECK(std::find(p.missing.begin(), p.missing.end(), "end_point") != p.missing.end()); CHECK(std::find(p.missing.begin(), p.missing.end(), "length") != p.missing.end()); for (const char* bound : @@ -715,9 +727,9 @@ TEST_CASE("a product with every kind of difference binds as the report says") { CHECK_FALSE(b.is_valid); CHECK(c.is_valid); // the crossed enum keeps its default - CHECK(a.shape == ParticleShape::UNKNOWN); - CHECK(b.shape == ParticleShape::UNKNOWN); - CHECK(c.shape == ParticleShape::UNKNOWN); + CHECK(a.shape == RecoParticle{}.shape); + CHECK(b.shape == RecoParticle{}.shape); + CHECK(c.shape == RecoParticle{}.shape); CHECK(a.units == "cm"); CHECK(b.units == "px"); CHECK(a.match_ids == std::vector{1, 2}); @@ -733,10 +745,11 @@ TEST_CASE("a product with every kind of difference binds as the report says") { CHECK_MESSAGE(!a.has(field), "field " << static_cast(field)); } // a mismatched or missing field keeps SPINE's default - CHECK(std::isnan(a.start_point[0])); - CHECK(std::isnan(a.length)); - CHECK(a.interaction_id == -1); - CHECK(a.pid == ParticlePID::UNKNOWN); + const RecoParticle defaults; + CHECK(spine_test::nan_equal(a.start_point, defaults.start_point)); + CHECK(spine_test::nan_equal(a.length, defaults.length)); + CHECK(a.interaction_id == defaults.interaction_id); + CHECK(a.pid == defaults.pid); // strict: this product is incomplete ReaderOptions strict; diff --git a/tools/EGM.md b/tools/EGM.md index 7e206ba..6b57631 100644 --- a/tools/EGM.md +++ b/tools/EGM.md @@ -3,15 +3,21 @@ ## Overview Python developer tools for spine-reader. None of them is built into the C++ -library. Both subsystems are tied to SPINE and to the single committed +library. They are tied to SPINE and to the single committed `schema/spine-*.json`. `gen` turns SPINE's object model into the generated C++ model. `fixtures` produces the golden HDF5 files and their decoded expectations, -which the C++ tests read. Each subsystem registers a ctest check: +which the C++ tests read. `release` holds the tooling for following SPINE +releases; today `scan_consumer_fields.py`, which lists the model fields a +CAFMaker build reads. `gen` and `fixtures` each register a ctest check: `spine_reader_generated_model` (`gen/generate.py --check`) and -`spine_reader_golden_members` (`fixtures/make_member_list.py --check`), registered -only when CMake finds a Python 3 interpreter. Run them -in the LCG_110 view (`source -/cvmfs/sft.cern.ch/lcg/views/LCG_110/x86_64-el9-gcc13-opt/setup.sh`). +`spine_reader_golden_members` (`fixtures/make_member_list.py --check`). +`tests/CMakeLists.txt` registers them when CMake finds a Python 3 interpreter; +with `-DSPINE_READER_REQUIRE_PYTHON=ON` (CI turns it on) a missing interpreter +fails the configuration instead of leaving them out. Run the tools in the +LCG_110 view (`source +/cvmfs/sft.cern.ch/lcg/views/LCG_110/x86_64-el9-gcc13-opt/setup.sh`), except +`scan_consumer_fields.py`, which needs only Python 3.9 and runs in the +CAFMaker's environment. ## Subdirectories & Boundaries @@ -30,3 +36,7 @@ in the LCG_110 view (`source resolves tags and clones commits. `make_member_list.py` writes or checks `tests/golden_members.inc` from the schema. Legacy notes: [./fixtures/README.md](./fixtures/README.md). +- release: [./release/EGM.md](./release/EGM.md) - `scan_consumer_fields.py` + (compiles a CAFMaker's sources with `-fsyntax-only` against model headers whose + members are marked `[[deprecated]]`, and lists the fields read; with + `--contracts`, the ones that have no row in `tests/test_contracts.cpp`). diff --git a/tools/fixtures/EGM.md b/tools/fixtures/EGM.md index a935967..1e57914 100644 --- a/tools/fixtures/EGM.md +++ b/tools/fixtures/EGM.md @@ -11,7 +11,8 @@ They are then decoded by an independent h5py-only decoder into one tag, by default the model's SPINE tag; and the frozen cases, written by old releases and never rewritten by a new tag. `manifest.json` records each case's tag and commit. The directory also generates `tests/golden_members.inc`, the per-class -member list from `schema/`. The hand-written [README.md](./README.md) is the +member list from `schema/` that `tests/test_golden.cpp`, `tests/test_model.cpp` and +`tests/test_contracts.cpp` walk. The hand-written [README.md](./README.md) is the detailed reference for the cases, the manifest, the expected JSON format and the findings about the real writers. This file is the contract summary; it does not replace that README. diff --git a/tools/fixtures/make_member_list.py b/tools/fixtures/make_member_list.py index 06c1144..1554399 100644 --- a/tools/fixtures/make_member_list.py +++ b/tools/fixtures/make_member_list.py @@ -6,8 +6,10 @@ tests/test_golden.cpp expands GOLDEN_MEMBERS_(X) to compare every member of every object the Reader returns with the value h5py decoded from the fixture, so that a field whose table -row assigns the wrong member, or whose type or default is wrong, cannot go unnoticed. The names -come from the committed schema, which was dumped from SPINE: the list is not the model's own. +row assigns the wrong member, or whose type or default is wrong, cannot go unnoticed. +tests/test_model.cpp walks it to check that field i has the name of enumerator i, and +tests/test_contracts.cpp to find the members the contract table lists. The names come from the +committed schema, which was dumped from SPINE: the list is not the model's own. """ import argparse import json @@ -26,7 +28,8 @@ def render(): lines = [ f"// GENERATED from schema/{schema_files[0].name} by tools/fixtures/make_member_list.py. " "Do not edit.", - "// The members of each model class, in SPINE's order, for tests/test_golden.cpp.", + "// The members of each model class, in SPINE's order, for tests/test_golden.cpp,", + "// tests/test_model.cpp and tests/test_contracts.cpp.", ] for cls, info in schema["classes"].items(): lines.append("") diff --git a/tools/gen/README.md b/tools/gen/README.md index 290e689..4d9c844 100644 --- a/tools/gen/README.md +++ b/tools/gen/README.md @@ -44,15 +44,18 @@ deterministic, so a diff after regeneration is a real change. (HDF5, ROOT) to the scan. 4. **Build and test.** `cmake -S . -B build && cmake --build build -j8 && ctest --test-dir build`. The `static_assert`s in `src/model/*.cpp` fail the build if a member's C++ type disagrees with - its descriptor row. `tests/test_model.cpp` then needs the new field counts, the `LAST_FIELD` - list and the enum member counts; its default-value checks should be regenerated from SPINE by - printing `getattr(Class(), name)`. + its descriptor row. No test holds field counts, defaults or enum member counts: they follow + the schema. Write the new tag's fixtures first (`tools/fixtures/make_fixtures.py --tag `), + since the golden test checks the model's fields against their columns. If + `spine_reader_contracts` fails, SPINE changed a unit, a default or an enum value that a + CAFMaker relies on: talk to the CAFMaker maintainers before editing its row in + `tests/test_contracts.cpp`. 5. **gcc 12, C++17** in the SL7 container (`-fsyntax-only` of every `src/model/*.cpp` and header with `-Wall -Wextra -Wpedantic -Werror` is enough). 6. **Docs and units.** `doc_source` in the JSON says which class docstring a field's description came from; SPINE copies some docs between classes (for example `TruthInteraction.id` says - "Index of the neutrino"). Missing docs are empty strings, and the test requires every field to - have one. + "Index of the neutrino"). Missing docs are empty strings; the generated member then has no + description, only its tags (for example `/// [units: MeV]`). ## What is in the JSON diff --git a/tools/release/EGM.md b/tools/release/EGM.md new file mode 100644 index 0000000..5ccd29d --- /dev/null +++ b/tools/release/EGM.md @@ -0,0 +1,102 @@ +# tools/release + +## Overview + +Tooling for following SPINE releases. Today it holds `scan_consumer_fields.py`, which keeps the +contract table of `tests/test_contracts.cpp` current: it lists the model fields one CAFMaker +build reads, and, with `--contracts`, the ones that have no row in the table. A row is added +when a CAFMaker starts reading a field. The tool runs the CAFMaker's own compile commands, so it +is run by hand, in that CAFMaker's environment; no ctest entry runs it. + +## Interface + +### `scan_consumer_fields.py` (CLI; Python 3.9+, standard library only) + +``` +scan_consumer_fields.py --source SRC (--build DIR | --compile-commands FILE) + [--setup BASH] [--wrap COMMAND] [--contracts FILE] [--name LABEL] + [--root DIR] [--schema FILE] [--workdir DIR] [--keep] [--json FILE] +``` + +- `--source`: the CAFMaker's source root. Only diagnostics that point into it count. +- `--build`: the build folder of a Makefile build; its compile commands are read from + `make -n -B`, which runs nothing. `--compile-commands`: a `compile_commands.json` instead. + Files under the build folder (or the folder of `compile_commands.json`) never count. +- `--setup`: bash lines run, in the same shell, before `make -n` and before the compiles (for + example `source ./ndcaf_setup_deps.sh prof`). Their output goes to `setup.log`. +- `--wrap`: a command prefix that runs `bash