Skip to content

Fix formatting of modification section #402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 25, 2018
Merged

Fix formatting of modification section #402

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 53 additions & 42 deletions docs/src/apimanual.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -435,16 +435,17 @@ instance of the same type.
Given a constraint of type `F`-in-`S` (see [Constraints by function-set pairs](@ref)
above for an explanation), we can modify parameters (but not the type) of the
set `S` by replacing it with a new instance of the same type. For example,
given the variable bound ``x \\le 1``:
given the variable bound ``x \le 1``:
```julia
c = addconstraint(m, SingleVariable(x), LessThan(1.0))
```
we can modify the set so that the bound now ``x \\le 2`` as follows:
we can modify the set so that the bound now ``x \le 2`` as follows:
```julia
set!(m, ConstraintSet(), c, LessThan(2.0))
```
where `m` is our [`ModelLike`](@ref) model. However, the following will fail as
the new set (`GreaterThan`) is of a different type to the original set
where `m` is our [`ModelLike`](@ref MathOptInterface.ModelLike) model. However,
the following will fail as the new set (`GreaterThan`) is of a different type to
the original set
(`LessThan`):
```julia
set!(m, ConstraintSet(), c, GreaterThan(2.0)) # errors
Expand All @@ -453,36 +454,40 @@ If our constraint is an affine inequality, then this corresponds to modifying
the right-hand side of a constraint in linear programming.

In some special cases, solvers may support efficiently changing the set of a
constraint (for example, from [`LessThan`](@ref) to [`GreaterThan`](@ref)). For
these cases, MathOptInterface provides the [`transform!`](@ref) method. For
example, instead of the error we observed above, the following will work:
constraint (for example, from [`LessThan`](@ref MathOptInterface.LessThan) to
[`GreaterThan`](@ref MathOptInterface.GreaterThan)). For these cases,
MathOptInterface provides the [`transform!`](@ref MathOptInterface.transform!)
method. For example, instead of the error we observed above, the following will
work:
```julia
c2 = transform!(m, c, GreaterThan(1.0))
```
The [`transform!`](@ref) function returns a new constraint index, and the old
constraint index (i.e., `c`) is no longer valid:
The [`transform!`](@ref MathOptInterface.transform!) function returns a new
constraint index, and the old constraint index (i.e., `c`) is no longer valid:
```julia
isvalid(m, c) # false
isvalid(m, c2) # true
```
Also note that [`transform!`](@ref) cannot be called with a set of the same
type; [`set!`](@ref) should be used instead.
Also note that [`transform!`](@ref MathOptInterface.transform!) cannot be called
with a set of the same type; [`set!`](@ref MathOptInterface.set!) should be used
instead.

#### The function of a constraint

Given a constraint of type `F`-in-`S` (see [Constraints by function-set pairs](@ref)
above for an explanation), it is also possible to modify the function of type
`F` by replacing it with a new instance of the same type. For example, given the
variable bound ``x \\le 1``:
variable bound ``x \le 1``:
```julia
c = addconstraint(m, SingleVariable(x), LessThan(1.0))
```
we can modify the function so that the bound now ``y \\le 1`` as follows:
we can modify the function so that the bound now ``y \le 1`` as follows:
```julia
set!(m, ConstraintFunction(), c, SingleVariable(y))
```
where `m` is our [`ModelLike`](@ref) model. However, the following will fail as
the new function is of a different type to the original function:
where `m` is our [`ModelLike`](@ref MathOptInterface.ModelLike) model. However,
the following will fail as the new function is of a different type to the
original function:
```julia
set!(m, ConstraintFunction(), c,
ScalarAffineFunction([ScalarAffineTerm(1.0, x)], 0.0)
Expand All @@ -501,25 +506,28 @@ MathOptInterface. They are:

To distinguish between the replacement of the function with a new instance
(described above) and the modification of an existing function, the in-place
modifications use the [`modify!`](@ref) method:
modifications use the [`modify!`](@ref MathOptInterface.modify!) method:
```julia
modify!(model, index, change::AbstractFunctionModification)
```
[`modify!`](@ref) takes three arguments. The first is the [`ModelLike`](@ref)
model `model`, the second is the constraint index, and the third is an instance
of an [`AbstractFunctionModification`](@ref).
[`modify!`](@ref MathOptInterface.modify!) takes three arguments. The first is
the [`ModelLike`](@ref MathOptInterface.ModelLike) model `model`, the second is
the constraint index, and the third is an instance of an
[`AbstractFunctionModification`](@ref MathOptInterface.AbstractFunctionModification).

We now detail each of these four in-place modifications.

#### Constant term in a scalar function

MathOptInterface supports is the ability to modify the constant term within a
[`ScalarAffineFunction`](@ref) and a [`ScalarQuadraticFunction`](@ref) using the
[`ScalarConstantChange`](@ref) subtype of
[`AbstractFunctionModification`](@ref). This includes the objective function, as
well as the function in a function-pair constraint.

For example, consider a problem `m` with the objective ``\\max 1.0x + 0.0``:
[`ScalarAffineFunction`](@ref MathOptInterface.ScalarAffineFunction) and a
[`ScalarQuadraticFunction`](@ref MathOptInterface.ScalarQuadraticFunction) using
the [`ScalarConstantChange`](@ref MathOptInterface.ScalarConstantChange) subtype
of [`AbstractFunctionModification`](@ref MathOptInterface.AbstractFunctionModification).
This includes the objective function, as well as the function in a function-pair
constraint.

For example, consider a problem `m` with the objective ``\max 1.0x + 0.0``:
```julia
set!(m,
ObjectiveFunction{ScalarAffineFunction{Float64}}(),
Expand All @@ -533,13 +541,13 @@ modify!(m,
ScalarConstantChange(1.0)
)
```
The objective function will now be ``\\max 1.0x + 1.0``.
The objective function will now be ``\max 1.0x + 1.0``.

#### Constant terms in a vector function

We can modify the constant terms in a [`VectorAffineFunction`](@ref) or a
[`VectorQuadraticFunction`](@ref) using the [`VectorConstantChange`](@ref)
subtype of [`AbstractFunctionModification`](@ref).
We can modify the constant terms in a [`VectorAffineFunction`](@ref MathOptInterface.VectorAffineFunction) or a [`VectorQuadraticFunction`](@ref MathOptInterface.VectorQuadraticFunction) using the
[`VectorConstantChange`](@ref MathOptInterface.VectorConstantChange) subtype of
[`AbstractFunctionModification`](@ref MathOptInterface.AbstractFunctionModification).

For example, consider a model with the following
`VectorAffineFunction`-in-`Nonpositives` constraint:
Expand All @@ -554,20 +562,20 @@ c = addconstraint!(m,
Nonpositives(2)
)
```
We can modify the constant vector in the [`VectorAffineFunction`](@ref) from
`[0.0, 0.0]` to `[1.0, 2.0]` as follows:
We can modify the constant vector in the [`VectorAffineFunction`](@ref MathOptInterface.VectorAffineFunction)
from `[0.0, 0.0]` to `[1.0, 2.0]` as follows:
```julia
modify!(m, c, VectorConstantChange([1.0, 2.0])
)
```
The constraints are now ``1.0x + 1.0 \\le 0.0`` and ``2.0y + 2.0 \\le 0.0``.
The constraints are now ``1.0x + 1.0 \le 0.0`` and ``2.0y + 2.0 \le 0.0``.

#### Affine coefficients in a scalar function

In addition to modifying the constant terms in a function, we can also modify
the affine variable coefficients in an [`ScalarAffineFunction`](@ref) or a
[`ScalarQuadraticFunction`](@ref) using the [`ScalarCoefficientChange`](@ref)
subtype of [`AbstractFunctionModification`](@ref).
the affine variable coefficients in an [`ScalarAffineFunction`](@ref MathOptInterface.ScalarAffineFunction) or a [`ScalarQuadraticFunction`](@ref MathOptInterface.ScalarQuadraticFunction) using
the [`ScalarCoefficientChange`](@ref MathOptInterface.ScalarCoefficientChange)
subtype of [`AbstractFunctionModification`](@ref MathOptInterface.AbstractFunctionModification).

For example, given the constraint ``1.0x <= 1.0``:
```julia
Expand All @@ -582,19 +590,22 @@ we can modify the coefficient of the `x` variable so that the constraint becomes
modify!(m, c, ScalarCoefficientChange(x, 2.0))
```

[`ScalarCoefficientChange`](@ref) can also be used to modify the objective
function by passing an instance of [`ObjectiveFunction`](@ref) instead of the
[`ScalarCoefficientChange`](@ref MathOptInterface.ScalarCoefficientChange) can
also be used to modify the objective function by passing an instance of
[`ObjectiveFunction`](@ref MathOptInterface.ObjectiveFunction) instead of the
constraint index `c` as we saw above.

#### Affine coefficients in a vector function

Finally, the last modification supported by MathOptInterface is the ability to
modify the affine coefficients of a single variable in a
[`VectorAffineFunction`](@ref) or a [`VectorQuadraticFunction`](@ref) using the
[`MultirowChange`](@ref) subtype of [`AbstractFunctionModification`](@ref).
[`VectorAffineFunction`](@ref MathOptInterface.VectorAffineFunction) or a
[`VectorQuadraticFunction`](@ref MathOptInterface.VectorQuadraticFunction) using
the [`MultirowChange`](@ref MathOptInterface.MultirowChange) subtype of
[`AbstractFunctionModification`](@ref MathOptInterface.AbstractFunctionModification).

For example, given the constraint ``Ax \\in \\mathbb{R}^2_+``, where
``A = [1.0, 2.0]^\\top``:
For example, given the constraint ``Ax \in \mathbb{R}^2_+``, where
``A = [1.0, 2.0]^\top``:
```julia
c = addconstraint!(m,
VectorAffineFunction([
Expand All @@ -607,7 +618,7 @@ c = addconstraint!(m,
)
```
we can modify the coefficients of the `x` variable so that the `A` matrix
becomes ``A = [3.0, 4.0]^\\top`` as follows:
becomes ``A = [3.0, 4.0]^\top`` as follows:
```julia
modify!(m, c, MultirowChange(x, [3.0, 4.0]))
```
Expand Down
20 changes: 7 additions & 13 deletions docs/src/apireference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,8 +163,6 @@ isvalid(::ModelLike,::ConstraintIndex)
canaddconstraint
addconstraint!
addconstraints!
modify!
canmodify
transform!
cantransform
supportsconstraint
Expand Down Expand Up @@ -207,15 +205,6 @@ Functions for getting and setting properties of sets.
output_dimension
```

List of function modifications.
```@docs
AbstractFunctionModification
ScalarConstantChange
VectorConstantChange
ScalarCoefficientChange
MultirowChange
```

## Sets

List of recognized sets.
Expand Down Expand Up @@ -257,13 +246,18 @@ Functions for getting and setting properties of sets.
dimension
```

## Objective modifications
## Modifications

Functions for modifying objective functions. Use `ObjectiveFunction` and `ObjectiveSense` to set and query the objective function.
Functions for modifying objective and constraint functions.

```@docs
modify!
canmodify
AbstractFunctionModification
ScalarConstantChange
VectorConstantChange
ScalarCoefficientChange
MultirowChange
```

## Nonlinear programming (NLP)
Expand Down