Reference Guide: The Mimi API

defcomp(comp_name::Symbol, ex::Expr)

Define a Mimi component comp_name with the expressions in ex. The following types of expressions are supported:

1. dimension_name = Index() # defines a dimension
2. parameter = Parameter(index = [dimension_name], units = "unit_name", default = default_value) # defines a parameter with optional arguments
3. variable = Variable(index = [dimension_name], units = "unit_name") # defines a variable with optional arguments
4. init(p, v, d) # defines an init function for the component
5. run_timestep(p, v, d, t) # defines a run_timestep function for the component

Parses a @defcomp definition, converting it into a series of function calls that create the corresponding ComponentDef instance. At model build time, the ModelDef (including its ComponentDefs) will be converted to a runnable model.

MarginalModel

A Mimi Model whose results are obtained by subtracting results of one base Model from those of another marginal Model that has a difference of delta.

Model

A user-facing API containing a ModelInstance (mi) and a ModelDef (md). This Model can be created with the optional keyword argument number_type indicating the default type of number used for the ModelDef. If not specified the Model assumes a number_type of Float64.

add_comp!(
    obj::AbstractCompositeComponentDef,
    comp_def::AbstractComponentDef,
    comp_name::Symbol=comp_def.comp_id.comp_name;
    before::NothingSymbol=nothing,
    after::NothingSymbol=nothing,
    rename::NothingPairList=nothing
)

Add the component comp_def to the composite component indicated by obj. The component is added at the end of the list unless one of the keywords before or after is specified. Note that a copy of comp_id is made in the composite and assigned the give name. The optional argument rename can be a list of pairs indicating original_name => imported_name.

add_comp!(
    obj::AbstractCompositeComponentDef,
    comp_id::ComponentId,
    comp_name::Symbol=comp_id.comp_name;
    before::NothingSymbol=nothing,
    after::NothingSymbol=nothing,
    rename::NothingPairList=nothing
)

Add the component indicated by comp_id to the composite component indicated by obj. The component is added at the end of the list unless one of the keywords before or after is specified. Note that a copy of comp_id is made in the composite and assigned the give name.

[Not yet implemented:] The optional argument rename can be a list of pairs indicating original_name => imported_name.

add_comp!(obj::AbstractCompositeComponentInstance, ci::AbstractComponentInstance)

Add the (leaf or composite) component ci to a composite's list of components.

add_comp!(
    m::Model, comp_id::ComponentId, comp_name::Symbol=comp_id.comp_name;
    before::NothingSymbol=nothing,
    after::NothingSymbol=nothing,
    rename::NothingPairList=nothing
)

Add the component indicated by comp_id to the model indicated by m. The component is added at the end of the list unless one of the keywords before or after is specified. Note that a copy of comp_id is made in the composite and assigned the give name. The optional argument rename can be a list of pairs indicating original_name => imported_name.

add_comp!(
    m::Model, comp_def::AbstractComponentDef, comp_name::Symbol=comp_id.comp_name;
    before::NothingSymbol=nothing,
    after::NothingSymbol=nothing,
    rename::NothingPairList=nothing
)

Add the component comp_def to the model indicated by m. The component is added at the end of the list unless one of the keywords, first, last, before, after. Note that a copy of comp_id is made in the composite and assigned the give name. The optional argument rename can be a list of pairs indicating original_name => imported_name.

connect_param!(obj::AbstractCompositeComponentDef, comp_name::Symbol, param_name::Symbol, ext_param_name::Symbol;
               check_labels::Bool=true)

Connect a parameter param_name in the component comp_name of composite obj to the external parameter ext_param_name.

connect_param!(obj::AbstractCompositeComponentDef,
    dst::Pair{Symbol, Symbol}, src::Pair{Symbol, Symbol},
    backup::Union{Nothing, Array}=nothing;
    ignoreunits::Bool=false, offset::Int=0)

Bind the parameter dst[2] of one component dst[1] of composite obj to a variable src[2] in another component src[1] of the same composite using backup to provide default values and the ignoreunits flag to indicate the need to check match units between the two. The offset argument indicates the offset between the destination and the source ie. the value would be 1 if the destination component parameter should only be calculated for the second timestep and beyond.

connect_param!(dst::ComponentReference, dst_name::Symbol, src::ComponentReference, src_name::Symbol)

Connect two components as connect_param!(dst, dst_name, src, src_name).

connect_param!(dst::ComponentReference, src::ComponentReference, name::Symbol)

Connect two components with the same name as connect_param!(dst, src, name).

connect_param!(m::Model, dst_comp_name::Symbol, dst_par_name::Symbol, src_comp_name::Symbol, src_var_name::Symbol, 
backup::Union{Nothing, Array}=nothing; ignoreunits::Bool=false, offset::Int=0)

Bind the parameter dst_par_name of one component dst_comp_name of model m to a variable src_var_name in another component src_comp_name of the same model using backup to provide default values and the ignoreunits flag to indicate the need to check match units between the two. The offset argument indicates the offset between the destination and the source ie. the value would be 1 if the destination component parameter should only be calculated for the second timestep and beyond.

connect_param!(m::Model, comp_name::Symbol, param_name::Symbol, ext_param_name::Symbol)

Bind the parameter param_name in the component comp_name of model m to the external parameter ext_param_name already present in the model's list of external parameters.

connect_param!(m::Model, dst::Pair{Symbol, Symbol}, src::Pair{Symbol, Symbol}, backup::Array; ignoreunits::Bool=false)

Bind the parameter dst[2] of one component dst[1] of model m to a variable src[2] in another component src[1] of the same model using backup to provide default values and the ignoreunits flag to indicate the need to check match units between the two. The offset argument indicates the offset between the destination and the source ie. the value would be 1 if the destination component parameter should only be calculated for the second timestep and beyond.

create_marginal_model(base::Model, delta::Float64=1.0)

Create a MarginalModel where base is the baseline model and delta is the difference used to create the marginal model. Return the resulting MarginaModel which shares the internal ModelDef between the base and marginal.

dim_count(mi::ModelInstance, dim_name::Symbol)

Return the size of index dim_name in model instance mi.

dim_count(m::Model, dim_name::Symbol)

Return the size of index dim_name in model m.

dim_keys(m::Model, dim_name::Symbol)

Return keys for dimension dim-name in model m.

dim_key_dict(m::Model)

Return a dict of dimension keys for all dimensions in model m.

disconnect_param!(obj::AbstractCompositeComponentDef, comp_def::AbstractComponentDef, param_name::Symbol)

Remove any parameter connections for a given parameter param_name in a given component comp_def which must be a direct subcomponent of composite obj.

disconnect_param!(obj::AbstractCompositeComponentDef, comp_name::Symbol, param_name::Symbol)

Remove any parameter connections for a given parameter param_name in a given component comp_def which must be a direct subcomponent of composite obj.

disconnect_param!(m::Model, comp_name::Symbol, param_name::Symbol)

Remove any parameter connections for a given parameter param_name in a given component comp_def in model m.

explore(m::Model; title = "Electron")

Produce a UI to explore the parameters and variables of Model m in a Window with title title.

explore(sim_inst::SimulationInstance; title="Electron", model_index::Int = 1, scen_name::Union{Nothing, String} = nothing, results_output_dir::Union{Nothing, String} = nothing)

Produce a UI to explore the output distributions of the saved variables in SimulationInstancesim for results of model model_index and scenario with the name scen_name in a Window with title title. The optional arguments default to a model_index of 1, a scen_name of nothing assuming there is no secenario dimension, and a window with title Electron. The results_output_dir keyword argument refers to the main output directory as provided to run, where all subdirectories are held. If provided, results are assumed to be stored there, otherwise it is assumed that results are held in results.sim and not in an output folder.

getdataframe(m::AbstractModel, comp_name::Symbol, pairs::Pair{Symbol, Symbol}...)

Return a DataFrame with values for the given variables or parameters of model m indicated by pairs, where each pair is of the form comp_name => item_name. If more than one pair is provided, all must refer to items with the same dimensions, which are used to join the respective item values.

getdataframe(m::AbstractModel, pair::Pair{Symbol, NTuple{N, Symbol}})

Return a DataFrame with values for the given variables or parameters indicated by pairs, where each pair is of the form comp_name => item_name. If more than one pair is provided, all must refer to items with the same dimensions, which are used to join the respective item values.

getdataframe(m::AbstractModel, comp_name::Symbol, item_name::Symbol)

Return the values for variable or parameter item_name in comp_name of model m as a DataFrame.

gettime(ts::FixedTimestep)

Return the time (year) represented by Timestep ts

gettime(ts::VariableTimestep)

Return the time (year) represented by Timestep ts

gettime(c::Clock)

Return the current time of the timestep held by the c clock.

get_param_value(ci::AbstractComponentInstance, name::Symbol)

Return the value of parameter name in (leaf or composite) component ci.

get_var_value(ci::AbstractComponentInstance, name::Symbol)

Return the value of variable name in component ci.

hasvalue(arr::TimestepArray, ts::FixedTimestep)

Return true or false, true if the TimestepArray arr contains the Timestep ts.

hasvalue(arr::TimestepArray, ts::VariableTimestep)

Return true or false, true if the TimestepArray arr contains the Timestep ts.

hasvalue(arr::TimestepArray, ts::FixedTimestep, idxs::Int...)

Return true or false, true if the TimestepArray arr contains the Timestep ts within indices idxs. Used when Array and Timestep have different FIRST, validating all dimensions.

hasvalue(arr::TimestepArray, ts::VariableTimestep, idxs::Int...)

Return true or false, true if the TimestepArray arr contains the Timestep ts within indices idxs. Used when Array and Timestep different TIMES, validating all dimensions.

is_first(ts::AbstractTimestep)

Return true or false, true if ts is the first timestep to be run.

is_last(ts::FixedTimestep)

Return true or false, true if ts is the last timestep to be run.

is_last(ts::VariableTimestep)

Return true or false, true if ts is the last timestep to be run. Note that you may run next_timestep on ts, as ths final timestep has not been run through yet.

is_time(ts::AbstractTimestep, t::Int)

Return true or false, true if the current time (year) for ts is t

is_timestep(ts::AbstractTimestep, t::Int)

Return true or false, true if ts timestep is step t.

modeldef(mi)

Return the ModelDef contained by ModelInstance mi.

modeldef(m)

Return the ModelDef contained by Model m.

parameter_names(md::ModelDef, comp_name::Symbol)

Return a list of all parameter names for a given component comp_name in a model def md.

parameter_dimensions(obj::AbstractComponentDef, param_name::Symbol)

Return the names of the dimensions of parameter param_name exposed in the component definition indicated by obj.

parameter_dimensions(obj::AbstractComponentDef, comp_name::Symbol, param_name::Symbol)

Return the names of the dimensions of parameter param_name in component comp_name, which is exposed in composite component definition indicated byobj.

plot_comp_graph(m::Model, filename::Union{Nothing, Symbol} = nothing)

Plot the DAG of component connections within model m and save to filename. If no filename is given, plot will simply display.

replace_comp!(
    m::Model, comp_id::ComponentId, comp_name::Symbol=comp_id.comp_name;
    before::NothingSymbol=nothing,
    after::NothingSymbol=nothing,
    reconnect::Bool=true
)

Deprecated function for replacing the component with name comp_name in model m with the new component specified by comp_id. Use the following syntax instead:

replace!(m, comp_name => Mimi.compdef(comp_id); kwargs...)

See docstring for replace! for further description of available functionality.

replace_comp!(
    m::Model, comp_def::ComponentDef, comp_name::Symbol=comp_id.comp_name;
    before::NothingSymbol=nothing,
    after::NothingSymbol=nothing,
    reconnect::Bool=true
)

Deprecated function for replacing the component with name comp_name in model m with the new component specified by comp_def. Use the following syntax instead:

replace!(m, comp_name => comp_def; kwargs...)

See docstring for replace! for further description of available functionality.

set_dimension!(ccd::CompositeComponentDef, name::Symbol, keys::Union{Int, Vector, Tuple, AbstractRange})

Set the values of ccd dimension name to integers 1 through count, if keys is an integer; or to the values in the vector or range if keys is either of those types.

set_dimension!(m::Model, name::Symbol, keys::Union{Vector, Tuple, AbstractRange})

Set the values of m dimension name to integers 1 through count, if keysis an integer; or to the values in the vector or range ifkeys`` is either of those types.

set_leftover_params!(m::Model, parameters::Dict)

Set all of the parameters in model m that don't have a value and are not connected to some other component to a value from a dictionary parameters. This method assumes the dictionary keys are strings that match the names of unset parameters in the model.

set_param!(md::ModelDef, comp_name::Symbol,
           value_dict::Dict{Symbol, Any}, param_names)

Call set_param!() for each name in param_names, retrieving the corresponding value from value_dict[param_name].

set_param!(md::ModelDef, param_name::Symbol, value; dims=nothing)

Set the value of a parameter in all components of the model that have a parameter of the specified name.

The value can by a scalar, an array, or a NamedAray. Optional keyword argument 'dims' is a list of the dimension names of the provided data, and will be used to check that they match the model's index labels.

set_param!(ref::ComponentReference, name::Symbol, value)

Set a component parameter as set_param!(reference, name, value). This creates a unique name :compname_paramname in the model's external parameter list, and sets the parameter only in the referenced component to that value.

set_param!(m::Model, comp_name::Symbol, param_name::Symbol, value; dims=nothing)

Set the parameter of a component comp_name in a model m to a given value. The value can by a scalar, an array, or a NamedAray. Optional keyword argument 'dims' is a list of the dimension names of the provided data, and will be used to check that they match the model's index labels.

set_param!(m::Model, comp_name::Symbol, param_name::Symbol, ext_param_name::Symbol, value; dims=nothing)

Set the parameter param_name of a component comp_name in a model m to a given value, storing the value in the model's external parameter list by the provided name ext_param_name. The value can by a scalar, an array, or a NamedAray. Optional keyword argument 'dims' is a list of the dimension names of the provided data, and will be used to check that they match the model's index labels.

set_param!(m::Model, param_name::Symbol, value; dims=nothing)

Set the value of a parameter in all components of the model that have a parameter of the specified name.

TimestepIndex

A user-facing type used to index into a TimestepArray in run_timestep functions, containing an Int index that indicates the position in the array in terms of timesteps.

TimestepValue

A user-facing type used to index into a TimestepArray in run_timestep functions, containing a value of the same Type as the times in the TimstepArray which is used to index into the array at that position, with an optional Int offset in terms of timesteps.

variable_dimensions(obj::AbstractCompositeComponentDef, comp_path::ComponentPath, var_name::Symbol)

Return the names of the dimensions of variable var_name exposed in the composite component definition indicated byobj along the component path comp_path. The comp_path is of type Mimi.ComponentPath with the single field being an NTuple of symbols describing the relative (to a composite) or absolute (relative to ModelDef) path through composite nodes to specific composite or leaf node.

variable_dimensions(obj::AbstractCompositeComponentDef, comp::Symbol, var_name::Symbol)

Return the names of the dimensions of variable var_name exposed in the composite component definition indicated by obj for the component comp, which exists in a flat model.

variable_dimensions(obj::AbstractCompositeComponentDef, comp::Symbol, var_name::Symbol)

Return the names of the dimensions of variable var_name exposed in the composite component definition indicated by obj along the component path comp_path. The comp_path is a tuple of symbols describing the relative (to a composite) or absolute (relative to ModelDef) path through composite nodes to specific composite or leaf node.

variable_dimensions(obj::AbstractComponentDef, name::Symbol)

Return the names of the dimensions of variable name exposed in the component definition indicated by obj.

variable_names(md::AbstractCompositeComponentDef, comp_name::Symbol)

Return a list of all variable names for a given component comp_name in a model def md.

update_param!(obj::AbstractCompositeComponentDef, name::Symbol, value; update_timesteps = false)

Update the value of an external model parameter in composite obj, referenced by name. Optional boolean argument update_timesteps with default value false indicates whether to update the time keys associated with the parameter values to match the model's time index.

update_param!(m::Model, name::Symbol, value; update_timesteps = false)

Update the value of an external model parameter in model m, referenced by name. Optional boolean argument update_timesteps with default value false indicates whether to update the time keys associated with the parameter values to match the model's time index.

update_params!(obj::AbstractCompositeComponentDef, parameters::Dict{T, Any};
               update_timesteps = false) where T

For each (k, v) in the provided parameters dictionary, update_param! is called to update the external parameter by name k to value v, with optional Boolean argument update_timesteps. Each key k must be a symbol or convert to a symbol matching the name of an external parameter that already exists in the component definition.

update_params!(m::Model, parameters::Dict{T, Any}; update_timesteps = false) where T

For each (k, v) in the provided parameters dictionary, update_param!` is called to update the external parameter by name k to value v, with optional Boolean argument update_timesteps. Each key k must be a symbol or convert to a symbol matching the name of an external parameter that already exists in the model definition.