# QStone
A utility to benchmark the quality of HPC and Quantum Computer integration.
## Overview
QStone allows you to define a set of users for which configurable quantum applications will be randomly selected and executed. The benchmark generates different portable files (`.tar.gz`), each supporting different users and schedulers.
**Currently supported quantum applications:**
- VQE (Variational Quantum Eigensolver)
- PyMatching
- RB (Randomized Benchmarking)
- QBC (Quantum Benchmarking Circuit)
**Key features:**
- Support for custom applications alongside core applications
- Multi-scheduler support (SLURM, LSF, bare metal)
- Detailed performance metrics collection
- Bottleneck and resource constraint analysis at the quantum-HPC interface
The benchmark operates under specific [assumptions](ASSUMPTIONS.md).
## Why QStone?
Building appropriate hardware/software infrastructure for HPCQC requires significant effort. QStone enables a data-driven approach where you can measure performance, implement fixes, and measure again with every new version of quantum computers, software, and HPC hardware.
## Supported Platforms
| Platform | Architecture | OS |
|----------|-------------|-----|
| Apple Silicon | M1-M4 | macOS |
| Intel | x86_64 | Ubuntu |
| IBM Power | Power9 | RedHat |
**Python versions:** 3.10 - 3.12
## Installation
### Basic Installation
```bash
pip install QStone
```
### Full Installation with MPI Support
First, install OpenMPI:
```bash
# Ubuntu/Debian
sudo apt install openmpi-bin openmpi-common libopenmpi-dev
# RedHat/CentOS/Fedora
sudo yum install openmpi openmpi-devel
# macOS
brew install openmpi
```
Then install QStone with MPI support:
```bash
pip install QStone[mpi]
```
## Usage
### 1. Generate Benchmark Suite
```bash
qstone generate -i config.json [--atomic/-a] [--scheduler/-s "slurm"/"jsrun"/"bare_metal"]
```
**Options:**
- `--atomic` / `-a`: Generate single-step jobs instead of three-phase jobs (pre/run/post)
- `--scheduler` / `-s`: Select output scheduler (default: `bare_metal`)
**Supported schedulers:** bare metal, Altair/FNC, SLURM/SchedMD
### 2. Execute Benchmark
```bash
qstone run -i scheduler.qstone.tar.gz [-o output_folder]
```
**Alternative:** Extract the tar.gz file and run manually:
```bash
tar -xzf scheduler.qstone.tar.gz
cd qstone_suite
sh qstone.sh
```
### 3. Profile Results
**Single user:**
```bash
qstone profile --cfg config.json --folder qstone_profile
```
**Multiple users:**
```bash
qstone profile --cfg config.json --folder qstone_profile --folder qstone_profile2
```
## Configuration
### Sample Configuration File
Create a `config.json` file with the following structure:
```json
{
"environment": {
"project_name": "my_quantum_project",
"scheduling_mode": "LOCK",
"job_count": 5,
"qpu": {
"mode": "RANDOM"
},
"connectivity": {
"mode": "NO_LINK",
"qpu": {
"ip_address": "0.0.0.0",
"port": 55
}
},
"timeouts": {
"http": 5,
"lock": 4
}
},
"jobs": [
{
"type": "VQE",
"qubits": [4, 6],
"num_shots": [100, 200],
"walltime": 10,
"nthreads": 4,
"app_logging_level": 2
},
{
"type": "RB",
"qubits": [2],
"num_shots": [100],
"walltime": 10,
"nthreads": 2
},
{
"type": "QBC",
"qubits": [4],
"num_shots": [32],
"walltime": 20,
"nthreads": 2
}
],
"users": [
{
"user": "user0",
"computations": {
"VQE": 0.05,
"RB": 0.94,
"PyMatching": 0.01
}
}
]
}
```
For detailed configuration options, refer to the [JSON schema](qstone/utils/config_schema.py).
**Note:** Only SLURM currently supports the high-performance "SCHEDULER" mode with lowest latency. See [SLURM documentation](SLURM.md) for more details.
## Programmatic Usage
```python
from qstone.generators import generator
def main():
generator.generate_suite(
config="config.json",
job_count=100,
output_folder=".",
atomic=False,
scheduler="bare_metal"
)
if __name__ == "__main__":
main()
```
## Supported Backend Connectivities
- **Local no-link runner** - For testing without quantum hardware
- **gRPC** - High-performance remote procedure calls
- **HTTP/REST** - Standard web-based communication
- **Rigetti** - Native Rigetti quantum computer integration
## Examples and Resources
- 📓 [Getting Started Notebook](examples/running/getting_started.ipynb)
- 🔧 [Adding New Computation Types](examples/adding/computation/README.md)
- 🌐 [Creating a Simple Gateway](examples/node/README.md)
## Contributing
- [Contributing Guidelines](contributing.md)
- [Change Log](changelog.md)
## License
[License](LICENSE)
---
*For questions, issues, or feature requests, please visit our [GitHub repository](https://github.com/your-org/qstone) or open an issue.*
Raw data
{
"_id": null,
"home_page": "https://github.com/riverlane/QStone",
"name": "qstone",
"maintainer": null,
"docs_url": null,
"requires_python": "<=3.13,>=3.10",
"maintainer_email": null,
"keywords": "Quantum, HPC",
"author": "Riverlane ",
"author_email": "team@riverlane.com",
"download_url": "https://files.pythonhosted.org/packages/be/51/12a2d5fc94a4a816410c8b64aae7ab7017280bf757a05d5195aae9ebde0b/qstone-0.4.1.tar.gz",
"platform": null,
"description": "# QStone\n\nA utility to benchmark the quality of HPC and Quantum Computer integration.\n\n## Overview\n\nQStone allows you to define a set of users for which configurable quantum applications will be randomly selected and executed. The benchmark generates different portable files (`.tar.gz`), each supporting different users and schedulers.\n\n**Currently supported quantum applications:**\n- VQE (Variational Quantum Eigensolver)\n- PyMatching\n- RB (Randomized Benchmarking)\n- QBC (Quantum Benchmarking Circuit)\n\n**Key features:**\n- Support for custom applications alongside core applications\n- Multi-scheduler support (SLURM, LSF, bare metal)\n- Detailed performance metrics collection\n- Bottleneck and resource constraint analysis at the quantum-HPC interface\n\nThe benchmark operates under specific [assumptions](ASSUMPTIONS.md).\n\n## Why QStone?\n\nBuilding appropriate hardware/software infrastructure for HPCQC requires significant effort. QStone enables a data-driven approach where you can measure performance, implement fixes, and measure again with every new version of quantum computers, software, and HPC hardware.\n\n## Supported Platforms\n\n| Platform | Architecture | OS |\n|----------|-------------|-----|\n| Apple Silicon | M1-M4 | macOS |\n| Intel | x86_64 | Ubuntu |\n| IBM Power | Power9 | RedHat |\n\n**Python versions:** 3.10 - 3.12\n\n## Installation\n\n### Basic Installation\n\n```bash\npip install QStone\n```\n\n### Full Installation with MPI Support\n\nFirst, install OpenMPI:\n\n```bash\n# Ubuntu/Debian\nsudo apt install openmpi-bin openmpi-common libopenmpi-dev\n\n# RedHat/CentOS/Fedora \nsudo yum install openmpi openmpi-devel\n\n# macOS\nbrew install openmpi\n```\n\nThen install QStone with MPI support:\n\n```bash\npip install QStone[mpi]\n```\n\n## Usage\n\n### 1. Generate Benchmark Suite\n\n```bash\nqstone generate -i config.json [--atomic/-a] [--scheduler/-s \"slurm\"/\"jsrun\"/\"bare_metal\"]\n```\n\n**Options:**\n- `--atomic` / `-a`: Generate single-step jobs instead of three-phase jobs (pre/run/post)\n- `--scheduler` / `-s`: Select output scheduler (default: `bare_metal`)\n\n**Supported schedulers:** bare metal, Altair/FNC, SLURM/SchedMD\n\n### 2. Execute Benchmark\n\n```bash\nqstone run -i scheduler.qstone.tar.gz [-o output_folder]\n```\n\n**Alternative:** Extract the tar.gz file and run manually:\n```bash\ntar -xzf scheduler.qstone.tar.gz\ncd qstone_suite\nsh qstone.sh\n```\n\n### 3. Profile Results\n\n**Single user:**\n```bash\nqstone profile --cfg config.json --folder qstone_profile\n```\n\n**Multiple users:**\n```bash\nqstone profile --cfg config.json --folder qstone_profile --folder qstone_profile2\n```\n\n## Configuration\n\n### Sample Configuration File\n\nCreate a `config.json` file with the following structure:\n\n```json\n{\n \"environment\": { \n \"project_name\": \"my_quantum_project\",\n \"scheduling_mode\": \"LOCK\",\n \"job_count\": 5,\n \"qpu\": {\n \"mode\": \"RANDOM\"\n },\n \"connectivity\": {\n \"mode\": \"NO_LINK\",\n \"qpu\": {\n \"ip_address\": \"0.0.0.0\",\n \"port\": 55\n }\n },\n \"timeouts\": {\n \"http\": 5,\n \"lock\": 4\n } \n },\n \"jobs\": [\n {\n \"type\": \"VQE\",\n \"qubits\": [4, 6],\n \"num_shots\": [100, 200],\n \"walltime\": 10,\n \"nthreads\": 4,\n \"app_logging_level\": 2 \n },\n {\n \"type\": \"RB\",\n \"qubits\": [2],\n \"num_shots\": [100],\n \"walltime\": 10,\n \"nthreads\": 2\n },\n {\n \"type\": \"QBC\",\n \"qubits\": [4],\n \"num_shots\": [32],\n \"walltime\": 20,\n \"nthreads\": 2\n }\n ],\n \"users\": [\n {\n \"user\": \"user0\",\n \"computations\": {\n \"VQE\": 0.05,\n \"RB\": 0.94,\n \"PyMatching\": 0.01\n }\n }\n ]\n}\n```\n\nFor detailed configuration options, refer to the [JSON schema](qstone/utils/config_schema.py).\n\n**Note:** Only SLURM currently supports the high-performance \"SCHEDULER\" mode with lowest latency. See [SLURM documentation](SLURM.md) for more details.\n\n## Programmatic Usage\n\n```python\nfrom qstone.generators import generator\n\ndef main():\n generator.generate_suite(\n config=\"config.json\",\n job_count=100, \n output_folder=\".\", \n atomic=False, \n scheduler=\"bare_metal\"\n )\n\nif __name__ == \"__main__\":\n main()\n```\n\n## Supported Backend Connectivities\n\n- **Local no-link runner** - For testing without quantum hardware\n- **gRPC** - High-performance remote procedure calls\n- **HTTP/REST** - Standard web-based communication\n- **Rigetti** - Native Rigetti quantum computer integration\n\n## Examples and Resources\n\n- \ud83d\udcd3 [Getting Started Notebook](examples/running/getting_started.ipynb)\n- \ud83d\udd27 [Adding New Computation Types](examples/adding/computation/README.md)\n- \ud83c\udf10 [Creating a Simple Gateway](examples/node/README.md)\n\n## Contributing\n\n- [Contributing Guidelines](contributing.md)\n- [Change Log](changelog.md)\n\n## License\n\n[License](LICENSE)\n\n\n---\n\n*For questions, issues, or feature requests, please visit our [GitHub repository](https://github.com/your-org/qstone) or open an issue.*\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Benchmarking suite for Quantum Computers integration into HPC Systems",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/riverlane/QStone",
"Repository": "https://github.com/riverlane/QStone",
"changelog": "https://github.com/riverlane/QStone/blob/main/CHANGELOG.md",
"documentation": "https://riverlane.github.io/QStone"
},
"split_keywords": [
"quantum",
" hpc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f7906f3b28acd1309776dff91a9a52eafc34dd7485025e34eb09d6b040900f45",
"md5": "f4ba0115ae9ef95734ed5187621faab4",
"sha256": "d10f369eb4a7ed0155e7cde9bed69b3660a1d559a45a896ac76608d36bb32177"
},
"downloads": -1,
"filename": "qstone-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f4ba0115ae9ef95734ed5187621faab4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<=3.13,>=3.10",
"size": 47959,
"upload_time": "2025-07-25T13:38:41",
"upload_time_iso_8601": "2025-07-25T13:38:41.212896Z",
"url": "https://files.pythonhosted.org/packages/f7/90/6f3b28acd1309776dff91a9a52eafc34dd7485025e34eb09d6b040900f45/qstone-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "be5112a2d5fc94a4a816410c8b64aae7ab7017280bf757a05d5195aae9ebde0b",
"md5": "cb5221b0b873fc9ff87fda1aac5ff10d",
"sha256": "2d3da6ec529979cf2391edbd18d36011414450e8745ce1616277fcb59cfb89b5"
},
"downloads": -1,
"filename": "qstone-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "cb5221b0b873fc9ff87fda1aac5ff10d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<=3.13,>=3.10",
"size": 36356,
"upload_time": "2025-07-25T13:38:42",
"upload_time_iso_8601": "2025-07-25T13:38:42.454324Z",
"url": "https://files.pythonhosted.org/packages/be/51/12a2d5fc94a4a816410c8b64aae7ab7017280bf757a05d5195aae9ebde0b/qstone-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 13:38:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "riverlane",
"github_project": "QStone",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "qstone"
}
JSON
