Installation

The short version

$ virtualenv -p python3 ~/ptychography-venv/
$ source ~/ptychography-venv/bin/activate
(ptychography) $ python -m pip install ptychography40

# optional for GPU support
# See also https://docs.cupy.dev/en/stable/install.html
(ptychography) $ python -m pip install cupy

For details, please read on!

Linux and Mac OS X

Creating an isolated Python environment

To provide an isolated environment for ptychography and its dependencies, you can use virtualenvs or conda environments.

Using virtualenv

You can use virtualenv or venv if you have a system-wide Python 3.6 or newer installation. For Mac OS X, using conda is recommended.

To create a new virtualenv for ptychography, you can use the following command:

$ virtualenv -p python3.9 ~/ptychography-venv/

Replace ~/ptychography-venv/ with any path where you would like to create the venv. You can then activate the virtualenv with

$ source ~/ptychography-venv/bin/activate

Afterwards, your shell prompt should be prefixed with (ptychography) to indicate that the environment is active:

(ptychography) $

For more information about virtualenv, for example if you are using a shell without source, please refer to the virtualenv documentation. If you are often working with virtualenvs, using a convenience wrapper like virtualenvwrapper is recommended.

Using conda

If you are already using conda, or if you don’t have a system-wide Python 3.6, 3.7 or 3.8 installation, you can create a conda environment for ptychography.

This section assumes that you have installed conda and that your installation is working.

You can create a new conda environment to install ptychography with the following command:

$ conda create -n ptychography python=3.9

To install or later run ptychography, activate the environment with the following command:

$ conda activate ptychography

Afterwards, your shell prompt should be prefixed with (ptychography) to indicate that the environment is active:

(ptychography) $

Now the environment is ready to install ptychography.

For more information about conda, see their documentation about creating and managing environments.

Installing from PyPi

To install the latest release version, you can use pip. Activate the Python environment (conda or virtualenv) and install using:

(ptychography) $ python -m pip install ptychography40

This should install ptychography40 and its dependencies in the environment. Please continue by reading about the Algorithms.

Installing from a git clone

If you want to follow the latest development or contribute to ptychography, you should install ptychography from a git clone:

$ git clone https://github.com/Ptychography-4-0/ptychography

Activate the Python environment (conda or virtualenv) and change to the newly created directory with the clone of the ptychography repository. Now you can start the ptychography40 installation. Please note the dot at the end, which indicates the current directory!

(ptychography) $ python -m pip install -e .

This should download the dependencies and install ptychography in the environment. Please continue by reading about the Algorithms.

Updating

If you have installed from a git clone, you can easily update it to the current status. Open a command line in the base directory of the ptychography clone and update the source code with this command:

$ git pull

The installation with pip install -e has installed ptychography40 in “editable” mode. That means the changes pulled from git are active immediately. Only if the requirements for installed third-party packages have changed, you can re-run pip install -e . in order to install any missing packages.

CuPy

GPU support is based on CuPy. See https://docs.cupy.dev/en/stable/install.html#installing-cupy for installation of precompiled binary packages (recommended). python -m pip install cupy installs CuPy from source, which requires a build chain and can be time-consuming.

(libertem) $ python -m pip install cupy

Windows

The recommended method to install ptychography on Windows is based on Miniconda 64 bit. This installs a Python distribution.

For installing from a git clone you require a suitable git client, for example GitHub Desktop, TortoiseGit, or git for windows. Clone the repository https://github.com/Ptychography-4-0/ptychography in a folder of your choice.

From here on the installation and running of ptychography on Windows with the Anaconda Prompt is very similar to Using conda on Linux or Mac OS X.

Differences:

The command to activate a conda environment on Windows is

> conda activate ptychography

You might have to install pip into your local ptychography conda environment to make sure that pip install installs packages into your local environment and not into the global Anaconda base environment. This helps to avoid permission issues and interference between environments.

(ptychography) > conda install pip

Jupyter

To use the Python API from within a Jupyter notebook, you can install Jupyter into your ptychography virtual environment.

(ptychography) $ python -m pip install jupyter

You can then run a local notebook from within the ptychography environment, which should open a browser window with Jupyter that uses your ptychography environment.

(ptychography) $ jupyter notebook

JupyterHub

If you’d like to use the Python API from a ptychography virtual environment on a system that manages logins with JupyterHub, you can easily install a custom kernel definition for your ptychography environment.

First, you can launch a terminal on JupyterHub from the “New” drop-down menu in the file browser. Alternatively you can execute shell commands by prefixing them with “!” in a Python notebook.

In the terminal you can create and activate virtual environments and perform the ptychography40 installation as described above. Within the activated ptychography environment you additionally install ipykernel:

(ptychography) $ python -m pip install ipykernel

Now you can create a custom ipython kernel definition for your environment:

(ptychography) $ python -m ipykernel install --user --name ptychography --display-name "Python (ptychography)"

After reloading the file browser window, a new Notebook option “Python (ptychography)” should be available in the “New” drop-down menu. You can test it by creating a new notebook and running

In [1]: import ptychography40

Troubleshooting

If you are having trouble with the installation, please let us know by filing an issue.