Release Notes#

Version 2.4.0 Stable#

11-18-2026#

New#

  • pyEMAPS reads experimental diffraction patterns from microscope and detector files itself, for 4D-STEM indexing and imaging. StackImage.from_file creates an image from a file, and pyemaps.read_image returns the patterns as numpy arrays, with the scan shape, calibration and the file’s metadata. Reading needs no license. The formats:

    • TIFF (.tif, .tiff), including BigTIFF and ImageJ stacks over 4 GB.

    • Gatan DigitalMicrograph (.dm3, .dm4), with the scan shape, calibration, high voltage and camera length DigitalMicrograph recorded.

    • EMD (.emd): Thermo Fisher Velox, and Berkeley EMD including py4DSTEM datacubes. These need the h5py package: pip install "pyemaps[emd]". On Python 3.15, h5py has no Windows release yet.

    • MRC (.mrc, .mrcs, .st), Quantum Detectors Merlin (.mib), PNG, BMP and JPEG pictures, and NumPy .npy arrays.

    binning and scan_roi read large patterns and scans within the 4D-STEM limits, and convertImage with nformat=E_FILE saves a converted copy in pyEMAPS’ .im3 format. See 4D-STEM pattern indexing. We’d like to hear how these work with your files: contact us at support@emlabsoftware.com.

  • CIF files in the CIF 2.0 format can be loaded with from_cif(), as well as CIF 1.1.

Changes#

  • Anisotropic displacement parameters in a CIF file go to the atoms they’re listed for, by the atom labels in _atom_site_aniso_label. Before, they were assigned row by row, so when the anisotropic table listed only some atoms, or listed them in a different order (as most published structures with hydrogen atoms do), atoms got other atoms’ values. Atoms the table doesn’t list keep their isotropic value. Results change for such CIF files.

  • CIF files that give _atom_site_Uiso_or_equiv instead of _atom_site_U_iso_or_equiv, or a single atom written without a loop_, now load. Before, they failed with an error.

Improvements#

  • pyEMAPS reads CIF files with its own reader, following the IUCr CIF 1.1 and 2.0 standards, instead of the bundled PyCifRW package. Other CIF files give the same results as before, and the pyEMAPS package is smaller.

  • Requires emaps >= 2.1.0.

Version 2.3.0 Stable#

11-16-2026#

Changes#

  • Bloch and LACBED images are centred: the pattern’s centre is at the image’s centre. Before, every image from generateBloch(), in both modes, and from getBlochImages() was 2 rows too high, so images saved with earlier versions are offset by 2 rows from new ones. This comes from emaps 2.1.0.

  • emaps 2.1.0 states its own license terms, in the license.txt file installed with it. emaps is free to use with pyEMAPS, including versions of pyEMAPS you have modified, and may be redistributed unmodified together with pyEMAPS. Its COPYING file lists the third-party software it includes, with their notices and license terms.

Improvements#

  • From emaps 2.1.0:

    • The license checks of the 4D-STEM features use LicenseSpring C++ SDK 7.51.3, which comes with OpenSSL 3.5.7 and curl 8.21.0.

    • Third-party numerical routines in the 4D-STEM indexing are replaced by EMLab’s own implementations. Results are unchanged.

  • Requires emaps >= 2.1.0.

Version 2.2.1 Stable#

11-16-2026#

Changes#

  • pyEMAPS stays under the GNU General Public License v3.0 or later, now with a linking exception that permits combining it with emaps, the separately licensed simulation engine it runs on. The exception is in the license-exception.txt file, installed with pyEMAPS, and on the Licenses for pyEMAPS page. Each source file’s license notice is now a short SPDX header that points to it.

  • The commercial license covers the 4D-STEM features of emaps. pyEMAPS’ own code is all under the GPL with the exception. How to buy and activate a license is unchanged.

Improvements#

  • showDif() and showBloch() with layout='table' leave room for each pattern’s caption, which no longer runs into the panel below it.

  • showBloch()’s “No intensity detected” message for a dark image fits its panel. Before, only fragments of it showed in a LACBED table.

Version 2.2.0 Stable#

11-14-2026#

New#

  • Jupyter notebooks, one for each sample, that walk through pyEMAPS step by step, with the physics behind each step: kinematic and dynamic diffraction, large-angle CBED, the scattering matrix, structure factors, stereographic projections, supercells, powder diffraction, and 4D-STEM indexing and virtual detectors. pyemaps -cp notebooks copies them into a pyemaps_notebooks folder. On GitHub, the notebooks folder shows them with their results.

  • In a Jupyter notebook, pyEMAPS draws its plots in the notebook, instead of in a separate window.

  • pyemaps -cp takes samples or notebooks to copy only the sample scripts or only the notebooks; with neither, it copies both. It no longer overwrites files already there.

  • Printing an EMControl or SIMControl, or showing one at the Python prompt, gives an aligned list of the controls, with the default value next to each control that was changed.

Changes#

  • Powder profiles from generatePowder() put each peak at its scattering angle 2θ. Before, every peak was at θ, half its angle. This comes from emaps 2.0.1, so powder results change.

  • A crystal simulated after another crystal now gives its own results. Before, a Crystal used after another one could reuse the other crystal’s data, and deleting it could crash the current one.

  • The built-in Germanium crystal declared the wrong origin for its space group, giving 16 atoms per cell instead of 8. Results for Germanium change.

  • The sample scripts are rewritten for readability, and their functions have new names. Code that imports them from pyemaps.samples needs the new names.

  • printCSF() prints the right units: volts for electron structure factors, and 1/Angstrom^2 for the other electron types; the high voltage is in kV.

Improvements#

  • From emaps 2.0.1:

    • loadImage() reads 16-bit 4D-STEM images correctly. Before, it returned wrong values for them, and loading a single pattern could crash Python.

    • A one-character mask file name in generateMaskedImage() no longer crashes Python.

  • showDif() with layout='table' frames each pattern, and hides indices cut off at its edge.

  • Fixed samples: si_constructor.py always builds the supercell, dm_diff.py saves the images it reports, and si_scm.py always closes its session.

  • generatePowder() documents gamma as the peaks’ full width at half maximum.

  • The README, Get Started, User Guide and Help pages are corrected throughout, checked against the code.

  • pyEMAPS files on PyPI now come with provenance attestations, which link each file to the GitHub workflow and commit that built it.

  • Requires emaps >= 2.0.1.

Version 2.1.0 Stable#

11-12-2026#

Changes#

  • generateBloch() and beginBloch() called without em_controls now start from the default controls every time. Before, every such call shared one controls object, so the crystal x-axis chosen for the first call was reused for every later call in the session, for any crystal. Results for those later calls change: each crystal now gets the x-axis chosen for it. generateDPDB() called without emc is fixed the same way.

  • Non-default gctl and zctl simulation controls now reach the simulation. Before, they were silently ignored. A value too small for the pattern, such as gctl=1, now makes generateDP() fail.

  • convertImage() now converts numpy images: pass the 2-D array as imgfn with nformat=E_NPY. It returns the converted file’s path, and raises XDPImageError when the conversion fails instead of only printing a message.

  • plot2Powder() has new titles and ylabels parameters. By default the plots have no titles; before, they were always titled “Silicon” and “Diamond”.

  • showDif() raises DPListError when it isn’t given a DPList, and plots nothing for an empty one.

  • Comparing a pyEMAPS point, index, disk, diffraction pattern or controls object with == to an object of another type returns False instead of raising an error.

  • An invalid camera length in EMControl raises EMCError, like the other controls, instead of ValueError.

Improvements#

  • Fixed Crystal, Atom and Cell:

    • A crystal created without data can be checked with loaded(), and no longer prints an error when it’s freed.

    • Atom.atype returns the thermal factor type instead of the element symbol, so identical atoms and crystals now compare equal.

    • An atom created without a position has 5 values (10 for anisotropic atoms), not 6.

    • Creating a crystal from a dictionary no longer deletes symb from the dictionary’s atoms, so the same data can be used again.

    • Cell errors name the right cell constant.

    • Cell.session_controls is None until set, instead of raising an error.

    • from_xtl() and from_cif() report a file that can’t be read as CrystalClassError.

  • Fixed the microscope and simulation controls:

    • Each EMControl created without simulation controls gets its own SIMControl. Before, they all shared one, so changing one changed them all.

    • EMControl.from_dict uses the defaults for missing keys, and the simulation controls given in the dictionary.

    • Plot captions show a non-default diffracted beam size and bmin.

    • Unknown keys passed to a SIMControl are ignored, as its message says.

    • Error messages name the right control.

  • Fixed kinematic and dynamic diffraction results:

    • Printing a diffraction pattern shows the number of diffracted beams, not the number of Kikuchi lines.

    • Kikuchi and HOLZ lines sort by their end points and intensity.

    • Points, lines and disks that compare equal also hash equally, so sets and dictionaries treat them as the same.

    • (emc, image) in bloch_images works on BImgList.

  • Fixed 4D-STEM (stem4d) images:

    • viewExpImage() displays images that aren’t square correctly, and its stack check no longer accepts one stack past the last.

    • generateMaskedImage() rejects a missing or blank mask file name, and prints the error when the image can’t be loaded.

    • showMatchedDBDP() returns -1 on failure instead of ending the Python session.

    • Invalid image dimensions report the valid ranges.

    • The database pattern shown by showMatchedDBDP() is now normalized as intended.

    • A script no longer prints an Exception ignored in: StackImage.__del__ error when it ends while a StackImage is still alive.

  • Fixed file and structure utilities:

    • compose_ofn() accepts an empty file name.

    • from_cif() reports a missing CIF file, and a space group setting or number out of range, with the right error.

    • Each ACoord created without coordinates gets its own coordinate list.

  • Requires emaps >= 2.0.0.

Version 2.0.0 Stable#

11-10-2026#

New#

  • pyEMAPS now runs on Python 3.12, 3.13, 3.14 and 3.15 on Windows, with NumPy 2. The emaps backend ships one wheel for each of these Python versions.

  • pyEMAPS is now a pure-Python package: a single wheel installs on every supported Python version, with no compiler needed.

Changes#

  • Python 3.7 is no longer supported. On Python 3.7, pip install pyemaps keeps installing pyEMAPS 1.1.x with emaps 1.1.x.

  • Requires numpy >= 2.0 and matplotlib >= 3.8.4.

  • The emaps backend no longer exposes the undocumented emaps.diffract.emaps_sims.metric attribute (the crystal metric tensors). Nothing in pyEMAPS used it, and simulation results are unchanged.

  • emaps no longer depends on the msvc-runtime package. The C++ runtime that the 4D-STEM (stem4d) module needs now ships inside emaps.

Improvements#

  • Fixed plot windows on matplotlib 3.6 and newer, which removed the window-title call pyEMAPS used.

  • Simulation results are identical to pyEMAPS 1.1.8 on every supported Python version.

  • Plot windows shown with bClose=True now stay up 3 seconds after the last image before closing, instead of about 1 second.

  • New 4D-STEM (stem4d) checks in the test suite cover image loading, diffraction pattern database generation and indexing.

  • Requires emaps >= 2.0.0.

Version 1.1.8 Stable#

11-09-2026#

Improvements#

  • Fixed a threading bug in dynamic diffraction (Bloch) and LACBED simulations with more than 512 beams, where parallel threads shared internal work arrays. Results in this regime could be wrong and could differ from one run to the next, without any error.

  • Fixed loading 4D-STEM (stem4d) images from numpy arrays. StackImage with nformat=E_NPY failed with TypeError whenever its data was set, and now works. Any 2-D boolean, integer or floating-point array, including float64 and int32, is accepted and converted to float32. Invalid input raises XDPImageError with a clear message. In the emaps backend, images with more rows than columns, or transposed arrays, could crash Python, and uint8/uint16 arrays and wide or non-C-ordered arrays loaded wrong pixel values without any error.

  • Fixed a memory leak when loading multiple images into the 4D-STEM (stem4d) feature in one session, and possible memory corruption or wrong fit maps when switching diffraction pattern databases without reloading the image.

  • The Bloch stress test now compares its result exactly against a stored baseline (-bc), instead of relying only on a visual check.

  • Requires emaps >= 1.1.2.

Version 1.1.7 Stable#

09-21-2026#

Improvements#

  • Tuned the dynamic diffraction (Bloch) stress test with a wider thickness range and longer camera length, and updated it to save its rendered image and leave the plot window open for visual inspection.

  • Regenerated the stored Bloch feature test baselines against emaps 1.1.0.

  • Reduced memory usage when generating large diffraction pattern databases (dpgen) by streaming database records to disk as they are computed instead of accumulating them all in memory first.

  • Fixed memory leaks and improved out-of-memory robustness in the peak-search code used by the 4D-STEM (stem4d) feature.

  • Requires emaps >= 1.1.1.

Version 1.1.6 Stable#

09-18-2026#

Improvements#

  • Fixed a bug in dynamic diffraction (Bloch) simulations where, for larger unit cells or zone axes with a large number of beams, an uninitialized internal value could silently corrupt the computed scattering matrix and produce a visibly incorrect image without any error or crash. Simulations in this regime are also noticeably faster now that the underlying computation is correct.

  • Fixed structure factor calculations for atoms specified with an ionic charge or site-index suffix in their element label (e.g. K1+, Zr4+, F1-), which were previously being silently matched to the wrong element’s scattering data.

  • Improved the performance of powder diffraction pattern generation for large reflection counts.

  • Requires emaps >= 1.1.0.

Version 1.1.5 Stable#

09-12-2026#

New#

  • generateCSF() now raises a catchable CSFError when structure factor generation fails, an invalid sftype is given, or the number of reflections within smax exceeds the backend beam limit – instead of silently returning a partial result.

Improvements#

  • Fixed an out-of-bounds memory write in dynamic diffraction (Bloch) image generation that could occasionally cause instability on repeated runs.

  • Significant performance improvement to dynamic diffraction (Bloch) simulations from a corrected OpenMP parallelization fix in the eigensolver – benchmarks show consistent speedups across all built-in crystals, with the largest gains on bigger structures.

  • Raised the structure factor calculation’s reflection limit and improved the reflection-selection algorithm to scale linearly with reflection count, allowing larger smax values that previously failed.

  • Packaging fix ensuring the scattering and space-group backend modules link correctly during installation.

Version 1.1.4 Stable#

03-19-2025#

Improvements#

  • Bug fixes and performance imporvements in dynamic diffraction or Bloch simulations.

  • Added python package short description in python package repository pypi.org.

Version 1.1.3 Stable#

03-01-2025#

New#

  • Added new crystal structure data module xtal with Xtal class for better handling of crystal structure data. The return from generateMxtal() now also return an Xtal class object.

Improvements#

  • Bug fixes.

  • Dynamic diffraction image list class BlochImgs in ddiffs now has better data comparison function with overloading == operator.

  • Microscopy and simulation controls module emcontrols also has improved data comparison functions for all of its classes.

  • Added automated testing for quality control. Before this version, the tests are run by developers’ on his/her local systems prior to every release. Now it is done with github’s workflow automatically triggered by code changes on release branch. More tests are to be added.

  • Adjusting sample code based on the new feature and improvements in this latest version.

Version 1.1.2 Stable#

12-03-2024#

Improvements#

  • Bug fixes.

  • User based license storage. All authenticated users on the system should be able to use pyEMAPS 4D STEM features. See the section on license activation License Activation for how to activate icense for each user.

Version 1.1.1 Stable#

11-02-2024#

What’s New?#

License activation of 4DSTEM features added. While many features remained free without license. See the section on license activation License Activation for more details.

New 4DSTEM module and its sub-modules. Importing the new 4DSTEM module as follows:

from pyemaps import stem4d

where stem4d functions are organized into two submodules called ediom and send:

To import these two modules, use the follwoing code:

from pyemaps import ediom
from pyemaps import send

Both modules will share some common values in its parent module stem4d.

Improvements#

  • Simplified pyEMAPS command line from:

pyemaps -m pyemaps [options]

to:

pyemaps [options]

Version 1.0.9 Stable#

05-29-2024#

Improvements#

  • Bug fixes for image display. Now all displays are utilizing Matplotlib’s Tkinter backend.

  • Expanded pyemaps build guide.

Version 1.0.8 Stable#

11-07-2023#

New#

  • Separated pyemaps simulations backend into standalone python package.

  • pyemaps package installation automatically installs backend python package. as one of its depedencies.

  • Made pyemaps source code ready for open source and community contribution. We invite you to become pyemaps contributor, contact support@emlabsoftware.com for further information.

Improvements#