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_filecreates an image from a file, andpyemaps.read_imagereturns 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.npyarrays.
binning and scan_roi read large patterns and scans within the 4D-STEM limits, and
convertImagewithnformat=E_FILEsaves a converted copy in pyEMAPS’.im3format. 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_equivinstead of_atom_site_U_iso_or_equiv, or a single atom written without aloop_, 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 fromgetBlochImages()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()andshowBloch()withlayout='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 notebookscopies 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 -cptakessamplesornotebooksto copy only the sample scripts or only the notebooks; with neither, it copies both. It no longer overwrites files already there.Printing an
EMControlorSIMControl, 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
Crystalused after another one could reuse the other crystal’s data, and deleting it could crash the current one.The built-in
Germaniumcrystal 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.samplesneeds 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()withlayout='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()andbeginBloch()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
gctlandzctlsimulation controls now reach the simulation. Before, they were silently ignored. A value too small for the pattern, such asgctl=1, now makesgenerateDP()fail.convertImage()now converts numpy images: pass the 2-D array as imgfn withnformat=E_NPY. It returns the converted file’s path, and raisesXDPImageErrorwhen 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()raisesDPListErrorwhen it isn’t given aDPList, 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 returnsFalseinstead of raising an error.An invalid camera length in
EMControlraisesEMCError, like the other controls, instead ofValueError.
Improvements#
-
A crystal created without data can be checked with
loaded(), and no longer prints an error when it’s freed.Atom.atypereturns 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
symbfrom the dictionary’s atoms, so the same data can be used again.Cell errors name the right cell constant.
Cell.session_controlsisNoneuntil set, instead of raising an error.from_xtl()andfrom_cif()report a file that can’t be read asCrystalClassError.
Fixed the microscope and simulation controls:
Each
EMControlcreated without simulation controls gets its ownSIMControl. Before, they all shared one, so changing one changed them all.EMControl.from_dictuses 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
SIMControlare 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_imagesworks onBImgList.
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 aStackImageis 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
ACoordcreated 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 pyemapskeeps installing pyEMAPS 1.1.x with emaps 1.1.x.Requires
numpy >= 2.0andmatplotlib >= 3.8.4.The emaps backend no longer exposes the undocumented
emaps.diffract.emaps_sims.metricattribute (the crystal metric tensors). Nothing in pyEMAPS used it, and simulation results are unchanged.emaps no longer depends on the
msvc-runtimepackage. 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=Truenow 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.
StackImagewithnformat=E_NPYfailed withTypeErrorwhenever itsdatawas set, and now works. Any 2-D boolean, integer or floating-point array, includingfloat64andint32, is accepted and converted tofloat32. Invalid input raisesXDPImageErrorwith a clear message. In the emaps backend, images with more rows than columns, or transposed arrays, could crash Python, anduint8/uint16arrays 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 catchableCSFErrorwhen 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
xtalwithXtalclass for better handling of crystal structure data. The return fromgenerateMxtal()now also return anXtalclass object.
Improvements#
Bug fixes.
Dynamic diffraction image list class
BlochImgsinddiffsnow has better data comparison function with overloading == operator.Microscopy and simulation controls module
emcontrolsalso 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:
ediom: electron diffraction indexing and oriention mapping. currently, this module contains the diffraction indexing.
Orientan mapping will be added to ediom later.
send: scanning electronic nano-diffraction. This module now has the following functions:
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#
Bug fixes related to DigitalMicrograph (DM) integration and added DM python script sample code, as shown in Rendering by Third Party Tools