# python-quanfluence-sdk
Quanfluence Developer Kit for Python
Learn how to solve complex problems with Quanfluence using Python.
## Table of Contents
1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Authentication](#authentication)
4. [Device Management](#device-management)
- [Creating a Device](#creating-a-device)
- [Retrieving Device Information](#retrieving-device-information)
- [Updating Device Parameters](#updating-device-parameters)
5. [Executing QUBOs](#executing-qubos)
6. [Complete Workflow Example](#complete-workflow-example)
7. [Troubleshooting](#troubleshooting)
8. [Examples](#examples)
9. [Feedback](#feedback)
## Introduction
The Quanfluence SDK provides a Python interface for accessing Quanfluence's Coherent Ising Machine. This SDK allows you to create and manage virtual devices, define Quadratic Unconstrained Binary Optimization (QUBO) problems, and execute these problems on Quanfluence's hardware.
## Installation
To install the Quanfluence SDK:
```bash
pip install quanfluence-sdk
```
## Authentication
Before using the SDK, you need to authenticate with your Quanfluence account credentials:
```python
from quanfluence_sdk import QuanfluenceClient
# Initialize the client
client = QuanfluenceClient()
# Authenticate with your credentials
response = client.signin("your_username", "your_password")
# The client will automatically store your access token for subsequent API calls
```
> Initialising the client and authentication is required everytime you run a script that uses the SDK to make API calls.
## Device Management
### Creating a Device
Quanfluence allows you to create virtual devices with specific configurations for solving your optimization problems. The following function creates a device. Always set device 'type', 'private_ipv4_address', and 'public_ipv4_address' to the values shown below. You can tweak the paramter values for better results for your problem. Once set, the values remain same until changed using the 'update_device()' function.
```python
# Create a basic local device
device = client.create_device(
title="Device 1",
description="A device for testing QUBO problems",
type="aws", # Always set to this default value
iters=10000, # Number of iterations
runs=5, # Number of runs per problem
alpha=2.0, # Alpha parameter
beta=0.333, # Beta parameter
beta_decay=0.1, # Beta decay rate
noise_stdev=0.0, # Standard deviation of noise
runtime=0, # Default value
trials=1 # Number of trials
'private_ipv4_address': 'http://172.31.12.198:5050'
'public_ipv4_address': ''
)
print(f"Created device with ID: {device['id']}")
```
> Remember the device ID as it is needed for all the API calls to the device. Ideally you will be assigned with a preconfigured device ID from Quanfluence and won't need to create a device.
### Retrieving Device Information
To get information about an existing device:
```python
# Replace with your actual device ID
device_id = YOUR_ID
device_info = client.get_device(device_id)
print(device_info)
```
> This will return the existing paramters values and device details for the device ID.
### Updating Device Parameters
You can update device parameters to optimize performance for specific problems. Once updated using this function, the parameter values remain the same until updated again.
```python
# Update device parameters
updated_device = client.update_device(device_id, {
"alpha": 2.0,
"beta": 1.5,
"iters": 200,
"runs": 10
})
print(f"Updated device: {updated_device}")
```
> Consider decreasing or increasing the number iterations to optimise between time taken and quality of results.
## Executing QUBOs
There are multiple ways to execute a QUBO on a Quanfluence device:
### Method 1: Direct QUBO Execution
The QUBO should always be in a python dictionary format with keys indicating spin number using consecutive integers starting from 0 as shown in the example below:
```python
# Execute QUBO directly on the device
Q = [[0, 0, 1], [0, 1, -1], [1, 1, 2]]
result = client.execute_device_qubo_input(device_id, QUBO)
print("Optimization result:", result)
```
### Method 2: Upload and Execute a QUBO File
In case of large problems, a QUBO file can be uploaded to the server and run multiple times without having to send the large problem to the server everytime. The file can be uploaded using the function shown below to obtain the file ID from the server. Use the file ID recieved to execute the file subsequently.
```python
# First, upload a QUBO file to the device
response = client.upload_device_qubo(device_id, "path/to/your/qubo_file.qubo") # Remember the file_name
print("Uploaded filename", response['result'])
# Then execute the uploaded file
execution_result = client.execute_device_qubo_file(device_id, file_name) # Pass the file_name obtained to execute it
print("Execution result:", execution_result)
```
> The QUBO file should be in serialised coordinate (COO) format and have a '.qubo' extension. Refer the [Example QUBO file](https://github.com/quanfluence/python-quanfluence-sdk/tree/main/example_qubo) for the format.
### Method 3: Jobs - Asynchronous QUBO Execution
For large-scale optimization problems that require significant computational time, Quanfluence provides an asynchronous job execution system. This method allows you to submit QUBO problems as background jobs and monitor their progress without blocking your application.
**When to use this method:**
- Large QUBO problems that may take several minutes to hours to complete
- When you need to submit multiple problems simultaneously
- Applications requiring non-blocking execution
- Batch processing scenarios
**Workflow:**
1. **Upload QUBO File**: First, upload your QUBO file to the device (same as Method 2)
2. **Create Job**: Submit the uploaded file for asynchronous execution
3. **Monitor Progress**: Poll the job status to track execution progress
4. **Retrieve Results**: Get the final results once the job completes
```python
# Step 1: Upload a QUBO file to the device (if not already uploaded)
response = client.upload_device_qubo(device_id, "path/to/your/large_problem.qubo")
file_name = response['result']
print(f"Uploaded file: {file_name}")
# Step 2: Create an asynchronous job
job_response = client.create_job(device_id, file_name)
job_id = job_response['id']
print(f"Created job with ID: {job_id}")
# Step 3: Get job progress & result
execution_result = client.get_job(job_id) # Pass the job_id obtained to execute it
print("Job Status & Execution result:", execution_result)
```
**Job Status Values (AWS Batch):**
- `SUBMITTED`: Job has been submitted to the queue
- `PENDING`: Job is waiting for resources to become available
- `RUNNABLE`: Job is ready to run but waiting for compute resources
- `STARTING`: Job is being prepared for execution
- `RUNNING`: Job is currently being executed on the compute resources
- `SUCCEEDED`: Job completed successfully with results available
- `FAILED`: Job encountered an error and failed to complete
- `CANCELLED`: Job was cancelled before execution
## Complete Workflow Example
Here's a complete example of using the Quanfluence SDK to solve a simple QUBO problem:
```python
import dimod
from quanfluence_sdk import QuanfluenceClient
# Initialize and authenticate
client = QuanfluenceClient()
client.signin("your_username", "your_password")
# Use an existing device
device_id = DEVICE_ID # Replace with your actual device ID
# Define a QUBO problem
# This example minimizes: x₀ - x₀x₁ + 2x₁
Q = [[0, 0, 1], [0, 1, -1], [1, 1, 2]]
# Optimize device parameters for this problem
device = client.update_device(device_id, {
"alpha": 2.0,
"beta": 0.333,
"beta_decay": 0.1,
"iters": 1000
})
# Execute the QUBO
result = client.execute_device_qubo_input(device_id, Q)
print("Optimization result:", result)
# Print the solution
if "solution" in result:
print("Solution variables:", result["solution"])
print("Solution energy:", result["energy"])
```
## Troubleshooting
### Limitations
The current supported BQM on the Ising machine has the following limitations:
1. The nodes in the BQM (QUBO or Ising models) should always be indexed from 0 to N-1 where N is the number of nodes.
2. Disconnected nodes with 0 self-weight are not allowed.
3. The values in QUBO passed in dictionary format should always be 32 - bit floating point numbers.
### Common Issues
1. **Authentication Errors**: Make sure your username and password are correct.
2. **Missing Access Token**: If you see a "Access token is missing" error, ensure you're calling `signin()` before making other API calls.
3. **QUBO Format Issues**: Ensure your QUBO is formatted as a dictionary where keys are tuples of indices and values are floating-point numbers.
## Examples
- [Examples](https://github.com/quanfluence/python-quanfluence-sdk/tree/main/examples) - explore our examples docs and learn more about using sdk.
### Feedback
---
If you get stuck, we’re here to help. The following are the best ways to get assistance working through your issue:
Use our [GitHub Issue Tracker][gh-issues] for reporting bugs or requesting features.
Visit the [Quanfluence Community][quanfluence-community] for getting help using Quanfluence Developer Kit for Python or just generally bond with your fellow Quanfluence developers.
<!-- Markdown links -->
Raw data
{
"_id": null,
"home_page": "https://github.com/quanfluence/python-quanfluence-sdk",
"name": "quanfluence-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6.0",
"maintainer_email": null,
"keywords": "quanfluence, quanfluence-api, web-api, sdk, rest-api-client",
"author": "Quanfluence SDK",
"author_email": "sdk@quanfluence.com",
"download_url": "https://files.pythonhosted.org/packages/bd/61/af6cccbec2b3fa06e048192f226cf9eeb442b188f91d67c44d53dfd5d124/quanfluence_sdk-0.0.7.tar.gz",
"platform": null,
"description": "# python-quanfluence-sdk\nQuanfluence Developer Kit for Python\nLearn how to solve complex problems with Quanfluence using Python.\n\n## Table of Contents\n1. [Introduction](#introduction)\n2. [Installation](#installation)\n3. [Authentication](#authentication)\n4. [Device Management](#device-management)\n - [Creating a Device](#creating-a-device)\n - [Retrieving Device Information](#retrieving-device-information)\n - [Updating Device Parameters](#updating-device-parameters)\n5. [Executing QUBOs](#executing-qubos)\n6. [Complete Workflow Example](#complete-workflow-example)\n7. [Troubleshooting](#troubleshooting)\n8. [Examples](#examples)\n9. [Feedback](#feedback)\n\n## Introduction\n\nThe Quanfluence SDK provides a Python interface for accessing Quanfluence's Coherent Ising Machine. This SDK allows you to create and manage virtual devices, define Quadratic Unconstrained Binary Optimization (QUBO) problems, and execute these problems on Quanfluence's hardware.\n\n## Installation\n\nTo install the Quanfluence SDK:\n\n```bash\npip install quanfluence-sdk\n```\n\n## Authentication\n\nBefore using the SDK, you need to authenticate with your Quanfluence account credentials:\n\n```python\nfrom quanfluence_sdk import QuanfluenceClient\n\n# Initialize the client\nclient = QuanfluenceClient()\n\n# Authenticate with your credentials\nresponse = client.signin(\"your_username\", \"your_password\")\n\n# The client will automatically store your access token for subsequent API calls\n```\n\n> Initialising the client and authentication is required everytime you run a script that uses the SDK to make API calls.\n\n## Device Management\n\n### Creating a Device\n\nQuanfluence allows you to create virtual devices with specific configurations for solving your optimization problems. The following function creates a device. Always set device 'type', 'private_ipv4_address', and 'public_ipv4_address' to the values shown below. You can tweak the paramter values for better results for your problem. Once set, the values remain same until changed using the 'update_device()' function. \n\n```python\n# Create a basic local device\ndevice = client.create_device(\n title=\"Device 1\",\n description=\"A device for testing QUBO problems\",\n type=\"aws\", # Always set to this default value\n iters=10000, # Number of iterations\n runs=5, # Number of runs per problem\n alpha=2.0, # Alpha parameter\n beta=0.333, # Beta parameter\n beta_decay=0.1, # Beta decay rate\n noise_stdev=0.0, # Standard deviation of noise\n runtime=0, # Default value\n trials=1 # Number of trials\n 'private_ipv4_address': 'http://172.31.12.198:5050'\n 'public_ipv4_address': ''\n)\n\nprint(f\"Created device with ID: {device['id']}\")\n```\n\n> Remember the device ID as it is needed for all the API calls to the device. Ideally you will be assigned with a preconfigured device ID from Quanfluence and won't need to create a device. \n\n### Retrieving Device Information\n\nTo get information about an existing device:\n\n```python\n# Replace with your actual device ID\ndevice_id = YOUR_ID\ndevice_info = client.get_device(device_id)\nprint(device_info)\n```\n\n> This will return the existing paramters values and device details for the device ID.\n\n### Updating Device Parameters\n\nYou can update device parameters to optimize performance for specific problems. Once updated using this function, the parameter values remain the same until updated again.\n\n```python\n# Update device parameters\nupdated_device = client.update_device(device_id, {\n \"alpha\": 2.0,\n \"beta\": 1.5,\n \"iters\": 200,\n \"runs\": 10\n})\nprint(f\"Updated device: {updated_device}\")\n```\n> Consider decreasing or increasing the number iterations to optimise between time taken and quality of results.\n\n## Executing QUBOs\n\nThere are multiple ways to execute a QUBO on a Quanfluence device:\n\n### Method 1: Direct QUBO Execution\n\nThe QUBO should always be in a python dictionary format with keys indicating spin number using consecutive integers starting from 0 as shown in the example below: \n\n```python\n# Execute QUBO directly on the device\nQ = [[0, 0, 1], [0, 1, -1], [1, 1, 2]]\nresult = client.execute_device_qubo_input(device_id, QUBO)\nprint(\"Optimization result:\", result)\n```\n\n### Method 2: Upload and Execute a QUBO File\n\nIn case of large problems, a QUBO file can be uploaded to the server and run multiple times without having to send the large problem to the server everytime. The file can be uploaded using the function shown below to obtain the file ID from the server. Use the file ID recieved to execute the file subsequently.\n\n```python\n# First, upload a QUBO file to the device\nresponse = client.upload_device_qubo(device_id, \"path/to/your/qubo_file.qubo\") # Remember the file_name\nprint(\"Uploaded filename\", response['result'])\n\n# Then execute the uploaded file\n\nexecution_result = client.execute_device_qubo_file(device_id, file_name) # Pass the file_name obtained to execute it\nprint(\"Execution result:\", execution_result)\n```\n> The QUBO file should be in serialised coordinate (COO) format and have a '.qubo' extension. Refer the [Example QUBO file](https://github.com/quanfluence/python-quanfluence-sdk/tree/main/example_qubo) for the format.\n\n### Method 3: Jobs - Asynchronous QUBO Execution\n\nFor large-scale optimization problems that require significant computational time, Quanfluence provides an asynchronous job execution system. This method allows you to submit QUBO problems as background jobs and monitor their progress without blocking your application.\n\n**When to use this method:**\n- Large QUBO problems that may take several minutes to hours to complete\n- When you need to submit multiple problems simultaneously\n- Applications requiring non-blocking execution\n- Batch processing scenarios\n\n**Workflow:**\n1. **Upload QUBO File**: First, upload your QUBO file to the device (same as Method 2)\n2. **Create Job**: Submit the uploaded file for asynchronous execution\n3. **Monitor Progress**: Poll the job status to track execution progress\n4. **Retrieve Results**: Get the final results once the job completes\n\n```python\n# Step 1: Upload a QUBO file to the device (if not already uploaded)\nresponse = client.upload_device_qubo(device_id, \"path/to/your/large_problem.qubo\")\nfile_name = response['result']\nprint(f\"Uploaded file: {file_name}\")\n\n# Step 2: Create an asynchronous job\njob_response = client.create_job(device_id, file_name)\njob_id = job_response['id']\nprint(f\"Created job with ID: {job_id}\")\n\n# Step 3: Get job progress & result\nexecution_result = client.get_job(job_id) # Pass the job_id obtained to execute it\nprint(\"Job Status & Execution result:\", execution_result)\n```\n\n**Job Status Values (AWS Batch):**\n- `SUBMITTED`: Job has been submitted to the queue\n- `PENDING`: Job is waiting for resources to become available\n- `RUNNABLE`: Job is ready to run but waiting for compute resources\n- `STARTING`: Job is being prepared for execution\n- `RUNNING`: Job is currently being executed on the compute resources\n- `SUCCEEDED`: Job completed successfully with results available\n- `FAILED`: Job encountered an error and failed to complete\n- `CANCELLED`: Job was cancelled before execution\n\n## Complete Workflow Example\n\nHere's a complete example of using the Quanfluence SDK to solve a simple QUBO problem:\n\n```python\nimport dimod\nfrom quanfluence_sdk import QuanfluenceClient\n\n# Initialize and authenticate\nclient = QuanfluenceClient()\nclient.signin(\"your_username\", \"your_password\")\n\n# Use an existing device\ndevice_id = DEVICE_ID # Replace with your actual device ID\n\n# Define a QUBO problem\n# This example minimizes: x\u2080 - x\u2080x\u2081 + 2x\u2081\nQ = [[0, 0, 1], [0, 1, -1], [1, 1, 2]]\n\n# Optimize device parameters for this problem\ndevice = client.update_device(device_id, {\n \"alpha\": 2.0,\n \"beta\": 0.333,\n \"beta_decay\": 0.1,\n \"iters\": 1000\n})\n\n# Execute the QUBO\nresult = client.execute_device_qubo_input(device_id, Q)\nprint(\"Optimization result:\", result)\n\n# Print the solution\nif \"solution\" in result:\n print(\"Solution variables:\", result[\"solution\"])\n print(\"Solution energy:\", result[\"energy\"])\n```\n\n## Troubleshooting\n\n### Limitations\n\nThe current supported BQM on the Ising machine has the following limitations:\n \n1. The nodes in the BQM (QUBO or Ising models) should always be indexed from 0 to N-1 where N is the number of nodes.\n2. Disconnected nodes with 0 self-weight are not allowed. \n3. The values in QUBO passed in dictionary format should always be 32 - bit floating point numbers.\n\n### Common Issues\n\n1. **Authentication Errors**: Make sure your username and password are correct.\n \n2. **Missing Access Token**: If you see a \"Access token is missing\" error, ensure you're calling `signin()` before making other API calls.\n\n3. **QUBO Format Issues**: Ensure your QUBO is formatted as a dictionary where keys are tuples of indices and values are floating-point numbers.\n\n\n## Examples\n- [Examples](https://github.com/quanfluence/python-quanfluence-sdk/tree/main/examples) - explore our examples docs and learn more about using sdk.\n\n\n### Feedback\n\n---\n\nIf you get stuck, we\u2019re here to help. The following are the best ways to get assistance working through your issue:\n\nUse our [GitHub Issue Tracker][gh-issues] for reporting bugs or requesting features.\nVisit the [Quanfluence Community][quanfluence-community] for getting help using Quanfluence Developer Kit for Python or just generally bond with your fellow Quanfluence developers.\n\n<!-- Markdown links -->\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Quanfluence Developer Kit for Python",
"version": "0.0.7",
"project_urls": {
"Download": "https://github.com/quanfluence/python-quanfluence-sdk/archive/v_01.tar.gz",
"Homepage": "https://github.com/quanfluence/python-quanfluence-sdk"
},
"split_keywords": [
"quanfluence",
" quanfluence-api",
" web-api",
" sdk",
" rest-api-client"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "de577e82ec9f855d3ba04f8bd40fc936a7083bc040e0260fc9b565ef9de19597",
"md5": "a6d96be7144689b8f71c3163876b0c60",
"sha256": "77ce63745edab453449113d1558719a2ef20a2f4374fe1c2edde59790133f6da"
},
"downloads": -1,
"filename": "quanfluence_sdk-0.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a6d96be7144689b8f71c3163876b0c60",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6.0",
"size": 8324,
"upload_time": "2025-07-22T06:32:50",
"upload_time_iso_8601": "2025-07-22T06:32:50.230273Z",
"url": "https://files.pythonhosted.org/packages/de/57/7e82ec9f855d3ba04f8bd40fc936a7083bc040e0260fc9b565ef9de19597/quanfluence_sdk-0.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bd61af6cccbec2b3fa06e048192f226cf9eeb442b188f91d67c44d53dfd5d124",
"md5": "ae0d7d1da174cd6ffe450f5e5d34c9f8",
"sha256": "db50399b5ad565e2d5156fd589501ffa7b086916ac84cfdbdae5b8c0d8318959"
},
"downloads": -1,
"filename": "quanfluence_sdk-0.0.7.tar.gz",
"has_sig": false,
"md5_digest": "ae0d7d1da174cd6ffe450f5e5d34c9f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.0",
"size": 8391,
"upload_time": "2025-07-22T06:32:51",
"upload_time_iso_8601": "2025-07-22T06:32:51.300982Z",
"url": "https://files.pythonhosted.org/packages/bd/61/af6cccbec2b3fa06e048192f226cf9eeb442b188f91d67c44d53dfd5d124/quanfluence_sdk-0.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 06:32:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quanfluence",
"github_project": "python-quanfluence-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "quanfluence-sdk"
}
JSON
