Skip to content

Latest commit

 

History

History
186 lines (104 loc) · 10.7 KB

README.md

File metadata and controls

186 lines (104 loc) · 10.7 KB

DOI DOI

quantum_HEOM

Author: Joseph W. Abbott *

* Currently: PhD Student, Lab COSMO, EPFL.

What's New - 2022

  • October 2022: Users will soon be able to define their own system using a custom Hamiltonian and plot its EET dynamics - stay tuned!

  • 11 April 2022: quantum_HEOM was used to generate training data for a trajectory learning 'AI-QD' approach to predicting energy transfer dynamics in a recent paper in Nature Communications:

    Predicting the future of excitation energy transfer in light-harvesting complex with artificial intelligence-based quantum dynamics, A. Ullah, P.O. Dral, Nat Commun, 13, 1930, (2022). DOI: 10.1038/s41467-022-29621-w

Citing This Work

The author's master's thesis can be (preferentially) cited as:

Quantum Dynamics of Bath Influenced Excitonic Energy Transfer in Photosynthetic Pigment-Protein Complexes, J.W. Abbott, University of Bristol, 2020. DOI: 10.5281/zenodo.7229807

and this Python package as:

quantum_HEOM (github.com/jwa7/quantum_HEOM), J.W. Abbott, 2022, DOI: 10.5281/zenodo.7230160

Introduction

Summary

With high control over input parameters and interactable in notebooks via 'black-boxed' code written in Python, quantum_HEOM allows the bath-influenced excitonic energy transfer dynamics of open quantum systems to be calculated and plotted. Users can simulate EET for in-built model systems, namely a 2-site spin-boson system or the 7-site FMO complex. For describing the dynamics, three different forms of the Lindblad quantum master equation are implemented, while simulation of dynamics using the Hierarchical Equations of Motion (HEOM) approach is performed by interfacing with QuTiP's HEOM solver class.

This package was initially produced as part of the author's final year MSci project, supervised by Fred Manby, at the University of Bristol in 2020, and accompanies his thesis entitled "Quantum Dynamics of Bath Influenced Excitonic Energy Transfer in Photosynthetic Pigment-Protein Complexes". Users can easily reproduce figures from this thesis, as well as define their own parameters and plot the dynamics. After completing the installation instructions below, the short tutorials can be followed to best show the functionality of the package.

Scientific Background

All life on Earth relies on the ability of photosynthetic organisms to efficiently harvest and trap energy from sunlight. Acting as a molecular wire, a protein-pigment complex known as the Fenna-Matthews-Olson (FMO) complex found in green sulfur bacteria mediates the transfer of photo-excitation energy between the photosynthetic antennae complex, where energy is harvested, and the reaction centre, where it is trapped.

The fine balance between intra-system and system-bath couplings present in the FMO complex allows it to perform unidirectional quantum coherence excitonic energy transfer (EET) with an almost unit quantum yield. Using coherent theories, quantum dynamical treatment of the bath-influenced EET process can simulate, in silico, coherence effects that have been observed experimentally. The celebrated hierarchical equations of motion (HEOM) approach, based on a path integral formalism, accurately describes EET dynamics and successfully accounts for non-equilibrium and non-Markovian effects. Though exact, with very few assumptions made about the dynamics or state of the system, HEOM is computationally very expensive for large systems.

This motivates the use of a quantum master equation, such as the Lindblad equation formed under the Markov approximation, as an alternative and cheaper description of EET. One such Lindblad model, in agreement with the HEOM approach and experiment, is particularly effective in describing the EET dynamics in the FMO complex despite the minimal computational cost.

Getting Started

NOTE: These set-up instructions have only been tested on macOS and may not work on Windows.

Pre-requisites

Installation

Copy the following commands into your computer's terminal application (or equivalent) and execute them.

  1. Clone the quantum_HEOM repository in your computer's terminal (or equivalent) application:
    git clone https://github.com/jwa7/quantum_HEOM.git

  2. Enter the top directory of the quantum_HEOM package:
    cd quantum_HEOM

  3. Create a virtual environment from the specification yaml file. This environment will contain all external package dependencies (i.e. numpy, scipy, QuTiP, matplotlib, etc.) relied upon by quantum_HEOM:
    conda env create -f environment.yml

  4. Enter the virtual environment:
    conda activate qheom

  5. Install the environment as a ipython kernel. This allows jupyter notebooks to be executed from within the virtual environment:
    ipython kernel install --name=qheom

  6. Run all unit tests. All of these should pass if the package is working as it should. If something is wrong, please raise an issue here.
    chmod +x run_tests.sh && ./run_tests.sh

Tutorials

In the quantum_HEOM/doc/tutorials/ directory, there exists the following tutorials:

  • 0_reproducing_figures.ipynb; reproducing figures found in the author's thesis.
  • 1_unit_system.ipynb; description of the unit system used by quantum_HEOM, as well as a small unit converter.
  • 2_system_parameters.ipynb; the parameters that can be set when defining a system.
  • 3_example_plots.ipynb; examples of all the types of plots that can be produced with quantum_HEOM.

To launch the tutorials:

  1. From your computer's terminal application, ensure you are in the qheom virtual environment (see Installation above).
  2. Navigate to the quantum_HEOM/doc/tutorials/ directory.
  3. To launch the notebook for the third tutorial, for example, execute the following:
    jupyter notebook 3_example_plots.ipynb &

Functionality

Current Features

The models used to describe open quantum system dynamics currently implemented in quantum_HEOM are (see also the References below):

  • Local dephasing Lindblad
  • Global thermalising Lindblad
  • Local thermalising Lindblad
  • HEOM (currently only for 2-site systems) from QuTiP's HEOM Solver

Important Points

There are some restrictions on some of the settings used in relation to their compatability with others:

  • QuTiP's HEOM Solver currently (as of April 2020) only allows for 2-site systems described by a spin-boson Hamiltonian and a Debye (otherwise known as a Drude-Lorentz or overdamped Brownian) spectral density to be solved for.
  • The spin-boson Hamiltonian is only applicable to 2-site systems.
  • The FMO Hamiltonian is only applicable to 7-site systems.
  • All Lindblad models are applicable to any N-site system (using the nearest neighbour model Hamiltonian or self-defined Hamiltonian)
  • All Lindblad models can be used in conjunction with the approximate Debye and Ohmic, as well as the parametrised Renger-Marcus (see reference below) spectral density.

References

Lindblad models:

HEOM:

Spectral Density:

FMO Complex:

Other:

Troubleshooting

ModuleNotFoundError

Problem:

ModuleNotFoundError: No module named 'quantum_heom'

Solution:

Whether working in an ipython kernel or a jupyter notebook, ensure you are working from a directory within the quantum_HEOM top directory, and run the following codeblock:

import os
import sys
ROOT_DIR = os.getcwd()[:os.getcwd().rfind('quantum_HEOM')]
if ROOT_DIR not in sys.path: 
	sys.path.append(ROOT_DIR + 'quantum_HEOM')

The quantum_HEOM module should now be in your path. Import modules using this as the top directory. For example, to import the QuantumSystem class from the quantum_HEOM/quantum_heom/quantum_system module, run the import with the following syntax:

from quantum_heom.quantum_system import QuantumSystem

or to import the figures module:

from quantum_heom import figures as figs

Configuring the virtual environment kernel in a jupyter notebook

Problem:

The option for the qheom virtual environment cannot be found in the toolbar of the jupyter notebook at 'Kernel' > 'Change Kernel' > 'qheom'.

Solution:

  1. In your computer's terminal application, ensure you are in the qheom virtual environment using source activate qheom or conda activate qheom

  2. Execute the following command:
    ipython kernel install --name=qheom