BornAgain integration - part 0

[rozyczko]

Look at the existing Python bindings in BA and evaluate the cost of embracing BA in ERL

[rozyczko]

BornAgain integration (view)

[rozyczko]

13-18 work days.

Essentially a month of dedicated effort.

[rozyczko]

Plan: Adding BornAgain as a Calculator Backend

Context

EasyReflectometryLib currently supports two calculator backends — refnx and refl1d. A non-functional stub for BornAgain already exists in src/easyreflectometry/calculators/bornagain/. This plan describes bringing BornAgain to full parity with the existing calculators so users can seamlessly switch between all three backends.

BornAgain should only provide the reflectivity profile for a given model. Our code converts the EasyReflectometry model objects into BornAgain's native types, runs the simulation, and converts the result back.

BornAgain v23 Python API (target version)

The existing stub was written against a pre-v22 BornAgain API that no longer exists. BornAgain v23 introduces breaking changes. Key v23 API constructs:

Concept	BornAgain v23 API
Material (SLD)	ba.MaterialBySLD("name", sld_real, sld_imag) — SLD in Å⁻²
Layer	ba.Layer(material, thickness, roughness?) — thickness in nm
Roughness	ba.Roughness(ba.SelfAffineFractalModel(sigma, hurst, corr_len), ba.TanhTransient())
Periodic stack	ba.LayerStack(n_periods) then .addLayer() / .addStack()
Sample	ba.Sample() then .addLayer() / .addStack()
Qz scan	ba.QzScan(q_array) — q in nm⁻¹
Q-resolution	scan.setRelativeQResolution(distr, dq_rel) or scan.setVectorResolution(distr, dq_vector)
Simulation	ba.SpecularSimulation(scan, sample)
Run	result = simulation.simulate()
Result	result.dataArray() → numpy array of intensities
SLD profile	from bornagain import sample_tools; z, sld = sample_tools.materialProfile(sample, n)

EasyReflectometry units vs BornAgain units

Quantity	EasyReflectometry	BornAgain v23
SLD	10⁻⁶ Å⁻²	Å⁻²
Thickness	Å	nm
Roughness σ	Å	nm
Q	Å⁻¹	nm⁻¹

All conversions must be applied in the wrapper layer.

---

Design Decisions

1. Target BornAgain version: v23 (latest stable). The old stub targets a pre-v22 API with ba.Multilayer, ba.QSpecScan, setScan, setSample, runSimulation; these are all replaced in v23.

2. Wrapper storage strategy: Follow the refl1d pattern (dict-based storage for model, items as plain lists/dicts) rather than trying to keep live BornAgain objects in storage. The BornAgain Sample is rebuilt from scratch before each calculate() call, which is the simplest and most robust approach.

3. Roughness mapping: EasyReflectometry uses a single σ (RMS roughness) per layer. BornAgain v23 requires a Roughness object constructed from an autocorrelation model. We will map σ → ba.SelfAffineFractalModel(sigma, hurst=0.5, corr_len=10*nm) with ba.TanhTransient() using sensible defaults for Hurst exponent and lateral correlation length.

4. Magnetism: Will initially be marked as NotImplementedError (same as refnx). Can be added later since BornAgain supports polarized neutron reflectometry.

5. SLD profile: Use bornagain.sample_tools.materialProfile(sample, n) rather than the custom reimplementation currently in the stub.

6. Resolution handling policy:

   • PercentageFwhm and LinearSpline are supported via BornAgain QzScan resolution methods.
   • Pointwise is initially unsupported for BornAgain and must raise NotImplementedError with a clear message, because EasyReflectometry Pointwise performs full reflectivity smearing from (Qz, R, sQz) data and is not equivalent to assigning only scan dq(q).

7. Resolution API insulation: BornAgain docs note that Q-resolution handling may change; keep all BornAgain resolution calls in a dedicated adapter/helper to isolate API drift.

8. Contract-first implementation: Full WrapperBase method signature conformance is a hard gate before numerical validation.

9. Roughness parity objective: Roughness defaults (hurst, corr_len) are provisional and must be calibrated against refnx/refl1d with explicit acceptance criteria.

---

Phase 1: Rewrite BornAgainWrapper against v23 API

Goal: A fully functional wrapper that can create materials, layers, items, models, and run calculations using BornAgain v23.

Estimated time: 4–5 days

---

Phase 2: Update BornAgainCalculator

Goal: Make the calculator class clean and minimal (like Refnx and Refl1d).

Tasks

1. Simplify calculator.py — Remove the duplicated create() method override (the base class already handles this). The calculator should only define:

   • name = 'BornAgain'
   • _material_link, _layer_link, _item_link, _model_link dicts
   • __init__ instantiating BornAgainWrapper

2. Update _model_link — Remove resolution from the link dict (resolution is handled via set_resolution_function, not as a model parameter — matching how refnx/refl1d work).

3. Ensure _layer_link keys match the wrapper's attribute names (e.g. 'roughness': 'sigma').

4. Preserve base model flow — do not reintroduce custom create() logic; keep model naming and model-aware wrapper calls aligned with CalculatorBase lifecycle.

Estimated time: 0.5–1 day

---

Phase 3: Register BornAgain in the Calculator Factory

Goal: Users can switch to BornAgain via the standard interface selection mechanism.

Tasks

1. Update calculators/__init__.py — Uncomment the BornAgain import block with a try/except:

   try:
       from .bornagain.calculator import BornAgain
       imported_calculators.append(BornAgain)
   except Exception:
       traceback.print_exc()
       print('Warning: BornAgain python is not installed')

2. Add bornagain as an optional dependency in pyproject.toml under an extras group (e.g. [project.optional-dependencies] → bornagain = ["bornagain>=23"]).

3. Verify factory switching — Confirm CalculatorFactory can list and switch between refnx, refl1d, and BornAgain.

4. CI-ready dependency wiring — ensure jobs that execute BornAgain tests explicitly install BornAgain dependencies, not only .[dev].

Estimated time: 1 day

---

Phase 4: Unit Tests for Wrapper

Goal: Comprehensive unit tests for BornAgainWrapper, mirroring the test structure of refnx/refl1d.

Estimated time: 2.5–3.5 days

---

Phase 5: Unit Tests for Calculator

Goal: Tests for BornAgain calculator class (in tests/calculators/bornagain/test_bornagain_calculator.py).

Tests to write

1. test_init — verify name, link dicts
2. test_fit_func — 3-layer model end-to-end via reflectity_profile()
3. test_calculate_with_repeats — periodic model end-to-end
4. test_sld_profile — via calculator interface

Estimated time: 1–1.5 days

---

Phase 6: Cross-Calculator Validation (Integration Tests)

Goal: Verify that BornAgain produces results consistent with refnx and refl1d for the same model.

Tasks

1. Simple 3-layer model — vacuum / single film / substrate. Compare reflectivity profiles from all three calculators. Allow tolerances (rtol ~1-5%) since different Fresnel engines can differ slightly.

2. Periodic multilayer — repeating bilayer structure. Compare across calculators.

3. SLD profile comparison — Build same model, extract SLD profiles, compare z and SLD arrays.

4. Resolution function test — Apply same resolution to all three, verify output consistency.

   • Numeric cross-calculator checks in this phase cover PercentageFwhm and LinearSpline only.
   • For Pointwise, verify explicit unsupported behavior for BornAgain until dedicated implementation is added.

5. Scale and background — Verify scale/background parameters are applied equivalently.

6. Calculator switching test — Create a model with refnx, switch to BornAgain mid-session, verify parameters are preserved and reflectivity is consistent.

7. Roughness calibration and acceptance criteria — calibrate BornAgain roughness defaults (hurst, corr_len) against refnx/refl1d:

   • Use canonical simple-film and periodic-multilayer models.
   • Validate by regime (critical edge, fringe region, high-q decay), not only one global tolerance.
   • Verify physical invariants (attenuation trend with increasing roughness, consistent scale/background behavior).

Estimated time: 3–4 days

---

Phase 7: Documentation & Cleanup

Goal: Document the new calculator and clean up.

Tasks

1. Remove "NOT FUNCTIONAL" warnings from calculator.py and wrapper.py.
2. Update README if it references available calculators.
3. Add BornAgain to CI with a two-lane strategy:
   • Core lane: existing matrix without BornAgain, must stay green.
   • BornAgain lane: dedicated job that installs BornAgain and runs BornAgain-marked tests.
   • Use pytest markers/skip logic so missing BornAgain does not fail unrelated jobs.
4. Guard against BornAgain resolution API drift — keep resolution logic in one helper and add focused regression tests around helper behavior.
5. Add docstrings to all public methods in wrapper and calculator.
6. Run Ruff on all new/modified files, fix any linting issues.

Estimated time: 1.5–2 days

---

Open Questions / Risks

#	Question	Impact	Recommendation
1	BornAgain v23 binary availability: Is bornagain installable via pip on all three CI platforms (Linux, macOS, Windows)?	May limit CI coverage	Check PyPI availability; if not available on all platforms, mark BornAgain tests with pytest.mark.skipif
2	Roughness model defaults: BornAgain v23 uses SelfAffineFractalModel(sigma, hurst, corr_len). What defaults for Hurst exponent and lateral correlation length?	Affects reflectivity match with refnx/refl1d	Start with hurst=0.5, corr_len=10*nm, tune to match Névot-Croce results from refnx/refl1d. May need investigation.
3	Unit system: BornAgain v23 uses nm internally. EasyReflectometry uses Å.	All conversions happen in wrapper — easy to get wrong	Thorough unit testing with round-trip checks
4	sample_tools.materialProfile availability: Is this submodule reliably present in v23?	SLD profile feature	Verify during Phase 1; fall back to manual SLD calculation if unavailable
5	Performance: Rebuilding the BornAgain Sample on every calculate() call	Could be slow for fitting	Acceptable for now; optimize later with caching if needed
6	Magnetism: BornAgain supports polarized neutrons natively	Future feature	Defer to a follow-up PR; raise NotImplementedError for now
7	Resolution API volatility: BornAgain docs indicate Q-resolution handling may change	Risk of breakage after BornAgain updates	Isolate all BornAgain resolution calls in one helper and keep dedicated regression tests
8	Pointwise semantic mismatch: EasyReflectometry Pointwise is reflectivity smearing, not just scan dq	Risk of incorrect physics if naively mapped	Keep unsupported initially with explicit NotImplementedError; design dedicated follow-up implementation

---

Time Summary

Phase	Description	Estimated Time
1	Rewrite BornAgainWrapper (v23 API)	4–5 days
2	Update BornAgainCalculator	0.5–1 day
3	Register in factory + optional dependency	1 day
4	Unit tests for wrapper	2.5–3.5 days
5	Unit tests for calculator	1–1.5 days
6	Cross-calculator integration tests	3–4 days
7	Documentation & cleanup	1.5–2 days
Total		13.5–18 days

Estimates assume a single developer familiar with the codebase and BornAgain. Add buffer for unexpected BornAgain API quirks or platform-specific issues.

[rozyczko]

Related Kanban project board:

BornAgain integration