input.example.toml

[simulation]
  # Name of the simulation:
  #   @required
  #   @type: string
  #   @example: "MySim"
  #   @note: The name is used for the output files.
  name = ""
  # Simulation engine to use
  #   @required
  #   @type: string
  #   @valid: "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)
    #   @default: MPI_SIZE (MPI)
    number = ""
    # Decomposition of the domain (e.g., for MPI) in each of the directions
    #   @type array of int of size 1, 2 or 3
    #   @example: [2, 2, 2] (for a total of 8 domains)
    #   @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
    decomposition = ""

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

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

  [grid.metric]
    # Metric on the grid
    #   @required
    #   @type: string
    #   @valid: "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 (e.g., x1 = log(r))
    #   @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 (e.g., x2 = th)
    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
    #     @valid: "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: 1/2/3-size array of string tuples, each of size 1 or 2
    #   @valid: "PERIODIC", "ABSORB", "ATMOSPHERE", "CUSTOM", "HORIZON"
    #   @example: [["CUSTOM", "ABSORB"]] (for 2D spherical [[rmin, rmax]])
    #   @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"]]
    fields = ""
    # Boundary conditions for fields:
    #   @required
    #   @type: 1/2/3-size array of string tuples, each of size 1 or 2
    #   @valid: "PERIODIC", "ABSORB", "ATMOSPHERE", "CUSTOM", "REFLECT", "HORIZON"
    #   @example: [["PERIODIC"], ["PERIODIC"]]
    #   @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"]]
    particles = ""
    
    [grid.boundaries.absorb]
      # Size of the absorption layer 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 = ""
      # Absorption coefficient for fields:
      #   @type: float: -inf < ... < inf, != 0
      #   @default: 1.0
      coeff = ""

    [grid.boundaries.atmosphere]
    # @required: if ATMOSPHERE is one of the boundaries
      # Temperature of the atmosphere in units of m0 c^2
      #   @type: float
      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 of ints of 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 [= temperature / height]
      #     @brief: Acceleration due to imposed gravity
      #     @type: float
      #     @from: `grid.boundaries.atmosphere.temperature`, `grid.boundaries.atmosphere.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 [= ppc0 / V0]
  #     @brief: Fiducial number density
  #     @type: float
  #     @from: `particles.ppc0`, `grid`
  # - q0 [= 1 / (n0 * skindepth0^2)]
  #     @brief: Fiducial elementary charge
  #     @type: float
  #     @from: `scales.skindepth0`, `scales.n0`
  # - sigma0 [= (skindepth0 / larmor0)^2]
  #     @brief: Fiducial magnetization parameter
  #     @type: float
  #     @from: `scales.larmor0`, `scales.skindepth0`
  # - B0 [= 1 / larmor0]
  #     @brief: Fiducial magnetic field
  #     @type: float
  #     @from: `scales.larmor0`
  # - omegaB0 [= 1 / larmor0]
  #     @brief: Fiducial cyclotron frequency
  #     @type: float
  #     @from: `scales.larmor0`

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

  [algorithms.toggles]
    # Toggle for the field solver:
    #   @type bool
    #   @default: true
    fieldsolver = ""
    # Toggle for the current deposition:
    #   @type bool
    #   @default: true
    deposit = ""

  [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: ~1
    #   @default: 1.0
    correction = ""
    
    # @inferred:
    # - dt [= CFL * dx0]
    #     @brief: timestep duration
    #     @type: float

  [algorithms.gr]
    # Stepsize for numerical differentiation in GR pusher:
    #   @type: float: > 0
    #   @default: 1e-6
    pusher_eps = ""
    # Number of iterations for the Newton-Raphson method in GR pusher:
    #   @type: unsigned short: > 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: > 0
    #   @default: 0.0
    #   @note: When `larmor_max` == 0, the limit is disabled
    larmor_max = ""

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

[particles]
  # Fiducial number of particles per cell:
  #   @required
  #   @type: float: > 0
  ppc0 = ""
  # Toggle for using particle weights:
  #   @type: bool
  #   @default: false
  use_weights = ""
  # Timesteps between particle re-sorting:
  #   @type: unsigned int: >= 0
  #   @default: 100
  #   @note: When MPI is enable, particles are sorted every step.
  #   @note: When `sort_interval` == 0, the sorting is disabled.
  sort_interval = ""

  # @inferred:
  # - nspec
  #     @brief: Number of particle species
  #     @type: unsigned int
  #     @from: `particles.species`
  # - species
  #     @brief: An object containing information about all the species
  #     @type: vector of ParticleSpecies
  #     @from: `particles.species`

  [[particles.species]]
    # Label of the species:
    #   @type: string
    #   @default: "s*" (where "*" is the species index starting at 1)
    #   @example: "e-"
    label = ""
    # Mass of the species (in units of fiducial mass):
    #   @required
    #   @type: float
    mass = ""
    # Charge of the species (in units of fiducial charge):
    #   @required
    #   @type: float
    charge = ""
    # Maximum number of particles per task:
    #   @required
    #   @type: unsigned int: > 0
    maxnpart = ""
    # Pusher algorithm for the species:
    #   @type: string
    #   @default: "Boris" for massive and "Photon" for massless
    #   @valid: "Boris", "Vay", "Boris,GCA", "Vay,GCA", "Photon", "None"
    pusher = ""
    # Number of additional (payload) variables for each particle of the given species:
    #   @type: unsigned short: >= 0
    #   @default: 0
    n_payloads = ""
    # Radiation reaction to use for the species:
    #   @type: string
    #   @default: "None"
    #   @valid: "None", "Synchrotron"
    cooling = ""

# Parameters for specific problem generators and setups:
[setup]

[output]
  # Output format:
  #   @type: string
  #   @valid: "disabled", "hdf5", "BPFile"
  #   @default: "hdf5"
  format = ""
  # Number of timesteps between all outputs (overriden by specific output interval below):
  #   @type: unsigned int: > 0
  #   @default: 1
  interval = ""
  # Physical (code) time interval between all outputs (overriden by specific output intervals below):
  #   @type: float: > 0
  #   @default: -1.0 (disabled)
  #   @note: When `interval_time` < 0, the output is controlled by `interval`, otherwise by `interval_time`
  interval_time = ""

  [output.fields]
    # Toggle for the field output:
    #   @type: bool
    #   @default: true
    enable = ""
    # Field quantities to output:
    #   @type: array of strings
    #   @valid: fields: "E", "B", "J", "divE"
    #   @valid: moments: "Rho", "Charge", "N", "Nppc", "T0i", "Tij"
    #   @valid: for GR: "D", "H", "divD", "A"
    #   @default: []
    #   @note: For T, you can use unspecified indices, e.g., Tij, T0i, or specific ones, e.g., 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: e.g., Ttt_1_2, Rho_1, Rho_3_4
    quantities = ""
    # Custom (user-defined) field quantities:
    #   @type: array of strings
    #   @default: []
    custom = ""
    # @NOT_IMPLEMENTED: Stride for the output of fields:
    #   @type: unsigned short: > 1
    #   @default: 1
    stride = ""
    # Smoothing window for the output of moments (e.g., "Rho", "Charge", "T", etc.):
    #   @type: unsigned short: >= 0
    #   @default: 0
    mom_smooth = ""
    # Number of timesteps between field outputs (overrides `output.interval`):
    #   @type: unsigned int: > 0
    #   @default: 0 (use `output.interval`)
    interval = ""
    # Physical (code) time interval between field outputs (overrides `output.interval_time`):
    #   @type: float: > 0
    #   @default: -1.0 (use `output.interval_time`)
    #   @note: When `interval_time` < 0, the output is controlled by `interval`, otherwise by `interval_time`
    interval_time = ""

  [output.particles]
    # Toggle for the particles output:
    #   @type: bool
    #   @default: true
    enable = ""
    # Particle species indices to output:
    #   @type: array of ints
    #   @default: [] = all species
    species = ""
    # Stride for the output of particles:
    #   @type: unsigned int: > 1
    #   @default: 100
    stride = ""
    # Number of timesteps between particle outputs (overrides `output.interval`):
    #   @type: unsigned int: > 0
    #   @default: 0 (use `output.interval`)
    interval = ""
    # Physical (code) time interval between field outputs (overrides `output.interval_time`):
    #   @type: float: > 0
    #   @default: -1.0 (use `output.interval_time`)
    #   @note: When `interval_time` < 0, the output is controlled by `interval`, otherwise by `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: unsigned int: > 0
    #   @default: 200
    n_bins = ""
    # Number of timesteps between spectra outputs (overrides `output.interval`):
    #   @type: unsigned int: > 0
    #   @default: 0 (use `output.interval`)
    interval = ""
    # Physical (code) time interval between spectra outputs (overrides `output.interval_time`):
    #   @type: float: > 0
    #   @default: -1.0 (use `output.interval_time`)
    #   @note: When `interval_time` < 0, the output is controlled by `interval`, otherwise by `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 = ""

[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 = ""