Simulation

Cropbox.instance — Function
instance(S; <keyword arguments>) -> S

Make an instance of system S with an initial condition specified in configuration and additional options.

See also: @config, simulate

Arguments

  • S::Type{<:System}: type of system to be instantiated.

Keyword Arguments

  • config=(): configuration containing parameter values for the system.
  • options=(): keyword arguments passed down to the constructor of S; named tuple expected.
  • seed=nothing: random seed initialized before parsing configuration and making an instance.

Examples

julia> @system S(Controller) begin
           a => 1 ~ preserve(parameter)
           b(a) ~ accumulate
       end;

julia> instance(S)
S
  context = <Context>
  config = <Config>
  a = 1.0
  b = 0.0
Cropbox.simulate — Function
simulate([f,] S[, layout, [configs]]; <keyword arguments>) -> DataFrame

Run simulations by making instance of system S with given configuration to generate an output in the form of DataFrame. layout contains a list of variables to be saved in the output. A layout of single simulation can be specified in the layout arguments placed as keyword arguments. configs contains a list of configurations for each run of simulation. Total number of simulation runs equals to the size of configs. For a single configuration, config keyword argument may be preferred. Optional callback function f allows do-block syntax to specify snatch argument for finer control of output format.

See also: instance, @config

Arguments

  • S::Type{<:System}: type of system to be simulated.
  • layout::Vector: list of output layout definition in a named tuple (; base, index, target, meta).
  • configs::Vector: list of configurations for defining multiple runs of simluations.

Keyword Arguments

Layout

  • base=nothing: base system where index and target are populated; default falls back to the instance of S.
  • index=nothing: variables to construct index columns of the output; default falls back to context.clock.time.
  • target=nothing: variables to construct non-index columns of the output; default includes most variables in the root instance.
  • meta=nothing: name of systems in the configuration to be included in the output as metadata.

Configuration

  • config=(): a single configuration for the system, or a base for multiple configurations (when used with configs).
  • configs=[]: multiple configurations for the system.
  • seed=nothing: random seed for resetting each simulation run.

Progress

  • stop=nothing: condition checked before calling updates for the instance; default stops with no update.
  • snap=nothing: condition checked to decide if a snapshot of current update is saved in the output; default snaps all updates.
  • snatch=nothing: callback for modifying intermediate output; list of DataFrame D collected from current update and the instance of system s are provided.
  • verbose=true: shows a progress bar.

Format

  • nounit=false: remove units from the output.
  • long=false: convert output table from wide to long format.

Examples

julia> @system S(Controller) begin
           a => 1 ~ preserve(parameter)
           b(a) ~ accumulate
       end;

julia> simulate(S; stop=1)
2×3 DataFrame
 Row │ time       a        b
     │ Quantity…  Float64  Float64
─────┼─────────────────────────────
   1 │    0.0 hr      1.0      0.0
   2 │    1.0 hr      1.0      1.0
Cropbox.evaluate — Function
evaluate(S, obs; <keyword arguments>) -> Number | Tuple

Compare output of simulation results for the given system S and observation data obs with a choice of evaluation metric.

Arguments

  • S::Type{<:System}: type of system to be evaluated.
  • obs::DataFrame: observation data to be used for evaluation.

Keyword Arguments

Configuration

  • config=(): a single configuration for the system (can't be used with configs).
  • configs=[]: multiple configurations for the system (can't be used with config).

Layout

  • index=nothing: variables to construct index columns of the output; default falls back to context.clock.time.
  • target: variables to construct non-index columns of the output.

Evaluation

  • metric=nothing: evaluation metric (:rmse, :nrmse, :mae, :mape, :ef, :dr); default is RMSE.

Remaining keyword arguments are passed down to simulate with regard to running system S.

See also: simulate, calibrate, @config

Examples

julia> @system S(Controller) begin
           a => 19 ~ preserve(u"m/hr", parameter)
           b(a) ~ accumulate(u"m")
       end;

julia> obs = DataFrame(time=10u"hr", b=200u"m");

julia> configs = @config !(:S => :a => [19, 21]);

julia> evaluate(S, obs; configs, target=:b, stop=10u"hr")
10.0 m
evaluate(obs, est; <keyword arguments>) -> Number | Tuple

Compare observation data obs and estimation data est with a choice of evaluation metric.

Arguments

  • obs::DataFrame: observation data to be used for evaluation.
  • est::DataFrame: estimated data from simulation.

Keyword Arguments

Layout

  • index: variables referring to index columns of the output.
  • target: variables referring to non-index columns of the output.

Evaluation

  • metric=nothing: evaluation metric (:rmse, :nrmse, :mae, :mape, :ef, :dr); default is RMSE.

See also: evaluate

Examples

julia> obs = DataFrame(time = [1, 2, 3]u"hr", b = [10, 20, 30]u"g");

julia> est = DataFrame(time = [1, 2, 3]u"hr", b = [10, 20, 30]u"g", c = [11, 19, 31]u"g");

julia> evaluate(obs, est; index = :time, target = :b)
0.0 g

julia> evaluate(obs, est; index = :time, target = :b => :c)
1.0 g
Cropbox.calibrate — Function
calibrate(S, obs; <keyword arguments>) -> Config | OrderedDict

Obtain a set of parameters for the given system S that simulates provided observation obs closely as possible. A multitude of simulations are conducted with a differing combination of parameter sets specified by the range of possible values and the optimum is selected based on a choice of evaluation metric. Internally, differential evolution algorithm from BlackboxOptim.jl is used.

Arguments

  • S::Type{<:System}: type of system to be calibrated.
  • obs::DataFrame: observation data to be used for calibration.

Keyword Arguments

Configuration

  • config=(): a single base configuration for the system (can't be used with configs).
  • configs=[]: multiple base configurations for the system (can't be used with config).

Layout

  • index=nothing: variables to construct index columns of the output; default falls back to context.clock.time.
  • target: variables to construct non-index columns of the output.

Calibration

  • parameters: parameters with a range of boundary values to be calibrated within.
  • metric=nothing: evaluation metric (:rmse, :nrmse, :mae, :mape, :ef, :dr); default is RMSE.

Multi-objective

  • weight=nothing: weights for calibrating multiple targets; default assumes equal weights.
  • pareto=false: returns a dictionary containing Pareto frontier instead of a single solution satisfying multiple targets.

Advanced

  • optim=(): extra options for BlackBoxOptim.bboptimize.

Remaining keyword arguments are passed down to simulate with regard to running system S.

See also: simulate, evaluate, @config

Examples

julia> @system S(Controller) begin
           a => 0 ~ preserve(parameter)
           b(a) ~ accumulate
       end;

julia> obs = DataFrame(time=10u"hr", b=200);

julia> p = calibrate(S, obs; target=:b, parameters=:S => :a => (0, 100), stop=10)
...
Config for 1 system:
  S
    a = 20.0