easyreflectometry 1.8.0__tar.gz → 2.0.0__tar.gz

{easyreflectometry-1.8.0 → easyreflectometry-2.0.0}/.github/copilot-instructions.md

@@ -174,7 +174,6 @@ tox
 ```
 src/easyreflectometry/     # Main package source code
 ├── calculators/           # Calculator implementations (refnx, refl1d)
-│   └── bornagain/         # BornAgain calculator (not yet functional)
 ├── model/                 # Reflectometry models
 ├── sample/                # Sample structures and materials
 ├── special/               # Special calculations and parsing

{easyreflectometry-1.8.0 → easyreflectometry-2.0.0}/.github/workflows/pypi-test.yml

@@ -47,6 +47,14 @@ jobs:
       - name: Init pixi project
         run: pixi init easyreflectometry
 
+      # A fresh pixi project assumes macOS 13.0 on osx-arm64, which rejects
+      # scipp's macosx_14_0 wheels and forces a failing source build. Match
+      # the macOS minimum set in the repository's pixi.toml.
+      - name: Require macOS 14 (matches scipp wheels)
+        working-directory: easyreflectometry
+        shell: bash
+        run: printf '\n[system-requirements]\nmacos = "14.0"\n' >> pixi.toml
+
       - name: Add Python 3.13 from Conda
         working-directory: easyreflectometry
         run: pixi add "python=3.13"

easyreflectometry-2.0.0/.planning/codebase/ARCHITECTURE.md

@@ -0,0 +1,311 @@
+# Architecture
+
+**Analysis Date:** 2026-10-15 **Branch analysed:** `develop` @
+`66adaf54` **Revised:** 2026-11-08 for the easyscience 3 port
+(`core-3.0`)
+
+## Pattern Overview
+
+**Overall:** Layered library with two facades. `Project` is the
+stateful, GUI-oriented facade (experiments, models, persistence,
+constraints, contrasts); `MultiFitter` is the fitting facade that turns
+datasets into a `PreparedFit` and delegates execution to EasyScience's
+`MultiFitter` / `Sampler`, which drive LMFit, BUMPS or DFO. Reflectivity
+is computed by pluggable engine wrappers (refnx, refl1d) behind
+`CalculatorFactory`.
+
+**Key Characteristics:**
+
+- Prepare / execute / record split: `Project.prepare_fit` →
+  `PreparedFit` (immutable snapshot of settings, arrays, bound fit
+  functions, configured core fitter) → `execute()` or a GUI worker →
+  `Project.record_fit` → `FitRun`
+- Resolution follows the dataset, not the calculator: each
+  `DataSet1D.resolution_function` is bound into its fit function;
+  `CalculatorBase` keeps one resolution per model id
+- Parameters are EasyScience `Parameter`s; all coupling (conformal
+  thickness, contrasts, user constraints, sum constraints) is expressed
+  as parameter dependencies and persisted by structural path
+- Inequality constraints are enforced by patching the BUMPS driver in
+  the core's namespace, because the core offers no hook
+- Shared objects (one material in two layers, one assembly in two
+  models) serialize once through `sample/references.py`
+  (`file_format` 4)
+
+## Layers
+
+**Project Facade:**
+
+- Purpose: Hold the session state an application needs and expose
+  index-based accessors for plots and tables
+- Location: `src/easyreflectometry/project.py` (`Project`,
+  `ModelRemoval`, spin-asymmetry helpers)
+- Contains: experiments `Dict[int, DataSet1D | PolarizedDataSet]`,
+  `ModelCollection`, `MaterialCollection` palette, `FitSettings`,
+  inequality specs, link records, `last_fit`, load/save, ORSO import,
+  contrasts, polarized loading, `spin_asymmetry_for_experiment_at_index`
+- Depends on: every other package in the library
+- Used by: EasyReflectometry GUI (ERA app), tutorials, `Summary`
+
+**Fitting Layer:**
+
+- Purpose: Zero-variance handling, per-dataset resolution binding,
+  settings snapshot, constraint enforcement, goodness-of-fit metrics
+- Location: `src/easyreflectometry/fitting.py`, `fit_settings.py`,
+  `_bumps_constraints.py`, `inequality_constraints.py`
+- Contains: `MultiFitter` (`fit`, `fit_single_data_set_1d`,
+  `fit_polarized`, `for_experiments`, `prepare`, `mcmc_sample`,
+  `switch_minimizer`, chi-square properties), `PreparedFit`, `FitRun`,
+  `_ConstrainedEasyScienceMultiFitter`, `FitSettings`,
+  `MinimizerOption`, `InequalitySpec`, `build_constraints_factory`
+- Depends on: `easyscience.fitting` (`MultiFitter`, `Sampler`,
+  `FitResults`), `easyscience.Minimizers`, `asteval`, `scipp`
+
+**Bayesian Analysis Layer:**
+
+- Purpose: Post-hoc posterior analysis and chain persistence
+- Location: `src/easyreflectometry/analysis/bayesian.py`
+- Contains: `PosteriorResults` (summary, corner, trace, distribution,
+  credible*interval, gelman_rubin, save), `posterior_predictive*\*`,
+  `save_posterior`/`load_posterior` with fingerprinted sidecar
+- Depends on: plotly (required), arviz (optional), numpy
+
+**Model / Sample Layer:**
+
+- Purpose: Physical description of the sample and measurement
+- Location: `src/easyreflectometry/model/`,
+  `src/easyreflectometry/sample/`
+- Contains: `Model` (scale, background, resolution, `total_thickness`
+  derived parameter), `Sample` and assemblies/layers/materials,
+  `LayerMagnetism`, `MaterialDensity.sld_coupled`, `volume_fraction`,
+  `paths`, `references`
+- Depends on: `easyscience.base_classes`, `easyscience.variable`,
+  periodictable (via `special/`)
+
+**Constraints and Contrasts Layer:**
+
+- Purpose: User-level coupling between parameters and between models
+- Location: `src/easyreflectometry/constraints.py`, `contrasts.py`
+- Contains: `constrain*`, `derived_parameter`, `clamp_sum_partners`;
+  `derive_contrast`, `ReplaceMaterial`, `ReplaceFormula`, `plan_link` /
+  `LinkPlan` / `LinkRecord`, `tie_corresponding`, `snapshot` / `restore`
+- Depends on: EasyScience dependency mechanism; `USER_CONSTRAINT_FLAG`
+  marks constraints the project should persist
+
+**Data Layer:**
+
+- Purpose: Load, merge and describe measured data
+- Location: `src/easyreflectometry/data/`, `orso_utils.py`
+- Contains: `DataSet1D`, `PolarizedDataSet`, `load`, `load_as_dataset`,
+  `merge_datasets`, `resolution_from_dataset`, channel detection, ORSO
+  read/write and model-language conversion
+
+**Calculator Layer:**
+
+- Purpose: Pluggable reflectivity engines
+- Location: `src/easyreflectometry/calculators/`
+- Contains: `CalculatorBase` (thin layer over the wrapper: model
+  membership, resolution, magnetism flag and channel),
+  `StatelessWrapperBase` (one entry per served model, held weakly, with
+  its resolution and cache; magnetism reconciliation; abstract engine
+  API incl. `calculate_channel`, `calculate_polarized`,
+  `magnetic_sld_profile`), `CalculatorFactory` (`fit_func`,
+  `fit_func_for(channel, resolution_function)`), `PolarizationChannel`
+- Stateless: each evaluation builds the engine structure from the model
+  and drops it again; no value is copied into a backend, so model edits
+  need no mirroring
+- Implementations: `refnx/` (unpolarized), `refl1d/` (magnetism,
+  polarized probes with a per-model cache, oversampled resolution)
+
+**EasyScience Core (external, `>=3.0.2,<4`):**
+
+- `Fitter` / `MultiFitter` (reshaping of multi-dataset arrays, minimizer
+  dispatch), `Sampler` / `SamplingResults` (DREAM chain, `extend`,
+  `save`, `load_state`), minimizer wrappers, `Minimizers`
+
+## Data Flow
+
+**Classical Fit (project path):**
+
+1. GUI/user calls
+   `Project.prepare_fit(experiments=None, objective=None, skip_invalid=False)`
+2. `_fit_scope` selects experiments with `include_in_fit` and a model;
+   `_fitter_for` builds `MultiFitter.for_experiments(...)` with a deep
+   copy of `fit_settings` and a weak `constraints_factory_provider`
+3. `MultiFitter.prepare` applies the objective (`hybrid` default:
+   Mighell for zero-variance points, WLS otherwise), binds each
+   dataset's fit function to its own resolution
+   (`_resolution_for_fitted_points` for `legacy_mask`), collects
+   `added_roots` (free parameters of left-out models that fitted
+   parameters follow), builds the core fitter via `_core_fitter_for` +
+   `FitSettings.configure`, checks preconditions (finite bounds for
+   engines that need them, warns on starts at bounds)
+4. Caller runs `prepared.execute(**kwargs)` or `core_fitter.fit(...)` in
+   a thread; the `_ConstrainedEasyScienceMultiFitter.fit` property wraps
+   the call in `_bumps_constraints.applied(factory)`
+5. `Project.record_fit(prepared, results, status)` computes classical
+   metrics from the measured arrays (`prepared.finalize`), stores a
+   `FitRun` on `last_fit` and pushes results to `project.fitter`
+
+**Classical Fit (library path):**
+
+1. `MultiFitter(model, ...)` and `fitter.fit(data: sc.DataGroup)`
+2. `_datagroup_inputs` pairs curve `Qz_<n>` with model/dataset `n` in
+   numeric order
+3. `prepare` → `execute` → results written back into the `DataGroup`
+   (model curves, SLD profiles, pooled chi-square)
+
+**Polarized Fit:**
+
+- `fit_polarized(polarized_dataset)` or `for_experiments([...])`: one
+  fit function per spin channel, all against one model, each bound to
+  its channel via `CalculatorFactory.fit_func_for(channel, resolution)`.
+  Structural parameters shared, magnetic parameters constrained by all
+  channels.
+
+**Bayesian MCMC:**
+
+1. `Project.prepare_sample()` → `for_experiments` fitter with settings
+   snapshot; or `fitter.mcmc_sample(data)` directly
+2. `mcmc_sample` requires a BUMPS minimizer
+   (`minimizer.package == 'bumps'`), refuses all-zero variances unless
+   `objective='mighell'`, calls `prepare(action='sampling')`
+3. Builds `Sampler(core_fitter, x, y, weights)` inside the constraints
+   context, patches `sampler.extend` to re-enter it, keeps the sampler
+   on `fitter.sampler`, runs
+   `sampler.sample(samples, burn, thin, population, sampler_kwargs, progress_callback, abort_test)`
+4. Returns `{'draws', 'param_names', 'state', 'logp'}`; user wraps in
+   `PosteriorResults` or calls `save_posterior`
+
+**Persistence:**
+
+- `Project.as_dict` writes models, materials in order, experiments by
+  model index with per-dataset resolution, fit settings, inequality
+  specs, user-constraint records by path, contrast provenance, links.
+  `references.writing()` replaces repeated objects with `@ref`. Always
+  `file_format` 4.
+- `from_dict` refuses anything but format 4 first (files from 1.x carry
+  2, 3 or none), then rebuilds shared objects (`references.reading`),
+  restores constraints by path, reports problems in `load_report`.
+
+**State Management:**
+
+- `Project._sync_parameter_states` disables physically meaningless
+  parameters (superphase thickness/roughness, subphase thickness) and
+  applies default limits to enabled parameters created from project
+  defaults
+- `PreparedFit` owns copies of the measured arrays; model parameters and
+  constraints stay live because they are what the fit changes
+- Parameter values saved/restored around posterior predictive evaluation
+  (`_save_parameter_state` / `_restore_parameter_state`)
+
+## Key Abstractions
+
+**`PreparedFit` (fitting.py):** Snapshot pattern. Everything a run
+needs, fixed at prepare time; owns copies of measured arrays, the
+configured core fitter and both full-resolution (`curve_funcs`) and
+fitted-point (`fit_funcs`) evaluators.
+
+**`FitRun` (fitting.py):** Frozen record of a run (status, minimizer,
+objective, inputs by experiment key, pooled and per-dataset statistics).
+Outlives model changes; `remapped()` follows experiment re-keying.
+
+**`FitSettings` (fit_settings.py):** Serializable configuration
+(minimizer, mode, objective, tolerance, budget, per-minimizer options
+validated by `MinimizerOption` schemas). `configure(fitter)` and
+`engine_kwargs()` are the two consumers.
+
+**`_ConstrainedEasyScienceMultiFitter` / `_bumps_constraints`:**
+Property override plus monkeypatch. The subclass overrides the core's
+read-only `fit` property so the raw `easy_science_multi_fitter.fit(...)`
+path resolves the owner's constraints provider in the calling thread and
+consumes an explicit `constraints_factory` keyword (the core would
+swallow it via `**kwargs`). `install()`, run at import of
+`_bumps_constraints`, wraps `minimizer_bumps.FitDriver` so each
+`FitProblem` gets `constraints = factory(pars)` before the driver runs.
+Non-BUMPS engines raise `NON_BUMPS_ERROR`.
+
+**`InequalitySpec` (inequality_constraints.py):** Declarative
+`lhs op rhs` over parameter paths, evaluated with asteval in a
+restricted symbol table; `build_constraints_factory` returns BUMPS
+penalty callables.
+
+**Contrasts (`contrasts.py`):** A contrast is an ordinary `Model`
+sharing structure with a reference by identity or by `constrain_equal`.
+`derive_contrast` copies touched assemblies, shares the rest and ties
+parameters; `plan_link` / `apply_link` / `unlink` manage equalities
+between two models of one layout with full state snapshots.
+
+**`CalculatorBase` / `StatelessWrapperBase` / `CalculatorFactory`:**
+Template + Adapter + Factory. Explicit model membership
+(`register_model` / `discard_model` / `reset_storage`), per-model
+resolution, a magnetism flag reconciled with the served models,
+channel-bound fit functions.
+
+**`references` (sample/references.py):** Context-managed shared-object
+serialization (`writing()`, `reading(report)`, `suspended()`), with
+`prune`, `rebuild` and `register` for load-time reconciliation.
+
+**`paths.walk` (sample/paths.py):** Structural addressing of every
+parameter; the stable identity used by constraints and persistence
+instead of EasyScience unique names.
+
+## Entry Points
+
+- `Project.prepare_fit` / `prepare_sample` / `record_fit` - GUI fit and
+  sampling
+- `Project.load_experiment_from_files`, `load_polarized_experiment*`,
+  `load_orso_file`, `save_as_json`, `load_from_json`
+- `Project.add_contrast`, `plan_link`, `apply_link`, `detach`
+- `MultiFitter.fit`, `fit_polarized`, `mcmc_sample`
+- `Summary(project).save_html_summary` / `save_pdf_summary`
+- `python -m easyreflectometry.main` prints available calculators (no
+  console script registered)
+
+## Error Handling
+
+**Strategy:** Fail loudly at preparation time; warn for recoverable data
+issues; refuse silent degradation.
+
+**Patterns:**
+
+- `FitScopeError` (nothing to fit / experiment without model),
+  `FitPreconditionError` (unusable bounds for the engine), `ValueError`
+  for invalid settings or empty datasets after masking
+- `RuntimeError` when sampling without a BUMPS minimizer
+- `ValueError(NON_BUMPS_ERROR)` when inequality constraints meet a
+  non-BUMPS engine
+- `UnitError` (subclass of `ValueError`) for inequality unit mismatches
+- `FileExistsError` / `FileNotFoundError` / `OSError` / `ValueError`
+  from project persistence (no printing)
+- `warnings.warn` for zero-variance handling, ORSO column problems,
+  negative volume fractions, unreadable dependencies on load; load
+  issues also collected in `Project.load_report`
+- `try/finally` restores parameter state around posterior predictive;
+  `Project.save_as_json` writes atomically
+
+## Cross-Cutting Concerns
+
+**Logging:** `logging.getLogger(__name__)` in a handful of modules; no
+handler configured. `warnings` is the main user-facing channel.
+
+**Validation:** `FitSettings.validate`, `MinimizerOption.validate`,
+`InequalitySpec.validate_syntax` + `check_units`, ORSO column
+validation, `_check_fit_preconditions`.
+
+**Threading:** The constraints factory lives in a `contextvars`
+variable, resolved in the calling thread; `PreparedFit` owns array
+copies so a worker thread is isolated from later edits. Resolution for
+one-off curves is bound to the evaluator rather than swapped on the
+model to avoid racing a running fit.
+
+**Serialization:** EasyScience serializer plus library extensions:
+`references` for shared objects, structural paths for constraints, per
+dataset resolution entries, a `file_format` check. Posterior chains have
+their own sidecar format.
+
+**Authentication:** Not applicable.
+
+---
+
+_Architecture analysis: 2026-10-15 (develop @ 66adaf54)_

easyreflectometry-2.0.0/.planning/codebase/CONCERNS.md

@@ -0,0 +1,280 @@
+# Codebase Concerns
+
+**Analysis Date:** 2026-10-15 **Branch analysed:** `develop` @
+`66adaf54` **Revised:** 2026-11-08 for the easyscience 3 port
+(`core-3.0`)
+
+## Summary
+
+`develop` is 51 commits past `v1.7.0` and carries the unreleased 1.9
+work (contrasts, shared-object persistence, per-dataset resolution,
+prepare/record fit split, volume fractions, inequality constraints on
+BUMPS). The earlier concerns about the `bayesian_mp` branch
+(multiprocessing, chains/seed, git-branch core pin) are gone: the core
+dependency is a PyPI range, `n_workers`/`chains`/`seed` and
+`CalculatorFactory.__reduce__` no longer exist in the library, and MCMC
+goes through the core `Sampler`. The concerns below are what remains.
+
+---
+
+## 1. Coupling to EasyScience internals
+
+### Monkeypatch of `minimizer_bumps.FitDriver`
+
+**Issue:** Inequality constraints work only because
+`_bumps_constraints.install()` rebinds the module-level `FitDriver` name
+inside the core's `minimizer_bumps` namespace and inspects
+`problem.models[0].pars`. Any core refactor (importing `FitDriver`
+differently, building the problem elsewhere, renaming `.pars`) silently
+disables every inequality constraint; the shim passes untouched problems
+through without complaint.
+
+**Files:** `src/easyreflectometry/_bumps_constraints.py`,
+`src/easyreflectometry/fitting.py` (`_constraints`,
+`_keep_constraints_on_extend`),
+`tests/unit/test_bumps_constraints_shim.py`
+
+**Impact:** High. Physics silently dropped on a core upgrade.
+
+**Fix approach:** Keep the shim test that asserts penalties reach the
+problem on both `fit` and `mcmc_sample`; add a start-up assertion that
+the patched attribute exists; pursue an upstream hook
+(`constraints=`/callback) in corelib and keep the `<4` pin until it
+lands. Since core 3 the shim patches both `minimizer_bumps` and
+`samplers.sampler_bumps`, which imports its own `FitDriver`.
+
+### Core API surface (`easyscience>=3.0.2,<4`)
+
+**Issue:** Besides the public `Parameter`, `DescriptorNumber`,
+`global_object`, `Minimizers`, `ModelBase`/`EasyList`/`EasyBase`,
+`SerializerBase`, `MultiFitter`, `Sampler` and `FitResults`, the library
+depends on module paths a core refactor could move:
+`fitting.engine_base.PARAMETER_PREFIX`, the module-level `FitDriver` in
+`fitting.minimizers.minimizer_bumps` and
+`fitting.samplers.sampler_bumps`, and
+`variable.descriptor_base.DescriptorBase`.
+
+**Files:** `analysis/bayesian.py`, `inequality_constraints.py`,
+`_bumps_constraints.py`, `fitting.py`, `sample/base_core.py`
+
+**Impact:** Medium. A core minor release can break them.
+
+**Fix approach:** Keep the shim tests; check this list on every core
+upgrade.
+
+### Private core imports
+
+**Issue:** `PARAMETER_PREFIX` from `fitting.engine_base` and
+`DescriptorBase` from `variable.descriptor_base` are not exported at a
+package level.
+
+**Files:** `analysis/bayesian.py`, `inequality_constraints.py`,
+`sample/base_core.py`
+
+**Impact:** Medium.
+
+---
+
+## 2. Size and complexity hotspots
+
+### `project.py` is a 3211-line god object
+
+**Issue:** `Project` mixes session state, persistence (two file formats,
+reference resolution, constraint records), fit orchestration, contrasts
+and links, ORSO import, polarized loading, spin asymmetry, derived data
+for plots, and GUI index bookkeeping. Most behaviours are tested through
+it, so refactors are expensive.
+
+**Files:** `src/easyreflectometry/project.py`
+
+**Impact:** Medium-High for maintainability; the radon dashboard
+publishes the complexity.
+
+**Fix approach:** Extract cohesive modules that `Project` delegates to:
+`project_io.py` (as_dict/from_dict helpers, `_needs_new_format`),
+`project_experiments.py` (loading, polarized, merge),
+`spin_asymmetry.py` (`_spin_asymmetry`, `_unwrapped_angle`, channel
+helpers). Keep `Project` as the facade.
+
+### `fitting.py` (1428 lines) and `analysis/bayesian.py` (1412 lines)
+
+**Issue:** `bayesian.py` is mostly plotly styling constants and
+hand-rolled contour/density code for corner plots; `fitting.py` combines
+data preparation, settings, constraints wiring and five public fit
+paths.
+
+**Impact:** Low-Medium.
+
+**Fix approach:** Split `bayesian.py` into `posterior.py` (results,
+persistence, predictive) and `posterior_plots.py`; consider moving
+`PreparedFit`/`FitRun` to `fit_run.py`.
+
+### `Project.__init__` and `from_dict` ordering
+
+**Issue:** Loading depends on a specific order (materials → models →
+experiments → constraints → contrasts → links) and on `references`
+contexts being active. Several `_from_dict_*` helpers append to a shared
+`report` list. Easy to break when adding a persisted field.
+
+**Files:** `project.py` lines ~2845-3000
+
+**Impact:** Medium.
+
+---
+
+## 3. Persistence format risks
+
+### Project files from 1.x no longer load
+
+**Issue:** By design: 2.0 writes and reads `file_format` 4 only, and
+refuses files from 1.x (format 2, 3 or none) with a message; there is no
+converter. 1.x refuses format 4 in turn.
+
+**Files:** `project.py` (`FILE_FORMAT`, `from_dict`)
+
+**Impact:** Medium. Users re-create such projects or stay on 1.9; in the
+CHANGELOG.
+
+### Constraint records keyed by structural path
+
+**Issue:** `_user_constraints` refuses (raises `ValueError`) when a
+constrained parameter is not reachable from the models (e.g. a
+constraint on a palette material not used by any model). Saving a
+project then fails late, at save time.
+
+**Files:** `project.py` (`_constraint_candidates`, `_constraint_record`)
+
+**Impact:** Medium. Surfaced as an exception, which is the intended
+behaviour, but the GUI must handle it.
+
+### `derived_parameter` is session-only
+
+**Issue:** Documented, but a user who builds a derived parameter and
+saves loses it silently.
+
+**Files:** `constraints.py`
+
+**Impact:** Low.
+
+---
+
+## 4. Testing gaps
+
+### Thin integration/functional layers
+
+**Issue:** `tests/functional/test_dummy.py` asserts `2 + 2 == 4` and is
+the whole functional suite; `tests/integration/fitting/test_dummy.py`
+and `tests/integration/scipp-analysis/test_dummy.py` are `slow`-marked
+placeholders. Real integration coverage is `integration/convergence/`,
+`test_cross_engine_resolution.py`, `test_ort_file_fitting.py`.
+
+**Impact:** Medium. CI jobs named "functional tests" pass vacuously.
+
+**Fix approach:** Either delete the placeholders or move the end-to-end
+project tests (`test_project.py` fit paths, `test_polarized_fitting.py`
+slow cases) under `integration/`.
+
+### Sampler continuation and persistence
+
+**Issue:** `fitter.sampler.extend()` after constraints, and
+`save_posterior`/`load_posterior` fingerprint mismatch handling, have
+limited coverage (`TestMCMCSample*` in `test_fitting.py`,
+`test_bayesian.py`); all real DREAM runs are `slow` and only run on
+PRs/develop.
+
+**Impact:** Medium.
+
+### Default `pytest` skips `slow`
+
+**Issue:** `addopts = -m "not slow"` means local runs and some CI pushes
+never execute a real minimizer or sampler. Regressions in engine wiring
+surface only on PR CI.
+
+**Impact:** Medium; deliberate trade-off (see `pyproject.toml` comment).
+34 of 1410 tests are `slow`.
+
+### refnx-only assumptions
+
+**Issue:** Several fits and convergence references are refnx-based;
+refl1d is exercised mainly through polarized/magnetism tests and
+`test_cross_engine_resolution.py`.
+
+**Impact:** Low-Medium.
+
+---
+
+## 5. Repository hygiene
+
+### Duplicate CI matrices
+
+**Issue:** `python-ci.yml` and `python-package.yml` (pip-based, run on
+every push/PR) duplicate `test.yml`; `python-publish.yml` duplicates
+`pypi-publish.yml`.
+
+**Impact:** Low-Medium (CI minutes, confusing failures).
+
+### Untracked planning/notes directories
+
+**Issue:** `.planning/`, `.claude/`, `MD/`, `examples/`, `integration/`
+are untracked and not in `.gitignore`, so `git status` is always noisy
+and an accidental `git add .` would commit them.
+
+**Impact:** Low.
+
+**Fix approach:** Add `.planning/`, `.claude/`, `MD/` to `.gitignore`
+(or a global excludes file); decide whether `examples/` and
+`integration/` belong in the repo.
+
+### Docstring tooling disabled
+
+**Issue:** `pydoclint` and `format-docstring` are configured with
+`exclude = '\.'` (everything), `interrogate --fail-under=0`. The
+`docstring-lint-check` CI step therefore cannot fail.
+
+**Impact:** Low.
+
+### `main.py` has no console entry
+
+**Issue:** `main()` prints available calculators but `pyproject.toml`
+declares no `[project.scripts]`.
+
+**Impact:** Low; remove or register.
+
+---
+
+## 6. Numerical and physics conventions to keep in view
+
+- **SLD unit convention:** values are stored in units of 1e-6 Å^-2 while
+  the declared unit is `1/angstrom^2`; EasyScience strips numeric unit
+  factors so this cannot be fixed without a breaking migration (issue
+  #377 left open on purpose).
+- **Resolution convention:** `SIGMA_TO_FWHM` conversions in
+  `resolution_functions.py`, `orso_utils.py` and the refnx wrapper must
+  stay consistent; `tests/calculators/test_resolution_conventions.py`
+  and `tests/integration/test_cross_engine_resolution.py` pin them.
+- **Weights convention:** core weights are 1/σ (issue #370); keep in
+  mind when touching `_prepare_fit_arrays`.
+- **refl1d magnetism angle:** `DEFAULT_THETA_M = 270.0` and
+  `GUIDE_FIELD_ANGLE = 270.0`; thetaM=90 is parallel to the guide field
+  in refl1d. Past reviews got this backwards.
+- **Mighell objective:** `hybrid` default substitutes Mighell for zero
+  variance points; sampling with `mighell` is a bias correction, not a
+  likelihood (warned in `mcmc_sample`).
+- **Spin asymmetry heuristics:** `SPIN_ASYMMETRY_SIGNIFICANCE = 3.0`,
+  `SPIN_ASYMMETRY_CANCELLATION_FRACTION = 1e-3`,
+  `MAGNETIC_MOMENT_FLOOR_FRACTION = 0.01` in `project.py` are tuned
+  constants without a documented derivation.
+
+---
+
+## 7. Work in flight (not on develop)
+
+- The easyscience 3 port is on `core-3.0`, in PRs into that branch; it
+  is merged into `develop` only once the app no longer installs the
+  library from `develop` (the app needs its own port).
+- Uncommitted app-side work for per-dataset resolution (A1-A5) and the
+  magnetism/fitting gaps lives in the GUI repository, not here.
+
+---
+
+_Concerns audit: 2026-10-15 (develop @ 66adaf54)_