Package: py4DSTEM
:warning:py4DSTEM version 0.14 update:warning: Warning: this is a major update and we expect some workflows to break.  You can still install previous versions of py4DSTEMas discussed herepy4DSTEMis an open source set of python tools for processing and analysis of four-dimensional scanning transmission electron microscopy (4D-STEM) data.
Additional information:Installation instructionsThe py4DSTEM documentation pages.Tutorials and example codeWant to get involved?Our open access py4DSTEM publication in Microscopy and Microanalysisdescribing this project and demonstrating a variety of applications.Our open access 4D-STEM review in Microscopy and Microanalysisdescribing this project and demonstrating a variety of applications.What is 4D-STEM?In a traditional STEM experiment, a beam of high energy electrons is focused to a very fine probe - on the order of, or even smaller than, the spacing between atoms - and rastered across the surface of the sample. A conventional two-dimensional STEM image is formed by populating the value of each pixel with the electron flux through a detector at the corresponding beam position. In 4D-STEM, a pixelated detector is used instead, where a 2D image of the diffracted probe is recorded at every rastered probe position. A 4D-STEM scan thus results in a 4D data array.4D-STEM data is information rich.
A datacube can be collapsed in real space to yield information comparable to nanobeam electron diffraction experiment, or in diffraction space to yield a variety of virtual images, corresponding to both traditional STEM imaging modes as well as more exotic virtual imaging modalities.
The structure, symmetries, and spacings of Bragg disks can be used to extract spatially resolved maps of crystallinity, grain orientations, and lattice strain.
Redundant information in overlapping Bragg disks can be leveraged to calculate the sample potential.
Structure in the diffracted halos of amorphous systems can be used to describe the short and medium range order.py4DSTEMsupports many different modes of 4DSTEM analysis.
The tutorials, sample code, module, and function documentation all provide more detailed discussion on some of the analytical methods possible with this code.py4DSTEM InstallationThe recommended installation forpy4DSTEMuses the Anaconda python distribution.
First, download and install Anaconda:www.anaconda.com/download.
If you prefer a more lightweight conda client, you can instead install Miniconda:https://docs.conda.io/en/latest/miniconda.html.
Then open a conda terminal and run one of the following sets of commands to ensure everything is up-to-date and create a new environment for your py4DSTEM installation:conda update conda
conda create -n py4dstem
conda activate py4dstem
conda install -c conda-forge py4dstem pymatgen jupyterlabIn order, these commandsensure your installation of anaconda is up-to-datemake a virtual environment (see below)enter the environmentinstall py4DSTEM, as well as pymatgen (used for crystal structure calculations) and JupyterLab (an interface for running Python notebooks like those in thepy4DSTEM tutorials repository)We've had some recent reports install ofcondagetting stuck trying to solve the environment using the above installation.  If you run into this problem, you can install py4DSTEM usingpipinstead ofcondaby running:conda update conda
conda create -n py4dstem python=3.10 
conda activate py4dstem
pip install py4dstem pymatgenBothcondaandpipare programs which manage package installations, i.e. make sure different codes you're installing which depend on one another are using mutually compatible versions.  Each has advantages and disadvantages;pipis a little more bare-bones, and we've seen this install work whencondadoesn't.  If you also want to use Jupyterlab you can then use eitherpip install jupyterlaborconda install jupyterlab.If you would prefer to install only the base modules ofpy4DSTEM, and skip pymategen and Jupterlab, you can instead run:conda install -c conda-forge py4dstemFinally, regardless of which of the above approaches you used, in Windows you should then also run:conda install pywin32which enables Python to talk to the Windows API.Please note that virtual environments are used in the instructions above in order to make sure packages that have different dependencies don't conflict with one another.
Because these directions install py4DSTEM to its own virtual environment, each time you want to use py4DSTEM you'll need to activate this environment.
You can do this in the command line by runningconda activate py4dstem, or, if you're using the Anaconda Navigator, by clicking on the Environments tab and then clicking onpy4dstem.Last - as of the version 0.14.4 update, we've had a few reports of problems upgrading to the newest version.  We're not sure what's causing the issue yet, but have found the new version can be installed successfully in these cases using a fresh Anaconda installation.Legacy installations (version <0.14)The latest version of py4DSTEM (v0.14) makes changes to the classes and functions which may not be compatible with code written for prior versions.
We are working to ensure better backwards-compatibility in the future.
For now, if you have code from earlier versions, you can either (1) install the legacy version of your choice, or (2) update legacy code to use the version 0.14 methods.
To update your code to the new syntax, check out the examples in thepy4DSTEM tutorials repositoryand the docstrings for the classes and functions you're using.
To install the legacy version of py4DSTEM of your choice, you can callpip install py4dstem==0.XX.XXsubstituting the desired version forXX.XX.  For instance, you can install the last version 13 release withpip install py4dstem==0.13.17or the last version 12 release withpip install py4dstem==0.12.24Advanced installations - GPU acceleration and ML functionalityTo install the py4dstem with AI/ML functionality, follow the steps below.
If you're using a machine with an Nvidia GPU and CUDA capability, run:conda update conda
conda create -n py4dstem-aiml
conda activate py4dstem-aiml
conda install -c conda-forge cudatoolkit=11.0 cudnn=8.1 cupy 
pip install "py4dstem[aiml-cuda]"If your machine does not have a CUDA capable device, runconda update conda
conda create -n py4dstem
conda activate py4dstem
conda install pip
pip install "py4dstem[aiml]"The py4DSTEM GUIThe py4DSTEM GUI data browser has been moved to a separate repository.
You canfind that repository here.
You can install the GUI from the command line with:pip install py4D-browserThe py4D-browser can then be launched from the command line by calling:py4DGUIRunning the codeThe anaconda navigator can be used to launch various Python interfaces, including Jupyter Notebooks, JupyterLab, PyCharm, and others.Once you're inside the conda environment where you installed py4DSTEM and you've launched an interface to the Python interpreter, you can importpy4DSTEMto access all its modules and functions usingimport py4DSTEM.Example code and tutorialsAt this point you'll need code, and data!
Sample code demonstrating a variety of workflows can be found inthe py4DSTEM tutorials repositoryin the/notebooksdirectory.
These sample files are provided as Jupyter notebooks.
Links to the data used in each notebook are provided in the intro cell of each notebook.More informationContributing GuideWe are grateful for your interest in contributing to py4DSTEM. There are many ways to contribute to py4DSTEM, including Reporting bugs, Submitting feature requests, Improving documentation and Developing new codeFor more information checkout ourContributors GuideDocumentationOur documentation pages areavailable here.Scientific papers which usepy4DSTEMSee a listhere.AcknowledgementsIf you use py4DSTEM for a scientific study, please citeour open access py4DSTEM publication in Microscopy and Microanalysis. You are also free to use the py4DSTEMlogo in PDF formatorlogo in PNG formatfor presentations or posters.The developers gratefully acknowledge the financial support of the Toyota Research Institute for the research and development time which made this project possible.Additional funding has been provided by the US Department of Energy, Office of Science, Basic Energy Sciences.LicenseGNU GPLv3py4DSTEMis open source software distributed under a GPLv3 license.
It is free to use, alter, or build on, provided that any work derived frompy4DSTEMis also kept free and open under a GPLv3 license.