temul-toolkit 0.1.9

Functions for analysis of high resolution electron microscopy and spectroscopy data.

TEMUL

Functions for image and signal processing, based on the packages Scikit-image, Hyperspy, Atomap, PyPrismatic, ASE, periodictable etc. Written by members of the TEMUL group from the University of Limerick, Ireland (though we welco`me all help, hints and contributions!)

Documentation & Installation

pip install temul-toolkit

For full installation instructions and documentation, go to temul-toolkit.readthedocs.io.

Optional PyPrismatic Environment

temul.model_refiner and temul.simulations use pyprismatic for STEM simulation workflows. We do not install pyprismatic from PyPI by default in pyproject.toml, because the current PyPI project only exposes an old source distribution rather than maintained platform wheels.

For simulation work, create the conda environment in environment-pyprismatic.yml:

conda env create -f environment-pyprismatic.yml
conda activate temul-pyprismatic

This environment installs:

• pyprismatic
• prismatic_cli
• pytest
• flake8
• TEMUL in editable mode via pip install -e .

After activation, you can run the simulation-oriented tests with:

pytest tests/test_simulations.py tests/test_model_refiner_active.py

The GitHub Actions CI also has a dedicated conda job that builds this environment and runs the pyprismatic-related tests separately from the standard pip-based matrix.

To use the vast majority of the temul functionality, import it from the api module::

import temul.api as tml

Interactive Notebooks in the Browser

Jupyter Notebooks and MyBinder allow us to analyse data in the browser without needing any downloads using the below "launch binder" button.

If the button does not work, try this link instead. You also share this link with others for quick access.

• To run through some code documentation tutorials, go to the "code_tutorials" folder after clicking the above button.

• To analyse data published in the listed scientific papers, go to the "publication_examples" folder after clicking the above button.

Example Publications that have used the TEMUL Toolkit

Publication Details	Folder Location in TEMUL
M. Hadjimichael, Y. Li et al, Metal-ferroelectric supercrystals with periodically curved metallic layers, Nature Materials 2021	publication_examples/PTO_supercrystal_hadjimichael
K. Moore et al Highly charged 180 degree head-to-head domain walls in lead titanate, Nature Communications Physics 2020	publication_examples/PTO_Junction_moore
K. Moore et al Charged Domain Wall and Polar Vortex Topologies in a Room-Temperature Magnetoelectric Multiferroic Thin Film, ACS Appl. Mater. Interfaces 2022, 14, 4	Coming soon
E.N. O'Connell et al TopoTEM: A Python Package for Quantifying and Visualizing Scanning Transmission Electron Microscopy Data of Polar Topologies, Microsc Microanal. 2022 doi:10.1017/S1431927622000435 Arxiv Version	See the Docs

Cite TEMUL Toolkit/TopoTEM

To cite the latest TEMUL toolkit, use the following DOI:

• 

To cite all TEMUL Toolkit versions, use this DOI:

• 

You can also cite the TopoTEM publication if you only worked with polarisation-type analysis.

• See the TopopTEM publication here.

Information for developers

Linting (PEP8)

We use flake8 to enforce coding style:

pip install -r tests/requirements.txt
flake8 temul
flake8 tests
flake8 docs

Testing

Tests are carried out with pytest:

pip install -r tests/requirements.txt
pytest tests

Documentation (docs)

To build the docs, do the following::

pip install -r docs/requirements.txt
sphinx-build docs _build  # open "index.html" in the "_build" directory

Make sure that the docs build locally and online (if you have the rights to check that).

Incrementing version

temul gets its version from the latest git tag. If you think that a new version should be published, create a tag on the master branch (if you have the necessary permissions to do so):

git tag -a 'x.y.z' -m 'new tag'
git push --tags <remote>

GitHub Actions will then automatically build source package and wheels and publish them on PyPI.