FARSIGHT-1D configuration

Use solver: farsight-1d with the explicit runner. Unknown fields, nonfinite values, nonintegral counters and invalid ranges are rejected. Float64 must be enabled before preparation (the module CLI does this). Quantities use normalized electron plasma units with q = -1, m = 1, mean density one.

Section / key	Default	Meaning
grid.nx	required	Even number of x intervals, at least 4
grid.nv	required	Even number of v intervals, at least 2
grid.xmin	0	Left periodic boundary
grid.xmax	required	Right boundary, greater than xmin
grid.vmin, grid.vmax	required	Increasing velocity bounds; zero inflow on remesh
time.tmin	0	Starting time
time.tmax	required	Ending time, greater than tmin
time.dt	required	Positive timestep; the time span must be a positive integer multiple
initial.kind	maxwellian	maxwellian or symmetric two-stream
initial.thermal_speed	1	Positive Gaussian standard deviation in v
initial.drift	0	Maxwellian mean; two-stream means ±drift, requiring drift > 0
initial.amplitude	0.01	Density modulation A in 1 + A*cos(2*pi*mode*(x-xmin)/L), between -1 and 1
initial.mode	1	Positive integer strictly below nx/2
numerical.epsilon	required	Positive regularization length, in x units
numerical.quadrature	trapezoid	trapezoid or simpson; both assemble shared panel weights
numerical.remesh_every	1	Remesh every this many steps; 0 disables remeshing for diagnostic experiments
numerical.chunk_size	64	Positive target batch size for field and panel lookup
numerical.field_solver	direct	direct or treecode, used for all RK stages and field observations
numerical.treecode.degree	8	Interpolation polynomial degree, 1–32 (degree+1 nodes)
numerical.treecode.theta	0.5	Opening ratio in [0,1); 0 dispatches to exact direct evaluation
numerical.treecode.leaf_size	32	Positive source capacity per direct leaf
amr.enabled	false	Use packed adaptive leaves; fixed-grid path is unchanged when false
amr.max_level	1	Maximum quadtree depth, 0–4; 0 is the fixed root partition
amr.min_level	0	Force refinement to at least this depth, no greater than max_level
amr.max_panels	256	Static leaf-slot capacity; overflow fails explicitly
amr.atol, amr.rtol	0.05, 0	Nonnegative range threshold atol + rtol*max(abs(f))
amr.max_gap_fraction	0.01	Positive maximum interior extension distance in (x/L,v/velocity_span)
save.scalars.every_steps	1	Scalar observation stride
save.fields.every_steps	10	Fixed-grid electric field stride; fields: null disables
save.distribution	null	Enable with {every_steps: N} to save moving x, v and f

All enabled schedules include step zero and the final step, even if the stride does not divide the step count. Saves are at integer steps; observations never interpolate between two different remeshed representations. The full final state is retained independently of all observation strides. A final step not divisible by remesh_every retains moving coordinates. tmin labels the initial state supplied by the chosen initial condition; it does not evolve it beforehand.

The sampled initial distribution is normalized once to sum(W*f) = L; no normalization is applied during evolution. Two-stream initialization uses equal Gaussian beams. This normalization cannot resolve a narrow beam on an inadequate velocity grid or restore truncated tails. There are no collisions, multiple species, external fields or limiters.

Treecode options are validated even when the direct evaluator is selected, but only affect evaluation for field_solver: treecode. A positive-theta tree walk is not reverse-mode differentiable; its prepared capability says so. Use direct evaluation or theta=0 for reverse-mode objectives. Force approximation can add momentum drift; compare fields and trajectories against direct sums while varying degree/theta, independently of AMR tolerances and softening.

AMR initially samples all candidate nodes, normalizing their finest-level quadrature before threshold decisions, then normalizes the selected partition once to mass L. Later remeshes never normalize. At least (nx/2)*(nv/2)*4**min_level slots are required; a more refined initial selection can require more and is checked before execution. The full candidate hierarchy is limited to 32768 panels. These bounds are allocation guards, not accuracy guarantees. Refinement and balancing iterate to a fixed point; newly created leaves are checked against the same range criterion.

Saved data

scalars is a dataset with dimension t:

Variable	Definition
mass, c2	Reference/material quadrature sums sum(W*f), sum(W*f*f)
momentum, kinetic_energy	Unit-mass sums sum(W*f*v), sum(W*f*v*v)/2
electric_energy, total_energy	Fixed-x L*mean(E*E)/2, and its sum with kinetic energy
min_f, negative_mass	Minimum nodal value and sum(W*max(-f,0))
remesh_count	Number of executed remeshes
remap_mass_change, remap_c2_change	Sum of signed after-minus-before remesh changes
remap_mass_abs_change, remap_c2_abs_change	Sum of absolute per-remesh changes
remap_uncovered_nodes	Cumulative target-node count outside all panels, including legitimate zero inflow and the duplicated x endpoint
invalid_panels	Cumulative invalid panel count at remeshes
max_panel_area_error	Maximum absolute relative corner-polygon area error observed at any remesh
valid	Persistent validity flag; a false value makes host analysis fail

With AMR enabled, additional scalar variables are saved:

Variable	Definition
active_panels, requested_panels	Packed leaf count and requested count before capacity check
capacity_exceeded	Persistent overflow flag; invalidates the result
refinement_limited_panels	Current maximum-level leaves still exceeding the range threshold
regrid_mass_change, regrid_c2_change	Cumulative quadrature-change portion of the total remap_* budget
remap_gap_nodes	Cumulative candidate-node evaluations extended across interior polygon gaps
max_gap_fraction	Largest recorded interior extension in the fixed normalized phase-space metric

AMR uncovered/gap counts include every candidate node evaluation, including duplicates and candidates not ultimately selected. They are diagnostics of reconstruction work, not unique-node counts or lost mass. min_f excludes inactive slots. Changing AMR quadrature changes C2; it is part of the reported total remap defect, not an invisible correction.

fields.electric_field has dimensions (t,x) on nx unique periodic locations. distribution.x, .v, and .f have dimensions (t,x_node,v_node) with (nx+1,nv+1) nodes. x and v are data variables holding the current moving coordinates. Neither node index is generally a physical coordinate. The x endpoint is a duplicate with quadrature endpoint weighting.

With AMR, distribution variables x, v, f, weights instead have dimensions (t,panel,node), with panel=max_panels and nine nodes. active, panel_id, and level have dimensions (t,panel). Slots can change identity at remesh; use panel_id (the hierarchy index) and the mask when comparing frames. Inactive IDs/levels are -1. The complete final NPZ state includes this topology and quadrature information even when distribution snapshots are disabled.

See conservation and resolution before interpreting C2, energy or geometry diagnostics.