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: 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

source

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

source

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

source

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

source