Skip to content

Document Test submodule #1273

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
Mar 9, 2021
Merged

Document Test submodule #1273

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
96 changes: 0 additions & 96 deletions docs/src/manual/implementing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,99 +215,3 @@ should be stored in a `src/MOI_wrapper` folder and included by a
By convention, optimizers should not be exported and should be named
`PackageName.Optimizer`. For example, `CPLEX.Optimizer`, `Gurobi.Optimizer`, and
`Xpress.Optimizer`.

## Testing guideline

The skeleton below can be used for the wrapper test file of a solver named
`FooBar`.
```julia
using Test

using MathOptInterface
const MOI = MathOptInterface
const MOIT = MOI.Test
const MOIU = MOI.Utilities
const MOIB = MOI.Bridges

import FooBar
const OPTIMIZER_CONSTRUCTOR = MOI.OptimizerWithAttributes(
FooBar.Optimizer, MOI.Silent() => true
)
const OPTIMIZER = MOI.instantiate(OPTIMIZER_CONSTRUCTOR)

@testset "SolverName" begin
@test MOI.get(OPTIMIZER, MOI.SolverName()) == "FooBar"
end

@testset "supports_default_copy_to" begin
@test MOIU.supports_default_copy_to(OPTIMIZER, false)
# Use `@test !...` if names are not supported
@test MOIU.supports_default_copy_to(OPTIMIZER, true)
end

const BRIDGED = MOI.instantiate(
OPTIMIZER_CONSTRUCTOR, with_bridge_type = Float64
)
const CONFIG = MOIT.TestConfig(atol=1e-6, rtol=1e-6)

@testset "Unit" begin
# Test all the functions included in dictionary `MOI.Test.unittests`,
# except functions "number_threads" and "solve_qcp_edge_cases."
MOIT.unittest(
BRIDGED,
CONFIG,
["number_threads", "solve_qcp_edge_cases"]
)
end

@testset "Modification" begin
MOIT.modificationtest(BRIDGED, CONFIG)
end

@testset "Continuous Linear" begin
MOIT.contlineartest(BRIDGED, CONFIG)
end

@testset "Continuous Conic" begin
MOIT.contlineartest(BRIDGED, CONFIG)
end

@testset "Integer Conic" begin
MOIT.intconictest(BRIDGED, CONFIG)
end
```

Test functions like `MOI.Test.unittest` and `MOI.Test.modificationtest` are
wrappers around corresponding dictionaries `MOI.Test.unittests` and
`MOI.Test.modificationtests`. The keys of each dictionary (strings describing
the test) map to functions that take two arguments: an optimizer and a
`MOI.Test.TestConfig` object. Exclude tests by passing a vector of strings
corresponding to the test keys you want to exclude as the third positional
argument to the test function (e.g., `MOI.Test.unittest`).

Print a list of all keys using `println.(keys(MOI.Test.unittests))`

The optimizer `BRIDGED` constructed with [`instantiate`](@ref)
automatically bridges constraints that are not supported by `OPTIMIZER`
using the bridges listed in [Bridges](@ref). It is recommended for an
implementation of MOI to only support constraints that are natively supported
by the solver and let bridges transform the constraint to the appropriate form.
For this reason it is expected that tests may not pass if `OPTIMIZER` is used
instead of `BRIDGED`.

To test that a specific problem can be solved without bridges, a specific test
can be run with `OPTIMIZER` instead of `BRIDGED`. For instance
```julia
@testset "Interval constraints" begin
MOIT.linear10test(OPTIMIZER, CONFIG)
end
```
checks that `OPTIMIZER` implements support for
[`ScalarAffineFunction`](@ref)-in-[`Interval`](@ref).

If the wrapper does not support building the model incrementally (i.e. with
[`add_variable`](@ref) and [`add_constraint`](@ref)),
then [`Utilities.supports_default_copy_to`](@ref) can be replaced by
[`Utilities.supports_allocate_load`](@ref) if appropriate (see
[Implementing copy](@ref)).

3 changes: 1 addition & 2 deletions docs/src/submodules/Bridges/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,7 @@ constraints of different types. There are two important concepts to distinguish:
by using the list of bridges that were added to it by
[`Bridges.add_bridge`](@ref). [`Bridges.full_bridge_optimizer`](@ref) wraps a
model in a [`Bridges.LazyBridgeOptimizer`](@ref) where all the bridges defined
in MOI are added. This is the recommended way to use bridges in the
[Testing guideline](@ref), and JuMP automatically calls
in MOI are added. JuMP automatically calls
[`Bridges.full_bridge_optimizer`](@ref) when attaching an optimizer.
[`Bridges.debug_supports_constraint`](@ref) and [`Bridges.debug_supports`](@ref)
allow introspection into the bridge selection rationale of
Expand Down
Loading