ecole 0.8.1
Extensible Combinatorial Optimization Learning Environments
License: BSD-3-Clause
Requires Python: >=3.6

.. image:: https://raw.githubusercontent.com/ds4dm/ecole/master/docs/_static/images/ecole-logo.svg
   :target: https://www.ecole.ai
   :alt: Ecole logo
   :width: 30 %
   :align: right

Ecole
=====

.. image:: https://github.com/ds4dm/ecole/actions/workflows/continuous-testing.yml/badge.svg
   :target: https://github.com/ds4dm/ecole/actions/workflows/continuous-testing.yml
   :alt: Test and deploy on Github Actions

Ecole (pronounced [ekɔl]) stands for *Extensible Combinatorial Optimization Learning
Environments* and aims to expose a number of control problems arising in combinatorial
optimization solvers as Markov
Decision Processes (*i.e.*, Reinforcement Learning environments).
Rather than trying to predict solutions to combinatorial optimization problems directly, the
philosophy behind Ecole is to work
in cooperation with a state-of-the-art Mixed Integer Linear Programming solver
that acts as a controllable algorithm.

The underlying solver used is `SCIP <https://scip.zib.de/>`_, and the user facing API is
meant to mimic the `OpenAI Gym <https://gym.openai.com/>`_ API (as much as possible).

.. code-block:: python

   import ecole

   env = ecole.environment.Branching(
       reward_function=-1.5 * ecole.reward.LpIterations() ** 2,
       observation_function=ecole.observation.NodeBipartite(),
   )
   instances = ecole.instance.SetCoverGenerator()

   for _ in range(10):
       obs, action_set, reward_offset, done, info = env.reset(next(instances))
       while not done:
           obs, action_set, reward, done, info = env.step(action_set[0])


Documentation
-------------
Consult the `user Documentation <https://doc.ecole.ai>`_ for tutorials, examples, and library reference.

Discussions and help
--------------------
Head to `Github Discussions <https://github.com/ds4dm/ecole/discussions>`_ for interaction with the community: give
and recieve help, discuss intresting envirnoment, rewards function, and instances generators.

Installation
------------
Conda
^^^^^

.. image:: https://img.shields.io/conda/vn/conda-forge/ecole?label=version&logo=conda-forge
   :target: https://anaconda.org/conda-forge/ecole
   :alt: Conda-Forge version
.. image:: https://img.shields.io/conda/pn/conda-forge/ecole?logo=conda-forge
   :target: https://anaconda.org/conda-forge/ecole
   :alt: Conda-Forge platforms

.. code-block:: bash

   conda install -c conda-forge ecole

All dependencies are resolved by conda, no compiler is required.

Pip wheel (binary)
^^^^^^^^^^^^^^^^^^
Currently unavailable.

Pip source
^^^^^^^^^^^
.. image:: https://img.shields.io/pypi/v/ecole?logo=python
   :target: https://pypi.org/project/ecole/
   :alt: PyPI version

Building from source requires:
 - A `C++17 compiler <https://en.cppreference.com/w/cpp/compiler_support>`_,
 - A `SCIP <https://www.scipopt.org/>`__ installation.

.. code-block:: bash

   pip install ecole

Other Options
^^^^^^^^^^^^^
Checkout the `installation instructions <https://doc.ecole.ai/py/en/stable/>`_ in the
documentation for more installation options.

Related Projects
----------------

* `OR-Gym <https://github.com/hubbs5/or-gym>`_ is a gym-like library providing gym-like environments to produce feasible solutions
  directly, without the need for an MILP solver;
* `MIPLearn <https://github.com/ANL-CEEESA/MIPLearn>`_ for learning to configure solvers.

Use It, Cite It
---------------

.. image:: https://img.shields.io/badge/arxiv-2011.06069-red
   :target: https://arxiv.org/abs/2011.06069
   :alt: Ecole publication on Arxiv


If you use Ecole in a scientific publication, please cite the Ecole publication

.. code-block:: text

   @inproceedings{
       prouvost2020ecole,
       title={Ecole: A Gym-like Library for Machine Learning in Combinatorial Optimization Solvers},
       author={Antoine Prouvost and Justin Dumouchelle and Lara Scavuzzo and Maxime Gasse and Didier Ch{\'e}telat and Andrea Lodi},
       booktitle={Learning Meets Combinatorial Algorithms at NeurIPS2020},
       year={2020},
       url={https://openreview.net/forum?id=IVc9hqgibyB}
   }