plot

Functions and attributes

atomman.plot.get_prop_values(system: System, prop_name: str, prop_index: int | tuple | None = None, prop_magnitude: bool = False, prop: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, prop_unit: str | None = None) Tuple[str, ndarray]

Utility method to manage the prop parameters used by the various plotting tools.

Parameters:
  • system (atomman.System) – The system with the per-atom property that you want to plot.

  • prop_name (str) – The name of the per-atom property that you want to plot.

  • prop_index (int or tuple, optional) – Specifies which component of a multidimensional property to plot. Not needed if the property is scalar.

  • prop_magnitude (bool, optional) – If True, plots the per-atom magnitude of a vector property. Cannot be combined with index. Default value is False.

  • prop (array-like object, optional) – Values for the per-atom property to plot. If not given, values will be taken as the “name” property of system.

  • prop_unit (str or None, optional) – The units to use for the property value being plotted. Default value is None, in which no unit conversion is applied.

Returns:

  • prop_name (str) – The updated property name.

  • prop (np.ndarray) – The per-atom property values.

atomman.plot.interpolate_contour(system: System, prop_name: str, prop_index: int | tuple | None = None, prop_magnitude: bool = False, prop: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, plotxaxis: str = 'x', plotyaxis: str = 'y', xlim: tuple | None = None, ylim: tuple | None = None, zlim: tuple | None = None, vlim: tuple | None = None, xbins: int = 200, ybins: int = 200, dots: bool = True, colorbar: bool = True, vzero: bool = True, title: bool | str = True, length_unit: str = 'angstrom', prop_unit: str | None = None, cmap: str = 'jet', fill_value: float = nan, figsize: int | float | tuple | None = None, matplotlib_axes: axes | None = None) Tuple[float, float, figure | None]

Creates a contour plot of a system’s per-atom properties by interpolating properties between atoms.

Parameters:
  • system (atomman.System) – The system with the per-atom property that you want to plot.

  • propname (str) – The name of the per-atom property that you want to plot.

  • prop (array-like object, optional) – Values for the per-atom property to plot. If not given, values will be taken as the “name” property of system.

  • propindex (int or tuple, optional) – Specifies which component of a multidimensional property to plot. Not needed if the property is scalar.

  • magnitude (bool, optional) – If True, plots the per-atom magnitude of a vector property. Cannot be combined with index. Default value is False.

  • 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. If not given, then the limits are set based on min and max atomic coordinates along the axis.

  • vlim (tuple, optional) – Allows for the color range to be specified. If not give, the range will be auto-selected based on the vzero parameter.

  • 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.

  • dots (bool, optional) – If True, then the positions of the atoms are shown as circles. Default value is True.

  • vzero (bool, optional) – Specifies how to auto-select the vlim values if vlim is not directly given. vzero=True (default) will center the range around 0, i.e. vlim[0] = -vlim[1]. vzero=False will select vlim[0] and vlim[1] independently based on the the property values.

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

  • title (bool or str, optional) – If True (default), a plot title will be added matching the property name plus index/magnitude info. If False, no title will be used. If a string is given, then that will be used instead of the property name.

  • length_unit (str, optional) – The units of length to use for the plotting x- and y-axes. Default value is ‘angstrom’.

  • prop_unit (str or None, optional) – The units to use for the property value being plotted. Default value is None, in which no unit conversion is applied.

  • cmap (str, optional) – The name of the matplotlib colormap to use. Default value is ‘jet’.

  • 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.

  • figsize (int, float or tuple, optional) – Specifies the size of the figure to create in inches. Note the plot itself is always made based on an equal aspect ratio of the coordinates. If a single value is given, then the size of the larger dimension will be set to this and the smaller dimension will be scaled accordingly. The width or height can be directly set to a specific value by giving (w, None) or (None, w), respectively. If you give values for both width and height the width value affects the size of the plot and height affects the size of the colorbar if one is included.

  • 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:

  • intsum (float) – The area integrated sum of the property over the plotted region.

  • avsum (float) – The average property value taken across all plotting bins.

  • figure (matplotlib.pyplot.figure) – The generated figure object is returned if matplotlib_axes is not given.

atomman.plot.values_to_hexcolors(values: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], cmap: str, minvalue: float | None = None, maxvalue: float | None = None, reverse: bool = False)

Takes an array of values and converts them to hex value numbers based on a colormap.

Parameters:
  • values (Array-like object) – The values to use as the basis for coloring.

  • cmap (str or matplotlib colormap) – The matplotlib colormap to use for identifying the colors.

  • minvalue (float or None, optional) – The minimum limit value to use for the color scale. If None (default) then the minimum value in values will be used.

  • maxvalue (float or None, optional) – The maximum limit value to use for the color scale. If None (default) then the maximum value in values will be used.

  • reverse (bool, optional) – If set to True the colormap will be reversed.