{"id":48433813,"url":"https://github.com/osamamit/qitesse","last_synced_at":"2026-04-06T12:00:55.320Z","repository":{"id":349490819,"uuid":"1061945442","full_name":"OsamaMIT/qitesse","owner":"OsamaMIT","description":"Python API for performant quantum circuit simulation using qitesse-sim","archived":false,"fork":false,"pushed_at":"2026-04-06T06:42:17.000Z","size":93,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T08:44:38.329Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OsamaMIT.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T15:41:39.000Z","updated_at":"2026-04-06T06:42:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/OsamaMIT/qitesse","commit_stats":null,"previous_names":["osamamit/qitesse"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/OsamaMIT/qitesse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OsamaMIT%2Fqitesse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OsamaMIT%2Fqitesse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OsamaMIT%2Fqitesse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OsamaMIT%2Fqitesse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OsamaMIT","download_url":"https://codeload.github.com/OsamaMIT/qitesse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OsamaMIT%2Fqitesse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31471466,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-04-06T12:00:47.309Z","updated_at":"2026-04-06T12:00:55.271Z","avatar_url":"https://github.com/OsamaMIT.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# qitesse\n[![PyPI Version](https://img.shields.io/pypi/v/qitesse.svg)](https://pypi.org/project/qitesse/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/OsamaMIT/qitesse/blob/main/LICENSE)\n[![Python Versions](https://img.shields.io/pypi/pyversions/qitesse.svg)](https://pypi.org/project/qitesse/)\n\n**qitesse** is a high-throughput CPU backend for repeated evaluation of parameterized quantum circuits.\n\nqitesse is built upon qitesse-sim, the **high-performance CPU-based state-vector execution engine** for quantum circuits, fully built in Rust.\n\nThis PyPI module provides a Python interface designed for hybrid quantum algorithms, repeated circuit evaluation, backend integration, and low-overhead CPU execution from Python.\n\n## Features\n\n- Rust-based CPU statevector simulator with a Python API\n- One-off circuit execution through `Gate` and `Circuit`\n- Compiled parameterized circuits through `CircuitSpec`, `Parameter`, and `CompiledCircuit`\n- Reusable zero-copy parameter buffers through `ParamBuffer` and `ParamBatchBuffer`\n- Expectation-value workflows for Pauli observables and Hamiltonians\n- Batch expectation execution for parameter sweeps and optimizer loops\n- Gradient APIs for compiled circuits via parameter-shift evaluation\n- Reusable `ExecutionContext` buffers for repeated scalar execution\n- Full statevector output for both one-off and compiled execution paths\n- Mid-circuit `measure`, `reset`, and `barrier` operations\n- Custom unitary operations with `Gate.unitary(...)`\n- Controlled custom unitaries with `Gate.controlled_unitary(...)`\n- Common single-, two-, and multi-qubit gates\n- Read the Docs documentation with autogenerated API reference pages\n\n## Installation\n\nqitesse requires **Python 3.8+**. Install it via pip:\n\n```bash\npip install qitesse\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/OsamaMIT/qitesse.git\n\npip install maturin\n\nmaturin develop --release\n```\nTo run examples:\n\n`python examples/h_example.py`\n\n`python examples/qft._example.py`\n\n`python examples/custom_unitary.py`\n\n## Documentation\n\nThe documentation is now set up for Read the Docs with automatic API generation.\n\n- Entry point: [docs/index.rst](docs/index.rst)\n- Current features: [docs/current_features.rst](docs/current_features.rst)\n- Compiled execution guide: [docs/guides/compiled_execution.rst](docs/guides/compiled_execution.rst)\n- Generated API reference root: [docs/api/index.rst](docs/api/index.rst)\n- Read the Docs config: [.readthedocs.yaml](.readthedocs.yaml)\n\nTo add a new public class to the API docs, add it once in [docs/api/index.rst](docs/api/index.rst). Sphinx will generate the class page and include its methods and attributes automatically.\n\n## Current Capabilities\n\nqitesse currently has two main usage modes:\n\n1. General-purpose simulation with `Gate` and `Circuit` for one-off execution.\n2. Compiled execution with `CircuitSpec` and `CompiledCircuit` for repeated parameterized workloads.\n\nThe compiled path currently supports:\n\n- reusable zero-copy parameter buffers\n- scalar expectation evaluation\n- batched expectation evaluation\n- scalar gradients\n- batched gradients\n- reusable execution contexts\n- statevector inspection when needed\n\nThe simulator path currently supports:\n\n- standard single-qubit gates\n- controlled and multi-qubit gates\n- custom unitaries\n- measurement, reset, and barrier operations\n\n## Compiled Circuits\n\n```python\nimport numpy as np\nimport qitesse\n\nspec = qitesse.CircuitSpec(2)\ntheta = spec.param(\"theta\")\n\nspec.ry(0, theta)\nspec.cx(0, 1)\n\ncompiled = spec.compile()\nobservable = qitesse.Observable.pauli_z(1)\n\nvalue = compiled.expectation(np.array([0.4], dtype=np.float32), observable)\ngradient = compiled.gradient(np.array([0.4], dtype=np.float32), observable)\nvalue_again, grad_again = compiled.value_and_gradient(\n    np.array([0.4], dtype=np.float32),\n    observable,\n)\nstate = compiled.statevector(np.array([0.4], dtype=np.float32))\n\nparams_batch = np.array([[0.1], [0.2], [0.3]], dtype=np.float32)\nvalues = compiled.batch_expectation(params_batch, observable)\ngrads = compiled.batch_gradient(params_batch, observable)\n\ncontext = compiled.execution_context()\nvalue_again = context.expectation(compiled, np.array([0.5], dtype=np.float32), observable)\ngrad_again = context.gradient(compiled, np.array([0.5], dtype=np.float32), observable)\n```\n\nThis execution path is intended for repeated evaluation of the same circuit structure with different parameter values.\n\n## Backend Integration\n\nThe compiled execution path is the primary integration surface for higher-level libraries.\n\nThe intended backend pattern is:\n\n1. Translate a framework circuit into `CircuitSpec`\n2. Compile once per circuit structure\n3. Keep parameters in contiguous `numpy.float32` arrays\n4. Call `expectation`, `batch_expectation`, `gradient`, or `value_and_gradient`\n\nFor sequential scalar calls, reuse `compiled.execution_context()` to keep internal buffers alive.\n\nFor sweeps, minibatches, or optimizer batches, prefer `batch_expectation(...)` and `batch_gradient(...)` instead of looping in Python.\n\n## Supported Gates\n\nSingle-qubit gates:\n\n- `i`\n- `x`\n- `y`\n- `z`\n- `h`\n- `s`\n- `sdg`\n- `t`\n- `tdg`\n- `rx`\n- `ry`\n- `rz`\n- `p` / `phase`\n- `u`\n\nTwo-qubit gates:\n\n- `cnot` / `cx`\n- `cy`\n- `cz`\n- `ch`\n- `swap`\n- `iswap`\n- `crx`\n- `cry`\n- `crz`\n- `cp` / `cphase`\n- `cu`\n\nThree-qubit and larger:\n\n- `ccx` / `toffoli`\n- `cswap` / `fredkin`\n- `mcx`\n- `mcz`\n- `mcp` / `mcphase`\n- `controlled_unitary`\n\nCircuit operations:\n\n- `measure`\n- `reset`\n- `barrier`\n\nCustom unitaries:\n\n```python\nimport numpy as np\nimport qitesse\n\nhadamard = np.array([[1, 1], [1, -1]], dtype=np.complex64) / np.sqrt(2)\n\ncircuit = qitesse.Circuit([\n    qitesse.Gate.unitary([0], hadamard),\n    qitesse.Gate.controlled_unitary([0], [1], hadamard),\n])\n\nstate = circuit.run(2)\n```\n\nUse `run_with_measurements(num_qubits)` if the circuit contains measurement gates and you want the observed bit values back.\n\n## Planned Features\n- Additional simulation backends\n\n## Contributing\nContributions are welcome! To contribute:\n\n1. Fork the repository\n2. Create a new branch (feature-branch)\n3. Commit your changes and open a pull request\n\n## License\nThis project is licensed under the MIT License. See the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosamamit%2Fqitesse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosamamit%2Fqitesse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosamamit%2Fqitesse/lists"}