WIP: reorganize API file, make it more consistent

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,47 @@ 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
+
+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}``
 
 ## 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{C}_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{C}_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

docs/src/apireference.md

@@ -4,7 +4,31 @@ 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
+AbstractSolverOrModelAttribute
+AbstractVariableAttribute
+AbstractConstraintAttribute
+```
+
+Functions for getting and setting attributes.
+
+```@docs
+cangetattribute
+getattribute
+getattribute!
+cansetattribute
+setattribute!
+```
+
+## Solver and Model
+
+[separate solver and model?]
 
 ```@docs
 AbstractModel
@@ -17,47 +41,67 @@ optimize!
 freemodel!
 ```
 
-## Variables
+List of solver or model attributes. [category AbstractSolverOrModelAttribute]
 
 ```@docs
-VariableReference
-candelete(::AbstractModel,::VariableReference)
-isvalid(::AbstractModel,::VariableReference)
-delete!(::AbstractModel,::VariableReference)
-addvariables!
-addvariable!
+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
 ```
 
-## Objectives
+### Termination Status
+
+The `TerminationStatus` attribute indicates why the solver stopped executing.
+The value of the attribute is of type `TerminationStatusCode`.
 
-How to add and set objectives.
 ```@docs
-setobjective!
-modifyobjective!
-getobjectiveconstant
-getobjectiveaffine
+TerminationStatusCode
 ```
 
-## Constraints
+### 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`.
 
-How to add and modify constraints.
 ```@docs
-VariablewiseConstraintReference
-AffineConstraintReference
-QuadraticConstraintReference
-candelete(::AbstractModel,::ConstraintReference)
-isvalid(::AbstractModel,::ConstraintReference)
-delete!(::AbstractModel,::ConstraintReference)
-addconstraint!
-modifyconstraint!
-getconstraintconstant
-getconstraintaffine
-getconstraintquadratic
+ResultStatusCode
+```
+
+### Basis Status
+
+[what? BasisStatus]
+
+```@docs
+BasisStatusCode
 ```
 
 ## Sets
 
-List of sets.
+List of recognized sets.
+
 ```@docs
 AbstractSet
 Reals
@@ -81,94 +125,71 @@ 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
-
-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.
-```@docs
-ConstraintPrimalStart
-ConstraintDualStart
-ConstraintPrimal
-ConstraintDual
-ConstraintBasisStatus
-```
+## Objectives
 
-## Status Codes
+Functions for adding and modifying objectives.
 
-### 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`.
 ```@docs
-TerminationStatusCode
+setobjective!
+modifyobjective!
+getobjectiveconstant
+getobjectiveaffine
 ```
 
-### Result Status
+## Constraints
+
+Constraint references and functions for adding, modifying, and removing constraints.
 
-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`.
 ```@docs
-ResultStatusCode
+VariablewiseConstraintReference
+AffineConstraintReference
+QuadraticConstraintReference
+candelete(::AbstractModel,::ConstraintReference)
+isvalid(::AbstractModel,::ConstraintReference)
+delete!(::AbstractModel,::ConstraintReference)
+addconstraint!
+modifyconstraint!
+getconstraintconstant
+getconstraintaffine
+getconstraintquadratic
 ```
 
-### Basis Status
+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
-BasisStatusCode
+ConstraintPrimalStart
+ConstraintDualStart
+ConstraintPrimal
+ConstraintDual
+ConstraintBasisStatus
 ```

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
 ```

src/MathOptInterface.jl

@@ -1,24 +1,23 @@
 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.
 """
@@ -34,19 +33,18 @@ 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
 
 """
     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