qpyd 0.1.0__tar.gz

qpyd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefanos Vasileiadis
+
+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.

qpyd-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: qpyd
+Version: 0.1.0
+Summary: A high-performance Python simulation framework for calculating charge transport in single quantum dot systems.
+Author-email: Stefanos Vasileiadis <stefanosvas2@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: sympy>=1.12
+Requires-Dist: jax>=0.4.13
+Requires-Dist: jaxlib>=0.4.13
+Requires-Dist: matplotlib>=3.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "dev"
+Dynamic: license-file
+
+# QPyD — Sequential Electron Transport Simulator for Quantum Dots
+
+![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)
+![JAX](https://img.shields.io/badge/JAX-Accelerated-FF6F00.svg)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+**QPyD** (imported as `qpyd`) is an open-source Python framework for simulating sequential electron transport in quantum dot devices.
+
+`qpyd` uses a steady-state rate equation (Pauli Master equation) approach to model sequential electron tunneling. Built on **JAX**, it utilizes XLA compilation and hardware-accelerated vectorization to process high-resolution Coulomb diamond stability diagrams instantly.
+
+## 🚀 Features
+
+* **Microscopic ED Engine (`DerivedParameters`):** Automatically constructs many-body Hamiltonians using Exact Diagonalization. Fully supports single-particle orbitals, intra/inter-orbital Coulomb interactions, exchange/pair-hopping, and Zeeman splitting.
+* **Macroscopic Phenomenological Engine (`DirectParameters`):** Bypass microscopic Hamiltonian setup to manually enforce arbitrary many-body state energies, spin labels, and transition spin degeneracies.
+* **JAX Backend:** The core Master equation solver uses `@jax.jit` and `jax.vmap` to solve steady-state probabilities across 2D voltage meshes.
+* **Memory-Safe Execution:** A hybrid chunking algorithm streams data directly to the CPU host, bypassing GPU VRAM bottlenecks on high-resolution grids.
+
+## ⚙️ Installation
+
+It is recommended to install this package in "editable" mode so that the `qpyd` module can be imported from anywhere on your system.
+
+```bash
+git clone https://github.com/stefv01/qpyd.git
+cd qpyd
+pip install -e .
+```
+
+## ⚡ Quick Start
+
+The package uses a factory pattern. Define your system parameters, pass them to Simulator(), and let the JAX backend handle the rest.
+
+```Python
+import numpy as np
+from qpyd import DerivedParameters, Simulator, Plotter
+
+# 1. Configure a 2-orbital quantum dot system
+params = DerivedParameters(
+    charge_numbers=[2, 3],      
+    orbital_energies=[1.0, 2.0],    
+    T=0.4, 
+    slopes=[1.0, 1.0],      
+    U=0.5 * np.ones(2),                  # Intra-orbital Coulomb
+    V=np.array([[0.0, 0.2],              # Inter-orbital Coulomb
+                [0.2, 0.0]]),        
+    J=0.0, Jp=0.0, B=[0.0, 0.0, 0.0],    # Exchange, Pair-hopping, Mag. field
+    gammas=[[1.0, 1.0], [1.0, 1.0]], 
+    setup="ground_R"
+)
+
+# 2. Solve the Master Equation
+sim = Simulator(params)
+sim.solve()
+results = sim.get_results()
+
+# 3. Visualize the Coulomb Diamonds
+plotter = Plotter()
+extent = [params.Vgmin, params.Vgmax, params.Vbmin, params.Vbmax]
+plotter.plot_heatmap(results['N_avg'], extent, title="Average Occupation")
+```
+
+## 📚 Documentation & Tutorials
+
+Interested in learning more about how QPyD works? Please check the documentation:
+
+* [Getting Started](docs/getting_started.md)
+* [Theoretical Description](docs/theoretical_description.md)
+* [API Reference & Parameter Mapping](docs/api_reference.md)
+* [Interactive Tutorials (Jupyter Notebooks)](tutorials/)
+
+## 🎓 Acknowledgements
+
+This project is an extension of my MSc thesis project *"Electronic Transport Analysis of Atomically Precise Armchair Graphene Nanoribbons"* at TU Delft, under the supervision of Herre S.J. van der Zant and Yongqing Yang. Special thanks to Jaime Ferrer (Universidad de Oviedo). His analytical calculations for Armchair Graphene Nanoribbons guided and inspired the development of the generalized Quantum Dot Hamiltonian implemented in this simulator.
+
+*Note: Users interested in alternate perturbative transport methods are highly encouraged to refer to the open-source QmeQ package (Kiršanskas et al., 2017).*
+
+## 📄 License
+
+This project is licensed under the MIT License.

qpyd-0.1.0/README.md

@@ -0,0 +1,78 @@
+# QPyD — Sequential Electron Transport Simulator for Quantum Dots
+
+![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)
+![JAX](https://img.shields.io/badge/JAX-Accelerated-FF6F00.svg)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+**QPyD** (imported as `qpyd`) is an open-source Python framework for simulating sequential electron transport in quantum dot devices.
+
+`qpyd` uses a steady-state rate equation (Pauli Master equation) approach to model sequential electron tunneling. Built on **JAX**, it utilizes XLA compilation and hardware-accelerated vectorization to process high-resolution Coulomb diamond stability diagrams instantly.
+
+## 🚀 Features
+
+* **Microscopic ED Engine (`DerivedParameters`):** Automatically constructs many-body Hamiltonians using Exact Diagonalization. Fully supports single-particle orbitals, intra/inter-orbital Coulomb interactions, exchange/pair-hopping, and Zeeman splitting.
+* **Macroscopic Phenomenological Engine (`DirectParameters`):** Bypass microscopic Hamiltonian setup to manually enforce arbitrary many-body state energies, spin labels, and transition spin degeneracies.
+* **JAX Backend:** The core Master equation solver uses `@jax.jit` and `jax.vmap` to solve steady-state probabilities across 2D voltage meshes.
+* **Memory-Safe Execution:** A hybrid chunking algorithm streams data directly to the CPU host, bypassing GPU VRAM bottlenecks on high-resolution grids.
+
+## ⚙️ Installation
+
+It is recommended to install this package in "editable" mode so that the `qpyd` module can be imported from anywhere on your system.
+
+```bash
+git clone https://github.com/stefv01/qpyd.git
+cd qpyd
+pip install -e .
+```
+
+## ⚡ Quick Start
+
+The package uses a factory pattern. Define your system parameters, pass them to Simulator(), and let the JAX backend handle the rest.
+
+```Python
+import numpy as np
+from qpyd import DerivedParameters, Simulator, Plotter
+
+# 1. Configure a 2-orbital quantum dot system
+params = DerivedParameters(
+    charge_numbers=[2, 3],      
+    orbital_energies=[1.0, 2.0],    
+    T=0.4, 
+    slopes=[1.0, 1.0],      
+    U=0.5 * np.ones(2),                  # Intra-orbital Coulomb
+    V=np.array([[0.0, 0.2],              # Inter-orbital Coulomb
+                [0.2, 0.0]]),        
+    J=0.0, Jp=0.0, B=[0.0, 0.0, 0.0],    # Exchange, Pair-hopping, Mag. field
+    gammas=[[1.0, 1.0], [1.0, 1.0]], 
+    setup="ground_R"
+)
+
+# 2. Solve the Master Equation
+sim = Simulator(params)
+sim.solve()
+results = sim.get_results()
+
+# 3. Visualize the Coulomb Diamonds
+plotter = Plotter()
+extent = [params.Vgmin, params.Vgmax, params.Vbmin, params.Vbmax]
+plotter.plot_heatmap(results['N_avg'], extent, title="Average Occupation")
+```
+
+## 📚 Documentation & Tutorials
+
+Interested in learning more about how QPyD works? Please check the documentation:
+
+* [Getting Started](docs/getting_started.md)
+* [Theoretical Description](docs/theoretical_description.md)
+* [API Reference & Parameter Mapping](docs/api_reference.md)
+* [Interactive Tutorials (Jupyter Notebooks)](tutorials/)
+
+## 🎓 Acknowledgements
+
+This project is an extension of my MSc thesis project *"Electronic Transport Analysis of Atomically Precise Armchair Graphene Nanoribbons"* at TU Delft, under the supervision of Herre S.J. van der Zant and Yongqing Yang. Special thanks to Jaime Ferrer (Universidad de Oviedo). His analytical calculations for Armchair Graphene Nanoribbons guided and inspired the development of the generalized Quantum Dot Hamiltonian implemented in this simulator.
+
+*Note: Users interested in alternate perturbative transport methods are highly encouraged to refer to the open-source QmeQ package (Kiršanskas et al., 2017).*
+
+## 📄 License
+
+This project is licensed under the MIT License.

qpyd-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qpyd"
+version = "0.1.0"
+description = "A high-performance Python simulation framework for calculating charge transport in single quantum dot systems."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Stefanos Vasileiadis", email = "stefanosvas2@gmail.com"} 
+]
+dependencies = [
+    "numpy>=1.24.0",
+    "sympy>=1.12",
+    "jax>=0.4.13",
+    "jaxlib>=0.4.13",
+    "matplotlib>=3.7.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "mkdocs-material>=9.0.0"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+packages = ["qpyd"]

qpyd-0.1.0/setup.cfg

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

qpyd-0.1.0/src/qpyd/__init__.py

@@ -0,0 +1,28 @@
+# Parameter Classes
+from .parameters import (
+    BaseParameters,
+    DirectParameters,
+    DerivedParameters
+)
+
+# Simulator Engines & Factory
+from .simulator import (
+    SimulatorBase,
+    DirectSimulator,
+    DerivedSimulator,
+    Simulator
+)
+
+# Plotting Utilities
+from .plotter import Plotter
+
+__all__ = [
+    "BaseParameters",
+    "DirectParameters",
+    "DerivedParameters",
+    "SimulatorBase",
+    "DirectSimulator",
+    "DerivedSimulator",
+    "Simulator",
+    "Plotter"
+]

qpyd-0.1.0/src/qpyd/datatypes.py

@@ -0,0 +1,28 @@
+import numpy as np
+from typing import TypedDict
+
+
+class StateProperties(TypedDict):
+    """
+    Dictionary structure containing the physical properties of a computed eigenstate.
+
+    Attributes
+    ----------
+    eigenstate : str
+        A rigidly ordered string representation of the many-body state.
+    single_particle_kets : list of tuple of (float or complex, str, np.ndarray)
+        A list of tuples representing the constituent many-body states expressed 
+        in the single-particle basis. Each tuple is formatted as 
+        `(amplitude, ket_string, ket_array)`.
+    energy : float
+        The calculated eigenenergy of the state.
+    S : float
+        The total spin quantum number.
+    Sz : float
+        The total spin projection quantum number.
+    """
+    eigenstate: str
+    single_particle_kets: list[tuple[float | complex, str, np.ndarray]]
+    energy: float
+    S: float
+    Sz: float