diff --git a/docs/apidoc/apidoc.rst b/docs/apidoc/apidoc.rst index fdd8ddc..e9b51ff 100644 --- a/docs/apidoc/apidoc.rst +++ b/docs/apidoc/apidoc.rst @@ -1,14 +1,22 @@ .. _apidoc: ***************** -API documentation +API Documentation ***************** -This chapter contains automatically generated API documentation, including a -list of TensorHEOM's public classes and functions. +This chapter contains automatically generated API documentation for all public +classes and functions in TensorHEOM. + +The API is organised into two files: + +- **Classes & Module Functions** (:doc:`classes`) — the internal building blocks: + bath decomposition, pulse types, tensor-train classes, circuit compilation, + dynamics, and HPC utilities. +- **Top-level Functions** (:doc:`functions`) — the functions you use most often, + importable directly via ``from ttheom import ...``. .. toctree:: :maxdepth: 3 - classes.rst - functions.rst + functions + classes diff --git a/docs/apidoc/classes.rst b/docs/apidoc/classes.rst index fd9c170..4db9240 100644 --- a/docs/apidoc/classes.rst +++ b/docs/apidoc/classes.rst @@ -1,30 +1,23 @@ -Classes & Functions -=================== +Classes & Module Functions +========================== -This section provides an overview of the available classes and functions contained in the `TensorHEOM` package. +This section documents TensorHEOM's internal classes and module-level +functions, grouped by subsystem. -Decomposition of bath auto-correlation functions ------------------------------------------------- - -.. currentmodule:: ttheom.bath - -.. autofunction:: getBathParams -.. autofunction:: broadbandNoise - -Connection of quantum gates and pulse sequences ------------------------------------------------ +Pulse types and gate specifications +------------------------------------- .. currentmodule:: ttheom.pulse .. autofunction:: setGates .. autofunction:: getGate -.. autoclass:: directCplStepVarJ -.. autoclass:: iSwapDPulse .. autoclass:: rxyStep .. autoclass:: U3Pulse +.. autoclass:: iSwapDPulse +.. autoclass:: directCplStepVarJ -Tensor Train representation ---------------------------- +Tensor-train representation +---------------------------- .. currentmodule:: ttheom.tt @@ -34,8 +27,8 @@ Tensor Train representation .. autoclass:: TTs2QId .. autoclass:: TTsMQChainId -Compilation of Qiskit circuits to pulse sequences -------------------------------------------------- +Circuit compilation +------------------- .. currentmodule:: ttheom.circuit @@ -54,15 +47,15 @@ Time evolution .. autofunction:: outputCurrentStates .. autofunction:: getRotatingRDO -Running Simulations on HPC --------------------------- +HPC cluster support +-------------------- .. currentmodule:: ttheom.ssh -.. autofunction:: slurmShell -.. autofunction:: slurmStatus +.. autofunction:: submitJob +.. autofunction:: downloadResult +.. autofunction:: getClient .. autofunction:: commandsForSubmission .. autofunction:: getStatus -.. autofunction:: getClient -.. autofunction:: submitJob -.. autofunction:: downloadResult \ No newline at end of file +.. autofunction:: slurmShell +.. autofunction:: slurmStatus diff --git a/docs/apidoc/functions.rst b/docs/apidoc/functions.rst index c0dfa53..0db9a38 100644 --- a/docs/apidoc/functions.rst +++ b/docs/apidoc/functions.rst @@ -1,4 +1,41 @@ -Main Function -============= +Top-level Functions +=================== -.. autofunction:: ttheom.main.main +This section documents the public functions available at the top level of the +``ttheom`` namespace (i.e., importable directly via ``from ttheom import ...``). + +High-level simulation interface +-------------------------------- + +.. currentmodule:: ttheom.main + +.. autofunction:: calcTimeEvo +.. autofunction:: main + +Physical-unit helpers +---------------------- + +.. currentmodule:: ttheom.main + +.. autofunction:: prepareSystemArgs +.. autofunction:: prepareBathArgs +.. autofunction:: prepareGateArgs + +Bath decomposition +------------------ + +.. currentmodule:: ttheom.bath + +.. autofunction:: getBathParams +.. autofunction:: broadbandNoise + +Evaluation and analysis +----------------------- + +.. currentmodule:: ttheom.evaluation + +.. autofunction:: loadResult +.. autofunction:: getFidelity +.. autofunction:: getConcurrence +.. autofunction:: getLogarithmicNegativity +.. autofunction:: plotPulseSeq diff --git a/docs/conf.py b/docs/conf.py index 704dd80..60e661b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -79,15 +79,25 @@ # Options for HTML output html_theme = "sphinx_rtd_theme" -html_static_path = [] +html_static_path = ["_static"] +html_logo = "figures/logo.png" +html_theme_options = { + "logo_only": False, + "prev_next_buttons_location": "bottom", + "collapse_navigation": False, + "sticky_navigation": True, + "navigation_depth": 3, +} -exclude_patterns = [ - "_build", - "Thumbs.db", - ".DS_Store", -] +html_context = { + "display_github": True, + "github_user": "dehe1011", + "github_repo": "TensorHEOM", + "github_version": "main", + "conf_py_path": "/docs/", +} -# Syntax highlighing for code blocks in the documentation +# Syntax highlighting for code blocks in the documentation pygments_style = "sphinx" # Do not add parentheses to function names in cross-references like :func: diff --git a/docs/copyright.rst b/docs/copyright.rst index 42e76b8..f5627ab 100644 --- a/docs/copyright.rst +++ b/docs/copyright.rst @@ -5,10 +5,10 @@ Copyright and Licensing *********************** The text of this documentation is licensed under the `Creative Commons Attribution 3.0 Unported License `_. -Unless specifically indicated otherwise, all code samples, the source code of qDNA, and its reproductions in this documentation, are licensed under the terms of the 3-clause BSD license, reproduced below. +Unless specifically indicated otherwise, all code samples, the source code of TensorHEOM, and its reproductions in this documentation, are licensed under the terms of the 3-clause BSD license, reproduced below. License Terms for Documentation Text -==================================== +===================================== The canonical form of this license is available at `https://creativecommons.org/licenses/by/3.0/ `_, which should be considered the binding version of this license. It is reproduced here for convenience. @@ -19,9 +19,9 @@ It is reproduced here for convenience. .. include:: LICENSE_cc-by-3.0.txt -License Terms for Source Code of QuantumDNA and Code Samples -============================================================ +License Terms for Source Code of TensorHEOM and Code Samples +============================================================= .. - BSD-3-Clause/ MIT license + BSD-3-Clause license .. include:: ../LICENSE.txt diff --git a/docs/gui/gui.rst b/docs/gui/gui.rst index 6f5b39a..52a9a1d 100644 --- a/docs/gui/gui.rst +++ b/docs/gui/gui.rst @@ -1,30 +1,63 @@ .. _guidoc: -***************** -GUI documentation -***************** +******************************* +Graphical User Interface (GUI) +******************************* -This chapter contains documentation for the graphical user interface (GUI) which is designed to provide an user-friendly way to interact with the `TensorHEOM` package. +TensorHEOM provides an optional graphical user interface built with +`CustomTkinter `_. +The GUI is designed for users who prefer an interactive, form-based workflow +without writing code. + +Launching the GUI +================= + +.. code-block:: python + + from ttheom import TensorHeomApp + + TensorHeomApp().mainloop() + +Or from the command line after installing the package: + +.. code-block:: bash + + python -c "from ttheom import TensorHeomApp; TensorHeomApp().mainloop()" + +Main window +=========== + +The main window provides input fields for all simulation parameters: +qubit frequencies, initial state, bath parameters, numerical settings, and the +output file name. .. figure:: ../figures/GUI1.png :align: center - :width: 3in + :width: 5in -*Figure 1: Main window of the GUI.* + Main window showing system, bath, and simulation parameter fields. ---- +Quantum circuit editor +====================== + +The circuit editor window integrates with Qiskit to let you build and visualise +quantum circuits graphically. Gates can be added via drop-down menus and the +resulting Qiskit circuit is passed directly to the simulation engine. .. figure:: ../figures/GUI2.png :align: center - :width: 3in + :width: 5in + + Quantum circuit editor with Qiskit circuit visualization. -*Figure 2: Quantum circuit editor window with qiskit integration.* +Results viewer +============== ---- +Once a simulation completes, the results viewer displays the time-evolved +reduced density matrix elements and derived quantities such as concurrence. .. figure:: ../figures/GUI3.png :align: center - :width: 3in - -*Figure 3: Visualization of results (here: concurrence).* + :width: 5in + Results viewer showing the concurrence as a function of time. diff --git a/docs/guide/guide.rst b/docs/guide/guide.rst index 2bb3aa8..2e58493 100644 --- a/docs/guide/guide.rst +++ b/docs/guide/guide.rst @@ -1,15 +1,305 @@ .. _guide: ********** -User guide +User Guide ********** -Welcome to the TensorHEOM Jupyter Notebook Tutorials! These tutorials and demonstrations are designed to help users explore and -understand the functionalities of the `TensorHEOM` package through practical examples. +This guide explains TensorHEOM's workflow in depth. It uses the **low-level +API** (:func:`ttheom.main.main`) to show explicitly how each layer of the +simulation — system, bath, pulse sequences, tensor-train structure, and time +evolution — fits together. The :ref:`Quickstart ` page covers the +high-level ``calcTimeEvo`` interface if you just want to run simulations +quickly. -For a detailed description of the classes and functions used in these tutorials, visit the :ref:`API documentation `. +.. contents:: On this page + :local: + :depth: 2 Overview ======== -Here, we plan to provide a collection of Jupyter notebooks that demonstrate, step by step, the main features and capabilities of the `TensorHEOM` package. +A TensorHEOM simulation proceeds in four steps: + +1. **Define the quantum circuit** using Qiskit. +2. **Specify system and bath parameters** (frequencies, temperature, T1). +3. **Build pulse sequences and the tensor-train structure**. +4. **Run the time evolution** and save the reduced density matrix. + +The diagram below shows how the package layers connect: + +.. code-block:: text + + Qiskit circuit ─┐ + System params ─┤─▶ main() / calcTimeEvo() ─▶ CSV results + Bath params ─┤ │ + Gate specs ─┘ TensorHEOM internals: + ├─ pulse sequence compilation + ├─ bath AAA decomposition + ├─ TT structure construction + └─ TDVP / Runge-Kutta propagation + +Example 1 — Single qubit with broadband noise +============================================= + +This example simulates a single-qubit gate sequence under broadband Ohmic +noise using the low-level interface. + +.. code-block:: python + + import numpy as np + from qiskit import QuantumCircuit + from ttheom.main import main + + # --- Quantum circuit --- + qc = QuantumCircuit(1) + qc.rx(0.5 * np.pi, 0) + qc.delay(0, 0) + qc.ry(0.5 * np.pi, 0) + qc.delay(0, 0) + qc.ry(-0.5 * np.pi, 0) + + # --- System dictionary (internal units) --- + rho = { + 'numQ': 1, + 'rhoIni': np.array([[1, 0], [0, 0]], dtype=np.complex128), + 'omegaQ': [1.0], # frequencies normalised to omegaQmax + } + + # --- Gate specification --- + # Each entry: [qubit_indices, gate_type, kwargs] + kwargs1Q = {'omega': -rho['omegaQ'][0], 'gateTime': 0.1 * np.pi} + gateList = [[[0], 'rxyStep', kwargs1Q]] + + # --- Bath parameters (internal units) --- + bath = [{'type': 'broadband', + 'beta': 5, + 'kappa': 0.004 / (2 * np.pi), + 'omegaC': 50, + 'exp': 1, + 'tol': 1e-6}] + + # --- System-bath coupling operator --- + V = np.array([[[0, 1], [1, 0]]], dtype=np.complex128) + + # --- Numerical parameters --- + dtFB = 0.001 # time step + strideTime = 0.01 + stride = int(strideTime / dtFB) + depth = [2] # hierarchy depth + bondDim = 20 # MPS bond dimension + + # --- Run --- + main('rdo_1qubit.csv', qc, 0.1, gateList, rho, + bath, V, dtFB, stride, depth, bondDim) + +The result is written to ``rdo_1qubit.csv``. + +Understanding the internal units +--------------------------------- + +All frequencies are normalised to ``omegaQmax`` (the highest qubit frequency). +Time is measured in units of ``1/omegaQmax``. The helper functions +:func:`ttheom.main.prepareSystemArgs`, :func:`ttheom.main.prepareBathArgs`, and +:func:`ttheom.main.prepareGateArgs` convert physical units (GHz, mK, µs, ns) +to internal units automatically. + +Example 2 — Realistic single-qubit simulation (physical units) +=============================================================== + +This example uses the physical-unit helpers and closely matches the parameters +of a real superconducting-qubit device. + +.. code-block:: python + + import numpy as np + from qiskit import QuantumCircuit + from ttheom.main import prepareSystemArgs, prepareBathArgs, prepareGateArgs, main + + qc = QuantumCircuit(1) + qc.rx(0.5 * np.pi, 0) + qc.delay(0, 0) + qc.ry(0.5 * np.pi, 0) + qc.delay(0, 0) + qc.ry(-0.5 * np.pi, 0) + + # Physical-unit system parameters + omegaQmax, rho = prepareSystemArgs( + numQ=1, + freqQ=[5.0], # GHz + rhoIni=np.array([[1, 0], [0, 0]], dtype=np.complex128), + ) + + # Physical-unit bath parameters (T=30 mK, T1=32 µs) + bath = prepareBathArgs(rho, omegaQmax, + T=30, T1=32, omegaC=50, exp=1, tol=1e-6) + + # Gate list (gate time = 16 ns) + gateList = prepareGateArgs(rho, omegaQmax, gateTime=[16.0]) + + V = np.array([[[0, 1], [1, 0]]], dtype=np.complex128) + + dtFB_ns = 0.005 # ns + dtFB = dtFB_ns * omegaQmax # internal units + strideTime_ns = 3.0 + stride = int(strideTime_ns / dtFB_ns) + + main('rdo_1qubit_realistic.csv', qc, 10 * np.pi, gateList, rho, + bath, V, dtFB, stride, depth=[1], bondDim=5, useRFPlus=True) + +The ``useRFPlus=True`` flag activates the Redfield+ method, which is a +computationally cheaper approximation suitable when the bath–system coupling +is weak. + +Example 3 — Two-qubit Bell state +================================== + +This example prepares a Bell state :math:`(|00\rangle + |11\rangle)/\sqrt{2}` using a Hadamard gate +followed by a CNOT, and simulates the entanglement dynamics under non-Markovian +noise. + +.. code-block:: python + + import numpy as np + from qiskit import QuantumCircuit + from ttheom.main import prepareSystemArgs, prepareBathArgs, prepareGateArgs, main + + qc = QuantumCircuit(2) + qc.h(0) + qc.cx(0, 1) + + omegaQmax, rho = prepareSystemArgs( + numQ=2, + freqQ=[5.0, 5.0], + rhoIni=np.array([[1, 0, 0, 0], + [0, 0, 0, 0], + [0, 0, 0, 0], + [0, 0, 0, 0]], dtype=np.complex128), + ) + + bath = prepareBathArgs(rho, omegaQmax, + T=30, T1=32, omegaC=50, exp=1, tol=1e-6) + + # Two single-qubit gates + one two-qubit gate + gateList = prepareGateArgs(rho, omegaQmax, gateTime=[16.0, 16.0, 50.0]) + + V = np.array([[[0, 1], [1, 0]], + [[0, 1], [1, 0]]], dtype=np.complex128) + + dtFB_ns = 0.001 + dtFB = dtFB_ns * omegaQmax + stride = int(0.01 / dtFB_ns) + + main('rdo_bell.csv', qc, 0.1, gateList, rho, + bath, V, dtFB, stride, depth=[2, 2], bondDim=20) + +Analysing the results +====================== + +After a simulation has run, use the evaluation functions to inspect the output. + +.. code-block:: python + + import numpy as np + from ttheom import loadResult, getFidelity, getConcurrence, getLogarithmicNegativity + + times, rhos = loadResult('rdo_bell.csv') + + # Target Bell state + bell = np.array([[0.5, 0, 0, 0.5], + [0, 0, 0, 0 ], + [0, 0, 0, 0 ], + [0.5, 0, 0, 0.5]]) + + fidelities = [getFidelity(bell, rho) for rho in rhos] + concurrences = [getConcurrence(rho) for rho in rhos] + log_neg = [getLogarithmicNegativity(rho) for rho in rhos] + + print(f"Final fidelity: {fidelities[-1]:.4f}") + print(f"Final concurrence: {concurrences[-1]:.4f}") + print(f"Final log. neg.: {log_neg[-1]:.4f}") + +Bath decomposition +================== + +The FP-HEOM method represents bath correlation functions as a sum of +exponentials. TensorHEOM uses the AAA algorithm (via the ``baryrat`` library) +to decompose the bath spectral density automatically. + +To inspect the decomposition: + +.. code-block:: python + + from ttheom import getBathParams + + bath_params = { + 'type': 'broadband', + 'beta': 5, + 'kappa': 0.004 / (2 * np.pi), + 'omegaC': 50, + 'exp': 1, + 'tol': 1e-6, + } + + z, d = getBathParams(bath_params) + print("Poles z:", z) + print("Weights d:", d) + +Each pole ``z[k]`` and weight ``d[k]`` represents one exponential in the +bath correlation function. More poles give a more accurate representation. +The ``tol`` parameter controls how many poles are used. + +Hierarchy depth and bond dimension +==================================== + +Two numerical parameters dominate accuracy and cost: + +``depth`` + FP-HEOM hierarchy depth (per qubit). Depth 1 includes first-order + system–bath entanglement. Depth 2 adds second-order corrections. + Values above 3 are rarely needed for weakly coupled baths. + +``bondDim`` + Maximum bond dimension of the MPS representation. + Larger values capture more quantum correlations between qubits and bath + modes. For single-qubit simulations, 5–20 is typically sufficient; + two-qubit simulations may need 20–100. + +A good convergence check is to rerun the simulation with doubled ``depth`` +and ``bondDim`` and verify that the output changes by less than your target +accuracy. + +Redfield+ approximation +========================= + +Setting ``useRFPlus=True`` activates the Redfield+ method, a perturbative +approximation that reduces computational cost significantly. It is suitable +for weak coupling (large T1) and serves as a fast sanity check before +running a full FP-HEOM calculation. + +HPC submission +============== + +For long-running simulations, TensorHEOM can submit jobs to a SLURM cluster +and retrieve results automatically. See :func:`ttheom.ssh.submitJob` and +:func:`ttheom.ssh.downloadResult` in the :ref:`API documentation `. + +.. code-block:: python + + from ttheom import submitJob + + submission_params = { + 'hostname': 'cluster.example.org', + 'username': 'myuser', + 'password': 'mypassword', + 'otp': '123456', + 'schedulerName': 'slurm', + 'numNodes': 1, + 'cpusPerTask': 16, + 'maxTime': '0-04:00:00', + 'emailAddress': 'user@example.org', + 'others': '#SBATCH --partition=normal', + 'venvPath': '/home/myuser/.venv', + } + + job_id = submitJob(submission_params, ...) + print("Job submitted with ID:", job_id) diff --git a/docs/index.rst b/docs/index.rst index ef318c3..6c9f143 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,41 +1,103 @@ .. figure:: figures/logo.png :align: center - :width: 2in + :width: 2.5in +TensorHEOM Documentation +========================= -Welcome to TensorHEOM's Documentation! -====================================== +**Version:** |release| | **License:** BSD 3-Clause | `GitHub `_ -TensorHEOM is an open-source python package. +TensorHEOM is a Python package for simulating quantum circuits in **non-Markovian environments** +using free-pole hierarchical equations of motion (FP-HEOM) combined with tensor-train (TT) compression. +It is designed for superconducting-qubit simulations and connects circuit-level `Qiskit `_ +input with microscopic open-system dynamics. .. figure:: figures/overview.png :align: center :width: 100% -Whether you're a scientist, student, or just curious, dive in and start exploring! +Key Features +------------ -About This Documentation ------------------------- -This documentation includes: +- **Non-Markovian open-system dynamics** via free-pole HEOM (FP-HEOM) +- **Tensor-train (MPS/MPO) compression** for efficient multi-qubit simulations +- **Native Qiskit integration**: transpile and simulate arbitrary quantum circuits +- **Physical unit interface**: specify temperatures in mK, relaxation times T1 in µs, frequencies in GHz +- **Bath decomposition** via AAA algorithm (baryrat) for arbitrary spectral densities +- **Built-in analysis tools**: fidelity, concurrence, logarithmic negativity +- **HPC support**: submit and retrieve jobs on SLURM clusters via SSH +- **Graphical user interface** for interactive exploration -- **API Reference**: Description of functions and classes. -- **User Guide**: Tutorial Jupyter notebooks for getting started. -- **Graphical User Interface (GUI)**: Information on how to use the GUI. +Quick Install +------------- -For additional resources and development information, visit the `TensorHEOM GitHub repository `_. +.. code-block:: bash + + pip install ttheom + +For a full installation guide including editable installs and platform-specific +instructions see :doc:`installation`. + +Minimal Example +--------------- + +.. code-block:: python + + from qiskit import QuantumCircuit + from ttheom import calcTimeEvo + + qc = QuantumCircuit(1) + qc.rx(1.5708, 0) # Rx(π/2) + + calcTimeEvo( + fileName="result", + qc=qc, + numQ=1, + freqQ=[5.0], # GHz + gateTime=[16.0], # ns + T=30, # mK + T1=32, # µs + omegaC=20, + exp=1, + tol=1e-4, + rhoIni=[[1,0],[0,0]], + idlingTime=1.0, # ns + dtFB=3.0, # ps + depth=[1], + bondDim=5, + strideTime=0.1, # ns + ) + +See :doc:`quickstart` for a step-by-step walkthrough with explanation of all parameters. .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Getting Started installation - apidoc/apidoc + quickstart + +.. toctree:: + :maxdepth: 2 + :caption: User Guide + guide/guide gui/gui + +.. toctree:: + :maxdepth: 3 + :caption: API Reference + + apidoc/apidoc + +.. toctree:: + :maxdepth: 1 + :caption: About + biblio copyright -Indices and tables +Indices and Tables ================== * :ref:`genindex` diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..cbb22e6 --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,207 @@ +.. _quickstart: + +********** +Quickstart +********** + +This page shows the fastest path from installation to a working simulation. +TensorHEOM offers two levels of API: a **high-level interface** (``calcTimeEvo``) that handles +unit conversions internally, and a **low-level interface** (``main``) that gives full control +over all parameters. + +.. contents:: On this page + :local: + :depth: 2 + +Installation +============ + +.. code-block:: bash + + pip install ttheom + +High-level API: a single qubit +================================ + +The function :func:`ttheom.main.calcTimeEvo` accepts physical units (GHz, ns, mK, µs) +and performs all internal conversions. + +.. code-block:: python + + from qiskit import QuantumCircuit + from ttheom import calcTimeEvo + + # 1. Define the quantum circuit + qc = QuantumCircuit(1) + qc.rx(1.5708, 0) # Rx(π/2) + qc.delay(0, 0) + qc.ry(1.5708, 0) # Ry(π/2) + qc.delay(0, 0) + qc.ry(-1.5708, 0) # Ry(-π/2) + + # 2. Run the simulation + calcTimeEvo( + fileName="result_1q", + qc=qc, + numQ=1, + freqQ=[5.0], # qubit frequency in GHz + gateTime=[16.0], # single-qubit gate time in ns + rhoIni=[[1, 0], + [0, 0]], # initial state |0><0| + idlingTime=1.0, # idling time between gates in ns + T=30, # temperature in mK + T1=32, # energy relaxation time in µs + omegaC=20, # bath cutoff frequency + exp=1, # spectral density exponent + tol=1e-4, # AAA decomposition tolerance + dtFB=3.0, # time step in ps + depth=[1], # FP-HEOM hierarchy depth + bondDim=5, # maximum MPS bond dimension + strideTime=0.1, # output interval in ns + ) + +The output is written to ``result_1q.csv``. + +High-level API: a two-qubit Bell state +========================================= + +For a two-qubit circuit, set ``numQ=2`` and provide gate times for the +single-qubit gates followed by the two-qubit coupling gate: + +.. code-block:: python + + from qiskit import QuantumCircuit + from ttheom import calcTimeEvo + + # Bell state: H ⊗ I followed by CNOT + qc = QuantumCircuit(2) + qc.h(0) + qc.cx(0, 1) + + calcTimeEvo( + fileName="result_bell", + qc=qc, + numQ=2, + freqQ=[5.0, 5.0], # GHz + gateTime=[16.0, 16.0, 50], # two 1Q gates + one 2Q gate, ns + rhoIni=[[1, 0, 0, 0], + [0, 0, 0, 0], + [0, 0, 0, 0], + [0, 0, 0, 0]], # |00><00| + idlingTime=1.0, # ns + T=30, # mK + T1=32, # µs + omegaC=20, + exp=1, + tol=1e-4, + dtFB=3.0, # ps + depth=[1, 1], # one depth per qubit + bondDim=5, + strideTime=0.1, # ns + ) + +Reading and analysing results +============================== + +The CSV output contains the time-evolved reduced density matrix. +TensorHEOM provides helper functions to load and analyse it: + +.. code-block:: python + + from ttheom import loadResult, getFidelity, getConcurrence + + # Load results + times, rhos = loadResult("result_bell.csv") + + # Gate fidelity with respect to the ideal Bell state + import numpy as np + rho_ideal = np.array([[0.5, 0, 0, 0.5], + [0, 0, 0, 0 ], + [0, 0, 0, 0 ], + [0.5, 0, 0, 0.5]]) + fidelities = [getFidelity(rho_ideal, rho) for rho in rhos] + + # Concurrence (entanglement measure) + concurrences = [getConcurrence(rho) for rho in rhos] + +Visualising the pulse sequence +================================ + +.. code-block:: python + + from ttheom import plotPulseSeq + + # Plots the pulse envelope of the compiled pulse sequence + plotPulseSeq(fileName="result_bell.csv") + +Understanding the parameters +============================= + +System parameters +----------------- + +``numQ`` + Number of qubits. + +``freqQ`` + Qubit transition frequencies in GHz. + +``rhoIni`` + Initial density matrix as a 2D list or NumPy array of shape + ``(2**numQ, 2**numQ)``. + +``idlingTime`` + Time between gates in ns. + +``gateTime`` + Gate durations: the first ``numQ`` values are single-qubit gate times, the + next ``numQ-1`` values are two-qubit gate times, all in ns. + +Bath parameters +--------------- + +``T`` + Temperature in mK. Can be a scalar (same for all qubits) or a list. + +``T1`` + Energy-relaxation time in µs. Can be a scalar or a list. + +``omegaC`` + Bath cutoff frequency (in units of the maximum qubit frequency). + +``exp`` + Exponent of the spectral density (Ohmic: ``exp=1``). + +``tol`` + Tolerance for the AAA bath-decomposition algorithm. + Smaller values give a more accurate decomposition but require more poles. + +Simulation parameters +--------------------- + +``dtFB`` + Time step for the forward/backward HEOM propagation in ps. + Typical values: 1–10 ps. Use smaller values for faster/stronger baths. + +``depth`` + FP-HEOM hierarchy depth per qubit (list of int). + Increasing depth improves accuracy; ``[1]`` or ``[2]`` is usually sufficient. + +``bondDim`` + Maximum MPS bond dimension. + Larger values are more accurate but slower. For a single qubit, 5–20 is typical. + +``strideTime`` + Time between successive output snapshots in ns. + +``fileName`` + Base name of the output CSV file (without extension). + +Next steps +========== + +- For the low-level ``main`` API and direct control over internal parameters, + see the :ref:`User Guide `. +- For the full list of classes and functions, see the :ref:`API documentation `. +- For running simulations on an HPC cluster, see + :func:`ttheom.ssh.submitJob` and :func:`ttheom.ssh.downloadResult`. diff --git a/ttheom/evaluation/__init__.py b/ttheom/evaluation/__init__.py index a6520a1..bc093b4 100644 --- a/ttheom/evaluation/__init__.py +++ b/ttheom/evaluation/__init__.py @@ -1,4 +1,5 @@ from .concurrence import * from .fidelity import * from .load_result import * +from .logarithmic_negativity import * from .plot_pulse_seq import * \ No newline at end of file diff --git a/ttheom/main.py b/ttheom/main.py index 718613c..86593ba 100644 --- a/ttheom/main.py +++ b/ttheom/main.py @@ -454,7 +454,7 @@ def calcTimeEvo(fileName, qc, numQ, freqQ, gateTime, T, T1, omegaC, exp, tol, rh idlingTime : float Idling time in ns. dtFB : float - Integration time step in fs. + Integration time step in ps. depth : list of int FP-HEOM hierarchy depths, one per qubit. bondDim : int