Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions EGM.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-<version>.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-<version>.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`):
Expand All @@ -53,7 +53,7 @@ Build and packaging (`CMakeLists.txt`):
- [./include/spine/EGM.md](./include/spine/EGM.md) - `Reader`, `ReaderOptions`, `Event`,
`Match<T>`, `SchemaReport`/`ProductReport`, descriptors, `Object<N>`, `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
Expand All @@ -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
Expand Down Expand Up @@ -113,20 +116,23 @@ 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.

## System Verification

- 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)
Expand Down
11 changes: 9 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
35 changes: 20 additions & 15 deletions include/spine/model/EGM.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-<version>.json`. Each file starts with the banner `// GENERATED from SPINE
<version> 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
Expand All @@ -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<N>` 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<N>` 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.
Expand Down
12 changes: 7 additions & 5 deletions src/model/EGM.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-<version>.json`; currently SPINE 1.4.0). Do not edit them by hand.** To
(the one `schema/spine-<version>.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.

Expand All @@ -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 `{"<Class>", kFields, std::size(kFields), "1.4.0"}`. The last
entry is the schema version, which the Reader reports as `model_version`.
- Each `ClassDescriptor` is `{"<Class>", kFields, std::size(kFields), "<version>"}`. 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,
Expand Down Expand Up @@ -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.

Expand All @@ -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`).
9 changes: 7 additions & 2 deletions tests/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion tests/check_spine_dump.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
3 changes: 2 additions & 1 deletion tests/golden_members.inc
Original file line number Diff line number Diff line change
@@ -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) \
Expand Down
109 changes: 109 additions & 0 deletions tests/member_compare.hpp
Original file line number Diff line number Diff line change
@@ -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 <json.hpp>

#include <algorithm>
#include <array>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <string>
#include <type_traits>
#include <vector>

namespace spine_test {

template <class T>
struct is_std_array : std::false_type {};
template <class T, std::size_t N>
struct is_std_array<std::array<T, N>> : std::true_type {};
template <class T>
struct is_std_vector : std::false_type {};
template <class T, class A>
struct is_std_vector<std::vector<T, A>> : 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 <class M>
bool equal_member(const M& value, const nlohmann::json& want) {
if constexpr (std::is_same_v<M, std::string>) {
return want.is_string() && want.get<std::string>() == value;
} else if constexpr (std::is_same_v<M, bool>) {
if (want.is_boolean()) return want.get<bool>() == value;
return want.is_number() && (want.get<double>() != 0) == value;
} else if constexpr (std::is_enum_v<M>) {
return want.is_number_integer() && want.get<std::int64_t>() == static_cast<std::int64_t>(value);
} else if constexpr (std::is_floating_point_v<M>) {
if (want.is_string()) {
const std::string text = want.get<std::string>();
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<M>(want.get<double>()) == value;
} else if constexpr (std::is_arithmetic_v<M>) {
return want.is_number_integer() && static_cast<M>(want.get<std::int64_t>()) == value;
} else {
static_assert(is_std_array<M>::value || is_std_vector<M>::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 <class M>
bool nan_equal(const M& a, const M& b) {
if constexpr (std::is_floating_point_v<M>) {
return (std::isnan(a) && std::isnan(b)) || a == b;
} else if constexpr (is_std_array<M>::value || is_std_vector<M>::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 <class M>
nlohmann::json member_json(const M& value) {
if constexpr (std::is_same_v<M, std::string> || std::is_same_v<M, bool>) {
return value;
} else if constexpr (std::is_enum_v<M>) {
return static_cast<std::int64_t>(value);
} else if constexpr (std::is_floating_point_v<M>) {
if (std::isnan(value)) return "nan";
if (std::isinf(value)) return value > 0 ? "inf" : "-inf";
return static_cast<double>(value);
} else if constexpr (std::is_arithmetic_v<M>) {
return static_cast<std::int64_t>(value);
} else {
nlohmann::json values = nlohmann::json::array();
for (const auto& v : value) values.push_back(member_json(v));
return values;
}
}

template <class A>
bool all_nan(const A& values) {
return std::all_of(values.begin(), values.end(), [](auto v) { return std::isnan(v); });
}

} // namespace spine_test
Loading