py4DSTEM

https://py4dstem.readthedocs.io/en/latest/
Admin
py4DSTEM is an open source Python library for processing and analysis of four-dimensional scanning...
Tokens:188,661
Snippets:1,117
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install py4D-browser from GitHub

Source: https://py4dstem.readthedocs.io/en/latest/gui.html

Clone the py4D-browser repository and install it using setup.py. This method is for direct installation from the source code.

```bash
git clone https://github.com/sezelt/py4D-browser.git
cd py4D-browser
python setupy.py
```

--------------------------------

### Tree Manipulation Examples

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Demonstrates various ways to interact with the node tree using the .tree() method, including showing, adding, getting, cutting, and grafting branches.

```python
>>> .tree()             # show tree from current node
>>> .tree(show=True)    # show from root
>>> .tree(show=False)   # show from current node
>>> .tree(add=node)     # add a child node
>>> .tree(get='path')   # return a '/' delimited child node
>>> .tree(get='/path')  # as above, starting at root
>>> .tree(cut=True)     # remove/return a branch, keep root metadata
>>> .tree(cut=False)    # remove/return a branch, discard root md
>>> .tree(cut='copy')   # remove/return a branch, copy root metadata
>>> .tree(graft=node)   # remove/graft a branch, keeping root metadata
>>> .tree(graft=(node,True))    # as above
>>> .tree(graft=(node,False))   # as above, discard root metadata
>>> .tree(graft=(node,'copy'))  # as above, copy root metadata

```

```python
>>> .tree(arg)

```

--------------------------------

### Install py4DSTEM from Source

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Methods for installing the latest development version of py4DSTEM directly from the repository.

```bash
1git clone
2git checkout <branch> # e.g. git checkout dev
3pip install -e .
```

```bash
1pip install git+https://github.com/py4DSTEM/py4DSTEM.git@dev # install the dev branch
```

--------------------------------

### Install py4DSTEM on Windows (Pip)

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Pip-based installation for Windows environments, including support for ACOM, GPU acceleration, and ML-AI features.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3pip install py4dstem[acom]
4conda install -c conda-forge pywin32
```

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3pip install py4dstem[cuda]
4conda install -c conda-forge pywin32
```

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3pip install py4dstem[aiml]
4conda install -c conda-forge pywin32
```

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge cudatoolkit=11.0
4pip install py4dstem[aiml-cuda]
5conda install -c conda-forge pywin32
```

--------------------------------

### Install py4DSTEM on Linux (Pip)

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Pip-based installation for Linux environments, supporting ACOM, GPU acceleration, and ML-AI configurations.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3pip install py4dstem[acom]
```

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3pip install py4dstem[cuda]
```

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3pip install py4dstem[aiml]
```

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge cudatoolkit=11.0
4pip install py4dstem[aiml-cuda]
```

--------------------------------

### Install py4DSTEM on Intel Mac (Pip)

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Pip-based installation for Intel-based Macs, noting that ML-AI features run on CPU only.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3pip install py4dstem[acom]
```

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3pip install py4dstem[aiml]
```

--------------------------------

### Install py4DSTEM on Apple Silicon (Pip)

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Pip-based installation for Apple Silicon Macs, including ACOM, ML-AI CPU, and experimental GPU support.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3pip install py4dstem[acom]
4conda install -c conda-forge py4dstem pymatgen
```

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3pip install py4dstem[aiml]
```

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c apple tensorflow-deps
4pip install tensorflow-macos==2.5.0 tensorflow-addons<=0.14 crystal4D tensorflow-metal py4dstem
```

--------------------------------

### Install py4DSTEM on Apple Silicon (Conda)

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Standard installation for ACOM, ML-AI CPU, and experimental ML-AI GPU support on Apple Silicon Macs.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge py4dstem pymatgen
```

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge py4dstem
4pip install tensorflow==2.4.1 tensorflow-addons<=0.14 crystal4D
```

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c apple tensorflow-deps
4pip install tensorflow-macos==2.5.0 tensorflow-addons<=0.14 crystal4D tensorflow-metal
5conda install -c conda-forge py4dstem
```

--------------------------------

### Install py4D-browser using pip

Source: https://py4dstem.readthedocs.io/en/latest/gui.html

Install the py4D-browser directly from its GitHub repository using pip. This is a convenient method for users who prefer using pip for package management.

```bash
pip install git+https://github.com/sezelt/py4D-browser
```

--------------------------------

### Tree Manipulation Methods

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Examples of how to use the .tree() method for various operations like getting, cutting, and grafting branches of a tree structure.

```APIDOC
## Tree Manipulation

### Description
Methods for manipulating tree structures within the py4DSTEM library.

### Methods
- `.tree(get='/path')`
- `.tree(cut=True)`
- `.tree(cut=False)`
- `.tree(cut='copy')`
- `.tree(graft=node)`
- `.tree(graft=(node,True))`
- `.tree(graft=(node,False))`
- `.tree(graft=(node,'copy'))`

### Usage
These methods are accessed via an instance of a class that supports tree operations.

### Parameters
- `get` (str): Specifies a path to retrieve a subtree.
- `cut` (bool or str): Controls the behavior of cutting a branch. `True` removes and returns the branch, keeping root metadata. `False` removes and returns the branch, discarding root metadata. `'copy'` removes and returns the branch, copying root metadata.
- `graft` (Node or tuple): Controls the behavior of grafting a branch. `node` is the branch to graft. If a tuple `(node, bool)` or `(node, str)` is provided, the boolean or string controls whether to keep or discard root metadata, or to copy it ('copy').
```

--------------------------------

### Deformation Matrix Example

Source: https://py4dstem.readthedocs.io/en/latest/api/process.html

Example of a 3x3 deformation matrix used for applying strain.

```python
deformation_matrix = np.array([
    [1.0+exx, 1.0*exy, 1.0*exz],
    [1.0*exy, 1.0+eyy, 1.0*eyz],
    [1.0*exz, 1.0*eyz, 1.0+ezz],
])
```

--------------------------------

### Windows Base Anaconda Install for py4DSTEM

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Installs py4DSTEM and recommended packages like jupyterlab and pymatgen on Windows using Anaconda. Ensure Anaconda is installed and the environment is activated.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge py4dstem
4conda install -c conda-forge pywin32
5# optional but recomended
6conda install jupyterlab pymatgen

```

--------------------------------

### Metadata Usage Example

Source: https://py4dstem.readthedocs.io/en/latest/api/emd.html

Demonstrates basic usage of the Metadata class for storing and retrieving key-value pairs. The getter methods return None if a parameter has not been set.

```python
>>> meta = Metadata()
>>> meta['param'] = value
>>> val = meta['param']
```

--------------------------------

### Image Scaling Options

Source: https://py4dstem.readthedocs.io/en/latest/api/py4DSTEM.html

Examples of applying different scaling methods to the displayed image without altering the underlying data.

```python
>>> show(ar,scaling='log')
>>> show(ar,power=0.5)
>>> show(ar,scaling='power',power=0.5,hist=True)
```

--------------------------------

### Geometric Overlays

Source: https://py4dstem.readthedocs.io/en/latest/api/py4DSTEM.html

Examples of adding geometric shapes like rectangles and annuli as overlays on the image.

```python
>>> show(ar, rectangle={'lims':(10,20,10,20),'color':'r'})
```

```python
>>> show(ar, annulus={'center':[(28,68),(92,160)],
                      'radii':[(16,24),(12,36)],
                      'fill':True,
                      'alpha':[0.9,0.3],
                      'color':['r',(0,1,1,1)]})
```

--------------------------------

### First Steps with py4DSTEM

Source: https://py4dstem.readthedocs.io/en/latest/examples.html

This snippet demonstrates the initial steps for using py4DSTEM. It includes importing the library, checking the version, downloading a sample dataset, loading the data into a datacube, and plotting a diffraction pattern. Ensure py4DSTEM is installed and the Python environment is activated.

```python
import py4DSTEM

py4DSTEM.__version__
py4DSTEM.io.download_file_from_google_drive(
    '1PmbCYosA1eYydWmmZebvf6uon9k_5g_S',
    'simulatedAuNanoplatelet_binned.h5'
)
file_data = "simulatedAuNanoplatelet_binned.h5"
datacube = py4DSTEM.io.read(
    file_data,
    data_id = 'polyAu_4DSTEM'
)
py4DSTEM.show(
    datacube[10,30],
    intensity_range='absolute',
    vmin=20,
    vmax=200,
    cmap='viridis'
)
```

--------------------------------

### Direct Access to Tree Methods

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

The `show`, `add`, and `get` methods can be accessed directly using `.tree(arg)` where `arg` is of the appropriate type (bool, Node, or string).

```python
>>> .tree(arg)
```

--------------------------------

### Get Node Path from Tree

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Retrieve the path of a child node as a '/' delimited string using `.tree(get='path')` or `.tree(get='/path')` starting from the root.

```python
>>> .tree(get='path')   # return a '/' delimited child node
```

```python
>>> .tree(get='/path')  # as above, starting at root
```

--------------------------------

### Initialization Methods

Source: https://py4dstem.readthedocs.io/en/latest/api/process.html

Methods for initializing a Featurization instance.

```APIDOC
## __init__

### Description
Initializes classification instance. This method: 1. Generates key:value pair to access input features 2. Initializes the empty dictionaries for feature modification and classification.

### Method
__init__

### Parameters
#### Path Parameters
- **features** (list) - Required - A list of ndarrays which will each be associated with value stored at the key in the same index within the list
- **R_Nx** (int) - Required - The real space x dimension of the dataset
- **R_Ny** (int) - Required - The real space y dimension of the dataset
- **name** (str) - Required - The name of the featurization object

### Response
#### Success Response (200)
- **new_instance** (Featurization instance) - Description of the returned instance

## from_braggvectors

### Description
Initialize a featurization instance from a BraggVectors instance. Transforms the calibrated pointlistarray in BraggVectors instance into a numpy array that can be clustered using the methods in featurization.

### Method
from_braggvectors

### Parameters
#### Path Parameters
- **braggvectors** (BraggVectors) - Required - BraggVectors instance containing calibrations
- **bins_x** (int) - Required - Number of pixels per bin in x direction
- **bins_y** (int) - Required - Number of pixels per bin in y direction
- **intensity_scale** (float) - Required - Value to scale intensity of detected disks by
- **name** (str) - Required - Name of featurization instance
- **mask** (bool) - Optional - Mask to remove disks in unwanted positions in diffraction space

### Response
#### Success Response (200)
- **new_instance** (Featurization instance) - Featurization instance

```

--------------------------------

### Linux Anaconda Install for py4DSTEM with ACOM

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Installs py4DSTEM and pymatgen on Linux using Anaconda. This is for the ACOM installation.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge py4dstem pymatgen

```

--------------------------------

### I/O and Utility Methods

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Methods for loading from and saving to HDF5 files, and for creating new nodes.

```APIDOC
## I/O and Utility Methods

### Description
Methods for interacting with HDF5 files and utility functions for node creation.

### Methods

#### _classmethod _from_h5(_group_)
Loads and returns a VirtualDiffraction object from an open h5py Group.

**Parameters:**
- **group** (h5py Group) - The h5py Group to load from.

#### _static _newnode(_method_)
A decorator for methods that produce and return a new node, automatically handling tree addition and metadata.

#### show_tree(_root =False_)
Displays the object tree, either from the current node or the root.

**Parameters:**
- **root** (bool) - If True, displays the full tree from the root.

#### to_h5(_group_)
Saves the VirtualDiffraction object, its data, and metadata to an h5py Group.

**Parameters:**
- **group** (h5py Group) - The h5py Group to save to.

**Returns:**
- (h5py Group) The h5py Group containing the saved data.
```

--------------------------------

### Calibration Initialization and Persistence

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Details on how to initialize a Calibration instance and how to save and load calibration data from HDF5 files.

```APIDOC
## POST /api/calibration/init

### Description
Initializes a new Calibration instance.

### Method
POST

### Endpoint
`/api/calibration/init`

### Parameters
#### Request Body
- **name** (string, optional) - The name for the calibration instance. Defaults to 'calibration'.
- **root** (object, optional) - The root object for the calibration tree.

### Request Example
```json
{
  "name": "my_calibration",
  "root": { ... }
}
```

## POST /api/calibration/to_h5

### Description
Saves the metadata dictionary and the list of registered calibration targets to an HDF5 group.

### Method
POST

### Endpoint
`/api/calibration/to_h5`

### Parameters
#### Request Body
- **group** (HDF5 group object) - Required - The HDF5 group to save the calibration data to.

### Request Example
```json
{
  "group": { ... } 
}
```

## CLASS_METHOD /api/calibration/from_h5

### Description
Loads and returns a Calibration instance from a given HDF5 group. Raises an exception if the group is not a valid representation of a Calibration instance.

### Method
CLASS_METHOD (equivalent to a static method or class constructor call)

### Endpoint
`/api/calibration/from_h5`

### Parameters
#### Request Body
- **group** (HDF5 group object) - Required - The HDF5 group to load the calibration from.

### Response
#### Success Response (200)
- **calibration_instance** (object) - The loaded Calibration instance.

#### Response Example
```json
{
  "calibration_instance": { ... }
}
```
```

--------------------------------

### Windows Anaconda Install for py4DSTEM with ACOM

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Installs py4DSTEM and pymatgen on Windows using Anaconda. This is for the ACOM installation.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge py4dstem pymatgen
4conda install -c conda-forge pywin32

```

--------------------------------

### QPoints Class Initialization

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Initializes a QPoints instance with diffraction space data.

```APIDOC
## QPoints Class

### Description
Stores a set of diffraction space points, with fields ‘qx’, ‘qy’ and ‘intensity’.

### Method
__init__

### Parameters
#### Request Body
- **data** (structured numpy ndarray) - Required - Should have three fields, which will be renamed ‘qx’,’qy’,’intensity’.
- **name** (str) - Optional - The name of the QPoints instance. Defaults to 'qpoints'.

### Response Example
```json
{
  "message": "QPoints instance created successfully"
}
```
```

--------------------------------

### Linux Base Anaconda Install for py4DSTEM

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Installs py4DSTEM and recommended packages like jupyterlab and pymatgen on Linux using Anaconda. Ensure Anaconda is installed and the environment is activated.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge py4dstem
4# optional but recomended
5conda install jupyterlab pymatgen

```

--------------------------------

### Array Class Initialization

Source: https://py4dstem.readthedocs.io/en/latest/api/emd.html

Demonstrates how to initialize the Array class with various parameters, including basic data, name, units, dimension calibrations, units, and labels.

```APIDOC
## Array Class Initialization

### Description
Initializes an Array object to store N-dimensional data with metadata.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **data** (np.ndarray) - Required - The N-dimensional array data.
- **name** (str) - Optional - The name of the Array. Defaults to 'array'.
- **units** (str) - Optional - The units for the pixel values. Defaults to ''.
- **dims** (list) - Optional - Calibration vectors for each axis. Can be None, a number, a 2-element list/array, or an M-element list/array. If None, populated with integers starting at 0 (units: 'pixels'). If a number, a linear vector starting at 0 with that step size. If a 2-element list/array, a linear vector with those two numbers as the first two elements. If a list/array of length M, it's used directly. If fewer arguments than dimensions are provided, remaining dimensions are populated as if None were passed.
- **dim_units** (list) - Optional - Units for the calibration dim vectors. If not passed, defaults to 'pixels' for auto-populated dims and 'unknown' for others. If length < array dimensions, values apply to first N dimensions, remaining are auto-populated.
- **dim_names** (list) - Optional - Labels for each axis of the data array.
- **slicelabels** (list) - Optional - Labels for distinct arrays within the final dimension, enabling stack-like behavior.

### Request Example
```python
from py4dstem.emdfile import Array
import numpy as np

# Basic initialization
ar_basic = Array(np.ones((20, 20, 256, 256)))

# Initialization with metadata
ar_metadata = Array(
    np.ones((20, 20, 256, 256)),
    name='test_array',
    units='intensity',
    dims=[
        [0, 5],  # rx dimension
        [0, 5],  # ry dimension
        [0, 0.01],
        [0, 0.01]
    ],
    dim_units=[
        'nm',
        'nm',
        'A^-1',
        'A^-1'
    ],
    dim_names=[
        'rx',
        'ry',
        'qx',
        'qy'
    ]
)

# Initialization with non-constant pixel lengths
x = np.logspace(0, 1, 100)
y = np.sin(x)
ar_non_constant = Array(y, dims=[x])

# Initialization with slicelabels for stack-like arrays
ar_stack = Array(
    np.ones((50, 50, 4)),
    name='test_array_stack',
    units='intensity',
    dims=[
        [0, 2],
        [0, 2]
    ],
    dim_units=['nm', 'nm'],
    dim_names=['rx', 'ry'],
    slicelabels=['a', 'b', 'c', 'd']
)
```

### Response
#### Success Response (200)
An initialized Array object.

#### Response Example
```json
{
  "message": "Array object created successfully"
}
```
```

--------------------------------

### Initialize Custom Kernel Disk Lattice

Source: https://py4dstem.readthedocs.io/en/latest/api/process.html

Constructor for the Custom Kernel Disk Lattice model.

```python
_class _py4DSTEM.process.wholepatternfit.wp_models.KernelDiskLattice(_WPF_ , _probe_kernel : ndarray_, _ux : float_, _uy : float_, _vx : float_, _vy : float_, _u_max : int_, _v_max : int_, _intensity_0 : float_, _exclude_indices : list = []_, _global_center : bool = True_, _x0 =0.0_, _y0 =0.0_, _name ='Custom Kernel Disk Lattice'_, _verbose =False_)
```

```python
__init__(_WPF_ , _probe_kernel : ndarray_, _ux : float_, _uy : float_, _vx : float_, _vy : float_, _u_max : int_, _v_max : int_, _intensity_0 : float_, _exclude_indices : list = []_, _global_center : bool = True_, _x0 =0.0_, _y0 =0.0_, _name ='Custom Kernel Disk Lattice'_, _verbose =False_)
```

--------------------------------

### Apple Silicon Mac Base Anaconda Install for py4DSTEM

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Installs py4DSTEM and recommended packages like jupyterlab and pymatgen on Apple Silicon Macs using Anaconda. Ensure Anaconda is installed and the environment is activated.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install pyqt hdf5
4conda install -c conda-forge py4dstem
5# optional but recomended
6conda install jupyterlab pymatgen

```

--------------------------------

### py4DSTEM.process.wholepatternfit.wp_models.KernelDiskLattice Methods

Source: https://py4dstem.readthedocs.io/en/latest/genindex.html

This section lists the methods available for the py4DSTEM.process.wholepatternfit.wp_models.KernelDiskLattice class.

```APIDOC
## py4DSTEM.process.wholepatternfit.wp_models.KernelDiskLattice Methods

### Description
Methods for modeling kernel disk lattices in whole pattern fitting.

### Methods
- `(py4DSTEM.process.wholepatternfit.wp_models.KernelDiskLattice method)`: Represents a kernel disk lattice method.
```

--------------------------------

### Linux Anaconda Install for py4DSTEM with GPU Acceleration

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Installs py4DSTEM with GPU acceleration (cupy, cudatoolkit) on Linux using Anaconda. Requires an NVIDIA GPU and drivers.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge py4dstem cupy cudatoolkit

```

--------------------------------

### Initialize VirtualImage

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Creates a VirtualImage instance with 2D data and an optional name. The data should be a NumPy ndarray.

```python
virtual_image = py4DSTEM.VirtualImage(data=np.zeros((10,10)), name='my_image')
```

--------------------------------

### DataCube Initialization

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Initializes a new DataCube instance for 4D-STEM data storage.

```APIDOC
## __init__

### Description
Creates a new DataCube instance for storing and processing 4D-STEM datasets.

### Parameters
- **data** (ndarray) - Required - The input data array.
- **name** (str) - Optional - The name of the datacube (default: 'datacube').
- **slicelabels** (bool | list) - Optional - Names for slices if the data is a stack.
- **calibration** (Calibration) - Optional - Calibration instance or 'pass' to attach to metadata.
```

--------------------------------

### Windows Anaconda Install for py4DSTEM with GPU Acceleration

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Installs py4DSTEM with GPU acceleration (cupy, cudatoolkit) on Windows using Anaconda. Requires an NVIDIA GPU and drivers.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge py4dstem cupy cudatoolkit
4conda install -c conda-forge pywin32

```

--------------------------------

### Create Array with Full Metadata

Source: https://py4dstem.readthedocs.io/en/latest/api/emd.html

Instantiate an Array with data, name, units, and detailed dimension calibrations including units and names.

```python
>>> ar = Array(
>>>     np.ones((20,20,256,256))Я,
>>>     name = 'test_array',
>>>     units = 'intensity',
>>>     dims = [
>>>         [0,5],
>>>         [0,5],
>>>         [0,0.01],
>>>         [0,0.01]
>>>     ],
>>>     dim_units = [
>>>         'nm',
>>>         'nm',
>>>         'A^-1',
>>>         'A^-1'
>>>     ],
>>>     dim_names = [
>>>         'rx',
>>>         'ry',
>>>         'qx',
>>>         'qy'
>>>     ],
>>> )
```

--------------------------------

### Linux Anaconda Install for py4DSTEM ML-AI CPU

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Installs py4DSTEM with ML-AI features (tensorflow, tensorflow-addons, crystal4D) for CPU-only on Linux using Anaconda. Note the specific versions for tensorflow and tensorflow-addons.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge py4dstem
4pip install tensorflow==2.4.1 tensorflow-addons<=0.14 crystal4D

```

--------------------------------

### Windows Anaconda Install for py4DSTEM ML-AI CPU

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Installs py4DSTEM with ML-AI features (tensorflow, tensorflow-addons, crystal4D) for CPU-only on Windows using Anaconda. Note the specific versions for tensorflow and tensorflow-addons.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge py4dstem
4pip install tensorflow==2.4.1 tensorflow-addons<=0.14 crystal4D
5conda install -c conda-forge pywin32

```

--------------------------------

### py4DSTEM.process.wholepatternfit.wp_models.GaussianBackground Methods

Source: https://py4dstem.readthedocs.io/en/latest/genindex.html

This section lists the methods available for the py4DSTEM.process.wholepatternfit.wp_models.GaussianBackground class.

```APIDOC
## py4DSTEM.process.wholepatternfit.wp_models.GaussianBackground Methods

### Description
Methods for modeling Gaussian background in whole pattern fitting.

### Methods
- `(py4DSTEM.process.wholepatternfit.wp_models.GaussianBackground method)`: Represents a Gaussian background method.
```

--------------------------------

### Linux Anaconda Install for py4DSTEM ML-AI GPU

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Installs py4DSTEM with ML-AI features (tensorflow, tensorflow-addons, crystal4D) and GPU acceleration (cupy, cudatoolkit) on Linux using Anaconda. Requires an NVIDIA GPU and drivers.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge py4dstem
4conda install -c conda-forge cupy cudatoolkit=11.0
5pip install tensorflow==2.4.1 tensorflow-addons<=0.14 crystal4D

```

--------------------------------

### py4DSTEM.process.wholepatternfit.wp_models.DCBackground Methods

Source: https://py4dstem.readthedocs.io/en/latest/genindex.html

This section lists the methods available for the py4DSTEM.process.wholepatternfit.wp_models.DCBackground class.

```APIDOC
## py4DSTEM.process.wholepatternfit.wp_models.DCBackground Methods

### Description
Methods for modeling DC background in whole pattern fitting.

### Methods
- `(py4DSTEM.process.wholepatternfit.wp_models.DCBackground method)`: Represents a DC background method.
```

--------------------------------

### Windows Anaconda Install for py4DSTEM ML-AI GPU

Source: https://py4dstem.readthedocs.io/en/latest/installation.html

Installs py4DSTEM with ML-AI features (tensorflow, tensorflow-addons, crystal4D) and GPU acceleration (cupy, cudatoolkit) on Windows using Anaconda. Requires an NVIDIA GPU and drivers.

```bash
1conda create -n py4dstem python=3.9
2conda activate py4dstem
3conda install -c conda-forge py4dstem
4conda install -c conda-forge cupy cudatoolkit=11.0
5pip install tensorflow==2.4.1 tensorflow-addons<=0.14 crystal4D
6conda install -c conda-forge pywin32

```

--------------------------------

### GET /get_class_image

Source: https://py4dstem.readthedocs.io/en/latest/api/process.html

Retrieves the scan position weights for a specific class.

```APIDOC
## GET /get_class_image

### Description
Get a single class, returning its scan position weights.

### Parameters
#### Path Parameters
- **i** (int) - Required - The class index

### Response
#### Success Response (200)
- **class_image** (shape (R_Nx,R_Ny) array of floats) - The weights of each scan position in this class
```

--------------------------------

### Initialize Calibration Instance

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Initializes a new Calibration instance. Optionally, a name and a root object can be provided.

```python
__init__(_name : str | None = 'calibration'_, _root : Root | None = None_)
```

--------------------------------

### Initialize Dynamical Matrix Cache

Source: https://py4dstem.readthedocs.io/en/latest/api/process.html

Constructor for the DynamicalMatrixCache class used in Bloch wave computations.

```python
_class _py4DSTEM.process.diffraction.crystal_bloch.DynamicalMatrixCache(_has_valid_cache: bool = False_, _cached_U_gmh: <built-in function array> = None_)_

__init__(_has_valid_cache : bool = False_, _cached_U_gmh : array | None = None_) → None
```

--------------------------------

### GET /get_class_BPs

Source: https://py4dstem.readthedocs.io/en/latest/api/process.html

Retrieves the Bragg peak weights for a specific class.

```APIDOC
## GET /get_class_BPs

### Description
Get a single class, returning its BP weights.

### Parameters
#### Path Parameters
- **i** (int) - Required - The class index

### Response
#### Success Response (200)
- **class_BPs** (length N_feat array of floats) - The weights of the N_feat Bragg peaks for this class
```

--------------------------------

### py4DSTEM.process.wholepatternfit.wp_models.ComplexOverlapKernelDiskLattice Methods

Source: https://py4dstem.readthedocs.io/en/latest/genindex.html

This section lists the methods available for the py4DSTEM.process.wholepatternfit.wp_models.ComplexOverlapKernelDiskLattice class.

```APIDOC
## py4DSTEM.process.wholepatternfit.wp_models.ComplexOverlapKernelDiskLattice Methods

### Description
Methods for modeling complex overlap in kernel disk lattices for whole pattern fitting.

### Methods
- `(py4DSTEM.process.wholepatternfit.wp_models.ComplexOverlapKernelDiskLattice method)`: Represents a complex overlap kernel disk lattice method.
```

--------------------------------

### Get Dimension Units

Source: https://py4dstem.readthedocs.io/en/latest/api/emd.html

Retrieves the units of the n'th dimension vector.

```python
get_dim_units(_n_)
    
Return the n’th dim vector units
```

--------------------------------

### Initialize Moire Lattice Model

Source: https://py4dstem.readthedocs.io/en/latest/api/process.html

Constructor for the Moire lattice model, defining lattice parameters and intensity linking behavior.

```python
__init__(_WPF_ , _lattice_a : SyntheticDiskLattice_, _lattice_b : SyntheticDiskLattice_, _intensity_0 : float_, _decorated_peaks : list | None = None_, _link_moire_disk_intensities : bool = False_, _link_disk_parameters : bool = True_, _refine_width : bool = True_, _edge_width : list | None = None_, _refine_radius : bool = True_, _disk_radius : list | None = None_, _name : str = 'Moire Lattice'_)
```

--------------------------------

### Get Dimension Name

Source: https://py4dstem.readthedocs.io/en/latest/api/emd.html

Retrieves the name of the n'th dimension vector.

```python
get_dim_name(_n_)
    
Get the n’th dim vector name
```

--------------------------------

### py4DSTEM.process.wholepatternfit.wp_models.SyntheticDiskLattice Methods

Source: https://py4dstem.readthedocs.io/en/latest/genindex.html

This section lists the methods available for the py4DSTEM.process.wholepatternfit.wp_models.SyntheticDiskLattice class.

```APIDOC
## py4DSTEM.process.wholepatternfit.wp_models.SyntheticDiskLattice Methods

### Description
Methods for modeling synthetic disk lattices in whole pattern fitting.

### Methods
- `(py4DSTEM.process.wholepatternfit.wp_models.SyntheticDiskLattice method)`: Represents a synthetic disk lattice method.
```

--------------------------------

### GET /process/utils/linear_interpolation_1D

Source: https://py4dstem.readthedocs.io/en/latest/api/process.html

Calculates the 1D linear interpolation of an array at a specific position.

```APIDOC
## GET /process/utils/linear_interpolation_1D

### Description
Calculates the 1D linear interpolation of array ar at position x using the two nearest elements.

### Method
GET

### Endpoint
py4DSTEM.process.utils.utils.linear_interpolation_1D(ar, x)
```

--------------------------------

### get_initial_classes_from_images

Source: https://py4dstem.readthedocs.io/en/latest/api/process.html

Initializes classes based on user-provided class images. This method allows for direct specification of expected phase patterns.

```APIDOC
## POST /api/classes/initial/images

### Description
Populate the initial classes using a set of user-defined class images.

### Method
POST

### Endpoint
/api/classes/initial/images

### Parameters
#### Request Body
- **class_images** (ndarray) - Required - Must have shape (R_Nx, R_Ny, N_c), where N_c is the number of classes, and class_images[:,:,i] is the image of class i.

### Request Example
{
  "class_images": [[[1.0, 0.0], [0.0, 0.0]], [[0.0, 1.0], [0.0, 0.0]]]
}

### Response
#### Success Response (200)
- **classes** (list) - A list of identified classes.
- **W** (ndarray) - The initial class matrix.
- **H** (ndarray) - The initial coefficient matrix.

#### Response Example
{
  "classes": [
    {"id": 0, "bragg_peaks": [1, 5, 10]},
    {"id": 1, "bragg_peaks": [2, 6, 11]}
  ],
  "W": [[1.0, 0.0], [0.0, 1.0], ...],
  "H": [[0.5, 0.8, ...]]
}
```

--------------------------------

### Dimension Management

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Methods to get and set dimension vectors, names, and units.

```APIDOC
## Dimension Management

### Methods
- **set_dim(n, dim, units=None, name=None)**: Sets the n'th dimension vector.
- **set_dim_name(n, name)**: Sets the name of the n'th dimension.
- **set_dim_units(n, units)**: Sets the units of the n'th dimension.
- **get_dim(n)**: Returns the n'th dimension vector.
- **get_dim_name(n)**: Returns the name of the n'th dimension.
- **get_dim_units(n)**: Returns the units of the n'th dimension.
```

--------------------------------

### Get Nice Spacing

Source: https://py4dstem.readthedocs.io/en/latest/api/visualize.html

Calculates a suitable spacing for gridlines, scalebars, etc.

```APIDOC
## get_nice_spacing

### Description
Get a nice distance for gridlines, scalebars, etc.

### Method
(Utility function)

### Endpoint
N/A (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Returns
A 3-tuple containing:
- **spacing_units** (float): the spacing in real units
- **spacing_pixels** (float): the spacing in pixels
- **spacing** (float): the leading digits of the spacing

### Return Type
(3-tuple)
```

--------------------------------

### Display object tree with options

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Display the object tree. Use the 'show' argument to control whether the tree is displayed from the root or the current node.

```python
>>> .tree()
>>> .tree(show=True)
>>> .tree(show=False)

```

--------------------------------

### GET /process/utils/get_voronoi_vertices

Source: https://py4dstem.readthedocs.io/en/latest/api/process.html

Extracts vertex positions for Voronoi regions from a scipy Voronoi instance.

```APIDOC
## GET /process/utils/get_voronoi_vertices

### Description
From a scipy.spatial.Voronoi instance, return a list of ndarrays, where each array is shape (N,2) and contains the (x,y) positions of the vertices of a voronoi region.

### Method
GET

### Endpoint
py4DSTEM.process.utils.utils.get_voronoi_vertices(voronoi, nx, ny, dist=10)

### Parameters
#### Path Parameters
- **voronoi** (scipy.spatial.Voronoi) - Required - The voronoi tesselation
- **nx** (int) - Required - The x field-of-view of the tesselated region
- **ny** (int) - Required - The y field-of-view of the tesselated region
- **dist** (float) - Optional - Place new vertices by extending new voronoi edges outside the frame

### Response
#### Success Response (200)
- **vertices** (list of ndarrays) - The (x,y) coords of the vertices of each voronoi region
```

--------------------------------

### py4DSTEM.process.wholepatternfit.wp_models.WPFModel Methods

Source: https://py4dstem.readthedocs.io/en/latest/genindex.html

This section lists the methods available for the py4DSTEM.process.wholepatternfit.wp_models.WPFModel class.

```APIDOC
## py4DSTEM.process.wholepatternfit.wp_models.WPFModel Methods

### Description
Base class for whole pattern fitting models.

### Methods
- `(py4DSTEM.process.wholepatternfit.wp_models.WPFModel method)`: Represents a whole pattern fitting model.
```

--------------------------------

### Basic Array Visualization

Source: https://py4dstem.readthedocs.io/en/latest/api/py4DSTEM.html

The simplest usage of the show function to display a 2D array.

```python
>>> show(ar)
```

--------------------------------

### GET /get_candidate_class

Source: https://py4dstem.readthedocs.io/en/latest/api/process.html

Retrieves both BP weights and scan position weights for a candidate class.

```APIDOC
## GET /get_candidate_class

### Description
Get a single candidate class, returning both its BP weights and scan position weights.

### Parameters
#### Path Parameters
- **i** (int) - Required - The class index

### Response
#### Success Response (200)
- **class_BPs** (length N_feat array of floats) - The weights of the N_feat Bragg peaks for this class
- **class_image** (shape (R_Nx,R_Ny) array of floats) - The weights of each scan position in this class
```

--------------------------------

### Create Basic Array Instance

Source: https://py4dstem.readthedocs.io/en/latest/api/emd.html

Instantiate an Array with just the numpy data. Dimensions will be automatically populated with pixel units.

```python
>>> ar = Array(np.ones((20,20,256,256)))
```

--------------------------------

### GET /get_class

Source: https://py4dstem.readthedocs.io/en/latest/api/process.html

Retrieves the BP weights and scan position weights for a specific class.

```APIDOC
## GET /get_class

### Description
Get a single class, returning both its BP weights and scan position weights.

### Method
GET

### Endpoint
/get_class

### Parameters
#### Query Parameters
- **i** (int) - Required - The class index

### Response
#### Success Response (200)
- **data** (tuple) - A 2-tuple containing BP weights and scan position weights
```

--------------------------------

### GET _get_probe_kernel_edge_gaussian

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Creates a cross-correlation kernel from the probe, subtracting a gaussian from the normalized probe.

```APIDOC
## GET _get_probe_kernel_edge_gaussian

### Description
Creates a cross-correlation kernel from the probe, subtracting a gaussian from the normalized probe such that the kernel integrates to zero, then shifting the center of the probe to the array corners.

### Parameters
#### Request Body
- **probe** (ndarray) - Required - The diffraction pattern corresponding to the probe over vacuum
- **sigma** (float) - Required - The width of the gaussian to subtract, relative to the standard deviation of the probe
- **origin** (2-tuple) - Optional - The origin of diffraction space
- **bilinear** (bool) - Required - By default probe is shifted via a Fourier transform. Setting this to True overrides it and uses bilinear shifting.

### Response
#### Success Response (200)
- **kernel** (ndarray) - The cross-correlation kernel
```

--------------------------------

### Probe Class Initialization

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Initializes a Probe object with vacuum probe data and an optional name.

```APIDOC
## Probe Class

### Description
Stores a vacuum probe and its associated cross-correlation kernel.

### Method
`__init__`

### Parameters
- **data** (np.ndarray) - Required - 2D or 3D numpy array representing the vacuum probe or vacuum probe + kernel.
- **name** (str) - Optional - A name for the probe instance. Defaults to 'probe'.
```

--------------------------------

### PointList Initialization and Basic Operations

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

This section covers the initialization of a PointList object and fundamental methods for data manipulation.

```APIDOC
## PointList Class

### Description
A wrapper around structured numpy arrays, with read/write functionality in/out of EMD formatted HDF5 files.

### Methods

#### `__init__(self, data: ndarray, name: str | None = 'pointlist')`

> Instantiate a PointList.

**Parameters:**

*   **data** (_structured numpy ndarray_) – the data; the dtype of this array will specify the fields of the PointList.
*   **name** (_str_) – name for the PointList

**Returns:**

a PointList instance

#### `add(self, data)`

Appends a numpy structured array. Its dtypes must agree with the existing data.

#### `remove(self, mask)`

Removes points wherever mask==True

#### `sort(self, field, order='ascending')`

Sorts the point list according to field, which must be a field in self.dtype. order should be ‘descending’ or ‘ascending’.

#### `copy(self, name=None)`

Returns a copy of the PointList. If name=None, sets to {name}_copy

#### `add_fields(self, new_fields, name='')`

Creates a copy of the PointList, but with additional fields given by new_fields.

**Parameters:**

*   **new_fields** – a list of 2-tuples, (‘name’, dtype)
*   **name** – a name for the new pointlist

#### `add_data_by_field(self, data, fields=None)`

Add a list of data arrays to the PointList, in the fields given by fields. If fields is not specified, assumes the data arrays are in the same order as self.fields

**Parameters:**

*   **data** (_list_) – arrays of data to add to each field
```

--------------------------------

### GET _get_probe_kernel_flat

Source: https://py4dstem.readthedocs.io/en/latest/api/classes.html

Creates a cross-correlation kernel from the vacuum probe by normalizing and shifting the center.

```APIDOC
## GET _get_probe_kernel_flat

### Description
Creates a cross-correlation kernel from the vacuum probe by normalizing and shifting the center.

### Parameters
#### Request Body
- **probe** (2d array) - Required - The vacuum probe
- **origin** (2-tuple) - Optional - The origin of diffraction space. If not specified, finds the origin using get_probe_radius.
- **bilinear** (bool) - Optional - By default probe is shifted via a Fourier transform. Setting this to True overrides it and uses bilinear shifting.

### Response
#### Success Response (200)
- **kernel** (ndarray) - The cross-correlation kernel corresponding to the probe, in real space
```
Tokens:
Raw