Skip to content

Commit

Permalink
update mps text for apple
Browse files Browse the repository at this point in the history
  • Loading branch information
m-reuter committed Sep 22, 2022
1 parent b1d1821 commit 3bc21af
Showing 1 changed file with 19 additions and 9 deletions.
28 changes: 19 additions & 9 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ FastSurfer is a pipeline for the segmentation of human brain MRI data. It consis

The preferred way of installing and running FastSurfer is via Singularity or Docker containers. We provide pre-build images at Dockerhub for various application cases: i) for only the segmentation (both GPU and CPU), ii) for only the CPU-based recon-surf pipeline, and iii) for the full pipeline (GPU or CPU).

We also provide information on a native installs on some operating systems, but since dependencies may vary, this can produce results different from our testing environment and we may not be able to support you if things don't work.
We also provide information on a native install on some operating systems, but since dependencies may vary, this can produce results different from our testing environment and we may not be able to support you if things don't work. Our testing is performed on Ubuntu 20.04 via our provided Docker images.


# Installation
Expand Down Expand Up @@ -58,7 +58,7 @@ This is enough to run the FastSurfer neural network segmentation, if you want to

#### FastSurfer

Get a FastSurfer version from GitHub. Here you can decide if you want to install the current experimental "dev" version (which can be broken) or the "stable" branch (that has been tested thoroughly).
Get a FastSurfer version from GitHub. Here you can decide if you want to install the current experimental "dev" version (which can be broken) or the "stable" branch (that has been tested thoroughly).

#### Conda

Expand Down Expand Up @@ -91,24 +91,24 @@ To run the full pipeline, install also FreeSurfer v7.2 according to their [Instr

## MacOS

Currently only CPU based procesing is supported. GPU processing on Apple Silicon Chips is under developoment.
Processing on Mac CPUs (both Intel and Apple Silicon) is possible. On Apple Silicon you can even use the GPU (experimental) by passing ```--device mps```

Recommended: Mac with Apple Silicon M Chip and 16 GB RAM
You can also run on older Intel chips but it will be 2-4 times slower.

You can also run on older Intel CPUs but it will be 2-4 times slower.

### Native

On modern Macs with the Apple Silicon M1 or M2 ARM-based chips, we recommend a native CPU install as it runs much faster than Docker in our tests. On Intel chips you can also use Docker (see below).
On modern Macs with the Apple Silicon M1 or M2 ARM-based chips, we recommend a native install as it runs much faster than Docker in our tests. On Intel chips you can also use Docker (see below).

We exepct you to already have git and a recent bash (version > 4.0) installed, e.g. via the packet manager brew.
We expect you to already have git and a recent bash (version > 4.0) installed, e.g. via the packet manager brew.
This installs brew and then bash:

```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install bash
```

Make sure you use this bash and not the older one provided with MacOS!
Clone FastSurfer:dev, create a python environment, activate it, upgrade pip and install the requirements:

```
Expand All @@ -135,11 +135,21 @@ python3 FastSurferCNN/download_checkpoints.py --all

Once all dependencies are installed, run the FastSurfer segmentation only (!!) by calling ```bash ./run_fastsurfer.sh --seg_only ....``` with the appropriate command line flags, see the [README](README.md).

You can also try out running on the Apple Silicon GPU by:

```
export PYTORCH_ENABLE_MPS_FALLBACK=1
./run_fastsurfer.sh --seg_only --device mps ....
```

This will be at least twice as fast as CPU. The fallback environment variable is necessary as one function is not yet implemented for
the GPU and will fall back to CPU.

To run the full pipeline, install also FreeSurfer v7.2 according to their [Instructions](https://surfer.nmr.mgh.harvard.edu/fswiki/rel7downloads). There is a freesurfer email list, if you run into problems during this step.

### Docker (currently only Intel)

Docker can be used on Intel Macs as it should be similarly fast as a native install there.
Docker can be used on Intel Macs as it should be similarly fast as a native install there. It would allow you to run the full pipeline.

First install Docker Desktop for Mac from https://docs.docker.com/get-docker/
Start it and under Preferences -> Resources set Memory to 15 GB (or the largest you have, if you are below 15GB, it may fail). Pull one of our pre-compiled Docker containers. For that open a terminal window and copy this command:
Expand All @@ -153,5 +163,5 @@ and run is as the example in our [README](README.md).

## Windows

Nothing has been tested so far on Windows. We expect the CPU-based containers to work here. GPU passthrough will be explored in the future. If you want to make use of your GPU, you need to install a dual-boot with Ubuntu on your system.
Nothing has been tested so far on Windows. We expect the CPU-based containers to work here. GPU passthrough will be explored in the future. If you want to make use of your GPU, you need to install a dual-boot with Ubuntu (or another liunx) on your system.

0 comments on commit 3bc21af

Please sign in to comment.