phaserEM 0.3.0

phaser: The weapon of choice for ptychographic reconstructions

phaser is a fully-featured package for multislice electron ptychography. See our arXiv paper for more details.

Features

• ePIE, LSQ-MLs, and gradient descent algorithms
• numpy, cupy, and jax backends.
• Single and multislice ptychography
• Multiple incoherent probe modes
• Probe position correction
• Upsampled (sPIE) and segmented ptychography (work in progress)
• Adaptive propagator correction (contributed by M Zhu)

Documentation

Documentation on phaser can be found here: https://hexane360.github.io/phaser/dev/

Documentation is still very much a work in progress, so please feel free to open an issue or email me if you have any questions!

Installation

To install, first clone the repository from github. This can be done from GitHub Desktop, or from the git command line:

$ git clone https://github.com/hexane360/phaser
# enter phaser directory
$ cd phaser

We recommend using a conda environment or Python virtual environment to keep things clean, although this is not mandatory.

phaser supports multiple computational backends. The simplest (and slowest) is numpy. cupy can be used for CUDA-accelerated. jax supports CPU and GPU acceleration, and is the only backend which supports the gradient descent engine. If you're unsure what engines to use, we recommend installing the jax engine.

If you're using cupy or jax with a GPU, start by following the installation instructions for those packages. Jax can be installed with or without CUDA support, if you're using CUDA make sure you install the correct version. Currently, Jax does not support CUDA on Windows.

Before moving on to installing phaser, make sure those packages you've installed work:

$ python
>>> import jax
>>> jax.default_backend()
'gpu'  # should be 'gpu' on cuda, 'cpu' otherwise
>>> jax.numpy.array([1, 2, 3, 4]) + 1   # test a basic operation
Array([2, 3, 4, 5], dtype=int32)

>>> import cupy
>>> cupy.array([1, 2, 3, 4]) + 1
array([2, 3, 4, 5])

Then, install phaser using pip:

$ python -m pip install -e .

For the jax or cupy backend, or for the optional webserver, install with the corresponding options:

$ python -m pip install -e ".[jax,cupy12,web]" # for the 'jax', 'cupy12', and 'web' options

Depending on your command line, you may need to put double quotes around the options (as shown).

Here are the supported installation options:

• jax: For the jax backend (required for the gradient descent engine)
• cupy11: cupy for CUDA toolkit 11.x
• cupy12: cupy for CUDA toolkit 12.x
• web: For the web interface

For Optuna hyperoptimization, install it as well:

$ pip install optuna

Running

After installation, the phaser command should be available. Phaser can be run from the command line, or through a job server.

To run a single reconstruction on the command line, call phaser run <file>, where file is the path to a reconstruction plan file.

To run the webserver, call phaser serve. By default, the server serves on https://localhost:5050/, so navigate there in a web browser. The server interface can be used to start workers and schedule reconstruction jobs.

To run a worker, call phaser worker <url>, where url is the URL of a running job server.

Sample data & Examples

Sample data can be downloaded from the following dropbox link: https://www.dropbox.com/scl/fo/txm3k88ubrzvt541v23ir/AL-l_m6VnGlFxzHWZSSc0TA?rlkey=8qxtwnc8cwhpff6jpr5s40y6i&st=x9pbwke0&dl=0

Copy the sample_data directory into the root code folder.

$ curl --output sample_data.zip -L 'https://www.dropbox.com/scl/fo/txm3k88ubrzvt541v23ir/AL-l_m6VnGlFxzHWZSSc0TA?rlkey=8qxtwnc8cwhpff6jpr5s40y6i&st=x9pbwke0&dl=1'
$ unzip sample_data.zip -x / -d sample_data

Sample data includes simulated and experimental MoS2 data, simulated and experimental Si data, and experimental PrScO3 data. After the data is downloaded, any of the example reconstructions can be run as phaser run examples/mos2_grad.yaml (for example).

Alternatives

Other notable ptychography packages:

• fold_slice branch of PtychoShelves
• py4DSTEM
• PtyLab.m/py/jl
• PtyPy
• PtyRAD