How to Install mdxplain

Prerequisites

  • Python >= 3.8 (Python 3.12 recommended)

  • Virtual environment manager (conda or venv)

Quick Setup

mdxplain uses a Makefile for streamlined installation and development workflows.

git clone https://github.com/maximilian-salomon/mdxplain.git
cd mdxplain

Python Virtual Environment (Alternative)

Create a new virtual environment with production dependencies, Jupyter, and nglview:

make setup-venv
source mdxplain-venv/bin/activate

Install in Existing Environment

Install mdxplain core package in your currently active environment:

# Without Jupyter notebooks and nglview
make install

# With Jupyter notebooks and nglview
make install-jupyter

Optional: PyMOL Installation

PyMOL is not included in the standard installation to avoid compatibility issues due to its complex system-level dependencies. If you need PyMOL for 3D structure visualization, install it separately:

make install-pymol

Note: For system-specific installation instructions, please refer to the official PyMOL documentation <https://www.pymol.org/>. Alternatively, you can install PyMOL independently and load mdxplain’s generated PyMOL scripts manually.

Installation Options

Environment Setup Commands

Command

Environment

Description

make setup-conda

conda

Production dependencies with Jupyter and nglview (no PyMOL)

make setup-dev-conda

conda

Development dependencies with Jupyter and nglview (no PyMOL)

make setup-pymol-conda

conda

Production dependencies with Jupyter, nglview and PyMOL

make setup-venv

venv

Production dependencies with Jupyter and nglview (no PyMOL)

make setup-dev-venv

venv

Development dependencies with Jupyter and nglview (no PyMOL)

make setup-pymol-venv

venv

Production dependencies with Jupyter, nglview and PyMOL

Installation in Existing Environment

Command

Description

make install

Install core package only (no Jupyter, no PyMOL)

make install-dev

Install with development dependencies plus Jupyter and nglview (no PyMOL)

make install-jupyter

Install Jupyter and nglview (adds to existing installation)

make install-pymol

Install PyMOL for 3D structure visualization

make install-full

Install with full dependencies including Jupyter and PyMOL

What’s Included

Production Setup (make setup-conda / make setup-venv)

  • Core mdxplain package

  • Jupyter ecosystem (JupyterLab, notebook, ipykernel, ipywidgets)

  • nglview for interactive 3D visualization in Jupyter

  • DPA (Density Peak Algorithm)

Core Installation (make install)

  • Core mdxplain package with basic dependencies

  • DPA (Density Peak Algorithm)

  • No Jupyter, no nglview, no PyMOL

  • Use this for minimal installations or server environments

Development Setup (make setup-dev-conda / make setup-dev-venv / make install-dev)

  • All production dependencies (core + Jupyter + nglview, no PyMOL)

  • Code formatting and style tools (black, autopep8, isort)

  • Linting and analysis tools (flake8, pylint, mypy, pydocstyle, etc.)

  • Testing and coverage tools (pytest, coverage)

  • Documentation tools (sphinx, sphinx-rtd-theme, myst-nb)

  • Security and profiling tools (bandit, safety, memory-profiler, snakeviz)

PyMOL Setup (make setup-pymol-conda / make setup-pymol-venv / make install-pymol)

  • Production dependencies with Jupyter, nglview and PyMOL

  • PyMOL for advanced 3D structure visualization (pymol-open-source >= 3.2.0a0)

  • Separate installation option to avoid compatibility issues

  • PyMOL only works in terminal/script environments (not Jupyter notebooks)

  • nglview provides 3D visualization within Jupyter notebooks

Jupyter Addition (make install-jupyter)

  • Jupyter ecosystem (JupyterLab, notebook, ipykernel, ipywidgets)

  • nglview for interactive 3D visualization

  • Adds Jupyter to existing mdxplain installation (e.g., after make install)

  • Use this if you installed core only but now need Jupyter support

Complete Installation (make install-full)

  • Full installation with all dependencies in existing environment

  • Core mdxplain package

  • Jupyter ecosystem (JupyterLab, notebook, ipykernel, ipywidgets)

  • nglview for interactive 3D visualization in Jupyter

  • PyMOL for advanced 3D structure visualization

Additional Commands

Jupyter

make jupyter       # Start JupyterLab
make notebook      # Start classic Jupyter Notebook

Development

make test          # Run tests with pytest
make lint          # Run code quality checks
make format        # Format code with black and isort
make html          # Build documentation
make clean         # Remove environments and cache files

Help

To see all available commands:

make help

Install on Windows

Windows requires Make to be installed for using the Makefile commands. If you don’t have Make, you can install it via Chocolatey or use the manual pip/conda commands below.

All make command except PyMOL installation are supported on Windows.

PyMOL Installation on Windows

The make install-pymol command is not supported on Windows due to PyMOL’s GUI-specific dependencies and the need for pre-built wheel files. Instead, install PyMOL manually using pre-compiled wheels.

Installation Steps:

Download and install the appropriate PyMOL wheel for your Python version from the official releases:

# Example for Python 3.12
wget https://github.com/cgohlke/pymol-open-source-wheels/releases/download/v2025.10.30/pymol-3.2.0a0-cp312-cp312-win_amd64.whl
pip install pymol-3.2.0a0-cp312-cp312-win_amd64.whl
Note:

  • Make sure to select the correct wheel file matching your Python version (e.g., cp312 for Python 3.12, cp311 for Python 3.11).

  • PyMOL version 3.2.0a0 or higher is required for compatibility with numpy 2.x.

  • For detailed instructions and troubleshooting, visit the PyMOL Windows Wheels repository.

Manual Installation (without Make)

  1. Create a virtual environment:

    # Using conda
conda create -n mdxplain python=3.12 -y
conda activate mdxplain

# Using venv
python -m venv mdxplain-venv
mdxplain-venv\Scripts\activate

  2. Install mdxplain with desired dependencies:

    # Production with Jupyter and nglview (no PyMOL)
pip install .[jupyter]
pip install --no-deps DPA

# Development with Jupyter and nglview (no PyMOL)
pip install .[dev,jupyter]
pip install --no-deps DPA

  3. Install PyMOL separately:

# Example for Python 3.12
wget https://github.com/cgohlke/pymol-open-source-wheels/releases/download/v2025.10.30/pymol-3.2.0a0-cp312-cp312-win_amd64.whl
pip install pymol-3.2.0a0-cp312-cp312-win_amd64.whl