DifferentialDisplacement

class atomman.defect.DifferentialDisplacement(system0: System, system1: System, neighbors: NeighborList | None = None, cutoff: float | None = None, reference: int = 1)

Bases: object

property arrowcenters: ndarray | None

The identified center positions for the ddvectors.

Type:

numpy.array or None

property arrowuvectors: ndarray | None

The unit vectors between all pairs of atoms for which the ddvectors have been computed.

Type:

numpy.array or None

property ddvectors: ndarray | None

The computed differential displacement vectors.

Type:

numpy.array or None

property neighbors: NeighborList

The list of neighbors identified for the reference system.

Type:

atomman.NeighborList

plot(component: str | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | bytes | _NestedSequence[bool | int | float | complex | str | bytes], ddmax: float | None, plotxaxis: str | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | bytes | _NestedSequence[bool | int | float | complex | str | bytes] = 'x', plotyaxis: str | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | bytes | _NestedSequence[bool | int | float | complex | str | bytes] = 'y', xlim: tuple | None = None, ylim: tuple | None = None, zlim: tuple | None = None, arrowscale: float = 1, arrowwidth: float = 0.005, use0z: bool = False, atomcolor: str | list | None = None, atomcmap: str | list | None = None, atomsize: float = 0.5, figsize: int = 10, matplotlib_axes: axes | None = None) → figure | None

Creates a matplotlib figure of a differential displacement map. Atom positions are represented as circles, while the selected components of the differential displacement vectors are plotted as arrows.

Parameters:

  • component (str or array-like object) – Indicates the component(s) of the differential displacement to plot. Values of ‘x’, ‘y’, or ‘z’ will plot the component along that Cartesian direction. A value of ‘projection’ will plot the differential displacement vectors as projected onto the plotting plane, thereby showing the two components perpendicular to the line direction. If a 3D vector is given, then the component parallel to that direction will be used.

  • ddmax (float or None) – The maximum differential displacement value allowed. Values will be kept between +-ddmax by wrapping values with larger absolute values around by adding/subtracting 2*ddmax. Typically, this is set to be |b|/2, but can be defect-specific. For instance, fcc a/2<110> dislocations and basal hcp dislocations are typically plotted with ddmax=|b|/4. If set to None, then no wrapping is done.

  • plotxaxis (str or array-like object, optional) – Indicates the Cartesian direction associated with the system’s atomic coordinates to align with the plotting x-axis. Values are either 3D unit vectors, or strings ‘x’, ‘y’, or ‘z’ for the Cartesian axes directions. plotxaxis and plotyaxis must be orthogonal. Default value is ‘x’ = [1, 0, 0].

  • plotyaxis (str or array-like object, optional) – Indicates the Cartesian direction associated with the system’s atomic coordinates to align with the plotting y-axis. Values are either 3D unit vectors, or strings ‘x’, ‘y’, or ‘z’ for the Cartesian axes directions. plotxaxis and plotyaxis must be orthogonal. Default value is ‘y’ = [0, 1, 0].

  • xlim (tuple, optional) – The minimum and maximum coordinates along the plotting x-axis to include in the fit. Values are taken in the specified length_unit. If not given, then the limits are set based on min and max atomic coordinates along the plotting axis.

  • ylim (tuple, optional) – The minimum and maximum coordinates along the plotting y-axis to include in the fit. Values are taken in the specified length_unit. If not given, then the limits are set based on min and max atomic coordinates along the plotting axis.

  • zlim (tuple, optional) – The minimum and maximum coordinates normal to the plotting axes (i.e. plotxaxis X plotyaxis) to include in the fit. Values are taken in the specified length_unit. The optimum zlim should encompass only a single periodic slice. If not given, then the limits are set based on min and max atomic coordinates along the axis.

  • arrowscale (float, optional) – Scaling factor for the magnitude of the differential displacement arrows. Default value is 1: no scaling, vectors are in units of length. For major components, this is often set such that the max differential displacement component after wrapping (see ddmax) is scaled to the distance between the atom pairs in the plot. For minor components, this is often set to a large value simply to make the components visible.

  • arrowwidth (float, optional) – Scaling factor to use for the width of the plotted arrows. Default value is 0.005 = 1/200.

  • use0z (bool, optional) – If False (default), the z coordinates from the reference system will be used for zlim and atomcmap colors. If True, the z coordinates will be used from system0 even if system1 is the reference system.

  • atomcolor (str or list, optional) – Matplotlib color name(s) to use to display the atoms. If str, that color will be assigned to all atypes. If list, must give a color value or None for each atype. Default value (None) will use cmap instead. Note: atomcolor and atomcmap can be used together as long as exactly one color or cmap is given for each unique atype.

  • atomcmap (str or list, optional) – Matplotlib colormap name(s) to use to display the atoms. Atoms will be colored based on their initial positions and scaled using zlim. If str, that cmap will be assigned to all atypes. If list, must give a cmap value or None for each atype. Default value (None) will use ‘hsv’ cmap. Note: atomcolor and atomcmap can be used together as long as exactly one color or cmap is given for each unique atype.

  • atomsize (float, optional) – The circle radius size to use for the plotted atom positions in units of length. Default value is 0.5.

  • figsize (float or tuple, optional) – Specifies the size of the figure to create in inches. If a single value is given, it will be used for the figure’s width, and the height will be scaled based on the xlim and ylim values. Alternatively, both the width and height can be set by passing a tuple of two values, but the plot will not be guaranteed to be “regular” with respect to length dimensions.

  • matplotlib_axes (matplotlib.Axes.axes, optional) – An existing matplotlib axes object. If given, the differential displacement plot will be added to the specified axes of an existing figure. This allows for subplots to be constructed. Note that figsize will be ignored as the figure would have to be created beforehand and no automatic optimum scaling of the figure’s dimensions will occur.

Returns:

The generated figure. Not returned if matplotlib_axes is given.

Return type:

matplotlib.Figure

plot_with_nye(component: str | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | bytes | _NestedSequence[bool | int | float | complex | str | bytes], ddmax: float | None, strain: Strain, plotxaxis: str | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | bytes | _NestedSequence[bool | int | float | complex | str | bytes] = 'x', plotyaxis: str | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | bytes | _NestedSequence[bool | int | float | complex | str | bytes] = 'y', xlim: tuple | None = None, ylim: tuple | None = None, zlim: tuple | None = None, vlim: tuple | None = None, cmap: str = 'bwr', arrowscale: float = 1, arrowwidth: float = 0.005, use0z: bool = False, atomcolor: str | list | None = None, atomcmap: str | list | None = None, atomsize: float = 0.5, figsize: int = 10, xbins: int = 200, ybins: int = 200, colorbar: bool = True, fill_value: float = nan, matplotlib_axes: axes | None = None) → Tuple[float, figure]

Utility function for simple combined dd-Nye plots. Note that this method is currently limited to components and plot axis values of ‘x’, ‘y’, and ‘z’. This could be generalized in the future, if there is interest…

Parameters:

  • component (str or array-like object) – Indicates the component(s) of the differential displacement to plot. Values of ‘x’, ‘y’, or ‘z’ will plot the component along that Cartesian direction. A value of ‘projection’ will plot the differential displacement vectors as projected onto the plotting plane, thereby showing the two components perpendicular to the line direction. If a 3D vector is given, then the component parallel to that direction will be used.

  • ddmax (float or None) – The maximum differential displacement value allowed. Values will be kept between +-ddmax by wrapping values with larger absolute values around by adding/subtracting 2*ddmax. Typically, this is set to be |b|/2, but can be defect-specific. For instance, fcc a/2<110> dislocations and basal hcp dislocations are typically plotted with ddmax=|b|/4. If set to None, then no wrapping is done.

  • strain (atomman.defect.Strain) – A strain object computed for the system in question. This will be used to compute the Nye tensor values that are included in the plot.

  • plotxaxis (str or array-like object, optional) – Indicates the Cartesian direction associated with the system’s atomic coordinates to align with the plotting x-axis. Values are either 3D unit vectors, or strings ‘x’, ‘y’, or ‘z’ for the Cartesian axes directions. plotxaxis and plotyaxis must be orthogonal. Default value is ‘x’ = [1, 0, 0].

  • plotyaxis (str or array-like object, optional) – Indicates the Cartesian direction associated with the system’s atomic coordinates to align with the plotting y-axis. Values are either 3D unit vectors, or strings ‘x’, ‘y’, or ‘z’ for the Cartesian axes directions. plotxaxis and plotyaxis must be orthogonal. Default value is ‘y’ = [0, 1, 0].

  • xlim (tuple, optional) – The minimum and maximum coordinates along the plotting x-axis to include in the fit. Values are taken in the specified length_unit. If not given, then the limits are set based on min and max atomic coordinates along the plotting axis.

  • ylim (tuple, optional) – The minimum and maximum coordinates along the plotting y-axis to include in the fit. Values are taken in the specified length_unit. If not given, then the limits are set based on min and max atomic coordinates along the plotting axis.

  • zlim (tuple, optional) – The minimum and maximum coordinates normal to the plotting axes (i.e. plotxaxis X plotyaxis) to include in the fit. Values are taken in the specified length_unit. The optimum zlim should encompass only a single periodic slice. If not given, then the limits are set based on min and max atomic coordinates along the axis.

  • vlim (tuple, optional) – Range limits for the Nye tensor contour plot. If not given, will be determined by the range of the Nye tensor component values.

  • cmap (str, optional) – The matplotlib colormap to use for the Nye tensor contour plot. Default value is ‘bwr’.

  • arrowscale (float, optional) – Scaling factor for the magnitude of the differential displacement arrows. Default value is 1: no scaling, vectors are in units of length. For major components, this is often set such that the max differential displacement component after wrapping (see ddmax) is scaled to the distance between the atom pairs in the plot. For minor components, this is often set to a large value simply to make the components visible.

  • arrowwidth (float, optional) – Scaling factor to use for the width of the plotted arrows. Default value is 0.005 = 1/200.

  • use0z (bool, optional) – If False (default), the z coordinates from the reference system will be used for zlim and atomcmap colors. If True, the z coordinates will be used from system0 even if system1 is the reference system.

  • atomcolor (str or list, optional) – Matplotlib color name(s) to use to display the atoms. If str, that color will be assigned to all atypes. If list, must give a color value or None for each atype. Default value (None) will use cmap instead. Note: atomcolor and atomcmap can be used together as long as exactly one color or cmap is given for each unique atype.

  • atomcmap (str or list, optional) – Matplotlib colormap name(s) to use to display the atoms. Atoms will be colored based on their initial positions and scaled using zlim. If str, that cmap will be assigned to all atypes. If list, must give a cmap value or None for each atype. Default value (None) will use ‘hsv’ cmap. Note: atomcolor and atomcmap can be used together as long as exactly one color or cmap is given for each unique atype.

  • atomsize (float, optional) – The circle radius size to use for the plotted atom positions in units of length. Default value is 0.5.

  • figsize (float or tuple, optional) – Specifies the size of the figure to create in inches. If a single value is given, it will be used for the figure’s width, and the height will be scaled based on the xlim and ylim values. Alternatively, both the width and height can be set by passing a tuple of two values, but the plot will not be guaranteed to be “regular” with respect to length dimensions.

  • xbins (int, optional) – Specifies the number of interpolation bins to use along the plotting x-axis. Default value is 200.

  • ybins (int, optional) – Specifies the number of interpolation bins to use along the plotting y-axis. Default value is 200.

  • colorbar (bool, optional) – If True (default) a colorbar will be added to the plot.

  • fill_value (float, optional) – Value used to fill in for grid points failed to interpolate in the fit. If not given, then the default is np.nan, which may cause an error in plotting for too narrow xlim and ylim settings.

  • matplotlib_axes (matplotlib.Axes.axes, optional) – An existing matplotlib axes object. If given, the differential displacement plot will be added to the specified axes of an existing figure. This allows for subplots to be constructed. Note that figsize will be ignored as the figure would have to be created beforehand and no automatic optimum scaling of the figure’s dimensions will occur.

Returns:

  • float – The integer sum of the Nye tensor over the plotted area.

  • matplotlib.Figure – The generated figure.

property reference: int

Indicates which system (0 or 1) is used as the reference.

Type:

int

solve(system0: System | None = None, system1: System | None = None, neighbors: NeighborList | None = None, cutoff: float | None = None, reference: int | None = None)

Solves the differential displacement vectors.

Parameters:

  • system0 (atomman.system, optional) – The base/reference system to use.

  • system1 (atomman.system, optional) – The defect/current system to use.

  • neighbors (atomman.NeighborList, optional) – The neighbor list to use.

  • cutoff (float, optional) – Cutoff distance for computing a neighbor list. If reference = 0, then system_0 will be used to generate the list. If reference = 1, then system_1 will be used to generate the list.

  • reference (int, optional) – Indicates which of the two systems should be used for the plotting reference: 0 or 1. If 0, then system0’s atomic positions will be used for the calculation and neighbors should be for system0. If 1, then system1’s atomic positions will be used for the calculation and neighbors should be for system1. Default value is whatever was set when the object was initialized.

property system0: System

The defect-free base system.

Type:

atomman.System

property system1: System

The defect containing system.

Type:

atomman.System