ESSOS Field-Line Import

This page documents the external stellarator field-line import lane. The magnetic-field evaluation, adaptive field-line integration, and Poincare section extraction are performed by ESSOS. drbx stores the resulting trajectories, field samples, coil curves, and sanitized metadata as portable arrays for downstream geometry, FCI, and SOL-operator workflows.

The active completion sequence is tracked in the project planning notes. For main, the next direct-coil open-field target is the direct_coil_open_sol.py workflow: first validate pure-coil FCI maps, endpoint masks, connection-length refinement, sheath/recycling/neutral source accounting, the explicit source/profile gate, stationarity reports, and the optional diagnostic media stage; only then promote a direct-coil turbulence movie. The source/profile gate checks target labels, heat-load maps, neutral source maps, radial profiles, and source-balance residuals from the same endpoint masks consumed by the closures. VMEC closed-field controls and hybrid VMEC/coil open-SOL bridges are separate lanes, not interchangeable interpretations of the same field-line artifact.

The published import figures and arrays are restored by python scripts/fetch_example_artifacts.py. Regenerating the field-line import from the external coil geometry is a developer workflow and requires the geometry source checkout:

DRBX_ESSOS_ROOT=/path/to/ESSOS \
PYTHONPATH=src .venv/bin/python examples/geometry-3D/essos-field-lines/landreman_paul_qa_import.py

The script is configured by constants near the top of examples/geometry-3D/essos-field-lines/landreman_paul_qa_import.py. Set COIL_JSON_PATH to use a JSON file directly; otherwise the example resolves the default file from DRBX_ESSOS_ROOT. The committed report stores only the source filename and ESSOS method names so public docs do not depend on a local checkout path.

Scope

This is a geometry-import gate, not a wall-resolved stellarator edge prediction. It proves that drbx can consume field-line data generated by the external stellarator tooling already used for coil fields and Poincare sections. The import bundle contains:

  • Cartesian field-line trajectories \((X,Y,Z)(t)\);
  • seed points and trace times;
  • Poincare points \((R,Z)\) by section and seed index;
  • sampled magnetic-field vectors \(\mathbf{B}(X,Y,Z)\);
  • coil curve coordinates and currents for figure context.

The important design decision is separation of responsibility. ESSOS owns the coil representation, Biot-Savart field object, adaptive integrator, and Poincare root extraction. drbx owns import, QA plotting, and later conversion of those arrays into FCI maps, masks, metrics, and reduced Braginskii operators.

Imported Data Model

The import adapter writes a compressed NPZ bundle with arrays named:

trajectories_xyz       shape (n_field_lines, n_times, 3)
times                  shape (n_times,)
initial_xyz            shape (n_field_lines, 3)
poincare_r             shape (n_poincare,)
poincare_z             shape (n_poincare,)
poincare_time          shape (n_poincare,)
poincare_section       shape (n_poincare,)
poincare_line_index    shape (n_poincare,)
field_sample_xyz       shape (n_field_samples, 3)
field_sample_b_xyz     shape (n_field_samples, 3)
coil_gamma_xyz         shape (n_coils, n_segments, 3)
coil_currents          shape (n_coils,)

The companion JSON report records the trace resolution, seed range, source filename, field model, tracing model, Poincare method, field-magnitude range, trajectory spans, and pass/fail status. Absolute paths are intentionally not stored.

Current Artifact

ESSOS Landreman-Paul QA field-line import

The current artifact uses the Landreman-Paul QA coil file through ESSOS and imports the resulting field-line bundle into drbx. This replaces the previous internal annular coil-field proxy: no drbx source file now evaluates the coil magnetic field or traces the field lines.

The companion field-line/VMEC surface registration gate overlays independently traced coil-field Poincare points on the scaled Landreman-Paul QA VMEC surfaces used by the imported FCI and movie campaigns. That diagnostic is intentionally stricter than this import smoke gate: it records the current order-unity long-trace departure from the seeded VMEC surface instead of hiding it behind aggregate import success.

Downstream FCI Map Validation

The first downstream validation is documented in ESSOS imported FCI validation. That gate converts a scaled VMEC QA shell of externally traced trajectories into fixed-shape FCI maps, builds connection-length and endpoint-mask diagnostics, and routes DRBX sheath/recycling and neutral closures through the imported maps. The remaining production work is to add wall-resolved target geometry and to promote the imported-map residuals into the same PyTree/JVP implicit-solver lane used by the native 3D operators.