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)

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

The first launch of Mosaic may take noticeably longer than subsequent starts. During this initial run, Qt and VTK compile and cache platform-specific resources, that are then reused on future launches.

Note

Mosaic versions prior to 1.2.1 required pymeshlab, which could be troublesome on some Linux distributions. This dependency has been replaced by gpytoolbox and open3d. If you are using an older version, refer to the pymeshlab installation guide.

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
dts -h                # smoke test

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

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

On MacOS, libomp needs to be installed separately to install trimem

brew install libomp

export LIBOMP_PATH=/opt/homebrew/opt/libomp
export CMAKE_POLICY_VERSION_MINIMUM=3.5
export CXXFLAGS="-Xpreprocessor -fopenmp -I$LIBOMP_PATH/include"
export CFLAGS="-Xpreprocessor -fopenmp -I$LIBOMP_PATH/include"
export LDFLAGS="-L$LIBOMP_PATH/lib -Wl,-rpath,$LIBOMP_PATH/lib -lomp"
export CMAKE_ARGS="-DCMAKE_C_COMPILER=$(which clang) -DCMAKE_CXX_COMPILER=$(which clang++)"
pip install trimem/

You can smoke test your installation using

mc_app run --help

which should output similar to the message shown below

usage: mc_app run [-h] --conf CONF [--restart [RESTART]]
Run a simulation parametrized by a configuration file.

options:
  -h, --help           show this help message and exit
  --conf CONF          configuration file name (see `mc_app config --help`).
  --restart [RESTART]  restart index.

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#