Metadata-Version: 2.5
Name: veloxq_sdk
Version: 1.0.0rc1
Project-URL: Homepage, https://github.com/quantumz-io/veloxq_sdk
Project-URL: source_archive, https://github.com/quantumz-io/veloxq_sdk/archive/5da2dfdbd88764ac91f779eaeb605b8a3b1cba1b.zip
Author-email: Hendrik D Louzada <hendriklouzada@qmz.ai>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Requires-Dist: dimod>=0.12.0
Requires-Dist: h5py>=3.11.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: traitlets>=5.0.0
Requires-Dist: websockets>=13.0.0
Requires-Dist: yarl>=1.15.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# VeloxQ SDK: README

This project provides a configurable Python API to interact with the VeloxQ platform, designed to provide users with a **powerful**, **robust** and **user-friendly** interface to upload and solve complex
optimization problems using an extensive list of physics-inspired and metaheuristic algorithms.

Find additional guides on configuration, jobs, solvers and result files in the [VeloxQ SDK Wiki](https://github.com/quantumz-io/veloxq_sdk/wiki).

---

## Installation & Setup

Install the VeloxQ API client as part of your Python environment. Ensure you have Python 3.9+:

```shell
pip install git+https://github.com/quantumz-io/veloxq_sdk.git
```

> **NOTE:** It is recomended to install this package in a dedicated python environment to prevent any dependency problems.

---

## Quickstart

Before executing any code from the API make sure that you have a proper **API key** configured. The easiest way to load the api key is using the environment variables:

```shell
export VELOX_TOKEN="12345678-90ab-cdef-1234-567890abcdef"
```

Then to solve your problem, the simplest approach is using `solver.sample(...)`, which:

1. Creates a `File` (see below) for your problem instance (biases and couplings defined as lists, NumPy arrays, dictionaries, file paths, etc.).
2. Automatically submits a job to the VeloxQ platform.
3. Waits until completion.
4. Returns the job result.

It accepts the same argument types as `File.from_instance`.

**Examples:**

**Submitting biases and couplings defined in memory:**

- **Using lists:**

  ```python
  from veloxq_sdk import VeloxQSolver

  solver = VeloxQSolver()

  biases = [1, -1, 0]
  couplings = [
      [0, -1, 0],
      [-1, 0, -1],
      [0, -1, 0]
  ]

  result = solver.sample(biases, couplings)  # Returns VeloxSampleSet object
  print(result)
  ```

- **Using NumPy arrays:**

  ```python
  import numpy as np
  from veloxq_sdk import VeloxQSolver

  solver = VeloxQSolver()

  biases = np.array([1, -1, 0])
  couplings = np.array([
      [0, -1, 0],
      [-1, 0, -1],
      [0, -1, 0]
  ])

  result = solver.sample(biases, couplings)
  print(result.first)  # get lowest energy/state
  ```

- **Using dictionaries (sparse data):**

  ```python
  from veloxq_sdk import VeloxQSolver

  solver = VeloxQSolver()

  biases = {0: 1.0, 2: -1.0}
  couplings = {(0, 1): -1.0, (1, 2): 0.5}

  result = solver.sample(biases=biases, couplings=couplings)
  print(result.energy)  # print energies
  ```

- **Using `dimod.BinaryQuadraticModel`**
  
  ```python
  import dimod
  from veloxq_sdk import VeloxQSolver

  bqm = dimod.BinaryQuadraticModel({0: 1.0, 2: -1.0}, {(0, 1): -1.0, (1, 2): 0.5}, 0, dimod.SPIN)
  solver = VeloxQSolver()
  result = solver.sample(bqm)
  print(result.sample)  # print all found states
  ```

**Submitting a problem defined in a file:**

```python
from veloxq_sdk import VeloxQSolver

solver = VeloxQSolver()

result = solver.sample("ising_model.h5")
print(result)
```

**Submitting an instance in dictionary format:**

```python
from veloxq_sdk import VeloxQSolver

solver = VeloxQSolver()

instance_data = {
    "biases": [1, -1],
    "couplings": [[0, -1], [-1, 0]]
}

result = solver.sample(instance_data)
print(result)
```
