quantum-cq 0.1.0__tar.gz

quantum_cq-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José Yrikes de Oliveira Feitosa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantum_cq-0.1.0/MANIFEST.in

@@ -0,0 +1,19 @@
+prune .pytest_cache
+prune .vscode
+prune logs
+prune results
+prune notebooks/experiments
+prune build
+prune dist
+prune src/quantum_cq.egg-info
+recursive-exclude src/quantum_cq.egg-info *
+exclude src/quantum_cq.egg-info/SOURCES.txt
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.pyo
+global-exclude *.log
+global-exclude *.executed.ipynb
+global-exclude .env
+global-exclude *.env
+global-exclude .env.*
+global-exclude .pypirc

quantum_cq-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: quantum-cq
+Version: 0.1.0
+Summary: Compact quantum circuit helpers, encodings, algorithms, navigation and Qiskit interop.
+Author: José Yrikes de Oliveira Feitosa
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jyrikes/quantum-cq
+Project-URL: Repository, https://github.com/jyrikes/quantum-cq
+Project-URL: Issues, https://github.com/jyrikes/quantum-cq/issues
+Keywords: quantum,qiskit,encoding,quantum-circuits,education
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: qiskit
+Requires-Dist: numpy
+Requires-Dist: packaging
+Provides-Extra: aer
+Requires-Dist: qiskit-aer; extra == "aer"
+Provides-Extra: ibm
+Requires-Dist: qiskit-ibm-runtime; extra == "ibm"
+Provides-Extra: notebook
+Requires-Dist: pandas; extra == "notebook"
+Requires-Dist: matplotlib; extra == "notebook"
+Requires-Dist: ipython; extra == "notebook"
+Requires-Dist: ipywidgets; extra == "notebook"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: all
+Requires-Dist: qiskit-aer; extra == "all"
+Requires-Dist: qiskit-ibm-runtime; extra == "all"
+Requires-Dist: pandas; extra == "all"
+Requires-Dist: matplotlib; extra == "all"
+Requires-Dist: ipython; extra == "all"
+Requires-Dist: ipywidgets; extra == "all"
+Dynamic: license-file
+
+# quantum_cq
+
+Biblioteca Python extraida de um notebook de computacao quantica, com uma
+camada compacta de circuitos (`QC`), encoders classicos, algoritmos basicos e
+interop com Qiskit.
+
+## Instalacao
+
+```powershell
+pip install quantum-cq
+```
+
+Extras opcionais:
+
+```powershell
+pip install "quantum-cq[aer]"       # simuladores Aer
+pip install "quantum-cq[ibm]"       # IBM Quantum Runtime
+pip install "quantum-cq[notebook]"  # pandas, matplotlib, IPython e widgets
+pip install "quantum-cq[all]"       # todos os extras opcionais
+```
+
+## Uso rapido
+
+```python
+from quantum_cq import CQ
+
+encoded_basis = CQ.encode([1, 0, 1])
+encoded_angle = CQ.encode([0.1, 0.2])
+```
+
+```python
+deutsch = CQ.algorithm("deutsch").with_case(2).build()
+bv = CQ.algorithm("bernstein_vazirani").with_secret("1011").build()
+dj = CQ.algorithm("deutsch_jozsa").with_num_qubits(3).with_kind("balanced").build()
+grover = CQ.algorithm("grover").with_marked_state("11").build()
+qpe = CQ.algorithm("phase_estimation").with_phase(0.25).with_precision(3).build()
+```
+
+```python
+qft = CQ.primitive("qft").build(num_qubits=3)
+diffuser = CQ.primitive("standard_diffuser").build(num_qubits=3)
+phase_rotation = CQ.operator("phase_rotation").with_phase(0.25).build()
+```
+
+```python
+memory = CQ.memory([3, 5, 7, 9])
+nav = CQ.encode(memory, role="navigation")
+qram_like = CQ.encode(memory, role="navigation", engine="qram_like")
+print(CQ.metrics(nav))
+print(CQ.to_qiskit(nav).draw())
+```
+
+```python
+graph = CQ.graph(edges=[(0, 1), (1, 2), (2, 3)], num_vertices=4)
+neighbor_oracle = CQ.encode(graph, role="navigation")
+
+cycle = CQ.graph(edges=[(0, 1), (1, 2), (2, 3), (3, 0)], num_vertices=4)
+walk = CQ.primitive("coined_quantum_walk").build(cycle, steps=1)
+```
+
+## QC como circuito oficial
+
+```python
+from quantum_cq import CQ
+from quantum_cq.algorithms import twobit_block
+from quantum_cq.compact import QC, m, obs, sep
+
+uf0 = twobit_block(2)
+qc = QC(
+    "Deutsch",
+    [
+        [0, "-", "H", obs("pre_oracle"), uf0, sep("after_oracle"), "H", m(0)],
+        [0, "X", "H", obs("pre_oracle"), uf0, "-", "-", "-"],
+    ],
+    c=1,
+)
+
+same_qc = CQ.from_qc(qc)
+qiskit_circuit = CQ.to_qiskit(qc)
+metrics = CQ.metrics(qc)
+```
+
+## Exportacao
+
+```python
+qiskit_circuit = CQ.export(qc, target="qiskit")
+```
+
+Exportadores futuros como `mqt` e `openqasm` ainda levantam
+`NotImplementedError`; eles nao fingem implementacao parcial.
+
+## Encodings generalizados
+
+A arquitetura separa os papeis:
+
+- `StateEncoding`: dados classicos para estado quantico.
+- `OracleEncoding`: funcao ou predicado para oraculo.
+- `OperatorEncoding`: operador ou unitario reutilizavel.
+- `NavigationEncoding`: memoria enderecada ou grafo para acesso coerente.
+- `QuantumWalk`: dinamica unitaria sobre uma estrutura navegavel.
+
+`engine="qram_like"` simula a semantica logica de acesso QRAM-like, mas nao e
+QRAM fisico. A metadata marca `physical_qram=False`.
+
+## Logging
+
+A biblioteca escreve eventos operacionais no terminal por padrao.
+
+```python
+from quantum_cq import configure_logging
+
+configure_logging(level="INFO")
+```
+
+## Testes
+
+```powershell
+python -m pytest -q
+```

quantum_cq-0.1.0/README.md

@@ -0,0 +1,119 @@
+# quantum_cq
+
+Biblioteca Python extraida de um notebook de computacao quantica, com uma
+camada compacta de circuitos (`QC`), encoders classicos, algoritmos basicos e
+interop com Qiskit.
+
+## Instalacao
+
+```powershell
+pip install quantum-cq
+```
+
+Extras opcionais:
+
+```powershell
+pip install "quantum-cq[aer]"       # simuladores Aer
+pip install "quantum-cq[ibm]"       # IBM Quantum Runtime
+pip install "quantum-cq[notebook]"  # pandas, matplotlib, IPython e widgets
+pip install "quantum-cq[all]"       # todos os extras opcionais
+```
+
+## Uso rapido
+
+```python
+from quantum_cq import CQ
+
+encoded_basis = CQ.encode([1, 0, 1])
+encoded_angle = CQ.encode([0.1, 0.2])
+```
+
+```python
+deutsch = CQ.algorithm("deutsch").with_case(2).build()
+bv = CQ.algorithm("bernstein_vazirani").with_secret("1011").build()
+dj = CQ.algorithm("deutsch_jozsa").with_num_qubits(3).with_kind("balanced").build()
+grover = CQ.algorithm("grover").with_marked_state("11").build()
+qpe = CQ.algorithm("phase_estimation").with_phase(0.25).with_precision(3).build()
+```
+
+```python
+qft = CQ.primitive("qft").build(num_qubits=3)
+diffuser = CQ.primitive("standard_diffuser").build(num_qubits=3)
+phase_rotation = CQ.operator("phase_rotation").with_phase(0.25).build()
+```
+
+```python
+memory = CQ.memory([3, 5, 7, 9])
+nav = CQ.encode(memory, role="navigation")
+qram_like = CQ.encode(memory, role="navigation", engine="qram_like")
+print(CQ.metrics(nav))
+print(CQ.to_qiskit(nav).draw())
+```
+
+```python
+graph = CQ.graph(edges=[(0, 1), (1, 2), (2, 3)], num_vertices=4)
+neighbor_oracle = CQ.encode(graph, role="navigation")
+
+cycle = CQ.graph(edges=[(0, 1), (1, 2), (2, 3), (3, 0)], num_vertices=4)
+walk = CQ.primitive("coined_quantum_walk").build(cycle, steps=1)
+```
+
+## QC como circuito oficial
+
+```python
+from quantum_cq import CQ
+from quantum_cq.algorithms import twobit_block
+from quantum_cq.compact import QC, m, obs, sep
+
+uf0 = twobit_block(2)
+qc = QC(
+    "Deutsch",
+    [
+        [0, "-", "H", obs("pre_oracle"), uf0, sep("after_oracle"), "H", m(0)],
+        [0, "X", "H", obs("pre_oracle"), uf0, "-", "-", "-"],
+    ],
+    c=1,
+)
+
+same_qc = CQ.from_qc(qc)
+qiskit_circuit = CQ.to_qiskit(qc)
+metrics = CQ.metrics(qc)
+```
+
+## Exportacao
+
+```python
+qiskit_circuit = CQ.export(qc, target="qiskit")
+```
+
+Exportadores futuros como `mqt` e `openqasm` ainda levantam
+`NotImplementedError`; eles nao fingem implementacao parcial.
+
+## Encodings generalizados
+
+A arquitetura separa os papeis:
+
+- `StateEncoding`: dados classicos para estado quantico.
+- `OracleEncoding`: funcao ou predicado para oraculo.
+- `OperatorEncoding`: operador ou unitario reutilizavel.
+- `NavigationEncoding`: memoria enderecada ou grafo para acesso coerente.
+- `QuantumWalk`: dinamica unitaria sobre uma estrutura navegavel.
+
+`engine="qram_like"` simula a semantica logica de acesso QRAM-like, mas nao e
+QRAM fisico. A metadata marca `physical_qram=False`.
+
+## Logging
+
+A biblioteca escreve eventos operacionais no terminal por padrao.
+
+```python
+from quantum_cq import configure_logging
+
+configure_logging(level="INFO")
+```
+
+## Testes
+
+```powershell
+python -m pytest -q
+```

quantum_cq-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quantum-cq"
+version = "0.1.0"
+description = "Compact quantum circuit helpers, encodings, algorithms, navigation and Qiskit interop."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "José Yrikes de Oliveira Feitosa" },
+]
+keywords = ["quantum", "qiskit", "encoding", "quantum-circuits", "education"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "qiskit",
+    "numpy",
+    "packaging",
+]
+
+[project.optional-dependencies]
+aer = ["qiskit-aer"]
+ibm = ["qiskit-ibm-runtime"]
+notebook = ["pandas", "matplotlib", "ipython", "ipywidgets"]
+dev = ["pytest", "build", "twine"]
+all = [
+    "qiskit-aer",
+    "qiskit-ibm-runtime",
+    "pandas",
+    "matplotlib",
+    "ipython",
+    "ipywidgets",
+]
+
+[project.urls]
+Homepage = "https://github.com/jyrikes/quantum-cq"
+Repository = "https://github.com/jyrikes/quantum-cq"
+Issues = "https://github.com/jyrikes/quantum-cq/issues"
+
+[tool.setuptools]
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+markers = [
+    "real_hardware: tests that submit jobs to IBM Quantum hardware",
+    "ibm_real: opt-in integration tests that submit jobs to IBM Quantum hardware",
+]

quantum_cq-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

quantum_cq-0.1.0/setup.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+import shutil
+
+from setuptools import setup
+from setuptools.command.sdist import sdist as _sdist
+
+
+class sdist(_sdist):
+    def make_release_tree(self, base_dir, files):
+        super().make_release_tree(base_dir, files)
+        egg_info = Path(base_dir) / "src" / "quantum_cq.egg-info"
+        if egg_info.exists():
+            shutil.rmtree(egg_info)
+
+
+setup(cmdclass={"sdist": sdist})

quantum_cq-0.1.0/src/quantum_cq/__init__.py

@@ -0,0 +1,166 @@
+"""quantum_cq package."""
+
+from typing import TYPE_CHECKING
+
+from quantum_cq._core.facade import CQ
+from quantum_cq._core.data import QuantumData
+from quantum_cq._core.interfaces import (
+    AlgorithmBuilderProtocol,
+    AlgorithmHandler,
+    AlgorithmProtocol,
+    ArithmeticOracleProtocol,
+    BackendAdapter,
+    BackendAdapterProtocol,
+    BlockEncodingProtocol,
+    CircuitBuilderProtocol,
+    CircuitExporterProtocol,
+    CircuitFactoryProtocol,
+    CircuitLikeProtocol,
+    CompilerAdapterProtocol,
+    ControlledUnitaryProtocol,
+    DiffuserProtocol,
+    EncodingHandler,
+    EncodingProtocol,
+    EncodingSelectorProtocol,
+    FourierTransformProtocol,
+    GraphNavigationProtocol,
+    HamiltonianEncodingProtocol,
+    LinearSystemProblemProtocol,
+    NavigationEncodingProtocol,
+    MetricsCollectorProtocol,
+    OperatorProtocol,
+    OperatorEncodingProtocol,
+    OracleProtocol,
+    OracleEncodingProtocol,
+    PhaseOracleProtocol,
+    PipelineBuilderProtocol,
+    PowerableUnitaryProtocol,
+    PrimitiveProtocol,
+    PredicateOracleProtocol,
+    RegistryProtocol,
+    ResultHandler,
+    StateEncodingProtocol,
+    StatePreparationProtocol,
+    UnitaryProtocol,
+    AddressedEncodingProtocol,
+)
+from quantum_cq._core.logging_config import configure_logging
+from quantum_cq._navigation.memory import (
+    AddressedMemory,
+    AddressedMemoryEncoding,
+    GraphData,
+    GraphNavigationEncoding,
+)
+from quantum_cq._core.results import (
+    AlgorithmCircuit,
+    AlgorithmSpec,
+    CompilerResult,
+    EncodedCircuit,
+    NavigationCircuit,
+    OperatorCircuit,
+    OracleCircuit,
+    QuantumResult,
+)
+from quantum_cq._core.settings import (
+    PipelineSettings,
+    RuntimeSettings,
+    get_pipeline_settings,
+    get_runtime_settings,
+)
+from quantum_cq._runtime.runtime import IBMRuntimeConfig
+
+if TYPE_CHECKING:
+    from quantum_cq._runtime.experiment import (
+        ExperimentPlan,
+        ExperimentResult,
+        ExperimentSpec,
+        PipelineResult,
+    )
+    from quantum_cq._runtime.pipeline import BenchmarkingPipeline
+
+
+_LAZY_EXPORTS = {
+    "ExperimentPlan": ("quantum_cq._runtime.experiment", "ExperimentPlan"),
+    "ExperimentSpec": ("quantum_cq._runtime.experiment", "ExperimentSpec"),
+    "ExperimentResult": ("quantum_cq._runtime.experiment", "ExperimentResult"),
+    "PipelineResult": ("quantum_cq._runtime.experiment", "PipelineResult"),
+    "BenchmarkingPipeline": ("quantum_cq._runtime.pipeline", "BenchmarkingPipeline"),
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        module_name, attr_name = _LAZY_EXPORTS[name]
+        value = getattr(import_module(module_name), attr_name)
+        globals()[name] = value
+        return value
+
+    raise AttributeError(f"module 'quantum_cq' has no attribute {name!r}")
+
+__all__ = [
+    "CQ",
+    "QuantumData",
+    "QuantumResult",
+    "EncodedCircuit",
+    "AlgorithmCircuit",
+    "AlgorithmSpec",
+    "CompilerResult",
+    "OperatorCircuit",
+    "OracleCircuit",
+    "NavigationCircuit",
+    "AddressedMemory",
+    "AddressedMemoryEncoding",
+    "GraphData",
+    "GraphNavigationEncoding",
+    "ExperimentPlan",
+    "ExperimentSpec",
+    "ExperimentResult",
+    "PipelineResult",
+    "BenchmarkingPipeline",
+    "IBMRuntimeConfig",
+    "EncodingHandler",
+    "EncodingProtocol",
+    "StateEncodingProtocol",
+    "OracleEncodingProtocol",
+    "OperatorEncodingProtocol",
+    "NavigationEncodingProtocol",
+    "AddressedEncodingProtocol",
+    "GraphNavigationProtocol",
+    "AlgorithmBuilderProtocol",
+    "AlgorithmHandler",
+    "AlgorithmProtocol",
+    "ArithmeticOracleProtocol",
+    "BackendAdapter",
+    "BackendAdapterProtocol",
+    "BlockEncodingProtocol",
+    "CircuitBuilderProtocol",
+    "CircuitExporterProtocol",
+    "CircuitFactoryProtocol",
+    "CircuitLikeProtocol",
+    "CompilerAdapterProtocol",
+    "ControlledUnitaryProtocol",
+    "DiffuserProtocol",
+    "EncodingSelectorProtocol",
+    "FourierTransformProtocol",
+    "HamiltonianEncodingProtocol",
+    "LinearSystemProblemProtocol",
+    "RegistryProtocol",
+    "PipelineBuilderProtocol",
+    "MetricsCollectorProtocol",
+    "OperatorProtocol",
+    "PrimitiveProtocol",
+    "OracleProtocol",
+    "PhaseOracleProtocol",
+    "PowerableUnitaryProtocol",
+    "PredicateOracleProtocol",
+    "ResultHandler",
+    "StatePreparationProtocol",
+    "UnitaryProtocol",
+    "configure_logging",
+    "PipelineSettings",
+    "RuntimeSettings",
+    "get_pipeline_settings",
+    "get_runtime_settings",
+]