Library

run_spineopt(url_in, url_out; <keyword arguments>)

Run SpineOpt using the contents of url_in and write report(s) to url_out. The argument url_in must be either a String pointing to a valid Spine database, or a Dict (e.g. manually created or parsed from a json file). A new Spine database is created at url_out if one doesn't exist.

Arguments

• log_level::Int=3: an integer to control the log level.
• upgrade::Bool=false: whether or not to automatically upgrade the data structure in url_in to latest.
• filters::Dict{String,String}=Dict("tool" => "object_activity_control"): a dictionary to specify filters. Possible keys are "tool" and "scenario". Values should be a tool or scenario name in the input DB.
• templates: a collection of templates to load on top of the SpineOpt template. Each template must be a Dict with the same structure as the one returned by SpineOpt.template().
• mip_solver=nothing: a MIP solver to use if no MIP solver specified in the DB.
• lp_solver=nothing: a LP solver to use if no LP solver specified in the DB.
• use_direct_model::Bool=false: whether or not to use JuMP.direct_model to build the Model object.
• use_model_names::Bool=true: whether or not to use the names in the model.
• add_bridges::Bool=false whether or not bridges from JuMP to the solver should be added to the model.
• optimize::Bool=true: whether or not to optimise the model (useful for running tests).
• update_names::Bool=false: whether or not to update variable and constraint names after the model rolls (expensive).
• alternative::String="": if non empty, write results to the given alternative in the output DB.
• write_as_roll::Int=0: if greater than 0 and the run has a rolling horizon, then write results every that many windows.
• log_file_path::String=nothing: if not nothing, log all console output to a file at the given path. The file is overwritten at each call.
• resume_file_path::String=nothing: only relevant in rolling horizon optimisations with write_as_roll greater or equal than one. If the file at given path contains resume data from a previous run, start the run from that point. Also, save resume data to that same file as the model rolls and results are written to the output database.

Example

using SpineOpt
m = run_spineopt(
    raw"sqlite:///C:\path\to\your\input_db.sqlite", 
    raw"sqlite:///C:\path\to\your\output_db.sqlite";
    filters=Dict("tool" => "object_activity_control", "scenario" => "scenario_to_run"),
    alternative="alternative_to_write_results"
)

run_spineopt(f, url_in, url_out; <keyword arguments>)

Same as run_spineopt(url_in, url_out; kwargs...) but call function f with the SpineOpt model as argument right after its creation (but before building and solving it).

This is intended to be called using do block syntax.

run_spineopt(url_in, url_out) do m
    # Do something with m after its creation
end  # Building and solving begins after quiting this block

prepare_spineopt(url_in; <keyword arguments>)

A SpineOpt model from the contents of url_in - ready to be passed to run_spineopt!. The argument url_in must be either a String pointing to a valid Spine database, or a Dict (e.g. manually created or parsed from a json file).

Arguments

• log_level
• upgrade
• filters
• templates
• mip_solver
• lp_solver
• use_direct_model
• use_model_names
• add_bridges

See run_spineopt for the description of the keyword arguments.

run_spineopt!(m, url_out; <keyword arguments>)

Build SpineOpt on the given m and solve it; write report(s) to url_out. A new Spine database is created at url_out if one doesn't exist.

Arguments

• log_level
• optimize
• update_names
• alternative
• write_as_roll
• log_file_path
• resume_file_path

See run_spineopt for the description of the keyword arguments.

create_model(mip_solver, lp_solver, use_direct_model, use_model_names, add_bridges)

A JuMP.Model extended to be used with SpineOpt. mip_solver and lp_solver are 'optimizer factories' to be passed to JuMP.Model or JuMP.direct_model; use_direct_model is a Bool indicating whether JuMP.Model or JuMP.direct_model should be used. use_model_names is a Bool indicating whether the names in the model should be used. add_bridges is a Bool indicating whether bridges from JuMP to the solver should be added to the model.

build_model!(m; log_level)

Build given SpineOpt model:

• create temporal and stochastic structures
• add variables
• add expressions
• add constraints
• set objective
• initialize outputs

Arguments

• log_level::Int: an integer to control the log level.

solve_model!(m; <keyword arguments>)

Solve given SpineOpt model and save outputs.

Arguments

• log_level::Int=3: an integer to control the log level.
• update_names::Bool=false: whether or not to update variable and constraint names after the model rolls (expensive).
• write_as_roll::Int=0: if greater than 0 and the run has a rolling horizon, then write results every that many windows.
• resume_file_path::String=nothing: only relevant in rolling horizon optimisations with write_as_roll greater or equal than one. If the file at given path contains resume data from a previous run, start the run from that point. Also, save resume data to that same file as the model rolls and results are written to the output database.
• calculate_duals::Bool=false: whether or not to calculate duals after the model solve.
• output_suffix::NamedTuple=(;): to add to the outputs.
• log_prefix::String="": to prepend to log messages.

add_event_handler!(fn, m, event)

Add an event handler for given model. event must be a Symbol corresponding to an event. fn must be a function callable with the arguments corresponding to that event. Below is a table of events, arguments, and when do they fire.

Example

run_spineopt("sqlite:///path-to-input-db", "sqlite:///path-to-output-db") do m
    add_event_handler!(println, m, :model_built)  # Print the model right after it's built
end

generate_temporal_structure!(m)

Create the temporal structure for the given SpineOpt model. After this, you can call the following functions to query the generated structure:

• time_slice
• t_before_t
• t_in_t
• t_in_t_excl
• t_overlaps_t
• to_time_slice
• current_window

roll_temporal_structure!(m[, window_number=1]; rev=false)

Roll the temporal structure of given SpineOpt model forward a period of time equal to the value of the roll_forward parameter. If roll_forward is an array, then window_number can be given either as an Integer or a UnitRange indicating the position or successive positions in that array.

If rev is true, then the structure is rolled backwards instead of forward.

rewind_temporal_structure!(m)

Rewind the temporal structure of given SpineOpt model back to the first window.

time_slice(m; temporal_block=anything, t=anything)

An Array of TimeSlices in model m.

Arguments

• temporal_block::Union{Object,Vector{Object}}: only return TimeSlices in these blocks.
• t::Union{TimeSlice,Vector{TimeSlice}}: only return TimeSlices that are also in this collection.

t_before_t(m; t_before=anything, t_after=anything)

An Array where each element is a Tuple of two consecutive TimeSlices in model m, i.e., the second starting when the first ends.

Arguments

• t_before: if given, return an Array of TimeSlices that start when t_before ends.
• t_after: if given, return an Array of TimeSlices that end when t_after starts.

t_in_t(m; t_short=anything, t_long=anything)

An Array where each element is a Tuple of two TimeSlices in model m, the second containing the first.

Keyword arguments

• t_short: if given, return an Array of TimeSlices that contain t_short.
• t_long: if given, return an Array of TimeSlices that are contained in t_long.

t_in_t_excl(m; t_short=anything, t_long=anything)

Same as tint but exclude tuples of the same TimeSlice.

Keyword arguments

• t_short: if given, return an Array of TimeSlices that contain t_short (other than t_short itself).
• t_long: if given, return an Array of TimeSlices that are contained in t_long (other than t_long itself).

t_overlaps_t(m; t)

An Array of TimeSlices in model m that overlap the given t, where t must be in m.

to_time_slice(m; t)

An Array of TimeSlices in model m overlapping the given TimeSlice (where t may not be in m).

current_window(m)

A TimeSlice corresponding to the current window of given model.

generate_stochastic_structure(m::Model)

Generate the stochastic structure for given SpineOpt model.

The stochastic structure is a directed acyclic graph (DAG) where the vertices are the stochastic_scenario objects, and the edges are given by the parent_stochastic_scenario__child_stochastic_scenario relationships.

After this, you can call active_stochastic_paths to slice the generated structure.

active_stochastic_paths(
    m; stochastic_structure::Union{Object,Vector{Object}}, t::Union{TimeSlice,Vector{TimeSlice}}
)

An Array of stochastic paths, where each path is itself an Array of stochastic_scenario Objects.

The paths are obtained as follows.

1. Start with the stochastic DAG associated to model m.
2. Remove all the scenarios that are not in the given stochastic_structure.
3. Remove scenarios that don't overlap the given t.
4. Return all the paths from root to leaf in the remaining sub-DAG.

write_model_file(m; file_name="model")

Write model file for given model.

write_report(m, url_out; <keyword arguments>)

Write report(s) from given SpineOpt model to url_out. A new Spine database is created at url_out if one doesn't exist.

Arguments

• alternative::String="": if non empty, write results to the given alternative in the output DB.

• log_level::Int=3: an integer to control the log level.

write_report_from_intermediate_results(intermediate_results_folder, default_url; <keyword arguments>)

Collect results generated on a previous, unsuccessful SpineOpt run from intermediate_results_folder, and write the corresponding report(s) to url_out. A new Spine database is created at url_out if one doesn't exist.

Arguments

• alternative::String="": if non empty, write results to the given alternative in the output DB.

• log_level::Int=3: an integer to control the log level.

master_model(m)

The Benders master model for given model.

stage_model(m, stage_name)

A stage model associated to given model.