Reorganization and Generation

[denehoffman]

This PR is all about reorganizing the underlying crate structure to make it a bit easier to find things. Files were getting very large and hard to read through, and I figured it made sense to break up some of these bigger files into submodules. Eventually I might break things up in to small crates to improve compile times even more, but for now this is probably fine.

The other major addition is the laddu-generation crate. My goal here was to allow an experiment-agnostic Monte Carlo generator to generate laddu Datasets with some extra metadata that can be used by experiment-specific translators to convert data to whatever pipeline an experiment uses.

A more detailed summary is as follows:

Dataset and Event APIs

• Reworked public event access around borrowed Event views rather than cloning or exposing awkward internal storage details.
• Replaced implicit dataset iteration with explicit events_local and events_global style accessors so MPI/local semantics are visible at the call site.
• Added explicit local/global dataset mutation APIs:
  • push_event_local
  • push_event_global
  • add_p4_column_local
  • add_p4_column_global
  • add_aux_column_local
  • add_aux_column_global
• Implemented round-robin collective global event appends under MPI and clarified that local appends stay rank-local.
• Changed filtered, bootstrapped, and binned datasets to share the underlying columnar storage through row selections instead of duplicating event data. Note that right now, we forbid pushing event data to such derived datasets, and pushing event data to their parent dataset will cause them to be out of sync. I might change these semantics in a future update.
• Added Python tests for event construction, column ingestion, dataset mutation, and display behavior.

Reaction and Generation APIs

• Added laddu-generation as a first-class workspace crate and re-exported generation APIs through the top-level Rust and Python packages.
• Introduced generated reaction, particle, vertex, storage, and batch metadata structures for Monte Carlo workflows.
• Added support for storing generated datasets with configurable generated-particle storage, including layouts that can omit intermediate or downstream products depending on the intended external simulation/reconstruction flow.
• Updated reaction APIs toward identifier-based particle queries and clearer Particle/Reaction construction semantics.

Parameters and Likelihoods

• Consolidated parameter access around ParameterMap rather than separate free/fixed parameter APIs.
• Exposed Python ParameterMap with indexing, containment, free/fixed filtered views, and improved string/repr behavior.
• Updated expressions, evaluators, likelihood expressions, NLLs, and related Python bindings so parameter fixing/freeing/renaming mutates in place and uses the new method names.
• Removed the old LikelihoodEvaluator split by merging evaluator-like behavior into likelihood expressions.

Amplitudes, Tags, and Expression Compilation

• Replaced single amplitude names with normalized tag lists.
• Empty string tags are ignored; amplitudes with no tags are valid untagged amplitudes and are always active because no selector can match them.
• Activation/deactivation/isolation now operates on tags and glob selectors.
• Semantic keys now ignore activation tags so equivalent computations can share cached amplitude values while distinct use-sites remain independently activatable.
• Added compiled-expression visualization for expressions, evaluators, and NLL-like wrappers.
• Added expression simplification passes for arithmetic identities and constant unary functions, including compiled-expression tests.
• Constants now interoperate with expressions, so we no longer need to do silly things like declare fixed scalar amplitudes.

Concrete Amplitudes and Physics Helpers

• Moved angular-momentum, frame, parity, channel, and related analysis helper types into laddu-core so they are available without depending on laddu-amplitudes.
• Added and refined plug-and-play factors for Wigner-D matrices, Clebsch-Gordan coefficients, Wigner 3j constants, Blatt-Weisskopf factors, photon SDMEs, and related angular components.
• Updated Kopf K-matrix constructors to use explicit channel enums in Rust and Python instead of raw channel numbers.

Python API Organization

• Reorganized Python modules to mirror the Rust API where practical:
  • laddu.amplitude for core expression/evaluator/parameter APIs.
  • laddu.amplitudes.* for concrete amplitude constructors.
  • laddu.data, laddu.generation, laddu.reaction, laddu.variables, laddu.vectors, laddu.math, and laddu.quantum for their Rust counterparts.
• Kept intentional Python flattening for laddu.likelihood, laddu.optimize, and laddu.experimental, which map to laddu-extensions in Rust.
• Updated .pyi files, top-level exports, and smoke tests for module import parity.
• Added or refreshed display/repr behavior for common user-facing objects.

Documentation and Tests

• Refreshed Rust docs and doctest examples for the new tag, dataset, parameter, and generation APIs.
• Preserved NumPy-style formatting for PyO3 docstrings.
• Added or updated tests for MPI dataset semantics, Python column ingestion, parameter maps, activation tags, compiled-expression rendering, expression simplification, and generation metadata.

Breaking Changes

• laddu_core::amplitudes is now laddu_core::amplitude.
• Single amplitude names were replaced with tag lists.
• Dataset event access and mutation now use explicit local/global APIs.
• Public dataset iteration no longer relies on implicit iterators.
• Parameter access now returns ParameterMap; separate free/fixed shortcut APIs were removed or reduced.
• Likelihood evaluator behavior was merged into likelihood expressions.
• Reaction APIs moved toward identifier/string-based particle queries and away from carrying handles around user code.
• Python amplitude constructors use positional string tags plus keyword-only configuration where practical.

[codecov]

Codecov Report

❌ Patch coverage is 77.95227% with 1081 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.29%. Comparing base (dd1f981) to head (2b9ee48).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/laddu-core/src/data/dataset.rs	79.38%	260 Missing and 37 partials ⚠️
crates/laddu-core/src/parameters/map.rs	62.19%	101 Missing and 9 partials ⚠️
crates/laddu-core/src/data/event.rs	76.38%	80 Missing and 18 partials ⚠️
...tes/laddu-amplitudes/src/resonance/breit_wigner.rs	55.37%	75 Missing and 8 partials ⚠️
crates/laddu-core/src/reaction/topology.rs	71.01%	34 Missing and 26 partials ⚠️
crates/laddu-amplitudes/src/angular/harmonics.rs	74.23%	51 Missing and 8 partials ⚠️
crates/laddu-amplitudes/src/angular/sdme.rs	52.11%	34 Missing ⚠️
crates/laddu-amplitudes/src/resonance/voigt.rs	60.25%	27 Missing and 4 partials ⚠️
...ates/laddu-amplitudes/src/resonance/phase_space.rs	63.49%	18 Missing and 5 partials ⚠️
crates/laddu-core/src/amplitude/ids.rs	0.00%	22 Missing ⚠️
... and 24 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #110      +/-   ##
==========================================
+ Coverage   78.00%   78.29%   +0.28%     
==========================================
  Files          66      104      +38     
  Lines       27020    26149     -871     
  Branches    26360    25469     -891     
==========================================
- Hits        21077    20473     -604     
+ Misses       5454     5131     -323     
- Partials      489      545      +56     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[codspeed-hq]

Merging this PR will not alter performance

✅ 10 untouched benchmarks
⏩ 104 skipped benchmarks¹

---

_{Comparing reorganization (2b9ee48) with main (f35aed6)}

Footnotes

1. 104 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩