Getting Started#
What you can do#
Quantagonia’s HybridSolver is a cloud-based mathematical optimization solver that utilizes CPUs, GPUs, and QPUs. It allows to solve several classes of challenging optimization problems. Among others, you can tackle mixed-integer linear problems (MILPs) and quadratic unconstrained binary optimization (QUBO) problems. Depending on the settings, the solver uses classic and hybrid branch-and-cut and novel classic-quantum decomposition approaches.
The package can be used in two ways:
A lightweight command-line interface (CLI) allows you to submit optimization tasks and track their progress from the command line.
A Python API lets you call the HybridSolver directly from your Python codebase.
This guide covers the first steps to use both the CLI and the API of the HybridSolver.
Setup#
The HybridSolver CLI and API client are available as a Python package on PyPI. Note that Python >= 3.8, < 3.12 is required.
Simply pip install the package, preferably inside a virtual environment:
pip install quantagonia
Note
If you want to model QUBOs with the quantagonia package you have to install the extra qubo, i.e., by running
pip install quantagonia[qubo].
Set up authentication for the Quantagonia Cloud to be able to submit compute jobs to the cloud-based solver. If you don’t have an API key yet, sign up for a free plan at platform.quantagonia.com and store it in an environment variable:
export QUANTAGONIA_API_KEY=<YOUR_API_KEY> #for windows users: set QUANTAGONIA_API_KEY=<YOUR_API_KEY>
Command-Line Interface#
The command-line interface (CLI) allows you to submit and monitor optimization problems seamlessly and with minimal setup effort. If you followed the steps above, a hybridsolver binary is available in your path. The binary accepts several commands, e.g., to submit, monitor, or cancel an optimization task.
For a practical example, let’s say you have a mixed-integer linear optimization problem stored in MPS format in the file my_problem.mps. You can easily submit this problem to the cloud-based HybridSolver by making a simple call
hybridsolver submit my_problem.mps
which gives an output similar to:
✅ Submitted job with ID: 29870456-8837-4434-9e6b-1f68e38e2d7c
You can use the given ID to monitor the progress of the solver as follows:
hybridsolver monitor 29870456-8837-4434-9e6b-1f68e38e2d7c
This streams the solver’s progress to the console in real-time. If the log indicates that the problem has been solved successfully, the command
hybridsolver solution 29870456-8837-4434-9e6b-1f68e38e2d7c
retrieves and prints the optimal solution vector to the console. Note that there is also a solve command, which combines the submit and monitor commands and, hence, immediately streams the solver output after submitting the job.
Python API Client#
Instead of using the CLI, you can also call the HybridSolver within Python by importing the quantagonia package. This requires that you have followed the setup steps above. Then, set up a connection to the HybridSolver:
from quantagonia import HybridSolver, HybridSolverParameters
api_key = "QUANTAGONIA_API_KEY"
hybrid_solver = HybridSolver(api_key)
To solve an MPS file, setup solver parameters and use the solve method:
# choose input file
import os
input_file_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "data", "example.mps")
# setup parameters
params = HybridSolverParameters()
params.set_time_limit(180)
# solve problem
res_dict, _ = hybrid_solver.solve(input_file_path, params)
On successful execution, the process returns a dictionary containing the results:
# display information and solution values
print("Runtime:", res_dict["timing"])
print("Objective:", res_dict["objective"])
print("Bound:", res_dict["bound"])
print("Solution values:")
for idx, val in res_dict["solution"].items():
print(f"\t{idx}: {val}")
Latest Changes#
0.10.0 — 2025-01-21#
Added#
Allow passing additional description files
0.9.2 — 2025-01-14#
Fixed#
Improved add and sub operations for variables
0.9.1 — 2024-12-26#
Fixed#
Improved parameter setting of modeling APIs
0.9.0 — 2024-12-11#
Added#
Implemented parameter setters and getters
Changed#
Removed release notes prompt
0.8.0 — 2024-11-28#
Added#
Added performance_code parameter
Fixed#
Fixed regex for parsing of best node and time
Changed#
Refactored model wrappers and updated documentation
0.7.0 — 2024-11-21#
Added#
Refactored the model class into separate wrapper classes
Fixed#
Fixed default name of the model
Fixed bug in pulp adapter when infeasibility
0.6.1 — 2024-11-13#
Fixed#
Fixed bug in get_variables() in model Class
Fixed documentation for solve, submit, and list arguments
0.6.0 — 2024-11-13#
Added#
Updated MIP model documentation after mimicking cplex and gurobipy
Implemented mimic of gurobi
Changed#
Added IDE files to gitignore
0.5.0 — 2024-10-29#
Added#
Added MIP modeling layer
Updated client with V2 API Endpoints
Changed#
Clustered file formats, examples and notebooks
Improved documentation organization and structure
0.4.0 — 2024-10-22#
Changed#
Updated publish script
Removed unmeaningful test
0.3.1 — 2024-10-17#
No significant changes documented
0.3.0 — 2024-10-01#
Fixed#
Client side compression of problem files over 10 MB
0.2.2 — 2024-09-23#
No significant changes documented
0.2.1 — 2024-08-20#
Fixed#
Re-enabled env variable for backend environments
0.2.0 — 2024-08-12#
Added#
Added LP and MPS file format documentation
Added feasibility and integrality tolerance parameters
Added client version number forwarding
Fixed#
Fixed bug when BQM models are imported
Re-evaluated and refined the QUBO file reader
Fixed client side compression of problem files over 10 MB
Replaced DB version check with PyPI check
Changed#
Removed internal servers from client
Removed deprecated example with multiple QUBOs in one file
0.1.11 — 2024-08-05#
Added#
Added styling to output
Added origin field to job submission
Changed#
Improved API client package building with a modern package builder
Added automatic versioning to API client
Fixed#
Made log parser more general and removed unused methods
[Earlier versions not converted to maintain changelog brevity]