Installation#

Before installing Mosaic, ensure your system meets the following requirements.

Prerequisites#

  • Python: 3.11+ (3.11 recommended)

  • Operating System:

    • Linux (recommended)

    • macOS (some performance limitations noted below)

    • Windows 10+ (not tested but principally supported)

  • Hardware:

    • Standard consumer laptops (8GB RAM recommended)

    • NVIDIA GPU with CUDA support required for: membrane segmentation, template matching and molecular dynamics simulations (oldest model tested: RTX 3090)

Note

macOS Users: Due to compatibility issues, some functions (edge length-based remeshing and certain parametrizations) have reduced performance compared to Linux systems, but yield the same output.

Installation#

We recommend creating a virtual environment for a clean and isolated setup.

Python’s built-in option, suitable for simpler setups.

python3 -m venv mosaic
source mosaic/bin/activate

Best for cross-platform compatibility and managing complex dependencies.

conda create --name mosaic -c conda-forge python=3.11
conda activate mosaic

After setting up your environment, Mosaic can be installed from PyPI

pip install "mosaic-gui[all]"
mosaic --version          # Smoke test to verify installation

Note

Installing pymeshlab from PyPi has proven troublesome on some Linux distributions. If the Mosaic installation fails with pymeshlab-related issues, you can either build pymeshlab from GitHub

python3 -m pip install git+https://github.com/cnr-isti-vclab/PyMeshLab.git@main

or follow their Tutorial for installing the lastest binaries for your system.

After installing pymeshlab you have to install Mosaic again.

Optional Dependencies#

Mosaic provides specialized functionality through the following optional components.

DTS Simulations#

If you intend to use Mosaic for dynamically triangulated surface (DTS) simulations, please install these additional tools

FreeDTS: Can be installed by following the instructions at weria-pezeshkian/FreeDTS. Alternatively, use our Python wrapper:

pip install pyfreedts

Trimem: Install from the repository at bio-phys/trimem:

git clone --recurse-submodules https://github.com/bio-phys/trimem.git
pip install trimem/

DTS Backmapping#

If you intend to use Mosaic for creating coarse-grained representations of meshes, install TS2CG (weria-pezeshkian/TS2CG-v2.0) for backmapping and Martinize2 (marrink-lab/vermouth-martinize) for creating coarse-grained representations of atomic structures

pip install TS2CG vermouth

We use Gromacs for equilibrating coarse-grained Martini models. The installation instructions are available here.

Instructions for Developers#

The latest development version of Mosaic can be installed from GitHub

pip install git+https://github.com/KosinskiLab/mosaic.git

If you want to modify the codebase

git clone https://github.com/KosinskiLab/mosaic.git
pip install -e mosaic

Getting Help#