Added a new tutorial notebook, improved the readme file

.github/workflows/coverage.yml → .github/workflows/code-quality.yml

@@ -1,4 +1,4 @@
-name: Coverage with coveralls
+name: Code quality
 
 on: [push, pull_request]
 
@@ -13,13 +13,25 @@ jobs:
  - name: Set up Python
  uses: actions/setup-python@v4
  with:
- python-version: '3.9'
+ python-version: '3.x'
 
  - name: Install dependencies
  run: |
  python -m pip install --upgrade pip
  pip install -r configs/requirements.txt
- pip install coverage pytest coveralls
+ pip install -r configs/dev-requirements.txt
+
+ - name: Run black
+ continue-on-error: true
+ run: black --check .
+
+ - name: Run lint with pylint
+ continue-on-error: true
+ run: |
+ find qDNA tools -type f -name "*.py" ! -name "__init__.py" | xargs pylint
+
+ - name: Run tests with pytest
+ run: python -m pytest
 
  - name: Run tests with coverage
  run: |

.github/workflows/jekyll-gh-pages.yml

@@ -2,9 +2,8 @@
 name: Deploy Jekyll with GitHub Pages dependencies preinstalled
 
 on:
- # Runs on pushes targeting the default branch
- push:
- branches: ["main"]
+ release:
+ types: [created]
 
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

README.md

@@ -18,11 +18,17 @@
  <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>
+ <a href='https://github.com/psf/black'>
+  <img src='https://img.shields.io/badge/code%20style-black-000000.svg'
+  alt='Code Style: black' /></a>
 </p>
 
 ---
 
-# QuantumDNA
+# QuantumDNA 
 
 **Author: [Dennis Herb](https://github.com/dehe1011)**
 
@@ -57,7 +63,9 @@ Welcome to QuantumDNA, a powerful and flexible tool designed to calculate lifeti
 
 For a quick installation, you can install the `qDNA` package using pip within a virtual environment:
 
-```pip install qDNA```
+```bash
+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).
 
@@ -92,14 +100,20 @@ The documentation for the [latest release](https://quantumdna.readthedocs.io/en/
 
 The code contains some tutorials and demonstrations to better understand and explore the functionalities. 
 
-In the `QuantumDNA/docs/tutorials` folder you can find the notebook **3_Paper.ipynb** that contains and reproduces all the figures contained in [D. Herb, M. Rossini and J. Ankerhold, Ultrafast excitonic dynamics in DNA: Bridging correlated quantum dynamics and sequence dependence.](https://arxiv.org/abs/2402.16892)
+In the [`docs/tutorials`](docs/tutorials) folder you can find the notebook **0_Paper.ipynb** that contains and reproduces all the figures contained in [D. Herb, M. Rossini and J. Ankerhold, Ultrafast excitonic dynamics in DNA: Bridging correlated quantum dynamics and sequence dependence.](https://arxiv.org/abs/2402.16892)
 
 Additionally, the `QuantumDNA/docs/tutorials` folder contains the following tutorials:
 
-* **0_TB_Model.ipynb**: tutorials on predefined and custom tight-binding models.
-* **1_Plotting_Routines.ipynb**: tutorial on the predefined plotting routines.
-* **2_Open_System.ipynb**: tutorial on different ways to treat DNA relaxation in the DNA environment.
-* **Exploration_Notebook.ipynb**: A place to test the functionality of individual functions isolated from the rest of the code.
+# QuantumDNA Tutorials
+
+| Tutorial Name | Description |
+|------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
+| [**1_TB_Model**](docs/tutorials/1_TB_Model.ipynb) | Tutorials on predefined and custom tight-binding models. |
+| [**2_Data_Visualization**](docs/tutorials/2_Data_Visualization.ipynb) | Tutorial on the predefined plotting routines. |
+| [**3_DNA_environment**](docs/tutorials/3_DNA_environment.ipynb) | Tutorial on different ways to treat DNA relaxation and the DNA environment. |
+| [**4_Parallelized_Calculations**](docs/tutorials/4_Parallelized_Calculations.ipynb) | Tutorial on how to perform parallelized calculations for several properties. |
+| [**Exploration_Notebook**](docs/tutorials/Exploration_Notebook.ipynb) | A place to test the functionality of individual functions isolated from the rest of the code. |
+
 
 These tutorials provide hands-on examples and explanations to help you effectively use the `qDNA` package.
 
@@ -118,7 +132,7 @@ 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.*
+* **Menu Window:** Access various functionalities from a centralized menu.
 
 ![](docs/figures/user_interface_figures/menu_1.png)
 > _Screenshot of the menu of the user interface._
@@ -140,20 +154,20 @@ The GUI streamlines the process of working with `qDNA`, making it accessible eve
 
 To enhance the readability and maintainability of the code, we have standardized a set of frequently used shortcuts. These abbreviations help keep the code concise while still being clear and understandable:
 
-* ham: hamiltonian
-* dm: density matrix
-* tb: tight-binding
-* eigv: eigenvalue/ eigenenergy
-* eigs: eigenstates/ eigenvectors
-* dim: dimension
-* fig: figure
-* op: operator
-* loc: local
-* glob: global
-* deph: dephasing
-* therm: thermalizing
-* seq: sequence
-* calc: calculate
+* ```ham```: hamiltonian
+* ```dm```: density matrix
+* ```tb```: tight-binding
+* ```eigv```: eigenvalue/ eigenenergy
+* ```eigs```: eigenstates/ eigenvectors
+* ```dim```: dimension
+* ```fig```: figure
+* ```op```: operator
+* ```loc```: local
+* ```glob```: global
+* ```deph```: dephasing
+* ```therm```: thermalizing
+* ```seq```: sequence
+* ```calc```: calculate
 
 
 ## References

docs/tutorials/Exploration_Notebook.ipynb

@@ -7,6 +7,10 @@
  "metadata": {},
  "outputs": [],
  "source": [
+ "# %pip install qDNA\n",
+ "# from qDNA import ROOT_DIR\n",
+ "\n",
+ "# This can be used alternatively if you cloned the GitHub repository\n",
  "import os\n",
  "ROOT_DIR = os.getcwd()[:os.getcwd().rfind('QuantumDNA')]+ 'QuantumDNA'\n",
  "os.chdir(ROOT_DIR)"
@@ -267,9 +271,9 @@
  ],
  "metadata": {
  "kernelspec": {
- "display_name": "Python (qDNA)",
+ "display_name": "Python 3 (ipykernel)",
  "language": "python",
- "name": "qdna"
+ "name": "python3"
  },
  "language_info": {
  "codemirror_mode": {

installation.md

@@ -3,14 +3,20 @@
 ## Installation via PyPI:
 
 We recommend creating a new virtual environment and Jupyter notebook kernel to avoid conflicts with existing packages like `qutip`. 
-1. Create a new virtual environment (using conda):\
-```conda create -n qDNA```
+1. Create a new virtual environment (using conda):
+```bash
+conda create -n qDNA
+```
 
-2. Create a new Jupyter kernel (if you are using Jupyter notebook):\
- ```ipykernel install --name qDNA --display-name "Python (qDNA)"```
+2. Create a new Jupyter kernel (if you are using Jupyter notebook):
+ ```bash
+ ipykernel install --name qDNA --display-name "Python (qDNA)"
+ ```
 
-3. Install the qDNA package:\
-```pip install qDNA```
+3. Install the qDNA package:
+```bash
+pip install qDNA
+```
 
 
 ## Installation via Cloning the Github Repository
@@ -29,14 +35,20 @@ If you want to make changes to the source code or try the example notebooks, you
 
 Open the Anconda Powershell Prompt. Copy and execute the following ```commands```.
 
-1. Clone the Github repository: \
-```git clone https://github.com/dehe1011/QuantumDNA.git```
+1. Clone the Github repository: 
+```bash
+git clone https://github.com/dehe1011/QuantumDNA.git
+```
 
-2. Navigate to the project directory: \
-```cd QuantumDNA ```
+2. Navigate to the project directory: 
+```bash
+cd QuantumDNA
+```
 
-2. Create and active a virtual environment (using a provided script): \
-```powershell -ExecutionPolicy Bypass -File tools/scripts/activate.ps1```
+2. Create and active a virtual environment (using a provided script): 
+```bash
+powershell -ExecutionPolicy Bypass -File tools/scripts/activate.ps1
+```
 
 If all tests passed, the package has been successfully installed, and the user interface opens automatically. You can access all the implemented functionalities. Enjoy!
 
@@ -46,16 +58,22 @@ After installing the package, you can access the code via the user interface or
 
 Using the User Interface: 
 
-1. Open the Anaconda PowerShell Prompt and navigate to the package directory:\
- ```Set-Location -Path "C:\Users\<YourUsername>\QuantumDNA``` 
+1. Open the Anaconda PowerShell Prompt and navigate to the package directory:
+ ```bash
+ Set-Location -Path "C:\Users\<YourUsername>\QuantumDNA
+ ``` 
 
-2. Run the activation script: \
-```powershell -ExecutionPolicy Bypass -File tools/scripts/activate.ps1```
+2. Run the activation script: 
+```bash
+powershell -ExecutionPolicy Bypass -File tools/scripts/activate.ps1
+```
 
 Using Jupyter Notebook: 
 
-1. Open a new Jupyter Notebook: \
-```jupyter notebook```
+1. Open a new Jupyter Notebook: 
+```bash
+jupyter notebook
+```
 
 2. Select the kernel "Python (qDNA)":
  * In the Jupyter Notebook interface, go to Kernel > Change kernel > Python (qDNA)
@@ -65,11 +83,15 @@ Using Jupyter Notebook:
 
 To remove the virtual environment and Jupyter kernel:
 
-1. Remove the virtual environment:\
- ```conda remove --name qDNA --all``` 
+1. Remove the virtual environment:
+ ```bash
+ conda remove --name qDNA --all
+ ``` 
 
-2. Remove the Jupyter kernel:\
- ```jupyter kernelspec remove qDNA``` 
+2. Remove the Jupyter kernel:
+ ```bash
+ jupyter kernelspec remove qDNA
+ ``` 
  
 3. Delete the project folder:
  * Manually delete the `QuantumDNA` folder that contains the cloned GitHub repository.