Install the Python SDK and adapters#
Until the 3.0.0 stable release, both the Book and API Reference describe main. You can install either the latest published prerelease or the source on main.
Installation |
Choose it when |
|---|---|
Latest prerelease |
You want to start with published packages. A compatible wheel avoids building the SDK locally. |
|
You need changes that have not been released yet, or want to work from the same source as the current documentation. |
A prerelease can lag behind the documentation. If a documented API is not yet available in your installed release, use main. Start with the SDK and add an adapter when you need a solver.
Install uv. These instructions use Python 3.12, which uv can install if needed.
1. Install the Python SDK#
Latest prerelease#
Create a working project outside the OMMX repository:
uv init --bare --python 3.12 ommx-work
cd ommx-work
uv add --python 3.12 --prerelease=allow ommx
This selects the latest compatible published version, including prereleases, and records the dependencies in pyproject.toml and uv.lock. Run subsequent commands for this route from ommx-work.
main#
Also install Git, the stable Rust toolchain, and your operating system’s C/C++ build tools. This route builds the SDK’s Rust extension from source.
git clone --branch main https://github.com/Jij-Inc/ommx.git
cd ommx
uv sync --locked --package ommx --no-default-groups --python 3.12
Run subsequent commands for this route from the checkout root. uv installs the checked-out SDK with the dependencies recorded in the repository’s uv.lock. Add adapters from this same checkout.
Check the environment#
Both routes create a .venv. From the directory for your chosen route, run:
uv run --no-sync python -c "from importlib.metadata import version; from ommx import Instance; print(version('ommx')); print(Instance.minimize())"
To run an example saved as a script, use uv run --no-sync python example.py. Transforming a problem with prepare(), checking InstanceClass membership, and evaluating a candidate as a Solution require only the SDK. Downloading public problems from MIPLIB or QPLIB requires network access on the first retrieval.
2. Add an adapter when you need a solver#
Use the commands for the same installation route as your SDK. For prereleases, uv add resolves the SDK and adapters together in your working project. For main, --inexact keeps other adapters and Notebook packages you have already added.
PySCIPOpt Adapter#
Latest prerelease:
uv add --prerelease=allow ommx-pyscipopt-adapter
main:
uv sync --locked --package ommx-pyscipopt-adapter --no-default-groups --inexact
The OMMXPySCIPOptAdapter Reference contains complete examples of a knapsack model and result analysis, native special constraints, and explicit preparation followed by solving.
HiGHS Adapter#
Latest prerelease:
uv add --prerelease=allow ommx-highs-adapter
main:
uv sync --locked --package ommx-highs-adapter --no-default-groups --inexact
The OMMXHighsAdapter Reference includes a complete example of preparing special constraints and solving the resulting model. It constructs its own input and needs only HiGHS and the SDK. To run the Adapter comparison example, install both HiGHS and PySCIPOpt, then add matplotlib as described below.
OpenJij Adapter#
Latest prerelease:
uv add --prerelease=allow ommx-openjij-adapter
main:
uv sync --locked --package ommx-openjij-adapter --no-default-groups --inexact
This also installs OpenJij itself. Other adapters and solver license setup are unnecessary. The OMMXOpenJijSAAdapter Reference contains a small example from choosing penalty weights to selecting a returned candidate. The optional TSP Notebook uses matplotlib to draw routes.
3. Add Notebook and plotting tools when needed#
For the prerelease project, record additional tools as dependencies:
uv add ipykernel
For the main checkout, add them to its environment:
uv pip install ipykernel
In a Jupyter-capable editor, select your chosen directory’s .venv as the kernel. To register it with an existing Jupyter environment, run the following and select “OMMX Book” in the Notebook:
uv run --no-sync python -m ipykernel install --user --name ommx-book --display-name "OMMX Book"
For plotting, use uv add matplotlib in the prerelease project or uv pip install matplotlib in the main checkout.
Update the environment#
For the latest prerelease, update the SDK and all adapters recorded in the project together:
uv sync --upgrade --prerelease=allow
For main:
git pull --ff-only
uv sync --locked --package ommx --no-default-groups --inexact
Repeat the main installation commands for the adapters you use so that they match the SDK checkout. Restart active Notebook kernels after updating either environment.
Optional: manage Artifacts with the CLI#
The SDK includes the OMMX CLI. From either environment, run:
uv run --no-sync ommx --version
uv run --no-sync ommx --help
To install only the CLI without the Python SDK, get the main source as above and build it with Rust from the checkout root:
cargo install --locked --path rust/ommx --features cli
ommx --version
ommx --help
The CLI reports the Rust SDK version. Rust and Python SDK versions are managed independently.