openquantumsim 0.1.0a1__py3-none-any.whl

openquantumsim/__init__.py

@@ -0,0 +1,202 @@
+"""OpenQuantumSim public Python API."""
+
+from ._version import __version__
+from .correlations import correlation_2op_1t, correlation_2op_2t
+from .hilbert import CompositeSpace, DickeSpace, FockSpace, HilbertSpace, SpinSpace
+from .observables import (
+    StateObservable,
+    bipartite_mutual_information,
+    bloch_observables,
+    bloch_vector,
+    bures_angle,
+    bures_distance,
+    entropy_observable,
+    evaluate_state_observables,
+    expect,
+    fidelity,
+    fidelity_observable,
+    hilbert_schmidt_distance,
+    infidelity,
+    is_density_matrix,
+    is_hermitian,
+    l1_coherence,
+    l1_coherence_observable,
+    linear_entropy,
+    linear_entropy_observable,
+    mutual_information,
+    normalize_state,
+    partial_trace,
+    partial_traces,
+    participation_ratio,
+    participation_ratio_observable,
+    population_observable,
+    population_observables,
+    populations,
+    purity,
+    purity_observable,
+    renyi_entropy,
+    state_metrics,
+    trace_distance,
+    trace_distance_observable,
+    trace_norm,
+    von_neumann_entropy,
+)
+from .operators import (
+    Operator,
+    basis,
+    coherent,
+    collective_excitation,
+    collective_lowering,
+    collective_raising,
+    collective_x,
+    collective_z,
+    create,
+    destroy,
+    dicke_excitation,
+    dicke_jm,
+    dicke_jp,
+    dicke_jx,
+    dicke_jz,
+    dicke_state,
+    eye,
+    fock,
+    ket2dm,
+    num,
+    sigmam,
+    sigmap,
+    sigmax,
+    sigmay,
+    sigmaz,
+    spin_jm,
+    spin_jp,
+    spin_jx,
+    spin_jz,
+    tensor,
+    thermal_dm,
+)
+from .phase_space import phase_space_grid, q_function, wigner
+from .plot import (
+    expect_plot,
+    plot_density_matrix,
+    plot_expectations,
+    plot_phase_space,
+    plot_q_function,
+    plot_state_observable,
+    plot_wigner,
+)
+from .result import Options, QuantumSystem, Result, load_result
+from .solvers import mcsolve, mesolve, single_trajectory, steadystate
+from .sweep import ParameterSweep, SweepPoint, SweepRunResult
+from .systems import JaynesCummingsSystem, MCWFSystem, jaynes_cummings_system
+from .timedep import (
+    HamiltonianTerm,
+    InterpolatedCoefficient,
+    TimeDependentHamiltonian,
+    time_dependent_hamiltonian,
+)
+
+__all__ = [
+    "__version__",
+    "CompositeSpace",
+    "DickeSpace",
+    "FockSpace",
+    "HamiltonianTerm",
+    "HilbertSpace",
+    "InterpolatedCoefficient",
+    "JaynesCummingsSystem",
+    "MCWFSystem",
+    "Operator",
+    "Options",
+    "ParameterSweep",
+    "QuantumSystem",
+    "Result",
+    "StateObservable",
+    "SpinSpace",
+    "SweepPoint",
+    "SweepRunResult",
+    "TimeDependentHamiltonian",
+    "basis",
+    "bipartite_mutual_information",
+    "bloch_vector",
+    "bloch_observables",
+    "bures_angle",
+    "bures_distance",
+    "coherent",
+    "collective_excitation",
+    "collective_lowering",
+    "collective_raising",
+    "collective_x",
+    "collective_z",
+    "correlation_2op_1t",
+    "correlation_2op_2t",
+    "create",
+    "destroy",
+    "dicke_excitation",
+    "dicke_jm",
+    "dicke_jp",
+    "dicke_jx",
+    "dicke_jz",
+    "dicke_state",
+    "entropy_observable",
+    "evaluate_state_observables",
+    "expect",
+    "expect_plot",
+    "fidelity",
+    "fidelity_observable",
+    "eye",
+    "fock",
+    "hilbert_schmidt_distance",
+    "infidelity",
+    "is_density_matrix",
+    "is_hermitian",
+    "ket2dm",
+    "jaynes_cummings_system",
+    "l1_coherence",
+    "l1_coherence_observable",
+    "linear_entropy",
+    "linear_entropy_observable",
+    "load_result",
+    "mcsolve",
+    "mesolve",
+    "mutual_information",
+    "normalize_state",
+    "num",
+    "partial_trace",
+    "partial_traces",
+    "participation_ratio",
+    "participation_ratio_observable",
+    "phase_space_grid",
+    "plot_density_matrix",
+    "plot_expectations",
+    "plot_phase_space",
+    "plot_q_function",
+    "plot_state_observable",
+    "plot_wigner",
+    "population_observable",
+    "population_observables",
+    "populations",
+    "purity",
+    "purity_observable",
+    "q_function",
+    "renyi_entropy",
+    "sigmam",
+    "sigmap",
+    "single_trajectory",
+    "spin_jm",
+    "spin_jp",
+    "spin_jx",
+    "spin_jz",
+    "sigmax",
+    "sigmay",
+    "sigmaz",
+    "steadystate",
+    "state_metrics",
+    "tensor",
+    "thermal_dm",
+    "time_dependent_hamiltonian",
+    "trace_distance",
+    "trace_distance_observable",
+    "trace_norm",
+    "von_neumann_entropy",
+    "wigner",
+]

openquantumsim/_julia_bridge.py

@@ -0,0 +1,80 @@
+"""Lazy Julia backend bridge.
+
+The bridge intentionally imports `juliacall` lazily so ordinary Python-side
+operator work and tests do not pay Julia startup cost.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+class JuliaBridgeUnavailable(RuntimeError):
+    """Raised when the Julia backend cannot be loaded."""
+
+
+_JL: Any | None = None
+_BACKEND: Any | None = None
+
+
+def backend_path() -> Path:
+    """Return the Julia backend package path."""
+    package_path = Path(__file__).resolve().parent / "julia" / "OpenQuantumSimJL"
+    dev_path = Path(__file__).resolve().parents[1] / "src" / "OpenQuantumSimJL"
+    if dev_path.exists():
+        return dev_path
+    return package_path
+
+
+def get_julia() -> Any:
+    """Return the `juliacall.Main` object, importing it on first use."""
+    global _JL
+    if _JL is not None:
+        return _JL
+    try:
+        from juliacall import Main as jl  # type: ignore[import-untyped]
+    except Exception as exc:  # pragma: no cover - depends on local Julia setup
+        msg = "juliacall is required to use the Julia backend."
+        raise JuliaBridgeUnavailable(msg) from exc
+    _JL = jl
+    return jl
+
+
+def load_backend() -> Any:
+    """Activate and load the `OpenQuantumSimJL` backend module."""
+    global _BACKEND
+    if _BACKEND is not None:
+        return _BACKEND
+
+    jl = get_julia()
+    path = str(backend_path())
+    try:
+        jl.seval("using Pkg")
+        jl.Pkg.activate(path)
+        _instantiate_and_load_backend(jl)
+        _BACKEND = jl.OpenQuantumSimJL
+    except Exception as exc:  # pragma: no cover - depends on local Julia setup
+        msg = f"Unable to load Julia backend from {path}."
+        raise JuliaBridgeUnavailable(msg) from exc
+    return _BACKEND
+
+
+def _instantiate_and_load_backend(jl: Any) -> None:
+    """Instantiate/load the backend, resolving stale manifests on retry."""
+    try:
+        jl.Pkg.instantiate()
+        jl.seval("using OpenQuantumSimJL")
+    except Exception:
+        jl.Pkg.resolve()
+        jl.Pkg.instantiate()
+        jl.seval("using OpenQuantumSimJL")
+
+
+def backend_available() -> bool:
+    """Return whether the Julia backend can be loaded."""
+    try:
+        load_backend()
+    except JuliaBridgeUnavailable:
+        return False
+    return True

openquantumsim/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.1.0a1"

openquantumsim/correlations.py

@@ -0,0 +1,144 @@
+"""Two-time correlation functions via the quantum regression theorem."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import cast
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ._julia_bridge import JuliaBridgeUnavailable, load_backend
+from .operators import Operator
+from .result import Options
+
+Array = NDArray[np.complex128]
+FloatArray = NDArray[np.float64]
+
+
+def correlation_2op_1t(
+    H: Operator,
+    rho0: Array,
+    taulist: Sequence[float],
+    a_op: Operator,
+    b_op: Operator,
+    *,
+    c_ops: Sequence[Operator] | None = None,
+    options: Options | None = None,
+) -> Array:
+    """Return ``<A(tau) B(0)>`` using quantum regression.
+
+    This first implementation supports time-independent Lindblad systems.
+    """
+    opts = options or Options()
+    rho0_array = np.asarray(rho0, dtype=np.complex128)
+    taus = np.asarray(taulist, dtype=np.float64)
+    c_arrays = [op.to_numpy() for op in c_ops or []]
+    _validate_correlation_inputs(H, rho0_array, taus, a_op, b_op, c_arrays, "taulist")
+
+    try:
+        backend = load_backend()
+    except JuliaBridgeUnavailable as exc:
+        msg = "correlation_2op_1t requires the Julia backend; run setup_julia.py first."
+        raise NotImplementedError(msg) from exc
+
+    raw = backend.correlation_2op_1t(
+        H.to_numpy(),
+        rho0_array,
+        taus,
+        a_op.to_numpy(),
+        b_op.to_numpy(),
+        c_arrays,
+        rtol=float(opts.rtol),
+        atol=float(opts.atol),
+        method=str(opts.method),
+        krylov_dim=int(opts.krylov_dim),
+    )
+    return np.asarray(_field(raw, "correlations"), dtype=np.complex128)
+
+
+def correlation_2op_2t(
+    H: Operator,
+    rho0: Array,
+    tlist: Sequence[float],
+    taulist: Sequence[float],
+    a_op: Operator,
+    b_op: Operator,
+    *,
+    c_ops: Sequence[Operator] | None = None,
+    options: Options | None = None,
+) -> Array:
+    """Return ``<A(t + tau) B(t)>`` for each ``t`` and ``tau``."""
+    opts = options or Options()
+    rho0_array = np.asarray(rho0, dtype=np.complex128)
+    times = np.asarray(tlist, dtype=np.float64)
+    taus = np.asarray(taulist, dtype=np.float64)
+    c_arrays = [op.to_numpy() for op in c_ops or []]
+    _validate_correlation_inputs(H, rho0_array, times, a_op, b_op, c_arrays, "tlist")
+    _validate_nonnegative_sorted_times(taus, "taulist")
+
+    try:
+        backend = load_backend()
+    except JuliaBridgeUnavailable as exc:
+        msg = "correlation_2op_2t requires the Julia backend; run setup_julia.py first."
+        raise NotImplementedError(msg) from exc
+
+    raw = backend.correlation_2op_2t(
+        H.to_numpy(),
+        rho0_array,
+        times,
+        taus,
+        a_op.to_numpy(),
+        b_op.to_numpy(),
+        c_arrays,
+        rtol=float(opts.rtol),
+        atol=float(opts.atol),
+        method=str(opts.method),
+        krylov_dim=int(opts.krylov_dim),
+    )
+    return np.asarray(_field(raw, "correlations"), dtype=np.complex128)
+
+
+def _validate_correlation_inputs(
+    H: Operator,
+    rho0: Array,
+    times: FloatArray,
+    a_op: Operator,
+    b_op: Operator,
+    c_ops: Sequence[Array],
+    time_name: str,
+) -> None:
+    if H.shape[0] != H.shape[1]:
+        msg = "H must be square."
+        raise ValueError(msg)
+    if rho0.shape != H.shape:
+        msg = "rho0 must have the same shape as H."
+        raise ValueError(msg)
+    _validate_nonnegative_sorted_times(times, time_name)
+    for op_name, operator in (("a_op", a_op), ("b_op", b_op)):
+        if operator.shape != H.shape:
+            msg = f"{op_name} must have the same shape as H."
+            raise ValueError(msg)
+    for collapse in c_ops:
+        if collapse.shape != H.shape:
+            msg = "collapse operators must have the same shape as H."
+            raise ValueError(msg)
+
+
+def _validate_nonnegative_sorted_times(times: FloatArray, name: str) -> None:
+    if times.ndim != 1 or len(times) == 0:
+        msg = f"{name} must be a non-empty one-dimensional sequence."
+        raise ValueError(msg)
+    if np.any(times < 0):
+        msg = f"{name} must be non-negative."
+        raise ValueError(msg)
+    if np.any(np.diff(times) < 0):
+        msg = f"{name} must be sorted in ascending order."
+        raise ValueError(msg)
+
+
+def _field(raw: object, name: str) -> object:
+    try:
+        return getattr(raw, name)
+    except AttributeError:
+        return cast(object, raw[name])  # type: ignore[index]

openquantumsim/hilbert.py

@@ -0,0 +1,114 @@
+"""Hilbert-space descriptors for OpenQuantumSim."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from functools import reduce
+from math import isclose
+from operator import mul
+
+
+class HilbertSpace:
+    """Base Hilbert-space descriptor."""
+
+    @property
+    def dim(self) -> int:
+        """Return the finite Hilbert-space dimension."""
+        raise NotImplementedError
+
+    def __mul__(self, other: HilbertSpace) -> CompositeSpace:
+        """Tensor-product composition using `space_a * space_b`."""
+        if isinstance(self, CompositeSpace):
+            left = self.spaces
+        else:
+            left = (self,)
+        if isinstance(other, CompositeSpace):
+            right = other.spaces
+        else:
+            right = (other,)
+        return CompositeSpace(left + right)
+
+
+@dataclass(frozen=True)
+class FockSpace(HilbertSpace):
+    """Truncated bosonic Fock space with states `|0>` through `|N-1>`."""
+
+    N: int = 2
+    label: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.N <= 0:
+            msg = "FockSpace dimension N must be positive."
+            raise ValueError(msg)
+
+    @property
+    def dim(self) -> int:
+        """Return the truncation dimension."""
+        return self.N
+
+
+@dataclass(frozen=True)
+class SpinSpace(HilbertSpace):
+    """Spin-S irreducible representation with dimension `2S + 1`."""
+
+    S: float = 0.5
+    label: str | None = None
+
+    def __post_init__(self) -> None:
+        dim = 2 * self.S + 1
+        if self.S < 0 or not isclose(dim, round(dim), rel_tol=0.0, abs_tol=1e-12):
+            msg = "SpinSpace requires S >= 0 and 2S + 1 to be an integer."
+            raise ValueError(msg)
+
+    @property
+    def dim(self) -> int:
+        """Return `2S + 1`."""
+        return int(round(2 * self.S + 1))
+
+
+@dataclass(frozen=True)
+class DickeSpace(HilbertSpace):
+    """Permutation-symmetric Dicke manifold for ``n_spins`` two-level systems."""
+
+    n_spins: int
+    label: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.n_spins < 0:
+            msg = "DickeSpace requires n_spins >= 0."
+            raise ValueError(msg)
+
+    @property
+    def dim(self) -> int:
+        """Return the symmetric-manifold dimension ``n_spins + 1``."""
+        return self.n_spins + 1
+
+    @property
+    def total_spin(self) -> float:
+        """Return the collective spin ``S = n_spins / 2``."""
+        return self.n_spins / 2
+
+
+@dataclass(frozen=True)
+class CompositeSpace(HilbertSpace):
+    """Tensor product of multiple Hilbert spaces."""
+
+    spaces: tuple[HilbertSpace, ...]
+    label: str | None = None
+
+    def __post_init__(self) -> None:
+        if len(self.spaces) == 0:
+            msg = "CompositeSpace requires at least one subsystem."
+            raise ValueError(msg)
+
+    @property
+    def dim(self) -> int:
+        """Return the product dimension."""
+        return reduce(mul, (space.dim for space in self.spaces), 1)
+
+    def __iter__(self) -> Iterator[HilbertSpace]:
+        return iter(self.spaces)
+
+    def __len__(self) -> int:
+        return len(self.spaces)