wolberlab · talagayev · May 30, 2025 · Apr 30, 2025 · Apr 30, 2025 · Apr 30, 2025
diff --git a/.github/workflows/CI-CD.yml b/.github/workflows/CI-CD.yml
@@ -38,7 +38,7 @@ jobs:
 
       - name: Run black formatter
         run: |
-          black -l 99 .
+          black -l 99 . --exclude '\.ipynb$'
 
       - name: Install pytest and run tests
         run: |

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,19 +16,34 @@ The rules for this file:
   * accompany each entry with github issue/PR number (Issue #xyz)
 -->
 
-## [Unreleased]
+## Version 1.1.0
 
 ### Authors
-<!-- GitHub usernames of contributors to this release -->
+talagayev, NDoering99
 
 ### Added
-<!-- New added features -->
+- Addition of option to select final frame in OpenMMDL Analysis (2025-04-23, Issue #136, PR #140)
+- Addition of `MDontallo` Visualization (2025-04-11)
+- Addition of `SMIRNOFF` small molecule force field (2025-04-10, Issue #76)
+- Addition of `PyMOL` support for visualization (2025-04-10)
+- Added `Dockerfile` for image creation  (2025-04-10)
+- Addition of citation page in documentation (2025-04-10)
 
 ### Fixed
-<!-- Bug fixes -->
+- Fixed error cases, where `ligand name` was not specified (2025-04-22, Issue #138, PR #139)
+- Fixed wrong color of the positive and negative ionizable interactions (2025-04-21, PR #137)
+- Fixed the `XMLSerializer` error appearing during simulation (2025-04-10, Issue #122)
+- Fixed the `sanitization` implementation in OpenMMDL Setup (2025-04-09)
 
 ### Changed
-<!-- Changes in existing functionality -->
+- Scripts moved into `analysis`, `core` and visualization` sections (PR #149)
+- Functions `update_dict`, `combine_subdict_values`, `update_values`, `remove_duplicate_values`,
+  `read_pdb_as_dataframe` and `filter_and_parse_pdb`were moved to `utils.py` (PR #149)
+- Classes `ImageMerger` and `FigureArranger` were moved to `image_handler.py`
+  (2025-04-30, Issue #141, PR #142)
+- The class `TrajectorySaver` was moved to `trajectory_saving.py` (2025-04-24, Issue #141, PR #142)
+- Changed to the use of `RDKitConverter` for Ligand recognition
+  without `-l` flag in `OpenMMDL Analysis` (2025-04-10)
 
 ### Deprecated
 <!-- Soon-to-be removed features -->

diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,37 @@
+FROM ubuntu:22.04
+
+# Install Miniconda
+RUN apt-get update && apt-get install -y wget && \
+    wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh && \
+    bash miniconda.sh -b -p /opt/conda && \
+    rm miniconda.sh && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Set environment variables
+ENV PATH="/opt/conda/bin:$PATH"
+
+# Create and activate a conda environment
+RUN conda create --name openmmdl_env python=3.12 -y && \
+    echo "conda activate openmmdl_env" >> ~/.bashrc
+
+# Install OpenMM and other dependencies
+RUN conda install -n openmmdl_env -c conda-forge openmmdl -y
+
+# Set environment variables for OpenMM
+ENV PATH /opt/conda/envs/openmmdl_env/bin:$PATH
+ENV CONDA_DEFAULT_ENV openmmdl_env
+
+# Set working directory
+WORKDIR /app
+
+# Copy the OpenMMDL repository that you already cloned locally
+COPY . /app
+
+# Install OpenMMDL
+RUN pip install .
+
+# Optional: install Jupyter if you want to run notebooks
+# RUN pip install jupyterlab
+
+# Default command to run bash
+CMD ["/bin/bash"]
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@ OpenMMDL @ Molecular Design Lab
 
 | **Release**        | [![Last release tag][badge_release]][url_latest_release] ![GitHub commits since latest release (by date) for a branch][badge_commits_since]|
 | :----------------- | :------- |
-| **Availability**   | [![Condaforge][badge_conda_forge]][url_conda_forge]|
+| **Availability**   | [![Condaforge][badge_conda_forge]][url_conda_forge] ![Docker][badge_docker]|
 | **Workflows**      | ![CI_CD][badge_ci_cd] ![CodeQL][badge_codeql]|
 | **Documentation**  | [![docs][badge_docs]][url_docs] [![codecov][badge_codecov]][url_codecov]|
 | **Dependencies**   | [![rdkit][badge_rdkit]][url_rdkit] [![mdanalysis][badge_mda]][url_mda] [![Code style: black][badge_black]][url_black]|
@@ -25,6 +25,28 @@ http://openmmdl.readthedocs.io/
 
     conda install -c conda-forge openmmdl
 
+## Installation via docker
+
+**OpenMMDL** is mainly supported for Linux distribution systems, thus for Windows and MacOS the installation with docker may be preferred,
+due to docker creating an image with ubuntu:22.04
+
+For this first clone this repository
+
+    cd ~
+    git clone https://github.com/wolberlab/OpenMMDL
+
+change the path to the OpenMMDL folder and build the docker image from there
+
+    cd OpenMMDL
+    docker build -t openmmdl_env .
+
+This will build the OpenMMDL image with docker. Now that it is build you can access it through an interactive terminal
+
+    docker run -it --name openmmdl_test openmmdl_env
+
+From there you can access all the OpenMMDL entry points. Currently due to OpenMMDL Setup using flask it can be difficult
+to access it through the docker image.
+
 ## Installation via repository
 
 #### Clone this repository
@@ -157,16 +179,31 @@ Start the analysis with the following Inputs:
 #### Visualization
 Most of the analysis outputs are JEPG images and do not need any further preparation to be viewed.
 
-For the visualization of your trajectory with interaction pointclouds you can use the jupyter notebook prepared in the **OpenMMDL** repository.
+For the visualization of your complex with interaction pointclouds you can use NGLView with the jupyter notebook prepared in the **OpenMMDL** repository or visualize the pointclouds in PyMOL.
 
-Or use this command:
+### Usage
 ```
 openmmdl_visualization
 ```
-Then edit the notebook to include the output of your analysis.
+#### Optional:
+--type = Software you wish to visualize openmmdl interactions with. Options: nglview, pymol. Default: nglview
+#### NGLView
+After running the start comand a jupyter notebook will automatically open.
+Edit the notebook to include the output files of your analysis.
+Then run all cells.
+#### PyMOL
+After running the start comand a python skript will apear in your directory.
+Open up PyMOL then run these two comands in the PyMOL console:
+```
+run visualization_pymol.py
+openmdl_visualization PATH_TO_interacting_waters.pdb, modulePATH_TO_clouds.json
+```
 ## Copyright
 Copyright (c) 2022, Valerij Talagayev, Yu Chen,  Niklas Piet Doering & Leon Obendorf (Wolber lab)
 
+### Citation
+If you use OpenMMDL in your research, please cite the following [paper](https://doi.org/10.1021/acs.jcim.4c02158).
+
 #### Acknowledgments
 
 The Script is based upon the OpenMM Toolkit [OpenMM](https://github.com/openmm)
@@ -194,6 +231,7 @@ This Project is based on the
 [badge_mda]: https://img.shields.io/badge/powered%20by-MDAnalysis-orange.svg?logoWidth=16&logo=data:image/x-icon;base64,AAABAAEAEBAAAAEAIAAoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJD+XwCY/fEAkf3uAJf97wGT/a+HfHaoiIWE7n9/f+6Hh4fvgICAjwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACT/yYAlP//AJ///wCg//8JjvOchXly1oaGhv+Ghob/j4+P/39/f3IAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJH8aQCY/8wAkv2kfY+elJ6al/yVlZX7iIiI8H9/f7h/f38UAAAAAAAAAAAAAAAAAAAAAAAAAAB/f38egYF/noqAebF8gYaagnx3oFpUUtZpaWr/WFhY8zo6OmT///8BAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgICAn46Ojv+Hh4b/jouJ/4iGhfcAAADnAAAA/wAAAP8AAADIAAAAAwCj/zIAnf2VAJD/PAAAAAAAAAAAAAAAAICAgNGHh4f/gICA/4SEhP+Xl5f/AwMD/wAAAP8AAAD/AAAA/wAAAB8Aov9/ALr//wCS/Z0AAAAAAAAAAAAAAACBgYGOjo6O/4mJif+Pj4//iYmJ/wAAAOAAAAD+AAAA/wAAAP8AAABhAP7+FgCi/38Axf4fAAAAAAAAAAAAAAAAiIiID4GBgYKCgoKogoB+fYSEgZhgYGDZXl5e/m9vb/9ISEjpEBAQxw8AAFQAAAAAAAAANQAAADcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAjo6Mb5iYmP+cnJz/jY2N95CQkO4pKSn/AAAA7gAAAP0AAAD7AAAAhgAAAAEAAAAAAAAAAACL/gsAkv2uAJX/QQAAAAB9fX3egoKC/4CAgP+NjY3/c3Nz+wAAAP8AAAD/AAAA/wAAAPUAAAAcAAAAAAAAAAAAnP4NAJL9rgCR/0YAAAAAfX19w4ODg/98fHz/i4uL/4qKivwAAAD/AAAA/wAAAP8AAAD1AAAAGwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALGxsVyqqqr/mpqa/6mpqf9KSUn/AAAA5QAAAPkAAAD5AAAAhQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADkUFBSuZ2dn/3V1df8uLi7bAAAATgBGfyQAAAA2AAAAMwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB0AAADoAAAA/wAAAP8AAAD/AAAAWgC3/2AAnv3eAJ/+dgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA9AAAA/wAAAP8AAAD/AAAA/wAKDzEAnP3WAKn//wCS/OgAf/8MAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIQAAANwAAADtAAAA7QAAAMAAABUMAJn9gwCe/e0Aj/2LAP//AQAAAAAAAAAA
 [badge_black]: https://img.shields.io/badge/code%20style-black-000000.svg
 [badge_license]: https://img.shields.io/badge/License-MIT-blue.svg
+[badge_docker]: https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=fff
 
 [url_latest_release]: https://github.com/wolberlab/openmmdl/releases
 [url_ci_cd]: https://github.com/wolberlab/OpenMMDL/actions/workflows/CI-CD.yml

diff --git a/docs/api.rst b/docs/api.rst
@@ -1,9 +1,47 @@
 API Documentation
-=================
+==============================
 
-.. autosummary::
-   :toctree: autosummary
+Here is the API Documentation.
 
-   openmmdl
-   
+The following API represents the MoleculeVisualizer, which is responsible for the display of the
+molecule in IPywidgets.
 
+
+OpenMMDL Analysis API
+------------------------------
+**OpenMMDL Analysis** consists of **analysis**, **core** and **visualization** modules.
+
+Here is the API of the **analysis** modules:
+
+.. toctree::
+   :maxdepth: 3
+   :caption: API Analysis Modules:
+
+   modules/openmmdl_analysis/analysis/bindingmodes
+   modules/openmmdl_analysis/analysis/interactions
+   modules/openmmdl_analysis/analysis/markovchains
+   modules/openmmdl_analysis/analysis/rmsd
+   modules/openmmdl_analysis/analysis/stablewaters
+
+
+Here is the API of the **core** modules:
+
+.. toctree::
+   :maxdepth: 3
+   :caption: API Core Modules:
+
+   modules/openmmdl_analysis/core/preprocessing
+   modules/openmmdl_analysis/core/trajectories
+   modules/openmmdl_analysis/core/utils
+
+Here is the API of the **visualization** modules:
+
+.. toctree::
+   :maxdepth: 3
+   :caption: API Visualization Modules:
+
+   modules/openmmdl_analysis/visualization/barcodes
+   modules/openmmdl_analysis/visualization/figures
+   modules/openmmdl_analysis/visualization/highlighting
+   modules/openmmdl_analysis/visualization/pharmacophore
+   modules/openmmdl_analysis/visualization/visualization
diff --git a/docs/citation.rst b/docs/citation.rst
@@ -0,0 +1,21 @@
+Citation
+====================
+
+If you use OpenMMDL in your research, please cite the following `paper <https://doi.org/10.1021/acs.jcim.4c02158>`_:
+
+.. code-block:: text
+
+    @article{doi:10.1021/acs.jcim.4c02158,
+        author = {Talagayev, Valerij and Chen, Yu and Doering, Niklas Piet and Obendorf, Leon and Denzinger, Katrin and Puls, Kristina and Lam, Kevin and Liu, Sijie and Wolf, Clemens Alexander and Noonan, Theresa and Breznik, Marko and Knaus, Petra and Wolber, Gerhard},
+        title = {OpenMMDL - Simplifying the Complex: Building, Simulating, and Analyzing Protein–Ligand Systems in OpenMM},
+        journal = {Journal of Chemical Information and Modeling},
+        volume = {65},
+        number = {4},
+        pages = {1967-1978},
+        year = {2025},
+        doi = {10.1021/acs.jcim.4c02158},
+            note ={PMID: 39933881},
+        URL = {https://doi.org/10.1021/acs.jcim.4c02158},
+        eprint = {https://doi.org/10.1021/acs.jcim.4c02158}
+        }
+
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -15,6 +15,16 @@ What OS does OpenMMDL support?
 
 **OpenMMDL** is available for Linux and Mac systems. **OpenMMDL Setup** and **OpenMMDL Simulation** are currently incompatible with Windows systems, thus only **OpenMMDL Analysis** of the **OpenMMDL** package can be used on Windows systems.
 
+How can I install OpenMMDL?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**OpenMMDL** is available as a conda package. To install it, you can use the following command:
+.. code-block:: text
+   
+   conda install -c conda-forge openmmdl
+
+How do I cite OpenMMDL?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Please refer to the :doc:`citation` page.
 
 OpenMMDL Setup
 ------------------------------------

diff --git a/docs/index.rst b/docs/index.rst
@@ -23,6 +23,8 @@
    :caption: User guide:
 
    installation
+   changelog
+   citation
    faq
 
 .. toctree::
@@ -57,8 +59,7 @@
    :maxdepth: 1
    :caption: API Docs
 
-   openmmdl_simulation_functions
-   openmmdl_analysis_functions
+   api
 
 
 Introduction

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -3,6 +3,18 @@
 
 This page details how to install **OpenMMDL** on your local device. 
 
+Installation via conda-forge
+------------------------------
+
+**OpenMMDL** is implemented in conda-forge and can be installed for linux-based system with the following command line:
+
+.. code-block:: text
+
+    conda install -c conda-forge openmmdl
+
+Installation via repository
+------------------------------
+**OpenMMDL** can be installed through the cloning of the repository and the installation of the required packages listed in *environment.yml* or *requirements.txt*
 
 The first step of the installation of **OpenMMDL** on your device consists in the cloning of **OpenMMDL** to your home directory.
 This can be achieved by using the following command lines:
@@ -12,21 +24,50 @@ This can be achieved by using the following command lines:
     cd ~
     git clone https://github.com/wolberlab/OpenMMDL
 
-
-The next step consists of installing all required dependencies in a new separate environment, which will be used to run the **OpenMMDL** package.
 **OpenMMDL** is written in Python 3.10 and uses several packages, which can be easily installed on a separate environment using conda (we recommend using miniconda):
 
 .. code-block:: text
 
     cd OpenMMDL
-    conda create -n openmmdl c conda-forge --file requirements.txt
-
-After installation, activate the conda environment and install the **OpenMMDL** package:
-(Be sure, you are still within the OpenMMDL folder)
+    conda create -n openmmdl -c conda-forge --file requirements.txt
+
+After installation, activate the conda environment:
 
 .. code-block:: text
 
     conda activate openmmdl
+
+Install the **OpenMMDL** package with the required entry points via pip:
+
+.. code-block:: text
+
     pip install .
+
+This should lead to the environment having now all the required packages and entry points for **OpenMMDL**.
+
+Installation via Docker
+------------------------------
+
+**OpenMMDL** is mainly supported for Linux distribution systems, thus for Windows and MacOS the installation with docker may be preferred, due to docker creating an image with *ubuntu:22.04*.
+
+For this first clone this repository:
+
+.. code-block:: text
+
+    cd ~
+    git clone https://github.com/wolberlab/OpenMMDL
+
+change the path to the **OpenMMDL** folder and build the docker image from there:
+
+.. code-block:: text
+
+    cd OpenMMDL
+    docker build -t openmmdl_env .
+
+This will build the **OpenMMDL** image with docker. Now that it is build you can access it through an interactive terminal:
+
+.. code-block:: text
+
+    docker run -it --name openmmdl_test openmmdl_env
 
-Now with **OpenMMDL** being installed on the local device, everything is set up to work with **OpenMMDL**.
+From there you can access all the **OpenMMDL** entry points. Currently due to **OpenMMDL Setup** using flask it can be difficult to access it through the docker image.