Trajectory Viewer¶

Export the full shell-relaxation trajectory as a self-contained HTML file with interactive playback.

Capturing the trajectory¶

Per-step positions and a per-atom cost history are only stored if capture_trajectory=True is passed through to shell_relax:

cell.generate(
    shell_target,
    capture_trajectory=True,
    **tc.Supercell.PRESETS["MRO"],
)
cell.export_trajectory_html("mro_trajectory.html")

The trajectory is stored on cell.shell_relax_history["trajectory"] (shape (num_steps + 1, num_atoms, 3), float32) and the per-atom cost on cell.shell_relax_history["atom_cost"] (shape (num_steps + 1, num_atoms)).

Features¶

Playback controls: play / pause, restart, loop, bounce (ping-pong), speed slider, and a frame scrubber.
Per-atom cost colouring: atoms and bonds are coloured through the Turbo colormap by each atom’s accumulated spring-network cost at that frame. The colour range is frozen for the whole trajectory and is shown as a vertical legend to the right of the canvas. Bonds take the mean cost of their two endpoints.
Cartoon shading: shiny Phong atoms and toon-shaded bonds, each with a thin black back-face outline so that individual atoms and bonds stay crisp against the structural background.
Periodic-image bond wrapping: bond cylinders use the minimum-image displacement across periodic boundaries.
Pointer interaction: drag to rotate, scroll to zoom.

Parameters¶

Parameter	Default	Description
`output_path`	required	File path for the generated HTML.
`bond_cutoff`	from `shell_target`	Maximum bond length in Å. Defaults to `shell_target.pair_peak.max() × 1.2`.
`atom_scale`	0.32	Multiplier on each atom’s covalent radius.
`bond_radius`	0.06	Bond cylinder radius in Å.
`background_color`	`"#f7f8f5"`	CSS colour for the viewer background.
`title`	`""`	Optional text shown at the top of the viewer.
`tetrahedra` / `octahedra` / `cuboctahedra`	`None`	Single-group polyhedra overlay (supersedes bonds). Detector dict with `center_symbol`, `vertex_symbol`, `bond_length`, `bond_length_tol`, `ideal_angle_deg`, `angle_tol_deg`, `scale`.
`polyhedra_groups`	`None`	Multi-group polyhedra list (sp²/sp³ carbon blends etc.). Same entry shape as `export_overview_html`; each dict may carry a `virtual_species` filter keyed to `Supercell._atom_shell_species_index`. Suppresses bonds automatically.
`show_bonds`	`None`	Auto-picks: `True` when no polyhedra are requested, `False` when the legacy single-group or `polyhedra_groups` is set.

Embedding in documentation¶

The file is fully self-contained and loads Three.js from a CDN, so it can be dropped into a Sphinx docs tree and embedded with a plain <iframe>:

<iframe src="../_static/trajectories/mro.html"
        width="100%" height="600"
        style="border: 1px solid rgba(0,0,0,0.1); border-radius: 6px;"
        loading="lazy"></iframe>