> :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 py4DSTEM [as discussed here](#legacyinstall)
> :warning: **Phase retrieval refactor version 0.14.9** :warning: Warning: The phase-retrieval modules in py4DSTEM (DPC, parallax, and ptychography) underwent a major refactor in version 0.14.9 and as such older tutorial notebooks will not work as expected. Notably, class names have been pruned to remove the trailing "Reconstruction" (`DPCReconstruction` -> `DPC` etc.), and regularization functions have dropped the `_iter` suffix (and are instead specified as boolean flags). We are working on updating the tutorial notebooks to reflect these changes. In the meantime, there's some more information in the relevant pull request [here](https://github.com/py4dstem/py4DSTEM/pull/597#issuecomment-1890325568).
**py4DSTEM** is an open source set of python tools for processing and analysis of four-dimensional scanning transmission electron microscopy (4D-STEM) data.
Additional information:
- [Installation instructions](#install)
- [The py4DSTEM documentation pages](https://py4dstem.readthedocs.io/en/latest/index.html).
- [Tutorials and example code](https://github.com/py4dstem/py4DSTEM_tutorials)
- [Want to get involved?](#Contributing)
- [Our open access py4DSTEM publication in Microscopy and Microanalysis](https://doi.org/10.1017/S1431927621000477) describing this project and demonstrating a variety of applications.
- [Our open access 4D-STEM review in Microscopy and Microanalysis](https://doi.org/10.1017/S1431927619000497) describing 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.
**py4DSTEM** supports 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.
<a id='install'></a>
# py4DSTEM Installation
[](https://badge.fury.io/py/py4dstem)
[](https://anaconda.org/conda-forge/py4dstem)
[](https://anaconda.org/conda-forge/py4dstem)
[](https://anaconda.org/conda-forge/py4dstem)
[](https://anaconda.org/conda-forge/py4dstem)
The recommended installation for **py4DSTEM** uses 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 jupyterlab
```
In order, these commands
- ensure your installation of anaconda is up-to-date
- make a virtual environment (see below)
- enter the environment
- install py4DSTEM, as well as pymatgen (used for crystal structure calculations) and JupyterLab (an interface for running Python notebooks like those in the [py4DSTEM tutorials repository](https://github.com/py4dstem/py4DSTEM_tutorials))
We've had some recent reports install of `conda` getting stuck trying to solve the environment using the above installation. If you run into this problem, you can install py4DSTEM using `pip` instead of `conda` by running:
```
conda update conda
conda create -n py4dstem python=3.10
conda activate py4dstem
pip install py4dstem pymatgen
```
Both `conda` and `pip` are 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; `pip` is a little more bare-bones, and we've seen this install work when `conda` doesn't. If you also want to use Jupyterlab you can then use either `pip install jupyterlab` or `conda install jupyterlab`.
If you would prefer to install only the base modules of **py4DSTEM**, and skip pymategen and Jupterlab, you can instead run:
```
conda install -c conda-forge py4dstem
```
Finally, regardless of which of the above approaches you used, in Windows you should then also run:
```
conda install pywin32
```
which 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 running `conda activate py4dstem`, or, if you're using the Anaconda Navigator, by clicking on the Environments tab and then clicking on `py4dstem`.
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.
<a id='legacyinstall'></a>
## 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 the [py4DSTEM tutorials repository](https://github.com/py4dstem/py4DSTEM_tutorials) and the docstrings for the classes and functions you're using.
To install the legacy version of py4DSTEM of your choice, you can call
```
pip install py4dstem==0.XX.XX
```
substituting the desired version for `XX.XX`. For instance, you can install the last version 13 release with
```
pip install py4dstem==0.13.17
```
or the last version 12 release with
```
pip install py4dstem==0.12.24
```
## Advanced installations - GPU acceleration and ML functionality
To 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, run
```
conda update conda
conda create -n py4dstem
conda activate py4dstem
conda install pip
pip install "py4dstem[aiml]"
```
# The py4DSTEM GUI
The py4DSTEM GUI data browser has been moved to a separate repository.
You can [find that repository here](https://github.com/py4dstem/py4D-browser).
You can install the GUI from the command line with:
```
pip install py4D-browser
```
The py4D-browser can then be launched from the command line by calling:
```
py4DGUI
```
# Running the code
The 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 import **py4DSTEM** to access all its modules and functions using `import py4DSTEM`.
## Example code and tutorials
At this point you'll need code, and data!
Sample code demonstrating a variety of workflows can be found in [the py4DSTEM tutorials repository](https://github.com/py4dstem/py4DSTEM_tutorials) in the `/notebooks` directory.
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 information
<a id='Contributing'></a>
## Contributing Guide
We 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 code
For more information checkout our [Contributors Guide](CONTRIBUTORS.md)
## Documentation
Our documentation pages are [available here](https://py4dstem.readthedocs.io/en/latest/index.html).
## Scientific papers which use **py4DSTEM**
See a list [here](docs/papers.md).
# Acknowledgements
If you use py4DSTEM for a scientific study, please cite [our open access py4DSTEM publication in Microscopy and Microanalysis](https://doi.org/10.1017/S1431927621000477). You are also free to use the py4DSTEM [logo in PDF format](images/py4DSTEM_logo_54.pdf) or [logo in PNG format](images/py4DSTEM_logo_54_export.png) for presentations or posters.
[](https://www.tri.global/)
The developers gratefully acknowledge the financial support of the Toyota Research Institute for the research and development time which made this project possible.
[](https://www.energy.gov/science/bes/basic-energy-sciences/)
Additional funding has been provided by the US Department of Energy, Office of Science, Basic Energy Sciences.
# License
GNU GPLv3
**py4DSTEM** is open source software distributed under a GPLv3 license.
It is free to use, alter, or build on, provided that any work derived from **py4DSTEM** is also kept free and open under a GPLv3 license.
Raw data
{
"_id": null,
"home_page": "https://github.com/py4dstem/py4DSTEM/",
"name": "py4DSTEM",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "STEM 4DSTEM",
"author": "Benjamin H. Savitzky",
"author_email": "ben.savitzky@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f6/0e/fb327fb8c27d8e483ee107fd6fe0f943ed0548d20d38e85a0d4f5722d6bf/py4DSTEM-0.14.14.tar.gz",
"platform": null,
"description": "\n> :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 py4DSTEM [as discussed here](#legacyinstall)\n\n> :warning: **Phase retrieval refactor version 0.14.9** :warning: Warning: The phase-retrieval modules in py4DSTEM (DPC, parallax, and ptychography) underwent a major refactor in version 0.14.9 and as such older tutorial notebooks will not work as expected. Notably, class names have been pruned to remove the trailing \"Reconstruction\" (`DPCReconstruction` -> `DPC` etc.), and regularization functions have dropped the `_iter` suffix (and are instead specified as boolean flags). We are working on updating the tutorial notebooks to reflect these changes. In the meantime, there's some more information in the relevant pull request [here](https://github.com/py4dstem/py4DSTEM/pull/597#issuecomment-1890325568).\n\n\n\n**py4DSTEM** is an open source set of python tools for processing and analysis of four-dimensional scanning transmission electron microscopy (4D-STEM) data.\nAdditional information:\n\n- [Installation instructions](#install)\n- [The py4DSTEM documentation pages](https://py4dstem.readthedocs.io/en/latest/index.html).\n- [Tutorials and example code](https://github.com/py4dstem/py4DSTEM_tutorials)\n- [Want to get involved?](#Contributing)\n- [Our open access py4DSTEM publication in Microscopy and Microanalysis](https://doi.org/10.1017/S1431927621000477) describing this project and demonstrating a variety of applications.\n- [Our open access 4D-STEM review in Microscopy and Microanalysis](https://doi.org/10.1017/S1431927619000497) describing this project and demonstrating a variety of applications.\n\n\n\n# What is 4D-STEM?\n\nIn 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.\n\n\n4D-STEM data is information rich.\nA 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.\nThe structure, symmetries, and spacings of Bragg disks can be used to extract spatially resolved maps of crystallinity, grain orientations, and lattice strain.\nRedundant information in overlapping Bragg disks can be leveraged to calculate the sample potential.\nStructure in the diffracted halos of amorphous systems can be used to describe the short and medium range order.\n\n**py4DSTEM** supports many different modes of 4DSTEM analysis.\nThe tutorials, sample code, module, and function documentation all provide more detailed discussion on some of the analytical methods possible with this code.\n\n\n\n<a id='install'></a>\n# py4DSTEM Installation\n\n[](https://badge.fury.io/py/py4dstem)\n[](https://anaconda.org/conda-forge/py4dstem)\n[](https://anaconda.org/conda-forge/py4dstem)\n[](https://anaconda.org/conda-forge/py4dstem)\n[](https://anaconda.org/conda-forge/py4dstem)\n\nThe recommended installation for **py4DSTEM** uses the Anaconda python distribution.\nFirst, download and install Anaconda: www.anaconda.com/download. \nIf you prefer a more lightweight conda client, you can instead install Miniconda: https://docs.conda.io/en/latest/miniconda.html.\nThen 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:\n\n```\nconda update conda\nconda create -n py4dstem\nconda activate py4dstem\nconda install -c conda-forge py4dstem pymatgen jupyterlab\n```\n\nIn order, these commands\n- ensure your installation of anaconda is up-to-date\n- make a virtual environment (see below)\n- enter the environment\n- install py4DSTEM, as well as pymatgen (used for crystal structure calculations) and JupyterLab (an interface for running Python notebooks like those in the [py4DSTEM tutorials repository](https://github.com/py4dstem/py4DSTEM_tutorials))\n\n\nWe've had some recent reports install of `conda` getting stuck trying to solve the environment using the above installation. If you run into this problem, you can install py4DSTEM using `pip` instead of `conda` by running:\n\n```\nconda update conda\nconda create -n py4dstem python=3.10 \nconda activate py4dstem\npip install py4dstem pymatgen \n```\n\nBoth `conda` and `pip` are 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; `pip` is a little more bare-bones, and we've seen this install work when `conda` doesn't. If you also want to use Jupyterlab you can then use either `pip install jupyterlab` or `conda install jupyterlab`.\n\nIf you would prefer to install only the base modules of **py4DSTEM**, and skip pymategen and Jupterlab, you can instead run:\n\n```\nconda install -c conda-forge py4dstem\n```\n\nFinally, regardless of which of the above approaches you used, in Windows you should then also run:\n\n```\nconda install pywin32\n```\n\nwhich enables Python to talk to the Windows API.\n\nPlease 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.\nBecause these directions install py4DSTEM to its own virtual environment, each time you want to use py4DSTEM you'll need to activate this environment.\nYou can do this in the command line by running `conda activate py4dstem`, or, if you're using the Anaconda Navigator, by clicking on the Environments tab and then clicking on `py4dstem`.\n\nLast - 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.\n\n\n<a id='legacyinstall'></a>\n## Legacy installations (version <0.14)\n\nThe latest version of py4DSTEM (v0.14) makes changes to the classes and functions which may not be compatible with code written for prior versions.\nWe are working to ensure better backwards-compatibility in the future.\nFor 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.\nTo update your code to the new syntax, check out the examples in the [py4DSTEM tutorials repository](https://github.com/py4dstem/py4DSTEM_tutorials) and the docstrings for the classes and functions you're using.\nTo install the legacy version of py4DSTEM of your choice, you can call\n\n```\npip install py4dstem==0.XX.XX\n```\n\nsubstituting the desired version for `XX.XX`. For instance, you can install the last version 13 release with\n\n```\npip install py4dstem==0.13.17\n```\n\nor the last version 12 release with\n\n```\npip install py4dstem==0.12.24\n```\n\n\n\n\n## Advanced installations - GPU acceleration and ML functionality\n\nTo install the py4dstem with AI/ML functionality, follow the steps below.\nIf you're using a machine with an Nvidia GPU and CUDA capability, run:\n\n```\nconda update conda\nconda create -n py4dstem-aiml\nconda activate py4dstem-aiml\nconda install -c conda-forge cudatoolkit=11.0 cudnn=8.1 cupy \npip install \"py4dstem[aiml-cuda]\"\n```\n\nIf your machine does not have a CUDA capable device, run\n```\nconda update conda\nconda create -n py4dstem\nconda activate py4dstem\nconda install pip\npip install \"py4dstem[aiml]\"\n```\n\n\n\n# The py4DSTEM GUI\n\nThe py4DSTEM GUI data browser has been moved to a separate repository.\nYou can [find that repository here](https://github.com/py4dstem/py4D-browser).\nYou can install the GUI from the command line with:\n\n```\npip install py4D-browser\n```\n\nThe py4D-browser can then be launched from the command line by calling:\n\n```\npy4DGUI\n```\n\n\n\n\n# Running the code\n\nThe anaconda navigator can be used to launch various Python interfaces, including Jupyter Notebooks, JupyterLab, PyCharm, and others.\n\nOnce you're inside the conda environment where you installed py4DSTEM and you've launched an interface to the Python interpreter, you can import **py4DSTEM** to access all its modules and functions using `import py4DSTEM`.\n\n\n## Example code and tutorials\n\nAt this point you'll need code, and data!\nSample code demonstrating a variety of workflows can be found in [the py4DSTEM tutorials repository](https://github.com/py4dstem/py4DSTEM_tutorials) in the `/notebooks` directory.\nThese sample files are provided as Jupyter notebooks.\nLinks to the data used in each notebook are provided in the intro cell of each notebook.\n\n\n\n\n# More information\n<a id='Contributing'></a>\n\n## Contributing Guide \nWe 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 code\n\nFor more information checkout our [Contributors Guide](CONTRIBUTORS.md)\n\n\n## Documentation\n\nOur documentation pages are [available here](https://py4dstem.readthedocs.io/en/latest/index.html).\n\n\n\n## Scientific papers which use **py4DSTEM**\n\nSee a list [here](docs/papers.md).\n\n\n\n\n# Acknowledgements\n\nIf you use py4DSTEM for a scientific study, please cite [our open access py4DSTEM publication in Microscopy and Microanalysis](https://doi.org/10.1017/S1431927621000477). You are also free to use the py4DSTEM [logo in PDF format](images/py4DSTEM_logo_54.pdf) or [logo in PNG format](images/py4DSTEM_logo_54_export.png) for presentations or posters.\n\n\n[](https://www.tri.global/)\n\n\nThe developers gratefully acknowledge the financial support of the Toyota Research Institute for the research and development time which made this project possible.\n\n[](https://www.energy.gov/science/bes/basic-energy-sciences/)\n\nAdditional funding has been provided by the US Department of Energy, Office of Science, Basic Energy Sciences.\n\n\n\n# License\n\nGNU GPLv3\n\n**py4DSTEM** is open source software distributed under a GPLv3 license.\nIt is free to use, alter, or build on, provided that any work derived from **py4DSTEM** is also kept free and open under a GPLv3 license.\n\n",
"bugtrack_url": null,
"license": "GNU GPLv3",
"summary": "An open source python package for processing and analysis of 4D STEM data.",
"version": "0.14.14",
"project_urls": {
"Homepage": "https://github.com/py4dstem/py4DSTEM/"
},
"split_keywords": [
"stem",
"4dstem"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "27ceaa1c555df44221a33e9854d3ba45bbaaf89b98e4309ac59d5654a45e171b",
"md5": "9bca8996b06ce4dc503c68e9d1b884a2",
"sha256": "1cccc2bf4c5af0b4df636fea0207581c6d73cbdfc5b76ece0b11b495f5bb62f5"
},
"downloads": -1,
"filename": "py4DSTEM-0.14.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9bca8996b06ce4dc503c68e9d1b884a2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 682731,
"upload_time": "2024-03-21T23:15:33",
"upload_time_iso_8601": "2024-03-21T23:15:33.088129Z",
"url": "https://files.pythonhosted.org/packages/27/ce/aa1c555df44221a33e9854d3ba45bbaaf89b98e4309ac59d5654a45e171b/py4DSTEM-0.14.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f60efb327fb8c27d8e483ee107fd6fe0f943ed0548d20d38e85a0d4f5722d6bf",
"md5": "316285a7d2dbe5cc00ad960c5893814b",
"sha256": "bbbf2f0b09fecd1aa66c615d323d87829fef004b70f9c2c98386f0bea32da93f"
},
"downloads": -1,
"filename": "py4DSTEM-0.14.14.tar.gz",
"has_sig": false,
"md5_digest": "316285a7d2dbe5cc00ad960c5893814b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 602063,
"upload_time": "2024-03-21T23:15:35",
"upload_time_iso_8601": "2024-03-21T23:15:35.216442Z",
"url": "https://files.pythonhosted.org/packages/f6/0e/fb327fb8c27d8e483ee107fd6fe0f943ed0548d20d38e85a0d4f5722d6bf/py4DSTEM-0.14.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-21 23:15:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "py4dstem",
"github_project": "py4DSTEM",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "py4dstem"
}
JSON
