425 multiple contrasts

[rozyczko]

This pull request introduces significant improvements to how contrasts, experiments, and fitting are managed in the easyreflectometry package. The main changes include the addition of a flexible contrasts system, enhanced project persistence with proper object sharing, and a comprehensive record of fitting runs. There are also important behavioral changes to experiment/model management and fitting statistics, as well as new API methods for advanced workflows.

Multiple Contrasts and Model Management:

• Added a new easyreflectometry.contrasts system, allowing models to share structure by identity or equality, and providing APIs to build, substitute, and manage contrasts (Project.add_contrast, ReplaceMaterial, ReplaceFormula, substitution_candidates, Project.contrast_reference, etc.). User constraints for multiple contrasts are now saved with the project.
• Introduced new methods for managing experiments and models, including Project.remove_experiment, set_model_for_experiment, model_index_for_experiment, experiments_for_model, and improved behavior for removing models and handling constraints.

Project Persistence Improvements:

• Changed how objects are saved and loaded: shared materials and assemblies are now serialized once and re-linked on load, preventing duplication and ensuring edits propagate. Materials are saved in order, and experiment/model associations are more robust.

Fitting Enhancements:

• Added include_in_fit to DataSet1D and PolarizedDataSet to control which experiments are included in a fit by default.
• Introduced a FitRun dataclass that records the outcome and statistics of each fit, independent of the current model state, including pooled and per-dataset chi-square values and experiment mapping.
• Changed per-dataset fit statistics: reduced chi-square values are now only reported for the pooled fit, not per dataset, reflecting the correct degrees of freedom calculation.
• Added logic to ensure free parameters tied to models outside the fit are still varied (_free_roots), preventing them from being held fixed unintentionally.

API and Internal Structure:

• Added new error classes (FitScopeError) for better error reporting when experiments cannot be fitted together.
• Refactored and extended the fitting pipeline to keep track of additional metadata (added_roots, labels, skipped) in PreparedFit, and improved how fitters are constructed and configured.

[codecov]

Codecov Report

❌ Patch coverage is 96.61017% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.39%. Comparing base (2febb08) to head (c9b701b).

Files with missing lines	Patch %	Lines
src/easyreflectometry/project.py	95.44%	18 Missing ⚠️
...eflectometry/sample/assemblies/surfactant_layer.py	14.28%	6 Missing ⚠️
src/easyreflectometry/sample/paths.py	90.69%	4 Missing ⚠️
src/easyreflectometry/sample/references.py	97.72%	3 Missing ⚠️
src/easyreflectometry/fitting.py	98.57%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #432      +/-   ##
===========================================
+ Coverage    95.13%   95.39%   +0.26%     
===========================================
  Files           56       59       +3     
  Lines         6249     7021     +772     
===========================================
+ Hits          5945     6698     +753     
- Misses         304      323      +19     

Flag	Coverage Δ
integration	37.34% <25.21%> (-0.95%)	⬇️
unittests	95.39% <96.61%> (+0.26%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/easyreflectometry/contrasts.py	100.00% <100.00%> (ø)
src/easyreflectometry/data/data_store.py	100.00% <100.00%> (ø)
src/easyreflectometry/data/polarized.py	95.31% <100.00%> (+0.03%)	⬆️
src/easyreflectometry/model/model.py	98.10% <ø> (ø)
src/easyreflectometry/sample/assemblies/bilayer.py	100.00% <100.00%> (ø)
src/easyreflectometry/sample/base_core.py	98.11% <100.00%> (+0.19%)	⬆️
...eflectometry/sample/collections/base_collection.py	90.22% <100.00%> (+0.11%)	⬆️
...flectometry/sample/collections/layer_collection.py	100.00% <ø> (ø)
...ctometry/sample/collections/material_collection.py	100.00% <ø> (ø)
src/easyreflectometry/sample/collections/sample.py	96.49% <ø> (ø)
... and 8 more

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

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