Skip to content
Switch branches/tags


Failed to load latest commit information.


Build Status Documentation Status

Welcome to the python binding of the Certifiably Optimal RulE ListS (CORELS) algorithm!


CORELS (Certifiably Optimal RulE ListS) is a custom discrete optimization technique for building rule lists over a categorical feature space. Using algorithmic bounds and efficient data structures, our approach produces optimal rule lists on practical problems in seconds.

The CORELS pipeline is simple. Given a dataset matrix of size n_samples x n_features and a labels vector of size n_samples, it will compute a rulelist (similar to a series of if-then statements) to predict the labels with the highest accuracy.

Here's an example: Whoops! The image failed to load

More information about the algorithm can be found here


CORELS uses Python, Numpy, GMP. GMP (GNU Multiple Precision library) is not required, but it is highly recommended, as it improves performance. If it is not installed, CORELS will run slower.


CORELS exists on PyPI, and can be downloaded with pip install corels

To install from this repo, simply run pip install . or python install from the corels/ directory.

Here are some detailed examples of how to install all the dependencies needed, followed by corels itself:


sudo apt install libgmp-dev
pip install corels


# Install g++ and gmp
/usr/bin/ruby -e "$(curl -fsSL"
brew install g++ gmp

pip install corels


Note: Python 2 is currently NOT supported on Windows.

pip install corels


  • If you come across an error saying Python version >=3.5 is required, try running pip install numpy before again running pip install corels.
  • If pip does not successfully install corels, try using pip3


The docs for this package are hosted on here:


After installing corels, run pytest (you may have to install it with pip install pytest first) from the tests/ folder, where the tests are located.


Large dataset, loaded from this file

from corels import *

# Load the dataset
X, y, _, _ = load_from_csv("data/compas.csv")

# Create the model, with 10000 as the maximum number of iterations 
c = CorelsClassifier(n_iter=10000)

# Fit, and score the model on the training set
a =, y).score(X, y)

# Print the model's accuracy on the training set

Toy dataset (See picture example above)

from corels import CorelsClassifier

# ["loud", "samples"] is the most verbose setting possible
C = CorelsClassifier(max_card=2, c=0.0, verbosity=["loud", "samples"])

# 4 samples, 3 features
X = [[1, 0, 1], [0, 0, 0], [1, 1, 0], [0, 1, 0]]
y = [1, 0, 0, 1]
# Feature names
features = ["Mac User", "Likes Pie", "Age < 20"]

# Fit the model, y, features=features, prediction_name="Has a dirty computer")

# Print the resulting rulelist

# Predict on the training set

More examples are in the examples/ directory


Email the maintainer at: