API Documentation

OptiGraph

The core modeling object of Plasmo.jl. An optigraph represents an optimization model as a set of OptiNode and OptiEdge objects.

OptiNode{GT<:AbstractOptiGraph} <: AbstractOptiNode

A data structure meant to encapsulate variables, constraints, an objective function, and other model data. An optinode is "lightweight" in the sense that it does not directly contain model data, but instead acts as an interface that maps to a backend where the model data is stored. This avoids the need to generate memory overhead through container structures in cases when a node contains very little model data.

OptiEdge{GT<:AbstractOptiGraph} <: AbstractOptiEdge

A data structure meant to encapsulate linking constraints and other model data. An optiedge is "lightweight" in the sense that it does not directly contain model data, but instead acts as an interface that maps to a backend where the model data is stored. This avoids the need to generate memory overhead through container structures in cases when a node contains very little model data.

@optinode(optigraph, expr...)

Add a new optinode to optigraph. The expression expr can either be

• of the form nodename creating a single optinode with the variable name varname
• of the form nodename[...] or [...] creating a container of optinodes using JuMP Containers

@linkconstraint(graph::OptiGraph, expr)

Add a linking constraint described by the expression expr.

@linkconstraint(graph::OptiGraph, ref[i=..., j=..., ...], expr)

Add a group of linking constraints described by the expression expr parametrized by i, j, ...

The @linkconstraint macro works the same way as the JuMP.@constraint macro.

@nodevariables(iterable, expr...)

Call the JuMP.@variable macro for each optinode in a given container

set_to_node_objectives(graph::OptiGraph)

Set the graph objective to the summation of all of its optinode objectives. Assumes the objective sense is an MOI.MIN_SENSE and adjusts the signs of node objective functions accordingly.

graph_backend(graph::OptiGraph)

Return the intermediate backend used to map the optigraph to an optimizer. Plasmo.jl currently only supports a backend to MathOptInterface.jl optimizers, but future versions intend to support GraphOptInterface.jl as a structured backend.

graph_backend(node::OptiNode)

Return the GraphMOIBackend that holds the associated node model attributes

graph_backend(edge::OptiEdge)

Return the GraphMOIBackend that holds the associated edge model attributes

graph_index(ref::RT) where {RT<:Union{NodeVariableRef,ConstraintRef}}

Return the the corresponding variable or constraint index corresponding to a reference.

graph_index(
    backend::GraphMOIBackend, 
    ref::RT
) where {RT<:Union{NodeVariableRef,ConstraintRef}}

Return the actual variable or constraint index of the backend model that corresponds to the local index of a node or edge.

source_graph(node::OptiNode)

Return the optigraph that contains the optinode. This is the optigraph that defined said node and stores node object dictionary data.

source_graph(edge::OptiEdge)

Return the optigraph that contains the optiedge. This is the optigraph that defined said edge and stores edge object dictionary data.

add_subgraph(graph::OptiGraph; name::Symbol=Symbol(:sg,gensym()))

Create and add a new subgraph to the optigraph graph.

add_subgraph(graph::OptiGraph; name::Symbol=Symbol(:sg,gensym()))

Add an existing subgraph to an optigraph. The subgraph cannot already be part of another optigraph. It also should not have nodes that already exist in the optigraph.

local_subgraphs(graph::OptiGraph)::Vector{OptiGraph}

Retrieve the local subgraphs of graph.

all_subgraphs(graph::OptiGraph)::Vector{OptiGraph}

Retrieve all subgraphs of graph. Includes subgraphs within other subgraphs.

num_local_subgraphs(graph::OptiGraph)::Int

Retrieve the number of local subgraphs in graph. Does not include graph in subgraphs.

num_subgraphs(graph::OptiGraph)::Int

Retrieve the total number of subgraphs in graph. Include subgraphs within subgraphs.

add_node(
    graph::OptiGraph; label=Symbol(graph.label, Symbol(".n"), length(graph.optinodes)+1
)

Add a new optinode to graph. By default, the node label is set to be "n<i+1>" where "i" is the number of nodes in the graph.

add_node(graph::OptiGraph, node::OptiNode)

Add an existing optinode (created in another optigraph) to graph. This copies model data from the other graph to the new graph.

get_node(graph::OptiGraph, idx::Int)

Retrieve the optinode in graph at the given index.

local_nodes(graph::OptiGraph)::Vector{<:OptiNode}

Retrieve the optinodes defined within the optigraph graph. This does not return nodes that exist in subgraphs.

all_nodes(graph::OptiGraph)::Vector{<:OptiNode}

Recursively collect all optinodes in graph by traversing each of its subgraphs.

collect_nodes(jump_func::T where T <: JuMP.AbstractJuMPScalar)

Retrieve the optinodes contained in a JuMP expression.

num_local_nodes(graph::OptiGraph)::Int

Return the number of local nodes in the optigraph graph.

num_nodes(graph::OptiGraph)::Int

Return the total number of nodes in graph by recursively checking subgraphs.

num_local_variables(graph::OptiGraph)

Return the number of local variables in graph. Does not include variables in subgraphs.

add_edge(
    graph::OptiGraph,
    nodes::OptiNode...;
    label=Symbol(graph.label, Symbol(".e"), length(graph.optiedges) + 1),
)

Add a new optiedge to graph that connects nodes. By default, the edge label is set to be "e<i+1>" where "i" is the number of edges in the graph.

add_edge(graph::OptiGraph, edge::OptiEdge)

Add an existing optiedge (created in another optigraph) to graph. This copies model data from the other graph to the new graph.

get_edge(graph::OptiGraph, nodes::Set{<:OptiNode})

Retrieve the optiedge in graph. that connects nodes.

get_edge(graph::OptiGraph, nodes::OptiNode...)

Convenience method. Retrieve the optiedge in graph that connects nodes.

get_edge_by_index(graph::OptiGraph, idx::Int64)

Retrieve the optiedge in graph that corresponds to the given index.

has_edge(graph::OptiGraph, nodes::Set{<:OptiNode})

Return whether an edge that connects nodes exists in the graph.

local_edges(graph::OptiGraph)

Retrieve the edges that exists in graph. Does not return edges that exist in subgraphs.

all_edges(graph::OptiGraph)::Vector{<:OptiNode}

Recursively collect all optiedges in graph by traversing each of its subgraphs.

num_local_edges(graph::OptiGraph)::Int

Return the number of local edges in the optigraph graph.

num_edges(graph::OptiGraph)::Int

Return the total number of nodes in graph by recursively checking subgraphs.

num_local_link_constraints(
    graph::OptiGraph,
    func_type::Type{<:Union{JuMP.AbstractJuMPScalar,Vector{<:JuMP.AbstractJuMPScalar}}},
    set_type::Type{<:MOI.AbstractSet},
)

Retrieve the number of local linking constraints with function func_type and set set_type in graph. Does not include linking constraints in subgraphs.

num_local_link_constraints(graph::OptiGraph)

Retrieve the number of local linking constraints (all constraint types) in graph. Does not include linking constraints in subgraphs.

num_link_constraints(
    graph::OptiGraph,
    func_type::Type{<:Union{JuMP.AbstractJuMPScalar,Vector{<:JuMP.AbstractJuMPScalar}}},
    set_type::Type{<:MOI.AbstractSet},
)

Retrieve the total number of linking constraints with function func_type and set set_type in graph. Includes constraints in subgraphs.

num_link_constraints(graph::OptiGraph)

Retrieve the number of local linking constraints (all constraint types) in graph. Does not include constraints in subgraphs.

local_link_constraints(
    graph::OptiGraph,
    func_type::Type{<:Union{JuMP.AbstractJuMPScalar,Vector{<:JuMP.AbstractJuMPScalar}}},
    set_type::Type{<:MOI.AbstractSet},
)

Retrieve the local linking constraints with function func_type and set set_type in graph. Does not include linking constraints in subgraphs.

local_link_constraints(graph::OptiGraph)

Retrieve the local linking constraints (all constraint types) in graph. Does not include constraints in subgraphs.

all_link_constraints(
    graph::OptiGraph,
    func_type::Type{<:Union{JuMP.AbstractJuMPScalar,Vector{<:JuMP.AbstractJuMPScalar}}},
    set_type::Type{<:MOI.AbstractSet},
)

Retrieve all linking constraints with function func_type and set set_type in graph. Does not include constraints in subgraphs.

all_link_constraints(graph::OptiGraph)

Retrieve all linking constraints (all constraint types) in graph. Includes linking constraints in subgraphs.

num_local_constraints(
    graph::OptiGraph,
    func_type::Type{<:Union{JuMP.AbstractJuMPScalar,Vector{<:JuMP.AbstractJuMPScalar}}},
    set_type::Type{<:MOI.AbstractSet},
)

Retrieve the number of local constraints with function func_type and set set_type in graph. Does not include constraints in subgraphs.

num_local_constraints(graph::OptiGraph)

Retrieve the number of local constraints (all constraint types) in graph. Does not include constraints in subgraphs.

local_constraints(
    graph::OptiGraph,
    func_type::Type{<:Union{JuMP.AbstractJuMPScalar,Vector{<:JuMP.AbstractJuMPScalar}}},
    set_type::Type{<:MOI.AbstractSet},
)

Retrieve the local constraints with function func_type and set set_type in graph. Does not include constraints in subgraphs.

local_constraints(graph::OptiGraph)

Retrieve the local constraints (all constraint types) in graph. Does not include constraints in subgraphs.

local_elements(graph::OptiGraph)

Retrieve the local elements (nodes and edges) in graph. Does not include elements in subgraphs.

local_elements(graph::OptiGraph)

Retrieve all elements (nodes and edges) in graph. Includes elements in subgraphs.

Base.getindex(graph::OptiGraph, idx::Int)

Get the optinode at the given index.

JuMP.name(graph::OptiGraph)

Return the name of graph.

JuMP.set_name(graph::OptiGraph, name::Symbol)

Set the name of graph to name.

JuMP.index(graph::OptiGraph, nvref::NodeVariableRef)

Return the backend model index of node variable nvref

JuMP.backend(graph::OptiGraph)

Return the backend model object for graph.

JuMP.value(graph::OptiGraph, nvref::NodeVariableRef; result::Int=1)

Return the primal value of nvref in graph. Note that this value is specific to the optimizer solution to the graph. The nvref can have different values for different optigraphs it is contained in.

JuMP.add_variable(node::OptiNode, v::JuMP.AbstractVariable, name::String="")

Add variable v to optinode node. This function supports use of the @variable JuMP macro. Optionally add a base_name to the variable for printing.

JuMP.num_variables(graph::OptiGraph)

Return the total number of variables in graph.

JuMP.all_variables(graph::OptiGraph)

Return all of the variables in graph.

JuMP.start_value(graph::OptiGraph, nvref::NodeVariableRef)

Return the start value for variable nvref in graph. Note that different graphs can have different start values for node variables.

JuMP.set_start_value(
    graph::OptiGraph, 
    nvref::NodeVariableRef, 
    value::Union{Nothing,Real}
)

Set the start value of variable nvref in graph. Note that different graphs can have different start values for node variables.

JuMP.add_constraint(graph::OptiGraph, con::JuMP.AbstractConstraint, name::String="")

Add a new constraint to graph. This method is called internall when a user uses the JuMP.@constraint macro.

JuMP.add_constraint(node::OptiNode, con::JuMP.AbstractConstraint, name::String="")

Add a constraint con to optinode node. This function supports use of the @constraint JuMP macro.

JuMP.list_of_constraint_types(graph::OptiGraph)::Vector{Tuple{Type,Type}}

List all of the constraint types in graph.

JuMP.num_constraints(
    graph::OptiGraph,
    func_type::Type{<:Union{JuMP.AbstractJuMPScalar,Vector{<:JuMP.AbstractJuMPScalar}}},
    set_type::Type{<:MOI.AbstractSet},
)

Return all the number of contraints in graph with func_type and set_type.

JuMP.num_constraints(graph::OptiGraph; count_variable_in_set_constraints=true)

Return the total number of constraints in graph. If count_variable_in_set_constraints is set to true, this also includes variable bound constraints.

JuMP.num_constraints(
element::OptiElement,
function_type::Type{
    <:Union{JuMP.AbstractJuMPScalar,Vector{<:JuMP.AbstractJuMPScalar}},
},set_type::Type{<:MOI.AbstractSet})::Int64

Return the total number of constraints on an element.

JuMP.all_constraints(
    graph::OptiGraph,
    func_type::Type{
        <:Union{JuMP.AbstractJuMPScalar,Vector{<:JuMP.AbstractJuMPScalar}},
    },
    set_type::Type{<:MOI.AbstractSet}
)

Return all of the constraints in graph with func_type and set_type.

JuMP.all_constraints(graph::OptiGraph)

Return all of the constraints in graph (all function and set types).

JuMP.objective_value(graph::OptiGraph)

Retrieve the current objective value on optigraph graph.

JuMP.dual_objective_value(graph::OptiGraph; result::Int=1)

Return the dual objective value for graph. Specify result for cases when a solver returns multiple results.

JuMP.objective_sense(graph::OptiGraph)

Return the objective sense for graph.

JuMP.objective_function(graph::OptiGraph)

Return the objective function for graph.

JuMP.objective_sense(graph::OptiGraph)

Return the objective function type for graph.

JuMP.objective_bound(graph::OptiGraph)

Return the objective bound for the current solution for graph.

JuMP.set_objective(
    graph::OptiGraph, 
    sense::MOI.OptimizationSense, 
    func::JuMP.AbstractJuMPScalar
)

Set the objective function and objective sense for graph. This method is called internally when a user uses the JuMP.@objective macro.

JuMP.set_objective_function(graph::OptiGraph, expr::JuMP.AbstractJuMPScalar)

Set the objective function of graph.

JuMP.set_objective_sense(graph::OptiGraph, sense::MOI.OptimizationSense)

Set the objective sense of graph.

JuMP.set_objective_coefficient(
    graph::OptiGraph, 
    variable::NodeVariableRef, 
    coeff::Real
)

Set the objective function coefficient for variable to coefficient coeff.

JuMP.set_optimizer(
    graph::OptiGraph, 
    JuMP.@nospecialize(optimizer_constructor); 
    add_bridges::Bool=true
)

Set the optimizer on graph by passing an optimizer_constructor.

JuMP.set_optimizer(
    node::OptiNode, 
    JuMP.@nospecialize(optimizer_constructor); 
    add_bridges::Bool=true
)

Set the optimizer for an optinode.This internally creates a new optigraph that is used to optimize the node. Calling this method on a node returns the newly created graph.

JuMP.add_nonlinear_operator(
    graph::OptiGraph,
    dim::Int,
    f::Function,
    args::Vararg{Function,N};
    name::Symbol=Symbol(f),
) where {N}

Add a nonlinear operator to a graph.

JuMP.optimize!(
    graph::OptiGraph;
    kwargs...,
)

Optimize graph using the current set optimizer.

JuMP.termination_status(graph::OptiGraph)

Return the solver termination status of graph if a solver has been executed.

JuMP.primal_status(graph::OptiGraph; result::Int=1)

Return the primal status of graph if a solver has been executed.

JuMP.dual_status(graph::OptiGraph; result::Int=1)

Return the dual status of graph if a solver has been executed.

JuMP.relative_gap(graph::OptiGraph)

Return the relative gap in the current solution for graph.

JuMP.constraint_ref_with_index(
element::OptiElement, 
idx::MOI.ConstraintIndex{<:MOI.AbstractScalarFunction, <:MOI.AbstractScalarSet}
)

Return a ConstraintRef given an optigraph element and MOI.ConstraintIndex. Note that the index is the index corresponding to the graph backend, not the element index.

JuMP.constraint_ref_with_index(backend::GraphMOIBackend, idx::MOI.Index)

Return the constraint reference (or variable reference) associated with the graph index in backend. Returns a JuMP.ConstraintRef (or NodeVariableRef) object.

JuMP.object_dictionary(graph::OptiGraph)

Return the object dictionary for graph.

Set a JuMP.Model to `node`. This copies the model data over and does not mutate

the model in any way.

GraphProjection

A mapping between OptiGraph elements (nodes and edges) and elements in a graph projection. A graph projection can be for example a hypergraph, a bipartite graph or a standard graph.

hyper_projection(graph::OptiGraph)

Retrieve a hypergraph representation of the optigraph graph. Returns a GraphProjection that maps elements between the optigraph and the projected graph.

edge_hyper_projection(graph::OptiGraph)

Retrieve an edge-hypergraph representation of the optigraph graph. This is sometimes called the dual-hypergraph representation of a hypergraph.

clique_projection(graph::OptiGraph)

Retrieve a standard graph representation of graph. The projection contains a standard Graphs.Graph and a mapping between its elements and the given optigraph. This projection works by creating an edge for each pair of nodes in each hyperedge.

edge_clique_projection(graph::OptiGraph)

Retrieve the edge-graph representation of optigraph graph. This is sometimes called the line graph of a hypergraph.

bipartite_graph(graph::OptiGraph)

Create a bipartite graph representation from graph. The bipartite graph contains two sets of vertices corresponding to optinodes and optiedges respectively.

Partition

A data structure that describes a (possibly recursive) graph partition.

assemble_optigraph(nodes::Vector{<:OptiNode}, edges::Vector{OptiEdge})

Create a new optigraph from a collection of nodes and edges.

Assemble a new optigraph from a given `Partition`.

apply_partition!(graph::OptiGraph, partition::Partition)

Generate subgraphs in an optigraph using a partition.

aggregate(graph::OptiGraph; name=gensym())

Aggregate an optigraph into a graph containing a single optinode. An optional name can be used to name the new optigraph. Returns the new optinode (which points to a new graph with source_graph(node)) and a mapping from the original graph variables and constraints to the new node variables and constraints.

aggregate_to_depth(graph::OptiGraph, max_depth::Int64=0)

Aggregate graph by converting subgraphs into optinodes. The max_depth determines how many levels of subgraphs remain in the new aggregated optigraph. For example, a max_depth of 0 signifies there should be no subgraphs in the aggregated optigraph. Return a new aggregated optigraph and reference map that maps elements from the old optigraph to the new aggregate optigraph.

aggregate_to_depth!(graph::OptiGraph, max_depth::Int64=0)

Aggregate graph by converting subgraphs into optinodes. The max_depth determines how many levels of subgraphs remain in the new aggregated optigraph. For example, a max_depth of 0 signifies there should be no subgraphs in the aggregated optigraph. This version of the method modifies the optigraph and transforms it into the aggregated version.

Graphs.all_neighbors(hyper::HyperGraphProjection, node::OptiNode)

Retrieve the optinode neighbors of node in the optigraph graph. Uses an underlying hypergraph to query for neighbors.

Graphs.induced_subgraph(graph::OptiGraph, nodes::Vector{OptiNode})

Create an induced subgraph of optigraph given a vector of optinodes.

neighborhood(
    hyper::HyperGraphProjection, 
    nodes::Vector{OptiNode}, 
    distance::Int64
)::Vector{OptiNode}

Return the optinodes within distance of the given nodes in the optigraph graph.

incident_edges(hyper::HyperGraphProjection, nodes::Vector{OptiNode})

Retrieve incident edges to a set of optinodes.

incident_edges(hyper::HyperGraphProjection, node::OptiNode)

Retrieve incident edges to a single optinode.

induced_edges(graph::OptiGraph, nodes::Vector{OptiNode})

Retrieve induced edges to a set of optinodes.

identify_edges(hyper::HyperGraphProjection, node_vectors::Vector{Vector{OptiNode}})

Identify induced edges and edge separators from a vector of optinode partitions.

Arguments

• hyper::HyperGraphProjection: A HyperGraphProjection obtained from hyper_projection.
• node_vectors::Vector{Vector{OptiNode}}: A vector of vectors that contain OptiNodes.

Returns

• partition_optiedges::Vector{Vector{OptiEdge}}: The OptiEdge vectors for each partition.
• cross_optiedges::Vector{OptiEdge}: A vector of optiedges that cross partitions.

identify_nodes(hyper::HyperGraphProjection, node_vectors::Vector{Vector{OptiEdge}})

Identify induced nodes and node separators from a vector of optiedge partitions.

expand(hyper::HyperGraphProjection, subgraph::OptiGraph, distance::Int64)

Return a new expanded subgraph given the optigraph graph and an existing subgraph subgraph. The returned subgraph contains the expanded neighborhood within distance of the given subgraph.