Welcome to TEMUL Toolkit’s documentation!

The TEMUL Toolkit is a suit of functions and classes for analysis and visualisation of atomic resolution images. It is mostly built upon the data structure of HyperSpy and Atomap.

Interactive Examples

The easiest way to try the TEMUL Toolkit is via Binder: introductory Jupyter Notebook. To install the TEMUL Toolkit on your own computer, see the Installation instructions.

And there are more examples with Binder, just click the below button!

Click the button above to start some data analysis (it may take a few minutes to load). The “code_tutorials” folder contains walkthroughs of some of the documentation examples from this website. The “publication_examples” folder will allow you to analyse data from published scientific papers! Just navigate to whichever of these folders you want click on the “.ipynb” files.

Some published results using the TEMUL Toolkit

News

16/02/2021: Version 0.1.4 released

The polarisation, structure tools and fft mapping has now been refactored into the topotem module. The temul functionality remains the same i.e. import temul.api as tml.

16/02/2021: Version 0.1.3 released

First articles uses and citations for the TEMUL Toolkit! This version updated the Publication Examples folder with two newly published articles. The folder contains interactive and raw code on how to reproduce the data in the publications. Congrats to those involved!

• 13. Hadjimichael, Y. Li et al, Metal-ferroelectric supercrystals with periodically curved metallic layers, Nature Materials 2020
• 11. Moore et al Highly charged 180 degree head-to-head domain walls in lead titanate, Nature Communications Physics 2020

If you have a question or issue with using the publication examples, please make an issue on GitHub.

Code changes in this version:

• The atom_deviation_from_straight_line_fit function has been corrected and expanded. For a use case, see Finding Polarisation Vectors
• Corrected the plot_polarisation_vectors function’s vector quiver key.
• Created the “polar_colorwheel” plot_style for plot_polarisation_vectors by using a HSV to RGB 2D colorwheel and mapping the angles and magnitudes to these values. Used code from PixStem for colorwheel visualisation.
• Fixed norm and cmap scaling for the colorbar for the “contour”, “colorwheel” and “colormap” plot_styles. Now each of these plot_styles scale nicely, and colorbar ticks may be specified.
• Added invert_y_axis param for plot_polarisation_vectors function, useful for testing if angles are displaying correctly.
• plot_polarisation_vectors function now returns a Matplotlib Axes object, which can be used to further edit the layout/presentation of the plotted map.
• Added functions to correct for possible off-zone tilt in the atomic columns. Use with caution.

Documentation changes in this version:

• Added documentation for how to find the polarisation vectors.
• Added “code_tutorials” ipynb (interactive Jupyter Notebook) examples. See the GitHub repository for downloads.
• The workflows folder in “code_tutorials/workflows” also contains starting workflows for analysis of different materials. See the GitHub repository for downloads.
• Added “publication_examples” tutorial ipynb (interactive Jupyter Notebook) examples. See the GitHub repository for downloads.

03/11/2020: Version 0.1.2 released

This version contains minor changes from the 0.1.1 release. It removes pyCifRW as a dependency.

02/11/2020: Version 0.1.1 released

This version contains many changes to the TEMUL Toolkit.

• More parameters have been added to the polarisation module’s plot_polarisation_vectors function. Check out the walkthrough here for more info!
• Interactive double Gaussian filtering with the visualise_dg_filter function in the signal_processing module. Thanks to Michael Hennessy for the help!
• The calculate_atom_plane_curvature function has been added, creating the lattice_structure_tools module.
• Strain, rotation, and c/a mapping can now be done here.
• Masked FFT filtering to obtain iFFTs. See this guide to see some code!
• Example walk-throughs for many features of the TEMUL Toolkit are now on this website! Check out the menu on the left to get started!

Contents

• Installation
  • Installation Problems & Notes
• Getting started
• Analysis Workflows
• Finding Polarisation Vectors
  • For standard Polarised Structures (e.g., PTO)
  • For nonstandard Polarised Structures (e.g., Boracites)
  • For single Polarised Sublattices (e.g., LNO)
• Plotting Polarisation and Movement Vectors
  • Prepare and Plot the dummy dataset
  • Find the Vector Coordinates using Atomap
• Plot Lattice Structure Maps
  • Prepare and Plot the dummy dataset
  • Plot the Lattice Strain Map
  • Plot the Lattice Atom Rotation Map
  • Plot the c/a Ratio
• Calculation of Atom Plane Curvature
  • Import the Modules and Load the Data
  • Set up the Parameters
  • Calculate the Curvature of Atom Planes
• Analysis of PTO Domain Wall Junction
  • Import the Modules and Load the Data
  • Set up the Parameters
  • Create the Lattice Strain Map
  • Create the Lattice Rotation Map
  • Create the Lattice c/a Ratio Map
  • Map the Polarisation
• Masked FFT and iFFT
  • Load the Example Image
  • Choose the Mask Coordinates
  • Plot the Masked iFFT
  • Run FFT masking for Multiple Images
• Line Intensity Profile Comparisons
  • Load the Example Images
  • Compare two Line Profiles in one Image
  • Compare two Images with Line Profile
• Interactive Image Filtering
  • Load the Experimental Image
  • Interactively Filter the Experimental Image
  • Return the Filtered Image
• API documentation
  • Classes
  • Modules

Installation

The TEMUL Toolkit can be installed easily with PIP (those using Windows may need to download VS C++ Build Tools, see below).

$ pip install temul-toolkit

Then, it can be imported with the name “temul”. For example, to import most of the temul functionality use:

import temul.api as tml

• If installing on Windows, you will need Visual Studio C++ Build Tools. Download it here. After downloading, choose the “C++ Build Tools” Workload and click install.

• If you want to use the temul.io.write_cif_from_dataframe() function, you will need to install pyCifRW version 4.3. This requires Visual Studio.

• If you wish to use the temul.simulations or temul.model_refiner modules, you will need to install PyPrismatic. This requires Visual Studio and other dependencies. It is unfortunately not guaranteed to work. If you want to help develop the temul.model_refiner.Model_Refiner, please create an issue and/or a pull request on the TEMUL github.

• If you’re using any of the functions or classes that require element quantification:

  • navigate to the “temul/external” directory, copy the “atomap_devel_012” folder and paste that in your “site-packages” directory.
  • Then, when using atomap to create sublattices and quantify elements call atomap like this: import atomap_devel_012.api as am.
  • This development version is slowly being folded into the master branch here: https://gitlab.com/atomap/atomap/-/issues/93 and any help or tips on implementation are welcome!

Getting started

There are many aspects to the TEMUL Toolkit, such as polarisation analysis, element quantification, and automatic image simulation (through pyprismatic).

Checkout the tutorials in the table of contents above or on the left of the page. One can also view the extensive documentation, where each function is described and examples of their use given.

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

import temul.api as tml

Code Documentation

See the API documentation for examples and a full list of modules and functions.

Cite

To cite the latest TEMUL Toolkit version, use the following DOI:

For example: Eoghan O’Connell, Michael Hennessy, & Eoin Moynihan. (2021). PinkShnack/TEMUL: (Version 0.1.3). Zenodo. http://doi.org/10.5281/zenodo.4543963

If you wish to cite an older release of the TEMUL Toolkit, click on the above badge to find the relevant version.

Contribute

• Issue Tracker
• Source Code

Support

If you are having issues, please let us know in the issue tracker on GitHub.

License

The project is licensed under the GPL-3.0 License.

Indices and tables

• Index
• Module Index
• Search Page