JuMP.Containers
This page lists the public API of JuMP.Containers
.
This page is an unstructured list of the JuMP.Containers API. For a more structured overview, read the Manual or Tutorial parts of this documentation.
Load all of the public the API into the current scope with:
using JuMP.Containers
Alternatively, load only the module with:
import JuMP.Containers
and then prefix all calls with JuMP.Containers.
to create JuMP.Containers.<NAME>
.
DenseAxisArray
JuMP.Containers.DenseAxisArray
— TypeDenseAxisArray(data::Array{T, N}, axes...) where {T, N}
Construct a JuMP array with the underlying data specified by the data
array and the given axes. Exactly N
axes must be provided, and their lengths must match size(data)
in the corresponding dimensions.
Example
julia> array = Containers.DenseAxisArray([1 2; 3 4], [:a, :b], 2:3)
+JuMP.Containers
This page lists the public API of JuMP.Containers
.
Info This page is an unstructured list of the JuMP.Containers API. For a more structured overview, read the Manual or Tutorial parts of this documentation.
Load all of the public the API into the current scope with:
using JuMP.Containers
Alternatively, load only the module with:
import JuMP.Containers
and then prefix all calls with JuMP.Containers.
to create JuMP.Containers.<NAME>
.
DenseAxisArray
JuMP.Containers.DenseAxisArray
— TypeDenseAxisArray(data::Array{T, N}, axes...) where {T, N}
Construct a JuMP array with the underlying data specified by the data
array and the given axes. Exactly N
axes must be provided, and their lengths must match size(data)
in the corresponding dimensions.
Example
julia> array = Containers.DenseAxisArray([1 2; 3 4], [:a, :b], 2:3)
2-dimensional DenseAxisArray{Int64,2,...} with index sets:
Dimension 1, [:a, :b]
Dimension 2, 2:3
@@ -12,7 +12,7 @@
3 4
julia> array[:b, 3]
-4
sourceDenseAxisArray{T}(undef, axes...) where T
Construct an uninitialized DenseAxisArray with element-type T
indexed over the given axes.
Example
julia> array = Containers.DenseAxisArray{Float64}(undef, [:a, :b], 1:2);
+4
sourceDenseAxisArray{T}(undef, axes...) where T
Construct an uninitialized DenseAxisArray with element-type T
indexed over the given axes.
Example
julia> array = Containers.DenseAxisArray{Float64}(undef, [:a, :b], 1:2);
julia> fill!(array, 1.0)
2-dimensional DenseAxisArray{Float64,2,...} with index sets:
@@ -34,7 +34,7 @@
Dimension 2, 1:2
And data, a 2×2 Matrix{Float64}:
1.0 5.0
- 1.0 1.0
sourceSparseAxisArray
JuMP.Containers.SparseAxisArray
— Typestruct SparseAxisArray{T,N,K<:NTuple{N, Any}} <: AbstractArray{T,N}
+ 1.0 1.0
sourceSparseAxisArray
JuMP.Containers.SparseAxisArray
— Typestruct SparseAxisArray{T,N,K<:NTuple{N, Any}} <: AbstractArray{T,N}
data::OrderedCollections.OrderedDict{K,T}
end
N
-dimensional array with elements of type T
where only a subset of the entries are defined. The entries with indices idx = (i1, i2, ..., iN)
in keys(data)
has value data[idx]
.
Note that, as opposed to SparseArrays.AbstractSparseArray
, the missing entries are not assumed to be zero(T)
, they are simply not part of the array. This means that the result of map(f, sa::SparseAxisArray)
or f.(sa::SparseAxisArray)
has the same sparsity structure as sa
, even if f(zero(T))
is not zero.
Example
julia> using OrderedCollections: OrderedDict
@@ -51,7 +51,7 @@
[b, 3] = 3.0
julia> array[:b, 3]
-3.0
sourceContainers.@container
JuMP.Containers.@container
— Macro@container([i=..., j=..., ...], expr[, container = :Auto])
Create a container with indices i
, j
, ... and values given by expr
that may depend on the value of the indices.
@container(ref[i=..., j=..., ...], expr[, container = :Auto])
Same as above but the container is assigned to the variable of name ref
.
The type of container can be controlled by the container
keyword.
Note When the index set is explicitly given as 1:n
for any expression n
, it is transformed to Base.OneTo(n)
before being given to container
.
Example
julia> Containers.@container([i = 1:3, j = 1:3], i + j)
+3.0
sourceContainers.@container
JuMP.Containers.@container
— Macro@container([i=..., j=..., ...], expr[, container = :Auto])
Create a container with indices i
, j
, ... and values given by expr
that may depend on the value of the indices.
@container(ref[i=..., j=..., ...], expr[, container = :Auto])
Same as above but the container is assigned to the variable of name ref
.
The type of container can be controlled by the container
keyword.
Note When the index set is explicitly given as 1:n
for any expression n
, it is transformed to Base.OneTo(n)
before being given to container
.
Example
julia> Containers.@container([i = 1:3, j = 1:3], i + j)
3×3 Matrix{Int64}:
2 3 4
3 4 5
@@ -86,7 +86,7 @@
[1, 3] = 4
[2, 2] = 4
[2, 3] = 5
- [3, 3] = 6
sourceContainers.container
JuMP.Containers.container
— Functioncontainer(f::Function, indices[[, ::Type{C} = AutoContainerType], names])
Create a container of type C
with index names names
, indices indices
and values at given indices given by f
.
If the method with names
is not specialized on Type{C}
, it falls back to calling container(f, indices, c)
for backwards compatibility with containers not supporting index names.
Example
julia> Containers.container((i, j) -> i + j, Containers.vectorized_product(Base.OneTo(3), Base.OneTo(3)))
+ [3, 3] = 6
sourceContainers.container
JuMP.Containers.container
— Functioncontainer(f::Function, indices[[, ::Type{C} = AutoContainerType], names])
Create a container of type C
with index names names
, indices indices
and values at given indices given by f
.
If the method with names
is not specialized on Type{C}
, it falls back to calling container(f, indices, c)
for backwards compatibility with containers not supporting index names.
Example
julia> Containers.container((i, j) -> i + j, Containers.vectorized_product(Base.OneTo(3), Base.OneTo(3)))
3×3 Matrix{Int64}:
2 3 4
3 4 5
@@ -115,7 +115,7 @@
[1, 2] = 3
[1, 3] = 4
[2, 3] = 5
- [3, 3] = 6
sourceContainers.rowtable
JuMP.Containers.rowtable
— Functionrowtable([f::Function=identity,] x; [header::Vector{Symbol} = Symbol[]])
Applies the function f
to all elements of the variable container x
, returning the result as a Vector
of NamedTuple
s, where header
is a vector containing the corresponding axis names.
If x
is an N
-dimensional array, there must be N+1
names, so that the last name corresponds to the result of f(x[i])
.
If header
is left empty, then the default header is [:x1, :x2, ..., :xN, :y]
.
Info A Vector
of NamedTuple
s implements the Tables.jl interface, and so the result can be used as input for any function that consumes a 'Tables.jl' compatible source.
Example
julia> model = Model();
+ [3, 3] = 6
sourceContainers.rowtable
JuMP.Containers.rowtable
— Functionrowtable([f::Function=identity,] x; [header::Vector{Symbol} = Symbol[]])
Applies the function f
to all elements of the variable container x
, returning the result as a Vector
of NamedTuple
s, where header
is a vector containing the corresponding axis names.
If x
is an N
-dimensional array, there must be N+1
names, so that the last name corresponds to the result of f(x[i])
.
If header
is left empty, then the default header is [:x1, :x2, ..., :xN, :y]
.
Info A Vector
of NamedTuple
s implements the Tables.jl interface, and so the result can be used as input for any function that consumes a 'Tables.jl' compatible source.
Example
julia> model = Model();
julia> @variable(model, x[i=1:2, j=i:2] >= 0, start = i+j);
@@ -129,7 +129,7 @@
3-element Vector{@NamedTuple{x1::Int64, x2::Int64, y::VariableRef}}:
(x1 = 1, x2 = 1, y = x[1,1])
(x1 = 1, x2 = 2, y = x[1,2])
- (x1 = 2, x2 = 2, y = x[2,2])
sourceContainers.default_container
JuMP.Containers.default_container
— Functiondefault_container(indices)
If indices
is a NestedIterator
, return a SparseAxisArray
. Otherwise, indices
should be a VectorizedProductIterator
and the function returns Array
if all iterators of the product are Base.OneTo
and returns DenseAxisArray
otherwise.
sourceContainers.nested
JuMP.Containers.nested
— Functionnested(iterators...; condition = (args...) -> true)
Create a NestedIterator
.
Example
julia> iterator = Containers.nested(
+ (x1 = 2, x2 = 2, y = x[2,2])
sourceContainers.default_container
JuMP.Containers.default_container
— Functiondefault_container(indices)
If indices
is a NestedIterator
, return a SparseAxisArray
. Otherwise, indices
should be a VectorizedProductIterator
and the function returns Array
if all iterators of the product are Base.OneTo
and returns DenseAxisArray
otherwise.
sourceContainers.nested
JuMP.Containers.nested
— Functionnested(iterators...; condition = (args...) -> true)
Create a NestedIterator
.
Example
julia> iterator = Containers.nested(
() -> 1:2,
(i,) -> ["A", "B"];
condition = (i, j) -> isodd(i) || j == "B",
@@ -139,21 +139,21 @@
3-element Vector{Tuple{Int64, String}}:
(1, "A")
(1, "B")
- (2, "B")
sourceContainers.vectorized_product
JuMP.Containers.vectorized_product
— Functionvectorized_product(iterators...)
Created a VectorizedProductIterator
.
Example
julia> iterator = Containers.vectorized_product(1:2, ["A", "B"]);
+ (2, "B")
sourceContainers.vectorized_product
JuMP.Containers.vectorized_product
— Functionvectorized_product(iterators...)
Created a VectorizedProductIterator
.
Example
julia> iterator = Containers.vectorized_product(1:2, ["A", "B"]);
julia> collect(iterator)
2×2 Matrix{Tuple{Int64, String}}:
(1, "A") (1, "B")
- (2, "A") (2, "B")
sourceContainers.build_error_fn
JuMP.Containers.build_error_fn
— Functionbuild_error_fn(macro_name, args, source)
Return a function that can be used in place of Base.error
, but which additionally prints the macro from which it was called.
sourceContainers.parse_macro_arguments
JuMP.Containers.parse_macro_arguments
— Functionparse_macro_arguments(
+ (2, "A") (2, "B")
sourceContainers.build_error_fn
JuMP.Containers.build_error_fn
— Functionbuild_error_fn(macro_name, args, source)
Return a function that can be used in place of Base.error
, but which additionally prints the macro from which it was called.
sourceContainers.parse_macro_arguments
JuMP.Containers.parse_macro_arguments
— Functionparse_macro_arguments(
error_fn::Function,
args;
valid_kwargs::Union{Nothing,Vector{Symbol}} = nothing,
num_positional_args::Union{Nothing,Int,UnitRange{Int}} = nothing,
-)
Returns a Tuple{Vector{Any},Dict{Symbol,Any}}
containing the ordered positional arguments and a dictionary mapping the keyword arguments.
This specially handles the distinction of @foo(key = value)
and @foo(; key = value)
in macros.
An error is thrown if multiple keyword arguments are passed with the same key.
If valid_kwargs
is a Vector{Symbol}
, an error is thrown if a keyword is not in valid_kwargs
.
If num_positional_args
is not nothing, an error is thrown if the number of positional arguments is not in num_positional_args
.
sourceContainers.parse_ref_sets
JuMP.Containers.parse_ref_sets
— Functionparse_ref_sets(
+)
Returns a Tuple{Vector{Any},Dict{Symbol,Any}}
containing the ordered positional arguments and a dictionary mapping the keyword arguments.
This specially handles the distinction of @foo(key = value)
and @foo(; key = value)
in macros.
An error is thrown if multiple keyword arguments are passed with the same key.
If valid_kwargs
is a Vector{Symbol}
, an error is thrown if a keyword is not in valid_kwargs
.
If num_positional_args
is not nothing, an error is thrown if the number of positional arguments is not in num_positional_args
.
sourceContainers.parse_ref_sets
JuMP.Containers.parse_ref_sets
— Functionparse_ref_sets(
error_fn::Function,
expr;
invalid_index_variables::Vector{Symbol} = Symbol[],
-)
Helper function for macros to construct container objects.
Warning This function is for advanced users implementing JuMP extensions. See container_code
for more details.
Arguments
error_fn
: a function that takes a String
and throws an error, potentially annotating the input string with extra information such as from which macro it was thrown from. Use error
if you do not want a modified error message.expr
: an Expr
that specifies the container, for example, :(x[i = 1:3, [:red, :blue], k = S; i + k <= 6])
Returns
name
: the name of the container, if given, otherwise nothing
index_vars
: a Vector{Any}
of names for the index variables, for example, [:i, gensym(), :k]
. These may also be expressions, like :((i, j))
from a call like :(x[(i, j) in S])
.indices
: an iterator over the indices, for example, Containers.NestedIterator
Example
See container_code
for a worked example.
sourceContainers.build_name_expr
JuMP.Containers.build_name_expr
— Functionbuild_name_expr(
+)
Helper function for macros to construct container objects.
Warning This function is for advanced users implementing JuMP extensions. See container_code
for more details.
Arguments
error_fn
: a function that takes a String
and throws an error, potentially annotating the input string with extra information such as from which macro it was thrown from. Use error
if you do not want a modified error message.expr
: an Expr
that specifies the container, for example, :(x[i = 1:3, [:red, :blue], k = S; i + k <= 6])
Returns
name
: the name of the container, if given, otherwise nothing
index_vars
: a Vector{Any}
of names for the index variables, for example, [:i, gensym(), :k]
. These may also be expressions, like :((i, j))
from a call like :(x[(i, j) in S])
.indices
: an iterator over the indices, for example, Containers.NestedIterator
Example
See container_code
for a worked example.
sourceContainers.build_name_expr
JuMP.Containers.build_name_expr
— Functionbuild_name_expr(
name::Union{Symbol,Nothing},
index_vars::Vector,
kwargs::Dict{Symbol,Any},
@@ -164,12 +164,12 @@
""
julia> Containers.build_name_expr(:y, [:i, :j], Dict{Symbol,Any}(:base_name => "y"))
-:(string("y", "[", string($(Expr(:escape, :i))), ",", string($(Expr(:escape, :j))), "]"))
sourceContainers.add_additional_args
JuMP.Containers.add_additional_args
— Functionadd_additional_args(
+:(string("y", "[", string($(Expr(:escape, :i))), ",", string($(Expr(:escape, :j))), "]"))
sourceContainers.add_additional_args
JuMP.Containers.add_additional_args
— Functionadd_additional_args(
call::Expr,
args::Vector,
kwargs::Dict{Symbol,Any};
kwarg_exclude::Vector{Symbol} = Symbol[],
-)
Add the positional arguments args
to the function call expression call
, escaping each argument expression.
This function is able to incorporate additional positional arguments to call
s that already have keyword arguments.
sourceContainers.container_code
JuMP.Containers.container_code
— Functioncontainer_code(
+)
Add the positional arguments args
to the function call expression call
, escaping each argument expression.
This function is able to incorporate additional positional arguments to call
s that already have keyword arguments.
sourceContainers.container_code
JuMP.Containers.container_code
— Functioncontainer_code(
index_vars::Vector{Any},
indices::Expr,
code,
@@ -194,7 +194,7 @@
Dimension 2, ["A", "B"]
And data, a 2×2 Matrix{String}:
"A" "B"
- "AA" "BB"
sourceContainers.AutoContainerType
JuMP.Containers.AutoContainerType
— TypeAutoContainerType
Pass AutoContainerType
to container
to let the container type be chosen based on the type of the indices using default_container
.
sourceContainers.NestedIterator
JuMP.Containers.NestedIterator
— Typestruct NestedIterator{T}
+ "AA" "BB"
sourceContainers.AutoContainerType
JuMP.Containers.AutoContainerType
— TypeAutoContainerType
Pass AutoContainerType
to container
to let the container type be chosen based on the type of the indices using default_container
.
sourceContainers.NestedIterator
JuMP.Containers.NestedIterator
— Typestruct NestedIterator{T}
iterators::T # Tuple of functions
condition::Function
end
Iterators over the tuples that are produced by a nested for loop.
Construct a NestedIterator
using nested
.
Example
julia> iterators = (() -> 1:2, (i,) -> ["A", "B"]);
@@ -217,6 +217,6 @@
end
(1, "A")
(1, "B")
-(2, "B")
sourceContainers.VectorizedProductIterator
JuMP.Containers.VectorizedProductIterator
— Typestruct VectorizedProductIterator{T}
+(2, "B")
sourceContainers.VectorizedProductIterator
JuMP.Containers.VectorizedProductIterator
— Typestruct VectorizedProductIterator{T}
prod::Iterators.ProductIterator{T}
-end
A wrapper type for Iterators.ProuctIterator
that discards shape information and returns a Vector
.
Construct a VectorizedProductIterator
using vectorized_product
.
sourceSettings
This document was generated with Documenter.jl version 1.6.0 on Tuesday 10 September 2024. Using Julia version 1.10.5.