Utils (ported SFINCS v3 scripts)

The vendored scripts in examples/sfincs_examples/utils/ are a Python-3 port of sfincs/fortran/version3/utils. They are kept with the upstream example suite so compatibility workflows can use the same plotting and scan post-processing layout as SFINCS Fortran v3.

The supported public entry point is the dkx postprocess-upstream CLI. Generate sfincsOutput.h5 first with dkx write-output or the Python output writer, then run the selected upstream plotting script non-interactively through the CLI wrapper.

Execution mode

Use the normal solver path to produce the output file. CLI runs are performance-oriented by default; Python workflows can request differentiable paths explicitly when a gradient calculation is required:

dkx write-output --input input.namelist --out sfincsOutput.h5
dkx postprocess-upstream --case-dir . --util sfincsPlot -- --save-prefix /tmp/sfincsPlot

For differentiable Python workflows, use the pure canonical APIs (dkx.solve.solve() with differentiable=True) before post-processing the resulting HDF5 file.

Note

The export‑f grid uses the full internal grids. sfincsPlotF expects export_delta_f or export_full_f to be enabled in the input namelist.

Quick start

Single run:

dkx write-output --input input.namelist --out sfincsOutput.h5
dkx postprocess-upstream --case-dir . --util sfincsPlot -- --save-prefix /tmp/sfincsPlot
dkx postprocess-upstream --case-dir . --util sfincsPlotF -- --save /tmp/sfincsPlotF.png

Scan:

dkx scan-er --input input.namelist --out scan_er
dkx postprocess-upstream --case-dir scan_er --util sfincsScanPlot_2 -- --save /tmp/scan_er.png

The following sections document each script and show compact checked figures from the documentation static assets. The supported user entry point is the dkx postprocess-upstream command shown above.

Scan directives (`!ss`)

Upstream SFINCS v3 uses special !ss lines in input.namelist to control scan scripts. These lines are ignored by the Fortran namelist reader and are consumed only by sfincsScan. Key points from the upstream user manual:

!ss directives can appear anywhere in input.namelist (inside or outside namelist blocks).
!ss directives do not have defaults; they must be explicitly set when you invoke sfincsScan.
The scan scripts assume the output file is named sfincsOutput.h5 (the upstream default). Renaming the output file breaks the plotting utilities.

Core scan types:

scanType = 1: resolution convergence scan (Ntheta/Nzeta/Nxi/Nx/...)
scanType = 2: radial electric field scan
scanType = 3: scan any single numeric input parameter
scanType = 4: radial scan using a profiles file (fixed Er at each radius)
scanType = 5: radial scan with an Er scan at each radius
scanType = 21: run-spec scan driven by runspec.dat
scanType = 22: run-spec radial scan with Er scans in each radius directory

Convergence scans (scanType = 1) use ...MinFactor, ...MaxFactor, and ...NumRuns to define log-spaced resolution values (similar to Matlab’s logspace). Ntheta is always forced to odd values.

Example !ss block:

!ss scanType = 3
!ss scanVariable = nuPrime
!ss scanVariableMin = 0.1
!ss scanVariableMax = 1.0
!ss scanVariableN = 4
!ss scanVariableScale = log

Single‑run plotting

sfincsPlot: Plot geometry and core diagnostics from a single sfincsOutput.h5. Use --save-prefix to write *_figN.png without showing a GUI window.

sfincsPlotF: Plot distribution‑function slices from full_f or delta_f. Requires export_delta_f or export_full_f in input.namelist.

Scan launchers (run `dkx`)

sfincsScan: Top‑level scan dispatcher. Reads !ss directives in input.namelist and calls the matching scan script. Use --yes to run without prompts.
sfincsScan_1: Convergence scan over resolution parameters.
sfincsScan_2: Scan over E_r (or dPhiHatd* based on inputRadialCoordinateForGradients).
sfincsScan_3: Scan any single numeric input parameter.
sfincsScan_4: Radial scan using a profiles file (see radialScans).
sfincsScan_5: Nested radial scan + E_r scan at each radius.
sfincsScan_21 / sfincsScan_22: Run‑spec scans driven by runspec.dat (single runs or nested E_r scans).

Run-spec files (`runspec.dat`)

runspec.dat begins with one or more comment lines starting with ! (or #/%). The last comment line lists the variable names; each following data line supplies values for one run. Example:

! rN_wish THats_1 THats_2 dPhiHatdpsiN
  0.2     1.0     1.0     0.0
  0.4     1.2     1.1     0.3

Scan plotting

sfincsScanPlot: Dispatcher for scan plot scripts. Use pdf or --save to write files.

sfincsScanPlot_1 – Convergence scan plots

sfincsScanPlot_2 – E_r scan + ambipolar roots

sfincsScanPlot_3 – Single‑parameter scan: For RHSMode>1, the plot shows transport matrix elements L_ij vs the scanned variable.

sfincsScanPlot_4 – Radial scan

sfincsScanPlot_5 – Radial + E_r scan

sfincsScanPlot_21 – Interactive x/y dataset plotting: Use --x, --y, --xscale, --yscale to run non‑interactively, plus --save to write a PNG (useful for batch runs/CI).

sfincsScanPlot_combine – Combine multiple scans: Use --save to write a PNG when running non‑interactively.

Radial scan helper

radialScans: Shared helper for scan types 4 and 5. Reads profiles and interpolates density/temperature profiles and their gradients.

`profiles` file format (profilesScheme=1)

For radial scans, the default profile scheme (!ss profilesScheme = 1) expects a plain-text profiles file:

The first non-comment line is the radial coordinate index (0=psiHat, 1=psiN, 2=rHat, 3=rN).
Each following line has 2*Nspecies+4 values: radius, NErs, Er_min, Er_max, nHat(1), THat(1), nHat(2), THat(2), ....

Example for a single species:

# radial coordinate: rN
3
0.20  3  -1e-3  1e-3  1.0  1.0
0.30  3  -1e-3  1e-3  1.0  1.0
0.40  3  -1e-3  1e-3  1.0  1.0

Monoenergetic transport coefficients

The figure below shows monoenergetic transport coefficients L_ij as a function of collisionality (nuPrime, scanned over 0.01–1) for three EStar values (0, 0.1, and 0.3; the E0/E1/E2 directories). This plot is generated by running three scanType=3 directories on the monoenergetic_geometryScheme1 example and combining them with sfincsScanPlot_combine --save.

Bootstrap current vs collisionality

sfincsScanPlot_21 can plot any output dataset. The figure below shows FSABjHat versus nu_n for a simple 2‑species PAS case.

Regenerating gallery evidence

The gallery figures above are release evidence, not first-pass examples. Use the post-processing CLI on a generated output directory to regenerate a local version of any panel, and keep large regenerated artifacts outside git.