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.

from sparc.src.utils.chemview import ChemView

For worked examples, see the companion notebook below.

Interactive Demo

The widget below shows 264 frames of an ammonia borane (NH₃BH₃) trajectory. The scatter plot maps B–N distance (y-axis) vs frame index (x-axis), coloured by relative energy. Click any point to jump to that structure in the 3-D viewer; click any atom to highlight its environment.

Note

The viewer loads chemiscope.js from the internet. If it does not appear, check your connection or open the file directly: docs/source/_static/chemview_demo.html.

To regenerate the demo from a different trajectory:

python docs/source/generate_chemview_demo.py path/to/file.traj

Requirements

chemiscope and numpy must be installed alongside ASE:

pip install chemiscope numpy

Parameters

framesase.Atoms or list[ase.Atoms]

Input structures. A single Atoms object or a list. Must be non-empty.

specslist[str]

Properties to compute from the trajectory. See Property Specs below.

x, ystr

Property names for the scatter-plot axes. Defaults to "frame" and "energy" when those specs are present.

zstr

Optional third axis for 3-D scatter plots.

colorstr

Property used to colour scatter-plot points.

sizestr

Property used to scale point size.

symbolstr

Property used for point symbols.

nameslist[str]

Custom names for each spec. Length must match specs.

color_atoms"element" | "atom_index" | None

Colouring scheme for atoms in the 3-D viewer. Default: "element".

labelsbool

Show element symbols on atoms in the 3-D viewer.

show_indexbool

Clicking an atom centres the view on it and shows its properties in the info panel.

env_cutofffloat

Cutoff radius in Å for the atom environment sphere. Default: 3.5.

plotbool

Show the scatter-plot panel alongside the 3-D viewer. Default: True.

Property Specs

Each spec is a string passed in the specs list.

Structure-level

One value per frame.

Spec

Unit

Description

"frame"

Frame index (0, 1, 2, …)

"energy"

eV

Potential energy from atoms.get_potential_energy()

"distance:i,j"

Å

Distance between atoms i and j

"angle:i,j,k"

deg

Angle at atom j in the i-j-k triplet

"dihedral:i,j,k,l"

deg

Dihedral angle for the i-j-k-l quadruplet

"volume"

ų

Cell volume from atoms.get_volume()

"cell_a", "cell_b", "cell_c"

Å

Lattice vector lengths

"cell_alpha", "cell_beta", "cell_gamma"

deg

Cell angles

Atom-level

One value per atom per frame. All frames must have the same number of atoms.

Spec

Unit

Description

"x_pos", "y_pos", "z_pos"

Å

Cartesian position components

"symbol"

Element symbol

"atomic_number"

Atomic number

"force_x", "force_y", "force_z"

eV/Å

Force components

"force_norm"

eV/Å

Force magnitude

If forces are not available on a frame, values are filled with NaN.

Note

atom_index is always included as a default property and does not need to be listed in specs.

Auto-generated Names

When names is not provided, property keys are generated from the spec string:

"frame"            → "frame"
"energy"           → "energy"
"distance:0,4"     → "distance_0_4"
"angle:0,1,2"      → "angle_0_1_2"
"dihedral:0,1,2,3" → "dihedral_0_1_2_3"
"force_norm"       → "force_norm"

These keys are used for x, y, color, etc. When the same spec type appears more than once, use names to assign distinct keys.

Constraints

  • All frames must contain the same number of atoms.

  • energy and force-based specs require a calculator or pre-stored arrays

    on the Atoms objects. Missing values are filled with NaN.

  • Duplicate property names are not allowed. Use names to disambiguate.

API Reference

sparc.src.utils.chemview.ChemView(*, frames, specs, x, y, z=None, names=None, units_override=None, **kwargs)[source]

Build properties from user defined specs and launch a Chemiscope viewer.

Parameters:

  • frames (sequence of ase.Atoms)

  • specs (list ("frame", "energy", "distance:i,j", "angle:i,j,k", "dihedral:i,j,k,l"))

  • x (str structure property names ('energy', 'distance',...))

  • y (str structure property names ('energy', 'distance',...))

  • z (str or None)

  • names (list or None)

  • units_override (dict or None)

  • meta_name (str, optional) – Dataset label shown in Chemiscope. Default "ChemView".

  • color_atoms (str or None, optional) – Atom colouring in the 3-D viewer: "element", "atom_index", or None. Default "element".

  • labels (bool, optional) – Show element symbols on atoms. Default False.

  • show_index (bool, optional) – Show atom index numbers on atoms. Default False.

  • env_cutoff (float, optional) – Cutoff radius (Å) for atom environment selection. Default 3.5.

  • map_color (str or None, optional) – Property used to colour scatter-plot points. Must be one of x, y, or z. Default None.

  • plot (bool, optional) – Show the scatter-plot panel alongside the 3-D viewer. Default True.

Examples

Basic usage:

from sparc.src.utils.chemview import ChemView

ChemView(frames=traj,
    specs=["frame", "energy", "angle:0,1,7"],
    x="frame",
    y="energy",
    map_color='energy')

Show atom indices and click-to-select:

ChemView(frames=traj,
    specs=["frame", "energy"],
    x="frame", y="energy",
    show_index=True,
    color_atoms='atom_index')