Metadata-Version: 2.4
Name: emicroml
Version: 0.0.3
Summary: A Python library for training machine learning models for applications in electron microscopy.
Author-email: Matthew Fitzpatrick <matthew.rc.fitzpatrick@gmail.com>
Project-URL: Homepage, https://mrfitzpa.github.io/emicroml
Project-URL: Repository, https://github.com/mrfitzpa/emicroml
Keywords: pytorch,electron microscopy,microscopy,diffraction,cbed,distortion measurement,distortion correction,machine learning,deep learning
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fakecbed>=0.3.6
Requires-Dist: empix>=0.0.6
Requires-Dist: kornia
Requires-Dist: h5pywrappers
Provides-Extra: tests
Requires-Dist: pytest-cov; extra == "tests"
Provides-Extra: examples
Requires-Dist: jupyter; extra == "examples"
Requires-Dist: ipympl; extra == "examples"
Requires-Dist: pyopencl[pocl]; extra == "examples"
Requires-Dist: prismatique; extra == "examples"
Provides-Extra: docs
Requires-Dist: sphinx<7; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"
Requires-Dist: docutils; extra == "docs"
Provides-Extra: all
Requires-Dist: emicroml[docs,examples,tests]; extra == "all"
Dynamic: license-file

# Electron Microscopy Machine Learning (EMicroML)

[![Test library](https://github.com/mrfitzpa/emicroml/actions/workflows/test_library.yml/badge.svg)](https://github.com/mrfitzpa/emicroml/actions/workflows/test_library.yml)
[![Code Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/mrfitzpa/14251fa16826487aa533af3cfe6887d4/raw/emicroml_coverage_badge.json)](https://github.com/mrfitzpa/emicroml/actions/workflows/measure_code_coverage.yml)
[![Documentation](https://img.shields.io/badge/docs-read-brightgreen)](https://mrfitzpa.github.io/emicroml)
[![PyPi Version](https://img.shields.io/pypi/v/emicroml.svg)](https://pypi.org/project/emicroml)
[![Conda-Forge Version](https://img.shields.io/conda/vn/conda-forge/emicroml.svg)](https://anaconda.org/conda-forge/emicroml)
[![License](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

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

Visit the `emicroml` [website](https://mrfitzpa.github.io/emicroml) 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](https://github.com/mrfitzpa/emicroml).



## Table of contents

- [Instructions for installing and uninstalling
  `emicroml`](#instructions-for-installing-and-uninstalling-emicroml)
  - [Installing `emicroml`](#installing-emicroml)
    - [Installing `emicroml` using `pip`](#installing-emicroml-using-pip)
    - [Installing `emicroml` using `conda`](#installing-emicroml-using-conda)
  - [Uninstalling `emicroml`](#uninstalling-emicroml)
- [Learning how to use `emicroml`](#learning-how-to-use-emicroml)
- [Reproducing data of preprints and published
  papers](#reproducing-data-of-preprints-and-published-papers)
  - [arXiv:2509.01075 (2025)](#arxiv250901075-2025)



## 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](https://pytorch.org/get-started/locally/) 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](https://github.com/mrfitzpa/emicroml), 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](https://mrfitzpa.github.io/emicroml/examples/prerequisites_for_execution_without_slurm.html#examples-prerequisites-for-execution-without-slurm-sec)
and [Prerequisites for running example scripts or Jupyter notebooks using a
SLURM workload
manager](https://mrfitzpa.github.io/emicroml/examples/prerequisites_for_execution_with_slurm.html#examples-prerequisites-for-execution-with-slurm-sec).



#### 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 from the root of the repository:

    pip uninstall emicroml

If `emicroml` was installed using `conda`, then to uninstall, run the following
command from the root of the repository:

    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](https://mrfitzpa.github.io/emicroml/examples.html) 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](https://mrfitzpa.github.io/emicroml/_autosummary/emicroml.html) to
understand what each line of code is doing.



## Reproducing data of preprints and published papers



### arXiv:2509.01075 (2025)

The majority of the data presented in
Ref. [Fitzpatrick1](https://mrfitzpa.github.io/emicroml/literature.html#fitzpatrick1)
can be reproduced by running all of the examples listed on the page [Examples of
distortion estimation of CBED
patterns](https://mrfitzpa.github.io/emicroml/examples/modelling/cbed/distortion/estimation.html#examples-modelling-cbed-distortion-estimation-sec).
