Skip to content

GunnerLab/MCCE4-Alpha

BranchesTags

Repository files navigation

Multi-Conformation Continuum Electrostatics

MCCE Logo

Welcome to MCCE4-Alpha!

Please see our CHANGELOG at the bottom for the latest updates!

📖 MCCE4-Alpha Tutorial

Comprehensive documentation covering:

  • Installation
  • Guide: Detailed explanations of all settings
  • Example Projects

Installation

If you have sudo access or would like a system-wide installation of the needed softwares:

The file MCCE_bin/sudo_install.txt has the necessary information for you or your sys admin to install the packages. To display the file, run this command:

 cat ./MCCE_bin/sudo_install.txt

Quick Installation

"Quick Install" script MCCE_bin/quick_install.sh:

Note: The quick install script will modify an existing conda environment named 'mc4'. If you need to re-create it, to troubleshoot an installation issue, for example, run this command before running the script:

 conda env remove -n mc4
  1. Clone this repo, then cd into it with this command:
 git clone https://github.com/GunnerLab/MCCE4-Alpha.git; cd MCCE4-Alpha;
  1. Run the quick_install.sh script to download MCCE PBE solver (NGPB) image file and create a conda environment for MCCE4 (this may need several passes if you need to install dependencies such as miniconda and apptainer):
 bash ./MCCE_bin/quick_install.sh

What this script does:

  • Checks for required conda; Stops if not found so you can install it (commands provided).
  • Create a conda environment for MCCE4 named 'mc4' (using 'mc4.yml').
  • Checks for required apptainer; If a system Apptainer installation is not found & an 'unprivilege' version cannot be installed, Apptainer is conda-installed in 'mc4'.
  • Downloads the generic image for NGPB in MCCE4-Alpha/bin.
  • Adds export commands to the PATH variable in ~/.bashrc for:
    • 'MCCE4-Alpha/bin' and 'MCCE4-Alpha/MCCE_bin'
    • the unprivilege version of Apptainer if installed by the script

OPTIONAL: MCCE4-Alpha CLI (mc4)

The mc4 command-line tool runs MCCE4-Alpha inside an Apptainer container, giving you a reproducible environment with all solvers (DELPHI, APBS, NGPB) pre-configured. No sudo required.

Linux

# 1. Clone the repository
git clone https://github.com/GunnerLab/MCCE4-Alpha.git
cd MCCE4-Alpha

# 2. Run the setup script
bash setup.sh

# 3. Source your shell config (or open a new terminal)
source ~/.bashrc

# 4. You're ready
mc4 step1.py prot.pdb

macOS

# 1. Clone the repository
git clone https://github.com/GunnerLab/MCCE4-Alpha.git
cd MCCE4-Alpha

# 2. Run the macOS setup script
bash setup_mac.sh

# 3. Source your shell config (or open a new terminal)
source ~/.zshrc    # or ~/.bashrc

# 4. You're ready
mc4 step1.py prot.pdb

What the Setup Scripts Do

setup.sh (Linux)

  1. Installs Apptainer — checks for a system installation first; if unavailable, installs it via Conda into user-space (no sudo needed).
  2. Downloads the NGPB solver — fetches the pre-built NextGenPB.sif (~1.6 GB) from GitHub Releases.
  3. Builds the container — creates mcce4-alpha.sif using the definition file at bin/mcce4-alpha.def. This image contains the mc4 Conda environment, compiled MCCE4 binaries, and all three PB solvers.
  4. Updates your PATH — adds bin/ to your ~/.bashrc so mc4 is available in new terminals.
Flag Effect
(none) Smart re-run — skips steps that are already complete
--rebuild Force a full container rebuild
--build-ngpb Build NGPB from source (bin/recipe_MCCE.def) instead of downloading the pre-built image

setup_mac.sh (macOS)

macOS cannot run Apptainer natively, so the script sets up a lightweight Linux VM via Lima:

  1. Installs Lima & QEMU via Homebrew.
  2. Creates an Ubuntu 24.04 VM (mcce4) with Apptainer pre-installed and your home directory mounted read-write.
  3. Downloads the NGPB solver inside the VM.
  4. Builds the container inside the VM.
  5. Updates your PATH — adds bin/ to your ~/.zshrc (or ~/.bashrc).

Your local code edits on macOS are instantly visible inside the VM — no rebuild needed.

Flag Effect
(none) Smart re-run — skips completed steps
--rebuild Delete the VM and start fresh
--build-ngpb Build NGPB from source instead of downloading

Usage

mc4 <command> [args...]

Examples:

mc4 step1.py <pdbfile>         # Run step 1
mc4 step2.py                   # Run step 2
mc4 step3.py                   # Run step 3 (PB solver)
mc4 step4.py                   # Run step 4
mc4 getpdb 4pti                # Fetch a PDB file
mc4 which python               # Check which Python the container uses
mc4 --shell                    # Open an interactive shell inside the container

Expected output (production mode):

/opt/conda/envs/mc4/bin/python

Development Mode

Use the -d flag to bind-mount your local MCCE4-Alpha source code into the container. Changes to files on your host are reflected immediately — no rebuild required.

mc4 -d <command> [args...]

Example:

mc4 -d step1.py prot.pdb
🔧 Running in Apptainer Development Mode...
INFO:    fuse2fs not found, will not be able to mount EXT3 filesystems
Preprocessing input pdb file, identifying ligands ...

Note: Dev mode is available on Linux. On macOS, code changes are already live via Lima's mount, so -d is not needed.

How mc4 Auto-Detects Its Mode

Platform Condition Mode
Linux mcce4-alpha.sif exists + apptainer on PATH Container — apptainer exec
macOS Lima VM mcce4 exists Lima — routes through limactl shell
Either No container or VM found Native fallback — runs commands directly via the mc4 Conda env

In native fallback mode, DELPHI and APBS work but NGPB requires the container.

Troubleshooting

apptainer: command not found

Fix: Activate the environment before using the CLI:

conda activate mc4
mc4 step1.py prot.pdb

Container build killed (OOM on HPC login nodes)

If setup.sh dies at the mksquashfs step, the OOM killer likely terminated it. This is common on shared HPC login nodes with memory limits.

Options:

# Option A: Build on a compute node with more RAM
srun --mem=8G --time=30:00 bash setup.sh --rebuild

# Option B: Point temp files to a larger filesystem
export APPTAINER_TMPDIR=/scratch/$USER/tmp
mkdir -p $APPTAINER_TMPDIR
bash setup.sh --rebuild

NGPB download failed

If the ~1.6 GB NextGenPB download times out, you can retry or build from source:

# Retry download
bash setup.sh --rebuild

# Or build from source (~20-30 min, requires bin/recipe_MCCE.def)
bash setup.sh --build-ngpb

DELPHI and APBS will still work even if NGPB is unavailable.

Lima VM issues (macOS)

# Check VM status
limactl list

# Restart the VM
limactl stop mcce4 && limactl start mcce4

# Full reset
bash setup_mac.sh --rebuild

Environment update (01-08-2026):

If your 'mc4' environment predates 01-08-2026, run these commands to update it:

CLONE=$(dirname $(dirname "$(python3 -c "import os, sys; print(os.path.realpath(sys.argv[1]))" "$(which ms_protonation)")"));
conda env update -n mc4 -f "$CLONE/mc4.yml

CHANGELOG:

This section will reflect important changes and will provide you with information on how to apply them; For example, if new python packages are added to the environment file (mc4.yml), then the entry pertaining to that change will list the command(s) to update your environment.

  • 2026-04-15:

    • Feature Merge: MCCE4 Topology Agent
    • Apply changes: cd to your clone, then run git pull

  • 2026-04-09:

    • Feature Merge: MCCE4 GUI
    • Feature Merge: Protein Dipole Vectors and Visualization
    • Apply changes: cd to your clone, then run git pull

  • 2026-02-20:

    • Feature Merge: Integrated Apptainer/Singularity containerization for the MCCE4-Alpha CLI tool.
    • Automated environment setup and image building via setup.sh to ensure cross-platform portability.
    • Apply changes: cd to your clone, then run git pull
    • Apply changes: run ./setup.sh to build the new container image

  • 2026-01-30:

    • Updated submit_mcce4.sh and driver_mcce4.sh to pass environment
    • Apply changes: cd to your clone, then run git pull

  • 2026-01-26:

    • Added numba in env file:
    • Apply changes: cd to your clone, then run git pull
    • Apply changes: run these commands:
    CLONE=$(dirname $(dirname "$(python3 -c "import os, sys; print(os.path.realpath(sys.argv[1]))" "$(which mcce)")"));
conda env update -n mc4 -f $CLONE/mc4.yml

  • 2026-01-20:

    • Comprehensive update of the tutorial site
    • Minimized README file

  • 2026-01-08:

    • Updated python dependencies in mc4.yml
    • Apply changes: run these commands:
    CLONE=$(dirname $(dirname "$(python3 -c "import os, sys; print(os.path.realpath(sys.argv[1]))" "$(which mcce)")"));
conda env update -n mc4 -f "$CLONE/mc4.yml

  • 2025-11-25:

    • step1.py: Added error trapping on atom.loadline call
    • mfe.py: Updated & moved to MCCE_bin
    • Apply changes: cd to your clone, then run git pull

  • 2025-11-11:

    • Fixed deleterious typo in bin/pdbs_interfaces.py
    • Apply changes: cd to your clone, then run git pull

  • 2025-10-30:

    • Updated README: Added CHANGELOG, link to sudo_install.txt
    • Added topologies for SO4 and PO4 in param/.
    • Updated bin/step3.py with longer timeout value
    • Updated MCCE_bin/quick_install.sh
    • Apply changes: cd to your clone, then run git pull

Help us improve MCCE4

This is a testing version of MCCE4 development. Please let us know about questions, comments or report any issues you encounter here. Thank You and we hope you enjoy using MCCE4!

MCCE Wiki

Learn about MCCE, installation, available tools, and research done with MCCE. (under construction)

Copyright (C) 2024 GunnerLab This software is distributed under the terms the terms of the MIT licence

About

Alpha version of MCCE4. MCCE4 is still being updated and developed, but we hope this public version will help more people use it, and help the Gunner Lab identify issues for the full release.

gunnerlab.github.io/mcce4_tutorial/

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

3 stars

Watchers

6 watching

Forks

5 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages