optalcp-cpo

Compatibility layer allowing DOcplex CP models to be solved using the OptalCP solver.

For new projects, use OptalCP's own Python modeling library — it is faster, supports all OptalCP features, and has a cleaner API. This package is for users with existing CP Optimizer models who want to switch to OptalCP without rewriting their code.

This is a fork of IBM DOcplex CP module (docplex.cp), modified to work with OptalCP instead of IBM CP Optimizer. The docplex.mp (mathematical programming) module has been removed.

Prerequisites

• Python 3.11+
• An OptalCP binary package (see Install below)

Install

pip install git+https://github.com/ScheduleOpt/optalcp-cpo.git

This installs the optalcp Python API package automatically. You also need an OptalCP binary package (the solver itself):

• Preview (free, reports objective values but no solution details):

  pip install git+https://github.com/ScheduleOpt/optalcp-py-bin-preview.git
  

• Academic / full: contact OptalCP with your GitHub username. Academic editions are usually free.

Usage

from optalcp_cpo.model import *

model = CpoModel()
x = model.integer_var(0, 10, name="x")
y = model.integer_var(0, 10, name="y")
model.add(x + y <= 15)
model.minimize(x + 2 * y)

result = model.solve(TimeLimit=10)
print("x = {}, y = {}".format(result[x], result[y]))

By default, the model is solved using OptalCP. No code changes are needed compared to the original docplex.cp package — just change your imports from docplex.cp to optalcp_cpo.

Switching between OptalCP and CP Optimizer

This package can use either OptalCP or IBM CP Optimizer as the solver backend. To switch to CP Optimizer, pass agent='local' to solve() (the term "agent" is inherited from the DOcplex architecture):

result = model.solve(agent='local')

Or change the default for all subsequent calls:

from optalcp_cpo.config import context
context.solver.agent = 'local'

See optalcp_cpo/config.py for the full set of configuration options and other ways to customize the configuration (per-project config files, environment variables).

Note: The constants INT_MAX, INT_MIN, INTERVAL_MAX, INTERVAL_MIN have different values depending on the configured solver. They are set at import time based on context.solver.agent:

Constant	OptalCP (default)	CP Optimizer (agent='local')
INT_MAX	1,073,741,823	9,007,199,254,740,991
INTERVAL_MAX	715,827,882	4,503,599,627,370,494

Compatibility notes

Not all DOcplex CP features are supported by OptalCP yet. Here is what to expect:

• Silently ignored features. KPIs, starting points, and solver parameters (except TimeLimit and Workers) are accepted but ignored. The solve log will show warnings for each ignored feature.
• Unsupported model features. If the model uses a feature OptalCP does not support (e.g. floating-point expressions), a runtime error is raised.
• noOverlap with direct transition times. CP Optimizer's noOverlap supports a "direct" mode where transition times are enforced only between direct successors. OptalCP always enforces transition times between all pairs, including indirect successors.

If you are interested in a particular missing feature, feel free to contact OptalCP.

Running examples

The examples/cp/ directory has ready-to-run examples. After installing the package and an OptalCP binary:

python examples/cp/basic/color.py
python examples/cp/visu/flow_shop.py

The visu/ and jupyter/ examples need extra packages:

pip install matplotlib numpy

For Jupyter notebooks, also install jupyter:

pip install jupyter
jupyter notebook examples/cp/jupyter/house_building.ipynb

Example status

The examples/cp/ directory contains examples from the original DOcplex repository. Working examples are in the top-level directories; examples that need features not yet supported by OptalCP are in unsupported/:

examples/cp/
  basic/              ← 4 working Python examples
  visu/               ← 12 working scheduling examples
  jupyter/            ← 2 working notebooks
  unsupported/        ← examples needing features not yet in OptalCP
    basic/            ← 23 Python examples
    visu/             ← 7 scheduling examples
    jupyter/          ← 7 notebooks + full scheduling_tuto

14 of 20 scheduling examples and 2 of 26 non-scheduling examples work. 2 of 9 notebooks work; the scheduling_tuto notebook includes chapters 1–6 (chapter 7 — state functions — is not yet supported).

The main missing features and how many examples they block (many examples need multiple features, so the counts overlap):

Feature	Examples blocked
allDiff	9
pack	7
allowedAssignments	3
blackbox functions	2
non-contiguous domains	2
noOverlap (direct transition times)	2

Performance comparison with CP Optimizer

Most of the working examples are small and solved instantly by both OptalCP and CP Optimizer. On the problems that take measurable time (tested with TimeLimit=30, 4 workers each, solver-reported TotalTime):

Example	Objective	OptalCP	CP Optimizer	Speedup
visu/flow_shop	1125	0.67s	2.92s	4.4x
visu/flow_shop_permutation	1136	0.17s	0.83s	4.9x
visu/rcpsp_multi_mode	40	0.024s	0.17s	7.1x
visu/house_building_optional	360	2.8s (optimal)	30s (feasible)	OptalCP proves optimal
visu/house_building_calendar	638	30s (feasible)	0.03s (optimal)	CPO proves optimal
visu/job_shop_flexible	238 vs 244	30s	30s	OptalCP finds better solution

OptalCP communicates via the CP Optimizer angel protocol (a compatibility layer, not OptalCP's native interface). This adds ~25ms startup overhead per solve() call, which is negligible for real problems but visible when benchmarking toy examples.

License

This library is delivered under the Apache License Version 2.0, January 2004 (see LICENSE.txt).