How to use PtyRAD Apptainer image

For more information on Apptainer containers and their use, we provide a description of Apptainer, a crash course on how to use Apptainer, and of course there’s also the official Apptainer’s documentation.

Quick Start

PtyRAD comes with a starter kit which contains examples and templates. The template project can be created using:

apptainer run ptyrad.sif init

or simply

ptyrad.sif init

This will create a subfolder called ptyrad in the current working directory. Then, you can switch to the project folder using cd and use the following command to download the demo data to run the ptychographic reconstruction:

cd ptyrad
python ./scripts/download_demo_data.py

After the data is downloaded and unzipped, there are two methods to launch the reconstruction:

First, using the interactive Jupyter interface. Run the ptyrad/notebooks/run_ptyrad.ipynb in an editor which supports Jupyter notebook (e.g., Visual Studio Code), or using the following command:

apptainer exec ptyrad.sif jupyter notebook ./notebooks/run_ptyrad.ipynb # Or directly open it in VS Code

Second, using the command-line interface (non-interactive reconstruction)

apptainer run ptyrad.sif run "params/examples/tBL_WSe2.yaml"
# equivalent to
# ptyrad.sif run "params/examples/tBL_WSe2.yaml"

Detailed usage for the PtyRAD container

This section includes other ways to use the PtyRAD container. For more details about Apptainer commands, please look at this tutorial.

Run with GPU

PtyRAD supports running with GPU. To make the container aware of the GPU on the host machine, you need to run the container with some special flags. For Nvidia GPU, you need to run the container with the --nv flag:

apptainer run --nv ptyrad.sif <other-arguments>
# or
# apptainer exec --nv ptyrad.sif <command-and-arguments>

To run it with AMD GPUs that support ROCm, you need to add --rocm:

apptainer run --rocm ptyrad.sif <other-arguments>
# or
# apptainer exec --rocm ptyrad.sif <command-and-arguments>

Multi-GPU acceleration

You can also enable multi-GPU acceleration if more than one GPU is available. To do this, you need to launch the container with the accelerate command using apptainer exec:

apptainer exec ptyrad.sif accelerate launch --multi_gpu --num_processes=2 -m ptyrad run "${PARAMS_PATH}" --gpuid acc 2>&1

You may need to add --nv and/or --rocm depending on what types of GPUs you have.

To go further

The official PtyRAD website includes several tutorials on how to use PtyRAD for ptychographic reconstruction. To understand how PtyRAD works in depth, check out its documentation.