{"id":24454224,"url":"https://github.com/qbrilliance/qristal","last_synced_at":"2025-10-01T17:30:33.405Z","repository":{"id":195999670,"uuid":"690330685","full_name":"qbrilliance/qristal","owner":"qbrilliance","description":"Qristal: hybrid quantum-classical C++/Python development platform from Quantum Brilliance","archived":false,"fork":false,"pushed_at":"2024-06-19T03:34:42.000Z","size":118,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-06-19T10:52:56.474Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qbrilliance.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-12T01:48:34.000Z","updated_at":"2024-06-19T03:34:45.000Z","dependencies_parsed_at":"2024-06-19T10:52:02.078Z","dependency_job_id":"c7050102-4361-4f1a-8d8d-00d6e587d4f1","html_url":"https://github.com/qbrilliance/qristal","commit_stats":null,"previous_names":["qbrilliance/qristal"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbrilliance%2Fqristal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbrilliance%2Fqristal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbrilliance%2Fqristal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbrilliance%2Fqristal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qbrilliance","download_url":"https://codeload.github.com/qbrilliance/qristal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234883315,"owners_count":18901365,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-21T02:01:23.467Z","updated_at":"2025-10-01T17:30:33.399Z","avatar_url":"https://github.com/qbrilliance.png","language":"Jupyter Notebook","funding_links":[],"categories":["Quantum full-stack libraries"],"sub_categories":[],"readme":"# Quantum Brilliance Qristal SDK\n\nQristal is the QB software development kit for quantum computing.\n\n## Getting Started\n\nQB Qristal can be installed directly from source or via a pre-built Docker image.\n\n### Docker\n\nA Docker image is provided in the GitLab container registry associated with the SDK repository.\n\nDepending on how you have set up Docker on your system, you may or may not need to run the following commands as root.\n\n1. Start the QB Qristal container\n```sh\ndocker run --rm -it --name qristal -d -p 8889:8889 registry.gitlab.com/qbau/software-and-apps/public/qbsdk/qristal-sdk\n```\nIf your system has one or more NVIDIA GPUs, install the [NVIDIA Container Toolkit](https://github.com/NVIDIA/nvidia-docker) and add the switch `--gpus all` to the `docker run` command in order to use them.\n\nThis command will start a container and map its TCP port 8889 to the same port on the Docker host (your computer).\n\nFrom your web browser, you can access a JupyterLab environment at http://localhost:8889 to view Python examples and start prototyping with QB Qristal.\n\n2. Connect to the QB Qristal container\n\nAfter starting the container, besides the [JupyterLab environment](http://localhost:8889), you can connect (attach) directly to the container via a terminal or VSCode.\n\n- For the terminal, run the following command to attach to a terminal session inside the container.\n\n```sh\ndocker exec -it qristal bash\n```\n\n- If you prefer to use VSCode, you can \"attach\" it to the  running `qristal` Docker container.\n\nTo attach to the `qristal` Docker container, either select `Dev Containers: Attach to Running Container...` from the `Command Palette` (F1) or use the `Remote Explorer` in the `Activity Bar` and from the `Containers` view, select the `Attach to Container` inline action on the container. In both methods, a dropdown will appear; select the `qristal` container.\n\n3. Stop and remove the container\n\n```sh\ndocker stop qristal\n```\n\n### Install from source\n\n**Prerequisites**\n\n*Bare metal*\n\nLinux (e.g. Ubuntu) is required. One may choose to use Ubuntu with WSL 2 ([Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/)), as the installation sequence is the same. The best performance is achieved with regular Linux, due to additional overhead coming from the Windows filesystem. Please ensure if using WSL that you turn on file system case sensitivity for the location where you intend to install Qristal.\n\nBefore building Qristal, you must have the following packages already installed and working:\n\n- Python 3.8 or later\n\n- gcc, g++, and gfortran 11.4.0 or later. LLVM-Clang 16.0.6 or later is supported, but gcc/g++ is still required for building exatn and tnqvm.\n\n- cmake 3.20 or later\n\n- Boost 1.71 or later\n\n- OpenBLAS\n\n- OpenSSL\n\n- Curl\n\n\nFor example, on Ubuntu 22.04, you can use `apt` to install all of the above:\n\n```sh\nsudo apt install build-essential cmake gfortran libboost-all-dev libcurl4-openssl-dev libssl-dev libopenblas-dev libpython3-dev python3 python3-pip\n```\n\nQristal will be built with support for CUDA Quantum if and only if cmake detects that your system has a compatible CUDA Quantum installation.\n\n*Dev container*\n\nAlternatively, you can build Qristal in a development container, using the contents of `integrations/vscode/.devcontainer`.  For this, the only prerequisites are\n\n- Docker\n\n- an IDE compliant with the Development Container Specification (e.g. VS Code)\n\n\n**Compilation**\n\n\u003ca name=\"compilation\"\u003e\u003c/a\u003e\n\nAfter cloning the Qristal SDK repository, compile and install it with\n\n```sh\nmkdir build \u0026\u0026 cd build\ncmake .. -DINSTALL_MISSING=ON\nmake -j$(nproc) install\n```\n\nThis will automatically install all missing dependencies neither covered by the `apt` commands above nor provided by the dev container. If you wish to only install missing C++ or Python dependencies, instead of passing `-DINSTALL_MISSING=ON` you can pass `-DINSTALL_MISSING=CXX` or `-DINSTALL_MISSING=PYTHON`.\n\nNote that the dependencies to be installed include the constituent Qristal components `core`, `decoder` and `integrations`.  By default, the latest tagged releases of each of these components is pulled in. If you would like cmake to retrieve alternative versions of these components, you can specify a git ref to pull in each case, by passing `-DCORE_TAG=\u003cYOUR_TAG\u003e`, `-DDECODER_TAG=\u003cYOUR_TAG\u003e` and/or `-DINTEGRATIONS_TAG=\u003cYOUR_TAG\u003e` when invoking cmake. Note that for the overall build to be successful, the refs of the different components, including the top-level Qristal SDK repo itself, must correspond to versions that are compatible with one another. You can always achieve this by using the same release tag (e.g. `v1.6.0`) for everything, or simply `main`, which will refer to the tips of all `main` branches.\n\nBy default, the public Qristal git repositories are used to retrieve each of these components. If you have access to and prefer to use the development repositories, you can pass `--preset=dev` when invoking cmake. Note that private repos contain refs not present in the public repos, so forgetting to include the `dev` preset can lead to errors about missing refs.\n\nIf you wish to build Qristal's C++ noise-aware circuit placement routines, you must also enable the use of the additional dependency [TKET](https://github.com/CQCL/tket). This is done by passing `-DWITH_TKET=ON` to `cmake`. TKET will be installed automatically by `cmake` if both `-DWITH_TKET=ON` and `-DINSTALL_MISSING=ON` (or `-DINSTALL_MISSING=CXX`) are passed to `cmake`. Alternatively, if you have an existing TKET installation, you can pass `-DWITH_TKET=ON -DTKET_DIR=\u003cYOUR TKET INSTALLATION DIR\u003e` to `cmake` to tell it to use your installation rather than building TKET from source.\n\nIf you also wish to build the html documentation, you can pass `-DBUILD_DOCS=ON` to `cmake`.\n\nWhen using QB Qristal, a user workflow normally consists of the following steps:\n\n- Define a quantum circuit, for example, as an OpenQASM source string.\n\n- Configure the QB Qristal runtime, e.g., the accelerator backend, number of measurement shots, etc.\n\n- Run the circuit with the specified configurations.\n\n- Retrieve and analyze the results of the experiments.\n\nHere is an example of the entire workflow:\n\n```python\n# Import the core of the QB SDK\nimport qristal.core\n\n# Create a quantum computing session using the QB SDK\nmy_sim = qristal.core.session()\n\n# Choose a simulator backend\nmy_sim.acc = \"qpp\"\n\n# Choose how many qubits to simulate\nmy_sim.qn = 2\n\n# Choose how many 'shots' to run through the circuit\nmy_sim.sn = 100\n\n# Define the quantum program to run (aka 'quantum kernel' aka 'quantum circuit')\nmy_sim.instring = '''\n__qpu__ void MY_QUANTUM_CIRCUIT(qreg q)\n{\n  OPENQASM 2.0;\n  include \"qelib1.inc\";\n  creg c[2];\n  h q[0];\n  cx q[0], q[1];\n  measure q[1] -\u003e c[1];\n  measure q[0] -\u003e c[0];\n}\n'''\n\n# Run the circuit 100 times and count up the results in each of the classical registers\nprint(\"About to run quantum program...\")\nmy_sim.run()\nprint(\"Ran successfully!\")\n\n# Print the cumulative results in each of the classical registers\nprint(\"Results:\\n\", my_sim.results)\n```\n\nIf you run the example, you will get an output similar to the following (right-hand values will both be around 50):\n\n```sh\nAbout to run quantum program...\nRan successfully!\nResults:\n {\n    \"00\": 45,\n    \"11\": 55\n}\n```\n\n## Further examples ##\n\nFollowing installation, you can find\n\n- A series of examples in the installed folder `examples`.  These are described [here](examples/README.md).\n- A detailed set of introductory exercises in the `exercises` folder.  These can be launched using Jupyter Notebook.\n- A standalone [Quantum Decoder application](docs/README_decoder.md).\n\n## Documentation\nYou can find the docs for Qristal on the web at [qristal.readthedocs.io](https://qristal.readthedocs.io).  If you have built and installed the documentation (see [compilation](#compilation)), you can also find it at `\u003cinstallation_directory\u003e/docs/html/index.html`.\n\n## License ##\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqbrilliance%2Fqristal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqbrilliance%2Fqristal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqbrilliance%2Fqristal/lists"}