HolisticElectricityModel API Reference

Abstract type for agents.

Required interfaces:

• get_id(agent::Agent)::String
• getcurrentyear(agent::Agent, model_data::HEMData)::Tuple{Float64,Symbol}
• solveagentproblem!( agents::AgentGroup, agentopts::AgentOptions, modeldata::HEMData, hemopts::HEMOptions, agentstore::AgentStore, )
• saveresults( agent::AbstractAgent, agentopts::AgentOptions, hemopts::HEMOptions, exportfilepath::AbstractString, fileprefix::AbstractString,

)

Abstract type for all individual agents.

Abstract type for a group of individual agents.

DERAggregatorOptions(attributes::MathOptInterface.OptimizerWithAttributes) -> DERAggregatorOptions

Construct DERAggregatorOptions with an MOI.OptimizerWithAttributes instance.

Behaves like a Vector of Symbols with additional metadata fields.

GreenDeveloperOptions(attributes::MathOptInterface.OptimizerWithAttributes) -> GreenDeveloperOptions

Construct GreenDeveloperOptions with an MOI.OptimizerWithAttributes instance.

Construct an Gurobi optimizer. Use default settings or pass an MOI.OptimizerWithAttributes instance.

If using the default settings, call import_gurobi() first. Gurobi must be installed.

Examples

julia> import_gurobi()
julia> hem_solver = GurobiSolver()

julia> import Gurobi
julia> import JuMP
julia> gurobi = JuMP.optimizer_with_attributes(
    () -> Gurobi.Optimizer(Gurobi.Env()),
    "MIPFocus" => 3,
)
julia> solver = GurobiSolver(gurobi)

Construct IPPOptions with solvers defined as MOI.OptimizerWithAttributes instances or HEMSolver instances.

Review the functions that call get_new_jump_model for Dict key requirements.

Examples

julia> ipp_opts = IPPOptions(
    LagrangeDecomposition(),
    Dict(
        "Lagrange_Sub_Investment_Retirement_Cap" => JuMP.optimizer_with_attributes(
            Ipopt.Optimizer,
            "print_level" => 0,
        ),
        "Lagrange_Sub_Dispatch_Cap" => JuMP.optimizer_with_attributes(
            Xpress.Optimizer,
        ),
        "Lagrange_Feasible_Cap" => JuMP.optimizer_with_attributes(
            Xpress.Optimizer,
        )
    )
)

Construct an Ipopt optimizer. Use default settings or pass an MOI.OptimizerWithAttributes instance.

If using the default settings, call import_ipopt() first. Ipopt must be installed.

Examples

julia> import_ipopt()
julia> hem_solver = IpoptSolver()

julia> import Ipopt
julia> import JuMP
julia> ipopt = JuMP.optimizer_with_attributes(Ipopt.Optimizer, "tol" => 1e-6, "print_level" => 0)
julia> solver = IpoptSolver(ipopt)

PVAdoptionModel(Shape, MeanPayback, Bass_p, Bass_q) -> HolisticElectricityModel.PVAdoptionModel

Constructs a PVAdoptionModel by computing Rate from the other parameters.

Behaves like a number with additional metadata fields.

UtilityOptions(attributes::MathOptInterface.OptimizerWithAttributes) -> UtilityOptions

Construct UtilityOptions with an MOI.OptimizerWithAttributes instance.

Construct an Xpress optimizer. Use default settings or pass an MOI.OptimizerWithAttributes instance.

If using the default settings, call import_xpress() first. Xpress must be installed.

Examples

julia> import_xpress()
julia> hem_solver = XpressSolver()

julia> import Xpress
julia> import JuMP
julia> xpress = JuMP.optimizer_with_attributes(
    Xpress.Optimizer,
    "MIPRELSTOP" => 0.01,
    "OUTPUTLOG" => 1,
)
julia> solver = XpressSolver(xpress)

configure_logging() -> InfrastructureSystems.MultiLogger

Creates console and file loggers and sets the global_logger.

Note: Log messages may not be written to the file until flush() or close() is called on the returned logger.

Arguments

• console_level = Logging.Error: level for console messages
• file_level = Logging.Info: level for file messages
• filename::Union{Nothing, AbstractString} = "hem.log": log file; pass nothing to disable file logging

Example

logger = configure_logging(console_level = Logging.Info)
@info "log message"
close(logger)

get_agent(::Type{T<:AbstractAgent}, store::AgentStore) -> AbstractAgent
get_agent(::Type{T<:AbstractAgent}, store::AgentStore, id) -> AbstractAgent

Return the agent of the given type and ID from the store.

If there is only one agent of the given type then id is optional.

get_current_year(agent::AbstractAgent, model_data::HEMData) -> Tuple{Any, Any}

Get the last year for which agent's data have been updated. Provided so other agents can access the right data for agent.

initialize_param(name::AbstractString, index::HolisticElectricityModel.Dimension) -> HolisticElectricityModel.ParamArray{1}

Returns a ParamArray with all values set to value.

initialize_param(name::AbstractString, indices...) -> HolisticElectricityModel.ParamArray{1}

Return a ParamArray with all values set to value, and indices formed from Iterators.product(indices...).

ipp_cap_lower(ipp, ipp_opts, model_data, delta_t, window_length, customers, der_aggregator, green_developer, utility, solver) -> Any

Lower level optimization results are used to set variable bounds for McCormick-envelope Relaxation

ipp_cap_lower_dual(ipp, ipp_opts, model_data, delta_t, window_length, customers, der_aggregator, green_developer, utility, solver) -> Any

Lower level dual optimization results are used to set variable bounds for McCormick-envelope Relaxation

make_keyed_array(indices...) -> Any

Return an uninitialized KeyedArray from any number of Dimension values.

read_keyed_array(filename::AbstractString, num_dims::Int64) -> Any

Return a KeyedArray from an N-dimensional array flattened in a CSV file.

If there is one dimension then the file must have a single row with dimension names. If there is more than one dimension then it must conform to the following format:

The header row consists of dimension names for the first N-1 dimensions followed by the last dimension's element ids pivoted out to form data column headers.

The data rows contain dimension element ids in the first N-1 columns followed by parameter values in the remaining columns. Each value maps to the dimension element ids listed in the row's first N-1 columns plus the dimension element id found in that value's column.

3-dimension example:

d1variablename,d2variablename,d3name1,d3name2,d3name3 d1name1,d2name1,1.0,1.0,1.0 d1name2,d2_name2,1.0,1.0,1.0

read_param(name::AbstractString, dirpath::AbstractString, filename::AbstractString, column_index::HolisticElectricityModel.Dimension, row_indices::Vector{HolisticElectricityModel.Dimension}) -> HolisticElectricityModel.ParamArray

Reads parameter data from the csv file at dirpath/filename. Assumes the data has a single header row, and that the columnindex elements are the right-most column names. All other data dimension values are listed in the first length(rowindices) columns of the file, corresonding one-to-one and in the same order as the row_indices.

Returns the data loaded into a ParamAxisArray with dimensions (rowindices..., columnindex).

read_param(name::AbstractString, dirpath::AbstractString, filename::AbstractString, index::HolisticElectricityModel.Dimension) -> HolisticElectricityModel.ParamArray{1}

Reads parameter data from the csv file at dirpath/filename. Assumes the data has a single header row, and that the index elements comprise the column names.

Returns the data loaded into a ParamAxisArray.

read_set(dirpath::AbstractString, filename::AbstractString, name::AbstractString) -> HolisticElectricityModel.Dimension

read_set(filename, filename)

Reads the column names of csv dirpath/filename in as symbols.

run_hem(input_dir::AbstractString, options::HEMOptions)

Solve the problem with the given inputs.

Arguments

• input_dir::AbstractString: Directory containing input data. Outputs will be recorded in a subdirectory.
• options::HEMOptions:
• ipp_options::IPPOptions: Independent Power Producer options. Defaults to NullAgentOptions.
• regulator_options::RegulatorOptions: Regulator options. Defaults to NullAgentOptions.
• utility_options::RegulatorOptions: Regulator options. Defaults to NullAgentOptions.
• max_iterations::Int: Max number of iterations to attempt a solution. Defaults to 100.
• window_length::Int:
• force::Bool: If true, overwrite results if a directory already exists.

set_log_level(level::Base.CoreLogging.LogLevel) -> Any

Sets the log level to, e.g., Logging.Debug, Logging.Warn. Currently only implemented for ConsoleLogger.

update_cumulative!(model_data::HEMData, agent::AbstractAgent)

Default no-op method for updating cumulative parameters in AbstractAgents after each model year.

update_cumulative!(model_data::HEMData, ipp::IPPGroup)

Update IPPGroup cumulative parameters

update_cumulative!(model_data::HEMData, utility::Utility)

Update Utility cumulative parameters

update_total_capacity!(total_capacity_my::HolisticElectricityModel.ParamArray, x_DG_new::HolisticElectricityModel.ParamArray, model_data::HEMData, reg_year::Integer, z::Symbol, h::Symbol, m::Symbol)

Calculates cumulative capacity for this year and future years if this technology was a build option.