Microvolution

Microvolution is a high-performance 3D deconvolution application, designed to deconvolve images from widefield, confocal, two photon, light sheet, and HCA microscopes, as well as perform blind deconvolution to ameliorate noise in other data types such as deep-tissue images.

More information about Microvolution is available on the Microvolution webpage.

System Requirements

Before running the NGC Microvolution container, please ensure that your system meets the following requirements.

• Pascal (sm60) or Volta (sm70) NVIDIA GPU(s)
• CUDA >= 9.0
• One of the following container runtimes
  • nvidia-docker >= 2.0.3
  • Singularity >= v2.5.0

A Microvolution executable optimized for your system hardware will be chosen automatically at runtime.

Running Microvolution

Command invocation

A typical Microvolution invocation takes the form:

$ MicrovolutionDecon -o  --timer  --iterations 10 --lambda 525 --dr 104 --dz 300 --background 120 --NA 1.1 --RI 1.33 --ns 1.33 --lsna 0.42

Where

• MicrovolutionDecon: Microvolution deconvolution executable
• -o : specify the directory for image output
• --timer: output time taken to complete each deconvolution
• ``: specify input file(s) for deconvolution

A full list of MicrovolutionDecon options is available in the MicrovoltionDecon --help output:

Deconvolution by Microvolution
Copyright Microvolution, LLC

Usage: MicrovolutionDecon  image1.tif image2.tif ...

General options:
  -h [ --help ]                  Produce this help message
  --version                      Print current version and exit
  --list-devices                 List available devices and exit
  -L [ --license ] arg           Path to license
  -D [ --devices ] arg (=-1)     Number of devices. Default is to use all
  -o [ --outDir ] arg            Where to save output
  --sync                         Use synchronous file writing

Deconvolution options:
  -i [ --iterations ] arg (=10)  Number of iterations to run.
  --xpad arg (=0)                Padding in the x dimension
  --ypad arg (=0)                Padding in the y dimension
  --zpad arg (=0)                Padding in the z dimension
  --xtiles arg (=0)              Number of tiles in the x dimension
  --ytiles arg (=0)              Number of tiles in the y dimension
  --ztiles arg (=0)              Number of tiles in the z dimension

PSF generation options:
  -l [ --lambda ] arg            Emission wavelength
  -r [ --dr ] arg                Lateral spacing (nm/pixel)
  -z [ --dz ] arg                Axial spacing (nm/plane)
  -N [ --NA ] arg                Objective numerical aperture
  -R [ --RI ] arg                Immersion medium refractive index
  --ns arg                       Sample refractive index. If this parameter is
                                 specified, then the 'Vectorial' PSF model is
                                 used. Otherwise, 'Born-Wolf' is used.
  -p [ --pinhole ] arg           Backprojected pinhole radius (nm). Changes
                                 mode to 'Confocal' or 'Spinning Disk'. If left
                                 unspecified, a 'Widefield' image is assumed.
  --pinholeSpacing arg           Backprojected pinhole distance (nm). Changes
                                 mode to 'Spinning Disk' if specified. Must
                                 also set pinhole.
  --lsna arg                     Light sheet NA. Changes modes to 'Light Sheet'
                                 if specified.

Advanced options:
  -B [ --blind ]                 Blind deconvolution
  --deskew arg                   Deskew angle for stage scanned light sheet
  --reg arg (=0)                 Regularization type (0 off, 1 TV, 2 entropy)
  -b [ --background ] arg (=0)   Background correction
  -g [ --gauss ]                 Gaussian filter on GPU before deconvolution

Examples

Microvolution requires a license file to execute from within the NGC Microvolution container. To acquire a Microvolution license, visit the Microvolution webpage.

The following commands are examples which bind-mount a license file, microvolution-license.lic, an input file, lattice.tif, and output directory out/ from the present working directory of the host. They also use the NGC Microvolution entrypoint script to set up and call MicrovolutionDecon:

Docker:

$ nvidia-docker run -e CUDA_VISIBLE_DEVICES=0,1 -v $(pwd)/microvolution-license.lic:/opt/microvolution/microvolution.lic:ro -v $(pwd):/host_pwd/ --rm nvcr.io/hpc/microvolution:2018.12 -o /host_pwd/out --timer /host_pwd/lattice.tif --iterations 10 --lambda 525 --dr 104 --dz 300 --background 120 --NA 1.1 --RI 1.33 --ns 1.33 --lsna 0.42

Singularity:

$ singularity build microvolution_2018.12.simg docker://nvcr.io/hpc/microvolution:2018.12
$ export CUDA_VISIBLE_DEVICES=0,1
$ singularity exec --nv -B $(pwd)/microvolution-floating.lic:/opt/microvolution/microvolution.lic -B $(pwd):/host_pwd microvolution_2018.12.simg /opt/microvolution/mv-entrypoint.sh -o /host_pwd/out --timer /host_pwd/lattice.tif --iterations 10 --lambda 525 --dr 104 --dz 300 --background 120 --NA 1.1 --RI 1.33 --ns 1.33 --lsna 0.42

More detailed instructions on using the NGC Microvolution container in Docker and Singularity can be found below.

Running with Singularity

Pull the image

Save the NGC Microvolution container as a local Singularity image file:

$ singularity build microvolution_2018.12.simg docker://nvcr.io/hpc/microvolution:2018.12

This command saves the container in the current directory as microvolution_2018.12.simg

Note: Singularity/2.x

In order to pull NGC images with singularity version 2.x and earlier, NGC container registry authentication credentials are required.

To set your NGC container registry authentication credentials:

$ export SINGULARITY_DOCKER_USERNAME='$oauthtoken'
$ export SINGULARITY_DOCKER_PASSWORD=

More information describing how to obtain and use your NVIDIA NGC Cloud Services API key can be found here.

Note: Singularity 3.1.x - 3.2.x

There is currently a bug in Singularity 3.1.x and 3.2.x causing the LD_LIBRARY_PATH to be incorrectly set within the container environment. As a workaround The LD_LIBRARY_PATH must be unset before invoking Singularity:

$ LD_LIBRARY_PATH="" singularity exec ...

Once the local Singularity image has been pulled, the following modes of running are supported:

• local workstation
• Slurm srun
• cluster mpirun
• container mpirun

Singularity Aliases

To simplify the examples below, define the following command alias. This may be set as an environment variable in a shell or batch script.

Singularity alias

SINGULARITY will be used to launch processes within the NGC Microvolution container using the Singularity runtime:

$ export SINGULARITY="$(which singularity) exec --nv -B :/opt/microvolution/microvolution.lic -B $(pwd):/host_pwd microvolution_2018.12.simg"

Where:

• exec: specifies mode of execution
• --nv: exposes the host GPUs to the container
• ``: path of Microvolution license to bind mount into the container
• -B $(pwd):/host_pwd: bind mounts the current working directory in the container at /host_pwd
• microvolution_2018.12.simg: path of the saved Singularity image file

Limiting GPU usage

By default, the NGC Microvolution container uses all Nvidia GPUs of a multi-GPU system. To limit GPU usage, use the following environment variable to specify which GPUs are usable by Microvolution:

export CUDA_VISIBLE_DEVICES=

Where:

• ``: specifies a comma-separated list of GPU IDs to use (for example, three GPUs: 0,1,2)

GPU IDs can be displayed by the nvidia-smi utility, in the GPU column.

Local workstation with Singularity

This mode of running is suitable for interactive execution from a local workstation containing one or more GPUs. There are no requirements other than those stated in the System Requirements section.

Command line

To launch Microvolution via Singularity, use:

$ ${SINGULARITY} /opt/microvolution/mv-entrypoint.sh -o  --timer  --iterations 10 --lambda 525 --dr 104 --dz 300 --background 120 --NA 1.1 --RI 1.33 --ns 1.33 --lsna 0.42

Where:

• SINGULARITY: singularity alias defined above
• /opt/microvolution/mv-entrypoint.sh: the Microvolution entrypoint start script
• -o : specify the directory for output files
• ``: specify input file(s) for deconvolution

The remainder of the arguments are described in Command Invocation above, and are populated here with example values.

Interactive shell

To invoke an interactive shell, use the SINGULARITY alias to run /bin/bash within the container:

$ ${SINGULARITY} /bin/bash

To run Microvolution while using the interactive shell:

$ /opt/microvolution/mv-entrypoint.sh -o  --timer  --iterations 10 --lambda 525 --dr 104 --dz 300 --background 120 --NA 1.1 --RI 1.33 --ns 1.33 --lsna 0.42

Where:

• /opt/microvolution/mv-entrypoint.sh: the Microvolution entrypoint start script
• -o : specify the directory for output files
• ``: specify input file(s) for deconvolution

Running with nvidia-docker

NGC supports the Docker runtime through the nvidia-docker plugin.

nvidia-docker Aliases

To simplify the examples below, define the following command alias. This may be set as an environment variable in a shell or batch script.

nvidia-docker alias

DOCKER will be used to launch processes within the NGC Microvolution container using the nvidia-docker runtime:

$ export DOCKER="nvidia-docker run -v :/opt/microvolution/microvolution.lic:ro -v $(pwd):/host_pwd --rm nvcr.io/hpc/microvolution:2018.12"

Where:

• DOCKER: alias used to store the base Docker command
• run: specifies the mode of execution
• ``: path of Microvolution license to bind mount into the container
• -v $(pwd):/host_pwd: bind mounts the current working directory in the container at /host_pwd
• --rm: makes the container instance ephemeral (does not save on exit)
• nvcr.io/hpc/microvolution:2018.12: URI of the latest NGC Microvolution container

Limiting GPU usage

By default, the NGC Microvolution container uses all Nvidia GPUs of a multi-GPU system. To limit GPU usage, add the following environment variable argument to the docker run command above:

-e CUDA_VISIBLE_DEVICES=

Where:

• ``: specifies a comma-separated list of GPU IDs to use (for example, three GPUs: 0,1,2)

GPU IDs can be displayed by the nvidia-smi utility, in the GPU column.

Local workstation with nvidia-docker

This mode of running is suitable for interactive execution from a local workstation containing one or more GPUs. There are no requirements other than those stated in the System Requirements section.

Command line execution with nvidia-docker

To launch Microvolution via nvidia-docker, use:

$ ${DOCKER} -o  --timer  --iterations 10 --lambda 525 --dr 104 --dz 300 --background 120 --NA 1.1 --RI 1.33 --ns 1.33 --lsna 0.42

Where:

• -o : specify the directory for output files
• ``: specify input file(s) for deconvolution

The remainder of the arguments are described in Command Invocation above, and are populated here with example values.

Interactive shell with nvidia-docker

To start an interactive shell within the container environment, add an argument to set the container entrypoint to bash:

$ nvidia-docker run --entrypoint=bash -v :/opt/microvolution/microvolution.lic:ro -v $(pwd):/host_pwd --rm -it nvcr.io/hpc/microvolution:2018.12

Where:

• DOCKER: alias used to store the base Docker command
• run: specifies the mode of execution
• --entrypoint=bash: changes the container entrypoint to bash
• ``: path of Microvolution license to bind mount into the container
• -v $(pwd):/host_pwd: bind mounts the current working directory in the container at /host_pwd
• --rm: makes the container instance ephemeral (does not save on exit)
• -it: starts an interactive shell session within the container (interactive tty)
• nvcr.io/hpc/microvolution:2018.12: URI of the latest NGC Microvolution container

To run Microvolution while using the interactive shell:

$ /opt/microvolution/mv-entrypoint.sh -o  --timer  --iterations 10 --lambda 525 --dr 104 --dz 300 --background 120 --NA 1.1 --RI 1.33 --ns 1.33 --lsna 0.42

Where:

• -o : specify the directory for output files
• ``: specify input file(s) for deconvolution

The remainder of the arguments are described in Command Invocation above, and are populated here with example values.