simulate.ron

(
    /* per-individual per-generation probability that an individual speciates
     *  i.e. is the creator of a new unique species */
    speciation: (0.0 < f64 <= 1.0),
    /* selection of the sample of individuals that are simulatd
     * optional, default = Sample(percentage: 1.0, origin: Habitat, mode: Genesis) */
    sample: Sample(
        /* percentage of individuals from the sample that are simulated
         * optional, default = 1.0 */
        percentage: (0.0 <= f64 <= 1.0),
        /* selection of the base sample of individuals
         * optional, default = Habitat */
        origin: (
            /* all individuals living inside the habitat are sampled
             * only compatible with mode = Genesis */
          | Habitat
            /* ordered set of individuals that are sampled */
          | List([
                Lineage(
                    /* UNIQUE reference of the individual */
                    ref: (u64),
                    /* time of the last event, 0.0 before the simulation */
                    time: (0.0 <= f64),
                    /* indexed location i@(x, y) of the individual */
                    loc: (
                        x: (u32),
                        y: (u32),
                        i: (u32),
                    ),
                )
            ])
            /* binary file containing an ordered set of individuals that
             *  are sampled */
          | Bincode(
                /* file path to a binary file listing the individuals */
                file: (PathBuf)
            )
        ),
        /* selection of the simulation initialisation mode
         * optional, default = Genesis */
        mode: (
            /* the simulation starts from the beginning with all individuals
             * only compatible with origin = Habitat */
          | Genesis
            /* WARNING: should only be used to resume a previously paused simulation
             *          WITHOUT changing the simulation parameters (the log and
             *           reporters can be changed without issues)
             *          OTHERWISE new events may occur before the previous pause
             *           timestamp
             *
             * resume the simulation from the given sample of individuals
             * ensures perfect continuity of the simulation, i.e. pausing + resuming
             *  has no effect on the simulation result */
          | Resume
            /* fix-up the given sample of individuals for a simulation restart
             * should be used to resume after the simulation parameters have been changed
             * breaks continuity of the simulation, i.e. pausing + fix-up + restarting
             *  affects the simulation result, but allows reconfiguration
             * requires an immediate pause at the same time as the original pause */
          | FixUp(
                /* selection of how to handle individuals at a valid location that is
                 *  already occupied by too many other individuals, i.e. the deme is full
                 * optional, default = Abort */
                out_of_deme: (
                    /* Abort the simulation during configuration before it runs */
                  | Abort
                    /* Simulate one event to speciate, or to get the individual back into
                     *  a valid habitable location and deme */
                  | Dispersal
                ),
                /* selection of how to handle individuals at an inhabitable location
                 * optional, default = Abort */
                out_of_habitat: (
                    /* Abort the simulation during configuration before it runs */
                  | Abort
                    /* Simulate one event to speciate, or to get the individual back into
                     *  ANY uniformly selected habitable location and deme */
                  | UniformDispersal
                ),
                /* selection of how to handle individuals at a valid location-index pair
                  *  that is already occupied by another individual, i.e. where these
                  *  individuals should have (already) coalesced during the simulation
                  * optional, default = Abort */
                coalescence: (
                    /* Abort the simulation during configuration before it runs */
                  | Abort
                    /* Output an immediate coalescence event to resolve the duplication */
                  | Coalescence
                ),
            )
            /* restart the simulation from the given sample of individuals
             * should be used to resume after the simulation parameters have been changed
             *  and the individuals have been fixed-up
             * breaks continuity of the simulation, i.e. pausing + restarting affects the
             *  simulation result, but allows reconfiguration */
          | Restart(
                /* the event timestamp from which to simulate (exclusive)
                 * must match the timestamp previously used to pause the simulation */
                after: (0.0 <= f64),
            )
        ),
    ),
    /* selection of whether the simulation should pause before completing
     * optional, default = None */
    pause: (
        /* the simulation will run until completion */
      | None
        /* the simulation will pause right before the time `before`
         * all events before `before` will be reported, but none at or after */
      | Pause(
            /* the event timestamp until which to simulate (exclusive)
             * pausing before 0.0 simply samples the individuals but does not
             *  simulate them, e.g. to write all initial individuals to a file
             * pausing before a fix-up and restart must be after 0.0 */
            before: (0.0 <= f64),
            /* path where a new configuration file will be created
             * from which the simulation can be resumed seamlessly */
            config: (PathBuf),
            /* selection of the output of the remaining individuals */
            destiny: (
                /* the remaining individuals will be listed literally inside the
                 *  new configuration file */
              | List
                /* the remaining individuals will be written to a new binary file
                 * only compatible with sample.origin = List */
              | Bincode(
                    /* file path to where the new binary file listing the remaining
                     *  individuals will be written */
                    file: (PathBuf),
                )
            ),
            /* selection of the pause mode, which affects how the simulation is
             *  resumed afterwards
             * optional, default = Resume */
            mode: (
                /* the simulation can be resumed with continuity after the pause
                 * no changes in configuration should be made */
              | Resume
                /* the simulation will first be fixed-up after the pause
                 * inconsistencies through a change in configuration are fixed */
              | FixUp
                /* the simulation can be restarted without continuity after the
                 *  pause
                 * used to continue the simulation directly after a FixUp */
              | Restart
            ),
        )
    ),
    /* selection of the initialisation of the random number generator */
    rng: (
        /* seeds from OS-provided randomness
         * forbidden for partitioned simulations
         * infallible for monolithic simulations (unless the OS malfunctions) */
      | Entropy
        /* seeds based on the given 64bit seed
         * infallible */
      | Seed(u64)
        /* seeds based on the given base32-string, which goes through a
         *  sponge function to fit the RNG's seed size
         * fails if the base32-string is actually an RNG state
         *  (safeguards confusing State and Sponge, unlikely by accident) */
      | Sponge(Base32)
        /* tries to set the RNG's state from the given base32-string
         * fails if the the base32-string is not a valid RNG state
         *  (use only for resuming a paused + unchanged simulation)
         *  (must come from the same RNG that the simulation was paused with) */
      | State(Base32)
        /* combination of the State and Sponge initialisation methods
         *  (a) try the State initialisation
         *  (b) on failure, use the Sponge initialisation
         * fails if the base32-string could not have come from a paused RNG */
      | StateElseSponge(Base32)
    ),

    /* selection of the scenario which will be simulated */
    scenario: (
        /* spatially explicit scenario using habitat (and optionally turnover) and dispersal maps */
      | SpatiallyExplicit(
            /* file path to a (WxH) TIFF file storing grayscale u32 habitat values */
            habitat: (PathBuf),
            /* file path to a (WxH x WxH) TIFF file storing grayscale f64 dispersal weights
             * the ith row of the image stores dispersal from the habitat cell (i % W, i / W) */
            dispersal: (PathBuf),
            /* selection of the turnover rate source
             * optional, default = Uniform(0.5) */
            turnover: (
                /* uniform positive turnover rate
                 * requires the `spatially-explicit-uniform-turnover-scenario` feature */
              | Uniform(0.0 < f64)
                /* file path to (WxH) TIFF file storing grayscale f64 turnover rates
                 * requires the `spatially-explicit-turnover-map-scenario` feature */
              | Map(PathBuf)
            ),
            /* selection of the map loading mode
             * optional, default = OffByOne */
            mode: (
                /* Fixes GDAL no-data value, habitat 0/1 rounding errors, zero turnover habitat,
                 *  and dispersal from/to non-habitat */
              | FixMe
                /* Fixes GDAL no-data value and habitat 0/1 rounding errors */
              | OffByOne
                /* Does not fix any habitat-dispersal discrepancies */
              | Strict
            ),
        )
        /* non-spatial scenario with homogeneous dispersal and a community size of
         *  (area.0 * area.1 * deme) 
         * requires the `non-spatial-scenario` feature */
      | NonSpatial(
            /* width and height of the non-spatial landscape */
            area: (1 <= u64 <= 2^32, 1 <= u64 <= 2^32),
            /* number of individuals which can live at the same habitat location */
            deme: (0 < u32),
        )
        /* spatially-implicit scenario with a non-spatial local and a non-spatial meta community
         *  and dynamic migration from the meta to the local community
         * requires the `spatially-implicit-scenario` feature */
      | SpatiallyImplicit(
            /* width and height of the non-spatial local landscape */
            local_area: (1 <= u64 <= 2^32, 1 <= u64 <= 2^32),
            /* number of individuals which can live at the same local habitat location */
            local_deme: (0 < u32),
            /* width and height of the non-spatial meta landscape */
            meta_area: (1 <= u64 <= 2^32, 1 <= u64 <= 2^32),
            /* number of individuals which can live at the same meta habitat location */
            meta_deme: (0 < u32),
            /* per-individual per-generation probability that the parent of an individual
             *  in the local community migrated from the meta community */
            migration: (0.0 < f64 <= 1.0),
        )
        /* (almost) infinite spatially-explicit scenario
         * the entire infinite landscape is habitat but, without loss of generality, has deme 1
         * the landscape is on a (wrapping) torus with 0 <= x < 2^32 and 0 <= y < 2^32 */
      | AlmostInfinite(
            /* selection of the sample area, individuals living in here are simulated
             * the sample area can wrap around the torus */
            sample: (
                /* circular sample area */
              | Circle(
                    /* centre (x, y) of the circle
                     * optional, default = (x: 2147483647, y: 2147483647)
                     *  note that 2147483647 = 2^31 - 1 */
                    centre: (
                        x: (u32),
                        y: (u32),
                    ),
                    /* radius of the circle */
                    radius: (u16),
                )
                /* rectangular sample area */
              | Rectangle(
                    /* lower-left origin of the sample area */
                    origin: (
                        x: (u32),
                        y: (u32),
                    ),
                    /* width of the sample area */
                    width: (1 <= u64 <= 2^32),
                    /* height of the sample area */
                    height: (1 <= u64 <= 2^32),
                )
            ),
            /* selection of the dispersal kernel */
            dispersal: (
                /* Gaussian Normal dispersal kernel N(0, sigma^2)
                 * requires the `almost-infinite-normal-dispersal-scenario` feature */
              | Normal(
                    /* sigma for the Gaussian dispersal kernel */
                    sigma: (0.0 <= f64),
                )
                /* Clark2Dt dispersal kernel
                 * requires the `almost-infinite-clark2dt-dispersal-scenario` feature */
              | Clark2Dt(
                    /* shape (u) for the Clark 2Dt dispersal kernel */
                    shape_u: (0.0 < f64),
                    /* tail (p) for the Clark 2Dt dispersal kernel
                     *  - Clark 2Dt dispersal tends to Gaussian as p becomes large
                     *  - Clark 2Dt dispersal tends to Cauchy as p goes to zero
                     * optional, default = 1.0 */
                    tail_p: (0.0 < f64),
                )
            ),
        )
        /* (almost) infinite spatially-explicit scenario with (approximate) Gaussian distributed dispersal
         * each location (x, y) in the landscape has either habitat for exactly one individual,
         *  or is inhabitable, depending on a sample from an OpenSimplexNoise
         * the landscape is on a (wrapping) torus with 0 <= x < 2^32 and 0 <= y < 2^32
         * requires the `wrapping-noise-scenario` feature */
      | WrappingNoise(
            /* random seed for the noise */
            seed: (i64),
            /* percentage of the habitat that will be habitable */
            coverage: (0.0 <= f64 <= 1.0),
            /* scale of the noise, is doubled on each octave
             * choose 0.025 for a reasonable default */
            scale: (0.0 < f64 <= 1.0),
            /* geometric persistence factor for noise amplitude across octaves
             * choose 0.5 for a reasonable default */
            persistence: (0.0 < f64 <= 1.0),
            /* number of noise octaves that are accumulated for each sample
             * a larger number of octaves provides finer-grained habitat boundaries
             *  but is less efficient to simulate
             * choose 1 for only one noise sample per location and maximum efficiency */
            octaves: (0 < usize),
            /* rectangular sample area, individuals living in here are simulated
             * the sample area can wrap around the torus */
            sample: Rectangle(
                /* lower-left origin of the sample area */
                origin: (
                    x: (u32),
                    y: (u32),
                ),
                /* width of the sample area */
                width: (1 <= u64 <= 2^32),
                /* height of the sample area */
                height: (1 <= u64 <= 2^32),
            ),
            /* sigma for the Gaussian dispersal kernel N(0, sigma^2) */
            sigma: (0.0 <= f64),
        )
    ),

    /* selection of the coalescence algorithm which is used */
    algorithm: (
        /* monolithic; optimised for low self-dispersal (i.e. small demes); CPU-based
         * requires the `gillespie-algorithms` feature */
      | Gillespie(
            /* selection of how the algorithm should be parallelised across partitions
             * optional, dynamic default = Monolithic / Lockstep */
            parallelism_mode: (
                /* no parallelisation, the algorithm runs on a single partition only
                 * invalid when the simulation is internally parallelised */
              | Monolithic
                /* (1) simulate each partition independently for some delta_sync
                 * (2) check if any (unknown) migrations between partitions occured
                 *     (a) if yes, roll back and try again with >= 1 more known migration
                 *     (b) if no, exit the repetition
                 * (3) designate the past delta_sync as the last safe point
                 * (4) repeat with the next delta_sync until finished
                 *
                 * invalid when the simulation is NOT internally parallelised */
              | Optimistic(
                    /* simulation time between safe points */
                    delta_sync: (0.0 < f64),
                )
                /* (1) vote on which partition has the earliest next event
                 * (2) advance this partition by one step
                 * (3) repeat until finished
                 *
                 * invalid when the simulation is NOT internally parallelised */
              | Lockstep
                /* (1) simulate each partition independently until their next emigration
                 * (2) vote on which partition has the earliest emigration event
                 * (3) roll back and simulate exactly until and including this first migration
                 * (4) repeat until finished
                 *
                 * invalid when the simulation is NOT internally parallelised */
              | OptimisticLockstep
                /* WARNING: may produce inaccurate results
                 *
                 * (1) simulate each partition independently for some delta_sync
                 * (2) perform all migrations simultaneously at this synchronisation point
                 * (3) repeat until finished
                 *
                 * invalid when the simulation is NOT internally parallelised */
              | Averaging(
                    delta_sync: (0.0 < f64),
                )
            )
        )
        /* monolithic; skips no-coalescence self-dispersal events -> optimised for high
         *  self-dispersal (i.e. large demes); CPU-based
         * requires the `gillespie-algorithms` feature */
      | EventSkipping(
            /* selection of how the algorithm should be parallelised across partitions
             * optional, dynamic default = Monolithic / Lockstep */
            parallelism_mode: (
                /* no parallelisation, the algorithm runs on a single partition only
                 * invalid when the simulation is internally parallelised */
              | Monolithic
                /* (1) simulate each partition independently for some delta_sync
                 * (2) check if any (unknown) migrations between partitions occured
                 *     (a) if yes, roll back and try again with >= 1 more known migration
                 *     (b) if no, exit the repetition
                 * (3) designate the past delta_sync as the last safe point
                 * (4) repeat with the next delta_sync until finished
                 *
                 * invalid when the simulation is NOT internally parallelised */
              | Optimistic(
                    /* simulation time between safe points */
                    delta_sync: (0.0 < f64),
                )
                /* (1) vote on which partition has the earliest next event
                 * (2) advance this partition by one step
                 * (3) repeat until finished
                 *
                 * invalid when the simulation is NOT internally parallelised */
              | Lockstep
                /* (1) simulate each partition independently until their next emigration
                 * (2) vote on which partition has the earliest emigration event
                 * (3) roll back and simulate exactly until and including this first migration
                 * (4) repeat until finished
                 *
                 * invalid when the simulation is NOT internally parallelised */
              | OptimisticLockstep
                /* WARNING: may produce inaccurate results
                 *
                 * (1) simulate each partition independently for some delta_sync
                 * (2) perform all migrations simultaneously at this synchronisation point
                 * (3) repeat until finished
                 *
                 * invalid when the simulation is NOT internally parallelised */
              | Averaging(
                    delta_sync: (0.0 < f64),
                )
            )
        )
        /* independent; simulates each individual without knowledge of others; CPU-based
         * requires the `independent-algorithm` feature */
      | Independent(
            /* simulation time between random number generator repriming
             *  -> lower deltas require fewer draws to pick the time of the next event
             *  -> higher deltas require fewer reprimings to pick the time of the next event
             * WARNING: changes the result of a particular simulation run
             * optional, default = 2.0 */
            delta_t: (0.0 < f64),
            /* number of steps which an individual performs on the CPU without supervision
             *  -> shorter slices enable quicker termination of single individuals
             * optional, default = 10 */
            step_slice: (0 < u64),
            /* Selection of the mode of the individual deduplication cache
             * optional, default = Relative(factor: 1.0) */
            dedup_cache: (
                /* cache has an absolute maximum capacity */
              | Absolute(
                    /* absolute capacity of the cache */
                    capacity: (0 < usize),
                )
                /* cache has a relative maximum capacity */
              | Relative(
                    /* capacity is the initial number of individuals * factor */
                    factor: (0.0 < f64),
                )
                /* individual deduplication is disabled */
              | None
            ),
            /* selection of the mode in which the simulation is parallelised
             * optional, dynamic default = Monolithic(event_slice: Relative(factor: 2.0))
             *                           / Probabilistic(communication: 0.25) */
            parallelism_mode: (
                /* no partitioning occurs
                 * invalid when the simulation is internally parallelised */
              | Monolithic(
                    /* average number of events between flushing the event buffer */
                    event_slice: (
                        /* absolute number of events between flushing */
                      | Absolute(
                            /* absolute capacity of the event buffer */
                            capacity: (0 < usize),
                        )
                        /* relative number of events between flushing */
                      | Relative(
                            /* capacity is the initial number of individuals * factor */
                            factor: (0.0 < f64),
                        )
                    ),
                )
                /* partition the initial set of individuals
                 * no individuals are migrated between partitions
                 * does not coordinate with other partitions
                 * only simulates a single partition which does not communicate at all
                 * invalid when the simulation is internally parallelised */
              | IsolatedIndividuals(
                    /* selection of the single partition that will be simulated */
                    partition: Partition(
                        rank: (u32 < size),
                        size: (0 < u32),
                    ),
                    /* average number of events between flushing the event buffer */
                    event_slice: (
                        /* absolute number of events between flushing */
                      | Absolute(
                            /* absolute capacity of the event buffer */
                            capacity: (0 < usize),
                        )
                        /* relative number of events between flushing */
                      | Relative(
                            /* capacity is the initial number of individuals * factor */
                            factor: (0.0 < f64),
                        )
                    ),
                )
                /* partition the original set of individuals
                 * optimised for intra-partition spatial locality
                 * no individuals are migrated between partitions
                 * does not coordinate with other partitions
                 * only simulates a single partition which does not communicate at all
                 * invalid when the simulation is internally parallelised */
              | IsolatedLandscape(
                    /* selection of the single partition that will be simulated */
                    partition: Partition(
                        rank: (u32 < size),
                        size: (0 < u32),
                    ),
                    /* average number of events between flushing the event buffer */
                    event_slice: (
                        /* absolute number of events between flushing */
                      | Absolute(
                            /* absolute capacity of the event buffer */
                            capacity: (0 < usize),
                        )
                        /* relative number of events between flushing */
                      | Relative(
                            /* capacity is the initial number of individuals * factor */
                            factor: (0.0 < f64),
                        )
                    ),
                )
                /* partition the initial set of individuals
                 * no individuals are migrated between partitions
                 * automatically coordinates between partitions
                 * communication between partitions only occurs for progress measuring
                 * invalid when the simulation is NOT internally parallelised */
              | Individuals
                /* partition the landscape
                 * individuals naturally migrate between partitions
                 * automatically coordinates between partitions
                 * communication between partitions occurs mostly for migration
                 * invalid when the simulation is NOT internally parallelised */
              | Landscape
                /* like Landscape but only migrates individuals at random intervals
                 *  to minimise the communication overhead
                 * invalid when the simulation is NOT internally parallelised */
              | Probabilistic(
                    /* probability with which a migration incurs communication
                     * otherwise the individual just stays in its current partition */
                    communication: (0.0 <= f64 <= 1.0),
                )
            )
        )
        /* independent; simulates each individual without knowledge of others; CUDA GPU-based
         * requires the `cuda-algorithm` feature */
      | CUDA(
            /* index of the CUDA GPU device on which the simulation will be run
             * optional, default = 0 */
            device: (u32),
            /* if true, enables just-in-time compilation of the simulation parameters into
             *  the CUDA kernel
             * optional, default = true */
            ptx_jit: (bool),
            /* simulation time between random number generator repriming
             *  -> lower deltas require fewer draws to pick the time of the next event
             *  -> higher deltas require fewer reprimings to pick the time of the next event
             * WARNING: changes the result of a particular simulation run
             * optional, default = 3.0 */
            delta_t: (0.0 < f64),
            /* CUDA thread block 1D size, should be a power of 2
             * optional, default = 64 */
            block_size: (0 < u32),
            /* CUDA thread grid 1D size, should be a power of 2
             * optional, default = 64 */
            grid_size: (0 < u32),
            /* number of steps which an individual performs on the GPU without supervision
             *  -> shorter slices enable quicker termination of single individuals
             *  -> longer slices incur less overhead from kernel launches
             * optional, default = 150 */
            step_slice: (0 < u64),
            /* selection of the mode of the individual deduplication cache
             * optional, default = Relative(factor: 0.1) */
            dedup_cache: (
                /* cache has an absolute maximum capacity */
              | Absolute(
                    /* absolute capacity of the cache */
                    capacity: (0 < usize),
                )
                /* cache has a relative maximum capacity */
              | Relative(
                    /* capacity is the initial number of individuals * factor */
                    factor: (0.0 < f64),
                )
                /* individual deduplication is disabled */
              | None
            ),
            /* selection of the mode in which the simulation is parallelised
             * optional, default = Monolithic(event_slice: Relative(factor: 20.0)) */
            parallelism_mode: (
                /* no partitioning occurs
                 * invalid when the simulation is internally parallelised */
              | Monolithic(
                    /* average number of events between flushing the event buffer */
                    event_slice: (
                        /* absolute number of events between flushing */
                      | Absolute(
                            /* absolute capacity of the event buffer */
                            capacity: (0 < usize),
                        )
                        /* relative number of events between flushing */
                      | Relative(
                            /* capacity is the initial number of individuals * factor */
                            factor: (0.0 < f64),
                        )
                    ),
                )
                /* partition the initial set of individuals
                 * no individuals are migrated between partitions
                 * does not coordinate with other partitions
                 * only simulates a single partition which does not communicate at all
                 * invalid when the simulation is internally parallelised */
              | IsolatedIndividuals(
                    /* selection of the single partition that will be simulated */
                    partition: Partition(
                        rank: (u32 < size),
                        size: (0 < u32),
                    ),
                    /* average number of events between flushing the event buffer */
                    event_slice: (
                        /* absolute number of events between flushing */
                      | Absolute(
                            /* absolute capacity of the event buffer */
                            capacity: (0 < usize),
                        )
                        /* relative number of events between flushing */
                      | Relative(
                            /* capacity is the initial number of individuals * factor */
                            factor: (0.0 < f64),
                        )
                    ),
                )
                /* partition the original set of individuals
                 * optimised for intra-partition spatial locality
                 * no individuals are migrated between partitions
                 * does not coordinate with other partitions
                 * only simulates a single partition which does not communicate at all
                 * invalid when the simulation is internally parallelised */
              | IsolatedLandscape(
                    /* selection of the single partition that will be simulated */
                    partition: Partition(
                        rank: (u32 < size),
                        size: (0 < u32),
                    ),
                    /* average number of events between flushing the event buffer */
                    event_slice: (
                        /* absolute number of events between flushing */
                      | Absolute(
                            /* absolute capacity of the event buffer */
                            capacity: (0 < usize),
                        )
                        /* relative number of events between flushing */
                      | Relative(
                            /* capacity is the initial number of individuals * factor */
                            factor: (0.0 < f64),
                        )
                    ),
                )
            )
        )
    ),

    /* selection of the simulation partitioning strategy
     * optional, default = Monolithic */
    partitioning: (
        /* the entire simulation is processed at once
         * single-threaded, single-process */
      | Monolithic()
        /* the simulation is divided up inside an MPI universe
         * single-threaded, multi-process
         * requires the `mpi-partitioning` feature */
      | MPI(
            /* explicit size of the MPI universe, must match the MPI universe
             * optional, dynamic default = MPI's world size */
            world: (1 < u32),
            /* minimum time interval between migration messages
             * optional, default = "100ms" */
            migration: (DurationString),
            /* minimum time interval between progress messages
             * optional, default = "100ms" */
            progress: (DurationString),
        )
        /* the simulation is divided up across multiple threads, which
            communicate using message passing and may share immutable data
         * multi-threaded, single-process
         * requires the `threads-partitioning` feature */
      | Threads(
            /* number of threads to distribute the simulation across */
            threads: (1 < u32),
            /* minimum time interval between migration messages
             * optional, default = "100ms" */
            migration: (DurationString),
            /* minimum time interval between progress messages
             * optional, default = "100ms" */
            progress: (DurationString),
            /* minimum time duration to wait after each progress message
             *  before checking if any of the thread partitions has panicked
             * optional, default = "200ms" */
            panic: (DurationString),
        )
    ),

    /* selection of the event persistence strategy
     * optional, default = None */
    log: (
        /* events are reported live but not persisted to disk
         * invalid when the simulation is internally parallelised */
      | None
        /* events are not reported live, but saved on disk
         *  so that they can be replayed later
         * required when the simulation is paused or resumed
         * required when the simulation is internally parellelised */
      | EventLog(
            /* file path to a directory in which a log of all events will be saved */
            directory: (PathBuf),
            /* event capacity of each log segment
             * optional, default = 1000000 */
            capacity: (0 < usize),
        )
    ),

    /* selection of the reporters which will analyse the simulation
     *
     * the selection will determine which events are produced during the simulation
     *  and stored in the log, if one is specified */
    reporters: [
        /* loads a single dynamic reporter plugin */
        Plugin(
            /* path to the dynamic library which defined the plugin */
            library: (PathBuf),
            /* selection of the reporters defined by this plugin */
            reporters: [
                /* initialisation of a single reporter named 'ReporterName'
                 *  with arguments args.. */
                ReporterName(args..)
            ]
        )
    ],
)