Skip to content

Update README #263

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
matbesancon merged 1 commit into from
Apr 10, 2023
Merged

Update README #263

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
190 changes: 113 additions & 77 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,119 +1,155 @@
# SCIP.jl

[SCIP.jl](https://github.com/scipopt/SCIP.jl) is a Julia interface to the [SCIP](https://scipopt.org) solver.

[![Build Status](https://github.com/scipopt/SCIP.jl/workflows/CI/badge.svg?branch=master)](https://github.com/scipopt/SCIP.jl/actions?query=workflow%3ACI)
[![codecov](https://codecov.io/gh/scipopt/SCIP.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/scipopt/SCIP.jl)
[![Genie Downloads](https://shields.io/endpoint?url=https://pkgs.genieframework.com/api/v1/badge/SCIP)](https://pkgs.genieframework.com?packages=SCIP)

[SCIP.jl](https://github.com/scipopt/SCIP.jl) is a Julia interface to the
[SCIP](https://scipopt.org) solver.

## Affiliation

This wrapper is maintained by the [SCIP project](https://www.scipopt.org/) with the help of the JuMP community.
This wrapper is maintained by the [SCIP project](https://www.scipopt.org/) with
the help of the JuMP community.

## License

`SCIP.jl` is licensed under the
[MIT License](https://github.com/scipopt/SCIP.jl/blob/master/LICENSE).
`SCIP.jl` is licensed under the [MIT License](https://github.com/scipopt/SCIP.jl/blob/master/LICENSE).

SCIP itself is licensed under the [Apache 2.0 license](https://github.com/scipopt/scip/blob/master/LICENSE).
The underlying solver, [scipopt/scip](https://github.com/scipopt/scip), is
licensed under the [Apache 2.0 license](https://github.com/scipopt/scip/blob/master/LICENSE).

## Installation

Install SCIP.jl as follows:
Install SCIP.jl using `Pkg.add`:
```julia
julia> import Pkg
julia> Pkg.add("SCIP")
import Pkg
Pkg.add("SCIP")
```

On MacOS and Linux, installing the SCIP Julia package will work out of the box and install the [SCIP_jll.jl](https://github.com/JuliaBinaryWrappers/SCIP_jll.jl) and
[SCIP_PaPILO_jll.jl](https://github.com/JuliaBinaryWrappers/SCIP_PaPILO_jll.jl) dependencies.
On MacOS and Linux, installing the SCIP Julia package will work out of the box
and install the [`SCIP_jll.jl`](https://github.com/JuliaBinaryWrappers/SCIP_jll.jl) and
[`SCIP_PaPILO_jll.jl`](https://github.com/JuliaBinaryWrappers/SCIP_PaPILO_jll.jl)
dependencies.

On Windows, the separate installation of SCIP is still mandatory as detailed below.
If you use an older Julia version, Windows or want a custom SCIP installation, see below for the build steps.
On Windows, a separate installation of SCIP is still mandatory, as detailed in
the "Custom installation" section below.

## Custom SCIP installations.
## Custom installations

If you prefer to link to your own installation of SCIP, please set the
environment variable `SCIPOPTDIR` to point to the **installation path**. That
is, either `$SCIPOPTDIR/lib/libscip.so`, `$SCIPOPTDIR/lib/libscip.dylib` or
`$SCIPOPTDIR/bin/scip.dll` should exist, depending on your operating system.
If you use an older Julia version, Windows, or you want a custom SCIP
installation, you must manually install the SCIP binaries.

When this is set before you install this package, it should be recognized
automatically. Afterward, you can trigger the build with
Once installed, set the `SCIPOPTDIR` environment variable to point to the
installation path, that is, depending on your operating system,
`$SCIPOPTDIR/lib/libscip.so`, `$SCIPOPTDIR/lib/libscip.dylib`, or
`$SCIPOPTDIR/bin/scip.dll` must exist.

Then, install `SCIP.jl` using `Pkg.add` and `Pkg.build`:
```julia
pkg> build SCIP
ENV["SCIPOPTDIR"] = "/Users/Oscar/code/SCIP"
import Pkg
Pkg.add("SCIP")
Pkg.build("SCIP")
```

## Setting Parameters
## Use with JuMP

There are two ways of setting the parameters
([all](https://scip.zib.de/doc-8.0.0/html/PARAMETERS.php) are supported). First,
using `MOI.set`:
Use SCIP with JuMP as follows:

```julia
import MathOptInterface as MOI
using SCIP

optimizer = SCIP.Optimizer()
MOI.set(optimizer, MOI.RawOptimizerAttribute("display/verblevel"), 0)
MOI.set(optimizer, MOI.RawOptimizerAttribute("limits/gap"), 0.05)
using JuMP, SCIP
model = Model(SCIP.Optimizer)
set_attribute(model, "display/verblevel", 0)
set_attribute(model, "limits/gap", 0.05)
```

Second, as keyword arguments to the constructor. But here, the slashes (`/`)
need to be replaced by underscores (`_`) in order to end up with a valid Julia
identifier. This should not lead to ambiguities as none of the official SCIP
parameters contain any underscores (yet).
## Options

```julia
import MathOptInterface as MOI
using SCIP
See the [SCIP documentation](https://scip.zib.de/doc-8.0.0/html/PARAMETERS.php)
for a list of supported options.

optimizer = SCIP.Optimizer(display_verblevel=0, limits_gap=0.05)
```
## MathOptInterface API

Note that in both cases, the correct value type must be used
(here, `Int64` and `Float64`).
The SCIP optimizer supports the following constraints and attributes.

## Errors with nonlinear models
List of supported objective functions:

When solving a nonlinear model, you may encounter `Error: no BLAS/LAPACK library loaded!`,
this comes from Ipopt, see the [README](https://github.com/jump-dev/Ipopt.jl/#julia-17) on Ipopt.jl.

## Design Considerations

**Wrapper of Public API**: All of SCIP's public API methods are wrapped and
available within the `SCIP` package. This includes the `scip_*.h` and `pub_*.h`
headers that are collected in `scip.h`, as well as all default constraint
handlers (`cons_*.h`.) But the wrapped functions do not transform any data
structures and work on the *raw* pointers (e.g. `SCIP*` in C, `Ptr{SCIP_}` in
Julia). Convenience wrapper functions based on Julia types are added as needed.

**Memory Management**: Programming with SCIP requires dealing with variable and
constraint objects that use [reference
counting](https://scip.zib.de/doc-8.0.0/html/OBJ.php) for memory management.
The `SCIP.Optimizer` wrapper type collects lists of `SCIP_VAR*`
and `SCIP_CONS*` under the hood, and releases all references when it is garbage
collected itself (via `finalize`).
When adding a variable (`add_variable`) or a constraint (`add_linear_constraint`),
an integer index is returned.
This index can be used to retrieve the `SCIP_VAR*` or `SCIP_CONS*`
pointer via `get_var` and `get_cons` respectively.
* [`MOI.ObjectiveFunction{MOI.ScalarAffineFunction{Float64}}`](@ref)

List of supported variable types:

* [`MOI.Reals`](@ref)

List of supported constraint types:

* [`MOI.ScalarAffineFunction{Float64}`](@ref) in [`MOI.EqualTo{Float64}`](@ref)
* [`MOI.ScalarAffineFunction{Float64}`](@ref) in [`MOI.GreaterThan{Float64}`](@ref)
* [`MOI.ScalarAffineFunction{Float64}`](@ref) in [`MOI.Interval{Float64}`](@ref)
* [`MOI.ScalarAffineFunction{Float64}`](@ref) in [`MOI.LessThan{Float64}`](@ref)
* [`MOI.ScalarQuadraticFunction{Float64}`](@ref) in [`MOI.EqualTo{Float64}`](@ref)
* [`MOI.ScalarQuadraticFunction{Float64}`](@ref) in [`MOI.GreaterThan{Float64}`](@ref)
* [`MOI.ScalarQuadraticFunction{Float64}`](@ref) in [`MOI.Interval{Float64}`](@ref)
* [`MOI.ScalarQuadraticFunction{Float64}`](@ref) in [`MOI.LessThan{Float64}`](@ref)
* [`MOI.VariableIndex`](@ref) in [`MOI.EqualTo{Float64}`](@ref)
* [`MOI.VariableIndex`](@ref) in [`MOI.GreaterThan{Float64}`](@ref)
* [`MOI.VariableIndex`](@ref) in [`MOI.Integer`](@ref)
* [`MOI.VariableIndex`](@ref) in [`MOI.Interval{Float64}`](@ref)
* [`MOI.VariableIndex`](@ref) in [`MOI.LessThan{Float64}`](@ref)
* [`MOI.VariableIndex`](@ref) in [`MOI.ZeroOne`](@ref)
* [`MOI.VectorOfVariables`](@ref) in [`MOI.SOS1{Float64}`](@ref)
* [`MOI.VectorOfVariables`](@ref) in [`MOI.SOS2{Float64}`](@ref)

List of supported model attributes:

**Supported Features for MathOptInterface**: We aim at exposing many of SCIP's
features through MathOptInterface. However, the focus is on keeping the wrapper
simple and avoiding duplicate storage of model data.
* [`MOI.NLPBlock()`](@ref)
* [`MOI.ObjectiveSense()`](@ref)
* [`MOI.UserCutCallback()`](@ref)

As a consequence, we do not currently support some features such as retrieving
constraints by name (`VariableIndex`-set constraints are not stored as SCIP
constraints explicitly).
## Design considerations

Support for more constraint types (quadratic, SOS1/2, nonlinear expression)
is implemented, but SCIP itself only supports affine objective functions.
Nonlinear objectives can be supported by MathOptInterface bridges.
### Wrapping the public API

All of the public API methods are wrapped and available within the `SCIP`
package. This includes the `scip_*.h` and `pub_*.h` headers that are collected
in `scip.h`, as well as all default constraint handlers (`cons_*.h`.)

The wrapped functions do not transform any data structures and work on the *raw*
pointers (for example, `SCIP*` in C, `Ptr{SCIP_}` in Julia). Convenience wrapper
functions based on Julia types are added as needed.

### Memory management

Programming with SCIP requires dealing with variable and constraint objects that
use [reference counting](https://scip.zib.de/doc-8.0.0/html/OBJ.php) for memory
management.

The `SCIP.Optimizer` wrapper type collects lists of `SCIP_VAR*` and `SCIP_CONS*`
under the hood, and it releases all references when it is garbage collected
itself (via `finalize`).

When adding a variable (`add_variable`) or a constraint (`add_linear_constraint`),
an integer index is returned. This index can be used to retrieve the `SCIP_VAR*`
or `SCIP_CONS*` pointer via `get_var` and `get_cons` respectively.

### Supported nonlinear operators

Supported operators in nonlinear expressions are as follows:

- unary: `-`, `sqrt`, `exp`, `log`, `abs`, `cos`, `sin`
- binary: `-`, `/`, `^`
- n-ary: `+`, `*`
* `+`
* `-`
* `*`
* `/`
* `^`
* `sqrt`
* `exp`
* `log`
* `abs`
* `cos`
* `sin`

## Errors with nonlinear models

When solving a nonlinear model, you may encounter `Error: no BLAS/LAPACK library loaded!`,
this comes from Ipopt, see the [README](https://github.com/jump-dev/Ipopt.jl/#julia-17)
on Ipopt.jl.