entity.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://entity-toolkit.github.io/schema/entity.schema.json",
  "title": "entity",
  "description": "Entity simulation input file",
  "$comment": "GENERATOR CONVENTION -- this schema is the single source of truth for `input.template.toml`. Standard keywords carry the machine-checkable part (type/enum/minimum/maximum/items/prefixItems/minItems/maxItems/pattern/default/required/deprecated). The `x-entity` object carries the parts JSON Schema cannot express, all verbatim from the template comments: `type` = the literal `@type:` annotation (use it for the comment line whenever present, else derive from the standard keywords); `default` = the literal `@default:` annotation (use it whenever present, else format the standard `default`); `notes` = ordered `@note:` lines; `examples` = ordered `@example:` lines; `enum` = an illustrative, NON-exhaustive value list that must not be validated as a real `enum`; `deprecated` = the `@deprecated:` text. `x-entity.inferred` on an object lists quantities the code derives rather than reads; they are NOT valid input keys (so they are absent from `properties` and rejected by `additionalProperties: false`) and should be emitted as an `@inferred:` comment block after that table's own keys and before its sub-tables. Property order in `properties` is the emission order. Objects with `additionalProperties: true` are free-form. `$ref` is used once, for `$defs/colormap`.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "simulation",
    "grid",
    "scales",
    "particles"
  ],
  "$defs": {
    "colormap": {
      "type": "string",
      "pattern": "(?i)^(cmr\\.)?(viridis|inferno|plasma|cool2warm|gray|RdBu_r|dusk|cosmic|freeze|apple|gothic|sunburst|voltage|ocean|fusion|prinsenvlag)$",
      "x-entity": {
        "type": "string",
        "enum": [
          "viridis",
          "inferno",
          "plasma",
          "cool2warm",
          "gray",
          "RdBu_r",
          "and the CMasher maps (BSD-3, https://cmasher.readthedocs.io): \"dusk\", \"cosmic\", \"freeze\", \"apple\", \"gothic\", \"sunburst\", \"voltage\", \"ocean\", \"fusion\", \"prinsenvlag\" (an optional \"cmr.\" prefix is ok)"
        ]
      }
    }
  },
  "properties": {
    "simulation": {
      "description": "Global simulation parameters",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "engine",
        "runtime"
      ],
      "properties": {
        "name": {
          "description": "Name of the simulation",
          "type": "string",
          "x-entity": {
            "type": "string",
            "notes": [
              "The name is used for the output files"
            ]
          }
        },
        "engine": {
          "description": "Simulation engine to use",
          "anyOf": [
            {
              "enum": [
                "SRPIC",
                "GRPIC"
              ]
            },
            {
              "type": "string",
              "pattern": "(?i)^(SRPIC|GRPIC)$"
            }
          ],
          "x-entity": {
            "type": "string"
          }
        },
        "runtime": {
          "description": "Max runtime in physical (code) units",
          "type": "number",
          "exclusiveMinimum": 0.0,
          "x-entity": {
            "type": "float [> 0]",
            "examples": [
              "1e5"
            ]
          }
        },
        "domain": {
          "description": "Parameters specific to domain decomposition",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "number": {
              "description": "Number of domains",
              "type": "integer",
              "minimum": 1,
              "x-entity": {
                "type": "int",
                "default": "1 [no MPI]; MPI_SIZE [MPI]"
              }
            },
            "decomposition": {
              "description": "Decomposition of the domain (for MPI) in each of the directions",
              "type": "array",
              "minItems": 1,
              "maxItems": 3,
              "items": {
                "type": "integer"
              },
              "default": [
                -1,
                -1,
                -1
              ],
              "x-entity": {
                "type": "array<int> [size 1 :->: 3]",
                "notes": [
                  "-1 means the code will determine the decomposition in the specific direction automatically",
                  "Automatic detection is either done by inference from # of MPI tasks, or by balancing the grid size on each domain"
                ],
                "examples": [
                  "[2, 2, 2] (total of 8 domains)"
                ]
              }
            },
            "load_balance": {
              "description": "Diffusion-style dynamic load balancing. Domain boundaries between MPI neighbors are nudged to equalize the active-particle count per rank. All inter-rank traffic uses only the existing nearest-neighbor field/particle communication paths.",
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "enable": {
                  "description": "Enable dynamic load balancing",
                  "type": "boolean",
                  "default": false,
                  "x-entity": {
                    "type": "bool"
                  }
                },
                "interval": {
                  "description": "Run the rebalancer every `interval` timesteps (0 disables)",
                  "type": "integer",
                  "minimum": 0,
                  "default": 0,
                  "x-entity": {
                    "type": "int"
                  }
                },
                "dimensions": {
                  "description": "Dimensions along which load is redistributed (1 = x1, 2 = x2, 3 = x3)",
                  "type": "array",
                  "minItems": 1,
                  "maxItems": 3,
                  "uniqueItems": true,
                  "items": {
                    "type": "integer",
                    "enum": [
                      1,
                      2,
                      3
                    ]
                  },
                  "default": [
                    1
                  ],
                  "x-entity": {
                    "type": "array<int> [subset of {1, 2, 3}]"
                  }
                },
                "tolerance": {
                  "description": "Skip rebalancing along a dim when (max - min) / mean of the per-slice particle count is below this fraction",
                  "type": "number",
                  "minimum": 0.0,
                  "default": 0.1,
                  "x-entity": {
                    "type": "float"
                  }
                },
                "max_shift": {
                  "description": "Maximum cell-shift per interior boundary per event; clamped at compile time to N_GHOSTS so the migrating field strip is already cached in the rank's ghost zone.",
                  "type": "integer",
                  "minimum": 0,
                  "x-entity": {
                    "type": "int",
                    "default": "N_GHOSTS"
                  }
                }
              }
            }
          }
        }
      }
    },
    "grid": {
      "description": "Parameters specific to grid geometry",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "resolution",
        "extent",
        "metric",
        "boundaries"
      ],
      "x-entity": {
        "inferred": [
          {
            "name": "dim",
            "brief": "Dimensionality of the grid",
            "type": "short",
            "enum": [
              1,
              2,
              3
            ],
            "from": "`grid.resolution`"
          }
        ]
      },
      "properties": {
        "resolution": {
          "description": "Spatial resolution of the grid",
          "type": "array",
          "minItems": 1,
          "maxItems": 3,
          "items": {
            "type": "integer",
            "minimum": 1
          },
          "x-entity": {
            "type": "array<uint> [size 1 :->: 3]",
            "notes": [
              "Dimensionality is inferred from the size of this array"
            ],
            "examples": [
              "[1024, 1024, 1024]"
            ]
          }
        },
        "extent": {
          "description": "Physical extent of the grid",
          "type": "array",
          "minItems": 1,
          "maxItems": 3,
          "items": {
            "type": "array",
            "minItems": 2,
            "maxItems": 2,
            "prefixItems": [
              {
                "type": "number"
              },
              {
                "type": "number"
              }
            ]
          },
          "x-entity": {
            "type": "array<tuple<float>> [size 1 :->: 3]",
            "notes": [
              "For spherical geometry, only specify `[[rmin, rmax]]`, other values are set automatically",
              "For cartesian geometry, cell aspect ratio has to be 1: `dx=dy=dz`"
            ],
            "examples": [
              "[[0.0, 1.0], [-1.0, 1.0]]"
            ]
          }
        },
        "metric": {
          "description": "Metric-related parameters",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "metric"
          ],
          "x-entity": {
            "inferred": [
              {
                "name": "coord",
                "brief": "Coordinate system on the grid",
                "type": "string",
                "enum": [
                  "cartesian",
                  "spherical",
                  "qspherical"
                ],
                "from": "`grid.metric.metric`"
              },
              {
                "name": "ks_rh",
                "brief": "Size of the horizon for GR Kerr Schild",
                "type": "float",
                "from": "`grid.metric.ks_a`"
              },
              {
                "name": "params",
                "brief": "A map of all metric-specific parameters together (for easy access)",
                "type": "map<string, float>",
                "from": "`grid.metric`"
              }
            ]
          },
          "properties": {
            "metric": {
              "description": "Metric on the grid",
              "anyOf": [
                {
                  "enum": [
                    "Minkowski",
                    "Spherical",
                    "QSpherical",
                    "Kerr_Schild",
                    "QKerr_Schild",
                    "Kerr_Schild_0"
                  ]
                },
                {
                  "type": "string",
                  "pattern": "(?i)^(Minkowski|Spherical|QSpherical|Kerr_Schild|QKerr_Schild|Kerr_Schild_0)$"
                }
              ],
              "x-entity": {
                "type": "string"
              }
            },
            "qsph_r0": {
              "description": "`r0` paramter for the QSpherical metric `x1 = log(r-r0)`",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float [-inf -> rmin]",
                "notes": [
                  "Negative values produce almost uniform grid in r"
                ]
              }
            },
            "qsph_h": {
              "description": "`h` paramter for the QSpherical metric `th = x2 + 2*h x2 (pi-2*x2)*(pi-x2)/pi^2`",
              "type": "number",
              "minimum": -1.0,
              "maximum": 1.0,
              "default": 0.0,
              "x-entity": {
                "type": "float [-1 :->: 1]"
              }
            },
            "ks_a": {
              "description": "Spin parameter for the Kerr Schild metric",
              "type": "number",
              "minimum": 0.0,
              "maximum": 1.0,
              "default": 0.0,
              "x-entity": {
                "type": "float [0 :-> 1]"
              }
            }
          }
        },
        "boundaries": {
          "description": "Boundary-condition related parameters",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "fields",
            "particles"
          ],
          "properties": {
            "fields": {
              "description": "Boundary conditions for fields",
              "type": "array",
              "minItems": 1,
              "maxItems": 3,
              "items": {
                "type": "array",
                "minItems": 1,
                "maxItems": 2,
                "items": {
                  "anyOf": [
                    {
                      "enum": [
                        "PERIODIC",
                        "MATCH",
                        "FIXED",
                        "ATMOSPHERE",
                        "CUSTOM",
                        "HORIZON",
                        "CONDUCTOR"
                      ]
                    },
                    {
                      "type": "string",
                      "pattern": "(?i)^(PERIODIC|MATCH|FIXED|ATMOSPHERE|CUSTOM|HORIZON|CONDUCTOR)$"
                    }
                  ]
                }
              },
              "x-entity": {
                "type": "array<tuple<string>> [size 1 :->: 3]",
                "notes": [
                  "When periodic in any of the directions, you should only set one value: [..., [\"PERIODIC\"], ...]",
                  "In spherical, bondaries in theta/phi are set automatically (only specify bc @ `[rmin, rmax]`): [[\"ATMOSPHERE\", \"MATCH\"]]",
                  "In GR, the horizon boundary is set automatically (only specify bc @ rmax): [[\"MATCH\"]]"
                ],
                "examples": [
                  "[[\"CUSTOM\", \"MATCH\"]] (for 2D spherical `[[rmin, rmax]]`)"
                ]
              }
            },
            "particles": {
              "description": "Boundary conditions for particles",
              "type": "array",
              "minItems": 1,
              "maxItems": 3,
              "items": {
                "type": "array",
                "minItems": 1,
                "maxItems": 2,
                "items": {
                  "anyOf": [
                    {
                      "enum": [
                        "PERIODIC",
                        "ABSORB",
                        "ATMOSPHERE",
                        "CUSTOM",
                        "REFLECT",
                        "HORIZON"
                      ]
                    },
                    {
                      "type": "string",
                      "pattern": "(?i)^(PERIODIC|ABSORB|ATMOSPHERE|CUSTOM|REFLECT|HORIZON)$"
                    }
                  ]
                }
              },
              "x-entity": {
                "type": "array<tuple<string>> [size 1 :->: 3]",
                "notes": [
                  "When periodic in any of the directions, you should only set one value [..., [\"PERIODIC\"], ...]",
                  "In spherical, bondaries in theta/phi are set automatically (only specify bc @ `[rmin, rmax]`) [[\"ATMOSPHERE\", \"ABSORB\"]]",
                  "In GR, the horizon boundary is set automatically (only specify bc @ `rmax`): [[\"ABSORB\"]]"
                ],
                "examples": [
                  "[[\"PERIODIC\"], [\"PERIODIC\"]]"
                ]
              }
            },
            "match": {
              "description": "Parameters specific to MATCH boundary conditions",
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "ds": {
                  "description": "Size of the matching layer in each direction for fields in physical (code) units",
                  "anyOf": [
                    {
                      "type": "number",
                      "exclusiveMinimum": 0.0
                    },
                    {
                      "type": "array",
                      "minItems": 1,
                      "maxItems": 3,
                      "items": {
                        "type": "array",
                        "maxItems": 2,
                        "items": {
                          "type": "number"
                        }
                      }
                    }
                  ],
                  "x-entity": {
                    "type": "float | array<tuple<float>>",
                    "default": "1% of the domain size (in shortest dimension)",
                    "notes": [
                      "In spherical, this is the size of the layer in `r` from the outer wall"
                    ],
                    "examples": [
                      "`ds = 1.5` (will set the same for all directions)",
                      "`ds = [[1.5], [2.0, 1.0], [1.1]]` (will duplicate 1.5 for +/- `x1` and 1.1 for +/- `x3`)",
                      "`ds = [[], [1.5], []]` (will only set for x2)"
                    ]
                  }
                }
              }
            },
            "absorb": {
              "description": "Parameters specific to ABSORB boundary conditions",
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "ds": {
                  "description": "Size of the absorption layer for particles in physical (code) units",
                  "type": "number",
                  "exclusiveMinimum": 0.0,
                  "x-entity": {
                    "type": "float",
                    "default": "1% of the domain size (in shortest dimension)",
                    "notes": [
                      "In spherical, this is the size of the layer in `r` from the outer wall",
                      "In cartesian, this is the same for all dimensions where applicable"
                    ]
                  }
                }
              }
            },
            "atmosphere": {
              "description": "Parameters specific to ATMOSPHERE boundary conditions",
              "type": "object",
              "additionalProperties": false,
              "x-entity": {
                "inferred": [
                  {
                    "name": "g",
                    "brief": "Acceleration due to imposed gravity",
                    "type": "float",
                    "from": "`grid.boundaries.atmosphere.temperature`, `grid.boundaries.atmosphere.height`",
                    "value": "`temperature / height`"
                  }
                ]
              },
              "properties": {
                "temperature": {
                  "description": "Temperature of the atmosphere in units of `m0 c^2`",
                  "type": "number",
                  "minimum": 0.0,
                  "x-entity": {
                    "type": "float",
                    "notes": [
                      "[required] if `ATMOSPHERE` is one of the boundaries"
                    ]
                  }
                },
                "density": {
                  "description": "Peak number density of the atmosphere at base in units of `n0`",
                  "type": "number",
                  "minimum": 0.0,
                  "x-entity": {
                    "type": "float"
                  }
                },
                "height": {
                  "description": "Pressure scale-height in physical units",
                  "type": "number",
                  "exclusiveMinimum": 0.0,
                  "x-entity": {
                    "type": "float"
                  }
                },
                "species": {
                  "description": "Species indices of particles that populate the atmosphere",
                  "type": "array",
                  "minItems": 2,
                  "maxItems": 2,
                  "prefixItems": [
                    {
                      "type": "integer",
                      "minimum": 1
                    },
                    {
                      "type": "integer",
                      "minimum": 1
                    }
                  ],
                  "x-entity": {
                    "type": "array<int> [size 2]"
                  }
                },
                "ds": {
                  "description": "Distance from the edge to which the gravity is imposed in physical units",
                  "type": "number",
                  "minimum": 0.0,
                  "default": 0.0,
                  "x-entity": {
                    "type": "float",
                    "notes": [
                      "0.0 means no limit"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "scales": {
      "description": "Fiducial scales that fix the code unit system",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "larmor0",
        "skindepth0"
      ],
      "x-entity": {
        "inferred": [
          {
            "name": "dx0",
            "brief": "fiducial minimum size of the cell",
            "type": "float",
            "from": "`grid`"
          },
          {
            "name": "V0",
            "brief": "fiducial elementary volume",
            "type": "float",
            "from": "`grid`"
          },
          {
            "name": "n0",
            "brief": "Fiducial number density",
            "type": "float",
            "from": "`particles.ppc0`, `grid`",
            "value": "`ppc0 / V0`"
          },
          {
            "name": "q0",
            "brief": "Fiducial elementary charge",
            "type": "float",
            "from": "`scales.skindepth0`, `scales.n0`",
            "value": "`1 / (n0 * skindepth0^2)`"
          },
          {
            "name": "sigma0",
            "brief": "Fiducial magnetization parameter",
            "type": "float",
            "from": "`scales.larmor0`, `scales.skindepth0`",
            "value": "`(skindepth0 / larmor0)^2`"
          },
          {
            "name": "B0",
            "brief": "Fiducial magnetic field",
            "type": "float",
            "from": "`scales.larmor0`",
            "value": "`1 / larmor0`"
          },
          {
            "name": "omegaB0",
            "brief": "Fiducial cyclotron frequency",
            "type": "float",
            "from": "`scales.larmor0`",
            "value": "`1 / larmor0`"
          }
        ]
      },
      "properties": {
        "larmor0": {
          "description": "Fiducial larmor radius",
          "type": "number",
          "exclusiveMinimum": 0.0,
          "x-entity": {
            "type": "float [> 0.0]"
          }
        },
        "skindepth0": {
          "description": "Fiducial plasma skin depth",
          "type": "number",
          "exclusiveMinimum": 0.0,
          "x-entity": {
            "type": "float [> 0.0]"
          }
        }
      }
    },
    "radiation": {
      "description": "Radiative drag and photon emission parameters",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "drag": {
          "description": "Radiation reaction (drag) parameters",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "synchrotron": {
              "description": "Synchrotron drag parameters",
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "gamma_rad": {
                  "description": "Radiation reaction limit gamma-factor for synchrotron",
                  "type": "number",
                  "exclusiveMinimum": 0.0,
                  "default": 1.0,
                  "x-entity": {
                    "type": "float [> 0.0]",
                    "notes": [
                      "[required] if one of the species has `radiative_drag = \"synchrotron\"`"
                    ]
                  }
                }
              }
            },
            "compton": {
              "description": "Compton drag parameters",
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "gamma_rad": {
                  "description": "Radiation reaction limit gamma-factor for Compton drag",
                  "type": "number",
                  "exclusiveMinimum": 0.0,
                  "default": 1.0,
                  "x-entity": {
                    "type": "float [> 0.0]",
                    "notes": [
                      "[required] if one of the species has `radiative_drag = \"compton\"`"
                    ]
                  }
                }
              }
            }
          }
        },
        "emission": {
          "description": "Photon emission parameters",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "synchrotron": {
              "description": "Synchrotron emission parameters",
              "type": "object",
              "additionalProperties": false,
              "required": [
                "photon_species"
              ],
              "x-entity": {
                "inferred": [
                  {
                    "name": "nominal_probability",
                    "brief": "Nominal probability of the emission for a particle with `gamma * beta = 1`, charge-to-mass = `q0 / m0`",
                    "type": "float",
                    "from": "`.gamma_qed`, `.photon_weight`, `...drag.synchrotron.gamma_rad`, `scales.omegaB0`, `algorithms.timestep.dt`",
                    "value": "`0.1 * omegaB0 * dt * (gamma_qed / gamma_rad)^2 / photon_weight`"
                  },
                  {
                    "name": "nominal_photon_energy",
                    "brief": "Nominal energy of the emitted photon for a particle with `gamma * beta = 1`, mass = `m0`",
                    "type": "float",
                    "from": "`.gamma_qed`",
                    "value": "`(1 / gamma_qed)^2`"
                  }
                ]
              },
              "properties": {
                "gamma_qed": {
                  "description": "Gamma-factor of a particle emitting synchrotron photons at energy `m0 c^2` in fiducial magnetic field `B0`",
                  "type": "number",
                  "exclusiveMinimum": 1.0,
                  "default": 10.0,
                  "x-entity": {
                    "type": "float [> 1.0]"
                  }
                },
                "photon_energy_min": {
                  "description": "Minimum photon energy for synchrotron emission (units of `m0 c^2`)",
                  "type": "number",
                  "exclusiveMinimum": 0.0,
                  "default": 0.001,
                  "x-entity": {
                    "type": "float [> 0.0]",
                    "default": "1e-3"
                  }
                },
                "photon_weight": {
                  "description": "Weights for the emitted synchrotron photons",
                  "type": "number",
                  "exclusiveMinimum": 0.0,
                  "default": 1.0,
                  "x-entity": {
                    "type": "float [> 0.0]"
                  }
                },
                "photon_species": {
                  "description": "Index of species for the emitted photon",
                  "type": "integer",
                  "minimum": 1,
                  "x-entity": {
                    "type": "ushort [> 0]"
                  }
                }
              }
            },
            "compton": {
              "description": "Inverse Compton emission parameters",
              "type": "object",
              "additionalProperties": false,
              "required": [
                "photon_species"
              ],
              "x-entity": {
                "inferred": [
                  {
                    "name": "nominal_probability",
                    "brief": "Nominal probability of the emission for a particle with `gamma * beta = 1`, charge-to-mass = `q0 / m0`",
                    "type": "float",
                    "from": "`.gamma_qed`, `.photon_weight`, `...drag.compton.gamma_rad`, `scales.omegaB0`, `algorithms.timestep.dt`",
                    "value": "`0.1 * omegaB0 * dt * (gamma_qed / gamma_rad)^2 / photon_weight`"
                  },
                  {
                    "name": "nominal_photon_energy",
                    "brief": "Nominal energy of the emitted photon for a particle with `gamma * beta = 1`, mass = `m0`",
                    "type": "float",
                    "from": "`.gamma_qed`",
                    "value": "`(1 / gamma_qed)^2`"
                  }
                ]
              },
              "properties": {
                "gamma_qed": {
                  "description": "Gamma-factor of a particle emitting inverse Compton photons at energy `m0 c^2` in fiducial magnetic field `B0`",
                  "type": "number",
                  "exclusiveMinimum": 1.0,
                  "default": 10.0,
                  "x-entity": {
                    "type": "float [> 1.0]"
                  }
                },
                "photon_energy_min": {
                  "description": "Minimum photon energy for inverse Compton emission (units of `m0 c^2`)",
                  "type": "number",
                  "exclusiveMinimum": 0.0,
                  "default": 0.001,
                  "x-entity": {
                    "type": "float [> 0.0]",
                    "default": "1e-3"
                  }
                },
                "photon_weight": {
                  "description": "Weights for the emitted inverse Compton photons",
                  "type": "number",
                  "exclusiveMinimum": 0.0,
                  "default": 1.0,
                  "x-entity": {
                    "type": "float [> 0.0]"
                  }
                },
                "photon_species": {
                  "description": "Index of species for the emitted photon",
                  "type": "integer",
                  "minimum": 1,
                  "x-entity": {
                    "type": "ushort [> 0]"
                  }
                }
              }
            }
          }
        }
      }
    },
    "algorithms": {
      "description": "Algorithm and solver tuning",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "current_filters": {
          "description": "Number of current smoothing passes",
          "type": "integer",
          "minimum": 0,
          "default": 0,
          "x-entity": {
            "type": "ushort [>= 0]"
          }
        },
        "timestep": {
          "description": "Timestep parameters",
          "type": "object",
          "additionalProperties": false,
          "x-entity": {
            "inferred": [
              {
                "name": "dt",
                "brief": "timestep duration",
                "type": "float",
                "from": "`algorithms.timestep.CFL`, `scales.dx0`",
                "value": "`CFL * dx0`"
              }
            ]
          },
          "properties": {
            "CFL": {
              "description": "Courant-Friedrichs-Lewy number",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "maximum": 1.0,
              "default": 0.95,
              "x-entity": {
                "type": "float [0.0 -> 1.0]",
                "notes": [
                  "CFL number determines the timestep duration"
                ]
              }
            },
            "correction": {
              "description": "Correction factor for the speed of light used in field solver",
              "type": "number",
              "default": 1.0,
              "x-entity": {
                "type": "float"
              }
            }
          }
        },
        "deposit": {
          "description": "Current deposition parameters",
          "type": "object",
          "additionalProperties": false,
          "x-entity": {
            "inferred": [
              {
                "name": "order",
                "brief": "order of the particle shape function",
                "type": "ushort [0 -> 10]",
                "from": "compile-time definition `shape_order`"
              }
            ]
          },
          "properties": {
            "enable": {
              "description": "Enable the current deposition",
              "type": "boolean",
              "default": true,
              "x-entity": {
                "type": "bool"
              }
            },
            "team_policy_team_size": {
              "description": "Tiled-deposit work-group (team) size",
              "type": "integer",
              "minimum": 0,
              "default": 0,
              "deprecated": true,
              "x-entity": {
                "type": "uint [>= 0]",
                "deprecated": "removed in 1.6+, use `tiled_deposit_team_size` instead"
              }
            },
            "tiled_deposit_team_size": {
              "description": "Tiled-deposit work-group (team) size",
              "type": "integer",
              "minimum": 0,
              "default": 0,
              "x-entity": {
                "type": "uint [>= 0]",
                "notes": [
                  "0 keeps Kokkos::AUTO (backend occupancy heuristic); a positive value overrides it, clamped to the backend/scratch maximum at launch. Only used in `tiled_deposit=ON` builds. Pick a multiple of the device subgroup width for best occupancy (see ideal_tile_size.py)"
                ]
              }
            }
          }
        },
        "gr": {
          "description": "GR pusher parameters",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "pusher_eps": {
              "description": "Stepsize for numerical differentiation in GR pusher",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "default": 1e-06,
              "x-entity": {
                "type": "float [> 0.0]",
                "default": "1e-6"
              }
            },
            "pusher_niter": {
              "description": "Number of iterations for the Newton-Raphson method in GR pusher",
              "type": "integer",
              "minimum": 1,
              "default": 10,
              "x-entity": {
                "type": "ushort [> 0]"
              }
            }
          }
        },
        "gca": {
          "description": "Guiding-center approximation parameters",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "e_ovr_b_max": {
              "description": "Maximum value for E/B allowed for GCA particles",
              "type": "number",
              "minimum": 0.0,
              "maximum": 1.0,
              "default": 0.9,
              "x-entity": {
                "type": "float [0.0 -> 1.0]"
              }
            },
            "larmor_max": {
              "description": "Maximum Larmor radius allowed for GCA particles (in physical units)",
              "type": "number",
              "minimum": 0.0,
              "default": 0.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "When `larmor_max` == 0, the limit is disabled"
                ]
              }
            }
          }
        },
        "fieldsolver": {
          "description": "Stencil coefficients for the field solver [notation as in Blinne+ (2018)]",
          "type": "object",
          "additionalProperties": false,
          "x-entity": {
            "notes": [
              "Standard Yee solver: `delta_i = beta_ij = 0.0`"
            ]
          },
          "properties": {
            "enable": {
              "description": "Enable the fieldsolver",
              "type": "boolean",
              "default": true,
              "x-entity": {
                "type": "bool"
              }
            },
            "delta_x": {
              "description": "delta_x coefficient (for `F_{i +/- 3/2, j, k}`)",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float"
              }
            },
            "delta_y": {
              "description": "delta_y coefficient (for `F_{i, j +/- 3/2, k}`)",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "Used only for 2D and 3D"
                ]
              }
            },
            "delta_z": {
              "description": "delta_z coefficient (for `F_{i, j, k +/- 3/2}`)",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "Used only for 3D"
                ]
              }
            },
            "beta_xy": {
              "description": "beta_xy coefficient (for `F_{i +/- 1/2, j +/- 1, k}`)",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "Used only for 2D and 3D"
                ]
              }
            },
            "beta_yx": {
              "description": "beta_yx coefficient (for `F_{i +/- 1, j +/- 1/2, k}`)",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "Used only for 2D and 3D"
                ]
              }
            },
            "beta_xz": {
              "description": "beta_xz coefficient (for `F_{i +/- 1/2, j, k +/- 1}`)",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "Used only for 3D"
                ]
              }
            },
            "beta_zx": {
              "description": "beta_zx coefficient (for `F_{i +/- 1, j, k +/- 1/2}`)",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "Used only for 3D"
                ]
              }
            },
            "beta_yz": {
              "description": "beta_yz coefficient (for `F_{i, j +/- 1/2, k +/- 1}`)",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "Used only for 3D"
                ]
              }
            },
            "beta_zy": {
              "description": "beta_zy coefficient (for `F_{i, j +/- 1, k +/- 1/2}`)",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "Used only for 3D"
                ]
              }
            }
          }
        }
      }
    },
    "particles": {
      "description": "Particle and species parameters",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "ppc0"
      ],
      "x-entity": {
        "inferred": [
          {
            "name": "nspec",
            "brief": "Number of particle species",
            "type": "uint",
            "from": "`particles.species`"
          }
        ]
      },
      "properties": {
        "ppc0": {
          "description": "Fiducial number of particles per cell",
          "type": "number",
          "exclusiveMinimum": 0.0,
          "x-entity": {
            "type": "float [> 0.0]"
          }
        },
        "use_weights": {
          "description": "Toggle for using particle weights",
          "type": "boolean",
          "default": false,
          "x-entity": {
            "type": "bool"
          }
        },
        "clear_interval": {
          "description": "Timesteps between particle re-sorting by tags (removing dead particles)",
          "type": "integer",
          "minimum": 0,
          "default": 100,
          "x-entity": {
            "type": "uint",
            "notes": [
              "Set to 0 to disable re-sorting"
            ]
          }
        },
        "spatial_sorting_interval": {
          "description": "Timesteps between spatial sorting of particles (for better cache performance)",
          "type": "integer",
          "minimum": 0,
          "default": 0,
          "x-entity": {
            "type": "uint",
            "notes": [
              "Set to 0 to disable spatial sorting"
            ]
          }
        },
        "species": {
          "description": "Particle species definitions",
          "type": "array",
          "minItems": 1,
          "x-entity": {
            "array_of_tables": true
          },
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "mass",
              "charge",
              "maxnpart"
            ],
            "properties": {
              "label": {
                "description": "Label of the species",
                "type": "string",
                "x-entity": {
                  "type": "string",
                  "default": "\"s<INDEX>\"",
                  "notes": [
                    "`<INDEX>` is the index of the species in the list starting from 1"
                  ],
                  "examples": [
                    "\"e-\""
                  ]
                }
              },
              "mass": {
                "description": "Mass of the species (in units of fiducial mass)",
                "type": "number",
                "minimum": 0.0,
                "x-entity": {
                  "type": "float [>= 0.0]"
                }
              },
              "charge": {
                "description": "Charge of the species (in units of fiducial charge)",
                "type": "number",
                "x-entity": {
                  "type": "float"
                }
              },
              "maxnpart": {
                "description": "Maximum number of particles per task",
                "type": "number",
                "x-entity": {
                  "type": "uint [> 0]",
                  "notes": [
                    "Read as a float, so exponential notation is fine (e.g. `1e8`)"
                  ]
                },
                "exclusiveMinimum": 0
              },
              "pusher": {
                "description": "Pusher algorithm for the species",
                "anyOf": [
                  {
                    "enum": [
                      "Boris",
                      "Vay",
                      "Boris,GCA",
                      "Vay,GCA",
                      "Photon",
                      "None"
                    ]
                  },
                  {
                    "type": "string",
                    "pattern": "(?i)^(Boris|Vay|Boris,GCA|Vay,GCA|Photon|None)$"
                  }
                ],
                "x-entity": {
                  "type": "string",
                  "default": "\"Boris\" [massive]; \"Photon\" [massless]"
                }
              },
              "n_payloads_real": {
                "description": "Number of additional real-valued variables (payloads) for each particle of the given species",
                "type": "integer",
                "minimum": 0,
                "default": 0,
                "x-entity": {
                  "type": "ushort"
                }
              },
              "n_payloads_int": {
                "description": "Number of additional integer-valued variables (payloads) for each particle of the given species",
                "type": "integer",
                "minimum": 0,
                "default": 0,
                "x-entity": {
                  "type": "ushort",
                  "notes": [
                    "If tracking is enabled, one or two extra integer payloads are reserved (depending on whether MPI is enabled)"
                  ]
                }
              },
              "tracking": {
                "description": "Enable tracking of particles using indices for the given species",
                "type": "boolean",
                "default": false,
                "x-entity": {
                  "type": "bool"
                }
              },
              "radiative_drag": {
                "description": "Radiation reaction to use for the species",
                "type": "string",
                "pattern": "(?i)^(None|(Synchrotron|Compton)(,(Synchrotron|Compton))*)$",
                "default": "None",
                "x-entity": {
                  "type": "string",
                  "enum": [
                    "None",
                    "Synchrotron",
                    "Compton"
                  ],
                  "notes": [
                    "Can also be coma-separated combination, e.g., \"Synchrotron,Compton\"",
                    "Relevant radiation.drag parameters should also be provided"
                  ]
                }
              },
              "emission": {
                "description": "Particle emission policy for the species",
                "anyOf": [
                  {
                    "enum": [
                      "None",
                      "Synchrotron",
                      "Compton",
                      "Custom"
                    ]
                  },
                  {
                    "type": "string",
                    "pattern": "(?i)^(None|Synchrotron|Compton|Custom)$"
                  }
                ],
                "default": "None",
                "x-entity": {
                  "type": "string",
                  "notes": [
                    "Only one emission mechanism allowed",
                    "Appropriate radiation drag flag will be applied automatically (unless explicitly set to \"None\")"
                  ]
                }
              },
              "spatial_sorting_interval": {
                "description": "Timesteps between spatial sorting of particles for given species",
                "type": "integer",
                "minimum": 0,
                "default": 0,
                "x-entity": {
                  "type": "uint",
                  "notes": [
                    "Set to 0 to disable spatial sorting",
                    "Overrides `particles.spatial_sorting_interval` for the given species"
                  ]
                }
              },
              "clear_interval": {
                "description": "Timesteps between particle re-sorting by tags (removing dead particles)",
                "type": "integer",
                "minimum": 0,
                "default": 100,
                "x-entity": {
                  "type": "uint",
                  "notes": [
                    "Set to 0 to disable re-sorting",
                    "Overrides `particles.clear_interval` for the given species"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "setup": {
      "description": "Parameters for specific problem generators and setups",
      "type": "object",
      "additionalProperties": true,
      "x-entity": {
        "notes": [
          "Free-form: keys are defined by the problem generator, so nothing here is validated"
        ]
      }
    },
    "output": {
      "description": "Output parameters",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "format": {
          "description": "Output format",
          "anyOf": [
            {
              "enum": [
                "disabled",
                "hdf5",
                "BPFile"
              ]
            },
            {
              "type": "string",
              "pattern": "(?i)^(disabled|hdf5|BPFile)$"
            }
          ],
          "default": "bpfile",
          "x-entity": {
            "type": "string"
          }
        },
        "interval": {
          "description": "Number of timesteps between all outputs",
          "type": "integer",
          "minimum": 1,
          "default": 100,
          "x-entity": {
            "type": "uint [> 0]",
            "notes": [
              "Value is overriden by output intervals for specific outputs"
            ]
          }
        },
        "interval_time": {
          "description": "Physical (code) time interval between all outputs",
          "type": "number",
          "default": -1.0,
          "x-entity": {
            "type": "float",
            "notes": [
              "When `interval_time` < 0, the output is controlled by `interval`, otherwise by `interval_time`",
              "Value is overriden by output intervals for specific outputs"
            ]
          }
        },
        "fields": {
          "description": "Field output parameters",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "enable": {
              "description": "Toggle for the field output",
              "type": "boolean",
              "default": true,
              "x-entity": {
                "type": "bool"
              }
            },
            "quantities": {
              "description": "Field quantities to output",
              "type": "array",
              "items": {
                "type": "string"
              },
              "default": [],
              "x-entity": {
                "type": "array<string>",
                "enum": [
                  "E",
                  "B",
                  "J",
                  "divE",
                  "Rho",
                  "Charge",
                  "N",
                  "Nppc",
                  "T0i",
                  "Tij",
                  "Vi",
                  "D",
                  "H",
                  "divD",
                  "A"
                ],
                "notes": [
                  "For `T`, you can use unspecified indices: `Tij`, `T0i`, or specific ones: `Ttt`, `T00`, `T02`, `T23`",
                  "For `T`, in cartesian can also use \"x\" \"y\" \"z\" instead of \"1\" \"2\" \"3\"",
                  "By default, we accumulate moments from all massive species, one can specify only specific species: `Ttt_1_2`, `Rho_1`, `Rho_3_4`"
                ]
              }
            },
            "custom": {
              "description": "Custom (user-defined) field quantities",
              "type": "array",
              "items": {
                "type": "string"
              },
              "default": [],
              "x-entity": {
                "type": "array<string>"
              }
            },
            "interval": {
              "description": "Number of timesteps between field outputs",
              "type": "integer",
              "minimum": 0,
              "default": 0,
              "x-entity": {
                "type": "uint",
                "notes": [
                  "When `!= 0`, overrides `output.interval`",
                  "When `== 0`, `output.interval` is used"
                ]
              }
            },
            "interval_time": {
              "description": "Physical (code) time interval between field outputs",
              "type": "number",
              "default": -1.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "When `< 0`, the output is controlled by `interval`",
                  "When specified, overrides `output.interval_time`"
                ]
              }
            },
            "downsampling": {
              "description": "Downsample factor for the output of fields",
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": 1
                },
                {
                  "type": "array",
                  "minItems": 1,
                  "maxItems": 3,
                  "items": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              ],
              "default": [
                1,
                1,
                1
              ],
              "x-entity": {
                "type": "uint | array<uint> [>= 1]",
                "notes": [
                  "The output is downsampled by the given factors in each direction",
                  "If a scalar is given, it is applied to all directions"
                ]
              }
            },
            "smoothing": {
              "description": "Smoothing of the output moments",
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "order": {
                  "description": "Smoothing order for the output of moments (\"Rho\", \"Charge\", \"T\", ...)",
                  "type": "integer",
                  "minimum": 0,
                  "default": 0,
                  "x-entity": {
                    "type": "ushort"
                  }
                },
                "method": {
                  "description": "Smoothing algorithm",
                  "anyOf": [
                    {
                      "enum": [
                        "const",
                        "spline"
                      ]
                    },
                    {
                      "type": "string",
                      "pattern": "(?i)^(const|spline)$"
                    }
                  ],
                  "default": "spline",
                  "x-entity": {
                    "type": "string",
                    "notes": [
                      "When using \"spline\", `order` corresponds to the order of the polynomial used",
                      "When using \"const\", the smoothing window is `ceil(order / 2)` in both directions"
                    ]
                  }
                }
              }
            }
          }
        },
        "particles": {
          "description": "Particle output parameters",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "enable": {
              "description": "Toggle for the particles output",
              "type": "boolean",
              "default": true,
              "x-entity": {
                "type": "bool"
              }
            },
            "species": {
              "description": "Particle species indices to output",
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 1
              },
              "default": [],
              "x-entity": {
                "type": "array<int>",
                "notes": [
                  "If empty, all species are output"
                ]
              }
            },
            "stride": {
              "description": "Stride for the output of particles",
              "type": "integer",
              "default": 100,
              "x-entity": {
                "type": "uint [>= 1]"
              },
              "minimum": 1
            },
            "interval": {
              "description": "Number of timesteps between particle outputs",
              "type": "integer",
              "minimum": 0,
              "default": 0,
              "x-entity": {
                "type": "uint",
                "notes": [
                  "When `!= 0`, overrides `output.interval`",
                  "When `== 0`, `output.interval` is used"
                ]
              }
            },
            "interval_time": {
              "description": "Physical (code) time interval between particle outputs",
              "type": "number",
              "default": -1.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "When `< 0`, the output is controlled by `interval`",
                  "When specified, overrides `output.interval_time`"
                ]
              }
            }
          }
        },
        "spectra": {
          "description": "Spectra output parameters",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "enable": {
              "description": "Toggle for the spectra output",
              "type": "boolean",
              "default": true,
              "x-entity": {
                "type": "bool"
              }
            },
            "e_min": {
              "description": "Minimum energy for the spectra output",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "default": 0.001,
              "x-entity": {
                "type": "float",
                "default": "1e-3"
              }
            },
            "e_max": {
              "description": "Maximum energy for the spectra output",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "default": 1000.0,
              "x-entity": {
                "type": "float",
                "default": "1e3"
              }
            },
            "log_bins": {
              "description": "Whether to use logarithmic bins for energy",
              "type": "boolean",
              "default": true,
              "x-entity": {
                "type": "bool"
              }
            },
            "n_bins": {
              "description": "Number of energy bins for the spectra output",
              "type": "integer",
              "minimum": 1,
              "default": 200,
              "deprecated": true,
              "x-entity": {
                "type": "uint [> 0]",
                "deprecated": "removed in 1.6+, use `num_energy_bins` instead"
              }
            },
            "num_energy_bins": {
              "description": "Number of energy bins for the spectra output",
              "type": "integer",
              "minimum": 1,
              "default": 200,
              "x-entity": {
                "type": "uint [> 0]"
              }
            },
            "num_spatial_bins": {
              "description": "Number of spatial bins for the spectra output",
              "type": "array",
              "minItems": 1,
              "maxItems": 3,
              "items": {
                "type": "integer",
                "minimum": 1
              },
              "default": [
                1,
                1,
                1
              ],
              "x-entity": {
                "type": "array<uint> [size 1 :->: 3]"
              }
            },
            "interval": {
              "description": "Number of timesteps between spectra outputs",
              "type": "integer",
              "minimum": 0,
              "default": 0,
              "x-entity": {
                "type": "uint",
                "notes": [
                  "When `!= 0`, overrides `output.interval`",
                  "When `== 0`, `output.interval` is used"
                ]
              }
            },
            "interval_time": {
              "description": "Physical (code) time interval between spectra outputs",
              "type": "number",
              "default": -1.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "When `< 0`, the output is controlled by `interval`",
                  "When specified, overrides `output.interval_time`"
                ]
              }
            }
          }
        },
        "debug": {
          "description": "Debug output parameters",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "as_is": {
              "description": "Output fields \"as is\" without conversions",
              "type": "boolean",
              "default": false,
              "x-entity": {
                "type": "bool"
              }
            },
            "ghosts": {
              "description": "Output fields with values in ghost cells",
              "type": "boolean",
              "default": false,
              "x-entity": {
                "type": "bool"
              }
            }
          }
        },
        "stats": {
          "description": "Integrated statistics output parameters",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "enable": {
              "description": "Toggle for the stats output",
              "type": "boolean",
              "default": true,
              "x-entity": {
                "type": "bool"
              }
            },
            "interval": {
              "description": "Number of timesteps between stat outputs",
              "type": "integer",
              "minimum": 1,
              "default": 100,
              "x-entity": {
                "type": "uint [> 0]",
                "notes": [
                  "Overriden if `output.stats.interval_time != -1`"
                ]
              }
            },
            "interval_time": {
              "description": "Physical (code) time interval between stat outputs",
              "type": "number",
              "default": -1.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "When `< 0`, the output is controlled by `interval`"
                ]
              }
            },
            "quantities": {
              "description": "Field quantities to output",
              "type": "array",
              "items": {
                "type": "string"
              },
              "default": [
                "B^2",
                "E^2",
                "ExB",
                "Rho",
                "T00"
              ],
              "x-entity": {
                "type": "array<string>",
                "enum": [
                  "B^2",
                  "E^2",
                  "ExB",
                  "N",
                  "Npart",
                  "Charge",
                  "Rho",
                  "T00",
                  "T0i",
                  "Tij"
                ],
                "notes": [
                  "For particle moments, ...",
                  "... same notation is used as for `output.fields.quantities`"
                ]
              }
            },
            "custom": {
              "description": "Custom (user-defined) stats",
              "type": "array",
              "items": {
                "type": "string"
              },
              "default": [],
              "x-entity": {
                "type": "array<string>"
              }
            }
          }
        }
      }
    },
    "checkpoint": {
      "description": "Checkpointing parameters",
      "type": "object",
      "additionalProperties": false,
      "x-entity": {
        "inferred": [
          {
            "name": "is_resuming",
            "brief": "Whether the simulation is resuming from a checkpoint",
            "type": "bool",
            "from": "command-line flag"
          },
          {
            "name": "start_step",
            "brief": "Timestep of the checkpoint used to resume",
            "type": "uint",
            "from": "automatically determined during restart"
          },
          {
            "name": "start_time",
            "brief": "Time of the checkpoint used to resume",
            "type": "float",
            "from": "automatically determined during restart"
          }
        ]
      },
      "properties": {
        "interval": {
          "description": "Number of timesteps between checkpoints",
          "type": "integer",
          "minimum": 1,
          "default": 1000,
          "x-entity": {
            "type": "uint [> 0]"
          }
        },
        "interval_time": {
          "description": "Physical (code) time interval between checkpoints",
          "type": "number",
          "default": -1.0,
          "x-entity": {
            "type": "float [> 0]",
            "notes": [
              "When `< 0`, the output is controlled by `interval`"
            ]
          }
        },
        "keep": {
          "description": "Number of checkpoints to keep",
          "type": "integer",
          "minimum": -1,
          "default": 2,
          "x-entity": {
            "type": "int",
            "notes": [
              "0 = disable checkpointing",
              "-1 = keep all checkpoints"
            ]
          }
        },
        "walltime": {
          "description": "Write a checkpoint once after a fixed walltime",
          "type": "string",
          "pattern": "^$|^[0-9]{2,}:[0-9]{2}:[0-9]{2}$",
          "default": "00:00:00",
          "x-entity": {
            "type": "string",
            "notes": [
              "The format is \"HH:MM:SS\"",
              "Empty string or \"00:00:00\" disables this functionality",
              "Writing checkpoint at walltime does not stop the simulation"
            ]
          }
        },
        "write_path": {
          "description": "Parent directory to write checkpoints to",
          "type": "string",
          "x-entity": {
            "type": "string",
            "default": "`<simname>.ckpt`",
            "notes": [
              "The directory is created if it does not exist"
            ]
          }
        },
        "read_path": {
          "description": "Parent directory to use when resuming from a checkpoint",
          "type": "string",
          "x-entity": {
            "type": "string",
            "default": "inherit `write_path`"
          }
        }
      }
    },
    "adios2": {
      "description": "ADIOS2 BP5 tuning, applied to both [output] and [checkpoint] writers",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "aggregators_per_node": {
          "description": "Number of ADIOS2 aggregators per node",
          "type": "integer",
          "minimum": 0,
          "default": 0,
          "x-entity": {
            "type": "uint",
            "notes": [
              "Set to either MPI ranks/node or NICs/node for best performance\nIf set to 0, will use ADIOS2 default (one aggregator per node)"
            ]
          }
        },
        "max_shm_size": {
          "description": "Maximum shared-memory segment size per node, in bytes (BP5 MaxShmSize)",
          "type": "integer",
          "minimum": 0,
          "default": 4294967296,
          "x-entity": {
            "type": "uint",
            "notes": [
              "Lower this on memory-constrained nodes; matches ADIOS2's default"
            ]
          }
        },
        "buffer_chunk_size": {
          "description": "Internal serialization buffer chunk size, in bytes (BP5 BufferChunkSize)",
          "type": "integer",
          "minimum": 0,
          "default": 16777216,
          "x-entity": {
            "type": "uint",
            "notes": [
              "Scales with per-rank output volume; matches ADIOS2's default"
            ]
          }
        }
      }
    },
    "render": {
      "description": "In-situ renderer. Renders scalar fields on the GPU and writes PNG images directly to `<simname>/renders/` each cadence -- no field data is written to storage, and the result is seamless across MPI domain boundaries.",
      "type": "object",
      "additionalProperties": false,
      "x-entity": {
        "notes": [
          "two modes, selected automatically by the simulation dimension:\n- 3D Cartesian (Minkowski): volume ray-march (uses `samples`, `step_size`, `early_term_alpha`, and the [camera] table)\n- 2D (Minkowski, Spherical/QSpherical, and all GR Kerr-Schild): flat slice rasterizer. Cartesian shows the (x, y) plane; spherical shows the meridional (r, theta) half-plane mapped to Cartesian (X = r sin th, Z = r cos th), optionally mirrored (see `mirror`). The `samples`/`step_size`/`early_term_alpha`/[camera] keys are ignored in 2D (one opaque sample per pixel).",
          "1D (and 3D non-Cartesian, which does not exist) is a no-op",
          "One PNG stream per scene (e.g. a density/|B|/|J| triptych)"
        ]
      },
      "properties": {
        "enable": {
          "description": "Toggle for the on-the-fly renderer",
          "type": "boolean",
          "default": false,
          "x-entity": {
            "type": "bool"
          }
        },
        "interval": {
          "description": "Number of timesteps between renders",
          "type": "integer",
          "minimum": 0,
          "default": 0,
          "x-entity": {
            "type": "uint",
            "notes": [
              "When `!= 0`, overrides `output.interval`",
              "When `== 0`, `interval_time` (or `output.interval`) is used"
            ]
          }
        },
        "interval_time": {
          "description": "Physical (code) time interval between renders",
          "type": "number",
          "default": -1.0,
          "x-entity": {
            "type": "float",
            "notes": [
              "When `< 0`, the output is controlled by `interval`"
            ]
          }
        },
        "width": {
          "description": "Image width in pixels (the rendered region; the PNG is wider if a colorbar margin is added, see `colorbar_outside`)",
          "type": "integer",
          "minimum": 1,
          "default": 1024,
          "x-entity": {
            "type": "int [> 0]"
          }
        },
        "height": {
          "description": "Image height in pixels",
          "type": "integer",
          "minimum": 1,
          "default": 1024,
          "x-entity": {
            "type": "int [> 0]"
          }
        },
        "resolution": {
          "description": "Convenience: force a square frame (sets width == height == resolution), the natural shape for a dome master. Overrides `width`/`height` when > 0.",
          "type": "integer",
          "minimum": 0,
          "default": 0,
          "x-entity": {
            "type": "int [> 0]",
            "default": "0 (use width/height)"
          }
        },
        "extent": {
          "description": "Limit the render region to axis-aligned box in physical/world coordinates. Left unset it spans the full domain. Clamped to the box.",
          "type": "object",
          "additionalProperties": false,
          "x-entity": {
            "notes": [
              "3D -> the volume is depth-clipped to this box, the wireframe/axes frame it, and the default camera zooms to it; 2D -> the slice window is framed to it"
            ]
          },
          "properties": {
            "x1": {
              "description": "Axis-aligned render region [lo, hi] along x1, in physical/world coords. Left unset it spans the full domain. Clamped to the box.",
              "anyOf": [
                {
                  "type": "array",
                  "maxItems": 0
                },
                {
                  "type": "array",
                  "minItems": 2,
                  "maxItems": 2,
                  "prefixItems": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    }
                  ]
                }
              ],
              "default": [],
              "x-entity": {
                "type": "array<float> [size 2]",
                "default": "[] (full extent)",
                "notes": [
                  "For a spherical 2D slice, x1 crops the radius r."
                ],
                "examples": [
                  "x1 = [-64.0, 64.0]"
                ]
              }
            },
            "x2": {
              "description": "Render region [lo, hi] along x2.",
              "anyOf": [
                {
                  "type": "array",
                  "maxItems": 0
                },
                {
                  "type": "array",
                  "minItems": 2,
                  "maxItems": 2,
                  "prefixItems": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    }
                  ]
                }
              ],
              "default": [],
              "x-entity": {
                "type": "array<float> [size 2]",
                "default": "[] (full extent)",
                "notes": [
                  "For a spherical 2D slice, x2 crops the polar angle theta."
                ]
              }
            },
            "x3": {
              "description": "Render region [lo, hi] along x3.",
              "anyOf": [
                {
                  "type": "array",
                  "maxItems": 0
                },
                {
                  "type": "array",
                  "minItems": 2,
                  "maxItems": 2,
                  "prefixItems": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    }
                  ]
                }
              ],
              "default": [],
              "x-entity": {
                "type": "array<float> [size 2]",
                "default": "[] (full extent)"
              }
            }
          }
        },
        "volume": {
          "description": "Volume rendering parameters (3D Cartesian only)",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "samples": {
              "description": "Number of ray-march steps across the global box diagonal",
              "type": "integer",
              "minimum": 1,
              "default": 400,
              "x-entity": {
                "type": "int [> 0]",
                "notes": [
                  "The world-space step is `box_diagonal / samples` unless `step_size` is set. Higher = better quality, slower."
                ]
              }
            },
            "step_size": {
              "description": "Fixed world-space step between ray samples",
              "type": "number",
              "minimum": 0.0,
              "default": 0.0,
              "x-entity": {
                "type": "float [>= 0.0]",
                "notes": [
                  "0 derives the step from `samples`. The step is identical on all ranks, which is what makes the multi-domain composite seamless."
                ]
              }
            },
            "early_term_alpha": {
              "description": "Stop marching a ray once its accumulated opacity reaches this value",
              "type": "number",
              "minimum": 0.0,
              "maximum": 1.0,
              "default": 0.99,
              "x-entity": {
                "type": "float [0.0 -> 1.0]",
                "notes": [
                  "Pure speed optimization; set to 1.0 to disable early termination"
                ]
              }
            }
          }
        },
        "n_lut": {
          "description": "Number of entries in the color/opacity lookup table",
          "type": "integer",
          "exclusiveMinimum": 1,
          "default": 256,
          "x-entity": {
            "type": "int [> 1]"
          }
        },
        "background": {
          "description": "Opaque background RGB (each channel 0..1) shown through transparent/low-opacity pixels; also fills the colorbar margin",
          "type": "array",
          "minItems": 3,
          "maxItems": 3,
          "items": {
            "type": "number",
            "minimum": 0.0,
            "maximum": 1.0
          },
          "default": [
            0.0,
            0.0,
            0.0
          ],
          "x-entity": {
            "type": "array<float> [size 3]"
          }
        },
        "colorbar": {
          "description": "Draw a colorbar (gradient + value ticks + label) on each PNG",
          "type": "boolean",
          "default": true,
          "x-entity": {
            "type": "bool"
          }
        },
        "colorbar_outside": {
          "description": "Draw the colorbar in an added right margin (the PNG becomes wider by a fixed strip) instead of overlaying it on the rendered volume",
          "type": "boolean",
          "default": true,
          "x-entity": {
            "type": "bool"
          }
        },
        "mirror": {
          "description": "2D spherical slice only: mirror the meridional half-plane across the symmetry axis to render a full disk from one axisymmetric half. No effect on Cartesian or 3D rendering.",
          "type": "boolean",
          "default": true,
          "x-entity": {
            "type": "bool"
          }
        },
        "time_label": {
          "description": "Draw the current simulation time as a label (\"T = <value>\", fixed to 2 decimals) in the upper-right corner of the render region, in a contrasting color, vertically centered between the frame top and the colorbar.",
          "type": "boolean",
          "default": false,
          "x-entity": {
            "type": "bool"
          }
        },
        "axes": {
          "description": "Draw a spine (frame) + axis ticks + labels around the rendered region. The PNG gains left/bottom margins (background-filled) for the tick labels and axis names, so they never overlap the data.",
          "type": "boolean",
          "default": false,
          "x-entity": {
            "type": "bool",
            "notes": [
              "2D Cartesian = a rectangular frame with linear spatial ticks;\n2D spherical = polar axes (an \"R\" radial axis on the symmetry axis with R=0 centered, and a \"Theta\" axis along the curved outline / spine);\n3D = the global box projected to a wireframe with ticks on the three silhouette edges (x bottom, y & z on the left)"
            ]
          }
        },
        "axis_labels": {
          "description": "Axis names. 3D uses all three; the 2D slice uses the first two. When unset, the 2D slice defaults to \"x\",\"y\" (Cartesian) or \"X\",\"Z\" (spherical).",
          "type": "array",
          "maxItems": 3,
          "items": {
            "type": "string"
          },
          "default": [
            "x",
            "y",
            "z"
          ],
          "x-entity": {
            "type": "array<string> [size <= 3]"
          }
        },
        "axis_ticks": {
          "description": "Target number of ticks per axis (actual count is rounded to nice values)",
          "type": "integer",
          "minimum": 2,
          "default": 5,
          "x-entity": {
            "type": "int [>= 2]"
          }
        },
        "spine_width": {
          "description": "3D only: target width (pixels) of the box wireframe \"spine\". The spine is drawn inside the ray-march (opaque, depth-occluded by the volume); its width is floored by the ray step, so for a crisper thin line raise `samples` as well.",
          "type": "number",
          "exclusiveMinimum": 0.0,
          "default": 2.0,
          "x-entity": {
            "type": "float [> 0.0]"
          }
        },
        "moving_view": {
          "description": "Translate the render region (and, in 3D, the camera), to keep a propagating feature (e.g. a shock) in frame. Pair with x{1,2,3} extent to crop the moving window.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "velocity": {
              "description": "Velocity of the moving camera in world units.",
              "anyOf": [
                {
                  "type": "array",
                  "maxItems": 0
                },
                {
                  "type": "array",
                  "minItems": 2,
                  "maxItems": 3,
                  "items": {
                    "type": "number"
                  }
                }
              ],
              "default": [],
              "x-entity": {
                "type": "array<float> [size 2 or 3]",
                "default": "[] (static view)",
                "examples": [
                  "velocity = [0.9, 0.0]   # pan along +x1 at 0.9 c"
                ]
              }
            },
            "start_time": {
              "description": "Sim time at which the view starts moving (static before it, e.g. to let an initial ramp-up finish)",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float"
              }
            }
          }
        },
        "camera": {
          "description": "Camera (3D volume mode only; ignored by the 2D slice rasterizer). Defaults frame the whole global box from outside, looking down the (1,1,1) diagonal -- the production setup for which the structured composite is provably seamless.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "mode": {
              "description": "Projection mode. Overrides `orthographic` below when set.",
              "anyOf": [
                {
                  "enum": [
                    "orthographic",
                    "perspective",
                    "dome"
                  ]
                },
                {
                  "type": "string",
                  "pattern": "(?i)^(orthographic|perspective|dome)$"
                }
              ],
              "x-entity": {
                "type": "string",
                "default": "(unset -> use `orthographic`)",
                "notes": [
                  "\"dome\" is a fulldome azimuthal-equidistant fisheye rendered from an INTERIOR eye (the domain center by default), i.e. a 3D planetarium dome master. It uses a depth-resolved (A-buffer) composite that is seamless across a full 3D domain decomposition (unlike ortho/perspective, which need the eye outside the box). Set a square frame (`resolution`, or width == height). `forward` is the dome ZENITH (screen-up defaults to +y for a +z zenith)."
                ]
              }
            },
            "position": {
              "description": "Camera (eye) position in world (physical) coordinates",
              "type": "array",
              "minItems": 3,
              "maxItems": 3,
              "items": {
                "type": "number"
              },
              "x-entity": {
                "type": "array<float> [size 3]",
                "default": "box center pushed back ~1.7 box-diagonals along (1, 1, 1);\nfor `mode = \"dome\"`, the domain center (interior eye)"
              }
            },
            "look_at": {
              "description": "Point the camera looks at, in world coordinates (the dome ZENITH target)",
              "type": "array",
              "minItems": 3,
              "maxItems": 3,
              "items": {
                "type": "number"
              },
              "x-entity": {
                "type": "array<float> [size 3]",
                "default": "box center; for `mode = \"dome\"`, the zenith defaults to +z"
              }
            },
            "up": {
              "description": "Camera up vector (dome: the disk's screen-up)",
              "type": "array",
              "minItems": 3,
              "maxItems": 3,
              "items": {
                "type": "number"
              },
              "default": [
                0.0,
                0.0,
                1.0
              ],
              "x-entity": {
                "type": "array<float> [size 3]",
                "default": "[0.0, 0.0, 1.0]; for `mode = \"dome\"`, [0.0, 1.0, 0.0]"
              }
            },
            "fov": {
              "description": "Vertical field of view in degrees (perspective only)",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "default": 35.0,
              "x-entity": {
                "type": "float [> 0.0]"
              }
            },
            "dome_fov": {
              "description": "Full dome field of view in degrees (dome mode only): the image rim is at dome_fov/2 from the zenith (180 = a full hemisphere down to the horizon).",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "maximum": 360.0,
              "default": 180.0,
              "x-entity": {
                "type": "float [> 0.0, <= 360.0]"
              }
            },
            "dome_radius": {
              "description": "Dome far-clip radius in world units (dome mode only): each ray stops this far from the eye, so the sampled region is a half-ball (hemisphere) of this radius rather than the whole box -> uniform path length and no box corner/edge projection artifacts. `samples` then counts steps across this radius.",
              "type": "number",
              "minimum": 0.0,
              "x-entity": {
                "type": "float [>= 0.0]",
                "default": "the largest sphere centered in the box (half the shortest side), so it touches the face centers and never a corner",
                "notes": [
                  "0 disables the clip (rays march to the box boundary)"
                ]
              }
            },
            "ortho_height": {
              "description": "Vertical extent of the view in world units (orthographic only)",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "x-entity": {
                "type": "float [> 0.0]",
                "default": "the global box diagonal (the whole box fits from any angle)"
              }
            }
          }
        },
        "dome": {
          "description": "Fulldome fisheye (\"planetarium dome master\"). 2D only; a circular image is centered in the frame's inscribed circle with the corners left as the background (the dome master's black border). Set `width == height` (e.g. 4096) for a square master. When enabled, the axes and the outside colorbar strip are suppressed so the PNG stays exactly width x height. Seamless across MPI domains (the pixel->world map is a shared, deterministic function and the tiles stay disjoint). Ignored (with a warning) for 3D.",
          "type": "object",
          "additionalProperties": false,
          "x-entity": {
            "notes": [
              "CARTESIAN -- the flat plane is warped radially into the disk; use `fov`/`radius`/`center`/`projection` below.",
              "SPHERICAL / GR Kerr-Schild -- the meridional slice is ALREADY a disk, so dome mode only mirrors it to a full disk (see `mirror` above; keep it true) and fits it to the inscribed circle. The `fov`/`radius`/`center`/`projection` keys are ignored (the native (X, Z) meridional map is used, with image radius proportional to the physical radius r, r=0 at the disk center)."
            ]
          },
          "properties": {
            "enable": {
              "description": "Build the fisheye dome master instead of the plain slice",
              "type": "boolean",
              "default": false,
              "x-entity": {
                "type": "bool"
              }
            },
            "fov": {
              "description": "(Cartesian only) Full dome field of view in degrees (image radius maps linearly to the dome zenith angle: the rim is at fov/2)",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "maximum": 180.0,
              "default": 180.0,
              "x-entity": {
                "type": "float [> 0.0, <= 180.0]",
                "default": "180.0   # a full hemisphere"
              }
            },
            "radius": {
              "description": "(Cartesian only) World radius of the circular cutout mapped onto the dome",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "x-entity": {
                "type": "float [> 0.0]",
                "default": "half the shorter domain side (the largest centered disk that fits inside the box)"
              }
            },
            "center": {
              "description": "(Cartesian only) World-space center of the cutout",
              "type": "array",
              "minItems": 2,
              "maxItems": 2,
              "items": {
                "type": "number"
              },
              "x-entity": {
                "type": "array<float> [size 2]",
                "default": "the domain center"
              }
            },
            "projection": {
              "description": "(Cartesian only) How the dome zenith angle maps to a world radius on the flat slice",
              "anyOf": [
                {
                  "enum": [
                    "equidistant",
                    "gnomonic",
                    "stereographic",
                    "orthographic"
                  ]
                },
                {
                  "type": "string",
                  "pattern": "(?i)^(equidistant|gnomonic|stereographic|orthographic)$"
                }
              ],
              "default": "equidistant",
              "x-entity": {
                "type": "string",
                "enum": [
                  "\"equidistant\"  (r proportional to angle; the fulldome image standard -- a straight radial scaling of the cutout)",
                  "\"gnomonic\"     (r ~ tan(angle); the slice as a flat \"ceiling\" tangent to the dome -- straight sim lines stay straight)",
                  "\"stereographic\" (r ~ tan(angle/2); conformal, preserves shapes)",
                  "\"orthographic\" (r ~ sin(angle); the slice as seen face-on)"
                ]
              }
            }
          }
        },
        "fieldlines": {
          "description": "Magnetic field lines, drawn from a coarse, MPI-replicated copy of the field so the geometry is global and seamless across domains (the coarsening is what makes this cheap -- no parallel particle advection / flux scan).\n- 3D (Cartesian): traced as solid tubes, colored by |field|, composited inside the volume ray-march so the volume correctly occludes them.\n- 2D (Cartesian): iso-contours of the flux function psi (Bx = d psi/dy, By = -d psi/dx), i.e. the in-plane field lines, colored by |B|.\n- 2D (spherical / Kerr-Schild): traced meridional streamlines of the poloidal (Br, Btheta) field (nt2py style).\nBuilt once per frame and shared by every scene that opts in (per-scene `fieldlines = true`) and by any standalone `field = \"fieldlines\"` scene.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "enable": {
              "description": "Build the field-line geometry this run",
              "type": "boolean",
              "default": false,
              "x-entity": {
                "type": "bool",
                "notes": [
                  "implied true if any scene sets `fieldlines = true` or uses `field = \"fieldlines\"`"
                ]
              }
            },
            "field": {
              "description": "Vector field to trace",
              "anyOf": [
                {
                  "enum": [
                    "B",
                    "E",
                    "J"
                  ]
                },
                {
                  "type": "string",
                  "pattern": "(?i)^(B|E|J)$"
                }
              ],
              "default": "B",
              "x-entity": {
                "type": "string"
              }
            },
            "bin": {
              "description": "Field coarsening factor (simulation cells per coarse cell, per axis)",
              "type": "integer",
              "minimum": 1,
              "maximum": 16,
              "default": 4,
              "x-entity": {
                "type": "int [1..16]",
                "notes": [
                  "larger = smoother \"morphology\" lines + cheaper replication (the coarse field is ~ N_cells / bin^D floats/rank; D = sim dimension)"
                ]
              }
            },
            "seed_px": {
              "description": "(3D tubes) Seed-lattice spacing in screen pixels (sets line density)",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "default": 8,
              "x-entity": {
                "type": "float [> 0]",
                "notes": [
                  "capped by `seed_max`; if seed_px asks for more seeds than that, the spacing grows to fit and seed_px no longer governs"
                ]
              }
            },
            "seed_max": {
              "description": "(3D tubes) Hard cap on the seed count (lattice is n^3, 2 lines per seed)",
              "type": "integer",
              "minimum": 1,
              "default": 4096,
              "x-entity": {
                "type": "int [> 0]",
                "notes": [
                  "lower this for fewer / more widely spaced lines"
                ]
              }
            },
            "levels": {
              "description": "(2D contours) Number of evenly-spaced flux-function contour levels",
              "type": "integer",
              "minimum": 1,
              "default": 16,
              "x-entity": {
                "type": "int [> 0]",
                "notes": [
                  "evenly-spaced psi levels => line density tracks |B| automatically"
                ]
              }
            },
            "tube_px": {
              "description": "Tube radius (3D) / contour line width (2D), in screen pixels",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "default": 2,
              "x-entity": {
                "type": "float [> 0]"
              }
            },
            "colormap": {
              "description": "Colormap for the field lines (mapped by |B| along each line)",
              "$ref": "#/$defs/colormap",
              "default": "inferno"
            },
            "color": {
              "description": "Monochrome override: draw the lines in a single [r,g,b] color (each 0..1) instead of the |B| colormap -- reads well as an overlay on another volume",
              "anyOf": [
                {
                  "type": "array",
                  "maxItems": 0
                },
                {
                  "type": "array",
                  "minItems": 3,
                  "maxItems": 3,
                  "items": {
                    "type": "number",
                    "minimum": 0.0,
                    "maximum": 1.0
                  }
                }
              ],
              "default": [],
              "x-entity": {
                "type": "array<float> [size 3]",
                "default": "[] (empty => color by |B|)",
                "examples": [
                  "[1.0, 1.0, 1.0]   # white field lines"
                ]
              }
            },
            "log": {
              "description": "Map the tube color range logarithmically",
              "type": "boolean",
              "default": false,
              "x-entity": {
                "type": "bool",
                "notes": [
                  "requires min > 0"
                ]
              }
            },
            "min": {
              "description": "Tube color range: lower bound on |field|",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "when min >= max, the range is auto-set from |field| along the lines"
                ]
              }
            },
            "max": {
              "description": "Tube color range: upper bound on |field|",
              "type": "number",
              "default": 0.0,
              "x-entity": {
                "type": "float",
                "notes": [
                  "when min >= max, the range is auto-set from |field| along the lines"
                ]
              }
            },
            "step_frac": {
              "description": "(3D tubes) RK4 integration step as a fraction of one coarse cell",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "default": 0.5,
              "x-entity": {
                "type": "float [> 0]"
              }
            },
            "max_steps": {
              "description": "(3D tubes) Per-direction integration-step cap",
              "type": "integer",
              "minimum": 1,
              "default": 4000,
              "x-entity": {
                "type": "int [> 0]"
              }
            },
            "max_length": {
              "description": "(3D tubes) Maximum line length, in global box diagonals (per direction)",
              "type": "number",
              "exclusiveMinimum": 0.0,
              "default": 3.0,
              "x-entity": {
                "type": "float [> 0]"
              }
            }
          }
        },
        "scene": {
          "description": "One scene per scalar field -> one PNG stream. Repeat the table for each.",
          "type": "array",
          "x-entity": {
            "array_of_tables": true
          },
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "field"
            ],
            "properties": {
              "field": {
                "description": "Scalar field to render (a volume render needs a scalar, so vectors are given as a magnitude or a single component)",
                "type": "string",
                "x-entity": {
                  "type": "string",
                  "enum": [
                    "(fields): \"{E,B,J}mag\"; \"{E,B,J}{1,2,3}\" or \"{E,B,J}{x,y,z}\"",
                    "(moments): \"N\", \"Nppc\", \"Rho\", \"Charge\"; \"T{i}{j}\"; \"V{i}\"; \"Vmag\""
                  ],
                  "notes": [
                    "\"{E,B,J}mag\" = vector magnitude |.|; \"B1\"/\"Bx\", \"J3\"/\"Jz\", ... = a single (signed) physical component",
                    "a bare vector (\"E\"/\"B\"/\"J\") is not renderable -- choose a component or the magnitude",
                    "\"N\"/\"Nppc\" = number / per-cell count, \"Rho\" = mass density, \"Charge\" = charge density",
                    "\"T{i}{j}\" = one stress-energy component, i,j in {t,x,y,z} or {0,1,2,3} (e.g. \"Txx\", \"Ttt\", \"T0x\"); \"V{i}\" = one bulk-velocity component, i in {x,y,z} or {1,2,3} (e.g. \"Vx\", \"V1\"); \"Vmag\" = bulk-velocity magnitude sqrt(V1^2+V2^2+V3^2)",
                    "moments follow the engine: SRPIC = tetrad-basis bulk 3-velocity and stress-energy; GRPIC = Eckart-frame 4-velocity (so \"Vt\"/\"V0\" = u^0 = Gamma/alpha is also valid) and contravariant T",
                    "per-species selection with a \"_<id>\" suffix on moments, e.g. \"N_1\", \"Rho_2\", \"Txy_1_2\", \"V1_3\"; default = all massive species",
                    "components are signed; pair a symmetric `min`/`max` with a diverging colormap (\"cool2warm\") to center zero",
                    "\"fieldlines\" renders the magnetic field-line tubes on their own (no scalar volume sampled); see [render.fieldlines] below"
                  ]
                }
              },
              "prefix": {
                "description": "PNG filename prefix; files are `<prefix><cycle>.png`",
                "type": "string",
                "x-entity": {
                  "type": "string",
                  "default": "\"<field>_\""
                }
              },
              "label": {
                "description": "Colorbar title",
                "type": "string",
                "x-entity": {
                  "type": "string",
                  "default": "`field`"
                }
              },
              "min": {
                "description": "Lower bound of the value range mapped onto the colormap/opacity",
                "type": "number",
                "default": 0.0,
                "x-entity": {
                  "type": "float"
                }
              },
              "max": {
                "description": "Upper bound of the value range",
                "type": "number",
                "default": 1.0,
                "x-entity": {
                  "type": "float"
                }
              },
              "log": {
                "description": "Map the value range logarithmically",
                "type": "boolean",
                "default": false,
                "x-entity": {
                  "type": "bool",
                  "notes": [
                    "Requires min > 0 and max > 0"
                  ]
                }
              },
              "colormap": {
                "description": "Colormap name",
                "$ref": "#/$defs/colormap",
                "default": "viridis"
              },
              "alpha": {
                "description": "Opacity transfer function: [position, opacity] control points, both in [0, 1], piecewise-linear in the normalized value",
                "type": "array",
                "items": {
                  "type": "array",
                  "minItems": 2,
                  "maxItems": 2,
                  "prefixItems": [
                    {
                      "type": "number",
                      "minimum": 0.0,
                      "maximum": 1.0
                    },
                    {
                      "type": "number",
                      "minimum": 0.0,
                      "maximum": 1.0
                    }
                  ]
                },
                "x-entity": {
                  "type": "array<tuple<float>>",
                  "default": "linear ramp (opacity = normalized value)",
                  "notes": [
                    "Keep the low end near 0 so empty regions stay transparent"
                  ],
                  "examples": [
                    "[[0.0, 0.0], [0.3, 0.1], [1.0, 0.7]]"
                  ]
                }
              },
              "colorbar_ticks": {
                "description": "Explicit value(s) to label on the colorbar",
                "type": "array",
                "items": {
                  "type": "number"
                },
                "x-entity": {
                  "type": "array<float>",
                  "default": "5 evenly-spaced ticks between min and max",
                  "notes": [
                    "Values outside [min, max] are skipped"
                  ],
                  "examples": [
                    "[0.0, 0.5, 1.0]"
                  ]
                }
              },
              "fieldlines": {
                "description": "Overlay the magnetic field-line tubes inside this scene's volume",
                "type": "boolean",
                "default": false,
                "x-entity": {
                  "type": "bool",
                  "notes": [
                    "requires the [render.fieldlines] enabled (3D only). A scene with field = \"fieldlines\" instead renders them alone."
                  ]
                }
              }
            }
          }
        }
      }
    },
    "diagnostics": {
      "description": "Diagnostic logging parameters",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "interval": {
          "description": "Number of timesteps between diagnostic logs",
          "type": "integer",
          "minimum": 1,
          "default": 1,
          "x-entity": {
            "type": "int [> 0]"
          }
        },
        "blocking_timers": {
          "description": "Blocking timers between successive algorithms",
          "type": "boolean",
          "default": false,
          "x-entity": {
            "type": "bool"
          }
        },
        "colored_stdout": {
          "description": "Enable colored stdout",
          "type": "boolean",
          "default": true,
          "x-entity": {
            "type": "bool"
          }
        },
        "log_level": {
          "description": "Specify the log level",
          "anyOf": [
            {
              "enum": [
                "VERBOSE",
                "WARNING",
                "ERROR"
              ]
            },
            {
              "type": "string",
              "pattern": "(?i)^(VERBOSE|WARNING|ERROR)$"
            }
          ],
          "default": "VERBOSE",
          "x-entity": {
            "type": "string",
            "notes": [
              "\"VERBOSE\" prints all messages, \"WARNING\" prints only warnings and errors, \"ERROR\" prints only errors"
            ]
          }
        }
      }
    }
  }
}