erlab.plotting.atoms

Plot atoms.

Classes and functions for plotting atoms and bonds in a crystal structure using matplotlib’s 3D plotting capabilities.

Some of the projection code was adapted from kwant.

Classes

CrystalProperty(atom_pos, avec[, offset, ...])

Crystal positions and bond geometry for three-dimensional plotting.

class erlab.plotting.atoms.CrystalProperty(atom_pos, avec, offset=(0.0, 0.0, 0.0), radii=None, colors=None, repeat=(1, 1, 1), bounds=None, mask=None, r_factor=0.4)

Bases: object

Crystal positions and bond geometry for three-dimensional plotting.

Positions, lattice vectors, offsets, bounds, atomic radii, and bond lengths must use one consistent length unit. The class does not assign or convert physical units.

classmethod from_fractional(frac_pos, avec, *args, **kwargs)

Create plotting properties from fractional atomic coordinates.

Parameters:

• frac_pos (dict[str, list[tuple[float, float, float]]]) – Mapping from each species name to its fractional coordinates (u, v, w).

• avec (ndarray[tuple[Any, ...], dtype[float64]]) – Direct-lattice vectors with shape (3, 3). Vectors are stored by row. Their unit becomes the unit of the Cartesian atom positions.

• *args – Additional arguments passed to the CrystalProperty constructor.

• **kwargs – Additional arguments passed to the CrystalProperty constructor.

Returns:

CrystalProperty – New instance whose Cartesian positions are u * avec[0] + v * avec[1] + w * avec[2]. The input mapping is not modified.

property bounds: list[tuple[float, float]]

Bounds for the x, y, and z coordinates, in that order.

An unspecified direction has bounds (-inf, inf).

property atoms: list[str]

Species names in the insertion order of the input position mapping.

property atom_pos: dict[str, ndarray[tuple[Any, ...], dtype[float64]]]

Repeated and filtered Cartesian positions for each species.

The calculation applies repeat, offset, bounds, and mask, and removes duplicate positions after rounding to five decimal places. The result is cached after its first use.

clear_bonds()

Remove all bond segments and their stored plot styles in place.

add_bonds(atom1, atom2, min_length=0.0, max_length=2.6, linewidth=0.25, color=None)

Add bonds between two species.

Parameters:

• atom1 (str) – Species names in atom_pos.

• atom2 (str) – Species names in atom_pos.

• min_length (float, default: 0.0) – Inclusive center-to-center distance range. Values use the same unit as the atom positions.

• max_length (float, default: 2.6) – Inclusive center-to-center distance range. Values use the same unit as the atom positions.

• linewidth (float, default: 0.25) – Stored bond width. With scale_bonds=True in plot(), this value is interpreted in position-coordinate units. Otherwise, Matplotlib interprets it as a line width in points.

• color (str | tuple[float, ...] | None, default: None) – Matplotlib color for the new bonds. If omitted, use "#b2b2b2".

Notes

This method appends to existing bonds. Each visible segment is shortened at both ends by the corresponding atomic radius multiplied by r_factor.

plot(ax=None, scale_bonds=True, scale_atoms=True, clean_axes=True, bond_kw=None, atom_kw=None)

Plot the crystal structure.

Parameters:

• ax (Axes3D | None, default: None) – A 3D axes object to plot the crystal on. If not provided, add_subplot will be called on the current figure.

• scale_bonds (bool, default: True) – Whether to scale the bond linewidths based on the distance from the camera, by default True

• scale_atoms (bool, default: True) – Whether to scale the atom sizes based on the distance from the camera, by default True

• clean_axes (bool, default: True) – Whether to clean the axes by removing the background and grid, setting pane color, and removing the margins, by default True

• bond_kw (dict | None, default: None) – Keyword arguments passed onto Bond3DCollection

• atom_kw (dict | None, default: None) – Keyword arguments passed onto mpl_toolkits.mplot3d.Axes3D.scatter used to plot the atoms.