# QStone
## What
An utility to benchmark the quality of an HPC and Quantum Computers integration. The benchmark allows the definition of a set of users for which a set of configurable quantum applications will be randomly selected. Example of currently supported quantum applications: VQE, PyMatching, RB. Users can create custom applications and use them together with the core applications.
QStone generates different portable files (.tar.gz), each supporting a different user and a different scheduler (currently supporting: slurm, lsf, bare_metal). During execution of the benchmark, QStone gathers information on each steps of the applications, allowing investigations on bottlenecks and/or resource constraints at the interface between Quantum and HPC.
The benchmark under the following [assumptions](assumptions.md).
## Why
Building an appropriate hardware/software infrastructure to support HPCQC requires
loads of work. We believe we shoud use a data driven approach in which we measure, fix, measure again with every new version of Quantum Computers, software and HPC hardware.
## Where
Currently supported platforms/architectures:
- MacOS: M1/M2 (Sequoia)
- Intel: x86 (Ubuntu)
- PowerPC: Power9 (RedHat)
Tested on Python [3.9-3.12]
## How
### Installation
`pip install QStone`
### Execution
Run QStone using Command Line Interface
- Run the **generator** command
`qstone generate -i conf.json [--atomic/-a] [--scheduler/-s "slurm"/"jsrun"/"bare_metal"]`
Generates tar.gz files that contains all the scripts to run scheduler for each user. Currently supported schedulers: [baremetal, altair/fnc, slurm/schedmd]. QStone expects an input configuration describing the users to want to generate jobs for as well as the description of the quantum computer you are generating jobs for. The optional `--atomic` flag forces the generation of single step jobs, instead of the default repartition in three jobs (pre, run, post). The `-s` flag allows selecting the output scheduler, default is `bare_metal`.
With `config.json`:
```json
{
"environment": {
"project_name": "proj_name",
"connector": "NO_LINK",
"qpu_ip_address": "0.0.0.0",
"qpu_port": "55",
"qpu_management": "LOCK",
"timeouts" : {
"http": 5,
"lock": 4
}
},
"jobs": [
{
"type": "VQE",
"qubit_min": 2,
"qubit_max": 4,
"walltime" : 10,
"nthreads" : 4,
"lsf/jsrun_opt": "-nnodes=4 "
},
{
"type": "RB",
"qubit_min": 2,
"qubit_max": 4,
"walltime" : 10,
"nthreads" : 2,
"slurm/schedmd_opt": "--cpus-per-task=4"
}
],
"users": [
{
"user": "user0",
"weight": 1,
"computations": {
"VQE": 0.05,
"RB": 0.94,
"PyMatching": 0.01
}
}
]
}
```
For more information on the `config.json` format refer to the associated [json schema](qstone/utils/config_schema.py).
Among the other things, the config file allows setting different polling/querying/scheduling policies for handling shared access to the QPU.
Only SLURM currently supports the high-performance (lowest-latency) "SCHEDULER" mode" please refer to [SLURM](SLURM.md) for more information.
- Alternatively call the generator in script:
```python
from qstone.generators import generator
def main():
generator.generate_suite(config="config.json",
num_calls=100,output_folder=".",atomic=False, scheduler="bare_metal")
if __name__ == "__main__":
main()
```
- Run the **run** command to execute chosen scheduler/workload selecting an optional output folder
`qstone run -i scheduler.qstone.tar.gz [-o folder]`
The optional `-o` allows selecting the output folder in which to run the benchmark instance.
- Alternatively may untar on your machine of choice and run as the selected user.
- Run the jobs by executing `sh qstone_suite/qstone.sh`
- Run the profiling tool to extract metrics of interest.
- Run the **profile** command providing the initial input configuration and output folder to run profiling tool on run information
`qstone profile --cfg conf.json --folder qstone_profile`
- Run the **profile** command providing the initial input configuration and multiple output folders (in case of multi-user run) to run profiling tool on run information
`qstone profile --cfg conf.json --folder qstone_profile --folder qstone_profile2`
### Supported backend connectivities
- Local no-link runner
- gRPC
- Http
- Rigetti
### Examples
- Getting started [notebook](examples/running/getting_started.ipynb)
- How to add a [new type of computation](examples/adding/computation/README.md)
- How to create a simple [gateway](examples/node/README.md)
### Contributing
Guidance on how to [contribute](CONTRIBUTING.md) and [change logs](CHANGELOG.md)
Raw data
{
"_id": null,
"home_page": "https://github.com/riverlane/QStone",
"name": "qstone",
"maintainer": null,
"docs_url": null,
"requires_python": "<=3.13,>=3.9",
"maintainer_email": null,
"keywords": "Quantum, HPC",
"author": "Riverlane",
"author_email": "team@riverlane.com",
"download_url": "https://files.pythonhosted.org/packages/2c/f7/a704d35c090febdf8bcce3b0058a94dfefd9c074b9d220554c09e9b53234/qstone-0.2.0.tar.gz",
"platform": null,
"description": "# QStone\n\n## What\n\nAn utility to benchmark the quality of an HPC and Quantum Computers integration. The benchmark allows the definition of a set of users for which a set of configurable quantum applications will be randomly selected. Example of currently supported quantum applications: VQE, PyMatching, RB. Users can create custom applications and use them together with the core applications.\nQStone generates different portable files (.tar.gz), each supporting a different user and a different scheduler (currently supporting: slurm, lsf, bare_metal). During execution of the benchmark, QStone gathers information on each steps of the applications, allowing investigations on bottlenecks and/or resource constraints at the interface between Quantum and HPC.\nThe benchmark under the following [assumptions](assumptions.md).\n\n## Why\n\nBuilding an appropriate hardware/software infrastructure to support HPCQC requires\nloads of work. We believe we shoud use a data driven approach in which we measure, fix, measure again with every new version of Quantum Computers, software and HPC hardware.\n\n## Where\n\nCurrently supported platforms/architectures:\n\n- MacOS: M1/M2 (Sequoia)\n- Intel: x86 (Ubuntu)\n- PowerPC: Power9 (RedHat)\n\nTested on Python [3.9-3.12]\n\n## How\n\n### Installation\n\n`pip install QStone`\n\n### Execution\n\nRun QStone using Command Line Interface\n\n- Run the **generator** command\n\n `qstone generate -i conf.json [--atomic/-a] [--scheduler/-s \"slurm\"/\"jsrun\"/\"bare_metal\"]`\n\n Generates tar.gz files that contains all the scripts to run scheduler for each user. Currently supported schedulers: [baremetal, altair/fnc, slurm/schedmd]. QStone expects an input configuration describing the users to want to generate jobs for as well as the description of the quantum computer you are generating jobs for. The optional `--atomic` flag forces the generation of single step jobs, instead of the default repartition in three jobs (pre, run, post). The `-s` flag allows selecting the output scheduler, default is `bare_metal`.\n\n With `config.json`:\n\n```json\n{\n \"environment\": { \n \"project_name\": \"proj_name\",\n \"connector\": \"NO_LINK\",\n \"qpu_ip_address\": \"0.0.0.0\",\n \"qpu_port\": \"55\",\n \"qpu_management\": \"LOCK\",\n \"timeouts\" : {\n \"http\": 5,\n \"lock\": 4\n } \n },\n \"jobs\": [\n {\n \"type\": \"VQE\",\n \"qubit_min\": 2,\n \"qubit_max\": 4,\n \"walltime\" : 10,\n \"nthreads\" : 4,\n \"lsf/jsrun_opt\": \"-nnodes=4 \"\n },\n {\n \"type\": \"RB\",\n \"qubit_min\": 2,\n \"qubit_max\": 4,\n \"walltime\" : 10,\n \"nthreads\" : 2,\n \"slurm/schedmd_opt\": \"--cpus-per-task=4\"\n }\n ],\n \"users\": [\n {\n \"user\": \"user0\",\n \"weight\": 1,\n \"computations\": {\n \"VQE\": 0.05,\n \"RB\": 0.94,\n \"PyMatching\": 0.01\n }\n }\n ]\n}\n```\n\nFor more information on the `config.json` format refer to the associated [json schema](qstone/utils/config_schema.py).\nAmong the other things, the config file allows setting different polling/querying/scheduling policies for handling shared access to the QPU.\nOnly SLURM currently supports the high-performance (lowest-latency) \"SCHEDULER\" mode\" please refer to [SLURM](SLURM.md) for more information.\n\n- Alternatively call the generator in script:\n\n```python\nfrom qstone.generators import generator\n\ndef main():\n generator.generate_suite(config=\"config.json\",\n num_calls=100,output_folder=\".\",atomic=False, scheduler=\"bare_metal\")\n\nif __name__ == \"__main__\":\n main()\n```\n\n- Run the **run** command to execute chosen scheduler/workload selecting an optional output folder\n\n `qstone run -i scheduler.qstone.tar.gz [-o folder]`\n\nThe optional `-o` allows selecting the output folder in which to run the benchmark instance.\n\n- Alternatively may untar on your machine of choice and run as the selected user.\n\n - Run the jobs by executing `sh qstone_suite/qstone.sh`\n\n - Run the profiling tool to extract metrics of interest.\n\n- Run the **profile** command providing the initial input configuration and output folder to run profiling tool on run information\n\n `qstone profile --cfg conf.json --folder qstone_profile`\n\n- Run the **profile** command providing the initial input configuration and multiple output folders (in case of multi-user run) to run profiling tool on run information\n\n `qstone profile --cfg conf.json --folder qstone_profile --folder qstone_profile2`\n\n### Supported backend connectivities\n\n- Local no-link runner\n- gRPC\n- Http\n- Rigetti\n\n### Examples\n\n- Getting started [notebook](examples/running/getting_started.ipynb)\n- How to add a [new type of computation](examples/adding/computation/README.md)\n- How to create a simple [gateway](examples/node/README.md)\n\n### Contributing\n\nGuidance on how to [contribute](CONTRIBUTING.md) and [change logs](CHANGELOG.md)\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Benchmarking suite for Quantum Computers integration into HPC Systems",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/riverlane/QStone",
"Repository": "https://github.com/riverlane/QStone"
},
"split_keywords": [
"quantum",
" hpc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b75ff62872602f6cdfab489446e37d11799afa4d45d6c470b323482ff1a51192",
"md5": "534476fd8dd8e0f1383a9f060bbfddf3",
"sha256": "f6c6aa801352dad3ce6e1ff03548c6f264529692de03d1ff13b177072f80e3e3"
},
"downloads": -1,
"filename": "qstone-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "534476fd8dd8e0f1383a9f060bbfddf3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<=3.13,>=3.9",
"size": 40508,
"upload_time": "2025-01-15T15:52:25",
"upload_time_iso_8601": "2025-01-15T15:52:25.069383Z",
"url": "https://files.pythonhosted.org/packages/b7/5f/f62872602f6cdfab489446e37d11799afa4d45d6c470b323482ff1a51192/qstone-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2cf7a704d35c090febdf8bcce3b0058a94dfefd9c074b9d220554c09e9b53234",
"md5": "e1503a0bc3ab88d049fc0341632cc811",
"sha256": "3adb4ed25596f41f0b8d96ed2497a228a6bf19df9dc1786e1dd5b7b2aa6b6c61"
},
"downloads": -1,
"filename": "qstone-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "e1503a0bc3ab88d049fc0341632cc811",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<=3.13,>=3.9",
"size": 30041,
"upload_time": "2025-01-15T15:52:28",
"upload_time_iso_8601": "2025-01-15T15:52:28.240805Z",
"url": "https://files.pythonhosted.org/packages/2c/f7/a704d35c090febdf8bcce3b0058a94dfefd9c074b9d220554c09e9b53234/qstone-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-15 15:52:28",
"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
