cpsat-primer: a book that teaches you to model with Google OR-Tools CP-SAT

Why a primer, and why CP-SAT rather than a MIP solver

The project exists because the choice of solver matters more than most users expect. The primer opens by noting that many combinatorially difficult problems can be solved reasonably well in practice despite proven theoretical hardness, and that the standard approach is Mixed Integer Linear Programming. It names Gurobi, CPLEX, COPT Cardinal Solver and FICO Xpress Optimization as the most successful MIP solvers, all commercial and expensive, though mostly free for academics, and mentions open source solvers such as SCIP and HiGHS as often not as powerful yet.

The argument then turns to the modelling technique rather than the solver brand. Branch and bound and cut on linear relaxations struggle with problems that contain a lot of logical constraints that the solution has to satisfy, and the Constraint Programming approach may then be more successful. Classical CP solvers have open source implementations, but they usually do not scale as well as MIP solvers and are worse at optimizing objective functions: MIP solvers can often handle hundreds of thousands of variables and constraints, while classical CP solvers struggle beyond a few thousand. CP-SAT, described as relatively new within Google's OR-Tools suite, is presented as overcoming many of those weaknesses and being competitive for many problems.

The audience is stated plainly in the content section: MIP community members seeking alternatives, and people for whom CP-SAT is the first optimization solver they have used.

A book, a site, and a notebook repository in one tree

The repository layout shows a book project rather than a software package. There is a `chapters/` directory holding the text, a `.mdbook/` directory for the mdBook configuration that renders the site, `images/` for figures, `manuscripts/` for paper versions, and a `.scripts/` directory with the build tooling. The README itself carries a generated-file warning: it was produced by the `.scripts/build.py` script and should not be edited manually, and each section is marked with a comment pointing back to the source markdown file such as `intro.md`.

Alongside the book are the things that make it teachable. `examples/` holds runnable code: notebooks such as `add_all_different.ipynb`, `add_no_overlap_2d.ipynb`, `patterns_multi_objective.ipynb` and `scheduling_multi_resources.ipynb`, Python scripts such as `add_circuit.py`, `add_circuit_budget.py`, `add_circuit_multi_tour.py`, `add_no_overlap_scheduling.py` and `add_reservoir.ipynb`, plus directories for `a_b_comparison/`, `cvrp/`, `embedding_cpsat/`, `optimization_api/` and `tdd/`.

There is also `evaluations/`, `tests/`, `CITATION.cff` for citation metadata, CONTRIBUTING.md, a `.pre-commit-config.yaml`, and a LICENSE file. The published book version is available at d-krupke.github.io/cpsat-primer, and the author is Dominik Krupke of TU Braunschweig, with contributions from Leon Lan, Michael Perk and others.

The structure of the content is two parts. The first introduces the fundamentals of CP-SAT and demonstrates its features, starting with a chapter on installation that covers setup and hardware requirements, then a simple example explained with the mathematical notation and its approximation in Python using overloaded operators, then basic modeling of variables, objectives and fundamental constraints, then advanced modeling of complex constraints such as circuit constraints and intervals. The second part covers building and deploying optimization algorithms with CP-SAT.

The knapsack example shows the whole modelling loop

The primer opens its demonstration with the NP-hard Knapsack Problem: selecting a subset of items with given weights and values to maximise total value without exceeding a weight limit. The scaling argument is part of the teaching: 100 items yield roughly 2^100, about 10^30, candidate solutions, which even at 10^18 operations per second on a supercomputer would take more than 31,000 years to enumerate.

The example installs the solver inline, with the package name in a comment on the import line:

from ortools.sat.python import cp_model  # pip install -U ortools

The instance data is given as parallel lists of 100 weights and 100 values, with a capacity of 2000. The modelling part is where the API pattern becomes visible, and it is short enough to read in full:

# Now we solve the problem
model = cp_model.CpModel()
xs = [model.new_bool_var(f"x_{i}") for i in range(len(weights))]

accumulated_weight = sum(x * w for x, w in zip(xs, weights))
model.add(accumulated_weight <= capacity)
accumulated_value = sum(x * v for x, v in zip(xs, values))
model.maximize(accumulated_value)

solver = cp_model.CpSolver()
solver.solve(model)

print("Optimal selection:", [i for i, x in enumerate(xs) if solver.value(x)])
print("Total packed value:", solver.objective_value)

The structure worth noticing is that the Python operator overloading does the modelling work. A sum of products of boolean variables and weights is not valid Python arithmetic on its own, but the CP-SAT model objects intercept it and turn it into a linear constraint, which is why `model.add(accumulated_weight <= capacity)` reads like ordinary Python.

The published output for this instance lists 19 selected indices and a total packed value of 1161.0, and the author reports that CP-SAT found the provably best solution in 0.01 seconds on his machine. The point being made is not the timing but the method: CP-SAT does not evaluate all solutions, it uses deduction and pruning on the search space.

Why the repository ships examples rather than a library

There is no package to install from this repository, no exported API and no release tags. The top level carries no package manifest of the sort a Python library would have; instead the deliverable is the book, the website built from it, and the example files.

That design has consequences for how you use it. The examples are the curriculum, and they are meant to be read and run rather than imported. The `tdd/` directory and `evaluations/` directory suggest that the project treats the example code as something that is tested and measured, not just illustrative, and the presence of `.pre-commit-config.yaml` indicates the code is kept formatted by automated checks.

For a reader, the difference from an official tutorial is that the examples go past the happy path. Directory names such as `a_b_comparison/`, `embedding_cpsat/`, `optimization_api/`, `cvrp/` and `lns_knapsack.ipynb` point at topics that are about how to use the solver well rather than what its API calls are. The `lns_knapsack.ipynb` file with a companion `lns_knapsack_full_output.ipynb` is a good example of the format: the small notebook holds the exercise and the full-output notebook holds the verbose run for comparison.

If you are after a quick answer about a single CP-SAT API, the primer is the wrong shape. If you are trying to build intuition about why CP-SAT beats a MIP solver on your problem, or you want worked examples of constraint patterns, it is the right one.

The licence lets you reuse the material outright

The repository is published under CC-BY-4.0, which is a different kind of licence from the code licences most developers encounter. It applies to the written content rather than to a software package, and its practical effect is permissive with one obligation: attribution.

For a lecturer, a team writing internal documentation, or a company that wants to run a reading group, that means the chapters can be copied, translated or adapted as long as the author is credited. The CITATION.cff file at the repository root exists to support exactly that, giving the citation metadata a reading group can reference.

The written text is also licensed separately from any code it contains, since the examples depend on Google OR-Tools as an external package. Anyone lifting an example into a production codebase is taking a dependency on OR-Tools and inherits that dependency's licensing and support situation, which is a different conversation from reusing the prose.

One consequence of a book project is worth noting for an evaluation: there are no GitHub releases, so there is no versioned artifact to pin. The repository is not archived and the last push was on 2026-09-06, so the text does change, and a fork used as course content will need to track the main branch or freeze its own copy.

Where a primer is not enough

The strongest thing this project can do is explain the modelling mindset. It cannot decide your objective function, and it cannot tell you whether CP-SAT is the right solver for your instance. The primer itself frames CP-SAT as competitive for many problems and sometimes superior, which is a claim about a class of problems rather than a guarantee about yours.

The evidence offered for CP-SAT's capability in the visible portion of the documentation is a single 100-item knapsack solved in 0.01 seconds on the author's machine. That is a demonstration of the technique, not a benchmark across problem classes, and the repository does not publish a comparison table of solver performance in the files shown here. Anyone citing the primer as evidence that CP-SAT will beat their MIP solver on a scheduling problem with 50,000 variables should test that directly instead.

There is a second practical limit. The code in the primer is Python, and the primer says the mathematical notation is approximated in Python with overloaded operators. Teams whose production stack is in another language, or who use the C++ API of OR-Tools for performance reasons, will need to translate the patterns themselves.

For those who want the reference documentation instead, the docs of Google OR-Tools and the CP-SAT solver page are the authoritative sources, and the primer links to them. The value added here is the narrative path from a problem to a model.

Editorial conclusion

Adopt cpsat-primer if you are a MIP user hitting the wall of logical constraints, or a Python developer who needs to learn CP-SAT from working code rather than from an API reference. Do not treat it as a solver to deploy: the solver is Google OR-Tools, and this repository only teaches it. Verify first that the examples run against the OR-Tools version you intend to ship, since the primer is written as a living document with no tagged releases, and the last push was on 2026-09-06.

Frequently asked questions

Official sources

1. d-krupke/cpsat-primer on GitHub
2. Issues
3. License: CC-BY-4.0
4. Project website
5. README