Merge pull request jump-dev#1058 from ccoffrin/master

Initial Migration to Docstrings

docs/src/refexpr.md

@@ -1,3 +1,7 @@
+```@meta
+CurrentModule = JuMP
+```
+
 Expressions and Constraints
 ===========================
 
@@ -24,50 +28,25 @@ The corresponding constraint is `QuadConstraint`, which is expected to be a conv
 Methods
 -------
 
--   `@constraint(m::Model, con)` - add linear or quadratic constraints.
--   `@constraint(m::Model, ref, con)` - add groups of linear or quadratic constraints. See Constraint Reference section for details.
--   `JuMP.addconstraint(m::Model, con)` - general way to add linear and quadratic constraints.
--   `@constraints` - add groups of constraints at once, in the same fashion as @constraint. The model must be the first argument, and multiple constraints can be added on multiple lines wrapped in a `begin ... end` block. For example:
-
-```julia
-    @constraints(m, begin
-      x >= 1
-      y - w <= 2
-      sum_to_one[i=1:3], z[i] + y == 1
-    end)
-```
--   `@expression(m::Model, ref, expr)` - efficiently builds a linear, quadratic, or second-order cone expression but does not add to model immediately. Instead, returns the expression which can then be inserted in other constraints. For example:
-
-```julia
-    @expression(m, shared, sum(i*x[i] for i=1:5))
-    @constraint(m, shared + y >= 5)
-    @constraint(m, shared + z <= 10)
+```@docs
+addconstraint
+@constraint
+@constraints
+@expression
+@SDconstraint
+addSOS1
+addSOS2
+@LinearConstraint
+@LinearConstraints
+@QuadConstraint
+@QuadConstraints
+Base.push!{C,V}(aff::GenericAffExpr{C,V}, new_coeff::C, new_var::V)
+Base.append!{C,V}(aff::GenericAffExpr{C,V}, other::GenericAffExpr{C,V})
+linearterms
+getvalue(a::AffExpr)
+getvalue(a::QuadExpr)
 ```
 
-The `ref` accepts index sets in the same way as `@variable`, and those indices can be used in the construction of the expressions:
-
-```julia
-@expression(m, expr[i=1:3], i*sum(x[j] for j=1:3))
-```
-
-Anonymous syntax is also supported:
-
-```julia
-expr = @expression(m, [i=1:3], i*sum(x[j] for j=1:3))
-```
-
--   `@SDconstraint(m::Model, expr)` - adds a semidefinite constraint to the model `m`. The expression `expr` must be a square, two-dimensional array.
--   `addSOS1(m::Model, coll::Vector{AffExpr})` - adds special ordered set constraint of type 1 (SOS1). Specify the set as a vector of weighted variables, e.g. `coll = [3x, y, 2z]`. Note that solvers expect the weights to be unique. See [here](http://lpsolve.sourceforge.net/5.5/SOS.htm) for more details. If there is no inherent weighting in your model, an SOS constraint is probably unnecessary.
--   `addSOS2(m::Model, coll::Vector{AffExpr})` - adds special ordered set constraint of type 2 (SOS2). Specify the set as a vector of weighted variables, e.g. `coll = [3x, y, 2z]`. Note that solvers expect the weights to be unique. See [here](http://lpsolve.sourceforge.net/5.5/SOS.htm) for more details.
--   `@LinearConstraint(expr)` - Constructs a `LinearConstraint` instance efficiently by parsing the `expr`. The same as `@constraint`, except it does not attach the constraint to any model.
--   `@LinearConstraints(expr)` - Constructs a vector of `LinearConstraint` objects. Similar to `@LinearConstraint`, except it accepts multiple constraints as input as long as they are separated by newlines.
--   `@QuadConstraint(expr)` - Constructs a `QuadConstraint` instance efficiently by parsing the `expr`. The same as `@constraint`, except it does not attach the constraint to any model.
--   `@QuadConstraints(expr)` - Constructs a vector of `QuadConstraint` objects. Similar to `@QuadConstraint`, except it accepts multiple constraints as input as long as they are separated by newlines.
--   `push!(aff::AffExpr, new_coeff::Float64, new_var::Variable)` - efficient way to grow an affine expression by one term. For example, to add `5x` to an existing expression `aff`, use `push!(aff, 5.0, x)`. This is significantly more efficient than `aff += 5.0*x`.
--   `append!(aff::AffExpr, other::AffExpr)` - efficiently append the terms of an affine expression to an existing affine expression. For example, given `aff = 5.0*x` and `other = 7.0*y + 3.0*z`, we can grow `aff` using `append!(aff, other)` which results in `aff` equaling `5x + 7y + 3z`. This is significantly more efficient than using `aff += other`.
--   `sum(affs::Array{AffExpr})` - efficiently sum an array of affine expressions.
--   `getvalue(expr)` - evaluate an `AffExpr` or `QuadExpr`, given the current solution values.
--   `linearterms{C,V}(aff::GenericAffExpr{C,V})` - provides an iterator over the `(a_i::C,x_i::V)` terms in affine expression ``\sum_i a_i x_i + b``.
 
 Constraint References
 ---------------------

docs/src/refmodel.md

@@ -1,3 +1,7 @@
+```@meta
+CurrentModule = JuMP
+```
+
 Models
 ======
 
@@ -34,40 +38,54 @@ Methods
 
 **General**
 
--   `MathProgBase.numvar(m::Model)` - returns the number of variables associated with the `Model m`.
--   `MathProgBase.numlinconstr(m::Model)` - returns the number of linear constraints associated with the `Model m`.
--   `MathProgBase.numquadconstr(m::Model)` - returns the number of quadratic constraints associated with the `Model m`.
--   `JuMP.numsocconstr(m::Model)` - returns the number of second order cone constraints associated with the `Model m`.
--   `JuMP.numsosconstr(m::Model)` - returns the number of sos constraints associated with the `Model m`.
--   `JuMP.numsdconstr(m::Model)` - returns the number of semi-definite constraints associated with the `Model m`.
--   `JuMP.numnlconstr(m::Model)` - returns the number of nonlinear constraints associated with the `Model m`.
--   `MathProgBase.numconstr(m::Model)` - returns the total number of constraints associated with the `Model m`.
--   `getsolvetime(m::Model)` - returns the solve time reported by the solver if it is implemented.
--   `getnodecount(m::Model)` - returns the number of explored branch-and-bound nodes, if it is implemented.
--   `getobjbound(m::Model)` - returns the best known bound on the optimal objective value. This is used, for example, when a branch-and-bound method is stopped before finishing.
--   `getobjgap(m::Model)` - returns the final relative optimality gap as optimization terminated. That is, it returns ``\frac{|b-f|}{|f|}``, where *b* is the best bound and *f* is the best feasible objective value.
--   `getrawsolver(m::Model)` - returns an object that may be used to access a solver-specific API.
--   `getsimplexiter(m::Model)` - returns the cumulative number of simplex iterations during the optimization process. In particular, for a MIP it returns the total simplex iterations for all nodes.
--   `getbarrieriter(m::Model)` - returns the cumulative number of barrier iterations during the optimization process.
--   `internalmodel(m::Model)` - returns the internal low-level `AbstractMathProgModel` object which can be used to access any functionality that is not exposed by JuMP. See the MathProgBase [documentation](https://mathprogbasejl.readthedocs.org/en/latest/).
--   `solve(m::Model; suppress_warnings=false, relaxation=false)` - solves the model using the selected solver (or a default for the problem class), and takes two optional arguments that are disabled by default. Setting `suppress_warnings` to `true` will suppress all JuMP-specific output (e.g. warnings about infeasibility and lack of dual information) but will not suppress solver output (which should be done by passing options to the solver). Setting `relaxation=true` solves the standard continuous relaxation for the model: that is, integrality is dropped, special ordered set constraints are not enforced, and semi-continuous and semi-integer variables with bounds `[l,u]` are replaced with bounds `[min(l,0),max(u,0)]`.
--   `JuMP.build(m::Model)` - builds the model in memory at the MathProgBase level without optimizing.
--   `setsolver(m::Model,s::AbstractMathProgSolver)` - changes the solver which will be used for the next call to `solve()`, discarding the current internal model if present.
--   `getindex(m::Model,name::Symbol)` - returns the variable, or group of variables, or constraint, or group of constraints, of the given name which were added to the model. This errors if multiple variables or constraints share the same name.
--   `setindex!(m::Model, value, name::Symbol)` - stores the object `value` in the model `m` so that it can be accessed via `getindex`.
+```@docs
+MathProgBase.numvar
+MathProgBase.numlinconstr
+MathProgBase.numquadconstr
+numsocconstr
+numsosconstr
+numsdconstr
+numnlconstr
+MathProgBase.numconstr
+internalmodel
+solve
+build
+setsolver
+Base.getindex(m::Model, name::Symbol)
+Base.setindex!(m::Model, value, name::Symbol)
+```
 
 **Objective**
 
--   `getobjective(m::Model)` - returns the objective function as a `QuadExpr`.
--   `getobjectivesense(m::Model)` - returns objective sense, either `:Min` or `:Max`.
--   `setobjectivesense(m::Model, newSense::Symbol)` - sets the objective sense (`newSense` is either `:Min` or `:Max`).
--   `getobjectivevalue(m::Model)` - returns objective value after a call to `solve`.
--   `getobjectivebound(m::Model)` - returns the best known bound on the optimal objective value after a call to `solve`.
+```@docs
+getobjective
+getobjectivesense
+setobjectivesense
+getobjectivevalue
+getobjectivebound
+```
+
+**Solver**
+
+These functions are JuMP versions of the similarly named functions in MathProgBase.
+
+```@docs
+getsolvetime
+getnodecount
+getobjbound
+getobjgap
+getrawsolver
+getsimplexiter
+getbarrieriter
+```
+
 
 **Output**
 
--   `writeLP(m::Model, filename::AbstractString; genericnames=true)` - write the model to `filename` in the LP file format. Set `genericnames=false` for user-defined variable names.
--   `writeMPS(m::Model, filename::AbstractString)` - write the model to `filename` in the MPS file format.
+```@docs
+writeLP
+writeMPS
+```
 
 Solve Status
 ------------

docs/src/refvariable.md

@@ -1,3 +1,7 @@
+```@meta
+CurrentModule = JuMP
+```
+
 Variables
 =========
 
@@ -178,24 +182,28 @@ Methods
 
 **Bounds**
 
--   `setlowerbound(x::Variable, lower)`, `getlowerbound(x::Variable)` - Set/get the lower bound of a variable.
--   `setupperbound(x::Variable, upper)`, `getupperbound(x::Variable)` - Set/get the upper bound of a variable.
+```@docs
+setlowerbound
+getlowerbound
+setupperbound
+getupperbound
+```
 
 **Variable Category**
 
--   `setcategory(x::Variable, v_type::Symbol)` - Set the variable category for `x` after construction. Possible categories are listed above.
--   `getcategory(x::Variable)` - Get the variable category for `x`.
-
-**Helper functions**
-
--   `sum(x)` - Operates on arrays of variables, efficiently produces an affine expression. Available in macros.
--   `dot(x, coeffs)` - Performs a generalized "dot product" for arrays of variables and coefficients up to three dimensions, or equivalently the sum of the elements of the Hadamard product. Available in macros, and also as `dot(coeffs, x)`.
+```@docs
+setcategory
+getcategory
+```
 
 **Values**
 
--   `getvalue(x)` - Get the value of this variable in the solution. If `x` is a single variable, this will simply return a number. If `x` is indexable then it will return an indexable dictionary of values. When the model is unbounded, `getvalue` will instead return the corresponding components of an unbounded ray, if available from the solver.
--   `setvalue(x,v)` - Provide an initial value `v` for this variable that can be used by supporting MILP solvers. If `v` is `NaN`, the solver may attempt to fill in this value to construct a feasible solution. `setvalue` cannot be used with fixed variables; instead their value may be set with `JuMP.fix(x,v)`.
--   `getdual(x)` - Get the reduced cost of this variable in the solution. Similar behavior to `getvalue` for indexable variables.
+```@docs
+getvalue(v::Variable)
+getvalue(arr::Array{Variable})
+setvalue
+getdual
+```
 
 !!! note
     The `getvalue` function always returns a floating-point value, even when a variable is constrained to take integer values, as most solvers only guarantee integrality up to a particular numerical tolerance. The built-in `round` function should be used to obtain integer values, e.g., by calling `round(Integer, getvalue(x))`.
@@ -204,7 +212,20 @@ Methods
 
 Variables (in the sense of columns) can have internal names (different from the Julia variable name) that can be used for writing models to file. This feature is disabled for performance reasons, but will be added if there is demand or a special use case.
 
--   `setname(x::Variable, newName)`, `getname(x::Variable)` - Set/get the variable's internal name.
+```@docs
+setname
+getname
+```
+
+
+Helper functions
+----------------
+The following built-in functions are overloaded to provide easy construction of expressions from variables,
+
+-   `sum(x)` - Operates on arrays of variables, efficiently produces an affine expression. Available in macros.
+-   `dot(x, coeffs)` - Performs a generalized "dot product" for arrays of variables and coefficients up to three dimensions, or equivalently the sum of the elements of the Hadamard product. Available in macros, and also as `dot(coeffs, x)`.
+
+
 
 Fixed variables
 ---------------