ChemView

ChemView is a wrapper around Chemiscope for visualising ASE trajectories in Jupyter notebooks. It computes geometric and atomic properties from ase.Atoms objects and renders them as a linked scatter plot and 3-D structure viewer.

Clicking a point on the scatter plot loads the corresponding frame. The trajectory player at the bottom of the viewer animates through all frames.

from ase.io import read
from sparc.src.utils.chemview import ChemView

Load a trajectory

Any ASE-readable format works. Here we load a molecular dynamics trajectory stored as an ASE .traj file.

traj = read('../tests/iter_000000/00.dft/AseMD.traj', index=':')
print(f"Total frames: {len(traj)}")

Total frames: 54

Energy vs. frame

The simplest usage: plot potential energy as a function of frame index.

ChemView(traj, specs=["frame", "energy"], x="frame", y="energy")

Geometric properties with colour mapping

Multiple geometric specs can be combined. Here we plot the O–H distance against the H–O–H angle and colour points by energy. Auto-generated property names follow the pattern distance_i_j and angle_i_j_k.

ChemView(traj, specs=["frame", "energy", "distance:0,2", "distance:0,1", "angle:0,1,2"], x="distance_0_2", y="angle_0_1_2", color="energy")

Atom-level forces

Atom-level specs such as force_norm produce one value per atom per frame. Setting color_atoms="atom_index" colours atoms by their index.

ChemView(traj, specs=["frame", "energy", "force_norm"], x="frame", y="energy", color_atoms="atom_index")

Cell parameters

For periodic systems, lattice vector lengths and cell volume can be tracked across frames.

ChemView(traj, specs=["frame", "volume", "cell_a", "cell_b", "cell_c"], x="frame", y="volume")

Single structure

A single ase.Atoms object can be passed directly. Set plot=False to show only the 3-D viewer without a scatter plot.

from ase.build import molecule
water = molecule("H2O")
ChemView(water, specs=["x_pos", "y_pos", "z_pos"], plot=False)

Custom property names

When the same spec type appears more than once (e.g. two distances), use names to assign distinct keys. The size parameter scales scatter-plot points by a property value.

ChemView(traj, specs=["energy", "distance:0,1", "distance:0,2"], names=["energy", "d_OH1", "d_OH2"], x="d_OH1", y="d_OH2", size="energy", color="d_OH2")

Periodic bulk structure

ChemView also works with bulk periodic systems. Here we build a 2×2×2 FCC copper supercell and view the atomic positions.

from ase.lattice.cubic import FaceCenteredCubic

system = FaceCenteredCubic(directions=[[1,0,0],[0,1,0],[0,0,1]], symbol='Cu', size=(2,2,2), pbc=True)
ChemView(system, specs=["x_pos", "y_pos", "z_pos"], plot=False)