Visualization

Pictures

render

render(system, path=None, *, atoms=None, color=None, colormap='viridis', value_range=None, representation='spheres', radius=None, bonds=None, bond_radius=None, box=True, box_radius=None, box_color='black', polyhedra=None, polyhedra_alpha=0.6, polyhedra_color='atom', polyhedra_edges=None, mesh=None, mesh_color='#8fb0d8', mesh_alpha=1.0, dislocations=None, dislocation_radius=0.5, burgers_vectors=False, burgers_scale=3.0, burgers_radius=0.3, burgers_color=(0.7, 0.7, 0.7), vectors=None, vector_scale=1.0, vector_radius=0.5, vector_color=(1.0, 1.0, 0.0), vector_alignment='base', lines=None, line_radius=0.1, line_color=(0.6, 0.6, 0.6), wrap_lines=False, legend=False, **options)

A picture of a system: its atoms, optionally bonds, the box, Voronoi cells and a surface.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
path	str or path - like	A PNG file to write the picture to.	None
atoms	array_like	A boolean mask or indices of the atoms shown. Default all.	None
color	optional	The colors of the atoms, see atom_colors. Default those of the elements.	None
colormap	str	The colormap of values. Default viridis.	'viridis'
value_range	sequence of float64	The values at the two ends of the colormap.	None
representation	str	How atoms and bonds are drawn, one of REPRESENTATIONS: spheres, ball_and_stick, space_filling or licorice. It sets the defaults of radius, bonds and bond_radius. Default spheres.	'spheres'
radius	(float32, array_like or str)	Radius of the atoms in Å, one or (N,) each, or the radii of the elements: "display", "covalent" or "vdw". Default the radius column of the system where it has one, else that of the representation.	None
bonds	(float64, NeighborList, covalent or topology)	Bonds between the atoms closer than this cutoff in Å, the pairs of a neighbor list, covalent bonds (see covalent_bonds), or the bonds of the topology of the system, such as those of a LAMMPS data file or of mdapy.transform.create_bonds. Default that of the representation.	None
bond_radius	float32	Radius of the bonds in Å. Default that of the representation.	None
box	bool	Draw the edges of the box. Default True.	True
box_radius	float32	Radius of the edges in Å. Default a tenth of the median atom radius.	None
box_color	color	Color of the edges. Default black.	'black'
polyhedra	VoronoiPolyhedra	Voronoi cells to draw for the atoms shown.	None
polyhedra_alpha	float32	Opacity of the cells. Default 0.6.	0.6
polyhedra_color	(atom, edges)	Color the faces as their atoms, or by their number of edges. Default atom.	"atom"
polyhedra_edges	float32	Radius in Å of the edges of the cells; 0 draws none. Default a twentieth of the median atom radius.	None
mesh	TriangleMesh	A surface to draw, such as that of mdapy.analysis.SurfaceMesh. Triangles across a periodic boundary are cut there, the part outside moved in through the opposite face.	None
mesh_color	optional	One color for the surface, or (F, 3) colors of its triangles. Default light blue.	'#8fb0d8'
mesh_alpha	float32	Opacity of the surface. Default 1.	1.0
dislocations	DislocationResult	Dislocation lines to draw, such as those of mdapy.analysis.DislocationAnalysis: tubes in the color of the family of their Burgers vector, cut at the periodic boundaries, the parts outside moved in through the opposite faces.	None
dislocation_radius	float32	Radius of the tubes in Å. Default 0.5.	0.5
burgers_vectors	bool	Also draw the Burgers vector of each line: an arrow from the middle of the line along the vector in space. Default False.	False
burgers_scale	float32	Length of the arrows in units of the Burgers vectors. Default 3.	3.0
burgers_radius	float32	Radius of the shafts of the arrows in Å. Default 0.3.	0.3
burgers_color	optional	One color for the arrows, or "family" for the color of each line. Default light gray.	(0.7, 0.7, 0.7)
vectors	str or array_like	A column of three components, such as displacement, velocities or forces, or (N, 3) vectors: an arrow for each atom shown.	None
vector_scale	float32	Length of the arrows in units of the vectors; negative reverses them. Default 1.	1.0
vector_radius	float32	Radius of the shafts of the arrows in Å. Default 0.5.	0.5
vector_color	optional	One color for the arrows, or "atom" for the color of each atom. Default yellow.	(1.0, 1.0, 0.0)
vector_alignment	(base, center, head)	The point of the arrow at its atom: its tail, its middle or its tip. Default base.	"base"
lines	array_like or sequence of array_like	Polylines to draw, such as the paths of mdapy.analysis.trajectory_lines: (M, T, 3) points, or (T, 3) points of each line.	None
line_radius	float32	Radius of the lines in Å. Default 0.1.	0.1
line_color	optional	One color for the lines. Default gray.	(0.6, 0.6, 0.6)
wrap_lines	bool	Cut the lines at the periodic faces of the box and move the parts outside in through the opposite faces (True), or draw them as they are (False, default).	False
legend	(bool, str or mapping)	A legend at the top left, which needs matplotlib. True gives the names of the structures or elements of the atoms shown with their colors, or a bar with the values and the colormap of a column or of (N,) values. A string does the same with this title, as for values that have no name. A mapping gives its own names and colors. Default none.	False
**options	Any	The options of Scene.render, such as width, height, view, style, zoom, perspective and background.	{}

Returns:

Type	Description
ndarray	(height, width, 4) uint8 RGBA picture.

show_image

show_image(image, *, width=None)

Shows a picture in a notebook, such as Jupyter.

Parameters:

Name	Type	Description	Default
image	(ndarray, str or path - like)	A picture as mdapy.visualization.render returns it, (H, W, 4) uint8 uint8 with rows from the top, or a PNG or JPEG file.	required
width	int32	Its width on the page in pixels. Default the width of the picture.	None

Scene

Scene()

Spheres, cylinders and polygons to render.

Colors are sRGB from 0 to 1, lengths in Å.

add_spheres

add_spheres(centers, radii, colors, *, ids=None)

Adds spheres, such as atoms.

Parameters:

Name	Type	Description	Default
centers	array_like	(N, 3) float32 centers.	required
radii	float32 or array_like	Radius of every sphere, or (N,) each.	required
colors	array_like	One color, as three numbers from 0 to 1 or a name such as "#rrggbb", or (N, 3) each.	required
ids	array_like	(N,) int64 non-negative ids; outlines separate different ids. Default new ids, one per sphere.	None

add_cylinders

add_cylinders(starts, ends, radii, colors, *, ids=None)

Adds cylinders without caps, such as bonds.

Parameters:

Name	Type	Description	Default
starts	array_like	(M, 3) float32, the two ends of each cylinder.	required
ends	array_like	(M, 3) float32, the two ends of each cylinder.	required
radii	float32 or array_like	Radius of every cylinder, or (M,) each.	required
colors	array_like	One color, or (M, 3) each.	required
ids	array_like	(M,) int64 non-negative ids. Default new ids.	None

add_triangles

add_triangles(vertices, colors, *, alpha=1.0, ids=None)

Adds triangles, seen from both sides.

Parameters:

Name	Type	Description	Default
vertices	array_like	(T, 3, 3) float32, the corners of each triangle.	required
colors	array_like	One color, or (T, 3) each.	required
alpha	float32 or array_like	Opacity from 0 to 1 of every triangle, or (T,) each. Default 1.	1.0
ids	array_like	(T,) int64 non-negative ids. Default new ids.	None

add_polygons

add_polygons(vertices, corner_offsets, corners, colors, *, alpha=1.0, ids=None)

Adds convex polygons, such as the faces of Voronoi cells.

Parameters:

Name	Type	Description	Default
vertices	array_like	(V, 3) float32 points.	required
corner_offsets	array_like	(F + 1,) int64, the corners of polygon f are corners[corner_offsets[f]:corner_offsets[f + 1]].	required
corners	array_like	(C,) int64, the vertex of each corner, in order around its polygon.	required
colors	array_like	One color, or (F, 3) each.	required
alpha	float32 or array_like	Opacity of every polygon, or (F,) each. Default 1.	1.0
ids	array_like	(F,) int64 ids, the same for the triangles of a polygon. Default new ids.	None

add_box

add_box(box, *, radius=0.15, color=(0.0, 0.0, 0.0))

Adds the twelve edges of a box, with a sphere on each corner.

Parameters:

Name	Type	Description	Default
box	Box	The box.	required
radius	float32	Radius of the edges in Å. Default 0.15.	0.15
color	color	Default black.	(0.0, 0.0, 0.0)

render

render(path=None, *, width=1200, height=900, view='iso', up=None, perspective=False, fov=30.0, zoom=1.0, focus=None, span=None, aperture=0.0, focal_distance=None, style='matte', background='white', device='cpu', progress=None, cancel=None, **options)

Renders the scene, framed to fill the picture.

Parameters:

Name	Type	Description	Default
path	str or path - like	A PNG file to write the picture to.	None
width	int32	Size of the picture in pixels. Default 1200 by 900.	1200
height	int32	Size of the picture in pixels. Default 1200 by 900.	1200
view	str or array_like	One of top, bottom, front, back, left, right and iso, or the (3,) direction of view. Default iso.	'iso'
up	array_like	(3,) float32, the direction up in the picture. Default that of the view, or z.	None
perspective	bool	A perspective camera, or orthographic. Default False.	False
fov	float32	Vertical angle of view of a perspective camera in degrees. Default 30.	30.0
zoom	float32	Magnification of the framed scene. Default 1.	1.0
focus	array_like	(3,) float32, the point in Å at the middle of the picture. Default the middle of the scene.	None
span	float32	The length in Å the picture shows from its bottom to its top at the focus, in place of the framing and zoom. Default the scene framed.	None
aperture	float32	Radius in Å of the lens of a perspective camera: 0 for a picture sharp everywhere, more for depth of field. Default 0.	0.0
focal_distance	float32	Distance in Å from the camera along the view to the plane that stays sharp. Default that of the focus.	None
style	str	One of STYLES. Default matte.	'matte'
background	color or None	The background, or None for transparent. Default white.	'white'
device	(cpu, gpu, auto)	Trace the rays on the processor, on the GPU (see gpu_available), or on the GPU when there is one. Pictures on the GPU differ from those on the processor by rounding only. Default cpu.	"cpu"
progress	optional	Progress reports and cancellation.	None
cancel	optional	Progress reports and cancellation.	None
**options	Any	Settings of the style to change: ambient, diffuse, specular, shininess, metalness, key, highlight, fill, fill_intensity, base_light, srgb, ao_samples, ao_distance, ao_strength, shadows, shadow_strength, flat, toon_levels, outline_width, outline_depth, outline_color, fog, supersample, samples, bounces, light_size.	{}

Returns:

Type	Description
ndarray	(height, width, 4) uint8 RGBA picture, rows from the top.

write_png

write_png(path, image)

Writes an RGBA image to a PNG file.

Parameters:

Name	Type	Description	Default
path	str or path - like	The file.	required
image	ndarray	(H, W, 4) uint8 image, rows from the top.	required

gpu_available

gpu_available()

Whether pictures can be traced on a GPU: with Metal on macOS, with Vulkan on Linux, with Direct3D 12 on Windows.

Returns:

Type	Description
bool	True when a GPU is found and its shader compiles.

Colors, radii and bonds

atom_names

atom_names(system)

The names the colors and radii of the atoms go by.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required

Returns:

Type	Description
ndarray	(N,) str, their elements; atoms of a type without an element, or of the element X, named after their type: Type 1, Type 2 and so on.

atom_colors

atom_colors(system, color=None, *, colormap_name='viridis', value_range=None, elements=None)

(N, 3) sRGB colors of the atoms of a system.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
color	optional	None for the color column of the system where it has one, else the colors of the elements; one color for all; (N, 3) colors; a column name or (N,) values through the colormap; or a structure result, with structure and colors.	None
colormap_name	str	The colormap of values. Default viridis.	'viridis'
value_range	sequence of float64	The values at the two ends of the colormap.	None
elements	mapping	Colors of elements, such as {"Cu": "#d4875a"}, in place of their own, for the colors of the elements.	None

Returns:

Type	Description
ndarray	(N, 3) float64 colors from 0 to 1.

atom_radii

atom_radii(system, radius='display', *, elements=None, scale=1.0)

(N,) radii of the atoms of a system in Å.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
radius	str	The radii of the elements: "display", "covalent" or "vdw". Default display.	'display'
elements	mapping	Radii of elements in Å, such as {"C": 0.6}, in place of their own.	None
scale	float64	A factor of every radius. Default 1.	1.0

Returns:

Type	Description
ndarray	(N,) float64, the radius column of the system where it has one, else the radii of the elements, times the scale.

color_coding

color_coding(system, column, colormap='rainbow', value_range=None, *, atoms=None)

The atoms colored by the values of a column through a colormap, as OVITO's color coding.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
column	str	A column of numbers, a component such as "velocities.z" or an expression over the columns.	required
colormap	str	One of COLORMAPS. Default rainbow, as OVITO's.	'rainbow'
value_range	sequence of float64	(low, high) values of the two ends; by default the smallest and the largest finite value of the atoms colored.	None
atoms	array_like	A boolean mask or indices of the atoms to color; the others keep their colors. All by default.	None

Returns:

Type	Description
System	The system with the colors in its color column.

color_by_type

color_by_type(system, column, *, atoms=None)

The atoms colored by the value of a column, as OVITO's color by type: one of LABEL_COLORS for each value, in increasing order.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
column	str	A column of values of one component, such as "element", "type" or "cluster", or an expression over the columns.	required
atoms	array_like	A boolean mask or indices of the atoms to color; the others keep their colors. All by default.	None

Returns:

Type	Description
System	The system with the colors in its color column.

assign_color

assign_color(system, color, *, atoms=None)

The atoms in one color, as OVITO's assign color.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
color	str or sequence of float64	A color: three numbers from 0 to 1, a code "#rrggbb" or a name such as "red".	required
atoms	array_like	A boolean mask or indices of the atoms to color; the others keep their colors. All by default.	None

Returns:

Type	Description
System	The system with the colors in its color column.

colormap

colormap(values, name='viridis', value_range=None)

Colors of values through a colormap.

Parameters:

Name	Type	Description	Default
values	array_like	(N,) float32, the values.	required
name	str	One of COLORMAPS: rainbow, viridis, magma, jet, hot, blue_white_red and gray, as OVITO's color coding computes them, and plasma and coolwarm; labels, for discrete values, gives each value one of LABEL_COLORS, in increasing order. Default viridis.	'viridis'
value_range	sequence of float64	(low, high) values of the two ends; by default the smallest and the largest finite value. Values beyond take the color of their end, NaN that of the low end. Not for labels.	None

Returns:

Type	Description
ndarray	(N, 3) float64 sRGB colors from 0 to 1.

element_colors

element_colors(elements)

(N, 3) default sRGB colors of elements, or of atom types named Type k, from 0 to 1.

element_radii

element_radii(elements, kind='display')

(N,) radii of elements in Å.

Parameters:

Name	Type	Description	Default
elements	sequence of str	Chemical symbols.	required
kind	(display, covalent, vdw)	The radii pictures show, the covalent radii or the van der Waals radii. Default display.	"display"

Returns:

Type	Description
ndarray	(N,) float64 radii; elements without a value take 1.5 Å as covalent radius and 2 Å as van der Waals radius.

covalent_bonds

covalent_bonds(system)

The covalent bonds of a system: the pairs of atoms closer than the sum of their covalent radii and 0.45 Å.

Parameters:

Name	Type	Description	Default
system	System	The atoms, with an element column.	required

Returns:

Type	Description
NeighborList	The bonds, each pair both ways.

voxel_faces

voxel_faces(values, box)

The faces of the box cut into the cells of a grid over it, each with the value of the cell inside it, to show the grid as colors on the box.

Parameters:

Name	Type	Description	Default
values	array_like	(na, nb, nc) float64, the values of the cells of a grid that divides the box into na, nb and nc cells along its vectors a, b and c, such as the values of a SpatialBinning along all three.	required
box	Box	The box the grid divides.	required

Returns:

Name	Type	Description
mesh	TriangleMesh	Two triangles for each cell at each of the six faces of the box, their normals pointing out of a right-handed box.
face_values	ndarray	(F,) float64, the value of the cell of each triangle, for colors such as those of colormap.

Raises:

Type	Description
InvalidParameter	For values that are not a three-dimensional grid of finite numbers.

style_settings

style_settings(style='matte')

Every setting of a style: the options of Scene.render it changes, and the defaults of the others.

Parameters:

Name	Type	Description	Default
style	str	One of STYLES. Default matte.	'matte'

Returns:

Type	Description
dict	Each setting by name; ao_distance and outline_depth are None, which a picture takes from the radii of its atoms, and highlight None, the direction of the key light.

Raises:

Type	Description
InvalidParameter	For an unknown style.

Movies

write_movie

write_movie(path, pictures, *, fps=30)

Writes pictures as a movie with FFmpeg, which must be on the PATH.

Parameters:

Name	Type	Description	Default
path	str or path - like	The file; its suffix, such as .mp4, tells FFmpeg the format.	required
pictures	iterable of numpy.ndarray	(H, W, 3) or (H, W, 4) uint8 images of one size, rows from the top. They are taken one at a time, so a generator of pictures writes a long movie without holding them in memory.	required
fps	float64	Pictures per second. Default 30.	30

Raises:

Type	Description
FileNotFoundError	If FFmpeg is not on the PATH.
InvalidParameter	If fps is not positive, there are no pictures, a picture is not an image of the size of the first, or they hold more than 8192 x 4320 pixels.
CalculationFailed	If FFmpeg fails, with what it says.

Plots

plot

Plot templates for figures of journals, and plots of the results of mdapy. Needs matplotlib.

MM module-attribute

MM = 1 / 25.4

Inches per millimetre.

SINGLE module-attribute

SINGLE = 88 * MM

Width of a single column, in inches.

DOUBLE module-attribute

DOUBLE = 180 * MM

Width of a double column, in inches.

style

style()

A context in which matplotlib uses STYLE and COLORS.

figure

figure(width='single', height=None, *, nrows=1, ncols=1, **options)

A figure of the width of a column of a journal.

Parameters:

Name	Type	Description	Default
width	(single, double)	One column (88 mm), two (180 mm), or a width in mm. Default single.	"single"
height	float64	Height in mm. Default 3/4 of the width of one panel times the rows.	None
nrows	int32	Rows and columns of panels. Default 1.	1
ncols	int32	Rows and columns of panels. Default 1.	1
**options	Any	Passed to matplotlib.pyplot.subplots.	{}

Returns:

Type	Description
tuple	The figure and its axes, as matplotlib.pyplot.subplots returns.

panel_label

panel_label(ax, text, *, x=-0.12, y=1.02)

A bold lower-case label of a panel, at the top left of its axes.

save

save(fig, path, formats=('pdf', 'svg', 'png'))

Saves a figure in several formats: vector PDF and SVG with text kept as text, and PNG.

Parameters:

Name	Type	Description	Default
fig	Figure	The figure.	required
path	str or path - like	The file, its suffix replaced by each format.	required
formats	sequence of str	Default PDF, SVG and PNG.	('pdf', 'svg', 'png')

Returns:

Type	Description
list of pathlib.Path	The files written.

parity

parity(reference, predicted, *, ax=None, label='', unit='', scale=1.0, density=False, color=None)

A parity plot of predicted against reference values, with the root mean square error in the legend.

Parameters:

Name	Type	Description	Default
reference	array_like of float64	The values, of the same size.	required
predicted	array_like of float64	The values, of the same size.	required
ax	Axes	The axes; by default a new figure.	None
label	str	Name of the set in the legend.	''
unit	str	Unit of the error in the legend.	''
scale	float64	Factor of the error in the legend, such as 1000 for meV from eV.	1.0
density	bool	A hexagonal density map instead of points, for many values.	False
color	str	Color of the points.	None

Returns:

Type	Description
Axes	The axes.

scatter

scatter(system, x, y, *, ax=None, atoms=None, max_points=20000, color=None)

Two columns of the atoms against each other, a point for each atom.

Parameters:

Name	Type	Description	Default
system	System	The atoms.	required
x	str	A column of numbers, a component such as "positions.z" or an expression, as system[x] takes it; the labels of the axes.	required
y	str	A column of numbers, a component such as "positions.z" or an expression, as system[x] takes it; the labels of the axes.	required
ax	Axes	The axes; by default a new figure.	None
atoms	array_like	A boolean mask or indices of the atoms drawn. Default all of them.	None
max_points	int32	At most this many atoms drawn, picked at random with a fixed seed from those with finite values. Default 20000.	20000
color	str	Color of the points.	None

Returns:

Type	Description
Axes	The axes.

rdf

rdf(result, *, ax=None, partial=False)

The radial distribution function, and optionally its partial functions, of a mdapy.analysis.RadialDistributionResult.

structure_factor

structure_factor(result, *, ax=None)

The structure factor of a mdapy.analysis.StructureFactorResult.

bond_angles

bond_angles(result, *, ax=None)

The bond angle distribution of a mdapy.analysis.BondAngleResult.

msd

msd(result, *, timestep=1.0, ax=None, fit=None)

The mean squared displacement of a mdapy.analysis.DisplacementResult against time, with a fit of the diffusion coefficient.

Parameters:

Name	Type	Description	Default
result	DisplacementResult	The mean squared displacement.	required
timestep	float64	Time between frames in ps. Default 1.	1.0
ax	Axes	The axes.	None
fit	tuple of int32	(first, last) lags of a straight line fitted to the MSD, whose slope over 6 is the diffusion coefficient, shown in the legend.	None

Returns:

Type	Description
Axes	The axes.

stacking_fault

stacking_fault(result, *, ax=None, **options)

The generalized stacking fault energy of a mdapy.simulation.StackingFaultResult, in mJ/m²: a point for each slip computed, joined by a line. options go to ax.plot, such as label.

band_structure

band_structure(result, *, ax=None, color=None)

The phonon frequencies of a mdapy.lattice_dynamics.BandStructure along its path, with the special points marked and labeled.

Parameters:

Name	Type	Description	Default
result	BandStructure	The band structure; with connected=True each branch is one line through its crossings.	required
ax	Axes	The axes.	None
color	str	One color for every branch; by default each branch its own.	None

Returns:

Type	Description
Axes	The axes.

phonon_dos

phonon_dos(result, *, ax=None, projected=False)

The phonon density of states of a mdapy.lattice_dynamics.PhononDOS, frequencies upward, to put beside a band structure.

Parameters:

Name	Type	Description	Default
result	PhononDOS	The density of states.	required
ax	Axes	The axes.	None
projected	bool	Also the density of each atom of the cell, when computed.	False

Returns:

Type	Description
Axes	The axes.

structure_counts

structure_counts(result, *, ax=None)

The number of atoms of each type of a structure identification, in the colors of the types.

phase_diagram

phase_diagram(result, *, ax=None, labels=True)

The boundaries of the phases of a mdapy.simulation.BinaryPhaseDiagram: where each tie line ends, against the temperature, with the name of each phase in the middle of where it is the only one.

Parameters:

Name	Type	Description	Default
result	BinaryPhaseDiagram	The phase diagram.	required
ax	Axes	The axes.	None
labels	bool	Write the names of the phases. Default True.	True

Returns:

Type	Description
Axes	The axes.

pressure_temperature

pressure_temperature(result, *, ax=None, labels=True)

The boundaries of the phases of a mdapy.simulation.PressureTemperatureDiagram: the temperature of each against the pressure, with the name of each phase in the middle of where it is stable.

Parameters:

Name	Type	Description	Default
result	PressureTemperatureDiagram	The phase diagram.	required
ax	Axes	The axes.	None
labels	bool	Write the names of the phases. Default True.	True

Returns:

Type	Description
Axes	The axes.