Electron Microscopy Machine Learning (EMicroML)

emicroml is a Python library for training machine learning models for applications in electron microscopy.

Visit the emicroml website for a web version of the installation instructions, the reference guide, and the examples archive.

The source code can be found in the emicroml GitHub repository.

Table of contents

• Instructions for installing and uninstalling emicroml
  • Installing emicroml
    • Installing emicroml using pip
    • Installing emicroml using conda
  • Uninstalling emicroml
• Learning how to use emicroml
• Reproducing data of preprints and published papers
  • Ultramicroscopy 283 (2026), 114347
• How to cite emicroml
  • For estimation of optical distortion in CBED patterns

Instructions for installing and uninstalling emicroml

Installing emicroml

For all installation scenarios, first open up the appropriate command line interface. On Unix-based systems, you could open e.g. a terminal. On Windows systems you could open e.g. an Anaconda Prompt as an administrator.

Before installing emicroml, it is recommended that users install PyTorch in the same environment that they intend to install emicroml according to the instructions given here for their preferred PyTorch installation option.

Installing emicroml using pip

Before installing emicroml, make sure that you have activated the (virtual) environment in which you intend to install said package. After which, simply run the following command:

pip install emicroml

The above command will install the latest stable version of emicroml.

To install the latest development version from the main branch of the emicroml GitHub repository, one must first clone the repository by running the following command:

git clone https://github.com/mrfitzpa/emicroml.git

Next, change into the root of the cloned repository, and then run the following command:

pip install .

Note that you must include the period as well. The above command executes a standard installation of emicroml.

Optionally, for additional features in emicroml, one can install additional dependencies upon installing emicroml. To install a subset of additional dependencies (along with the standard installation), run the following command from the root of the repository:

pip install .[<selector>]

where <selector> can be one of the following:

• tests: to install the dependencies necessary for running unit tests;
• examples: to install the dependencies necessary for executing files stored in <root>/examples, where <root> is the root of the repository;
• docs: to install the dependencies necessary for documentation generation;
• all: to install all of the above optional dependencies.

Alternatively, one can run:

pip install emicroml[<selector>]

elsewhere in order to install the latest stable version of emicroml, along with the subset of additional dependencies specified by <selector>. Note that the Python library pyprismatic>=2.0 must be installed prior to executing either of the last two commands with <selector> set to examples. The easiest way to install this additional dependency is within a conda virtual environment, using the following command::

conda install -y pyprismatic=*=gpu* -c conda-forge

if CUDA version >= 11 is available on your machine, otherwise users should run instead the following command::

conda install -y pyprismatic=*=cpu* -c conda-forge

For further discussions on running examples, see the pages Prerequisites for running example scripts or Jupyter notebooks without using a SLURM workload manager and Prerequisites for running example scripts or Jupyter notebooks using a SLURM workload manager.

Installing emicroml using conda

Before proceeding, make sure that you have activated the (virtual) conda environment in which you intend to install said package. For Windows systems, users must install PyTorch separately prior to following the remaining instructions below.

To install emicroml using the conda package manager, run the following command:

conda install -c conda-forge emicroml

The above command will install the latest stable version of emicroml.

Uninstalling emicroml

If emicroml was installed using pip, then to uninstall, run the following command:

pip uninstall emicroml

If emicroml was installed using conda, then to uninstall, run the following command:

conda remove emicroml

Learning how to use emicroml

For those new to the emicroml library, it is recommended that they take a look at the Examples page, which contain code examples that show how one can use the emicroml library. While going through the examples, readers can consult the emicroml reference guide to understand what each line of code is doing.

Reproducing data of preprints and published papers

Ultramicroscopy 283 (2026), 114347

The majority of the data presented in Ref. Fitzpatrick1 can be reproduced by running all of the examples listed on the page Examples of distortion estimation of CBED patterns.

How to cite emicroml

For estimation of optical distortion in CBED patterns

If you are using machine learning models constructed via our emicroml library to estimate optical distortion in convergent beam electron diffraction (CBED) patterns, please cite Ref. Fitzpatrick1.