Skip to content

Input reference ​

A PRISM run reads one INI file: mpirun -np N exe/adam_prism_cpu input.ini (or adam_prism_fnl). This page lists every section and key PRISM reads, with its type, whether it is required, its default, the accepted values and what happens on an invalid one. The sections the library reads for every application ([IO], [grid], [amr], [amr_marker_N], [runge_kutta], [weno], [fdv], [solids], [slices], the forest manifest) are in the library input reference, with PRISM's use of each; PRISM's additional rules for them are below. The library page also gives the parsing rules and the legend of the Req. column.

Read the hazards first: they collect the combinations PRISM refuses, and the ones it accepts but handles differently than the key names suggest.

Program entry and read order ​

adam_prism_cpu [file] / adam_prism_fnl [file] (default input.ini). A file with a [forest] section and realms_number >= 1 is a forest manifest; otherwise it is itself a single-realm input.

A realm input is read in this order: [IO] → [numerics] → [physics] → [runge_kutta] scheme and the coil counts (the memory budget) → the library sections ([grid], [amr], markers, [weno], [runge_kutta], [fdv], [solids], [slices]) → [bc_*] → [PIC] and [particle_injection] (PIC models) → [time] → [initial_conditions] → [coils_input] → [grms] → [magnetic_field_at_center_domain] → [probes] → [leapfrog] (PIC leapfrog) → [external_fields] → [fWLayer] → [PML]. The backend then checks the combinations (time and space schemes, PML, PIC current) and stops on the ones it does not implement.

CRLF. A Windows (CRLF) input reads as an LF one on both backends (see the library parsing rules).

Units. SI, except under the non-dimensional models (AdimEM, AdimPIC), where lengths are divided by L0, fields by B0 and D0 = B0 c0 ε0, times by T0 = L0/c0; the input stays in SI and PRISM converts it.


[IO] ​

The library keys are in the library reference; PRISM uses save_memory_status, save_curl_fields, save_divergence_fields and the seam div(B) monitor seam_divB_tol / seam_divB_error, which FLUME does not. PRISM adds one key.

KeyTypeReq.DefaultAccepted / invalidMeaning
save_fieldsstringnoallall, em; other values are fatalall: every field in the field files. em: D and B only (production runs); the save_residual/curl/divergence_fields flags still add their arrays.

A cadence <= 0 disables that output, end of run included (#97).


[numerics] ​

Every key is required; an unknown value is fatal.

KeyAccepted valuesMeaning
scheme_timerunge_kutta, leapfrog, blanes_moan, commutator_free_magnus (also UPPER and Capitalised)Time integration. Only runge_kutta runs: the other three are refused at initialization on both backends (#55).
scheme_spacefd_centered, fv_centered, weno (also UPPER and Capitalised)Spatial scheme. weno runs on the CPU backend only (the FNL backend refuses it).
reconstruction_variablesconservative, characteristicsVariables the WENO path reconstructs.
constrained_transportno, D, B, DB (case variants accepted)Which GLM scalars to carry: φ for D, ψ for B. See the divergence-correction matrix.
divergence_correctionno, hyperbolic, poissonhyperbolic: the GLM cleaning of the scalars selected by constrained_transport (required: D, B or DB). poisson: refused at load. no: no correction; a constrained_transport other than no is then ignored with a warning.

[physics] ​

KeyTypeReq.DefaultAccepted / invalidMeaning
physical_modelstringyes—EM (em, Electromagnetic, electromagnetic, Maxwell, maxwell), PIC (pic, ParticleInCell, particleincell), AdimEM (adimem, AdimensionalizedElectromagnetic, adimensionalelectromagnetic), AdimPIC (adimpic, adim_PIC, adim_pic); other values are fatalMaxwell's equations, with particles (PIC), in SI or non-dimensional form. A PIC model adds the charge density rho to the state.
L0realcond. (AdimEM, AdimPIC)—> 0, otherwise fatalReference length (m).
B0realcond. (AdimEM, AdimPIC)—> 0, otherwise fatalReference magnetic field (T).
chirealcond. (divergence_correction = hyperbolic)—> 0, otherwise fatalGLM propagation speed, in units of c: the fastest wave is max(1, chi) c0.
alpharealno0>= 0, otherwise fatalGLM damping rate (1/s, or 1/T0 non-dimensional); > 0 also caps the time step at 1/alpha. Read only with hyperbolic.

Library sections in PRISM ​

SectionPRISM rule
[grid]ngc >= fdv_order/2 (fatal); with scheme_space = weno also ngc >= [weno] S (fatal). Extents are divided by L0 in a non-dimensional model.
[amr]Refinement at initialization only, during the [initial_conditions] amr_iterations passes; frequency is read and unused, regrid_prolongation is unused.
[amr_marker_N]Mode 1 primitive-box refines; mode 3 (AMR_TV) refines on the total variation of the coils' current density (tol, delta_type, delta_fine, delta_coarse). stl is fatal. Mode 1 solid, mode 2, mode 4 and mode 5 do nothing, silently.
[runge_kutta]EM on CPU: every scheme, Yoshida included. EM on FNL: Yoshida is refused. PIC: runge-kutta-ssp-22/33/54 only. The PML, the charge-conserving PIC current and the staged path (2:1 faces, forests) need an SSP scheme (the PIC current one of SSP-22/33/54).
[weno]Used only with scheme_space = weno (CPU). weights (js, si) is used; ROR is not implemented.
[fdv]fdv_scheme (FD, FV) selects PRISM's operators and the coil stamping; fdv_order the order of the centred operators, which the t0 elliptic solves also use (they accept 2, 4, 6, 8).
[solids]Loaded and passed to the Runge-Kutta stages; no committed PRISM input uses solids.

[bc_x_min], [bc_x_max], [bc_y_min], [bc_y_max], [bc_z_min], [bc_z_max] ​

One key per section, required.

KeyAccepted valuesMeaning
typeextrapolation, Neumann, Dirichlet, Silver_Muller, periodic, PEC (or pec); case-sensitive, other values are fatal. radiative is refused (#57).Face boundary condition.
  • periodic is the library's periodicity (BC_PERIODIC = -1): the tree builds periodic neighbours and the ghost exchange fills the periodic ghosts, across blocks and ranks. The two faces of an axis must be both periodic or neither (fatal).
  • Dirichlet writes zero into the ghosts; there is no key for a prescribed value.
  • Edge and corner ghost rows receive no boundary condition.
  • Silver_Muller is spelled with an underscore.
  • The elliptic map gives the boundary the t0 solves see.

[time] ​

Every key is required.

KeyTypeMeaning
it_maxint> 0: stop after it_max steps. <= 0: run to time_max.
time_maxrealEnd time (s; divided by T0 in a non-dimensional model).
CFLrealCFL number on the fastest wave, max(1, chi) c0 (upper-case key). The PML (C_gamma) and the GLM damping (alpha) may cap the step further.

[initial_conditions] ​

KeyTypeReq.Accepted / invalidMeaning
amr_iterationsintyesnegative values are clamped to 0Initial-condition + AMR passes: each sets the initial condition and runs the markers.
typestringyessee below; other values are fatalInitial field.
typeExtra keys (all required, real unless stated)Field
vacuum—Every variable zero.
plane_wavekx, ky, kz (direction components), lambda (wavelength), B0 (amplitude, T)A plane wave of wavelength lambda along (kx, ky, kz), D = B0 c0 ε0.
gaussian_pulseB0, k0 (carrier wavenumber), r0 (centre along the direction), sigma (> 0, width), pulse_direction (string)A Gaussian-enveloped wave packet.
gaussian_derivative_pulseB0, r0, sigma (> 0), pulse_direction (string); optional k0 (carrier wavenumber, default 0)A pulse with no zero-frequency content: single-cycle with k0 = 0, a packet around k0 otherwise.
rmf_field[external_fields] RMF_frequency, RMF_B_amplitude, RMF_rotation_axis (X, Y, Z, either case; other values are fatal)A rotating magnetic field.
uniform_fieldB_x, B_y, B_zA uniform magnetic field.
riemann-problem—Refused: its regions were read but never applied (#56).
magnetic_nozzle, rmf_magnetic_nozzle—Refused: use [external_fields] external_fields_applied for a nozzle field (also refused, see there).

pulse_direction accepts +x, -x, +y, -y, +z, -z; another value is fatal when the initial condition is set. Under the non-dimensional models the pulse lengths are given in SI and converted.


[coils_input] and [coils_input_coil_N] ​

Coil current sources, stamped into the current density J as a Gaussian distribution around the coil path.

[coils_input] ​

KeyTypeReq.Meaning
rectangular_coils_numberintyesRectangular loops.
circular_coils_numberintyesCircular loops.
solenoid_coils_numberintyesSolenoids.
helicon_coils_numberintyesHelicon antennas (polylines).
time_delayrealcond. (any coil)Ramp-up time: the current is multiplied by g(s) = 10s³ − 15s⁴ + 6s⁵, s = t/time_delay clamped to [0, 1], so it grows smoothly from zero at t0 to full at time_delay. With time_delay <= 0 the coils carry full current at t0, and the t0 magnetic field is solved for (see [PIC] magnetic_field_elliptic_initialization).

The four counts are always required, even when they are all zero.

[coils_input_coil_N] (N = 1..total coils) ​

KeyTypeReq.Accepted / invalidMeaning
coil_typestringyesrectangular, circular, solenoid, helicon; another value is accepted silently and stamps no coilGeometry.
current_typestringyesDC_current, AC_current; another value is accepted silently and reads no amplitudeWaveform.
sigmarealyes—Width of the Gaussian current distribution.
x_center, y_center, z_centerrealyes (every kind)—Coil centre.
normalstringyes (every kind)+x, -x, +y, -y, +z, -z; another value stamps no coil, silentlyCoil plane normal (the axis of a solenoid).
lx, lyrealrectangular—Loop sides.
r_coilrealcircular, solenoid, helicon—Radius.
l_solenoidrealsolenoid—Length.
windingsintsolenoid—Turns.
N_pointsinthelicon<= 50, otherwise fatalPoints of the antenna path.
x_point_K, y_point_K, z_point_Krealhelicon, K = 1..N_points—Antenna path points.
Amplituderealyes (DC_current, AC_current)—Current amplitude (A).
Frequency, PhaserealAC_current—Frequency (Hz) and initial phase (degrees).

[external_fields] ​

KeyTypeReq.Accepted / invalidMeaning
external_fields_appliedstringyesnone (no), RMF, uniform_field (UniformField), and the case variants; magnetic_nozzle and rmf_and_magnetic_nozzle are parsed and refused at initialization (no backend implements them); other values are fatalExternal field added to the evolved one.
RMF_frequency, RMF_B_amplituderealRMF—Rotating field frequency (Hz) and amplitude (T).
RMF_rotation_axisstringRMFX, Y, Z (either case); another value leaves the rotation indices undefined, silentlyRotation axis.
Uniform_field_D_amplitude (or Uniform_D_amplitude)realuniform_field—Uniform D amplitude.
Uniform_field_B_amplitude (or Uniform_B_amplitude)realuniform_field—Uniform B amplitude.
Uniform_field_direction (or Uniform_direction)stringuniform_fieldx, y, z (either case); other values are fatalDirection of the uniform field.

For each pair, the first name is read first and the second is the fallback.


[fWLayer] ​

A far-wave damping layer along chosen domain faces.

KeyTypeReq.Accepted / invalidMeaning
widthrealyes (even when no layer is used)>= 0, otherwise fatalPhysical layer width; the cells per face are min(ni, ceiling(width/ds)). 0 disables the layer.
x_minus_layer, x_plus_layer, y_minus_layer, y_plus_layer, z_minus_layer, z_plus_layerstringyesyes, no (case variants); other values are fatalFaces carrying the layer.

The removed key C (cells per face) is rejected by the removed-keys lint.


[PML] ​

A perfectly matched layer, stored on the boundary blocks only. The section is optional: without PML_type the PML is off.

KeyTypeReq.DefaultAccepted / invalidMeaning
PML_typestringnononeno/none, CLASSIC (PML, STANDARD), CLASSIC_DIRECT (DIRECT, CLASSIC-DIRECT), CFS (CPML, CFS_PML), BERMUDEZ, with case variants; other values are fatalPML formulation.
widthrealyes (PML on)0> 0, otherwise fatalPhysical layer width.
C_gamma (or c_gamma)realno0.1> 0, otherwise fatalTime-step cap dt <= C_gamma / gamma_max.
x_minus_layer … z_plus_layerlogicalyes (PML on)—at least one .true., otherwise fatalFaces carrying the PML.
gamma_maxrealCLASSIC, CLASSIC_DIRECT, CFS—>= 0, otherwise fatalMaximum damping.
gamma_exponentrealCLASSIC, CLASSIC_DIRECT, BERMUDEZ—> 0, otherwise fatalExponent of the damping profile.
alfa_maxrealCFS—>= 0, otherwise fatalCFS frequency shift (spelled alfa).
k_maxrealCFS1> 0, otherwise fatalCFS stretching.
betarealBERMUDEZ—>= 0, otherwise fatalBermúdez profile coefficient.

See the PML hazards.


[PIC] (PIC models only) ​

KeyTypeReq.DefaultAccepted / invalidMeaning
problem_typestringyes—plasma, single_particle; another value is accepted silently and injects no particleProblem kind.
plasma_domainstringplasma—uniform (all, full, uniform_domain), cilinder (uniform_cilinder), slab (uniform_slab), box (uniform_box), with case variants; other values are fatalRegion the plasma fills. Note the spelling cilinder.
cilinder_radius, cilinder_length, cilinder_x_center, cilinder_y_center, cilinder_z_centerrealcilinder——Cylinder.
cilinder_axischarcilinder—x, y, z; another value leaves the particle positions undefined, silentlyCylinder axis.
slab_normalstringslab—x, y, z (either case); other values are fatalSlab normal.
slab_thickness, slab_centerrealslab—thickness > 0, otherwise fatalSlab along its normal.
box_length_x, box_length_y, box_length_z, box_x_center, box_y_center, box_z_centerrealbox——Box.
plasma_densityrealplasma——Total density (ions + electrons + neutrals) per unit volume: the particle count is nint(plasma_density × volume / particle_weight) of the plasma region.
particle_weightrealno1> 0, otherwise fatalReal particles per macroparticle: each particle carries particle_weight times the charge and the mass of its species (q/m unchanged).
neutral_fractionrealplasma——Fraction of neutrals; the rest is split evenly into ions and electrons.
initializationstringnocoherentcoherent only; other values are fatalField initialization.
electric_field_elliptic_initializationlogicalno.true.logicalSolve D(G) φ = −ρ/ε at t0 and correct D, so div D = ρ to round-off.
magnetic_field_elliptic_initializationlogicalno.true.logicalSolve D(G) A = −μ J at t0 and add curl A to B, when J ≠ 0 at t0.
elliptic_initialization_closurestringnogroundedgrounded, isolated; other values are fatal. isolated is fatal unless both t0 solves are on, and at t0 unless exactly one axis is non-periodic with PEC faces (the others periodic or null)Mean fields of the t0 solves: grounded zero (the PEC walls at one potential, no trapped flux), isolated those of the same sources in open space along the non-periodic axis (numerics).
elliptic_correctionlogical——.true. is fatal (#84 E3d); the lint rejects the keyRemoved.
particle_weighting_modelstringyes—NGP, CIC, TSC, cubic (3rd), quartic (4th), quintic (5th), sextic (6th), gaussian, with case variants; other values are fatalCharge deposition.
current_weighting_modelstringyes—the same list, plus conserving (charge_conserving); other values are fatalCurrent deposition. conserving needs fd_centered, runge_kutta and SSP-22/33/54 (fatal otherwise).
field_weighting_modelstringyes—0D … 6D, gaussian, londrillo, totorica (esirkepov_Q2), esirkepov_Q5, esirkepov_Q6, esirkepov_Q8, esirkepov_Q10, with case variants; other values are fatalField gather to the particles.
current_conserving_solverstringnolondrillolondrillo, totorica (esirkepov_Q2), esirkepov_Q5/Q6/Q8/Q10; the old names esirkepov, direct/line, esirkepov-modified stop with the new name; other values are fatal. Ignored unless current_weighting_model = conserving.Matched current of the conserving deposit. With periodic faces londrillo stops at the first step (CPU).
esirkepov_tail_cleanuplogicalno.false.logicalTail cleanup of the Esirkepov current; stops at the first step with periodic faces (CPU).
filter_depositionlogicalno.false.logicalFilter the deposited source.
sigma, cutoff_sigmarealcond. (any Gaussian model)—> 0, otherwise fatalGaussian width and cut-off (in widths).
gaussian_support_cellsintnoautomatic—Gaussian support in cells; automatic from the final cell size when absent.
scheme_timestringyes—runge_kutta, leapfrog (case variants); another value warns and falls back to runge_kuttaParticle push. leapfrog is refused at initialization.

The particle closure at the domain faces is not an input key: it follows the field [bc_*] type (periodic faces wrap the particles, every other kind keeps the legacy closure, where a particle leaving the domain stops the run).


[particle_injection] (PIC models only) ​

For problem_type = plasma:

KeyTypeReq.DefaultAccepted / invalidMeaning
random_seedintnoprocessor-dependentanyFixed seed, for a reproducible plasma.
space_random_number_generatorstringyes—random, layered (case variants); other values are fatalPosition sampling.
space_pairingstringyes—yes, no; other values are fatalElectrons placed on the ions' positions.
ions_velocity_distribution, electrons_velocity_distribution, neutrals_velocity_distributionstringyes—uniform_maxwellian (maxwellian, uniform), non_uniform_maxwellian, drift (pure_drift), with case variants; other values are fatalVelocity distribution per species.
ionic_temperature, electronic_temperature, neutrals_temperaturerealcond. (that species uniform_maxwellian)——Temperature (K).
ionic_temperature_x/_y/_z, electronic_temperature_x/_y/_z, neutrals_temperature_x/_y/_zrealcond. (that species non_uniform_maxwellian)——Temperature per axis (K).
velocity_random_number_generatorstringcond. (any Maxwellian species)—random, layered; other values are fatalVelocity sampling.
velocity_pairingstringcond. (any Maxwellian species)—yes, no; other values are fatal. yes needs the same distribution, temperatures and drifts for ions and electrons (fatal otherwise).Electrons take the ions' velocities.
ions_drift_x/_y/_z, electrons_drift_x/_y/_z, neutrals_drift_x/_y/_zrealyes——Drift velocity per species (m/s).
v_av_correctionstringyes—yes, no; other values are fatalRemove the sampled mean velocity.

For problem_type = single_particle: x_position, y_position, z_position, charge, mass, v_drift_x, v_drift_y, v_drift_z, all real and required.


[leapfrog] (PIC leapfrog only) ​

is_filtered (logical), nu, alpha (real), all required, read only with [PIC] scheme_time = leapfrog, which is then refused at initialization: the section has no working use.


Diagnostics ​

[grms] ​

KeyTypeReq.DefaultAccepted / invalidMeaning
save_historylogicalno.false.logicalWrite the RMS-field history.
history_saveintno10—Its cadence in steps.
region_typestringnoallall, cylinder; other values are fatalRegion of the RMS.
center_x, center_y, center_z, axis_x, axis_y, axis_z, radius, lengthrealcylinder—axis non-zero, radius and length > 0, otherwise fatalCylinder (the axis is normalised).

[magnetic_field_at_center_domain] ​

KeyTypeReq.DefaultMeaning
save_historylogicalno.false.Write the history of B at the domain centre.
history_saveintno10Its cadence in steps.

[probes] ​

Optional: without a [probes] section, or with neither point_N nor plane_N keys, there are no probes. Each probe samples the whole state at a point by trilinear interpolation.

ini
[probes]
save_every = 4
point_1 = -0.04 0.0 0.0       ; one probe at x y z
plane_1 = x 0.4364 48 48      ; a plane of probes normal to x at x = 0.4364: 48 x 48 points over y and z
KeyTypeReq.Accepted / invalidMeaning
save_everyintyes (probes on)> 0, otherwise fatalCadence in steps; the last step is always saved.
point_N3 realsnoinside the domain, otherwise fatalA probe at x y z.
plane_Naxis, real, 2 intsnoaxis x/y/z, abscissa inside the domain, n1 n2 >= 1, otherwise fatalA plane of n1 x n2 probes normal to the axis at the abscissa, on the cell centres of a uniform lattice spanning the domain along the other two axes (normal x: y then z; y: x then z; z: x then y). With n equal to the cells of the grid along an axis the probes sit on the cell centres.

Coordinates are in the grid's units (divided by L0 non-dimensional). point_N and plane_N are numbered from 1 without gaps: the first missing number ends the list. The former input, probes_number and one [probe_N] section (x, y, z) per probe, is refused at initialization: write each former probe as a point_N, or a full lattice of them as one plane_N.

Output (rank 0): <output_basename>-probe_NN.dat per point (one row per save: it time and the variables) and <output_basename>-plane_NN.dat per plane (per save, n1 x n2 rows it time i j and the variables, i fastest). The rows are not flushed at every save (a flush per file is a file-system round trip; on a shared file system it stalled every rank for seconds): they reach the files when the runtime buffers fill and at the end of the run, so after a crash the last rows may be missing.


Hazards ​

Divergence correction ​

The GLM scalars φ (for D) and ψ (for B) exist only under hyperbolic, and their slots follow physics (#11, #61):

constrained_transportdivergence_correctionResult
nononv = 9
D, B, DBnoconstrained transport ignored with a warning, nv = 9
D or Bhyperbolicnv = 10 (φ or ψ in slot 7)
DBhyperbolicnv = 11 (φ in 7, ψ in 8)
nohyperbolicrefused at initialization
anypoissonrefused at initialization

PIC adds rho, one more slot. At a 2:1 AMR seam div(B) is not kept at round-off: the seam injects an O(h^p) source that converges under refinement but grows in time at fixed h (#29); [IO] seam_divB_tol makes the growth visible.

PML ​

  • CPU: CLASSIC, CLASSIC_DIRECT, BERMUDEZ, CFS, on fd_centered, with no divergence correction and no constrained transport, with an SSP Runge-Kutta scheme; anything else is fatal.
  • FNL: fd_centered, runge_kutta with an SSP scheme, no hyperbolic correction, no constrained transport; anything else is fatal.
  • CLASSIC_DIRECT is not a Runge-Kutta PML: it skips the auxiliary-variable integration and applies direct per-face damping. It is a testing instrument, not the production path.
  • Enabling the section with every face flag .false. is fatal; each PML_type has its own required parameters, and a missing one is fatal, not defaulted.

Elliptic boundary map ​

The t0 solves ([PIC] electric_field_elliptic_initialization, magnetic_field_elliptic_initialization) run on FLAIL's FFT solver with PRISM's own operator D(G) of order fdv_order. Each face kind maps to an elliptic kind, then to a FLAIL face kind:

[bc_*] typeElliptic kindFLAIL face kind
periodicperiodicFLAIL_BC_PERIODIC
DirichletDirichletFLAIL_BC_ZERO_GHOSTS (every ghost layer zero)
PECPECFLAIL_BC_DIRICHLET (φ, tangential A), FLAIL_BC_NEUMANN (normal A)
Neumann, Silver_Mullerexact/openFLAIL_BC_FREE_GHOSTS (the free-space potential of the source in the ghosts, summed over the whole domain)
extrapolation—fatal, at the first t0 solve

The map is total and stops on what it cannot map, but only when a solve first touches the face: an input with an extrapolation face passes initialization and stops at t0 if a PIC field or a t0 current needs a solve. A null axis takes the periodic kind.

Refused combinations ​

InputWhere it stops
[numerics] scheme_time = leapfrog, blanes_moan, commutator_free_magnusinitialization, both backends (#55)
[PIC] scheme_time = leapfroginitialization, both backends
[numerics] divergence_correction = poissonload
hyperbolic without constrained transportload
[bc_*] type = radiativeload (#57)
[initial_conditions] type = riemann-problem, magnetic_nozzle, rmf_magnetic_nozzleload (#56)
[external_fields] external_fields_applied = magnetic_nozzle, rmf_and_magnetic_nozzleinitialization
[numerics] scheme_space = weno on FNLinitialization
runge-kutta-yoshida on FNL; a non-SSP scheme with PIC, the PML or the staged pathinitialization
[PIC] current_weighting_model = conserving on the CPU backend with more than one block or one rankthe first step (the CPU charge-conserving deposit is single-block, single-rank)
A refined grid that enters a t0 elliptic solvethe solve (#84 E7: the wide operator across 2:1 faces is not defined)
fdv_order = 10 with a t0 elliptic solvethe solve (FLAIL accepts 2, 4, 6, 8)