input.example.toml

[simulation]
  # Name of the simulation
  #   @required
  #   @type: string
  #   @note: The name is used for the output files
  name = ""
  # Simulation engine to use
  #   @required
  #   @type: string
  #   @enum: "SRPIC", "GRPIC"
  engine = ""
  # Max runtime in physical (code) units
  #   @required
  #   @type: float [> 0]
  #   @example: 1e5
  runtime = ""

  [simulation.domain]
    # Number of domains
    #   @type: int
    #   @default: 1 [no MPI]; MPI_SIZE [MPI]
    number = ""
    # Decomposition of the domain (for MPI) in each of the directions
    #   @type: array<int> [size 1 :->: 3]
    #   @default: [-1, -1, -1]
    #   @note: -1 means the code will determine the decomposition in the specific direction automatically
    #   @note: Automatic detection is either done by inference from # of MPI tasks, or by balancing the grid size on each domain
    #   @example: [2, 2, 2] (total of 8 domains)
    decomposition = ""

[grid]
  # Spatial resolution of the grid
  #   @required
  #   @type: array<uint> [size 1 :->: 3]
  #   @note: Dimensionality is inferred from the size of this array
  #   @example: [1024, 1024, 1024]
  resolution = ""
  # Physical extent of the grid
  #   @required
  #   @type: array<tuple<float>> [size 1 :->: 3]
  #   @note: For spherical geometry, only specify `[[rmin, rmax]]`, other values are set automatically
  #   @note: For cartesian geometry, cell aspect ratio has to be 1: `dx=dy=dz`
  #   @example: [[0.0, 1.0], [-1.0, 1.0]]
  extent = ""

  # @inferred:
  # - dim
  #     @brief: Dimensionality of the grid
  #     @type: short
  #     @enum: 1, 2, 3
  #     @from: `grid.resolution`

  [grid.metric]
    # Metric on the grid
    #   @required
    #   @type: string
    #   @enum: "Minkowski", "Spherical", "QSpherical", "Kerr_Schild", "QKerr_Schild", "Kerr_Schild_0"
    metric = ""
    # `r0` paramter for the QSpherical metric `x1 = log(r-r0)`
    #   @type: float [-inf -> rmin]
    #   @default: 0.0
    #   @note: Negative values produce almost uniform grid in r
    qsph_r0 = ""
    # `h` paramter for the QSpherical metric `th = x2 + 2*h x2 (pi-2*x2)*(pi-x2)/pi^2`
    #   @type: float [-1 :->: 1]
    #   @default: 0.0
    qsph_h = ""
    # Spin parameter for the Kerr Schild metric
    #   @type: float [0 :-> 1]
    #   @default: 0.0
    ks_a = ""

    # @inferred:
    # - coord
    #     @brief: Coordinate system on the grid
    #     @type: string
    #     @enum: "cartesian", "spherical", "qspherical"
    #     @from: `grid.metric.metric`
    # - ks_rh
    #     @brief: Size of the horizon for GR Kerr Schild
    #     @type: float
    #     @from: `grid.metric.ks_a`
    # - params
    #     @brief: A map of all metric-specific parameters together (for easy access)
    #     @type: map<string, float>
    #     @from: `grid.metric`

  [grid.boundaries]
    # Boundary conditions for fields
    #   @required
    #   @type: array<tuple<string>> [size 1 :->: 3]
    #   @enum: "PERIODIC", "MATCH", "FIXED", "ATMOSPHERE", "CUSTOM", "HORIZON", "CONDUCTOR"
    #   @note: When periodic in any of the directions, you should only set one value: [..., ["PERIODIC"], ...]
    #   @note: In spherical, bondaries in theta/phi are set automatically (only specify bc @ `[rmin, rmax]`): [["ATMOSPHERE", "MATCH"]]
    #   @note: In GR, the horizon boundary is set automatically (only specify bc @ rmax): [["MATCH"]]
    #   @example: [["CUSTOM", "MATCH"]] (for 2D spherical `[[rmin, rmax]]`)
    fields = ""
    # Boundary conditions for fields
    #   @required
    #   @type: array<tuple<string>> [size 1 :->: 3]
    #   @enum: "PERIODIC", "ABSORB", "ATMOSPHERE", "CUSTOM", "REFLECT", "HORIZON"
    #   @note: When periodic in any of the directions, you should only set one value [..., ["PERIODIC"], ...]
    #   @note: In spherical, bondaries in theta/phi are set automatically (only specify bc @ `[rmin, rmax]`) [["ATMOSPHERE", "ABSORB"]]
    #   @note: In GR, the horizon boundary is set automatically (only specify bc @ `rmax`): [["ABSORB"]]
    #   @example: [["PERIODIC"], ["PERIODIC"]]
    particles = ""

    [grid.boundaries.match]
      # Size of the matching layer in each direction for fields in physical (code) units
      #   @type: float | array<tuple<float>> 
      #   @default: 1% of the domain size (in shortest dimension)
      #   @note: In spherical, this is the size of the layer in `r` from the outer wall
      #   @example: `ds = 1.5` (will set the same for all directions)
      #   @example: `ds = [[1.5], [2.0, 1.0], [1.1]]` (will duplicate 1.5 for +/- `x1` and 1.1 for +/- `x3`)
      #   @example: `ds = [[], [1.5], []]` (will only set for x2)
      ds = ""

    [grid.boundaries.absorb]
      # Size of the absorption layer for particles in physical (code) units
      #   @type: float
      #   @default: 1% of the domain size (in shortest dimension)
      #   @note: In spherical, this is the size of the layer in `r` from the outer wall
      #   @note: In cartesian, this is the same for all dimensions where applicable
      ds = ""

    [grid.boundaries.atmosphere]
      # Temperature of the atmosphere in units of `m0 c^2`
      #   @type: float
      #   @note: [required] if `ATMOSPHERE` is one of the boundaries
      temperature = ""
      # Peak number density of the atmosphere at base in units of `n0`
      #   @type: float
      density = ""
      # Pressure scale-height in physical units
      #   @type: float
      height = ""
      # Species indices of particles that populate the atmosphere
      #   @type: array<int> [size 2]
      species = ""
      # Distance from the edge to which the gravity is imposed in physical units
      #   @type: float
      #   @default: 0.0
      #   @note: 0.0 means no limit
      ds = ""

      # @inferred:
      # - g
      #     @brief: Acceleration due to imposed gravity
      #     @type: float
      #     @from: `grid.boundaries.atmosphere.temperature`, `grid.boundaries.atmosphere.height`
      #     @value: `temperature / height`

[scales]
  # Fiducial larmor radius
  #   @required
  #   @type: float [> 0.0]
  larmor0 = ""
  # Fiducial plasma skin depth
  #   @required
  #   @type: float [> 0.0]
  skindepth0 = ""

  # @inferred:
  # - dx0
  #     @brief: fiducial minimum size of the cell
  #     @type: float
  #     @from: `grid`
  # - V0
  #     @brief: fiducial elementary volume
  #     @type: float
  #     @from: `grid`
  # - n0
  #     @brief: Fiducial number density
  #     @type: float
  #     @from: `particles.ppc0`, `grid`
  #     @value: `ppc0 / V0`
  # - q0
  #     @brief: Fiducial elementary charge
  #     @type: float
  #     @from: `scales.skindepth0`, `scales.n0`
  #     @value: `1 / (n0 * skindepth0^2)`
  # - sigma0
  #     @brief: Fiducial magnetization parameter
  #     @type: float
  #     @from: `scales.larmor0`, `scales.skindepth0`
  #     @value: `(skindepth0 / larmor0)^2`
  # - B0
  #     @brief: Fiducial magnetic field
  #     @type: float
  #     @from: `scales.larmor0`
  #     @value: `1 / larmor0`
  # - omegaB0
  #     @brief: Fiducial cyclotron frequency
  #     @type: float
  #     @from: `scales.larmor0`
  #     @value: `1 / larmor0`

[algorithms]
  # Number of current smoothing passes
  #   @type: ushort [>= 0]
  #   @default: 0
  current_filters = ""

  [algorithms.timestep]
    # Courant-Friedrichs-Lewy number
    #   @type: float [0.0 -> 1.0]
    #   @default: 0.95
    #   @note: CFL number determines the timestep duration
    CFL = ""
    # Correction factor for the speed of light used in field solver
    #   @type: float
    #   @default: 1.0
    correction = ""

    # @inferred:
    # - dt
    #     @brief: timestep duration
    #     @type: float
    #     @from: `algorithms.timestep.CFL`, `scales.dx0`
    #     @value: `CFL * dx0`

  [algorithms.deposit]
    # Enable the current deposition
    #   @type: bool
    #   @default: true
    enable = ""
    # Order of the particle shape function
    #   @type: int
    #   @default: 1
    order = ""

  [algorithms.gr]
    # Stepsize for numerical differentiation in GR pusher
    #   @type: float [> 0.0]
    #   @default: 1e-6
    pusher_eps = ""
    # Number of iterations for the Newton-Raphson method in GR pusher
    #   @type: ushort [> 0]
    #   @default: 10
    pusher_niter = ""

  [algorithms.gca]
    # Maximum value for E/B allowed for GCA particles
    #   @type: float [0.0 -> 1.0]
    #   @default: 0.9
    e_ovr_b_max = ""
    # Maximum Larmor radius allowed for GCA particles (in physical units)
    #   @type: float
    #   @default: 0.0
    #   @note: When `larmor_max` == 0, the limit is disabled
    larmor_max = ""

  [algorithms.synchrotron]
    # Radiation reaction limit gamma-factor for synchrotron
    #   @type: float [> 0.0]
    #   @default: 1.0
    #   @note: [required] if one of the species has `cooling = "synchrotron"`
    gamma_rad = ""

  # Stencil coefficients for the field solver [notation as in Blinne+ (2018)]
  #   @note: Standard Yee solver: `delta_i = beta_ij = 0.0`
  [algorithms.fieldsolver]
    # Enable the fieldsolver
    #   @type: bool
    #   @default: true
    enable = ""
    # delta_x coefficient (for `F_{i +/- 3/2, j, k}`)
    #   @type: float
    #   @default: 0.0
    delta_x = ""
    # delta_y coefficient (for `F_{i, j +/- 3/2, k}`)
    #   @type: float
    #   @default: 0.0
    #   @note: Used only for 2D and 3D
    delta_y = ""
    # delta_z coefficient (for `F_{i, j, k +/- 3/2}`)
    #   @type: float
    #   @default: 0.0
    #   @note: Used only for 3D
    delta_z = ""
    # beta_xy coefficient (for `F_{i +/- 1/2, j +/- 1, k}`)
    #   @type: float
    #   @default: 0.0
    #   @note: Used only for 2D and 3D
    beta_xy = ""
    # beta_yx coefficient (for `F_{i +/- 1, j +/- 1/2, k}`)
    #   @type: float
    #   @default: 0.0
    #   @note: Used only for 2D and 3D
    beta_yx = ""
    # beta_xz coefficient (for `F_{i +/- 1/2, j, k +/- 1}`)
    #   @type: float
    #   @default: 0.0
    #   @note: Used only for 3D
    beta_xz = ""
    # beta_zx coefficient (for `F_{i +/- 1, j, k +/- 1/2}`)
    #   @type: float
    #   @default: 0.0
    #   @note: Used only for 3D
    beta_zx = ""
    # beta_yz coefficient (for `F_{i, j +/- 1/2, k +/- 1}`)
    #   @type: float
    #   @default: 0.0
    #   @note: Used only for 3D
    beta_yz = ""
    # beta_zy coefficient (for `F_{i, j +/- 1, k +/- 1/2}`)
    #   @type: float
    #   @default: 0.0
    #   @note: Used only for 3D
    beta_zy = ""

[particles]
  # Fiducial number of particles per cell
  #   @required
  #   @type: float [> 0.0]
  ppc0 = ""
  # Toggle for using particle weights
  #   @type: bool
  #   @default: false
  use_weights = ""
  # Timesteps between particle re-sorting (removing dead particles)
  #   @type: uint
  #   @default: 100
  #   @note: Set to 0 to disable re-sorting
  clear_interval = ""

  # @inferred:
  # - nspec
  #     @brief: Number of particle species
  #     @type: uint
  #     @from: `particles.species`

  [[particles.species]]
    # Label of the species
    #   @type: string
    #   @default: "s<INDEX>"
    #   @example: "e-"
    #   @note: `<INDEX>` is the index of the species in the list starting from 1
    label = ""
    # Mass of the species (in units of fiducial mass)
    #   @required
    #   @type: float [>= 0.0]
    mass = ""
    # Charge of the species (in units of fiducial charge)
    #   @required
    #   @type: float
    charge = ""
    # Maximum number of particles per task
    #   @required
    #   @type: uint [> 0]
    maxnpart = ""
    # Pusher algorithm for the species
    #   @type: string
    #   @default: "Boris" [massive]; "Photon" [massless]
    #   @enum: "Boris", "Vay", "Boris,GCA", "Vay,GCA", "Photon", "None"
    pusher = ""
    # Number of additional real-valued variables (payloads) for each particle of the given species
    #   @type: ushort
    #   @default: 0
    n_payloads_real = ""
    # Number of additional integer-valued variables (payloads) for each particle of the given species
    #   @type: ushort
    #   @default: 0
    #   @note: If tracking is enabled, one or two extra integer payloads are reserved (depending on whether MPI is enabled)
    n_payloads_int = ""
    # Enable tracking of particles using indices for the given species
    #   @type: bool
    #   @default: false
    tracking = ""
    # Radiation reaction to use for the species
    #   @type: string
    #   @default: "None"
    #   @enum: "None", "Synchrotron"
    cooling = ""

# Parameters for specific problem generators and setups
[setup]

[output]
  # Output format
  #   @type: string
  #   @default: "hdf5"
  #   @enum: "disabled", "hdf5", "BPFile"
  format = ""
  # Number of timesteps between all outputs
  #   @type: uint [> 0]
  #   @default: 1
  #   @note: Value is overriden by output intervals for specific outputs
  interval = ""
  # Physical (code) time interval between all outputs
  #   @type: float
  #   @default: -1.0
  #   @note: When `interval_time` < 0, the output is controlled by `interval`, otherwise by `interval_time`
  #   @note: Value is overriden by output intervals for specific outputs
  interval_time = ""
  # Whether to output each timestep into separate files
  #   @type: bool
  #   @default: true
  #   @deprecated: starting v1.3.0
  separate_files = ""

  [output.fields]
    # Toggle for the field output
    #   @type: bool
    #   @default: true
    enable = ""
    # Field quantities to output
    #   @type: array<string>
    #   @default: []
    #   @enum: "E", "B", "J", "divE", "Rho", "Charge", "N", "Nppc", "T0i", "Tij", "Vi", "D", "H", "divD", "A"
    #   @note: For `T`, you can use unspecified indices: `Tij`, `T0i`, or specific ones: `Ttt`, `T00`, `T02`, `T23`
    #   @note: For `T`, in cartesian can also use "x" "y" "z" instead of "1" "2" "3"
    #   @note: By default, we accumulate moments from all massive species, one can specify only specific species: `Ttt_1_2`, `Rho_1`, `Rho_3_4`
    quantities = ""
    # Custom (user-defined) field quantities
    #   @type: array<string>
    #   @default: []
    custom = ""
    # Smoothing window for the output of moments ("Rho", "Charge", "T", ...)
    #   @type: ushort
    #   @default: 0
    mom_smooth = ""
    # Number of timesteps between field outputs
    #   @type: uint
    #   @default: 0
    #   @note: When `!= 0`, overrides `output.interval`
    #   @note: When `== 0`, `output.interval` is used
    interval = ""
    # Physical (code) time interval between field outputs
    #   @type: float
    #   @default: -1.0
    #   @note: When `< 0`, the output is controlled by `interval`
    #   @note: When specified, overrides `output.interval_time`
    interval_time = ""
    # Downsample factor for the output of fields
    #   @type: uint | array<uint> [>= 1]
    #   @default: [1, 1, 1]
    #   @note: The output is downsampled by the given factors in each direction
    #   @note: If a scalar is given, it is applied to all directions
    downsampling = ""

  [output.particles]
    # Toggle for the particles output
    #   @type: bool
    #   @default: true
    enable = ""
    # Particle species indices to output
    #   @type: array<int>
    #   @default: []
    #   @note: If empty, all species are output
    species = ""
    # Stride for the output of particles
    #   @type: uint [> 1]
    #   @default: 100
    stride = ""
    # Number of timesteps between particle outputs
    #   @type: uint
    #   @default: 0
    #   @note: When `!= 0`, overrides `output.interval`
    #   @note: When `== 0`, `output.interval` is used
    interval = ""
    # Physical (code) time interval between particle outputs
    #   @type: float
    #   @default: -1.0
    #   @note: When `< 0`, the output is controlled by `interval`
    #   @note: When specified, overrides `output.interval_time`
    interval_time = ""

  [output.spectra]
    # Toggle for the spectra output
    #   @type: bool
    #   @default: true
    enable = ""
    # Minimum energy for the spectra output
    #   @type: float
    #   @default: 1e-3
    e_min = ""
    # Maximum energy for the spectra output
    #   @type: float
    #   @default: 1e3
    e_max = ""
    # Whether to use logarithmic bins
    #   @type: bool
    #   @default: true
    log_bins = ""
    # Number of bins for the spectra output
    #   @type: uint [> 0]
    #   @default: 200
    n_bins = ""
    # Number of timesteps between spectra outputs
    #   @type: uint
    #   @default: 0
    #   @note: When `!= 0`, overrides `output.interval`
    #   @note: When `== 0`, `output.interval` is used
    interval = ""
    # Physical (code) time interval between spectra outputs
    #   @type: float
    #   @default: -1.0
    #   @note: When `< 0`, the output is controlled by `interval`
    #   @note: When specified, overrides `output.interval_time`
    interval_time = ""

  [output.debug]
    # Output fields "as is" without conversions
    #   @type: bool
    #   @default: false
    as_is = ""
    # Output fields with values in ghost cells
    #   @type: bool
    #   @default: false
    ghosts = ""

  [output.stats]
    # Toggle for the stats output
    #   @type: bool
    #   @default: true
    enable = ""
    # Number of timesteps between stat outputs
    #   @type: uint [> 0]
    #   @default: 100
    #   @note: Overriden if `output.stats.interval_time != -1`
    interval = ""
    # Physical (code) time interval between stat outputs
    #   @type: float
    #   @default: -1.0
    #   @note: When `< 0`, the output is controlled by `interval`
    interval_time = ""
    # Field quantities to output
    #   @type: array<string>
    #   @default: ["B^2", "E^2", "ExB", "Rho", "T00"]
    #   @enum: "B^2", "E^2", "ExB", "N", "Npart", "Charge", "Rho", "T00", "T0i", "Tij"
    #   @note: For particle moments, ...
    #   @note: ... same notation is used as for `output.fields.quantities`
    quantities = ""
    # Custom (user-defined) stats
    #   @type: array<string>
    #   @default: []
    custom = ""

[checkpoint]
  # Number of timesteps between checkpoints
  #   @type: uint [> 0]
  #   @default: 1000
  interval = ""
  # Physical (code) time interval between checkpoints
  #   @type: float [> 0]
  #   @default: -1.0
  #   @note: When `< 0`, the output is controlled by `interval`
  interval_time = ""
  # Number of checkpoints to keep
  #   @type: int
  #   @default: 2
  #   @note: 0 = disable checkpointing
  #   @note: -1 = keep all checkpoints
  keep = ""
  # Write a checkpoint once after a fixed walltime 
  #   @type: string
  #   @default: "00:00:00"
  #   @note: The format is "HH:MM:SS"
  #   @note: Empty string or "00:00:00" disables this functionality
  #   @note: Writing checkpoint at walltime does not stop the simulation
  walltime = ""
  # Parent directory to write checkpoints to
  #   @type: string
  #   @default: `<simname>.ckpt`
  #   @note: The directory is created if it does not exist
  write_path = ""
  # Parent directory to use when resuming from a checkpoint
  #   @type: string
  #   @default: inherit `write_path`
  read_path = ""

  # @inferred:
  # - is_resuming
  #     @brief: Whether the simulation is resuming from a checkpoint
  #     @type: bool
  #     @from: command-line flag
  # - start_step
  #     @brief: Timestep of the checkpoint used to resume
  #     @type: uint
  #     @from: automatically determined during restart
  # - start_time
  #     @brief: Time of the checkpoint used to resume
  #     @type: float
  #     @from: automatically determined during restart

[diagnostics]
  # Number of timesteps between diagnostic logs
  #   @type: int [> 0]
  #   @default: 1
  interval = ""
  # Blocking timers between successive algorithms
  #   @type: bool
  #   @default: false
  blocking_timers = ""
  # Enable colored stdout
  #   @type: bool
  #   @default: true
  colored_stdout = ""
  # Specify the log level
  #   @type: string
  #   @default: "VERBOSE"
  #   @enum: "VERBOSE", "WARNING", "ERROR"
  #   @note: "VERBOSE" prints all messages, "WARNING" prints only warnings and errors, "ERROR" prints only errors
  log_level = ""