39-EFT.WP.Plasma.Confinement v1.0 | Appendix B. Implementation Binding & Function Prototypes

Home ／ Docs-Technical WhitePaper ／ 39-EFT.WP.Plasma.Confinement v1.0

Appendix B. Implementation Binding & Function Prototypes

I. Goals & Coverage (I10-/I20-/S50-/S60-/S70-/S80-/M10-/SimStack)

1. Layers covered: I10-PC (geometry/coil/boundary/metric binding), I20-PC/S30- (equilibrium coupling), S50- (waves/dispersion/deposition/arrival), S60- (guiding center/neoclassical), S70- (transport closures & flux-surface averaging), S80- (Edge/SOL & sheath), M10- (metrology/observation operators/assimilation), SimStack.Plasma (simulation stack).
2. Mandatory arrival dialect (two equivalent forms; path/measure explicit; record delta_form):
   • Constant-factored: T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
   • General: T_arr = ( ∫ ( n_eff / c_ref ) d ell )
3. Hard gates for release: check_dim=pass; power closure (P_in = P_ref + P_rad + P_wall + ∫ P_dep dV); topology consistency (q(ψ)/LCFS/X); stability gates (δW_min>0 ∧ Δ'≤0 ∧ {D_S,D_M}>0); arrival two-dialect agreement.

II. Namespaces & Versioning

1. Namespaces:
   • pc.i10.binding (geometry/coils → field/metrics)
   • pc.i20.equilibrium (boundary build / GS equilibrium)
   • pc.s50.waves (dispersion/rays/deposition/arrival)
   • pc.s60.gc_nc (guiding center/neoclassical)
   • pc.s70.transport (QL/tabulated closures & flux-surface averaging)
   • pc.s80.edge (1D along-B/sheath/detachment)
   • pc.m10.metrology (metrology/observation operators/assimilation)
   • pc.simstack.plasma (simulation stack APIs)
2. Version policy: api_version: "1.0" (semver); every response attaches {api_version, impl_version, checksum}.

III. Common Data Structures (minimal set)

types:

Geometry:

fields: {S_wall:str, ports:str, divertor:str}

CoilSpec:

fields: {centerlines:str, cross_sections:str, I_coil_kA:list[float]}

Metrics:

fields: {coords:str, Vprime:str, g_ab:str}

Equilibrium:

fields: {psi:str, q:str, metrics:Metrics}

Stability:

fields: {deltaW_min_J:float, DeltaPrime:float, DS:str, DM:str}

Waves:

fields: {n_eff_tbl:str, rays_json:str, alpha_abs_tbl:str, P_dep:str}

GCNC:

fields: {D_nc:str, chi_nc:str, J_bs:str}

Transport:

fields: {D:str, chi:str, fluxes:str} # Γ/Q/Π_ψ

EdgeSOL:

fields: {s_grid:str, profiles_1D:str, qt_gate:float, R:float, Lz_tbl:str}

Diagnostics:

fields: {H_blocks:list[str], windows:str, AF:str, PF:str, dt_sync_s:float}

ArrivalRecord:

fields:

{form:enum["n_over_c","one_over_c_times_n"], gamma:"explicit", measure:"d_ell",

c_ref:float, Tarr_s:float, u_Tarr_s:float, delta_form:str}

QAGates:

fields: {check_dim:str, power_closure:str, topology:str, stability:str, Tarr_dual:str}

IV. I10-PC | Geometry/Coils Binding (prototypes)

pc.i10.binding:

- id: "bind_geometry_coils"

proto: "bind_geometry_coils(geom:Geometry, coils:CoilSpec, options:any) -> {B_field:str, psi_bc:str, metrics:Metrics}"

qa: ["check_dim", "divB_gate", "topology_gate"]

- id: "export_binding"

proto: "export_binding(binding:any, format:'yaml|json') -> path"

V. I20-/S30- | Equilibrium Coupling (prototypes)

pc.i20.equilibrium:

- id: "build_boundary"

proto: "build_boundary(binding:any) -> psi_bc:str"

- id: "solve_gs"

proto: "solve_gs(psi_bc:str, p_of_psi:any, F_of_psi:any, options:any) -> Equilibrium"

notes: ["require smooth/monotone p'(psi)/F'(psi)", "record free/fixed-boundary mode"]

VI. S50- | Waves/Dispersion/Arrival (prototypes)

pc.s50.waves:

- id: "compute_dispersion"

proto: "compute_dispersion(eq:Equilibrium, medium:any, bands:any) -> {n_eff_tbl:str, detD_meta:any}"

- id: "trace_rays"

proto: "trace_rays(eq:Equilibrium, n_eff_tbl:str, launch:any) -> rays_json:str"

- id: "absorb_deposit"

proto: "absorb_deposit(eq:Equilibrium, rays_json:str, medium:any) -> {alpha_abs_tbl:str, P_dep:str}"

- id: "arrival_time"

proto: "arrival_time(rays_json:str, n_eff_tbl:str, arrival:ArrivalRecord) -> {Tarr_s:float, u_Tarr_s:float}"

VII. S60- | Guiding Center / Neoclassical (prototypes)

pc.s60.gc_nc:

- id: "integrate_gc"

proto: "integrate_gc(eq:Equilibrium, metrics:Metrics, particles:any, options:any) -> {mu_J_check:bool, orbits:str}"

- id: "neoclassical_coeffs"

proto: "neoclassical_coeffs(eq:Equilibrium, metrics:Metrics, collisionality:any) -> GCNC"

VIII. S70- | Transport Closures & Flux Averaging (prototypes)

pc.s70.transport:

- id: "ql_closure"

proto: "ql_closure(eq:Equilibrium, spectra:any, scales:any) -> {D:str, chi:str}"

- id: "tabulated_closure"

proto: "tabulated_closure(table:str, inputs:any) -> {D:str, chi:str, V_pinch:str, C_TE:str}"

- id: "flux_surface_average"

proto: "flux_surface_average(eq:Equilibrium, D:str, chi:str, sources:any) -> {fluxes:str, energy_closure:bool}"

IX. S80- | Edge/SOL & Sheath (prototypes)

pc.s80.edge:

- id: "solve_edge_1d"

proto: "solve_edge_1d(geom:Geometry, eq:Equilibrium, sources:any, sheath:any) -> EdgeSOL"

- id: "detachment_scan"

proto: "detachment_scan(edge:EdgeSOL, Pin:list[float], R:list[float], geom:list[any]) -> {qt_curve:str, window:str}"

X. M10- | Metrology & Assimilation (prototypes)

pc.m10.metrology:

- id: "build_observation"

proto: "build_observation(diag:Diagnostics, eq:Equilibrium) -> y_obs:str"

- id: "assimilate"

proto: "assimilate(H_blocks:list[str], R:str, B:str, y_obs:str, x_b:any, options:any) -> {x_a:any, cost:float, qa:QAGates}"

XI. SimStack.Plasma | Simulation Stack (prototypes)

pc.simstack.plasma:

- id: "build"

proto: "build(geom:Geometry, coils:CoilSpec, options:any) -> sim_handle"

- id: "forward"

proto: "forward(sim_handle:any, theta:map, grid:any) -> {i10, eq, stab, waves, gc_nc, transport, edge, synth}"

- id: "invert"

proto: "invert(sim_handle:any, data:any, priors:any, sampler:'EnKF|4DVar') -> {posterior:any, logZ:float, summary:any}"

- id: "ppc"

proto: "ppc(sim_handle:any, posterior:any) -> {residuals:any, gates:QAGates}"

- id: "export"

proto: "export(sim_handle:any, format:'cards|json') -> artifacts:list[str]"

XII. QA Gates & Check Functions

qa:

- id: "check_dim" ; proto: "check_dim(obj:any) -> enum['pass','fail']"

- id: "divB_gate" ; proto: "divB_gate(B:str) -> {residual:float, pass:bool}"

- id: "power_closure" ; proto: "power_closure(Pin,Pref,Prad,Pwall,Pdep) -> {diff_W:float, pass:bool}"

- id: "topology_gate" ; proto: "topology_gate(eq:Equilibrium, imaging:any) -> {lcfs_ok:bool, xpoints_ok:bool}"

- id: "stability_gate" ; proto: "stability_gate(stab:Stability) -> {deltaW_min_ok:bool, DeltaPrime_ok:bool, DS_ok:bool, DM_ok:bool}"

- id: "arrival_dual_gate" ; proto: "arrival_dual_gate(T1:float, T2:float, u_Tarr:float) -> {pass:bool}"

XIII. Error Codes (Unified)

errors:

E_BAD_UNITS: "Unit or dimensional mismatch"

E_DIVB_FAIL: "∇·B residual above gate"

E_TOPOLOGY_FAIL: "Topology consistency failure (LCFS/X/separatrix)"

E_FORCE_BALANCE: "Force-balance residual above threshold"

E_POWER_CLOSURE: "Power closure failure"

E_STABILITY_FAIL: "Stability gates not satisfied (δW/Δ'/D_S/D_M)"

E_ARRIVAL_MISMATCH: "Two-dialect T_arr mismatch"

E_TABLE_OOB: "Closure table out-of-bounds / unband-limited interpolation"

E_ASSIM_OPS: "Observation-operator / covariance version or dimension mismatch"

E_QA_FAIL: "QA gates not satisfied"

XIV. Request/Response Example (minimal)

request:

api_version: "1.0"

op: "waves_deposit_arrival"

payload:

eq: "/eq/psi_q.nc"

medium: {ne_m3:6.0e19, Te_eV:3500, B_T:5.3}

launch: {mode:"X", freq_GHz:170, angles:{pol:..., tor:...}}

arrival:

form: "n_over_c"

gamma: "explicit"

measure: "d_ell"

c_ref: 299792458.0

u_Tarr_s: 9.0e-08

response:

api_version: "1.0"

result:

n_eff_tbl: "/waves/n_eff.tbl"

rays_json: "/waves/rays.json"

alpha_abs: "/waves/alpha.tbl"

P_dep_Wm3: "/waves/Pdep.nc"

Tarr_s: 3.08e-06

qa_gates: {check_dim:"pass", power_closure:"pass", Tarr_dual:"pass"}

checksum: "sha256:..."

XV. Compliance Templates (Arrival / Binding / Wave→Transport Chain)

arrival:

form: "n_over_c" # or "one_over_c_times_n"

gamma: "explicit"

measure: "d_ell"

c_ref: 299792458.0

Tarr_s: 3.10e-06

u_Tarr_s: 9.0e-08

delta_form: "n_over_c"

i10_binding:

geometry: {S_wall:"/cad/wall.step", ports:"/cad/ports.step", divertor:"/cad/div.step"}

coils: {centerlines:"/cad/coils.centerlines.json", cross_sections:"/cad/coils.cs.json", I_coil_kA:[...]}

B_field: "/fields/B_vacuum.nc"

metrics: {coords:"/eq/coords_boozer.nc", Vprime:"/eq/Vprime.nc", g_ab:"/eq/metric.nc"}

waves_to_transport_chain:

dispersion: {n_eff_tbl:"/waves/n_eff.tbl", bands:{ω1:..., ω2:...}}

rays: "/waves/rays.json"

absorption: "/waves/alpha.tbl"

P_dep: "/waves/Pdep.nc"

ql_closure: {table:"/closures/ql_mix.tbl", outputs:["/trans/D.nc","/trans/chi.nc"]}

fluxes: "/trans/fluxes.nc"

XVI. End-to-End Execution Order (pseudocode)

# 1) Binding & equilibrium

bind = bind_geometry_coils(geom, coils, opt)

eq = solve_gs(bind.psi_bc, p_of_psi, F_of_psi, opt)

# 2) Waves/deposition/arrival

n_eff = compute_dispersion(eq, medium, bands)

rays = trace_rays(eq, n_eff, launch)

Pdep = absorb_deposit(eq, rays, medium)

Tarr = arrival_time(rays, n_eff, arrival)

# 3) GC/neoclassical & transport

gc = integrate_gc(eq, bind.metrics, particles, opt)

nc = neoclassical_coeffs(eq, bind.metrics, coll)

ql = ql_closure(eq, spectra, scales)

flux = flux_surface_average(eq, ql.D, ql.chi, sources)

# 4) Edge/SOL & assimilation

edge = solve_edge_1d(geom, eq, sources, sheath)

yobs = build_observation(diag, eq)

xa = assimilate(H_blocks, R, B, yobs, xb, opt)

# 5) QA & export

assert power_closure(Pin, Pref, Prad, Pwall, Pdep).pass

assert arrival_dual_gate(Tarr1, Tarr2, arrival.u_Tarr_s).pass

export_cards(...)

XVII. Constraints & Release Gates (Plasma hard gates)