From abc3c32d286c76d2ac88be31b70d887cdd88e924 Mon Sep 17 00:00:00 2001 From: Chris Coey Date: Thu, 29 Jun 2017 22:25:47 -0400 Subject: [PATCH 1/7] reorganize API a bit, comment where work is needed --- docs/src/apireference.md | 185 ++++++++++++++++++++++----------------- 1 file changed, 104 insertions(+), 81 deletions(-) diff --git a/docs/src/apireference.md b/docs/src/apireference.md index 2767b1fb17..5c7b8257f2 100644 --- a/docs/src/apireference.md +++ b/docs/src/apireference.md @@ -4,60 +4,78 @@ CurrentModule = MathOptInterface # API -Some introduction to API. List basic standalone methods. +[Some introduction to API. List basic standalone methods.] + +## Attributes + +List of attribute categories. ```@docs -AbstractModel -AbstractSolver +AbstractSolverOrModelAttribute +AbstractVariableAttribute +AbstractConstraintAttribute ``` +Functions for getting and setting attributes. + ```@docs -Model -optimize! -freemodel! +cangetattribute +getattribute +getattribute! +cansetattribute +setattribute! ``` -## Variables +## Solver and Model + +[separate solver and model?] ```@docs -VariableReference -candelete(::AbstractModel,::VariableReference) -isvalid(::AbstractModel,::VariableReference) -delete!(::AbstractModel,::VariableReference) -addvariables! -addvariable! +AbstractModel +AbstractSolver ``` -## Objectives - -How to add and set objectives. ```@docs -setobjective! -modifyobjective! -getobjectiveconstant -getobjectiveaffine +Model +optimize! +freemodel! ``` -## Constraints +List of solver or model attributes. [category AbstractSolverOrModelAttribute] -How to add and modify constraints. ```@docs -VariablewiseConstraintReference -AffineConstraintReference -QuadraticConstraintReference -candelete(::AbstractModel,::ConstraintReference) -isvalid(::AbstractModel,::ConstraintReference) -delete!(::AbstractModel,::ConstraintReference) -addconstraint! -modifyconstraint! -getconstraintconstant -getconstraintaffine -getconstraintquadratic +ReturnsDuals +SupportsAddConstraintAfterSolve +SupportsDeleteConstraint +SupportsAddVariableAfterSolver +SupportsQuadraticObjective +SupportsConicThroughQuadratic +ObjectiveValue +ObjectiveBound +RelativeGap +SolveTime +Sense +SimplexIterations +BarrierIterations +NodeCount +RawSolver +ResultCount +NumberOfVariables +NumberOfVariablewiseConstraints +NumberOfAffineConstraints +NumberOfQuadraticConstraints +SupportsVariablewiseConstraint +SupportsAffineConstraint +SupportsQuadraticConstraint +TerminationStatus +PrimalStatus +DualStatus ``` ## Sets -List of sets. +List of recognized sets. + ```@docs AbstractSet Reals @@ -81,68 +99,65 @@ SOS2 ``` Functions for getting and setting properties of sets. + ```@docs dimension ``` -## Attributes - -### Solver or Model Attributes +## Variables -List of solver or model attributes. -```@docs -ReturnsDuals -SupportsAddConstraintAfterSolve -SupportsDeleteConstraint -SupportsAddVariableAfterSolver -SupportsQuadraticObjective -SupportsConicThroughQuadratic -ObjectiveValue -ObjectiveBound -RelativeGap -SolveTime -Sense -SimplexIterations -BarrierIterations -NodeCount -RawSolver -ResultCount -NumberOfVariables -NumberOfVariablewiseConstraints -NumberOfAffineConstraints -NumberOfQuadraticConstraints -SupportsVariablewiseConstraint -SupportsAffineConstraint -SupportsQuadraticConstraint -TerminationStatus -PrimalStatus -DualStatus -``` +Variable references and functions for adding and deleting variables. -Functions for getting and setting model or solver attributes. +[attribute that points to the (scalar) variable domain??? eg GreaterThan, NonNegatives, ZeroOne, SemiInteger] ```@docs -AbstractSolverOrModelAttribute -AbstractVariableAttribute -AbstractConstraintAttribute -cangetattribute -getattribute -getattribute! -cansetattribute -setattribute! +VariableReference +candelete(::AbstractModel,::VariableReference) +isvalid(::AbstractModel,::VariableReference) +delete!(::AbstractModel,::VariableReference) +addvariables! +addvariable! ``` -### Variable Attributes +List of attributes associated with variables. [category AbstractVariableAttribute] Calls to `getattribute` and `setattribute!` should include as an argument a single `VariableReference` or a vector of `VariableReference` objects. -List of attributes associated with variables. Calls to `getattribute` and `setattribute!` should include as an argument a single `VariableReference` or a vector of `VariableReference` objects. ```@docs VariablePrimalStart VariablePrimal VariableBasisStatus ``` -### Constraint Attributes +## Objectives + +Functions for adding and modifying objectives. + +```@docs +setobjective! +modifyobjective! +getobjectiveconstant +getobjectiveaffine +``` + +## Constraints + +Constraint references and functions for adding, modifying, and removing constraints. + +```@docs +VariablewiseConstraintReference +AffineConstraintReference +QuadraticConstraintReference +candelete(::AbstractModel,::ConstraintReference) +isvalid(::AbstractModel,::ConstraintReference) +delete!(::AbstractModel,::ConstraintReference) +addconstraint! +modifyconstraint! +getconstraintconstant +getconstraintaffine +getconstraintquadratic +``` + +List of attributes associated with constraints. [category AbstractConstraintAttribute] Calls to `getattribute` and `setattribute!` should include as an argument a single `ConstraintReference` or a vector of `ConstraintReference{T}` objects. -List of attributes associated with constraints. Calls to `getattribute` and `setattribute!` should include as an argument a single `ConstraintReference` or a vector of `ConstriaintReference{T}` objects. +[why is ConstraintBasisStatus under constraint attributes but below we have a basis status attribute separately??] ```@docs ConstraintPrimalStart ConstraintDualStart @@ -155,20 +170,28 @@ ConstraintBasisStatus ### Termination Status -The `TerminationStatus` attribute is meant to explain the reason why the solver stopped executing. The value of the attribute is of type `TerminationStatusCode`. +The `TerminationStatus` attribute indicates why the solver stopped executing. The value of the attribute is of type `TerminationStatusCode`. + ```@docs +TerminationStatus TerminationStatusCode ``` ### Result Status -The `PrimalStatus` and `DualStatus` attributes are meant to explain how to interpret the result returned by the solver. The value of the attributes are of type `ResultStatusCode`. +The `PrimalStatus` and `DualStatus` attributes indicate how to interpret the result returned by the solver. The value of the attribute is of type `ResultStatusCode`. + ```@docs +PrimalStatus +DualStatus ResultStatusCode ``` ### Basis Status +[what?] + ```@docs +BasisStatus BasisStatusCode ``` From 2b33d2def8e40aff6665284124399a37d5140a42 Mon Sep 17 00:00:00 2001 From: Chris Coey Date: Thu, 29 Jun 2017 23:11:13 -0400 Subject: [PATCH 2/7] update model and dual definitions --- docs/src/apimanual.md | 40 ++++++++++++++++++++++++++++------------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/docs/src/apimanual.md b/docs/src/apimanual.md index 844cf6bc55..83083b1e2b 100644 --- a/docs/src/apimanual.md +++ b/docs/src/apimanual.md @@ -3,7 +3,7 @@ ## Concepts -We define the standard form problem as: +The standard form problem is: ```math \begin{align} @@ -13,32 +13,48 @@ We define the standard form problem as: \end{align} ``` -At the moment all functions are described compactly with lists, vectors, and matrices. NLP is a special case discussed later. An objective function ``f_0`` can be affine or quadratic. The constraint functions ``f_i`` can be variablewise, affine, or quadratic (to be defined). +where: +* objective function ``f_0`` is affine or quadratic +* constraint functions ``f_i`` is variable-wise, affine, or quadratic +* constraint sets ``\mathcal{S}_i`` are pre-defined real scalar or vector sets + +Currently, all functions are described compactly with lists, vectors, and matrices. +The function types are: +* variable-wise: ``x_j`` (scalar variable) +* affine: ``A_i x + b_i`` (where ``A_i`` is a matrix and ``b_i`` is a vector) +* quadratic: ``q(x) + A_i x + b_i`` (where ``q(x)`` is a vector of quadratic expressions each of the form ``x^T Q_{i,k} x``) + +This API defines some commonly-used sets, but is extensible to other sets recognized by the solver. ## Duals -So far, we define a convention for duals for conic representable problems. We do not define behavior for duals involving quadratic constraints. -We take the convention that duals on lower bounds (`GreaterThan`) should be nonnegative, duals on upper bounds (`LessThan`) should be nonpositive, and duals on closed convex cones should belong to the dual cone. +Currently, a convention for duals is not defined for problems with non-conic sets ``\mathcal{S}_i`` or quadratic functions ``f_0, f_i``. Note that bound constraints are supported by re-interpretation in terms of the nonnegative or nonpositive cones. An affine constraint ``a^T x + b \ge c`` should be interpreted as ``a^T x + b - c \in \mathbb{R}_+``, and similarly ``a^T x + b \le c`` should be interpreted as ``a^T x + b - c \in \mathbb{R}_-``. Variable-wise constraints should be interpreted as affine constraints with the appropriate identity mapping in place of ``A_i``. -For minimization problems in conic form, we can define the primal as: +For such conic form minimization problems, the primal is: ```math \begin{align} -& \min_{x \in \mathbb{R}^n} & b_0^Tx +& \min_{x \in \mathbb{R}^n} & a_0^T x + b_0 \\ -& \;\;\text{s.t.} & A_ix + b_i & \in \mathcal{C}_i & \forall i +& \;\;\text{s.t.} & A_i x + b_i & \in \mathcal{S}_i & i = 1 \ldots m \end{align} ``` -and the dual as: + +and the dual is: ```math \begin{align} -& \max_{y_i \forall i} & -\sum_i b_i^T y_i +& \max_{y_1, \ldots, y_m} & -\sum_{i=1}^m b_i^T y_i + b_0 \\ -& \;\;\text{s.t.} & b_0 - \sum_i A_i^T y_i &= 0 +& \;\;\text{s.t.} & a_0 - \sum_{i=1}^m A_i^T y_i \in {0}^n \\ -& & y_i \in \mathcal{C}_i^* && \forall i +& & y_i & \in \mathcal{S}_i^* & i = 1 \ldots m \end{align} ``` -``a^Tx + b \ge c`` should be interpreted (for the purposes of duals) as ``a^Tx + b - c \in \mathbb{R}_+``, and similarly ``a^Tx + b \le c`` should be interpreted (for the purposes of duals) as ``a^Tx + b - c \in \mathbb{R}_-``. Variablewise constraints should be interpreted as affine constraints with the appropriate identity mapping in place of ``A_i``. +where each ``\mathcal{C}_i`` is a closed convex cone and ``\mathcal{C}_i`` is its dual cone. + +Note: +* lower bounds have nonnegative duals +* upper bounds have nonpositive duals +* closed convex cones have duals belonging to the corresponding dual cones From 5731c0688799a1d7b6251a9738803130d81c8e56 Mon Sep 17 00:00:00 2001 From: Chris Coey Date: Fri, 30 Jun 2017 01:07:58 -0400 Subject: [PATCH 3/7] made source files consistent --- docs/src/apimanual.md | 6 +- src/MathOptInterface.jl | 26 ++-- src/attributes.jl | 260 +++++++++++++++++++++------------------- src/constraints.jl | 225 ++++++++++++++++------------------ src/objectives.jl | 121 +++++++++---------- src/references.jl | 24 ++-- src/sets.jl | 17 ++- src/variables.jl | 24 ++-- 8 files changed, 342 insertions(+), 361 deletions(-) diff --git a/docs/src/apimanual.md b/docs/src/apimanual.md index 83083b1e2b..833f905a6a 100644 --- a/docs/src/apimanual.md +++ b/docs/src/apimanual.md @@ -20,9 +20,9 @@ where: Currently, all functions are described compactly with lists, vectors, and matrices. The function types are: -* variable-wise: ``x_j`` (scalar variable) -* affine: ``A_i x + b_i`` (where ``A_i`` is a matrix and ``b_i`` is a vector) -* quadratic: ``q(x) + A_i x + b_i`` (where ``q(x)`` is a vector of quadratic expressions each of the form ``x^T Q_{i,k} x``) +* variable-wise: ``x_j``, a (scalar) variable +* affine: ``A_i x + b_i``, where ``A_i`` is a matrix and ``b_i`` is a vector +* quadratic: ``q_i(x) + A_i x + b_i``, where ``q_i(x)`` is a scalar quadratic expression of the form``\frac{1}{2} x^T Q_{i,k} x`` (for objective or constraints), or a vector of such quadratic expressions (for constraints only) This API defines some commonly-used sets, but is extensible to other sets recognized by the solver. diff --git a/src/MathOptInterface.jl b/src/MathOptInterface.jl index 0be903d7ef..73a66f7998 100644 --- a/src/MathOptInterface.jl +++ b/src/MathOptInterface.jl @@ -1,26 +1,25 @@ module MathOptInterface -# package code goes here - """ AbstractSolver -Abstract supertype for "solver" objects. A solver is a lightweight object used for selecting solvers and parameters. It does not store any instance data. +Abstract supertype for "solver" objects. +A solver is a lightweight object used for selecting solvers and parameters. +It does not store any instance data. """ abstract type AbstractSolver end """ AbstractModel -Abstract supertype which represents a solver's in-memory representation of an -optimization problem. +Abstract supertype which represents a solver's in-memory representation of an optimization problem. """ abstract type AbstractModel end """ - Model(solver::AbstractMathProgSolver) + Model(solver::AbstractSolver) -Create an instance of `AbstractModel` using the given solver. +Create an instance of ``AbstractModel`` using the given solver. """ function Model end @@ -34,11 +33,9 @@ function optimize! end """ freemodel!(m::AbstractModel) -Release any resources and memory used by the model. Note that the -Julia garbage collector takes care of this automatically, but -automatic collection cannot always be forced. This method is useful for more -precise control of resources, especially in the case of commercial solvers -with licensing restrictions on the number of concurrent runs. +Release any resources and memory used by the model. +Note that the Julia garbage collector takes care of this automatically, but automatic collection cannot always be forced. +This method is useful for more precise control of resources, especially in the case of commercial solvers with licensing restrictions on the number of concurrent runs. Users must discard the model object after this method is invoked. """ function freemodel! end @@ -46,7 +43,8 @@ function freemodel! end """ writeproblem(m::AbstractModel, filename::String) -Writes the current problem data to the given file. Supported file types are solver-dependent. +Writes the current problem data to the given file. +Supported file types are solver-dependent. """ function writeproblem end @@ -58,4 +56,4 @@ include("references.jl") include("sets.jl") include("variables.jl") -end # module +end diff --git a/src/attributes.jl b/src/attributes.jl index 9cad7cfe56..0ce3ddb5ff 100644 --- a/src/attributes.jl +++ b/src/attributes.jl @@ -1,63 +1,61 @@ +# Attributes + """ AbstractSolverOrModelAttribute -Abstract supertype for attribute objects that can be used -to set or get attributes (properties) -of the model or solver. +Abstract supertype for attribute objects that can be used to set or get attributes (properties) of the model or solver. """ abstract type AbstractSolverOrModelAttribute end """ AbstractVariableAttribute -Abstract supertype for attribute objects that can be used -to set or get attributes (properties) of variables in the model. +Abstract supertype for attribute objects that can be used to set or get attributes (properties) of variables in the model. """ abstract type AbstractVariableAttribute end """ AbstractConstraintAttribute -Abstract supertype for attribute objects that can be used -to set or get attributes (properties) of constraints in the model. +Abstract supertype for attribute objects that can be used to set or get attributes (properties) of constraints in the model. """ abstract type AbstractConstraintAttribute end -const AnyAttribute = Union{AbstractSolverOrModelAttribute,AbstractVariableAttribute,AbstractConstraintAttribute} +const AnyAttribute = Union{AbstractSolverOrModelAttribute, AbstractVariableAttribute, AbstractConstraintAttribute} """ getattribute(s::AbstractSolver, attr::AbstractSolverOrModelAttribute) -Return an attribute `attr` of the solver `s`. +Return an attribute ``attr`` of the solver ``s``. getattribute(m::AbstractModel, attr::AbstractSolverOrModelAttribute) -Return an attribute `attr` of the model `m`. +Return an attribute ``attr`` of the model ``m``. getattribute(m::AbstractModel, attr::AbstractVariableAttribute, v::VariableReference) -Return an attribute `attr` of the variable `v` in model `m`. +Return an attribute ``attr`` of the variable ``v`` in model ``m``. getattribute(m::AbstractModel, attr::AbstractVariableAttribute, v::Vector{VariableReference}) -Return a vector of attributes corresponding to each variable in the collection `v` in the model `m`. +Return a vector of attributes corresponding to each variable in the collection ``v`` in the model ``m``. getattribute(m::AbstractModel, attr::AbstractConstraintAttribute, c::ConstraintReference) -Return an attribute `attr` of the constraint `c` in model `m`. +Return an attribute ``attr`` of the constraint ``c`` in model ``m``. getattribute(m::AbstractModel, attr::AbstractConstraintAttribute, c::Vector{VariablewiseConstraintReference{T}}) getattribute(m::AbstractModel, attr::AbstractConstraintAttribute, c::Vector{AffineConstraintReference{T}}) getattribute(m::AbstractModel, attr::AbstractConstraintAttribute, c::Vector{QuadraticConstraintReference{T}}) -Return a vector of attributes corresponding to each constraint in the collection `c` in the model `m`. +Return a vector of attributes corresponding to each constraint in the collection ``c`` in the model ``m``. -# Examples +### Examples ```julia getattribute(m, ObjectiveValue()) getattribute(m, VariableResult(), ref) -getattribute(m, VariableResult(5), [ref1,ref2]) +getattribute(m, VariableResult(5), [ref1, ref2]) getattribute(m, OtherAttribute("something specific to cplex")) ``` """ @@ -70,7 +68,8 @@ end """ getattribute!(output, m::AbstractModel, args...) -An in-place version of `getattribute`. The signature matches that of `getattribute` except that the the result is placed in the vector `output`. +An in-place version of ``getattribute``. +The signature matches that of ``getattribute`` except that the the result is placed in the vector ``output``. """ function getattribute! end function getattribute!(output, m, attr::AnyAttribute, args...) @@ -80,22 +79,23 @@ end """ cangetattribute(s::AbstractSolver, attr::AbstractSolverOrModelAttribute)::Bool -Return a `Bool` indicating whether it is possible to query attribute `attr` from the solver `s`. +Return a ``Bool`` indicating whether it is possible to query attribute ``attr`` from the solver ``s``. cangetattribute(m::AbstractModel, attr::AbstractVariableAttribute, R::Type{VariableReference})::Bool cangetattribute(m::AbstractModel, attr::AbstractConstraintAttribute, R::Type{VariablewiseConstraintReference{T})::Bool cangetattribute(m::AbstractModel, attr::AbstractConstraintAttribute, R::Type{AffineConstraintReference{T})::Bool cangetattribute(m::AbstractModel, attr::AbstractConstraintAttribute, R::Type{QuadraticConstraintReference{T})::Bool -Return a `Bool` indicating whether the model `m` currently has a value for -the attributed specified by attribute type `attr` applied to the reference type `R`. +Return a ``Bool`` indicating whether the model ``m`` currently has a value for the attributed specified by attribute type ``attr`` applied to the reference type ``R``. + +### Examples -# Examples ```julia cangetattribute(GurobiSolver(), SupportsAffineConstraint{Zero}()) cangetattribute(m, ObjectiveValue()) cangetattribute(m, VariablePrimalStart(), varref) cangetattribute(m, ConstraintPrimal(), conref) +``` """ function cangetattribute end cangetattribute(m::AbstractModel, attr::AnyAttribute) = false @@ -103,21 +103,23 @@ cangetattribute(m::AbstractModel, attr::AnyAttribute) = false """ cansetattribute(s::AbstractSolver, attr::AbstractSolverOrModelAttribute)::Bool -Return a `Bool` indicating whether it is possible to set attribute `attr` in the solver `s`. +Return a ``Bool`` indicating whether it is possible to set attribute ``attr`` in the solver ``s``. cansetattribute(m::AbstractModel, attr::AbstractVariableAttribute, R::Type{VariableReference})::Bool cansetattribute(m::AbstractModel, attr::AbstractConstraintAttribute, R::Type{VariablewiseConstraintReference{T})::Bool cangetattribute(m::AbstractModel, attr::AbstractConstraintAttribute, R::Type{AffineConstraintReference{T})::Bool cangetattribute(m::AbstractModel, attr::AbstractConstraintAttribute, R::Type{QuadraticConstraintReference{T})::Bool -Return a `Bool` indicating whether it is possible to set attribute `attr` applied to the reference type `R` in the model `m`. +Return a ``Bool`` indicating whether it is possible to set attribute ``attr`` applied to the reference type ``R`` in the model ``m``. + +### Examples -# Examples ```julia cansetattribute(GurobiSolver(), SupportsAffineConstraint{Zero}()) cansetattribute(m, ObjectiveValue()) cansetattribute(m, VariablePrimalStart(), VariableReference) cansetattribute(m, ConstraintPrimal(), AffineConstraintReference{NonNegative}) +``` """ function cansetattribute end cansetattribute(m::AbstractModel, attr::AnyAttribute) = false @@ -125,50 +127,50 @@ cansetattribute(m::AbstractModel, attr::AnyAttribute) = false """ setattribute!(s::AbstractSolver, attr::AbstractSolverOrModelAttribute, value) -Assign `value` to the attribute `attr` of the solver `s`. +Assign ``value`` to the attribute ``attr`` of the solver ``s``. setattribute!(m::AbstractModel, attr::AbstractSolverOrModelAttribute, value) -Assign `value` to the attribute `attr` of the model `m`. +Assign ``value`` to the attribute ``attr`` of the model ``m``. setattribute!(m::AbstractModel, attr::AbstractVariableAttribute, v::VariableReference, value) -Assign `value` to the attribute `attr` of variable `v` in model `m`. +Assign ``value`` to the attribute ``attr`` of variable ``v`` in model ``m``. setattribute!(m::AbstractModel, attr::AbstractVariableAttribute, v::Vector{VariableReference}, vector_of_values) -Assign a value respectively to the attribute `attr` of each variable in the collection `v` in model `m`. +Assign a value respectively to the attribute ``attr`` of each variable in the collection ``v`` in model ``m``. setattribute!(m::AbstractModel, attr::AbstractConstraintAttribute, c::ConstraintReference, value) -Assign a value to the attribute `attr` of constraint `c` in model `m`. +Assign a value to the attribute ``attr`` of constraint ``c`` in model ``m``. setattribute!(m::AbstractModel, attr::AbstractConstraintAttribute, c::Vector{VariablewiseConstraintReference{T}}) setattribute!(m::AbstractModel, attr::AbstractConstraintAttribute, c::Vector{AffineConstraintReference{T}}) setattribute!(m::AbstractModel, attr::AbstractConstraintAttribute, c::Vector{QuadraticConstraintReference{T}}) -Assign a value respectively to the attribute `attr` of each constraint in the collection `c` in model `m`. +Assign a value respectively to the attribute ``attr`` of each constraint in the collection ``c`` in model ``m``. """ function setattribute! end function setattribute!(m, attr::AnyAttribute, args...) throw(ArgumentError("Model of type $(typeof(m)) does not support setting the attribute $attr")) end -# Solver or model attributes +## Solver or model attributes """ ReturnsDuals() -A `Bool` indicating if the solver should be expected to return dual -solutions when appropriate. A solver attribute. +A ``Bool`` indicating if the solver should be expected to return dual solutions when appropriate. +A solver attribute. """ struct ReturnsDuals <: AbstractSolverOrModelAttribute end """ SupportsAddConstraintAfterSolver() -A `Bool` indicating if the solver supports adding constraints -after a solve. If `false`, then a new model should be constructed instead. +A ``Bool`` indicating if the solver supports adding constraints after a solve. +If ``false``, then a new model should be constructed instead. A solver attribute. """ struct SupportsAddConstraintAfterSolve <: AbstractSolverOrModelAttribute end @@ -176,17 +178,17 @@ struct SupportsAddConstraintAfterSolve <: AbstractSolverOrModelAttribute end """ SupportsDeleteConstraint() -A `Bool` indicating if the solver supports deleting constraints -from a model. A solver attribute. +A ``Bool`` indicating if the solver supports deleting constraints from a model. +A solver attribute. """ struct SupportsDeleteConstraint <: AbstractSolverOrModelAttribute end """ SupportsAddVariableAfterSolve() -A `Bool` indicating if the solver supports adding variables -after a solve. In the context of linear programming, -this is known as column generation. A solver attribute. +A ``Bool`` indicating if the solver supports adding variables after a solve. +In the context of linear programming, this is known as column generation. +A solver attribute. """ struct SupportsAddVariableAfterSolver <: AbstractSolverOrModelAttribute end @@ -197,7 +199,7 @@ struct SupportsAddVariableAfterSolver <: AbstractSolverOrModelAttribute end """ SupportsQuadraticObjective() -A `Bool` indicating if the solver supports quadratic objectives. +A ``Bool`` indicating if the solver supports quadratic objectives. A solver attribute. """ struct SupportsQuadraticObjective <: AbstractSolverOrModelAttribute end @@ -205,17 +207,18 @@ struct SupportsQuadraticObjective <: AbstractSolverOrModelAttribute end """ SupportsConicThroughQuadratic() -A `Bool` indicating if the solver interprets certain quadratic constraints -as second-order cone constraints. A solver attribute. +A ``Bool`` indicating if the solver interprets certain quadratic constraints as second-order cone constraints. +A solver attribute. """ struct SupportsConicThroughQuadratic <: AbstractSolverOrModelAttribute end """ ObjectiveValue(resultidx::Int=1, objectiveindex::Int=1) -The objective value of the `resultindex`'th primal result of the `objectiveindex`'th objective. A model attribute. +The objective value of the ``resultindex``th primal result of the ``objectiveindex``th objective. +A model attribute. -Both `resultindex` and `objectiveindex` default to 1. +Both ``resultindex`` and ``objectiveindex`` default to 1. """ struct ObjectiveValue <: AbstractSolverOrModelAttribute resultindex::Int @@ -226,28 +229,32 @@ end """ ObjectiveBound() -The best known bound on the optimal objective value. A model attribute. +The best known bound on the optimal objective value. +A model attribute. """ struct ObjectiveBound <: AbstractSolverOrModelAttribute end """ RelativeGap() -The final relative optimality gap as optimization terminated. That is, ``\\frac{|b-f|}{|f|}``, where ``b`` is the best bound and ``f`` is the best feasible objective value. A model attribute. +The final relative optimality gap, defined as ``\frac{|b-f|}{|f|}``, where ``b`` is the best bound and ``f`` is the best feasible objective value. +A model attribute. """ struct RelativeGap <: AbstractSolverOrModelAttribute end """ SolveTime() -The total elapsed solution time (in seconds) as reported by the solver. A model attribute. +The total elapsed solution time (in seconds) as reported by the solver. +A model attribute. """ struct SolveTime <: AbstractSolverOrModelAttribute end """ Sense() -The optimization sense of the model, an `OptimizationSense` with value `MinSense` or `MaxSense`. A model attribute. +The optimization sense of the model, an ``OptimizationSense`` with value ``MinSense`` or ``MaxSense``. +A model attribute. """ struct Sense <: AbstractSolverOrModelAttribute end @@ -256,103 +263,106 @@ struct Sense <: AbstractSolverOrModelAttribute end """ SimplexIterations() -The cumulative number of simplex iterations during the optimization process. In particular, for a MIP the total simplex iterations for all nodes. A model attribute. +The cumulative number of simplex iterations during the optimization process. +In particular, for a mixed-integer program (MIP), the total simplex iterations for all nodes. +A model attribute. """ struct SimplexIterations <: AbstractSolverOrModelAttribute end """ BarrierIterations() -The cumulative number of barrier iterations during the optimization process. A model attribute. +The cumulative number of barrier iterations while solving a problem. +A model attribute. """ struct BarrierIterations <: AbstractSolverOrModelAttribute end """ NodeCount() -The total number of branch-and-bound nodes explored. A model attribute. +The total number of branch-and-bound nodes explored while solving a mixed-integer program (MIP). +A model attribute. """ struct NodeCount <: AbstractSolverOrModelAttribute end """ RawSolver() -An object that may be used to access a solver-specific API for this model. A model attribute. +An object that may be used to access a solver-specific API for this model. +A model attribute. """ struct RawSolver <: AbstractSolverOrModelAttribute end """ ResultCount() -The number of results available. A model attribute. +The number of results available. +A model attribute. """ struct ResultCount <: AbstractSolverOrModelAttribute end """ NumberOfVariables() -The number of variables in the model. A model attribute. +The number of variables in the model. +A model attribute. """ struct NumberOfVariables <: AbstractSolverOrModelAttribute end """ NumberOfVariablewiseConstraints{T}() -The number of variablewise constraints of type T in the model. A model attribute. +The number of variablewise constraints of type ``T`` in the model. +A model attribute. """ struct NumberOfVariablewiseConstraints{T} <: AbstractSolverOrModelAttribute end """ NumberOfAffineConstraints{T}() -The number of affine constraints of type T in the model. A model attribute. +The number of affine constraints of type ``T`` in the model. +A model attribute. """ struct NumberOfAffineConstraints{T} <: AbstractSolverOrModelAttribute end """ NumberOfQuadraticConstraints{T}() -The number of quadratic constraints of type T in the model. A model attribute. +The number of quadratic constraints of type ``T`` in the model. +A model attribute. """ struct NumberOfQuadraticConstraints{T} <: AbstractSolverOrModelAttribute end - """ SupportsVariablewiseConstraint{T}() -A `Bool` indicating whether the solver or model supports -a variablewise constraint in the set ``S`` which -is a set of type `T`. A solver and model attribute. +A ``Bool`` indicating whether the solver or model supports a variable-wise constraint in the set ``s`` of type ``T``. +A solver and model attribute. """ struct SupportsVariablewiseConstraint{T} <: AbstractSolverOrModelAttribute end """ SupportsAffineConstraint{T}() -A `Bool` indicating whether the solver or model supports -a constraint of of the form "affine expression" in ``S`` where ``S`` -is a set of type `T`. A solver and model attribute. +A ``Bool`` indicating whether the solver or model supports an affine constraint in the set ``s`` of type ``T``. +A solver and model attribute. """ struct SupportsAffineConstraint{T} <: AbstractSolverOrModelAttribute end """ SupportsQuadraticConstraint{T}() -A `Bool` indicating whether the solver or model supports -a constraint of of the form "quadratic expression" in ``S`` where ``S`` -is a set of type `T`. A solver and model attribute. +A ``Bool`` indicating whether the solver or model supports a quadratic constraint in the set ``s`` of type ``T``. +A solver and model attribute. """ struct SupportsQuadraticConstraint{T} <: AbstractSolverOrModelAttribute end - - -# Variable attributes +## Variable attributes """ VariablePrimalStart() -An initial assignment of the variables that the solver may use -to warm-start the solve. +An initial assignment of the variables that the solver may use to warm-start the solve. """ struct VariablePrimalStart <: AbstractVariableAttribute end @@ -360,7 +370,8 @@ struct VariablePrimalStart <: AbstractVariableAttribute end VariablePrimal(N) VariablePrimal() -The assignment to the primal variables in result `N`. If `N` is omitted, it is 1 by default. +The assignment to the primal variables in result ``N``. +If ``N`` is omitted, it is 1 by default. """ struct VariablePrimal <: AbstractVariableAttribute N::Int @@ -370,37 +381,37 @@ VariablePrimal() = VariablePrimal(1) """ VariableBasisStatus() -Returns the `BasisStatusCode` of a given variable, with respect to an available optimal solution basis. +Returns the ``BasisStatusCode`` of a given variable, with respect to an available optimal solution basis. """ struct VariableBasisStatus <: AbstractVariableAttribute end """ BasisStatusCode -An Enum of possible values for the `VariableBasisStatus` and `ConstraintBasisStatus` attribute. This explains the status of a given element with respect to an optimal solution basis. Possible values are: - * `Basic`: element is in the basis. - * `Nonbasic`: element is not in the basis. - * `NonbasicAtLower`: element is not in the basis and is at its lower bound. - * `NonbasicAtUpper`: element is not in the basis and is at its upper bound. - * `SuperBasic`: element is not in the basis but is also not at one of its bounds. +An Enum of possible values for the ``VariableBasisStatus`` and ``ConstraintBasisStatus`` attribute. +This explains the status of a given element with respect to an optimal solution basis. +Possible values are: +* ``Basic``: element is in the basis +* ``Nonbasic``: element is not in the basis +* ``NonbasicAtLower``: element is not in the basis and is at its lower bound +* ``NonbasicAtUpper``: element is not in the basis and is at its upper bound +* ``SuperBasic``: element is not in the basis but is also not at one of its bounds """ @enum BasisStatusCode Basic Nonbasic NonbasicAtLower NonbasicAtUpper SuperBasic -# Constraint attributes +## Constraint attributes """ ConstraintPrimalStart() -An initial assignment of the constraint primal values that the solver may use -to warm-start the solve. +An initial assignment of the constraint primal values that the solver may use to warm-start the solve. """ struct ConstraintPrimalStart <: AbstractConstraintAttribute end """ ConstraintDualStart() -An initial assignment of the constriant duals that the solver may use -to warm-start the solve. +An initial assignment of the constriant duals that the solver may use to warm-start the solve. """ struct ConstraintDualStart <: AbstractConstraintAttribute end @@ -408,7 +419,8 @@ struct ConstraintDualStart <: AbstractConstraintAttribute end ConstraintPrimal(N) ConstraintPrimal() -The assignment to the constraint primal values in result `N`. If `N` is omitted, it is 1 by default. +The assignment to the constraint primal values in result ``N``. +If ``N`` is omitted, it is 1 by default. """ struct ConstraintPrimal <: AbstractConstraintAttribute N::Int @@ -419,7 +431,8 @@ ConstraintPrimal() = ConstraintPrimal(1) ConstraintDual(N) ConstraintDual() -The assignment to the constraint dual values in result `N`. If `N` is omitted, it is 1 by default. +The assignment to the constraint dual values in result ``N``. +If ``N`` is omitted, it is 1 by default. """ struct ConstraintDual <: AbstractConstraintAttribute N::Int @@ -429,72 +442,69 @@ ConstraintDual() = ConstraintDual(1) """ ConstraintBasisStatus() -Returns the `BasisStatusCode` of a given constraint, with respect to an available optimal solution basis. +Returns the ``BasisStatusCode`` of a given constraint, with respect to an available optimal solution basis. """ struct ConstraintBasisStatus <: AbstractConstraintAttribute end - - - -# Termination status +## Termination status """ TerminationStatus() -A `TerminationStatusCode` explaining why the solver stopped. A model attribute. +A ``TerminationStatusCode`` explaining why the solver stopped. +A model attribute. """ struct TerminationStatus <: AbstractSolverOrModelAttribute end """ TerminationStatusCode -An Enum of possible values for the `TerminationStatus` attribute. This attribute is meant to explain the reason why the solver stopped executing. +An Enum of possible values for the ``TerminationStatus`` attribute. +This attribute is meant to explain the reason why the solver stopped executing. -# OK +## OK These are generally OK statuses. - * `Success`: the algorithm ran successfully and has a result. This includes cases where the algorithm converges to an infeasible point (NLP) or converges to a solution of a homogeneous self-dual problem and has a certificate of primal/dual infeasibility. - - * `AlmostSuccess`: the algorithm *almost* ran successfully (e.g., to relaxed convergence tolerances) and has a result. - - * `InfeasibleNoResult`: the algorithm stopped because it decided that the problem is infeasible but does not have a result to return. - - * `UnboundedNoResult`: the algorithm stopped because it decided that the problem is unbounded but does not have a result to return. - - * `InfeasibleOrUnbounded`: the algorithm stopped because it decided that the problem is infeasible or unbounded; no result is available. This occasionally happens during MIP presolve. +* ``Success``: the algorithm ran successfully and has a result; this includes cases where the algorithm converges to an infeasible point (NLP) or converges to a solution of a homogeneous self-dual problem and has a certificate of primal/dual infeasibility +* ``AlmostSuccess``: the algorithm *almost* ran successfully (e.g., to relaxed convergence tolerances) and has a result +* ``InfeasibleNoResult``: the algorithm stopped because it decided that the problem is infeasible but does not have a result to return +* ``UnboundedNoResult``: the algorithm stopped because it decided that the problem is unbounded but does not have a result to return +* ``InfeasibleOrUnbounded``: the algorithm stopped because it decided that the problem is infeasible or unbounded (no result is available); this occasionally happens during MIP presolve -# Limits +## Limits The solver stopped because of some user-defined limit. -To be documented: `IterationLimit`, `TimeLimit`, `NodeLimit`, `SolutionLimit`, `MemoryLimit`, `ObjectiveLimit`, `NormLimit`, `OtherLimit`. +To be documented: ``IterationLimit``, ``TimeLimit``, ``NodeLimit``, ``SolutionLimit``, ``MemoryLimit``, ``ObjectiveLimit``, ``NormLimit``, ``OtherLimit``. -# Problematic +## Problematic This group of statuses means that something unexpected or problematic happened. - * `SlowProgress`: the algorithm stopped because it was unable to continue making progress towards the solution. `AlmostSuccess` should be used if there is additional information that relaxed convergence tolerances are satisfied. +* ``SlowProgress``: the algorithm stopped because it was unable to continue making progress towards the solution +* ``AlmostSuccess`` should be used if there is additional information that relaxed convergence tolerances are satisfied -To be documented: `NumericalError`, `InvalidModel`, `InvalidOption`, `Interrupted`, `OtherError`. +To be documented: ``NumericalError``, ``InvalidModel``, ``InvalidOption``, ``Interrupted``, ``OtherError``. """ @enum TerminationStatusCode Success AlmostSuccess InfeasibleNoResult UnboundedNoResult InfeasibleOrUnbounded IterationLimit TimeLimit NodeLimit SolutionLimit MemoryLimit ObjectiveLimit NormLimit OtherLimit SlowProgress NumericalError InvalidModel InvalidOption Interrupted OtherError -# Result status +## Result status """ ResultStatusCode -An Enum of possible values for the `PrimalStatus` and `DualStatus` attributes. The values indicate how to interpret the result vector. +An Enum of possible values for the ``PrimalStatus`` and ``DualStatus`` attributes. +The values indicate how to interpret the result vector. - * `FeasiblePoint` - * `NearlyFeasiblePoint` - * `InfeasiblePoint` - * `InfeasibilityCertificate` - * `NearlyInfeasibilityCertificate` - * `ReductionCertificate` - * `NearlyReductionCertificate` - * `Unknown` - * `Other` +* ``FeasiblePoint`` +* ``NearlyFeasiblePoint`` +* ``InfeasiblePoint`` +* ``InfeasibilityCertificate`` +* ``NearlyInfeasibilityCertificate`` +* ``ReductionCertificate`` +* ``NearlyReductionCertificate`` +* ``Unknown`` +* ``Other`` """ @enum ResultStatusCode FeasiblePoint NearlyFeasiblePoint InfeasiblePoint InfeasibilityCertificate NearlyInfeasibilityCertificate ReductionCertificate NearlyReductionCertificate Unknown Other @@ -502,7 +512,9 @@ An Enum of possible values for the `PrimalStatus` and `DualStatus` attributes. T PrimalStatus(N) PrimalStatus() -The `ResultStatusCode` of the primal result `N`. If `N` is omitted, it defaults to 1. A model attribute. +The ``ResultStatusCode`` of the primal result ``N``. +If ``N`` is omitted, it defaults to 1. +A model attribute. """ struct PrimalStatus <: AbstractSolverOrModelAttribute N::Int @@ -513,7 +525,9 @@ PrimalStatus() = PrimalStatus(1) DualStatus(N) DualStatus() -The `ResultStatusCode` of the dual result `N`. If `N` is omitted, it defaults to 1. A model attribute. +The ``ResultStatusCode`` of the dual result ``N``. +If ``N`` is omitted, it defaults to 1. +A model attribute. """ struct DualStatus <: AbstractSolverOrModelAttribute N::Int diff --git a/src/constraints.jl b/src/constraints.jl index 57591dc14f..7d32ce3086 100644 --- a/src/constraints.jl +++ b/src/constraints.jl @@ -1,181 +1,160 @@ +# Constraints + """ - addconstraint!(m::AbstractModel, b, a_constridx, a_varref::Vector{VariableReference}, a_coef, Q_constridx, Q_vari::Vector{VariableReference}, Q_varj::Vector{VariableReference}, Q_coef, S::AbstractSet)::QuadraticConstraintReference{typeof(S)} + addconstraint!(m::AbstractModel, b, a_constridx, a_v::Vector{VariableReference}, a_coef, Q_constridx, Q_vari::Vector{VariableReference}, Q_varj::Vector{VariableReference}, Q_coef, S::AbstractSet)::QuadraticConstraintReference{typeof(S)} -Add the quadratic-in-set constraint -```math -Ax + b + q(x) \\in S -``` -where ``A`` is a sparse matrix specified in triplet form by -`a_constridx`, `a_varref`, and `a_coef`; ``b`` is a vector; -``q(x)`` is a vector with component ``(q(x))_k`` defined to be ``\\frac{1}{2}x^TQ_kx`` -where the symmetric matrix ``Q_k`` is defined by the triplets in `Q_vari`, `Q_varj`, -`Q_coef` for which `Q_constridx` equals `k`; and the set ``S`` is defined by `S`. +Add the vector quadratic-in-set constraint ``q_i(x) + A_i^T x + b_i \in \mathcal{S}_i``, where: +* ``A_i`` is a sparse matrix specified in triplet form by ``a_constridx, a_v, a_coef`` +* ``b_i`` is a vector specified by ``b`` +* ``q_i(x)`` is a vector with component ``(q_i(x))_k`` defined as ``\frac{1}{2} x^T Q_{i,k} x``, where each symmetric matrix ``Q_{i,k}`` has ``Q_constridx = k`` and is specified in triplet form by ``Q_vari, Q_varj, Q_coef`` +* ``\mathcal{S}_i`` is a pre-defined set specified as ``S`` -Duplicate indices in either the ``A`` or the ``Q`` matrix are accepted and will be summed together. Off-diagonal entries of ``Q`` will be mirrored, so either the upper triangular or lower triangular entries of ``Q`` should be provided. If entries for both ``(i,j)`` and ``(j,i)`` are provided, these are considered duplicate terms. `a_varref`, `Q_vari`, `Q_varj` should be collections of `VariableReference` objects. +Duplicate indices in either the ``A_i`` matrix or any ``Q_{i,k}`` matrix are accepted and will be summed together. +Off-diagonal entries of ``Q_{i,k}`` will be mirrored, so either the upper triangular or lower triangular entries of ``Q_{i,k}`` should be provided. +If entries for both ``(i,j)`` and ``(j,i)`` are provided, these are considered duplicate terms. +``a_v``, ``Q_vari``, ``Q_varj`` should be collections of ``VariableReference`` objects. + addconstraint!(m::AbstractModel, b, a_v::Vector{VariableReference}, a_coef, Q_vari::Vector{VariableReference}, Q_varj::Vector{VariableReference}, Q_coef, S::AbstractSet)::QuadraticConstraintReference{typeof(S)} +Add the scalar quadratic-in-set constraint ``q_i(x) + a_i^T x + b_i \in \mathcal{S}_i``, where: +* ``a_i`` is a sparse vector specified in tuple form by ``a_v, a_coef`` +* ``b_i`` is a scalar specified by ``b`` +* ``q_i(x)`` is defined as ``\frac{1}{2} x^T Q_{i} x``, where the symmetric matrix ``Q_{i}`` is specified in triplet form by ``Q_vari, Q_varj, Q_coef`` +* ``\mathcal{S}_i`` is a pre-defined *scalar* set specified as ``S`` - addconstraint!(m::AbstractModel, b, a_varref::Vector{VariableReference}, a_coef, Q_vari::Vector{VariableReference}, Q_varj::Vector{VariableReference}, Q_coef, S::AbstractSet)::QuadraticConstraintReference{typeof(S)} + addconstraint!(m::AbstractModel, b, a_constridx, a_v::Vector{VariableReference}, a_coef, S::AbstractSet)::AffineConstraintReference{typeof(S)} -A specialized version of `addconstraint!` for one-dimensional sets. -Add the constraint -```math -a^Tx + b + \\frac{1}{2}x^TQx \\in S -``` -where ``a`` is a sparse vector specified in tuple form by -`a_varref`, and `a_coef`; ``b`` is a scalar; -the symmetric matrix ``Q`` is defined by the triplets in `Q_vari`, `Q_varj`, -`Q_coef`; and the set ``S`` is defined by `S`. +Add the vector affine-in-set constraint ``A_i^T x + b_i \in \mathcal{S}_i``, where: +* ``A_i`` is a sparse matrix specified in triplet form by ``a_constridx, a_v, a_coef`` +* ``b_i`` is a vector specified by ``b`` +* ``\mathcal{S}_i`` is a pre-defined set specified as ``S`` - addconstraint!(m::AbstractModel, b, a_constridx, a_varref::Vector{VariableReference}, a_coef, S::AbstractSet)::AffineConstraintReference{typeof(S)} +Duplicate indices in ``A_i`` are accepted and will be summed together. -Add the affine-in-set constraint -```math -Ax + b \\in S -``` -where ``A`` is a sparse matrix specified in triplet form by -`a_constridx`, `a_varref`, and `a_coef`; ``b`` is a vector; and the set ``S`` is defined by `S`. + addconstraint!(m::AbstractModel, b, a_v::Vector{VariableReference}, a_coef, S::AbstractSet)::AffineConstraintReference{typeof(S)} -Duplicate indices either ``A`` are accepted and will be summed together. +Add the scalar affine-in-set constraint ``a_i^T x + b_i \in \mathcal{S}_i``, where: +* ``a_i`` is a sparse vector specified in tuple form by ``a_v, a_coef`` +* ``b_i`` is a scalar specified by ``b`` +* ``\mathcal{S}_i`` is a pre-defined *scalar* set specified as ``S`` - addconstraint!(m::AbstractModel, b, a_varref::Vector{VariableReference}, a_coef, S::AbstractSet)::AffineConstraintReference{typeof(S)} + addconstraint!(m::AbstractModel, vs::Vector{VariableReference}, S::AbstractSet)::VariablewiseConstraintReference{typeof(S)} -A specialized version of `addconstraint!` for one-dimensional sets. -Add the constraint -```math -a^Tx + b \\in S -``` -where ``a`` is a sparse vector specified in tuple form by -`a_varref`, and `a_coef`; ``b`` is a scalar; and the set ``S`` is defined by `S`. +Add the vector variable-wise constraint ``(x_j)_{j \in v_i} \in \mathcal{S}_i``, where: +* ``v_i`` is a list of variable indices specified as a vector of variable references ``vs`` +* ``\mathcal{S}_i`` is a pre-defined set specified as ``S`` + addconstraint!(m::AbstractModel, v::VariableReference, S::AbstractSet)::VariablewiseConstraintReference{typeof(S)} - addconstraint!(m::AbstractModel, varref::Vector{VariableReference}, S::AbstractSet)::VariablewiseConstraintReference{typeof(S)} +Add the scalar variable-wise constraint ``x_j \in \mathcal{S}_i``, where: +* ``x_j`` is variable specified as a variable reference ``v`` +* ``\mathcal{S}_i`` is a pre-defined *scalar* set specified as ``S`` +""" +function addconstraint! end -A specialized version of `addconstraint!` for variablewise constraints. -Add the constraint -```math -x_{varref} \\in S -``` -where `varref` is a vector of variable references to specifiy the subset of the subvector of `x`. +# TODO: method to query if solver supports this type of modification - addconstraint!(m::AbstractModel, varref::VariableReference, S::AbstractSet)::VariablewiseConstraintReference{typeof(S)} -A specialized version of `addconstraint!` for one-dimensional variablewise constraints. -Add the constraint -```math -x_{varref} \\in S -``` -where `varref` is a single variable references to specifiy the index of `x`. """ -function addconstraint! end + getconstraintconstant(m::AbstractModel, c::ConstraintReference, k::Int) -# TODO: method to query if solver supports this type of modification +Return the constant term of the ``k``th row of the constraint ``c``. +""" +function getconstraintconstant end """ - modifyconstraint!(m::AbstractModel, c::ConstraintReference, i::Int, args...) + getconstraintaffine(m::AbstractModel, c::ConstraintReference) -Modify elements of the `i`'th row of the constraint `c` depending on the -arguments `args`. The `i`'th row will have the form -```math - a_i^Tx + b_i + \\frac{1}{2}x^TQ_ix \\in S -``` -There are three cases. +Return the ``A_i`` matrix of the constraint corresponding to ``c`` in triplet form ``(i, v, coef)`, where ``v`` is a ``VariableReference``, and ``coef`` is a coefficient value. +Output is a tuple of three vectors. -# Modify Constant term + getconstraintaffine(m::AbstractModel, c::ConstraintReference, k::Int) - modifyconstraint!(m::AbstractModel, c::ConstraintReference, i::Int, b) +Return the ``k``th row of the ``A_k`` matrix of the constraint corresponding to ``c`` in tuple form ``(v, coef)``, where ``v`` is a ``VariableReference``, and ``coef`` is a coefficient value. +Output is a tuple of two vectors. -Set the constant term of the `i`'th row in the constraint `c` to `b`. + getconstraintaffine(m::AbstractModel, c::ConstraintReference, k::Int, v::VariableReference) -### Examples +Return the element of the ``A_k`` matrix of the constraint corresponding to ``c`` in row ``k`` and variable ``v``. +""" +function getconstraintaffine end -```julia -modifyconstraint!(m, c, 1, 1.0) -``` +""" + getconstraintquadratic(m::AbstractModel, c::ConstraintReference, k::Int) -# Modify Linear term +Return the ``Q_{i,k}`` matrix of the ``k``th row of the constraint corresponding to ``c`` in triplet form ``(v_1, v_2, coef)``, where ``v_1, v_2`` are ``VariableReference``s, and ``coef`` is a coefficient value. +Output is a tuple of three vectors. +The ``Q_{i,k}`` matrix must be symmetric, and only one element is returned. - modifyconstraint!(m::AbstractModel, c::ConstraintReference, i::Int, a_varref::Vector{VariableReference}, a_coef) + getconstraintquadratic(m::AbstractModel, c::ConstraintReference, k::Int, v_1::VariableReference, v_2::VariableReference) -Set elements given by `a_varref` in the linear term of the `i`'th element in the -constraint `c` to `a_coef`. Either `a_varref` and `a_coef` are both singletons, -or they should be collections with equal length. +Return the element ``(v_1, v_2)`` of the ``Q_{i,k}`` matrix of the ``k``th row of the constraint corresponding to ``c``. +""" +function getconstraintquadratic end + +""" + modifyconstraint!(m::AbstractModel, c::ConstraintReference{Set}, S::Set) -The behaviour of duplicate entries in `a_varref` is undefined. +Change the set of constraint ``c`` to the new set ``S`` which should be of the same type as the original set. ### Examples +If ``c`` is a ``ConstraintReference{Interval}`` + ```julia -modifyconstraint!(m, c, v, 1.0) -modifyconstraint!(m, c, [v1, v2], [1.0, 2.0]) +modifyconstraint!(m, c, Interval(0, 5)) +modifyconstraint!(m, c, NonPositive) # errors ``` +""" +function modifyconstraint! end + +""" + modifyconstraint!(m::AbstractModel, c::ConstraintReference, k::Int, args...) -# Modify Quadratic term +Modify elements of the ``k``th row of the constraint ``c`` depending on the arguments ``args``. +The ``k``th row will have the form ``q_{i,k}(x) + A_{i,k}^T x + b_{i,k}`` +There are three cases. - modifyconstraint!(m::AbstractModel, c::ConstraintReference, i::Int, Q_vari, Q_varj, Q_coef) +## Modify Constant term -Set the elements in the quadratic term of the `i`'th element of the constraint `c` -specified by the triplets `Q_vari`, `Q_varj`, and `Q_coef`. Off-diagonal entries -will be mirrored. `Q_vari`, `Q_varj` should be collections of `VariableReference` -objects. + modifyconstraint!(m::AbstractModel, c::ConstraintReference, k::Int, b) -The behaviour of duplicate entries is undefined. If entries for both ``(i,j)`` -and ``(j,i)`` are provided, these are considered duplicate terms. +Set the constant term of the ``k``th row in the constraint ``c`` to ``b``. ### Examples ```julia -modifyconstraint!(m, c, v1, v2, 1.0) -modifyconstraint!(m, c, [v1, v2], [v1, v1], [1.0, 2.0]) +modifyconstraint!(m, c, 1, 1.0) ``` -# Modify Set +## Modify Linear term - modifyconstraint!(m::AbstractModel, c::ConstraintReference{S}, set::S) + modifyconstraint!(m::AbstractModel, c::ConstraintReference, k::Int, a_v::Vector{VariableReference}, a_coef) -Change the set of constraint `c` to the new set `set` which should be of the same -type as the original set. +Set elements given by ``a_v`` in the linear term of the ``k``th row in the constraint ``c`` to ``a_coef``. +Either ``a_v`` and ``a_coef`` are both singletons, or they should be collections with equal length. +The behavior of duplicate entries in ``a_v`` is undefined. ### Examples -If `c` is a `ConstraintReference{Interval}` - ```julia -modifyconstraint!(m, c, Interval(0, 5)) -modifyconstraint!(m, c, NonPositive) # errors +modifyconstraint!(m, c, v, 1.0) +modifyconstraint!(m, c, [v_1, v_2], [1.0, 2.0]) ``` -""" -function modifyconstraint! end - -""" - getconstraintconstant(m::AbstractModel, c::ConstraintReference, i::Int) - -Return the constant term of the `i`th row of the constraint corresponding to `c`. -""" -function getconstraintconstant end - -""" - getconstraintaffine(m::AbstractModel, c::ConstraintReference) - -Return the ``A`` matrix of the constraint corresponding to `c` in triplet form `(row,varref,coef)` where `row` is an integer, `varref` is a `VariableReference`, and `coef` is a coefficient. Output is a tuple of three vectors. - - getconstraintaffine(m::AbstractModel, c::ConstraintReference, i::Int) - -Return the `i`th row of the ``A`` matrix of the constraint corresponding to `c` in tuple form `(varref,coef)` where `varref` is a `VariableReference`, and `coef` is a coefficient. Output is a tuple of two vectors. - - getconstraintaffine(m::AbstractModel, c::ConstraintReference, i::Int, v::VariableReference) -Return the element of the ``A`` matrix of the constraint corresponding to `c` in row `i` and variable `v`. -""" -function getconstraintaffine end +## Modify Quadratic term -""" - getconstraintquadratic(m::AbstractModel, c::ConstraintReference, i::Int) + modifyconstraint!(m::AbstractModel, c::ConstraintReference, k::Int, Q_vari, Q_varj, Q_coef) -Return the ``Q`` matrix of the `i`th row of the constraint corresponding to `c` in triplet form `(varref_a,varref_b,coef)` where `varref_a` is a `VariableReference`, `varref_b` is a `VariableReference`, and `coef` is a coefficient. Output is a tuple of three vectors. The ``Q`` matrix must be symmetric, and only one of the two symmetric elements is returned. +Set the elements in the quadratic term of the ``k``th row of the constraint ``c`` specified by the triplets ``Q_vari, Q_varj, Q_coef``. +Off-diagonal entries will be mirrored. +``Q_vari, Q_varj`` should be collections of ``VariableReference`` objects. +The behavior of duplicate entries is undefined. +If entries for both ``(i,j)`` and ``(j,i)`` are provided, these are considered duplicate terms. - getconstraintquadratic(m::AbstractModel, c::ConstraintReference, i::Int, v1::VariableReference, v2::VariableReference) +### Examples -Return the element `(v1,v2)` of the ``Q`` matrix of the `i`th row of the constraint corresponding to `c`. -""" -function getconstraintquadratic end +```julia +modifyconstraint!(m, c, v_1, v_2, 1.0) +modifyconstraint!(m, c, [v_1, v_2], [v_1, v_1], [1.0, 2.0]) +``` diff --git a/src/objectives.jl b/src/objectives.jl index cf3db0db87..d5f6b27180 100644 --- a/src/objectives.jl +++ b/src/objectives.jl @@ -1,50 +1,62 @@ +# Objectives + """ setobjective!(m::AbstractModel, b, a_varref::Vector{VariableReference}, a_coef, Q_vari::Vector{VariableReference}, Q_varj::Vector{VariableReference}, Q_coef, N::Int=1) -Set the `N`'th objective in the model `m` to be -```math -a^Tx + b + \\frac{1}{2}x^TQx -``` -where ``a`` is a sparse vector specified in tuple form by `a_varref`, and -`a_coef`; ``b`` is a scalar; and the symmetric matrix ``Q`` is defined by the -triplets in `Q_vari`, `Q_varj`, `Q_coef`. +Set the ``N``th objective in the model ``m`` to be ``\frac{1}{2} x^T Q_0 x + a_0^T x + b_0``, where: +* ``a_0`` is a sparse vector specified in tuple form by ``a_varref, a_coef`` +* ``b_0`` is a scalar +* the symmetric matrix ``Q_0`` is defined by the triplets in ``Q_vari, Q_varj, Q_coef`` -Duplicate indices in either the ``a`` vector or the ``Q`` matrix are accepted and will be -summed together. Off-diagonal entries of ``Q`` will be mirrored, so either the -upper triangular or lower triangular entries of ``Q`` should be provided. If -entries for both ``(i,j)`` and ``(j,i)`` are provided, these are considered -duplicate terms. `a_varref`, `Q_vari`, `Q_varj` should be collections of -`VariableReference` objects. +Duplicate indices (sparse) in either the``a_0`` vector or the ``Q_0`` matrix are accepted and will be summed together. +Off-diagonal entries of ``Q_0`` will be mirrored, so either the upper triangular or lower triangular entries of ``Q_0`` should be provided. +If entries for both ``(i,j)`` and ``(j,i)`` are provided, these are considered duplicate terms. +``a_varref``, ``Q_vari``, ``Q_varj`` should be collections of ``VariableReference`` objects. setobjective!(m::AbstractModel, b, a_varref::Vector{VariableReference}, a_coef, N::Int=1) -Set the `N`'th objective in the model `m` to be -```math -a^Tx + b -``` -where ``a`` is a sparse vector specified in tuple form by `a_varref` and -`a_coef` and ``b`` is a scalar. +Set the ``N``th objective in the model ``m`` to be ``a_0^T x + b_0``, where: +* ``a_0`` is a sparse vector specified in tuple form by ``a_varref, a_coef`` +* ``b_0`` is a scalar -Duplicate indices in either the ``a`` vector are accepted and will be -summed together. +Duplicate indices (sparse) in either the``a_0`` vector or the ``Q_0`` matrix are accepted and will be summed together. """ function setobjective! end """ - modifyobjective!(m::AbstractModel, i::Int, args...) + getobjectiveconstant(m, N::Int=1) -Modify elements of the `i`'th objective depending on the -arguments `args`. The `i`'th objective will have the form: -```math - a_i^Tx + b_i + \\frac{1}{2}x^TQ_ix -``` -There are three cases. +Return the constant term in the ``N``th objective. +""" +function getobjectiveconstant end + +""" + getobjectiveaffine(m, N::Int=1) + +Return the affine part of the ``N``th objective in tuple form ``(varref, coef)`` where ``varref`` is a ``VariableReference`` and ``coef`` is a coefficient. +Output is a tuple of two vectors. + + getobjectiveaffine(m, v::VariableReference, N::Int=1) + +Return the coefficient for the variable ``v`` in the affine part of the ``N``th objective. +""" +function getobjectiveaffine end + +## TODO: getobjectivequadratic + +""" + modifyobjective!(m::AbstractModel, N::Int, args...) + +Modify elements of the ``N``th objective depending on the arguments ``args``. +The ``N``th objective has the form ``\frac{1}{2} x^T Q_0 x + a_0^T x + b_0``. -# Modify Constant term +There are three cases, below. - modifyobjective!(m::AbstractModel, i::Int, b) +## Modify Constant term -Set the constant term of the `i`'th row objective to `b`. + modifyobjective!(m::AbstractModel, N::Int, b_0) + +Set the constant term of the ``N``th objective to ``b_0``. ### Examples @@ -52,15 +64,13 @@ Set the constant term of the `i`'th row objective to `b`. modifyobjective!(m, 1, 1.0) ``` -# Modify Linear term - - modifyobjective!(m::AbstractModel, i::Int, a_varidx, a_coef) +## Modify Linear term -Set elements given by `a_varidx` in the linear term of the `i`'th objective to -`a_coef`. Either `a_varidx` and `a_coef` are both singletons, or they should be -collections with equal length. + modifyobjective!(m::AbstractModel, N::Int, a_varidx, a_coef) -The behaviour of duplicate entries in `a_varidx` is undefined. +Set elements given by ``a_varidx`` in the linear term of the ``N``th objective to ``a_coef``. +Either ``a_varidx`` and ``a_coef`` are both singletons, or they should be collections with equal length. +The behavior of duplicate entries in ``a_varidx`` is undefined. ### Examples @@ -69,16 +79,15 @@ modifyobjective!(m, 1, v, 1.0) modifyobjective!(m, 1, [v1, v2], [1.0, 2.0]) ``` -# Modify Quadratic term - - modifyobjective!(m::AbstractModel, i::Int, Q_vari, Q_varj, Q_coef) +## Modify Quadratic term -Set the elements in the quadratic term of the `i`'th objective specified by the -triplets `Q_vari`, `Q_varj`, and `Q_coef`. Off-diagonal entries will be mirrored. -`Q_vari`, `Q_varj` should be collections of `VariableReference` objects. + modifyobjective!(m::AbstractModel, N::Int, Q_vari, Q_varj, Q_coef) -The behaviour of duplicate entries is undefined. If entries for both ``(i,j)`` -and ``(j,i)`` are provided, these are considered duplicate terms. +Set the elements in the quadratic term of the ``N``th objective specified by the triplets ``Q_vari, Q_varj, Q_coef``. +Off-diagonal entries will be mirrored. +``Q_vari, Q_varj`` should be collections of ``VariableReference`` objects. +The behavior of duplicate entries is undefined. +If entries for both ``(i,j)`` and ``(j,i)`` are provided, these are considered duplicate terms. ### Examples @@ -88,23 +97,3 @@ modifyobjective!(m, 1, [v1, v2], [v1, v1], [1.0, 2.0]) ``` """ function modifyobjective! end - -""" - getobjectiveconstant(m, i::Int=1) - -Return the constant term in the `i`'th objective. -""" -function getobjectiveconstant end - -""" - getobjectiveaffine(m, i::Int=1) - -Return the affine part of the `i`'th objective in tuple form `(varref,coef)` where `varref` is a `VariableReference`, and `coef` is a coefficient. Output is a tuple of two vectors. - - getobjectiveaffine(m, v::VariableReference, i::Int=1) - -Return the coefficient for the variable `v` in the affine part of the `i`'th objective. -""" -function getobjectiveaffine end - -## TODO: getobjectivequadratic diff --git a/src/references.jl b/src/references.jl index 757df0b881..24f4c8f041 100644 --- a/src/references.jl +++ b/src/references.jl @@ -1,8 +1,10 @@ +# References + """ VariablewiseConstraintReference{T} A lightweight object used to reference variablewise constraints in a model. -The parameter `T` is the type of set constraint referenced. +The parameter ``T`` is the type of set constraint referenced. """ struct VariablewiseConstraintReference{T} value::UInt64 @@ -12,7 +14,7 @@ end AffineConstraintReference{T} A lightweight object used to reference affine-in-set constraints in a model. -The parameter `T` is the type of set constraint referenced. +The parameter ``T`` is the type of set constraint referenced. """ struct AffineConstraintReference{T} value::UInt64 @@ -22,26 +24,25 @@ end QuadraticConstraintReference{T} A lightweight object used to reference quadratic-in-set constraints in a model. -The parameter `T` is the type of set constraint referenced. +The parameter ``T`` is the type of set constraint referenced. """ struct QuadraticConstraintReference{T} value::UInt64 end -const ConstraintReference = Union{VariablewiseConstraintReference,AffineConstraintReference,QuadraticConstraintReference} +const ConstraintReference = Union{VariablewiseConstraintReference, AffineConstraintReference, QuadraticConstraintReference} """ candelete(m::AbstractModel, ref::ConstraintReference)::Bool -Return a `Bool` indicating whether this constraint can be removed from the model `m`. +Return a ``Bool`` indicating whether this constraint can be removed from the model ``m``. """ candelete(m::AbstractModel, ref::ConstraintReference) = throw(MethodError()) """ isvalid(m::AbstractModel, ref::ConstraintReference)::Bool -Return a `Bool` indicating whether this reference is valid -for an active constraint in the model `m`. +Return a ``Bool`` indicating whether this reference is valid for an active constraint in the model ``m``. """ isvalid(m::AbstractModel, ref::ConstraintReference) = throw(MethodError()) @@ -52,7 +53,7 @@ Delete the referenced constraint from the model. delete!(m::AbstractModel, refs::Vector{ConstraintReference}) -Delete the referenced constraints in the vector `refs` from the model. +Delete the referenced constraints in the vector ``refs`` from the model. """ Base.delete!(m::AbstractModel, ref::ConstraintReference) = throw(MethodError()) Base.delete!(m::AbstractModel, refs::Vector{ConstraintReference}) = throw(MethodError()) @@ -69,15 +70,14 @@ end """ candelete(m::AbstractModel, ref::VariableReference)::Bool -Return a `Bool` indicating whether this variable can be removed from the model `m`. +Return a ``Bool`` indicating whether this variable can be removed from the model ``m``. """ candelete(m::AbstractModel, ref::VariableReference) = throw(MethodError()) """ isvalid(m::AbstractModel, ref::VariableReference)::Bool -Return a `Bool` indicating whether this reference is valid -for an active variable in the model `m`. +Return a ``Bool`` indicating whether this reference is valid for an active variable in the model ``m``. """ isvalid(m::AbstractModel, ref::VariableReference) = throw(MethodError()) @@ -88,7 +88,7 @@ Delete the referenced variable from the model. delete!(m::AbstractModel, refs::Vector{VariableReference}) -Delete the referenced variables in the vector `refs` from the model. +Delete the referenced variables in the vector ``refs`` from the model. """ Base.delete!(m::AbstractModel, ref::VariableReference) = throw(MethodError()) Base.delete!(m::AbstractModel, refs::Vector{VariableReference}) = throw(MethodError()) diff --git a/src/sets.jl b/src/sets.jl index 1ea3f2987d..6ff4548299 100644 --- a/src/sets.jl +++ b/src/sets.jl @@ -1,3 +1,5 @@ +# Sets + """ AbstractSet @@ -69,7 +71,8 @@ end """ Interval(lower,upper) -The interval ``[lower, upper] \\subseteq \\mathbb{R}``. If ``lower`` or ``upper`` is ``-Inf`` or ``Inf``, respectively, the set is interpreted as a one-sided interval. +The interval ``[lower, upper] \\subseteq \\mathbb{R}``. +If ``lower`` or ``upper`` is ``-Inf`` or ``Inf``, respectively, the set is interpreted as a one-sided interval. """ struct Interval{T <: Real} <: AbstractSet lower::T @@ -190,7 +193,11 @@ dimension(s::Union{Integers,ZeroOne}) = 1 """ SOS1(weights) -The set corresponding to the special ordered set (SOS) constraint of type 1. Of the variables in the set, at most one can be nonzero. The ``weights`` induce an ordering of the variables; as such, they should be unique values. The ``k``-th element in the set corresponds to the ``k``-th weight in ``weights``. See [here](http://lpsolve.sourceforge.net/5.5/SOS.htm) for a description of SOS constraints and their potential uses. +The set corresponding to the special ordered set (SOS) constraint of type 1. +Of the variables in the set, at most one can be nonzero. +The ``weights`` induce an ordering of the variables; as such, they should be unique values. +The ``k``-th element in the set corresponds to the ``k``-th weight in ``weights``. +See [here](http://lpsolve.sourceforge.net/5.5/SOS.htm) for a description of SOS constraints and their potential uses. """ struct SOS1{T <: Real} <: AbstractSet weights::Vector{T} @@ -199,7 +206,11 @@ end """ SOS2(weights) -The set corresponding to the special ordered set (SOS) constraint of type 2. Of the variables in the set, at most two can be nonzero, and if two are nonzero, they must be adjacent in the ordering of the set. The ``weights`` induce an ordering of the variables; as such, they should be unique values. The ``k``-th element in the set corresponds to the ``k``-th weight in ``weights``. See [here](http://lpsolve.sourceforge.net/5.5/SOS.htm) for a description of SOS constraints and their potential uses. +The set corresponding to the special ordered set (SOS) constraint of type 2. +Of the variables in the set, at most two can be nonzero, and if two are nonzero, they must be adjacent in the ordering of the set. +The ``weights`` induce an ordering of the variables; as such, they should be unique values. +The ``k``-th element in the set corresponds to the ``k``-th weight in ``weights``. +See [here](http://lpsolve.sourceforge.net/5.5/SOS.htm) for a description of SOS constraints and their potential uses. """ struct SOS2{T <: Real} <: AbstractSet weights::Vector{T} diff --git a/src/variables.jl b/src/variables.jl index 6c8d654f61..ba72955cea 100644 --- a/src/variables.jl +++ b/src/variables.jl @@ -1,8 +1,9 @@ +# Variables + """ - addvariables!(m::AbstractModel, N::Int)::Vector{VariableReference} + addvariables!(m::AbstractModel, n::Int)::Vector{VariableReference} -Add `N` scalar variables to the model, returning a vector of variable -references. +Add ``n`` scalar variables to the model, returning a vector of variable references. """ function addvariables! end @@ -10,22 +11,11 @@ function addvariables! end addvariable!(m::AbstractModel)::VariableReference Add a scalar variable to the model, returning a variable reference. - In addition, there is a special case for adding variables to existing linear problems. - addvariable!(m::AbstractModel, - cref::Vector{Union{ - AffineConstraintRef{NonPositive}, - AffineConstraintRef{NonNegative}, - AffineConstraintRef{Zero}, - AffineConstraintRef{Interval} - }}, - coefs)::VariableReference + addvariable!(m::AbstractModel, cref::Vector{Union{AffineConstraintRef{NonPositive}, AffineConstraintRef{NonNegative}, AffineConstraintRef{Zero}, AffineConstraintRef{Interval}}}, coefs)::VariableReference -Add a variable with coefficients specified by `coefs` in the existing affine -constraints given by the constraint references `cref`. If you want to add a -variable with coefficients in a constraint that is not listed here (such as a -quadratic term, or in the SOC), use `addvariable!(m)` and then -`modifyconstraint!` instead. +Add a variable with coefficients specified by ``coefs`` in the existing affine constraints given by the constraint references ``cref``. +To add a variable with coefficients in a constraint that is not listed here, use ``addvariable!(m)`` and then ``modifyconstraint!`` instead. """ function addvariable! end From 2a30e041b1953b0e6e254f32f66b2c5504f2202e Mon Sep 17 00:00:00 2001 From: Chris Coey Date: Fri, 30 Jun 2017 01:59:34 -0400 Subject: [PATCH 4/7] fix some bugs and compile docs --- docs/src/apireference.md | 62 +++++++++++++++++++--------------------- docs/src/index.md | 2 +- src/constraints.jl | 40 +++++++++++++------------- 3 files changed, 51 insertions(+), 53 deletions(-) diff --git a/docs/src/apireference.md b/docs/src/apireference.md index 5c7b8257f2..caa4a24537 100644 --- a/docs/src/apireference.md +++ b/docs/src/apireference.md @@ -72,6 +72,32 @@ PrimalStatus DualStatus ``` +### Termination Status + +The ``TerminationStatus`` attribute indicates why the solver stopped executing. +The value of the attribute is of type ``TerminationStatusCode``. + +```@docs +TerminationStatusCode +``` + +### Result Status + +The ``PrimalStatus`` and ``DualStatus`` attributes indicate how to interpret the result returned by the solver. +The value of the attribute is of type ``ResultStatusCode``. + +```@docs +ResultStatusCode +``` + +### Basis Status + +[what? BasisStatus] + +```@docs +BasisStatusCode +``` + ## Sets List of recognized sets. @@ -118,7 +144,8 @@ addvariables! addvariable! ``` -List of attributes associated with variables. [category AbstractVariableAttribute] Calls to `getattribute` and `setattribute!` should include as an argument a single `VariableReference` or a vector of `VariableReference` objects. +List of attributes associated with variables. [category AbstractVariableAttribute] +Calls to ``getattribute`` and ``setattribute!`` should include as an argument a single ``VariableReference`` or a vector of ``VariableReference`` objects. ```@docs VariablePrimalStart @@ -155,7 +182,8 @@ getconstraintaffine getconstraintquadratic ``` -List of attributes associated with constraints. [category AbstractConstraintAttribute] Calls to `getattribute` and `setattribute!` should include as an argument a single `ConstraintReference` or a vector of `ConstraintReference{T}` objects. +List of attributes associated with constraints. [category AbstractConstraintAttribute] +Calls to ``getattribute`` and ``setattribute!`` should include as an argument a single ``ConstraintReference`` or a vector of ``ConstraintReference{T}`` objects. [why is ConstraintBasisStatus under constraint attributes but below we have a basis status attribute separately??] ```@docs @@ -165,33 +193,3 @@ ConstraintPrimal ConstraintDual ConstraintBasisStatus ``` - -## Status Codes - -### Termination Status - -The `TerminationStatus` attribute indicates why the solver stopped executing. The value of the attribute is of type `TerminationStatusCode`. - -```@docs -TerminationStatus -TerminationStatusCode -``` - -### Result Status - -The `PrimalStatus` and `DualStatus` attributes indicate how to interpret the result returned by the solver. The value of the attribute is of type `ResultStatusCode`. - -```@docs -PrimalStatus -DualStatus -ResultStatusCode -``` - -### Basis Status - -[what?] - -```@docs -BasisStatus -BasisStatusCode -``` diff --git a/docs/src/index.md b/docs/src/index.md index 55b9307070..9a35881127 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -3,6 +3,6 @@ [MathOptInterface.jl](https://github.com/JuliaOpt/MathOptInterface.jl) is a standardized API for Mathematical Optimization solvers. ```@contents -Pages = ["apimanual.md","apireference.md"] +Pages = ["apimanual.md", "apireference.md"] Depth = 3 ``` diff --git a/src/constraints.jl b/src/constraints.jl index 7d32ce3086..74cc017721 100644 --- a/src/constraints.jl +++ b/src/constraints.jl @@ -54,7 +54,6 @@ function addconstraint! end # TODO: method to query if solver supports this type of modification - """ getconstraintconstant(m::AbstractModel, c::ConstraintReference, k::Int) @@ -65,7 +64,7 @@ function getconstraintconstant end """ getconstraintaffine(m::AbstractModel, c::ConstraintReference) -Return the ``A_i`` matrix of the constraint corresponding to ``c`` in triplet form ``(i, v, coef)`, where ``v`` is a ``VariableReference``, and ``coef`` is a coefficient value. +Return the ``A_i`` matrix of the constraint corresponding to ``c`` in triplet form ``(i, v, coef)``, where ``v`` is a ``VariableReference``, and ``coef`` is a coefficient value. Output is a tuple of three vectors. getconstraintaffine(m::AbstractModel, c::ConstraintReference, k::Int) @@ -92,28 +91,12 @@ Return the element ``(v_1, v_2)`` of the ``Q_{i,k}`` matrix of the ``k``th row o """ function getconstraintquadratic end -""" - modifyconstraint!(m::AbstractModel, c::ConstraintReference{Set}, S::Set) - -Change the set of constraint ``c`` to the new set ``S`` which should be of the same type as the original set. - -### Examples - -If ``c`` is a ``ConstraintReference{Interval}`` - -```julia -modifyconstraint!(m, c, Interval(0, 5)) -modifyconstraint!(m, c, NonPositive) # errors -``` -""" -function modifyconstraint! end - """ modifyconstraint!(m::AbstractModel, c::ConstraintReference, k::Int, args...) Modify elements of the ``k``th row of the constraint ``c`` depending on the arguments ``args``. -The ``k``th row will have the form ``q_{i,k}(x) + A_{i,k}^T x + b_{i,k}`` -There are three cases. +The ``k``th row will have the form ``q_{i,k}(x) + A_{i,k}^T x + b_{i,k}``. +There are four cases. ## Modify Constant term @@ -158,3 +141,20 @@ If entries for both ``(i,j)`` and ``(j,i)`` are provided, these are considered d modifyconstraint!(m, c, v_1, v_2, 1.0) modifyconstraint!(m, c, [v_1, v_2], [v_1, v_1], [1.0, 2.0]) ``` + +## Modify Set + + modifyconstraint!(m::AbstractModel, c::ConstraintReference{Set}, S::Set) + +Change the set of constraint ``c`` to the new set ``S`` which should be of the same type as the original set. + +### Examples + +If ``c`` is a ``ConstraintReference{Interval}`` + +```julia +modifyconstraint!(m, c, Interval(0, 5)) +modifyconstraint!(m, c, NonPositives) # errors +``` +""" +function modifyconstraint! end From b8c56a885e3011a62995fa0caa80f5d254389c55 Mon Sep 17 00:00:00 2001 From: Chris Coey Date: Fri, 30 Jun 2017 02:07:16 -0400 Subject: [PATCH 5/7] fix bugs in manual --- docs/src/apimanual.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/src/apimanual.md b/docs/src/apimanual.md index 833f905a6a..eeca85d6f0 100644 --- a/docs/src/apimanual.md +++ b/docs/src/apimanual.md @@ -22,7 +22,7 @@ Currently, all functions are described compactly with lists, vectors, and matric The function types are: * variable-wise: ``x_j``, a (scalar) variable * affine: ``A_i x + b_i``, where ``A_i`` is a matrix and ``b_i`` is a vector -* quadratic: ``q_i(x) + A_i x + b_i``, where ``q_i(x)`` is a scalar quadratic expression of the form``\frac{1}{2} x^T Q_{i,k} x`` (for objective or constraints), or a vector of such quadratic expressions (for constraints only) +* quadratic: ``q_i(x) + A_i x + b_i``, where ``q_i(x)`` is a scalar quadratic expression of the form ``\frac{1}{2} x^T Q_i x`` (for objective or constraints) with symmetric matrix ``Q_i``, or a vector of such quadratic expressions (for constraints only) with symmetric matrices ``Q_{i,1}, \ldots, Q_{i,K_i}`` This API defines some commonly-used sets, but is extensible to other sets recognized by the solver. @@ -36,7 +36,7 @@ For such conic form minimization problems, the primal is: \begin{align} & \min_{x \in \mathbb{R}^n} & a_0^T x + b_0 \\ -& \;\;\text{s.t.} & A_i x + b_i & \in \mathcal{S}_i & i = 1 \ldots m +& \;\;\text{s.t.} & A_i x + b_i & \in \mathcal{C}_i & i = 1 \ldots m \end{align} ``` @@ -46,9 +46,9 @@ and the dual is: \begin{align} & \max_{y_1, \ldots, y_m} & -\sum_{i=1}^m b_i^T y_i + b_0 \\ -& \;\;\text{s.t.} & a_0 - \sum_{i=1}^m A_i^T y_i \in {0}^n +& \;\;\text{s.t.} & a_0 - \sum_{i=1}^m A_i^T y_i & \in {0}^n \\ -& & y_i & \in \mathcal{S}_i^* & i = 1 \ldots m +& & y_i & \in \mathcal{C}_i^* & i = 1 \ldots m \end{align} ``` From d28ca079ae31310f6d53f31eaa357608108fdb22 Mon Sep 17 00:00:00 2001 From: Chris Coey Date: Fri, 30 Jun 2017 03:04:28 -0400 Subject: [PATCH 6/7] fix backticks --- docs/src/apimanual.md | 3 +- docs/src/apireference.md | 10 +-- src/MathOptInterface.jl | 2 +- src/attributes.jl | 148 +++++++++++++++++++-------------------- src/constraints.jl | 82 +++++++++++----------- src/objectives.jl | 40 +++++------ src/references.jl | 18 ++--- src/sets.jl | 28 ++++---- src/variables.jl | 6 +- 9 files changed, 168 insertions(+), 169 deletions(-) diff --git a/docs/src/apimanual.md b/docs/src/apimanual.md index eeca85d6f0..83146ee25b 100644 --- a/docs/src/apimanual.md +++ b/docs/src/apimanual.md @@ -18,14 +18,13 @@ where: * constraint functions ``f_i`` is variable-wise, affine, or quadratic * constraint sets ``\mathcal{S}_i`` are pre-defined real scalar or vector sets +This API defines some commonly-used sets, but is extensible to other sets recognized by the solver. Currently, all functions are described compactly with lists, vectors, and matrices. The function types are: * variable-wise: ``x_j``, a (scalar) variable * affine: ``A_i x + b_i``, where ``A_i`` is a matrix and ``b_i`` is a vector * quadratic: ``q_i(x) + A_i x + b_i``, where ``q_i(x)`` is a scalar quadratic expression of the form ``\frac{1}{2} x^T Q_i x`` (for objective or constraints) with symmetric matrix ``Q_i``, or a vector of such quadratic expressions (for constraints only) with symmetric matrices ``Q_{i,1}, \ldots, Q_{i,K_i}`` -This API defines some commonly-used sets, but is extensible to other sets recognized by the solver. - ## Duals Currently, a convention for duals is not defined for problems with non-conic sets ``\mathcal{S}_i`` or quadratic functions ``f_0, f_i``. Note that bound constraints are supported by re-interpretation in terms of the nonnegative or nonpositive cones. An affine constraint ``a^T x + b \ge c`` should be interpreted as ``a^T x + b - c \in \mathbb{R}_+``, and similarly ``a^T x + b \le c`` should be interpreted as ``a^T x + b - c \in \mathbb{R}_-``. Variable-wise constraints should be interpreted as affine constraints with the appropriate identity mapping in place of ``A_i``. diff --git a/docs/src/apireference.md b/docs/src/apireference.md index caa4a24537..74d28a06cb 100644 --- a/docs/src/apireference.md +++ b/docs/src/apireference.md @@ -74,8 +74,8 @@ DualStatus ### Termination Status -The ``TerminationStatus`` attribute indicates why the solver stopped executing. -The value of the attribute is of type ``TerminationStatusCode``. +The `TerminationStatus` attribute indicates why the solver stopped executing. +The value of the attribute is of type `TerminationStatusCode`. ```@docs TerminationStatusCode @@ -83,8 +83,8 @@ TerminationStatusCode ### Result Status -The ``PrimalStatus`` and ``DualStatus`` attributes indicate how to interpret the result returned by the solver. -The value of the attribute is of type ``ResultStatusCode``. +The `PrimalStatus` and `DualStatus` attributes indicate how to interpret the result returned by the solver. +The value of the attribute is of type `ResultStatusCode`. ```@docs ResultStatusCode @@ -183,7 +183,7 @@ getconstraintquadratic ``` List of attributes associated with constraints. [category AbstractConstraintAttribute] -Calls to ``getattribute`` and ``setattribute!`` should include as an argument a single ``ConstraintReference`` or a vector of ``ConstraintReference{T}`` objects. +Calls to `getattribute` and `setattribute!` should include as an argument a single `ConstraintReference` or a vector of `ConstraintReference{T}` objects. [why is ConstraintBasisStatus under constraint attributes but below we have a basis status attribute separately??] ```@docs diff --git a/src/MathOptInterface.jl b/src/MathOptInterface.jl index 73a66f7998..27b02f5c18 100644 --- a/src/MathOptInterface.jl +++ b/src/MathOptInterface.jl @@ -19,7 +19,7 @@ abstract type AbstractModel end """ Model(solver::AbstractSolver) -Create an instance of ``AbstractModel`` using the given solver. +Create an instance of `AbstractModel` using the given solver. """ function Model end diff --git a/src/attributes.jl b/src/attributes.jl index 0ce3ddb5ff..e2c92de1e9 100644 --- a/src/attributes.jl +++ b/src/attributes.jl @@ -26,29 +26,29 @@ const AnyAttribute = Union{AbstractSolverOrModelAttribute, AbstractVariableAttri """ getattribute(s::AbstractSolver, attr::AbstractSolverOrModelAttribute) -Return an attribute ``attr`` of the solver ``s``. +Return an attribute `attr` of the solver `s`. getattribute(m::AbstractModel, attr::AbstractSolverOrModelAttribute) -Return an attribute ``attr`` of the model ``m``. +Return an attribute `attr` of the model `m`. getattribute(m::AbstractModel, attr::AbstractVariableAttribute, v::VariableReference) -Return an attribute ``attr`` of the variable ``v`` in model ``m``. +Return an attribute `attr` of the variable `v` in model `m`. getattribute(m::AbstractModel, attr::AbstractVariableAttribute, v::Vector{VariableReference}) -Return a vector of attributes corresponding to each variable in the collection ``v`` in the model ``m``. +Return a vector of attributes corresponding to each variable in the collection `v` in the model `m`. getattribute(m::AbstractModel, attr::AbstractConstraintAttribute, c::ConstraintReference) -Return an attribute ``attr`` of the constraint ``c`` in model ``m``. +Return an attribute `attr` of the constraint `c` in model `m`. getattribute(m::AbstractModel, attr::AbstractConstraintAttribute, c::Vector{VariablewiseConstraintReference{T}}) getattribute(m::AbstractModel, attr::AbstractConstraintAttribute, c::Vector{AffineConstraintReference{T}}) getattribute(m::AbstractModel, attr::AbstractConstraintAttribute, c::Vector{QuadraticConstraintReference{T}}) -Return a vector of attributes corresponding to each constraint in the collection ``c`` in the model ``m``. +Return a vector of attributes corresponding to each constraint in the collection `c` in the model `m`. ### Examples @@ -68,8 +68,8 @@ end """ getattribute!(output, m::AbstractModel, args...) -An in-place version of ``getattribute``. -The signature matches that of ``getattribute`` except that the the result is placed in the vector ``output``. +An in-place version of `getattribute`. +The signature matches that of `getattribute` except that the the result is placed in the vector `output`. """ function getattribute! end function getattribute!(output, m, attr::AnyAttribute, args...) @@ -79,14 +79,14 @@ end """ cangetattribute(s::AbstractSolver, attr::AbstractSolverOrModelAttribute)::Bool -Return a ``Bool`` indicating whether it is possible to query attribute ``attr`` from the solver ``s``. +Return a `Bool` indicating whether it is possible to query attribute `attr` from the solver `s`. cangetattribute(m::AbstractModel, attr::AbstractVariableAttribute, R::Type{VariableReference})::Bool cangetattribute(m::AbstractModel, attr::AbstractConstraintAttribute, R::Type{VariablewiseConstraintReference{T})::Bool cangetattribute(m::AbstractModel, attr::AbstractConstraintAttribute, R::Type{AffineConstraintReference{T})::Bool cangetattribute(m::AbstractModel, attr::AbstractConstraintAttribute, R::Type{QuadraticConstraintReference{T})::Bool -Return a ``Bool`` indicating whether the model ``m`` currently has a value for the attributed specified by attribute type ``attr`` applied to the reference type ``R``. +Return a `Bool` indicating whether the model `m` currently has a value for the attributed specified by attribute type `attr` applied to the reference type `R`. ### Examples @@ -103,14 +103,14 @@ cangetattribute(m::AbstractModel, attr::AnyAttribute) = false """ cansetattribute(s::AbstractSolver, attr::AbstractSolverOrModelAttribute)::Bool -Return a ``Bool`` indicating whether it is possible to set attribute ``attr`` in the solver ``s``. +Return a `Bool` indicating whether it is possible to set attribute `attr` in the solver `s`. cansetattribute(m::AbstractModel, attr::AbstractVariableAttribute, R::Type{VariableReference})::Bool cansetattribute(m::AbstractModel, attr::AbstractConstraintAttribute, R::Type{VariablewiseConstraintReference{T})::Bool cangetattribute(m::AbstractModel, attr::AbstractConstraintAttribute, R::Type{AffineConstraintReference{T})::Bool cangetattribute(m::AbstractModel, attr::AbstractConstraintAttribute, R::Type{QuadraticConstraintReference{T})::Bool -Return a ``Bool`` indicating whether it is possible to set attribute ``attr`` applied to the reference type ``R`` in the model ``m``. +Return a `Bool` indicating whether it is possible to set attribute `attr` applied to the reference type `R` in the model `m`. ### Examples @@ -127,29 +127,29 @@ cansetattribute(m::AbstractModel, attr::AnyAttribute) = false """ setattribute!(s::AbstractSolver, attr::AbstractSolverOrModelAttribute, value) -Assign ``value`` to the attribute ``attr`` of the solver ``s``. +Assign `value` to the attribute `attr` of the solver `s`. setattribute!(m::AbstractModel, attr::AbstractSolverOrModelAttribute, value) -Assign ``value`` to the attribute ``attr`` of the model ``m``. +Assign `value` to the attribute `attr` of the model `m`. setattribute!(m::AbstractModel, attr::AbstractVariableAttribute, v::VariableReference, value) -Assign ``value`` to the attribute ``attr`` of variable ``v`` in model ``m``. +Assign `value` to the attribute `attr` of variable `v` in model `m`. setattribute!(m::AbstractModel, attr::AbstractVariableAttribute, v::Vector{VariableReference}, vector_of_values) -Assign a value respectively to the attribute ``attr`` of each variable in the collection ``v`` in model ``m``. +Assign a value respectively to the attribute `attr` of each variable in the collection `v` in model `m`. setattribute!(m::AbstractModel, attr::AbstractConstraintAttribute, c::ConstraintReference, value) -Assign a value to the attribute ``attr`` of constraint ``c`` in model ``m``. +Assign a value to the attribute `attr` of constraint `c` in model `m`. setattribute!(m::AbstractModel, attr::AbstractConstraintAttribute, c::Vector{VariablewiseConstraintReference{T}}) setattribute!(m::AbstractModel, attr::AbstractConstraintAttribute, c::Vector{AffineConstraintReference{T}}) setattribute!(m::AbstractModel, attr::AbstractConstraintAttribute, c::Vector{QuadraticConstraintReference{T}}) -Assign a value respectively to the attribute ``attr`` of each constraint in the collection ``c`` in model ``m``. +Assign a value respectively to the attribute `attr` of each constraint in the collection `c` in model `m`. """ function setattribute! end function setattribute!(m, attr::AnyAttribute, args...) @@ -161,7 +161,7 @@ end """ ReturnsDuals() -A ``Bool`` indicating if the solver should be expected to return dual solutions when appropriate. +A `Bool` indicating if the solver should be expected to return dual solutions when appropriate. A solver attribute. """ struct ReturnsDuals <: AbstractSolverOrModelAttribute end @@ -169,8 +169,8 @@ struct ReturnsDuals <: AbstractSolverOrModelAttribute end """ SupportsAddConstraintAfterSolver() -A ``Bool`` indicating if the solver supports adding constraints after a solve. -If ``false``, then a new model should be constructed instead. +A `Bool` indicating if the solver supports adding constraints after a solve. +If `false`, then a new model should be constructed instead. A solver attribute. """ struct SupportsAddConstraintAfterSolve <: AbstractSolverOrModelAttribute end @@ -178,7 +178,7 @@ struct SupportsAddConstraintAfterSolve <: AbstractSolverOrModelAttribute end """ SupportsDeleteConstraint() -A ``Bool`` indicating if the solver supports deleting constraints from a model. +A `Bool` indicating if the solver supports deleting constraints from a model. A solver attribute. """ struct SupportsDeleteConstraint <: AbstractSolverOrModelAttribute end @@ -186,7 +186,7 @@ struct SupportsDeleteConstraint <: AbstractSolverOrModelAttribute end """ SupportsAddVariableAfterSolve() -A ``Bool`` indicating if the solver supports adding variables after a solve. +A `Bool` indicating if the solver supports adding variables after a solve. In the context of linear programming, this is known as column generation. A solver attribute. """ @@ -199,7 +199,7 @@ struct SupportsAddVariableAfterSolver <: AbstractSolverOrModelAttribute end """ SupportsQuadraticObjective() -A ``Bool`` indicating if the solver supports quadratic objectives. +A `Bool` indicating if the solver supports quadratic objectives. A solver attribute. """ struct SupportsQuadraticObjective <: AbstractSolverOrModelAttribute end @@ -207,7 +207,7 @@ struct SupportsQuadraticObjective <: AbstractSolverOrModelAttribute end """ SupportsConicThroughQuadratic() -A ``Bool`` indicating if the solver interprets certain quadratic constraints as second-order cone constraints. +A `Bool` indicating if the solver interprets certain quadratic constraints as second-order cone constraints. A solver attribute. """ struct SupportsConicThroughQuadratic <: AbstractSolverOrModelAttribute end @@ -215,10 +215,10 @@ struct SupportsConicThroughQuadratic <: AbstractSolverOrModelAttribute end """ ObjectiveValue(resultidx::Int=1, objectiveindex::Int=1) -The objective value of the ``resultindex``th primal result of the ``objectiveindex``th objective. +The objective value of the `resultindex`th primal result of the `objectiveindex`th objective. A model attribute. -Both ``resultindex`` and ``objectiveindex`` default to 1. +Both `resultindex` and `objectiveindex` default to 1. """ struct ObjectiveValue <: AbstractSolverOrModelAttribute resultindex::Int @@ -237,7 +237,7 @@ struct ObjectiveBound <: AbstractSolverOrModelAttribute end """ RelativeGap() -The final relative optimality gap, defined as ``\frac{|b-f|}{|f|}``, where ``b`` is the best bound and ``f`` is the best feasible objective value. +The final relative optimality gap, defined as ``\\frac{|b-f|}{|f|}``, where ``b`` is the best bound and ``f`` is the best feasible objective value. A model attribute. """ struct RelativeGap <: AbstractSolverOrModelAttribute end @@ -253,7 +253,7 @@ struct SolveTime <: AbstractSolverOrModelAttribute end """ Sense() -The optimization sense of the model, an ``OptimizationSense`` with value ``MinSense`` or ``MaxSense``. +The optimization sense of the model, an `OptimizationSense` with value `MinSense` or `MaxSense`. A model attribute. """ struct Sense <: AbstractSolverOrModelAttribute end @@ -312,7 +312,7 @@ struct NumberOfVariables <: AbstractSolverOrModelAttribute end """ NumberOfVariablewiseConstraints{T}() -The number of variablewise constraints of type ``T`` in the model. +The number of variablewise constraints of type `T` in the model. A model attribute. """ struct NumberOfVariablewiseConstraints{T} <: AbstractSolverOrModelAttribute end @@ -320,7 +320,7 @@ struct NumberOfVariablewiseConstraints{T} <: AbstractSolverOrModelAttribute end """ NumberOfAffineConstraints{T}() -The number of affine constraints of type ``T`` in the model. +The number of affine constraints of type `T` in the model. A model attribute. """ struct NumberOfAffineConstraints{T} <: AbstractSolverOrModelAttribute end @@ -328,7 +328,7 @@ struct NumberOfAffineConstraints{T} <: AbstractSolverOrModelAttribute end """ NumberOfQuadraticConstraints{T}() -The number of quadratic constraints of type ``T`` in the model. +The number of quadratic constraints of type `T` in the model. A model attribute. """ struct NumberOfQuadraticConstraints{T} <: AbstractSolverOrModelAttribute end @@ -336,7 +336,7 @@ struct NumberOfQuadraticConstraints{T} <: AbstractSolverOrModelAttribute end """ SupportsVariablewiseConstraint{T}() -A ``Bool`` indicating whether the solver or model supports a variable-wise constraint in the set ``s`` of type ``T``. +A `Bool` indicating whether the solver or model supports a variable-wise constraint in the set `s` of type `T`. A solver and model attribute. """ struct SupportsVariablewiseConstraint{T} <: AbstractSolverOrModelAttribute end @@ -344,7 +344,7 @@ struct SupportsVariablewiseConstraint{T} <: AbstractSolverOrModelAttribute end """ SupportsAffineConstraint{T}() -A ``Bool`` indicating whether the solver or model supports an affine constraint in the set ``s`` of type ``T``. +A `Bool` indicating whether the solver or model supports an affine constraint in the set `s` of type `T`. A solver and model attribute. """ struct SupportsAffineConstraint{T} <: AbstractSolverOrModelAttribute end @@ -352,7 +352,7 @@ struct SupportsAffineConstraint{T} <: AbstractSolverOrModelAttribute end """ SupportsQuadraticConstraint{T}() -A ``Bool`` indicating whether the solver or model supports a quadratic constraint in the set ``s`` of type ``T``. +A `Bool` indicating whether the solver or model supports a quadratic constraint in the set `s` of type `T`. A solver and model attribute. """ struct SupportsQuadraticConstraint{T} <: AbstractSolverOrModelAttribute end @@ -370,8 +370,8 @@ struct VariablePrimalStart <: AbstractVariableAttribute end VariablePrimal(N) VariablePrimal() -The assignment to the primal variables in result ``N``. -If ``N`` is omitted, it is 1 by default. +The assignment to the primal variables in result `N`. +If `N` is omitted, it is 1 by default. """ struct VariablePrimal <: AbstractVariableAttribute N::Int @@ -381,21 +381,21 @@ VariablePrimal() = VariablePrimal(1) """ VariableBasisStatus() -Returns the ``BasisStatusCode`` of a given variable, with respect to an available optimal solution basis. +Returns the `BasisStatusCode` of a given variable, with respect to an available optimal solution basis. """ struct VariableBasisStatus <: AbstractVariableAttribute end """ BasisStatusCode -An Enum of possible values for the ``VariableBasisStatus`` and ``ConstraintBasisStatus`` attribute. +An Enum of possible values for the `VariableBasisStatus` and `ConstraintBasisStatus` attribute. This explains the status of a given element with respect to an optimal solution basis. Possible values are: -* ``Basic``: element is in the basis -* ``Nonbasic``: element is not in the basis -* ``NonbasicAtLower``: element is not in the basis and is at its lower bound -* ``NonbasicAtUpper``: element is not in the basis and is at its upper bound -* ``SuperBasic``: element is not in the basis but is also not at one of its bounds +* `Basic`: element is in the basis +* `Nonbasic`: element is not in the basis +* `NonbasicAtLower`: element is not in the basis and is at its lower bound +* `NonbasicAtUpper`: element is not in the basis and is at its upper bound +* `SuperBasic`: element is not in the basis but is also not at one of its bounds """ @enum BasisStatusCode Basic Nonbasic NonbasicAtLower NonbasicAtUpper SuperBasic @@ -419,8 +419,8 @@ struct ConstraintDualStart <: AbstractConstraintAttribute end ConstraintPrimal(N) ConstraintPrimal() -The assignment to the constraint primal values in result ``N``. -If ``N`` is omitted, it is 1 by default. +The assignment to the constraint primal values in result `N`. +If `N` is omitted, it is 1 by default. """ struct ConstraintPrimal <: AbstractConstraintAttribute N::Int @@ -431,8 +431,8 @@ ConstraintPrimal() = ConstraintPrimal(1) ConstraintDual(N) ConstraintDual() -The assignment to the constraint dual values in result ``N``. -If ``N`` is omitted, it is 1 by default. +The assignment to the constraint dual values in result `N`. +If `N` is omitted, it is 1 by default. """ struct ConstraintDual <: AbstractConstraintAttribute N::Int @@ -442,7 +442,7 @@ ConstraintDual() = ConstraintDual(1) """ ConstraintBasisStatus() -Returns the ``BasisStatusCode`` of a given constraint, with respect to an available optimal solution basis. +Returns the `BasisStatusCode` of a given constraint, with respect to an available optimal solution basis. """ struct ConstraintBasisStatus <: AbstractConstraintAttribute end @@ -450,7 +450,7 @@ struct ConstraintBasisStatus <: AbstractConstraintAttribute end """ TerminationStatus() -A ``TerminationStatusCode`` explaining why the solver stopped. +A `TerminationStatusCode` explaining why the solver stopped. A model attribute. """ struct TerminationStatus <: AbstractSolverOrModelAttribute end @@ -458,32 +458,32 @@ struct TerminationStatus <: AbstractSolverOrModelAttribute end """ TerminationStatusCode -An Enum of possible values for the ``TerminationStatus`` attribute. +An Enum of possible values for the `TerminationStatus` attribute. This attribute is meant to explain the reason why the solver stopped executing. ## OK These are generally OK statuses. -* ``Success``: the algorithm ran successfully and has a result; this includes cases where the algorithm converges to an infeasible point (NLP) or converges to a solution of a homogeneous self-dual problem and has a certificate of primal/dual infeasibility -* ``AlmostSuccess``: the algorithm *almost* ran successfully (e.g., to relaxed convergence tolerances) and has a result -* ``InfeasibleNoResult``: the algorithm stopped because it decided that the problem is infeasible but does not have a result to return -* ``UnboundedNoResult``: the algorithm stopped because it decided that the problem is unbounded but does not have a result to return -* ``InfeasibleOrUnbounded``: the algorithm stopped because it decided that the problem is infeasible or unbounded (no result is available); this occasionally happens during MIP presolve +* `Success`: the algorithm ran successfully and has a result; this includes cases where the algorithm converges to an infeasible point (NLP) or converges to a solution of a homogeneous self-dual problem and has a certificate of primal/dual infeasibility +* `AlmostSuccess`: the algorithm *almost* ran successfully (e.g., to relaxed convergence tolerances) and has a result +* `InfeasibleNoResult`: the algorithm stopped because it decided that the problem is infeasible but does not have a result to return +* `UnboundedNoResult`: the algorithm stopped because it decided that the problem is unbounded but does not have a result to return +* `InfeasibleOrUnbounded`: the algorithm stopped because it decided that the problem is infeasible or unbounded (no result is available); this occasionally happens during MIP presolve ## Limits The solver stopped because of some user-defined limit. -To be documented: ``IterationLimit``, ``TimeLimit``, ``NodeLimit``, ``SolutionLimit``, ``MemoryLimit``, ``ObjectiveLimit``, ``NormLimit``, ``OtherLimit``. +To be documented: `IterationLimit`, `TimeLimit`, `NodeLimit`, `SolutionLimit`, `MemoryLimit`, `ObjectiveLimit`, `NormLimit`, `OtherLimit`. ## Problematic This group of statuses means that something unexpected or problematic happened. -* ``SlowProgress``: the algorithm stopped because it was unable to continue making progress towards the solution -* ``AlmostSuccess`` should be used if there is additional information that relaxed convergence tolerances are satisfied +* `SlowProgress`: the algorithm stopped because it was unable to continue making progress towards the solution +* `AlmostSuccess` should be used if there is additional information that relaxed convergence tolerances are satisfied -To be documented: ``NumericalError``, ``InvalidModel``, ``InvalidOption``, ``Interrupted``, ``OtherError``. +To be documented: `NumericalError`, `InvalidModel`, `InvalidOption`, `Interrupted`, `OtherError`. """ @enum TerminationStatusCode Success AlmostSuccess InfeasibleNoResult UnboundedNoResult InfeasibleOrUnbounded IterationLimit TimeLimit NodeLimit SolutionLimit MemoryLimit ObjectiveLimit NormLimit OtherLimit SlowProgress NumericalError InvalidModel InvalidOption Interrupted OtherError @@ -493,18 +493,18 @@ To be documented: ``NumericalError``, ``InvalidModel``, ``InvalidOption``, ``Int """ ResultStatusCode -An Enum of possible values for the ``PrimalStatus`` and ``DualStatus`` attributes. +An Enum of possible values for the `PrimalStatus` and `DualStatus` attributes. The values indicate how to interpret the result vector. -* ``FeasiblePoint`` -* ``NearlyFeasiblePoint`` -* ``InfeasiblePoint`` -* ``InfeasibilityCertificate`` -* ``NearlyInfeasibilityCertificate`` -* ``ReductionCertificate`` -* ``NearlyReductionCertificate`` -* ``Unknown`` -* ``Other`` +* `FeasiblePoint` +* `NearlyFeasiblePoint` +* `InfeasiblePoint` +* `InfeasibilityCertificate` +* `NearlyInfeasibilityCertificate` +* `ReductionCertificate` +* `NearlyReductionCertificate` +* `Unknown` +* `Other` """ @enum ResultStatusCode FeasiblePoint NearlyFeasiblePoint InfeasiblePoint InfeasibilityCertificate NearlyInfeasibilityCertificate ReductionCertificate NearlyReductionCertificate Unknown Other @@ -512,8 +512,8 @@ The values indicate how to interpret the result vector. PrimalStatus(N) PrimalStatus() -The ``ResultStatusCode`` of the primal result ``N``. -If ``N`` is omitted, it defaults to 1. +The `ResultStatusCode` of the primal result `N`. +If `N` is omitted, it defaults to 1. A model attribute. """ struct PrimalStatus <: AbstractSolverOrModelAttribute @@ -525,8 +525,8 @@ PrimalStatus() = PrimalStatus(1) DualStatus(N) DualStatus() -The ``ResultStatusCode`` of the dual result ``N``. -If ``N`` is omitted, it defaults to 1. +The `ResultStatusCode` of the dual result `N`. +If `N` is omitted, it defaults to 1. A model attribute. """ struct DualStatus <: AbstractSolverOrModelAttribute diff --git a/src/constraints.jl b/src/constraints.jl index 74cc017721..1f0fb59348 100644 --- a/src/constraints.jl +++ b/src/constraints.jl @@ -3,52 +3,52 @@ """ addconstraint!(m::AbstractModel, b, a_constridx, a_v::Vector{VariableReference}, a_coef, Q_constridx, Q_vari::Vector{VariableReference}, Q_varj::Vector{VariableReference}, Q_coef, S::AbstractSet)::QuadraticConstraintReference{typeof(S)} -Add the vector quadratic-in-set constraint ``q_i(x) + A_i^T x + b_i \in \mathcal{S}_i``, where: -* ``A_i`` is a sparse matrix specified in triplet form by ``a_constridx, a_v, a_coef`` -* ``b_i`` is a vector specified by ``b`` -* ``q_i(x)`` is a vector with component ``(q_i(x))_k`` defined as ``\frac{1}{2} x^T Q_{i,k} x``, where each symmetric matrix ``Q_{i,k}`` has ``Q_constridx = k`` and is specified in triplet form by ``Q_vari, Q_varj, Q_coef`` -* ``\mathcal{S}_i`` is a pre-defined set specified as ``S`` +Add the vector quadratic-in-set constraint ``q_i(x) + A_i^T x + b_i \\in \\mathcal{S}_i``, where: +* ``A_i`` is a sparse matrix specified in triplet form by `a_constridx, a_v, a_coef` +* ``b_i`` is a vector specified by `b` +* ``q_i(x)`` is a vector with component ``(q_i(x))_k`` defined as ``\\frac{1}{2} x^T Q_{i,k} x``, where each symmetric matrix ``Q_{i,k}`` has `Q_constridx` equal to `k` and is specified in triplet form by `Q_vari, Q_varj, Q_coef` +* ``\\mathcal{S}_i`` is a pre-defined set specified as `S` Duplicate indices in either the ``A_i`` matrix or any ``Q_{i,k}`` matrix are accepted and will be summed together. Off-diagonal entries of ``Q_{i,k}`` will be mirrored, so either the upper triangular or lower triangular entries of ``Q_{i,k}`` should be provided. If entries for both ``(i,j)`` and ``(j,i)`` are provided, these are considered duplicate terms. -``a_v``, ``Q_vari``, ``Q_varj`` should be collections of ``VariableReference`` objects. +`a_v`, `Q_vari`, `Q_varj` should be collections of ``VariableReference`` objects. addconstraint!(m::AbstractModel, b, a_v::Vector{VariableReference}, a_coef, Q_vari::Vector{VariableReference}, Q_varj::Vector{VariableReference}, Q_coef, S::AbstractSet)::QuadraticConstraintReference{typeof(S)} -Add the scalar quadratic-in-set constraint ``q_i(x) + a_i^T x + b_i \in \mathcal{S}_i``, where: -* ``a_i`` is a sparse vector specified in tuple form by ``a_v, a_coef`` -* ``b_i`` is a scalar specified by ``b`` -* ``q_i(x)`` is defined as ``\frac{1}{2} x^T Q_{i} x``, where the symmetric matrix ``Q_{i}`` is specified in triplet form by ``Q_vari, Q_varj, Q_coef`` -* ``\mathcal{S}_i`` is a pre-defined *scalar* set specified as ``S`` +Add the scalar quadratic-in-set constraint ``q_i(x) + a_i^T x + b_i \\in \\mathcal{S}_i``, where: +* ``a_i`` is a sparse vector specified in tuple form by `a_v, a_coef` +* ``b_i`` is a scalar specified by `b` +* ``q_i(x)`` is defined as ``\\frac{1}{2} x^T Q_{i} x``, where the symmetric matrix ``Q_{i}`` is specified in triplet form by `Q_vari, Q_varj, Q_coef` +* ``\\mathcal{S}_i`` is a pre-defined *scalar* set specified as `S` addconstraint!(m::AbstractModel, b, a_constridx, a_v::Vector{VariableReference}, a_coef, S::AbstractSet)::AffineConstraintReference{typeof(S)} -Add the vector affine-in-set constraint ``A_i^T x + b_i \in \mathcal{S}_i``, where: -* ``A_i`` is a sparse matrix specified in triplet form by ``a_constridx, a_v, a_coef`` -* ``b_i`` is a vector specified by ``b`` -* ``\mathcal{S}_i`` is a pre-defined set specified as ``S`` +Add the vector affine-in-set constraint ``A_i^T x + b_i \\in \\mathcal{S}_i``, where: +* ``A_i`` is a sparse matrix specified in triplet form by `a_constridx, a_v, a_coef` +* ``b_i`` is a vector specified by `b` +* ``\\mathcal{S}_i`` is a pre-defined set specified as `S` Duplicate indices in ``A_i`` are accepted and will be summed together. addconstraint!(m::AbstractModel, b, a_v::Vector{VariableReference}, a_coef, S::AbstractSet)::AffineConstraintReference{typeof(S)} -Add the scalar affine-in-set constraint ``a_i^T x + b_i \in \mathcal{S}_i``, where: -* ``a_i`` is a sparse vector specified in tuple form by ``a_v, a_coef`` -* ``b_i`` is a scalar specified by ``b`` -* ``\mathcal{S}_i`` is a pre-defined *scalar* set specified as ``S`` +Add the scalar affine-in-set constraint ``a_i^T x + b_i \\in \\mathcal{S}_i``, where: +* ``a_i`` is a sparse vector specified in tuple form by `a_v, a_coef` +* ``b_i`` is a scalar specified by `b` +* ``\\mathcal{S}_i`` is a pre-defined *scalar* set specified as `S` addconstraint!(m::AbstractModel, vs::Vector{VariableReference}, S::AbstractSet)::VariablewiseConstraintReference{typeof(S)} -Add the vector variable-wise constraint ``(x_j)_{j \in v_i} \in \mathcal{S}_i``, where: -* ``v_i`` is a list of variable indices specified as a vector of variable references ``vs`` -* ``\mathcal{S}_i`` is a pre-defined set specified as ``S`` +Add the vector variable-wise constraint ``(x_j)_{j \\in v_i} \\in \\mathcal{S}_i``, where: +* ``v_i`` is a list of variable indices specified as a vector of variable references `vs` +* ``\\mathcal{S}_i`` is a pre-defined set specified as `S` addconstraint!(m::AbstractModel, v::VariableReference, S::AbstractSet)::VariablewiseConstraintReference{typeof(S)} -Add the scalar variable-wise constraint ``x_j \in \mathcal{S}_i``, where: -* ``x_j`` is variable specified as a variable reference ``v`` -* ``\mathcal{S}_i`` is a pre-defined *scalar* set specified as ``S`` +Add the scalar variable-wise constraint ``x_j \\in \\mathcal{S}_i``, where: +* ``x_j`` is variable specified as a variable reference `v` +* ``\\mathcal{S}_i`` is a pre-defined *scalar* set specified as `S` """ function addconstraint! end @@ -57,52 +57,52 @@ function addconstraint! end """ getconstraintconstant(m::AbstractModel, c::ConstraintReference, k::Int) -Return the constant term of the ``k``th row of the constraint ``c``. +Return the constant term of the `k`th row of the constraint `c`. """ function getconstraintconstant end """ getconstraintaffine(m::AbstractModel, c::ConstraintReference) -Return the ``A_i`` matrix of the constraint corresponding to ``c`` in triplet form ``(i, v, coef)``, where ``v`` is a ``VariableReference``, and ``coef`` is a coefficient value. +Return the ``A_i`` matrix of the constraint corresponding to `c` in triplet form `(i, v, coef)`, where `v` is a `VariableReference`, and `coef` is a coefficient value. Output is a tuple of three vectors. getconstraintaffine(m::AbstractModel, c::ConstraintReference, k::Int) -Return the ``k``th row of the ``A_k`` matrix of the constraint corresponding to ``c`` in tuple form ``(v, coef)``, where ``v`` is a ``VariableReference``, and ``coef`` is a coefficient value. +Return the `k`th row of the ``A_k`` matrix of the constraint corresponding to `c` in tuple form `(v, coef)`, where `v` is a `VariableReference`, and `coef` is a coefficient value. Output is a tuple of two vectors. getconstraintaffine(m::AbstractModel, c::ConstraintReference, k::Int, v::VariableReference) -Return the element of the ``A_k`` matrix of the constraint corresponding to ``c`` in row ``k`` and variable ``v``. +Return the element of the ``A_k`` matrix of the constraint corresponding to `c` in row `k` and variable `v`. """ function getconstraintaffine end """ getconstraintquadratic(m::AbstractModel, c::ConstraintReference, k::Int) -Return the ``Q_{i,k}`` matrix of the ``k``th row of the constraint corresponding to ``c`` in triplet form ``(v_1, v_2, coef)``, where ``v_1, v_2`` are ``VariableReference``s, and ``coef`` is a coefficient value. +Return the ``Q_{i,k}`` matrix of the `k`th row of the constraint corresponding to `c` in triplet form `(v_1, v_2, coef)`, where `v_1, v_2` are `VariableReference`s, and `coef` is a coefficient value. Output is a tuple of three vectors. The ``Q_{i,k}`` matrix must be symmetric, and only one element is returned. getconstraintquadratic(m::AbstractModel, c::ConstraintReference, k::Int, v_1::VariableReference, v_2::VariableReference) -Return the element ``(v_1, v_2)`` of the ``Q_{i,k}`` matrix of the ``k``th row of the constraint corresponding to ``c``. +Return the element corresponding to `(v_1, v_2)` of the ``Q_{i,k}`` matrix of the `k`th row of the constraint corresponding to `c`. """ function getconstraintquadratic end """ modifyconstraint!(m::AbstractModel, c::ConstraintReference, k::Int, args...) -Modify elements of the ``k``th row of the constraint ``c`` depending on the arguments ``args``. -The ``k``th row will have the form ``q_{i,k}(x) + A_{i,k}^T x + b_{i,k}``. +Modify elements of the `k`th row of the constraint `c` depending on the arguments `args`. +The `k`th row will have the form ``q_{i,k}(x) + A_{i,k}^T x + b_{i,k}``. There are four cases. ## Modify Constant term modifyconstraint!(m::AbstractModel, c::ConstraintReference, k::Int, b) -Set the constant term of the ``k``th row in the constraint ``c`` to ``b``. +Set the constant term of the `k`th row in the constraint `c` to `b`. ### Examples @@ -114,9 +114,9 @@ modifyconstraint!(m, c, 1, 1.0) modifyconstraint!(m::AbstractModel, c::ConstraintReference, k::Int, a_v::Vector{VariableReference}, a_coef) -Set elements given by ``a_v`` in the linear term of the ``k``th row in the constraint ``c`` to ``a_coef``. -Either ``a_v`` and ``a_coef`` are both singletons, or they should be collections with equal length. -The behavior of duplicate entries in ``a_v`` is undefined. +Set elements given by `a_v` in the linear term of the `k`th row in the constraint `c` to `a_coef`. +Either `a_v` and `a_coef` are both singletons, or they should be collections with equal length. +The behavior of duplicate entries in `a_v` is undefined. ### Examples @@ -129,9 +129,9 @@ modifyconstraint!(m, c, [v_1, v_2], [1.0, 2.0]) modifyconstraint!(m::AbstractModel, c::ConstraintReference, k::Int, Q_vari, Q_varj, Q_coef) -Set the elements in the quadratic term of the ``k``th row of the constraint ``c`` specified by the triplets ``Q_vari, Q_varj, Q_coef``. +Set the elements in the quadratic term of the `k`th row of the constraint `c` specified by the triplets `Q_vari, Q_varj, Q_coef`. Off-diagonal entries will be mirrored. -``Q_vari, Q_varj`` should be collections of ``VariableReference`` objects. +`Q_vari, Q_varj` should be collections of `VariableReference` objects. The behavior of duplicate entries is undefined. If entries for both ``(i,j)`` and ``(j,i)`` are provided, these are considered duplicate terms. @@ -146,11 +146,11 @@ modifyconstraint!(m, c, [v_1, v_2], [v_1, v_1], [1.0, 2.0]) modifyconstraint!(m::AbstractModel, c::ConstraintReference{Set}, S::Set) -Change the set of constraint ``c`` to the new set ``S`` which should be of the same type as the original set. +Change the set of constraint `c` to the new set `S` which should be of the same type as the original set. ### Examples -If ``c`` is a ``ConstraintReference{Interval}`` +If `c` is a `ConstraintReference{Interval}` ```julia modifyconstraint!(m, c, Interval(0, 5)) diff --git a/src/objectives.jl b/src/objectives.jl index d5f6b27180..de508ff20a 100644 --- a/src/objectives.jl +++ b/src/objectives.jl @@ -3,42 +3,42 @@ """ setobjective!(m::AbstractModel, b, a_varref::Vector{VariableReference}, a_coef, Q_vari::Vector{VariableReference}, Q_varj::Vector{VariableReference}, Q_coef, N::Int=1) -Set the ``N``th objective in the model ``m`` to be ``\frac{1}{2} x^T Q_0 x + a_0^T x + b_0``, where: -* ``a_0`` is a sparse vector specified in tuple form by ``a_varref, a_coef`` +Set the `N`th objective in the model `m` to be ``\\frac{1}{2} x^T Q_0 x + a_0^T x + b_0``, where: +* ``a_0`` is a sparse vector specified in tuple form by `a_varref, a_coef` * ``b_0`` is a scalar -* the symmetric matrix ``Q_0`` is defined by the triplets in ``Q_vari, Q_varj, Q_coef`` +* the symmetric matrix ``Q_0`` is defined by the triplets in `Q_vari, Q_varj, Q_coef` -Duplicate indices (sparse) in either the``a_0`` vector or the ``Q_0`` matrix are accepted and will be summed together. +Duplicate indices (sparse) in either the ``a_0`` vector or the ``Q_0`` matrix are accepted and will be summed together. Off-diagonal entries of ``Q_0`` will be mirrored, so either the upper triangular or lower triangular entries of ``Q_0`` should be provided. If entries for both ``(i,j)`` and ``(j,i)`` are provided, these are considered duplicate terms. -``a_varref``, ``Q_vari``, ``Q_varj`` should be collections of ``VariableReference`` objects. +`a_varref`, `Q_vari`, `Q_varj` should be collections of `VariableReference` objects. setobjective!(m::AbstractModel, b, a_varref::Vector{VariableReference}, a_coef, N::Int=1) -Set the ``N``th objective in the model ``m`` to be ``a_0^T x + b_0``, where: -* ``a_0`` is a sparse vector specified in tuple form by ``a_varref, a_coef`` +Set the `N`th objective in the model `m` to be ``a_0^T x + b_0``, where: +* ``a_0`` is a sparse vector specified in tuple form by `a_varref, a_coef` * ``b_0`` is a scalar -Duplicate indices (sparse) in either the``a_0`` vector or the ``Q_0`` matrix are accepted and will be summed together. +Duplicate indices (sparse) in either the ``a_0`` vector or the ``Q_0`` matrix are accepted and will be summed together. """ function setobjective! end """ getobjectiveconstant(m, N::Int=1) -Return the constant term in the ``N``th objective. +Return the constant term in the `N`th objective. """ function getobjectiveconstant end """ getobjectiveaffine(m, N::Int=1) -Return the affine part of the ``N``th objective in tuple form ``(varref, coef)`` where ``varref`` is a ``VariableReference`` and ``coef`` is a coefficient. +Return the affine part of the `N`th objective in tuple form `(varref, coef)` where `varref` is a `VariableReference` and `coef` is a coefficient. Output is a tuple of two vectors. getobjectiveaffine(m, v::VariableReference, N::Int=1) -Return the coefficient for the variable ``v`` in the affine part of the ``N``th objective. +Return the coefficient for the variable `v` in the affine part of the `N`th objective. """ function getobjectiveaffine end @@ -47,16 +47,16 @@ function getobjectiveaffine end """ modifyobjective!(m::AbstractModel, N::Int, args...) -Modify elements of the ``N``th objective depending on the arguments ``args``. -The ``N``th objective has the form ``\frac{1}{2} x^T Q_0 x + a_0^T x + b_0``. +Modify elements of the `N`th objective depending on the arguments `args`. +The `N`th objective has the form ``\\frac{1}{2} x^T Q_0 x + a_0^T x + b_0``. There are three cases, below. ## Modify Constant term - modifyobjective!(m::AbstractModel, N::Int, b_0) + modifyobjective!(m::AbstractModel, N::Int, b) -Set the constant term of the ``N``th objective to ``b_0``. +Set the constant term ``b_0`` of the `N`th objective to `b`. ### Examples @@ -68,9 +68,9 @@ modifyobjective!(m, 1, 1.0) modifyobjective!(m::AbstractModel, N::Int, a_varidx, a_coef) -Set elements given by ``a_varidx`` in the linear term of the ``N``th objective to ``a_coef``. -Either ``a_varidx`` and ``a_coef`` are both singletons, or they should be collections with equal length. -The behavior of duplicate entries in ``a_varidx`` is undefined. +Set elements given by `a_varidx` in the linear term of the `N`th objective to `a_coef`. +Either `a_varidx` and `a_coef` are both singletons, or they should be collections with equal length. +The behavior of duplicate entries in `a_varidx` is undefined. ### Examples @@ -83,9 +83,9 @@ modifyobjective!(m, 1, [v1, v2], [1.0, 2.0]) modifyobjective!(m::AbstractModel, N::Int, Q_vari, Q_varj, Q_coef) -Set the elements in the quadratic term of the ``N``th objective specified by the triplets ``Q_vari, Q_varj, Q_coef``. +Set the elements in the quadratic term of the `N`th objective specified by the triplets `Q_vari, Q_varj, Q_coef`. Off-diagonal entries will be mirrored. -``Q_vari, Q_varj`` should be collections of ``VariableReference`` objects. +`Q_vari, Q_varj` should be collections of `VariableReference` objects. The behavior of duplicate entries is undefined. If entries for both ``(i,j)`` and ``(j,i)`` are provided, these are considered duplicate terms. diff --git a/src/references.jl b/src/references.jl index 24f4c8f041..7204258de1 100644 --- a/src/references.jl +++ b/src/references.jl @@ -4,7 +4,7 @@ VariablewiseConstraintReference{T} A lightweight object used to reference variablewise constraints in a model. -The parameter ``T`` is the type of set constraint referenced. +The parameter `T` is the type of set constraint referenced. """ struct VariablewiseConstraintReference{T} value::UInt64 @@ -14,7 +14,7 @@ end AffineConstraintReference{T} A lightweight object used to reference affine-in-set constraints in a model. -The parameter ``T`` is the type of set constraint referenced. +The parameter `T` is the type of set constraint referenced. """ struct AffineConstraintReference{T} value::UInt64 @@ -24,7 +24,7 @@ end QuadraticConstraintReference{T} A lightweight object used to reference quadratic-in-set constraints in a model. -The parameter ``T`` is the type of set constraint referenced. +The parameter `T` is the type of set constraint referenced. """ struct QuadraticConstraintReference{T} value::UInt64 @@ -35,14 +35,14 @@ const ConstraintReference = Union{VariablewiseConstraintReference, AffineConstra """ candelete(m::AbstractModel, ref::ConstraintReference)::Bool -Return a ``Bool`` indicating whether this constraint can be removed from the model ``m``. +Return a `Bool` indicating whether this constraint can be removed from the model `m`. """ candelete(m::AbstractModel, ref::ConstraintReference) = throw(MethodError()) """ isvalid(m::AbstractModel, ref::ConstraintReference)::Bool -Return a ``Bool`` indicating whether this reference is valid for an active constraint in the model ``m``. +Return a `Bool` indicating whether this reference is valid for an active constraint in the model `m`. """ isvalid(m::AbstractModel, ref::ConstraintReference) = throw(MethodError()) @@ -53,7 +53,7 @@ Delete the referenced constraint from the model. delete!(m::AbstractModel, refs::Vector{ConstraintReference}) -Delete the referenced constraints in the vector ``refs`` from the model. +Delete the referenced constraints in the vector `refs` from the model. """ Base.delete!(m::AbstractModel, ref::ConstraintReference) = throw(MethodError()) Base.delete!(m::AbstractModel, refs::Vector{ConstraintReference}) = throw(MethodError()) @@ -70,14 +70,14 @@ end """ candelete(m::AbstractModel, ref::VariableReference)::Bool -Return a ``Bool`` indicating whether this variable can be removed from the model ``m``. +Return a `Bool` indicating whether this variable can be removed from the model `m`. """ candelete(m::AbstractModel, ref::VariableReference) = throw(MethodError()) """ isvalid(m::AbstractModel, ref::VariableReference)::Bool -Return a ``Bool`` indicating whether this reference is valid for an active variable in the model ``m``. +Return a `Bool` indicating whether this reference is valid for an active variable in the model `m`. """ isvalid(m::AbstractModel, ref::VariableReference) = throw(MethodError()) @@ -88,7 +88,7 @@ Delete the referenced variable from the model. delete!(m::AbstractModel, refs::Vector{VariableReference}) -Delete the referenced variables in the vector ``refs`` from the model. +Delete the referenced variables in the vector `refs` from the model. """ Base.delete!(m::AbstractModel, ref::VariableReference) = throw(MethodError()) Base.delete!(m::AbstractModel, refs::Vector{VariableReference}) = throw(MethodError()) diff --git a/src/sets.jl b/src/sets.jl index 6ff4548299..ed46bfed3f 100644 --- a/src/sets.jl +++ b/src/sets.jl @@ -17,7 +17,7 @@ dimension(s::AbstractSet) = s.dim """ Reals(dim) -The set ``\\mathbb{R}^{dim}`` (containing all points) of dimension ``dim``. +The set ``\\mathbb{R}^{dim}`` (containing all points) of dimension `dim`. """ struct Reals <: AbstractSet dim::Int @@ -26,7 +26,7 @@ end """ Zeros(dim) -The set ``\\{ 0 \\}^{dim}`` (containing only the origin) of dimension ``dim``. +The set ``\\{ 0 \\}^{dim}`` (containing only the origin) of dimension `dim`. """ struct Zeros <: AbstractSet dim::Int @@ -35,7 +35,7 @@ end """ NonNegatives(dim) -The nonnegative orthant ``\\{ x \\in \\mathbb{R}^{dim} : x \\ge 0 \\}`` of dimension ``dim``. +The nonnegative orthant ``\\{ x \\in \\mathbb{R}^{dim} : x \\ge 0 \\}`` of dimension `dim`. """ struct NonNegatives <: AbstractSet dim::Int @@ -44,7 +44,7 @@ end """ NonPositives(dim) -The nonpositive orthant ``\\{ x \\in \\mathbb{R}^{dim} : x \\le 0 \\}`` of dimension ``dim``. +The nonpositive orthant ``\\{ x \\in \\mathbb{R}^{dim} : x \\le 0 \\}`` of dimension `dim`. """ struct NonPositives <: AbstractSet dim::Int @@ -72,7 +72,7 @@ end Interval(lower,upper) The interval ``[lower, upper] \\subseteq \\mathbb{R}``. -If ``lower`` or ``upper`` is ``-Inf`` or ``Inf``, respectively, the set is interpreted as a one-sided interval. +If `lower` or `upper` is `-Inf` or `Inf`, respectively, the set is interpreted as a one-sided interval. """ struct Interval{T <: Real} <: AbstractSet lower::T @@ -84,7 +84,7 @@ dimension(s::Union{Interval,GreaterThan,LessThan}) = 1 """ SecondOrderCone(dim) -The second-order cone (or Lorenz cone) ``\\{ (t,x) \\in \\mathbb{R}^{dim} : t \\ge || x ||_2 \\}`` of dimension ``dim``. +The second-order cone (or Lorenz cone) ``\\{ (t,x) \\in \\mathbb{R}^{dim} : t \\ge || x ||_2 \\}`` of dimension `dim`. """ struct SecondOrderCone <: AbstractSet dim::Int @@ -109,7 +109,7 @@ end """ PowerCone(a) -The 3-dimensional power cone ``\\{ (x,y,z) \\in \\mathbb{R}^3 : x^{a} y^{1-a} >= |z|, x \\ge 0, y \\ge 0 \\}`` with parameter ``a``. +The 3-dimensional power cone ``\\{ (x,y,z) \\in \\mathbb{R}^3 : x^{a} y^{1-a} >= |z|, x \\ge 0, y \\ge 0 \\}`` with parameter `a`. """ struct PowerCone{T <: Real} <: AbstractSet a::T @@ -118,7 +118,7 @@ end """ DualPowerCone(a) -The 3-dimensional power cone ``\\{ (u,v,w) \\in \\mathbb{R}^3 : (u/a)^a (v/(1-a))^{1-a} >= |w|, u \\ge 0, v \\ge 0 \\}`` with parameter ``a``. +The 3-dimensional power cone ``\\{ (u,v,w) \\in \\mathbb{R}^3 : (\\frac{u}{a})^a (\\frac{v}/{1-a})^{1-a} >= |w|, u \\ge 0, v \\ge 0 \\}`` with parameter `a`. """ struct DualPowerCone{T <: Real} <: AbstractSet a::T @@ -131,7 +131,7 @@ dimension(s::Union{ExponentialCone, DualExponentialCone, PowerCone, DualPowerCon The (vectorized) cone of symmetric positive semidefinite matrices, with off-diagonals unscaled. The entries of the upper triangular part of the matrix are given row by row (or equivalently, the entries of the lower triangular part are given column by column). -An ``n \\times n`` matrix has ``n(n+1)/2`` lower-triangular elements, so for the vectorized cone of dimension ``dim``, the corresponding symmetric matrix has side dimension ``\\sqrt (1/4 + 2 dim) - 1/2`` elements. +An ``n \\times n`` matrix has ``n(n+1)/2`` lower-triangular elements, so for the vectorized cone of dimension `dim`, the corresponding symmetric matrix has side dimension ``\\sqrt (1/4 + 2 dim) - 1/2`` elements. The scalar product is the sum of the pairwise product of the diagonal entries plus twice the sum of the pairwise product of the upper diagonal entries. ### Examples @@ -155,7 +155,7 @@ end The (vectorized) cone of symmetric positive semidefinite matrices, with off-diagonals scaled. The entries of the upper triangular part of the matrix are given row by row (or equivalently, the entries of the lower triangular part are given column by column). -An ``n \\times n`` matrix has ``n(n+1)/2`` lower-triangular elements, so for the vectorized cone of dimension ``dim``, the corresponding symmetric matrix has side dimension ``\\sqrt (1/4 + 2 dim) - 1/2`` elements. +An ``n \\times n`` matrix has ``n(n+1)/2`` lower-triangular elements, so for the vectorized cone of dimension `dim`, the corresponding symmetric matrix has side dimension ``\\sqrt (1/4 + 2 dim) - 1/2`` elements. The off-diagonal entries of the matrices of both the cone and its dual are scaled by ``\\sqrt{2}`` and the scalar product is simply the sum of the pairwise product of the entries. ### Examples @@ -195,8 +195,8 @@ dimension(s::Union{Integers,ZeroOne}) = 1 The set corresponding to the special ordered set (SOS) constraint of type 1. Of the variables in the set, at most one can be nonzero. -The ``weights`` induce an ordering of the variables; as such, they should be unique values. -The ``k``-th element in the set corresponds to the ``k``-th weight in ``weights``. +The `weights` induce an ordering of the variables; as such, they should be unique values. +The *k*th element in the set corresponds to the *k*th weight in `weights`. See [here](http://lpsolve.sourceforge.net/5.5/SOS.htm) for a description of SOS constraints and their potential uses. """ struct SOS1{T <: Real} <: AbstractSet @@ -208,8 +208,8 @@ end The set corresponding to the special ordered set (SOS) constraint of type 2. Of the variables in the set, at most two can be nonzero, and if two are nonzero, they must be adjacent in the ordering of the set. -The ``weights`` induce an ordering of the variables; as such, they should be unique values. -The ``k``-th element in the set corresponds to the ``k``-th weight in ``weights``. +The `weights` induce an ordering of the variables; as such, they should be unique values. +The *k*th element in the set corresponds to the *k*th weight in `weights`. See [here](http://lpsolve.sourceforge.net/5.5/SOS.htm) for a description of SOS constraints and their potential uses. """ struct SOS2{T <: Real} <: AbstractSet diff --git a/src/variables.jl b/src/variables.jl index ba72955cea..783a46b961 100644 --- a/src/variables.jl +++ b/src/variables.jl @@ -3,7 +3,7 @@ """ addvariables!(m::AbstractModel, n::Int)::Vector{VariableReference} -Add ``n`` scalar variables to the model, returning a vector of variable references. +Add `n` scalar variables to the model, returning a vector of variable references. """ function addvariables! end @@ -15,7 +15,7 @@ In addition, there is a special case for adding variables to existing linear pro addvariable!(m::AbstractModel, cref::Vector{Union{AffineConstraintRef{NonPositive}, AffineConstraintRef{NonNegative}, AffineConstraintRef{Zero}, AffineConstraintRef{Interval}}}, coefs)::VariableReference -Add a variable with coefficients specified by ``coefs`` in the existing affine constraints given by the constraint references ``cref``. -To add a variable with coefficients in a constraint that is not listed here, use ``addvariable!(m)`` and then ``modifyconstraint!`` instead. +Add a variable with coefficients specified by `coefs` in the existing affine constraints given by the constraint references `cref`. +To add a variable with coefficients in a constraint that is not listed here, use `addvariable!(m)` and then `modifyconstraint!` instead. """ function addvariable! end From 8086660b9b679d46328da2dce2cb05141525c6b5 Mon Sep 17 00:00:00 2001 From: Chris Coey Date: Fri, 30 Jun 2017 03:27:35 -0400 Subject: [PATCH 7/7] fix more backticks and compile docs --- docs/src/apireference.md | 2 +- src/constraints.jl | 10 ++++++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/src/apireference.md b/docs/src/apireference.md index 74d28a06cb..274ca0bfa7 100644 --- a/docs/src/apireference.md +++ b/docs/src/apireference.md @@ -145,7 +145,7 @@ addvariable! ``` List of attributes associated with variables. [category AbstractVariableAttribute] -Calls to ``getattribute`` and ``setattribute!`` should include as an argument a single ``VariableReference`` or a vector of ``VariableReference`` objects. +Calls to `getattribute` and `setattribute!` should include as an argument a single `VariableReference` or a vector of `VariableReference` objects. ```@docs VariablePrimalStart diff --git a/src/constraints.jl b/src/constraints.jl index 1f0fb59348..aa1f70a256 100644 --- a/src/constraints.jl +++ b/src/constraints.jl @@ -12,7 +12,7 @@ Add the vector quadratic-in-set constraint ``q_i(x) + A_i^T x + b_i \\in \\mathc Duplicate indices in either the ``A_i`` matrix or any ``Q_{i,k}`` matrix are accepted and will be summed together. Off-diagonal entries of ``Q_{i,k}`` will be mirrored, so either the upper triangular or lower triangular entries of ``Q_{i,k}`` should be provided. If entries for both ``(i,j)`` and ``(j,i)`` are provided, these are considered duplicate terms. -`a_v`, `Q_vari`, `Q_varj` should be collections of ``VariableReference`` objects. +`a_v`, `Q_vari`, `Q_varj` should be collections of `VariableReference` objects. addconstraint!(m::AbstractModel, b, a_v::Vector{VariableReference}, a_coef, Q_vari::Vector{VariableReference}, Q_varj::Vector{VariableReference}, Q_coef, S::AbstractSet)::QuadraticConstraintReference{typeof(S)} @@ -22,6 +22,8 @@ Add the scalar quadratic-in-set constraint ``q_i(x) + a_i^T x + b_i \\in \\mathc * ``q_i(x)`` is defined as ``\\frac{1}{2} x^T Q_{i} x``, where the symmetric matrix ``Q_{i}`` is specified in triplet form by `Q_vari, Q_varj, Q_coef` * ``\\mathcal{S}_i`` is a pre-defined *scalar* set specified as `S` +Duplicate indices in the ``a_i`` or the ``Q_{i,k}`` are accepted and will be summed together. + addconstraint!(m::AbstractModel, b, a_constridx, a_v::Vector{VariableReference}, a_coef, S::AbstractSet)::AffineConstraintReference{typeof(S)} Add the vector affine-in-set constraint ``A_i^T x + b_i \\in \\mathcal{S}_i``, where: @@ -29,7 +31,7 @@ Add the vector affine-in-set constraint ``A_i^T x + b_i \\in \\mathcal{S}_i``, w * ``b_i`` is a vector specified by `b` * ``\\mathcal{S}_i`` is a pre-defined set specified as `S` -Duplicate indices in ``A_i`` are accepted and will be summed together. +Duplicate indices in the ``A_i`` are accepted and will be summed together. addconstraint!(m::AbstractModel, b, a_v::Vector{VariableReference}, a_coef, S::AbstractSet)::AffineConstraintReference{typeof(S)} @@ -38,12 +40,16 @@ Add the scalar affine-in-set constraint ``a_i^T x + b_i \\in \\mathcal{S}_i``, w * ``b_i`` is a scalar specified by `b` * ``\\mathcal{S}_i`` is a pre-defined *scalar* set specified as `S` +Duplicate indices in the ``a_i`` are accepted and will be summed together. + addconstraint!(m::AbstractModel, vs::Vector{VariableReference}, S::AbstractSet)::VariablewiseConstraintReference{typeof(S)} Add the vector variable-wise constraint ``(x_j)_{j \\in v_i} \\in \\mathcal{S}_i``, where: * ``v_i`` is a list of variable indices specified as a vector of variable references `vs` * ``\\mathcal{S}_i`` is a pre-defined set specified as `S` +Behavior is not defined for duplicate indices in the ``v_i``. + addconstraint!(m::AbstractModel, v::VariableReference, S::AbstractSet)::VariablewiseConstraintReference{typeof(S)} Add the scalar variable-wise constraint ``x_j \\in \\mathcal{S}_i``, where: