sccircuits 0.1.0__tar.gz

sccircuits-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Joan Caceres
+
+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.

sccircuits-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: sccircuits
+Version: 0.1.0
+Summary: Superconducting Circuit Analysis Package
+Author-email: Joan Caceres <contact@joancaceres.com>
+License-Expression: MIT
+Project-URL: Homepage, https://joanjcaceres.github.io/sccircuits/
+Project-URL: Repository, https://github.com/joanjcaceres/sccircuits
+Project-URL: Documentation, https://joanjcaceres.github.io/sccircuits/
+Project-URL: Issues, https://github.com/joanjcaceres/sccircuits/issues
+Keywords: superconducting circuits,quantum circuits,circuit quantization,BBQ,black box quantization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=2.3
+Requires-Dist: scipy<2,>=1.15
+Requires-Dist: matplotlib<4,>=3.10
+Requires-Dist: sympy<2,>=1.13
+Requires-Dist: PyYAML<7,>=6
+Provides-Extra: interactive
+Requires-Dist: ipywidgets<9,>=8.1; extra == "interactive"
+Requires-Dist: IPython<10,>=9; extra == "interactive"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
+Requires-Dist: pymdown-extensions<11,>=10.8; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: pytest<9,>=8.4; extra == "dev"
+Requires-Dist: pytest-cov<7,>=5; extra == "dev"
+Requires-Dist: ruff<1,>=0.12; extra == "dev"
+Requires-Dist: mypy<2,>=1.16; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+Requires-Dist: jupyter<2,>=1; extra == "dev"
+Requires-Dist: notebook<8,>=7; extra == "dev"
+Dynamic: license-file
+
+# SCCircuits
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17751124.svg)](https://doi.org/10.5281/zenodo.17751124)
+
+SCCircuits is a Python package for numerical superconducting-circuit analysis.
+It focuses on matrix-based black-box quantization, dense Hamiltonian
+construction, spectroscopy workflows, and small research utilities for
+superconducting quantum circuits.
+
+## Documentation
+
+The user-facing documentation is published at:
+
+[https://joanjcaceres.github.io/sccircuits/](https://joanjcaceres.github.io/sccircuits/)
+
+Recommended starting points:
+
+- [BBQ Overview](https://joanjcaceres.github.io/sccircuits/bbq/) explains the practical workflow from cQEDraw or circuit matrices to `BBQ` results.
+- [BBQ Quickstart](https://joanjcaceres.github.io/sccircuits/bbq/quickstart/) gives a runnable matrix example with frequencies and phase ZPFs.
+- [BBQ Examples](https://joanjcaceres.github.io/sccircuits/bbq/examples/) collects worked examples and the planned cQEDraw project-download example.
+- [BBQ Validation](https://joanjcaceres.github.io/sccircuits/bbq/validation/) explains the code-backed checks behind the matrix reductions and branch conventions.
+- [BBQ Implementation Notes](https://joanjcaceres.github.io/sccircuits/bbq/implementation-notes/) maps the mathematical derivation to the current `BBQ` implementation stages.
+- [BBQ API](https://joanjcaceres.github.io/sccircuits/api/bbq/) shows how to call `sccircuits.BBQ`, read frequencies and phase ZPFs, and build Hamiltonians.
+- [Circuit Matrix Quantization](https://joanjcaceres.github.io/sccircuits/theory/circuit-matrix-quantization/) documents the matrix reductions, mode normalization, units, and branch phase zero-point fluctuations.
+
+The site is intentionally incremental. `BBQ` is the first fully documented
+research workflow because it is currently the most mature path between cQEDraw
+and SCCircuits. The rest of the package should be documented through the same
+site as those workflows stabilize.
+
+The Markdown source for the website lives in `docs/`. Build it locally with:
+
+```bash
+pixi run -e sccircuits docs-build
+```
+
+## Companion GUI
+
+[`cQEDraw`](https://cqedraw.org/) is the companion web app for drawing and
+analyzing superconducting circuit graphs. A typical workflow is:
+
+1. Draw the circuit in cQEDraw.
+2. Export or copy the generated capacitance matrix, inverse-inductance matrix,
+   and Josephson junction records.
+3. Pass those matrices and records to `sccircuits.BBQ`.
+4. Inspect mode frequencies, branch phase ZPFs, and Hamiltonian spectra in
+   Python.
+
+## Installation
+
+### Recommended: pip
+
+Researchers should install SCCircuits from PyPI:
+
+```bash
+python -m pip install sccircuits
+```
+
+This installs the pure-Python SCCircuits package plus NumPy, SciPy,
+Matplotlib, SymPy, and PyYAML from normal Python wheels. Pixi is not required
+to use the package.
+
+Optional extras are available for notebook widgets, development, and docs:
+
+```bash
+python -m pip install "sccircuits[interactive]"
+python -m pip install "sccircuits[dev]"
+python -m pip install "sccircuits[docs]"
+```
+
+### Development: Pixi
+
+Pixi remains the recommended contributor environment because it keeps the
+NumPy/SciPy stack reproducible while developing and testing the repository.
+
+```bash
+git clone https://github.com/joanjcaceres/sccircuits.git
+cd sccircuits
+pixi run -e sccircuits install-dev
+pixi run -e sccircuits test
+```
+
+For local editable development without Pixi:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev,interactive,docs]"
+```
+
+### Performance Baseline
+
+SCCircuits relies on NumPy and SciPy wheels for cross-platform BLAS/LAPACK
+linear algebra. The first public package does not compile native extensions or
+require GPU-specific backends.
+
+To record a quick local diagonalization baseline:
+
+```bash
+python benchmarks/diagonalization_smoke.py
+```
+
+## Quick Example
+
+```python
+import numpy as np
+from sccircuits import BBQ
+
+capacitance_matrix = np.array(
+    [
+        [40e-15, -32.9e-15],
+        [-32.9e-15, 40e-15],
+    ]
+)
+
+inverse_inductance_matrix = np.array(
+    [
+        [1 / 1.23e-9, 0.0],
+        [0.0, 1 / 1.23e-9],
+    ]
+)
+
+bbq = BBQ(
+    capacitance_matrix,
+    inverse_inductance_matrix,
+    nonlinear_branches=(0, 1),
+)
+
+print("Mode frequencies in GHz:", bbq.frequencies_ghz)
+print("Branch phase ZPFs:", bbq.branch_phase_zpfs)
+```
+
+For cQEDraw exports with Josephson junction records, pass the records directly:
+
+```python
+bbq = BBQ(
+    capacitance_matrix,
+    inverse_inductance_matrix,
+    junctions=junctions,
+)
+```
+
+`BBQ` keeps the junction row order when reporting `branch_phase_zpfs` and
+`josephson_energies_ghz`, so drawing tools can map results back to the original
+branches.
+
+## Core Modules
+
+- `sccircuits.BBQ`: black-box quantization from capacitance and inverse-inductance matrices.
+- `sccircuits.Circuit`: dense superconducting-circuit Hamiltonian construction and diagonalization.
+- `sccircuits.TransitionFitter`: transition-frequency fitting utilities.
+- `sccircuits.PointPicker`: interactive point selection for data analysis.
+
+## Development
+
+Run the main checks with:
+
+```bash
+pixi run -e sccircuits test
+pixi run -e sccircuits lint
+pixi run -e sccircuits docs-build
+```
+
+Check the pip package path with:
+
+```bash
+python -m build
+python -m twine check dist/*
+python -m pip install dist/sccircuits-0.1.0-py3-none-any.whl
+python -m pip check
+python tests/pip_smoke.py
+```
+
+If dependency resolution becomes inconsistent, recreate the Pixi environment:
+
+```bash
+pixi clean
+pixi run -e sccircuits install-dev
+```
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.
+
+## Contact
+
+Joan Caceres - contact@joanjcaceres.com
+
+Project link: [https://github.com/joanjcaceres/sccircuits](https://github.com/joanjcaceres/sccircuits)

sccircuits-0.1.0/README.md

@@ -0,0 +1,189 @@
+# SCCircuits
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17751124.svg)](https://doi.org/10.5281/zenodo.17751124)
+
+SCCircuits is a Python package for numerical superconducting-circuit analysis.
+It focuses on matrix-based black-box quantization, dense Hamiltonian
+construction, spectroscopy workflows, and small research utilities for
+superconducting quantum circuits.
+
+## Documentation
+
+The user-facing documentation is published at:
+
+[https://joanjcaceres.github.io/sccircuits/](https://joanjcaceres.github.io/sccircuits/)
+
+Recommended starting points:
+
+- [BBQ Overview](https://joanjcaceres.github.io/sccircuits/bbq/) explains the practical workflow from cQEDraw or circuit matrices to `BBQ` results.
+- [BBQ Quickstart](https://joanjcaceres.github.io/sccircuits/bbq/quickstart/) gives a runnable matrix example with frequencies and phase ZPFs.
+- [BBQ Examples](https://joanjcaceres.github.io/sccircuits/bbq/examples/) collects worked examples and the planned cQEDraw project-download example.
+- [BBQ Validation](https://joanjcaceres.github.io/sccircuits/bbq/validation/) explains the code-backed checks behind the matrix reductions and branch conventions.
+- [BBQ Implementation Notes](https://joanjcaceres.github.io/sccircuits/bbq/implementation-notes/) maps the mathematical derivation to the current `BBQ` implementation stages.
+- [BBQ API](https://joanjcaceres.github.io/sccircuits/api/bbq/) shows how to call `sccircuits.BBQ`, read frequencies and phase ZPFs, and build Hamiltonians.
+- [Circuit Matrix Quantization](https://joanjcaceres.github.io/sccircuits/theory/circuit-matrix-quantization/) documents the matrix reductions, mode normalization, units, and branch phase zero-point fluctuations.
+
+The site is intentionally incremental. `BBQ` is the first fully documented
+research workflow because it is currently the most mature path between cQEDraw
+and SCCircuits. The rest of the package should be documented through the same
+site as those workflows stabilize.
+
+The Markdown source for the website lives in `docs/`. Build it locally with:
+
+```bash
+pixi run -e sccircuits docs-build
+```
+
+## Companion GUI
+
+[`cQEDraw`](https://cqedraw.org/) is the companion web app for drawing and
+analyzing superconducting circuit graphs. A typical workflow is:
+
+1. Draw the circuit in cQEDraw.
+2. Export or copy the generated capacitance matrix, inverse-inductance matrix,
+   and Josephson junction records.
+3. Pass those matrices and records to `sccircuits.BBQ`.
+4. Inspect mode frequencies, branch phase ZPFs, and Hamiltonian spectra in
+   Python.
+
+## Installation
+
+### Recommended: pip
+
+Researchers should install SCCircuits from PyPI:
+
+```bash
+python -m pip install sccircuits
+```
+
+This installs the pure-Python SCCircuits package plus NumPy, SciPy,
+Matplotlib, SymPy, and PyYAML from normal Python wheels. Pixi is not required
+to use the package.
+
+Optional extras are available for notebook widgets, development, and docs:
+
+```bash
+python -m pip install "sccircuits[interactive]"
+python -m pip install "sccircuits[dev]"
+python -m pip install "sccircuits[docs]"
+```
+
+### Development: Pixi
+
+Pixi remains the recommended contributor environment because it keeps the
+NumPy/SciPy stack reproducible while developing and testing the repository.
+
+```bash
+git clone https://github.com/joanjcaceres/sccircuits.git
+cd sccircuits
+pixi run -e sccircuits install-dev
+pixi run -e sccircuits test
+```
+
+For local editable development without Pixi:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev,interactive,docs]"
+```
+
+### Performance Baseline
+
+SCCircuits relies on NumPy and SciPy wheels for cross-platform BLAS/LAPACK
+linear algebra. The first public package does not compile native extensions or
+require GPU-specific backends.
+
+To record a quick local diagonalization baseline:
+
+```bash
+python benchmarks/diagonalization_smoke.py
+```
+
+## Quick Example
+
+```python
+import numpy as np
+from sccircuits import BBQ
+
+capacitance_matrix = np.array(
+    [
+        [40e-15, -32.9e-15],
+        [-32.9e-15, 40e-15],
+    ]
+)
+
+inverse_inductance_matrix = np.array(
+    [
+        [1 / 1.23e-9, 0.0],
+        [0.0, 1 / 1.23e-9],
+    ]
+)
+
+bbq = BBQ(
+    capacitance_matrix,
+    inverse_inductance_matrix,
+    nonlinear_branches=(0, 1),
+)
+
+print("Mode frequencies in GHz:", bbq.frequencies_ghz)
+print("Branch phase ZPFs:", bbq.branch_phase_zpfs)
+```
+
+For cQEDraw exports with Josephson junction records, pass the records directly:
+
+```python
+bbq = BBQ(
+    capacitance_matrix,
+    inverse_inductance_matrix,
+    junctions=junctions,
+)
+```
+
+`BBQ` keeps the junction row order when reporting `branch_phase_zpfs` and
+`josephson_energies_ghz`, so drawing tools can map results back to the original
+branches.
+
+## Core Modules
+
+- `sccircuits.BBQ`: black-box quantization from capacitance and inverse-inductance matrices.
+- `sccircuits.Circuit`: dense superconducting-circuit Hamiltonian construction and diagonalization.
+- `sccircuits.TransitionFitter`: transition-frequency fitting utilities.
+- `sccircuits.PointPicker`: interactive point selection for data analysis.
+
+## Development
+
+Run the main checks with:
+
+```bash
+pixi run -e sccircuits test
+pixi run -e sccircuits lint
+pixi run -e sccircuits docs-build
+```
+
+Check the pip package path with:
+
+```bash
+python -m build
+python -m twine check dist/*
+python -m pip install dist/sccircuits-0.1.0-py3-none-any.whl
+python -m pip check
+python tests/pip_smoke.py
+```
+
+If dependency resolution becomes inconsistent, recreate the Pixi environment:
+
+```bash
+pixi clean
+pixi run -e sccircuits install-dev
+```
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.
+
+## Contact
+
+Joan Caceres - contact@joanjcaceres.com
+
+Project link: [https://github.com/joanjcaceres/sccircuits](https://github.com/joanjcaceres/sccircuits)

sccircuits-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sccircuits"
+version = "0.1.0"
+description = "Superconducting Circuit Analysis Package"
+readme = "README.md"
+authors = [
+    {name = "Joan Caceres", email = "contact@joancaceres.com"}
+]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13"
+]
+keywords = ["superconducting circuits", "quantum circuits", "circuit quantization", "BBQ", "black box quantization"]
+requires-python = ">=3.11"
+
+dependencies = [
+    "numpy>=2.3,<3",
+    "scipy>=1.15,<2",
+    "matplotlib>=3.10,<4",
+    "sympy>=1.13,<2",
+    "PyYAML>=6,<7",
+]
+
+[project.optional-dependencies]
+interactive = [
+    "ipywidgets>=8.1,<9",
+    "IPython>=9,<10"
+]
+docs = [
+    "mkdocs>=1.6,<2",
+    "mkdocs-material>=9.5,<10",
+    "pymdown-extensions>=10.8,<11",
+]
+dev = [
+    "build>=1.2,<2",
+    "pytest>=8.4,<9",
+    "pytest-cov>=5,<7",
+    "ruff>=0.12,<1",
+    "mypy>=1.16,<2",
+    "twine>=6,<7",
+    "jupyter>=1,<2",
+    "notebook>=7,<8"
+]
+
+[project.urls]
+Homepage = "https://joanjcaceres.github.io/sccircuits/"
+Repository = "https://github.com/joanjcaceres/sccircuits"
+Documentation = "https://joanjcaceres.github.io/sccircuits/"
+Issues = "https://github.com/joanjcaceres/sccircuits/issues"
+
+[tool.setuptools]
+packages = ["sccircuits"]
+
+[tool.setuptools.package-data]
+sccircuits = ["*.py"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"

sccircuits-0.1.0/sccircuits/__init__.py

@@ -0,0 +1,75 @@
+"""
+SCCircuits - Superconducting Circuit Analysis Package
+
+A comprehensive Python package for analyzing superconducting quantum circuits,
+including chain-based circuit models, Black Box Quantization (BBQ), and
+spectroscopy-fitting workflows.
+
+Main Classes:
+    Circuit: Main circuit class for superconducting quantum circuits
+    BBQ: Black Box Quantization analysis
+    TransitionFitter: General transition frequency fitting
+    FitAnalysis: Post-fit diagnostics for least-squares results
+    PointPicker: Interactive point selection tool for data analysis
+
+Utilities:
+    lanczos_krylov: Lanczos algorithm for Hermitian matrices
+    IterativeHamiltonianDiagonalizer: Multi-mode Hamiltonian diagonalization
+"""
+
+__version__ = "0.1.0"
+__author__ = "Joan Caceres"
+__email__ = "contact@joancaceres.com"
+
+# Core circuit analysis classes
+from .circuit import Circuit
+from .bbq import BBQ
+
+# Fitting and analysis tools
+from .transition_fitter import TransitionFitter
+from .pointpicker import PointPicker
+from .fit_analysis import FitAnalysis
+
+# Numerical utilities
+from .iterative_diagonalizer import IterativeHamiltonianDiagonalizer
+from .utilities import lanczos_krylov
+
+# Public API - what gets imported with "from sccircuits import *"
+__all__ = [
+    # Core classes
+    "Circuit",
+    "BBQ",
+    # Analysis tools
+    "TransitionFitter",
+    "PointPicker",
+    "FitAnalysis",
+    # Utilities
+    "IterativeHamiltonianDiagonalizer",
+    "lanczos_krylov",
+    # Package metadata
+    "__version__",
+    "__author__",
+    "__email__",
+]
+
+
+# Package information
+def get_version():
+    """Return the version of the sccircuits package."""
+    return __version__
+
+
+def get_info():
+    """Return basic information about the sccircuits package."""
+    return {
+        "name": "sccircuits",
+        "version": __version__,
+        "author": __author__,
+        "description": "Superconducting Circuit Analysis Package",
+        "main_classes": [
+            "Circuit",
+            "BBQ",
+            "TransitionFitter",
+            "FitAnalysis",
+        ],
+    }