russcip

[![][imgcrates]][crates] [![][imgdoc]][doc]

[img_crates]: https://img.shields.io/crates/v/russcip.svg

[crates]: https://crates.io/crates/russcip

[img_doc]: https://img.shields.io/badge/rust-documentation-blue.svg

[doc]: https://docs.rs/russcip/

[img_coverage]: https://img.shields.io/codecov/c/github/scipopt/russcip

A safe Rust interface for SCIP. This crate also exposes access to the SCIP's C-API through the ffi module. The project is currently actively developed, issues/pull-requests are very welcome.

russcip is currently compatible with SCIP 10.0.2, which is what the bundled feature ships. Linking against older SCIP versions may work but is not guaranteed and is not supported.

Installation

The easiest way is to run this in your crate directory

cargo add russcip --no-default-features --features bundled

The bundled feature ships prebuilt bindings, so this build needs neither a SCIP installation nor libclang. For other installation methods, please check INSTALL.md.

Usage

We provide multiple examples listed here, and you can also check the documentation.

Accessing unsafe functions

The ffi module provides access to the raw C-API of SCIP. This can be used to call functions that are not wrapped in the safe interface yet. The scip_ptr unsafe function in the Model struct, which gives you access to the underlying SCIP raw pointer. Each other wrapper struct has a similar function named inner, e.g. Variable::inner or Constraint::inner gives you a mut ffi::SCIPVAR or mut ffi::SCIPCONS respectively.

Implementing Custom Plugins

Some of SCIP's plugins are imported to the rust interface as traits. Currently the implemented plugins are:

| Name | File | Docs | |--------------------|---------------------------------------------------------------------------------|---------------------------------------------------------------------------------| | Branching rule | branchrule.rs | docs | | Variable Pricer | pricer.rs | docs | | Event Handler | eventhdlr.rs | docs | | Primal Heuristic | heuristic.rs | docs | | Separator | separator.rs | docs | | Constraint Handler | conshdlr.rs | docs | | Node Selector | nodesel.rs | docs |

To add a custom plugin to a SCIP Model instance, you should implement its trait and call the corresponding include{PLUGINNAME} method. For examples on implementing the specific plugin trait you can check the tests in the corresponding files.

Attaching custom data to SCIP instance

This is enabled with the help of the anymap crate. You can attach any data to the Model instance using the setdata method, and retrieve it using the getdata and getdatamut methods. This is useful for communicating data between plugins, or storing other representations of the variables/constraints in the model.

let mut model = Model::new();
// Some user-defined data struct MyData {     title: String, }
let data = MyData {     title: "My Data".to_string(), };
// Attach the data to the model model.set_data(data);
// Retrieve the data let dataref = model.getdata::<MyData>().unwrap(); asserteq!(dataref.title, "My Data");
// Mutate the data let datamut = model.getdata_mut::<MyData>().unwrap(); datamut.title = "New Title".tostring(); asserteq!(datamut.title, "New Title");

Contributing

Thinking about contributing to russcip? First of all thank you! You can check our issues page, there's a bunch of goodfirstissues, or you can check our contribution guide. If you'd like to contribute and unsure what to do, or thinking about a big feature and want to discuss if it makes sense and what is the best way to do it? you could open a new issue/discussion or send me a quick email @mmghannam.

About SCIP

SCIP is currently one of the fastest non-commercial solvers for mixed integer programming (MIP) and mixed integer nonlinear programming (MINLP). It is also a framework for constraint integer programming and branch-cut-and-price. It allows for total control of the solution process and the access of detailed information down to the guts of the solver.