new commit

.gitignore

@@ -8,6 +8,11 @@ TODO.txt
 main.py
 qDNA/data/raw/geometries/
 
+# documentation
+docs/_build
+docs/_static
+docs/_templates
+
 # created by coverage
 htmlcov/
 
@@ -18,6 +23,9 @@ __pycache__
 # pylint
 .pylintrc
 
+# mypy
+.mypy_cache/
+
 # created by coverage
 *.egg-info/
 .coverage

docs/_build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 0ddaa2a6a2c02a5cffaf66f59ffdd527
+config: 9e56602128238809abc61f630ee6f09e
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_build/html/_sources/guide/guide.rst.txt

@@ -1,13 +1,80 @@
 .. _guide:
 
-***********
-Users Guide
-***********
+**************************
+Jupyter Notebook Tutorials
+**************************
 
-The goal of this guide is to introduce you to the basic structures and functions that make up QuantumDNA.
-Have a look at the :ref:`API documentation <apidoc>` for a more detailed description of the classes and functions.
+Welcome to the **QuantumDNA Jupyter Notebook Tutorials**! These tutorials and demonstrations are designed to help users explore and
+understand the functionalities of the `qDNA` package through practical examples.
+
+For a detailed description of the classes and functions used in these tutorials, visit the :ref:`API documentation <apidoc>`.
+
+Overview
+========
+
+The Jupyter notebooks in the `tutorials` folder provide step-by-step demonstrations of various features and functionalities of the `qDNA` package.
+Each tutorial focuses on a specific aspect, helping you get started with quantum physical description of DNA and applications of quantum biology.
+
+Tutorials
+=========
+
+Below is a list of available tutorials. Click on each to access the detailed notebook:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+
+   PRE_2024 <tutorials/PRE_2024>
+   Tight Binding Parameters <tutorials/1_Tight_Binding_Parameters>
+   Tight Binding Method <tutorials/2_Tight_Binding_Method>
+   Environment Simulation <tutorials/3_Environment_Simulation>
+   Visualization <tutorials/4_Visualization>
+   Evaluation <tutorials/5_Evaluation>
+
+Descriptions
+------------
+
+**PRE2024**
+  Reproduces all the figures presented in the reference paper :cite:`Herb2024`.
+  This serves as a comprehensive example of `qDNA`'s visualization and analysis features.
+
+**Tight_Binding_Parameters**
+  Learn the Linear Combination of Atomic Orbitals (LCAO) approach using Slater–Koster two-center
+  integrals and Harrison-type expressions. Ideal for tight-binding model parameterization.
+
+**Tight_Binding_Method**
+  Explore predefined and custom tight-binding models. Includes calculating time-averaged exciton
+  populations in the Fishbone Ladder Model (FLM) and simulating charge transfer in the
+  Fenna-Matthews-Olson (FMO) complex.
+
+**Environment_Simulation**
+  Model DNA excited-state relaxation and environmental interactions. This tutorial covers dephasing
+  and thermalization models inspired by Quantum Biology.
+
+**Visualization**
+  Use `qDNA`'s built-in plotting routines for effective result visualization. Learn to create custom
+  visualizations tailored to your data.
+
+**Evaluation**
+  Perform calculations for observables like exciton lifetimes, average charge separation, and dipole
+  moments. Includes parallelization features for efficient computation.
+
+
+Getting Started
+===============
+
+These tutorials provide hands-on examples designed to guide you through using the `qDNA` package effectively. To get started:
+
+1. Navigate to the `tutorials` folder and open the desired `.ipynb` file in Jupyter Notebook or JupyterLab.
+2. Follow the instructions provided in the notebook to run the cells and explore the package's features interactively.
+3. Refer to the :ref:`API documentation <apidoc>` for deeper insights into the functions and classes used in the tutorials.
+
+
+Tips for Using the Tutorials
+----------------------------
+
+- **Run in a Jupyter Environment**: Ensure you have Jupyter Notebook or JupyterLab installed to execute the tutorials interactively.
+- **Dependencies**: Before starting, confirm that all dependencies for `qDNA` are installed. Check the `requirements.txt` file in the repository for details.
+- **Explore Further**: Modify and experiment with the code to deepen your understanding of the concepts.
+
 
-   guide-tb_model.rst
+We hope these tutorials help you leverage the full potential of the `qDNA` package for your quantum biology research!

docs/_build/html/_sources/installation.rst.txt

@@ -1,79 +1,204 @@
-Installation
-============
 
-**NOTE**: These set-up instructions have only been tested on Windows.
+******************
+Installation Guide
+******************
+
+Welcome to the installation guide for `QuantumDNA`. Follow the steps below to install the package, set up a virtual environment, and start using `qDNA` either through a Graphical User Interface or a Jupyter Notebook.
+
 
 Installation via PyPI
----------------------
+=====================
+
+The easiest way to install `qDNA` is through PyPI. For best results, we recommend creating a new virtual environment to avoid package conflicts.
+
+Steps
+-----
 
-We recommend creating a new virtual environment and Jupyter notebook kernel to avoid conflicts with existing packages.
+1. **Create a New Virtual Environment**:
 
-1. Open the Windows Powershell and navigate to your project folder. Create a new virtual environment:
+   Open your terminal and navigate to your project folder. Run:
 
    .. code-block:: bash
 
-       python -m venv .venv
+      python -m venv .venv
 
-2. Activate the virtual environment:
+2. **Activate the Virtual Environment**:
 
-   .. code-block:: bash
+   - **Windows**:
+
+     .. code-block:: bash
+
+        .venv\Scripts\activate
+
+   - **macOS/Linux**:
 
-       .venv/Scripts/activate.ps1
+     .. code-block:: bash
 
-3. Install the qDNA package:
+        source .venv/bin/activate
+
+3. **Install the `qDNA` Package**:
 
    .. code-block:: bash
 
-       pip install qDNA
+      pip install qDNA
+
+4. **Optional: Use `qDNA` Inside a Jupyter Notebook**:
 
-*Optional*: Use `qDNA` inside a Jupyter notebook:
+   Install Jupyter and launch the notebook:
 
    .. code-block:: bash
 
-       pip install ipykernel
-       jupyter notebook
+      pip install ipykernel notebook
+      jupyter notebook
+
 
 Installation via Cloning the GitHub Repository
-----------------------------------------------
+==============================================
+
+If you plan to contribute to the development or make changes to the source code, install `qDNA` in editable mode by cloning its GitHub repository.
+
+Prerequisites
+-------------
+
+Before proceeding, make sure the following prerequisites are met:
+
+1. **Python Installation**:
+
+   - Verify that Python is installed by running:
+
+     .. code-block:: bash
 
-If you want to make changes to the source code, you can clone the project's GitHub repository and install it in editable mode. On Windows, you first need to install Git (`Download <https://gitforwindows.org/>`_).
+        python --version
 
-1. Clone the GitHub repository:
+   - If Python is not installed, download and install it from `python.org <https://www.python.org/downloads/>`_.
+
+2. **Linux/macOS Users**:
+
+   - Ensure `pip` and `tkinter` are installed:
+
+     .. code-block:: bash
+
+        python3 -m pip --version
+        python3 -m tkinter
+
+   - If they are not installed, install them using your package manager:
+
+     - **Debian/Ubuntu**:
+
+       .. code-block:: bash
+
+          sudo apt install python3-pip python3-tk
+
+     - **Fedora**:
+
+       .. code-block:: bash
+
+          sudo dnf install python3-pip python3-tkinter
+
+3. **Windows Users**:
+
+   - Ensure Git is installed by running:
+
+     .. code-block:: bash
+
+        git --version
+
+   - If Git is not installed, download and install it from `Git for Windows <https://gitforwindows.org/>`_.
+
+Steps
+-----
+
+1. **Clone the GitHub Repository**:
 
    .. code-block:: bash
 
-       git clone https://github.com/dehe1011/QuantumDNA.git
+      git clone https://github.com/dehe1011/QuantumDNA.git
 
-2. Navigate to the directory of the cloned repository:
+2. **Navigate to the Cloned Repository**:
 
    .. code-block:: bash
 
-       cd QuantumDNA
+      cd QuantumDNA
+
+3. **Run the Activation Script**:
+
+   Use the provided activation script to complete the installation. Instructions vary by platform (see below).
+
+
+Platform-Specific Instructions for Activation
+=============================================
+
+**Windows**
+-----------
+
+1. Navigate to the project directory:
+
+   .. code-block:: powershell
 
-3. Use the provided activation script to finish the installation. Optionally, you can open the Graphical User Interface or a Jupyter Notebook:
+      Set-Location -Path "C:\Users\<YourUsername>\QuantumDNA"
+
+2. Run the activation script:
+
+   .. code-block:: powershell
+
+      powershell -ExecutionPolicy Bypass -File scripts\Activate.ps1
+
+
+**macOS**
+---------
+
+1. Navigate to the project directory:
 
    .. code-block:: bash
 
-       powershell -ExecutionPolicy Bypass -File scripts/activate.ps1
+      cd /Users/<YourUsername>/QuantumDNA
 
-If all tests passed, the package has been successfully installed, and you can access all the implemented functionalities. Enjoy!
+2. Run the activation script:
 
-Usage
------
+   .. code-block:: bash
 
-After installing the package, you can access the code via the Graphical User Interface or in a Jupyter Notebook simply by running the activation script again:
+      source scripts/activate
 
-.. code-block:: bash
+---
+
+**Linux**
+---------
+
+1. Navigate to the project directory:
+
+   .. code-block:: bash
+
+      cd /home/<YourUsername>/QuantumDNA
+
+2. Run the activation script:
+
+   .. code-block:: bash
+
+      source scripts/activate
+
+---
+
+Post-Installation and Usage
+===========================
+
+If all tests pass, the package has been successfully installed! You can now:
+
+- Launch the **Graphical User Interface** or
+- Start using `qDNA` inside a **Jupyter Notebook**.
+
+Run the activation script as mentioned in the platform-specific instructions to start the **Graphical User Interface** or a **Jupyter Notebook**. It is recommended to always run the activation script.
 
-    powershell -ExecutionPolicy Bypass -File scripts/activate.ps1
 
 Uninstallation
---------------
+==============
 
-Uninstall the package by running:
+To remove the package:
 
 .. code-block:: bash
 
-    pip uninstall qDNA
+   pip uninstall qDNA
+
+If you cloned the GitHub repository, manually delete the `QuantumDNA` folder from your computer.
+
 
-If you cloned the GitHub repository, remember to manually delete the `QuantumDNA` folder from your computer.
+🎉 **Congratulations!** You’ve successfully installed and set up `QuantumDNA`. Enjoy exploring the physics of DNA with this powerful tool.