New Features​

CP Optimizer Compatibility​

The new optalcp-cpo package is a drop-in replacement for IBM CP Optimizer's Python API. Existing DOcplex CP models can run on OptalCP with a single import change:

# Before:
from docplex.cp.model import *

# After:
from optalcp_cpo.model import *

No other code changes are needed. The package translates DOcplex CP models to OptalCP at solve time. In our testing, 14 out of 20 scheduling examples from the DOcplex repository work and run faster on OptalCP. The scheduling tutorial notebook works through 6 out of 7 chapters.

This is the initial release of the compatibility layer. Not all CP Optimizer features are supported yet — see the optalcp-cpo README for the current status. We are actively working on expanding compatibility.

Element Expression​

The new element function creates an integer expression equal to array[subscript], where subscript is a decision variable or expression. It automatically constrains subscript to the valid index range.

In this example, we model a learning effect: the more tasks a worker completes, the faster they get. Each task's duration depends on its position in the processing sequence:

# Learning effect: tasks get faster as the worker gains experience
durations = [50, 40, 33, 28, 25]

tasks = [model.interval_var(length=(25, 50), name=f"Task{i}") for i in range(5)]
seq = model.sequence_var(tasks)
model.no_overlap(seq)

for task in tasks:
    model.enforce(task.length() == model.element(durations, task.position(seq)))

model.minimize(model.max([t.end() for t in tasks]))

// Learning effect: tasks get faster as the worker gains experience
const durations = [50, 40, 33, 28, 25];

const tasks = Array.from({length: 5}, (_, i) =>
    model.intervalVar({ length: [25, 50], name: `Task${i}` }));
const seq = model.sequenceVar({ intervals: tasks });
model.noOverlap(seq);

for (const task of tasks) {
    model.enforce(task.length().eq(model.element(durations, task.position(seq))));
}

model.minimize(model.max(tasks.map(t => t.end())));

API Changes​

Solver.sendSolution is Now Synchronous​

Solver.sendSolution() / Solver.send_solution() is now a synchronous method. It queues the solution for delivery and returns immediately. Remove await from existing calls:

# Before:
await solver.send_solution(solution)

# After:
solver.send_solution(solution)

// Before:
await solver.sendSolution(solution);

// After:
solver.sendSolution(solution);

Solver.onSummary Removed​

The onSummary / on_summary callback and the SolveSummary type have been removed. Use the SolveResult returned by solve() instead — it contains the same fields:

# Before:
def on_summary(summary):
    print(f"Time: {summary.duration:.2f}s")
    print(f"Solutions: {summary.nb_solutions}")
solver.on_summary = on_summary
result = await solver.solve(model)

# After:
result = await solver.solve(model)
print(f"Time: {result.duration:.2f}s")
print(f"Solutions: {result.nb_solutions}")

// Before:
solver.onSummary = (summary) => {
    console.log(`Time: ${summary.duration.toFixed(2)}s`);
    console.log(`Solutions: ${summary.nbSolutions}`);
};
const result = await solver.solve(model);

// After:
const result = await solver.solve(model);
console.log(`Time: ${result.duration.toFixed(2)}s`);
console.log(`Solutions: ${result.nbSolutions}`);

Bug Fixes​

• Position expression reuse: Fixed an issue where using a position() expression in multiple constraints could produce incorrect results.
• Python sub-expression reuse: Fixed a Python API issue where reusing a sub-expression in multiple places caused degraded performance.

On the solver side, we've added automatic configuration through presets, making it easier to get good performance without manual parameter tuning. Decision problems now stop automatically after finding the first solution, eliminating a common source of confusion. Discrete resource constraints now support variable maximum capacity, enabling new classes of capacity planning problems.

Highlights​

New Python API​

OptalCP now has a Python API. The API is designed to be nearly identical to the TypeScript API, making it easy to switch between languages or translate examples.

import optalcp as cp

model = cp.Model()
task = model.interval_var(length=10, name="task")
model.minimize(task.end())

result = model.solve(cp.Parameters(timeLimit=60))
if result.solution:
    print(f"Task ends at {result.solution.get_end(task)}")

Key features:

• Method-based style: model.solve()
• Property accessors: interval.start_min, interval.length_max
• Comparison operators: cumul <= 10 and 5 < x
• Auto-registration of constraints and objectives

TypeScript API Changes​

The TypeScript API has been updated to align with the new Python API. Both APIs now share nearly identical syntax. The main changes are:

• model.constraint() renamed to model.enforce() for clarity
• solve(model, ...) replaced by model.solve()
• Functions merged into overloads: model.cumulPlus() is now just model.plus(), working for both integer and cumulative expressions
• Getter/setter methods replaced with properties
• And many more...

Old functions remain available but are deprecated. See TypeScript API Changes below for the full list.

Automatic Solver Configuration with Presets​

The new preset parameter simplifies solver configuration by setting optimal defaults for multiple parameters at once:

• Auto (default): Automatically selects preset based on problem size
• Default: Balanced configuration with maximum propagation and mixed search strategies
• Large: Optimized for problems with more than 100,000 variables

Variable Capacity for Discrete Resources​

Discrete resource constraints now support variable maximum capacity. Instead of a fixed integer limit, you can specify a decision variable or expression as the capacity bound:

# Variable capacity based on a decision variable
capacity = model.int_var(min=5, max=10, name="capacity")
model.enforce(cumul <= capacity)

// Variable capacity based on a decision variable
let capacity = model.intVar({ min: 5, max: 10, name: "capacity" });
model.enforce(cumul.le(capacity));

This enables modeling scenarios where resource capacity itself is a decision, such as:

• Selecting machine configurations with different capacities
• Optimizing workforce allocation where team size varies
• Capacity planning problems where investment decisions affect limits

Smart Default for Decision Problems​

The solutionLimit parameter now defaults to automatic mode: decision problems (without an objective) stop after finding the first solution, while optimization problems continue searching. This eliminates the common pitfall of forgetting to set solutionLimit=1 for satisfaction problems.

New Features​

Solver​

• Variable resource capacity: Discrete resource constraints now accept decision variables or expressions as capacity bounds
• Preset parameter: One-parameter solver configuration for different problem sizes
• Automatic solution limit: Smart default stops at first solution for decision problems
• Deferred solution values: Performance optimization for large models
• Improved logging: Parameter values now show reasons (preset, auto) and workers are grouped by configuration
• solverArgs parameter: Pass custom command-line arguments to the solver subprocess

TypeScript API Changes (Detail)​

The main goal of these changes is to align the TypeScript and Python APIs, making them nearly identical and easier to use across both languages.

All deprecated functions remain functional but are no longer documented. They will be removed in a future release.

Summary of Changes​

Variable Classes​

Variable properties are now accessed directly as properties instead of through getter/setter methods, making the code more concise and idiomatic.

IntVar​

BoolVar​

IntervalVar​

ModelElement​

Model Class​

Naming and Constraints​

The constraint() method is renamed to enforce() to better convey the intent of adding a constraint to the model.

Interval Accessors​

The Of suffix is removed from interval accessor functions for cleaner syntax.

Cumulative Expressions​

The cumul prefix is removed; these functions are now overloaded with their integer counterparts (e.g., plus() works for both integers and cumulative expressions).

Step Functions​

Step function operations are renamed to use standard mathematical terminology.

CumulExpr Class​

Instance methods mirror the model-level changes, removing the cumul prefix.

IntStepFunction Class​

Instance methods mirror the model-level changes, using standard mathematical names.

Solver Class​

Event Handlers​

Event handlers are now assigned as properties instead of using the on() method.

Result Types​

SolveSummary​

Field names are updated for consistency: lowerBound becomes objectiveBound to reflect that it applies to both minimization and maximization.

SolveResult​

The best prefix is removed from field names for brevity, and lowerBound becomes objectiveBound.

Global Functions​

Standalone functions are moved to class methods for better discoverability and a more object-oriented API.

Parameter Parsing​

The CLI parameter parsing API has been redesigned to use an options object for better flexibility and consistency.

The new functions use an options object:

const params = parseParameters({
  args: process.argv.slice(2),  // default
  defaults: { timeLimit: 60 },  // CLI overrides these
  usage: "Usage: myapp [options]",
  exitOnError: true  // false to throw instead of exit
});

const [params, unknown] = parseKnownParameters({ ... });

The --version flag has been renamed to --optalcpVersion to print solver version information.

Type Aliases (Backward Compatibility)​

These type aliases are preserved for backward compatibility but should be migrated to the new names.

Solver Parameter Changes​

Deprecated (Backward Compatible)​

The LB (lower bound) terminology is replaced with Dual to be consistent with optimization literature.

Breaking Changes (No Backward Compatibility)​

These parameter renames are not backward compatible; old names will cause errors.