Merge pull request #8 from dehe1011/main

merging main into development

.gitignore

@@ -8,13 +8,24 @@ TODO.txt
 main.py
 qDNA/data/raw/geometries/
 
+# documentation
+docs/_build/
+docs/_static/
+docs/_templates/
+
 # created by coverage
 htmlcov/
 
 # created by pytest
 __pycache__
 .pytest_cache/
 
+# pylint
+.pylintrc
+
+# mypy
+.mypy_cache/
+
 # created by coverage
 *.egg-info/
 .coverage

Dockerfile

@@ -0,0 +1 @@
+from ubuntu:latest

MANIFEST.in

@@ -4,19 +4,23 @@ include installation.md
 include LICENSE.txt
 include CITATION.bib
 
+# Include the MANIFEST file itself
+include MANIFEST.in
+
 # Include requirement files
 include requirements/*.txt
 
-# Include the MANIFEST file itself
-include MANIFEST.in
+# Include files in the package's root directory
+include qDNA/*.mplstyle
+include qDNA/defaults.yaml
 
 # Include all .py files
 recursive-include qDNA *.py
-include qDNA/defaults.yaml
 
 # Include specific data files
 include qDNA/data/data_paper/*.json
 include qDNA/data/figures_paper/*.pdf
-include qDNA/data/figures_paper/*.png
-include qDNA/data/raw/tb_params/*.json
+include qDNA/data/figures_tutorials/*.png
 include qDNA/data/raw/*.json
+include qDNA/data/raw/tb_params/*.json
+include qDNA/data/raw/lcao_params/*.json

README.md

@@ -1,6 +1,7 @@
 <p align="center">
-    <img src="docs/figures/qDNA_logo.png">
+    <img src="docs/figures/0_qDNA_logo.png" width="600">
 </p>
+
 <p align="center">
     <a href="https://opensource.org/licenses/BSD-3-Clause">
         <img src="https://img.shields.io/badge/license-New%20BSD-blue.svg"
@@ -12,11 +13,16 @@
         <img src="https://readthedocs.org/projects/quantumdna/badge/?version=latest"
             alt="Documentation Status"></a>
     <a href="https://github.com/dehe1011/QuantumDNA/releases">
-        <img src="https://img.shields.io/badge/version-0.1.10-blue"
-            alt="Release"></a>
+        <img src="https://img.shields.io/github/v/release/dehe1011/QuantumDNA"
+            alt="Latest Release"></a>
+    <a href="https://pypi.org/project/qDNA/">
+    <img src="https://img.shields.io/pypi/v/qDNA"
+        alt="PyPI Version"></a>
+    <!--
     <a href='https://coveralls.io/github/dehe1011/QuantumDNA?branch=main'>
         <img src='https://coveralls.io/repos/github/dehe1011/QuantumDNA/badge.svg?branch=main'
             alt='Coverage Status' /></a>
+    -->
     <a href='https://github.com/dehe1011/QuantumDNA/actions/workflows/code-quality.yml'>
         <img src='https://img.shields.io/github/actions/workflow/status/dehe1011/QuantumDNA/code-quality.yml?branch=main'
             alt='GitHub Workflow Status' /></a>
@@ -27,7 +33,7 @@
 
 ---
 
-# QuantumDNA
+# Welcome to QuantumDNA
 
 **Author: [Dennis Herb](https://github.com/dehe1011)**
 
@@ -37,24 +43,27 @@ This Python package can be cited as:
 
 ## Introduction
 
-Welcome to QuantumDNA, a powerful and flexible tool designed to calculate lifetimes, average charge separation, and dipole moments of excited states along DNA. Leveraging the formalism of open quantum systems and based on tight-binding Hamiltonians, QuantumDNA is equipped to handle various tight-binding models. Users can incorporate custom tight-binding parameters from ab initio calculations or experimental data, as well as define their own models, making the tool highly adaptable. QuantumDNA is regularly updated to ensure it remains at the cutting edge and includes a user-friendly interface to be accessible even to researchers less familiar with computer science. Results from several research papers can be reproduced with QuantumDNA.
+QuantumDNA is an open-source Python package for simulating charge transfer (CT) and excited states in DNA. These processes are key to understanding how DNA maintains genetic stability, how mutations occur, and even how we can use DNA in nanotechnology. QuantumDNA combines powerful quantum physics models like Linear Combination of Atomic Orbitals (LCAO) and tight-binding (TB) with quantum master equations to handle environmental effects. This makes it possible to analyze large DNA datasets quickly and accurately, uncovering insights into genetic and epigenetic phenomena. QuantumDNA comes with a clean and simple graphical user interface (GUI)—perfect for researchers and students, even without extensive coding experience.
+
+Whether you're a scientist, student, or just curious, QuantumDNA is here to help you explore the fascinating world of DNA charge transfer. Dive in and start exploring today!
 
 <p align="center">
-    <img src="docs/figures/structure.png" width="70%">
+    <img src="docs/figures/2_qDNA_structure.png" width="50%">
 </p>
 
 ### Key Features
 
-* Versatile Calculations: Calculate lifetimes, charge separation, and dipole moments.
-* Customizable Models: Add and use custom tight-binding parameters and models.
-* User-Friendly Interface: Designed for ease of use by all researchers.
-* Parallelization: Supports parallel computing for the calculation of excited state properties for large ensembles of DNA sequences, optimizing performance within the computationally intensive context of open quantum systems.
-* Regular Updates: Stay current with the latest advancements and improvements.
+* Graphical User Interface (GUI): Intuitive and user-friendly interface, making the tool accessible to researchers and students with limited programming experience.
+* Parallelized Calculations: Optimized for performance, enabling the analysis of large DNA ensembles with efficient computational resource utilization.
+* Integration with Publicly Accessible Databases: Supports input geometries from widely used DNA structure databases.
+* Unified Framework: Provides a reproducible platform for simulating and comparing results from different scientific papers and methodologies.
+* Open-Source: Fully open-source and extensible, allowing users to modify and adapt the code to suit their specific research needs.
+* Cross-Disciplinary Usability: Designed for researchers across physics, chemistry, biology, and medicine to explore DNA charge dynamics collaboratively.
 
 ## What's new
 
-* Added a graphical user interface (GUI) to the package such that it is easily accessible for users who are less familiar with computer science. The user interface is based on the [customtkinter](https://customtkinter.tomschimansky.com/) package by Tom Schimansky.
-* Added a [documentation](https://quantumdna.readthedocs.io/en/latest/) available on Read the Docs
+* Added a graphical user interface (GUI) to the package which is based on the [customtkinter](https://customtkinter.tomschimansky.com/) package by Tom Schimansky.
+* Added a Tutorial Jupyter Notebooks available on another [GitHub repopsitory](https://github.com/dehe1011/QuantumDNA-notebooks).
 
 ## Getting started
 
@@ -66,7 +75,7 @@ For a quick installation, you can install the `qDNA` package via pip:
 pip install qDNA
 ```
 
-To ensure compatibility and avoid conflicts with other packages, we recommend using a virtual environment. For detailed installation instructions and alternative methods, please refer to the [Installation Guide](INSTALLATION.md).
+To ensure compatibility and avoid conflicts with other packages, we recommend using a virtual environment. For detailed installation instructions and alternative methods, please refer to the [Installation Guide](installation.md).
 
 ### Example Program
 
@@ -92,7 +101,13 @@ print(f"Average charge separation {dipole} A")
 
 ## Documentation
 
-The documentation for the [latest release](https://quantumdna.readthedocs.io/en/latest/) is available for reading on Read The Docs. Tutorials can be found in a separate GitHub repository [QuantumDNA-notebooks](https://github.com/dehe1011/QuantumDNA-notebooks)
+<p align="left">
+    <a href="https://quantumdna.readthedocs.io/en/latest/?badge=latest">
+        <img src="https://readthedocs.org/projects/quantumdna/badge/?version=latest"
+            alt="Documentation Status"></a>
+</p>
+
+The documentation webpage for the latest release is available for reading on [Read The Docs](https://quantumdna.readthedocs.io/en/latest/). Tutorials can be found in a separate GitHub repository [QuantumDNA-notebooks](https://github.com/dehe1011/QuantumDNA-notebooks).
 
 ## Graphical User Interface
 
@@ -108,32 +123,38 @@ app.mainloop()
 
 The GUI allows you to easily explore and utilize the capabilities of the `qDNA` package. Below are some examples demonstrating its use:
 
-* **Menu Window:** Access various functionalities from a centralized menu.
+* **1BNA structure:** Perform simulations with geometries from publically availbale databases (here: PDB geometry of the 1BNA sequence from [RCSB.org](https://www.rcsb.org)).
 
 <p align="center">
-    <img src="docs/figures/user_interface_figures/menu_1_light.png" alt="Screenshot of the menu of the user interface.">
+    <img src="docs/figures/5_GUI.png" alt="Graphical User Interface (GUI).">
 </p>
-<blockquote><em>Screenshot of the menu of the user interface.</em></blockquote>
+<blockquote><em> Quantum-Physical Simulations with Real Geometries via the GUI
+
+**(a)** A Protein Data Bank (PDB) file containing the DNA geometry was obtained from [RCSB.org](https://www.rcsb.org) (identifier: `1BNA`) and modified using `Biovia Discovery Studio` by removing the sugar-phosphate backbone. The subsequence selected for simulation is highlighted in blue.
+
+**(b)** The GUI’s PDB Input Window allows users to upload the modified PDB file, specify an identifier, and select a Tight-Binding (TB) model. Clicking the "Save" button computes TB parameters tailored to the DNA geometry.
+
+**(c)** To simulate the highlighted sequence from (a), set the upper strand to `02G_03C_04G` and the lower strand to `23C_22G_21C`. Ensure the identifier (e.g., `1BNA`) is selected as the source. Exciton calculations can be performed using the Evaluation tab, with results displayed in the console at the bottom right (highlighted in green).
+
+**(d)** The plotting window provides a heatmap visualization of time-evolved populations for the DNA sequence highlighted in (a). All simulation steps can also be performed programmatically without the GUI, such as using Jupyter Notebooks.</em></blockquote>
 
 <ul>
     <li><strong>Plot Generation:</strong> Create plots effortlessly by submitting your parameters through the GUI.</li>
 </ul>
 
 <p align="center">
-    <img src="docs/figures/user_interface_figures/plot_1_light.png" width="60%" alt="Plot obtained after pressing the submit button on the menu.">
+    <img src="docs/figures/1BNA_2.png" width="60%" alt="Plot obtained after pressing the submit button on the menu.">
 </p>
-<blockquote><em>Plot obtained after pressing the submit button on the menu (see image above).</em></blockquote>
 
 <ul>
     <li><strong>Calculation Display:</strong> Perform calculations, such as exciton lifetime and average charge separation, and view the results directly within the interface.</li>
 </ul>
 
 <p align="center">
-    <img src="docs/figures/user_interface_figures/menu_2_light.png" alt="Screenshot of the menu of the user interface with calculations of the exciton lifetime, average charge separation and dipole moment displayed in the frame on the bottom right.">
+    <img src="docs/figures/1BNA_3.png" width="80%" alt="Screenshot of the menu of the user interface with calculations of the exciton lifetime, average charge separation and dipole moment displayed in the frame on the bottom right.">
 </p>
-<blockquote><em>Screenshot of the menu of the user interface with calculations of the exciton lifetime, average charge separation and dipole moment displayed in the frame on the bottom right.</em></blockquote>
 
-The GUI streamlines the process of working with `qDNA`, making it accessible even to those who may not be familiar with coding. Whether you're generating plots or calculating complex dynamics, the GUI provides a convenient and efficient way to achieve your goals.
+Whether you're generating plots or calculating complex dynamics, the GUI provides a convenient and efficient way to achieve your goals.
 
 ## Shortcuts
 
@@ -163,29 +184,45 @@ Papers from our group:
 
 Tight-binding parameters:
 
+
+* [R. G. Endres, D. L. Cox, and R. R. P. Singh, Colloquium: The quest for high-conductance DNA. Rev. Mod. Phys. 76, 195 (2004)](https://doi.org/10.1103/RevModPhys.76.195)
+
+* [H. Mehrez and M. P. Anantram, Interbase electronic coupling for transport through DNA. Phys. Rev. B 71, 115405 (2005)](https://doi.org/10.1103/PhysRevB.71.115405)
+
 * [L.G.D. Hawke, G. Kalosakas and C. Simserides, Electronic parameters for charge transfer along DNA. *The European Physical Journal E 32*, 291 (2010)](https://doi.org/10.1140/EPJE/I2010-10650-Y)
+
 * [C. Simserides, A systematic study of electron or hole transfer along DNA dimers, trimers and polymers. *Chemical Physics 440*, 31 (2014)](https://doi.org/10.1016/j.chemphys.2014.05.024)
+
 * [M. Mantela, C. Simserides and R. Di Felice, LCAO electronic structure of nucleic acid bases and other heterocycles and transfer integrals in B-DNA, including structural variability. *Materials 14*, 4930 (2021)](https://doi.org/10.3390/ma14174930)
 
 Tight-binding models:
 
 * [K. Lambropoulos and C. Simserides, Tight-binding modeling of nucleic acid sequences: Interplay between various types of order or disorder and charge transport. *Symmetry 11*, 968 (2019)](https://doi.org/10.3390/sym11080968)
 
-Excitons and electron-hole Coulomb interaction:
+DNA excited states and excitons:
 
 * [C. Crespo-Hernandez, B. Cohen and B. Kohler, Base stacking controls excited-state dynamics in A·T DNA. *Nature 436*, 1141 (2005)](https://doi.org/10.1038/nature03933)
+
 * [E.R. Bittner, Lattice theory of ultrafast excitonic and charge-transfer dynamics in DNA. *Journal of Chemical Physics 125*, 094909 (2006)](https://doi.org/10.1063/1.2335452)
+
+* [E. R. Bittner, Frenkel exciton model of ultrafast excited state dynamics in AT DNA double helices. Journal of Photochemistry and Photobiology A: Chemistry 190, 328-334 (2007)](https://doi.org/10.1016/j.jphotochem.2006.12.007)
+
 * [E.M. Conwell, P.M. McLaughlin and S.M. Bloch, Charge-Transfer Excitons in DNA. *The Journal of Physical Chemistry B 112*, 2268 (2008)](https://doi.org/10.1021/jp077344x)
+
 * [S. Tornow, R. Bulla, F.B. Anders and G. Zwicknagl, Multiple-charge transfer and trapping in DNA dimers. *Physical Review B 82*, 195106 (2010)](https://doi.org/10.1103/PhysRevB.82.195106)
 
-The biological relevance of DNA charge transfer:
+DNA charge transfer:
+
+* [Elizabeth M. Boon and Jacqueline K. Barton, Charge transport in DNA. Current Opinion in Structural Biology 12, 320–329 (2002)](https://doi.org/10.1016/S0959-440X(02)00327-5)
 
 * [J.C. Genereux and J.K. Barton, Mechanisms for  DNA charge transport. *Chemical Reviews 110*, 1642 (2010)](https://doi.org/10.1021/cr900228f)
+
 * [A.R. Arnold, M.A. Grodick and J.K. Barton, DNA Charge Transport: from Chemical Principles to the Cell. *Cell Chemical Biology 23*, 183 (2016)](https://doi.org/10.1016/j.chembiol.2015.11.010)
 
 Simulation of open quantum systems:
 
 * [J.R. Johansson, P.D. Nation and Franco Nori, QuTiP: An open-source Python framework for the dynamics of open quantum systems. *Computer Physics Communications 183*, 1760 (2012)](https://doi.org/10.1016/j.cpc.2012.02.021)
+
 * [quantum_HEOM (github.com/jwa7/quantum_HEOM), J.W. Abbott, 2022](https://doi.org/10.5281/zenodo.7230160)
 
 ## Support