GitHub | GitLab mirror | Preprint

Installation¶

This page provides instructions for installing the CABS-flex/CABS-dock standalone package.

TL;DR (Quick Install)¶

If you are on Linux or macOS, run these commands to install with default settings:

# Clone from GitHub
git clone https://github.com/LCBio/cabsflex.git
# OR from GitLab mirror (specifying folder name 'cabsflex'):
# git clone https://gitlab.com/lcbio1/CABSflex_standalone.git cabsflex

cd cabsflex
bash install.sh

After installation, activate the environment:

micromamba activate cabs

1. Prerequisites¶

⬆ Back to top

Before installation, ensure you have the following:

• Linux OS (recommended) or MacOS.
• Windows (via WSL 2 — see Section 4).
• Bash shell.
• Git (for repository access).
• curl and tar (for downloading and extracting dependencies).
• Python 3.7+ (mandatory for venv installation).
• Micromamba (optional - see note).

2. Standard Installation (Recommended)¶

⬆ Back to top

This method uses Micromamba to manage the environment. The installer automatically sets up a dual-environment system to ensure stability for reconstruction.

Step 1: Clone and Run the Installer¶

# Clone from GitHub
git clone https://github.com/LCBio/cabsflex.git
# OR from GitLab mirror (specifying folder name 'cabsflex'):
# git clone https://gitlab.com/lcbio1/CABSflex_standalone.git cabsflex

cd cabsflex
bash install.sh

Step 2: Configure Modeller (Optional)¶

During installation, you will be prompted for your MODELLER license key. - If provided, the installer will automatically locate and patch the configuration. - If you skip this step, you can always add the key later by following the instructions in Section 4.

Step 3: Activate and Use¶

The installer creates: 1. cabs: Main environment for simulations. 2. cabs_reconstruct: Segregated environment for cg2all reconstruction.

Activate the main environment:

micromamba activate cabs

The path to cabs_reconstruct is automatically saved in the configuration, so you don't need to activate it manually.

You can now use CABSflex and CABSdock commands.

3. HPC Installation¶

⬆ Back to top

For users on High-Performance Computing (HPC) clusters there are two possible installation procedures and two seperate scripts are provided for each.

Step 1: Clone the Repository¶

Common to all source-based installations on HPC clusters:

# Clone from GitHub
git clone https://github.com/LCBio/cabsflex.git
# OR from GitLab mirror (specifying folder name 'cabsflex'):
# git clone https://gitlab.com/lcbio1/CABSflex_standalone.git cabsflex

cd cabsflex

Step 2: Identify Storage Locations (Filesystem Check)¶

Before configuring any installer, identify your storage quotas and performance tiers:

• HOME: Usually persistent but limited in space. Best for the BASE_INSTALL_DIR.
• SCRATCH: Fast, high-capacity, but temporary. Use this for TEMP_ROOT in the scripts to handle heavy I/O during installation.
• Persistent/Project Storage: Recommended for BASE_INSTALL_DIR if your home directory is small or has limited quotas on the HPC.

Option A: HPC Micromamba Installer (install-hpc-micromamba.sh)¶

Recommended if your cluster allows Micromamba. This installer is largely self-contained.

Step 3: Configure Environment Variables¶

Open install-hpc-micromamba.sh and edit the configuration block at the top:

• BASE_INSTALL_DIR: Persistent path for the installation. Do not use scratch for the install root.
• TEMP_ROOT: Path for high-I/O temporary operations (e.g., $SCRATCH).
• MODELLER_KEY: Your MODELLER license key (optional).

Step 4: Run the Installer¶

bash install-hpc-micromamba.sh

Option B: HPC Virtualenv Installer (install-hpc.sh)¶

For clusters where Micromamba is not permitted. This method uses standard Python virtual environments.

Step 3: Identify and Load Modules¶

Before installing, identify and load compatible versions of GCC and Python on your cluster. This is required to create the virtual environment and build components:

module avail GCC
module avail Python
module load GCC/13.2.0 Python/3.11.5

Step 4: Configure Environment Variables¶

Open install-hpc.sh and edit the configuration section at the top:

• BASE_INSTALL_DIR: Where the virtual environment will live (e.g., inside your home directory or persistent project storage).
• TEMP_ROOT: Set to your cluster's high-speed scratch directory (e.g., $SCRATCH).
• MODELLER_KEY: Your MODELLER license key.
• GCC_MODULE: The exact name of the GCC module to load.
• PYTHON_MODULE: The name of the Python module to load.

Step 5: Run the Installer¶

bash install-hpc.sh

Step 6: Activate the Environment¶

source path/to/your/venv/bin/activate

4. Windows Support (WSL 2) Tips¶

⬆ Back to top

For Windows users, it is mandatory to use the Windows Subsystem for Linux (WSL 2). Native Windows Python is not supported.

How to enable WSL 2:

1. Open PowerShell as Administrator.
2. Run the command: wsl --install
3. Restart your computer.
4. Search for "Ubuntu" in the Start menu to open the Linux terminal.
5. Set up your Linux username and password.
6. Proceed with the Standard Installation (Section 2) within this Ubuntu terminal.

WSL Optimization Tips:

1. Memory Allocation: All-atom reconstruction (cg2all) is memory intensive. If you experience crashes, ensure your .wslconfig (in %USERPROFILE%) allocates at least 8GB-12GB of RAM.

[wsl2]
memory=12GB

1. Filesystem Performance: For maximum performance, clone and run CABS-flex from the native Linux filesystem (e.g., ~/projects/) instead of the Windows mount (/mnt/c/...).
2. Shell Job Control: If running custom test scripts or parallel wrappers, enable monitor mode (set -m) to ensure jobs surveillance works correctly in non-interactive shells.

5. Optional Dependencies¶

⬆ Back to top

MODELLER (Optional)¶

CABS-dock can use MODELLER as an alternative to cg2all for all-atom reconstruction.

If you skipped this step during installation or need to update your key, follow these instructions:

• Get a key: Register at https://salilab.org/modeller/registration.html (free for academic use).
• Manual Configuration: Locate the MODELLER configuration file and update the license key:

# Locate the config file automatically (for Micromamba install)
MOD_CONFIG=$(micromamba run -n cabs python -c "import modlib.modeller.config as c; print(c.__file__)")

# OR for standard venv users (after activating the environment)
MOD_CONFIG=$(python -c "import modlib.modeller.config as c; print(c.__file__)")

# Set the license
sed -i "s/license = .*/license = r'YOUR_KEY'/" $MOD_CONFIG

cg2all¶

The default all-atom reconstruction tool used in CABS-flex and CABS-dock. All installers set this up automatically in a segregated environment to avoid dependency conflicts.

6. Troubleshooting & FAQ¶

⬆ Back to top

7. Verification & Quick Runs¶

⬆ Back to top

Standard Verification¶

Verify that the commands are recognized (ensure your environment is activated with micromamba activate cabs):

CABSflex --help
CABSdock --help

Alternatively, run without activation:

micromamba run -n cabs CABSflex --help

Quick Runs (Check if installation works)¶

To quickly verify that the simulation and reconstruction engine are working correctly, run a short simulation of a small protein (e.g., 1HPW). This should take only a few minutes:

# Run 10 annealing cycles (default is 20) with fewer MC cycles
CABSflex -i 1hpw -a 10 -y 20

If the run completes without errors and you see model_1.pdb ... model_10.pdb in the output_pdbs/ directory, your installation is fully functional.

← Overview | ⬆ Back to top | Next: Modeling Scheme