Chemiscope Python
Designchemiscope-pythonChemiscope Python is an Agent Skill for design published in the lab-cosmo/chemiscope repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Author chemiscope visualizations in Python — build interactive structure/property explorers for molecules and materials. Use when creating chemiscope.show() / write_input() datasets, visualizing forces or vectors as arrows, atom-centered (per-environment) properties, custom shapes (spheres, ellipsoids, arrows, meshes), configuring map/structure display settings, or embedding chemiscope in Sphinx docs or a Streamlit app. Covers ASE / chemfiles / MDAnalysis / stk inputs and the JSON format.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/lab-cosmo/chemiscope/blob/HEAD/docs/skills/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/chemiscope-python, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Chemiscope in Python
Chemiscope is an interactive explorer for collections of molecules and materials. A dataset pairs structures (atomic geometries) with properties (scalars/vectors per structure or per atom). Three linked panels stay in sync: a 2D property map (Plotly scatter), a 3D structure viewer (3Dmol), and an info panel.
Requires
pip install chemiscope. Reading structures needs a backend such asase(pip install ase), orchemfiles/MDAnalysis/stk.
Reference files (load on demand)
settings-reference.md— fullsettingsdict schema (everymap/structurefield, defaults, accepted values, palettes). Read it when hand-authoring settings beyondquick_settings.shapes-reference.md— full shapes spec (all kinds, parameters, helper signatures). Read it when building custom shapes beyond the cookbook recipes below.
Choosing the right output
Pick the delivery mechanism before writing code:
| Goal | Use |
|---|---|
| Interactive view in a Jupyter / marimo / Colab notebook | chemiscope.show(...) (or show_input(file)) |
| Shareable file, open online | chemiscope.write_input("data.json.gz", ...) → load at chemiscope.org |
| Single offline HTML file, no server | write_input("data.json", ...) (uncompressed!) then cat chemiscope_standalone.html data.json > out.html |
| Embed in Sphinx documentation | chemiscope.sphinx extension + .. chemiscope:: directive |
| Embed in a Streamlit app | chemiscope.streamlit.viewer(dataset, ...) |
| Scripted PNG images / fully headless | widget save_structure_image / save_map_image, or chemiscope.headless |
| Build a map from learned ML features automatically | chemiscope.explore(...) |
There is no one-call Python API that emits a self-contained HTML; the standalone
route is "JSON + prebuilt chemiscope_standalone.html" (concatenation, uncompressed JSON
only). See "Other delivery mechanisms" at the bottom for Sphinx/Streamlit/headless detail.
show / show_input / streamlit.viewer / the .. chemiscope:: directive all accept
mode= "default" (map + structure) | "structure" (3D only) | "map" (map only).
Minimal recipe
import ase.io
import chemiscope
structures = ase.io.read("trajectory.xyz", ":") # ":" reads ALL frames
chemiscope.show(
structures=structures,
properties=chemiscope.extract_properties(structures), # pull props from the files
metadata={"name": "My dataset"},
settings=chemiscope.quick_settings(x="energy", y="volume", map_color="energy"),
)
Swap show(...) for write_input("out.json.gz", ...) (same args) to save instead.
create_input(...) returns the dataset dict without writing — useful for inspection.
Input structures
structures is a list of any supported object (don't mix types):
| Object | Backend | Notes |
|---|---|---|
ase.Atoms | ase | Most common. ase.io.read(path, ":") reads extxyz, CIF, PDB, POSCAR, LAMMPS dumps, … |
MDAnalysis.AtomGroup | MDAnalysis | Each trajectory frame → one structure; good for biomolecules. |
chemfiles Frame / Trajectory | chemfiles (>=0.10,<0.11) | PDB, trajectories, biomolecule metadata. |
stk.Molecule | stk | Bonds included; no cell, no stored properties. |
chemiscope structure dict | — | Hand-built (schema below). |
ASE emits a cell only for periodic systems (non-zero lattice).
Hand-built structure dict
{
"size": 3, # required: number of atoms
"names": ["O", "H", "H"], # required: per-atom symbol/name (len == size)
"x": [0.0, 0.76, -0.76], # required: Cartesian coords (len == size)
"y": [0.0, 0.59, 0.59], # required
"z": [0.0, 0.0, 0.0], # required
"cell": [a1,a2,a3, b1,b2,b3, c1,c2,c3], # optional: flattened 3x3, row-major
# optional: "bonds": [[i,j,order],...], "elements", "chains", "resnames",
# "resids", "hetatom"
}
Large datasets: external structures
external = chemiscope.write_external_structures(structures, prefix="structure")
chemiscope.write_input("dataset.json.gz", structures=external, properties=...)
# Structure files must be shipped alongside the JSON; such a dataset can't be opened
# on chemiscope.org (which needs everything inline).
Properties
A dict keyed by name. Full form (preferred for sharing — units/description matter) or shorthand (target auto-deduced by length):
properties = {
"energy": { # full form
"target": "structure", # "structure" (one per frame) or "atom" (one per atom)
"values": [1.2, 0.9, 1.5], # list, 1D np.ndarray, or 2D np.ndarray
"units": "eV", "description": "DFT energy",
},
"volume": [12.0, 12.1, 11.9], # shorthand
}
- A 2D numpy array (N×M, M>1) becomes M properties
name[1] … name[M](PCA components, eigenvalues, tensor entries…). Reference them asx="pca[1]". target="atom"values length = total atoms across all structures (or # selected environments).NaNhides that point on the map.
Extract from the structures
props = chemiscope.extract_properties(structures) # everything
props = chemiscope.extract_properties(structures, only=["energy", "forces"])
props = chemiscope.extract_properties(structures, environments=envs) # atom props for a subset
For ASE: structure props come from atoms.info, atom props from atoms.arrays;
attached-calculator energy/forces are injected automatically (so forces show up
as an atom property named "forces"). Only props present in every frame are kept.
Parameterized (multidimensional) properties
properties = {"spectrum": {"target": "structure", "values": spectra_2d,
"parameters": ["freq"]}}
parameters = {"freq": {"values": freq_grid_1d, "units": "cm^-1", "name": "frequency"}}
chemiscope.write_input("out.json.gz", structures=s, properties=properties,
parameters=parameters)
Environments (atom-centered properties)
To color/select per atom, declare which atoms carry data and their display cutoff, as
(structure_id, center_id, cutoff) tuples:
environments = chemiscope.all_atomic_environments(structures, cutoff=3.5) # all atoms
environments = [(0, 4, 3.5), (0, 7, 3.5), (2, 0, 4.0)] # manual subset
Pass environments=... and use target="atom" in the settings for per-atom views.
Settings (common case)
settings = chemiscope.quick_settings(
x="energy", y="volume", z=None, # map axes (property names; use name[i] for components)
map_color="energy", size=None, symbol=None,
structure_color=None, # color atoms by a property
target="structure", # "atom" for per-environment view
trajectory=False, # True: join map points + keep 3D orientation
periodic=False, # True: show unit cell + 3x3x3 supercell
)
For full control (every map/structure field, palettes, etc.), read
settings-reference.md and pass a settings dict directly.
Shapes (common case)
Pass shapes={name: definition}, then activate via the structure setting
"shape": "name". Helpers build definitions for you:
chemiscope.ase_vectors_to_arrows(structures, "forces", scale=1, radius=0.15)
chemiscope.ase_tensors_to_ellipsoids(structures, "alpha", force_positive=True, scale=0.2)
For custom meshes, batched spheres/cylinders, combined shapes, layered per-atom
parameters, and the full kind list, read shapes-reference.md.
Cookbook
Forces / vectors as arrows
chemiscope.write_input(
"trajectory.json.gz",
structures=structures,
properties=chemiscope.extract_properties(structures),
shapes={"forces": chemiscope.ase_vectors_to_arrows(structures, "forces", scale=1, radius=0.15)},
settings={
"structure": [{"keepOrientation": True, "playbackDelay": 100, "shape": "forces"}],
"map": {"joinPoints": True},
},
)
Works for any N×3 atom array (velocities, dipoles, displacements…).
Atom-centered property: color atoms + labels
chemiscope.show(
structures=structures,
properties={"charge": {"target": "atom", "values": charges_flat, "units": "e"}},
environments=chemiscope.all_atomic_environments(structures, cutoff=3.5),
settings={
"target": "atom",
"structure": [{"color": {"property": "charge", "palette": "bwr"},
"atomLabels": True, "labelsProperty": "charge"}],
},
)
Tensors as ellipsoids (e.g. polarizability)
chemiscope.write_input(
"tensors.json.gz", structures=structures,
properties=chemiscope.extract_properties(structures, only=["alpha"]),
shapes={"alpha": chemiscope.ase_tensors_to_ellipsoids(structures, "alpha",
force_positive=True, scale=0.2)},
settings={"structure": [{"atoms": False, "shape": "alpha"}]},
environments=chemiscope.all_atomic_environments(structures),
)
Custom mesh shape, per-atom scaling
cube = {
"kind": "custom",
"parameters": {
"global": {"vertices": [[-1,-1,-1],[1,-1,-1],[-1,1,-1],[1,1,-1],
[-1,-1,1],[1,-1,1],[-1,1,1],[1,1,1]]}, # hull auto-computed
"atom": [{"scale": 0.3, "color": 0x44AAFF} for _ in range(total_atoms)],
},
}
chemiscope.write_input("mesh.json.gz", structures=structures, shapes={"cube": cube},
settings={"structure": [{"shape": "cube"}]})
Trajectory / periodic / biomolecules
settings = chemiscope.quick_settings(x="time", y="energy", trajectory=True) # path + fixed view
settings = chemiscope.quick_settings(periodic=True, target="atom") # cell + supercell
import MDAnalysis as mda
u = mda.Universe("protein.pdb")
chemiscope.show(structures=u.atoms, mode="structure",
settings=chemiscope.quick_settings(structure_settings={"cartoon": True}))
Metadata
metadata = {"name": "Dataset title", # required (bare minimum)
"description": "...", "authors": ["Ada Lovelace"],
"references": ["doi:10.xxxx/yyyy"]}
Automatic dimensionality reduction
chemiscope.explore(structures, featurizer="pet-mad-1.0",
properties=chemiscope.extract_properties(structures),
environments=chemiscope.all_atomic_environments(structures))
# write straight to a file: explore(..., write_input="out.json.gz")
# custom model: featurizer = chemiscope.metatomic_featurizer(model="model.pt")
Other delivery mechanisms
Self-contained offline HTML
chemiscope.write_input("data.json", structures=s, properties=p) # uncompressed JSON!
Then download chemiscope_standalone.html from
https://chemiscope.org/chemiscope_standalone.html and concatenate:
cat chemiscope_standalone.html data.json > out.html # opens in any browser, no server
Only uncompressed .json (not .json.gz) works with the standalone HTML.
Sphinx documentation
Add the extension in conf.py: extensions = ["chemiscope.sphinx"]. Then in an .rst:
.. chemiscope:: ../datasets/showcase.json.gz
:mode: structure # default | structure | map (optional, default "default")
:warning_timeout: -1 # ms; 0 = persistent, -1 = disable (optional)
The path is to a .json/.json.gz file relative to the .rst. The widget loads data
dynamically, so serve the built docs over HTTP (e.g. python3 -m http.server in
build/html); opening the raw file won't work. (For sphinx-gallery examples, assigning a
show() widget to a variable named ___ auto-generates the directive via the bundled
ChemiscopeScraper.)
Streamlit app (pip install chemiscope[streamlit])
import chemiscope, ase.io, streamlit as st
structures = ase.io.read("structures.xyz", ":")
dataset = chemiscope.create_input(structures)
chemiscope.streamlit.viewer(dataset, mode="structure") # run with: streamlit run app.py
viewer(dataset, *, settings=None, mode="default", no_info_panel=False, width="stretch", height=550, key="chemiscope_viewer", selected_index=None, on_select=None, on_settings_change=None). on_select receives the selected structure index (or None);
selected_index (e.g. bound to st.session_state) drives the selection externally.
Headless / scripted images
w = chemiscope.show(structures=structures, properties=props, settings=settings)
await w.save_structure_image("frame.png") # await the futures in a notebook
await w.save_map_image("map.png")
await w.save_structure_sequence([0, 1, 2], ["a.png", "b.png", "c.png"])
# fully headless (no notebook), Playwright-based: from chemiscope import headless
Gotchas & validation cheat-sheet
settingsmust be a JSON-serializable dict (round-tripped through JSON).target="atom"/ atom-coloring requiresenvironments.mode="default"/"map"needs ≥2 properties for the map.- Properties-only dataset (no structures) requires every property
target="structure". - Atom-property length = total atoms; structure-property length = number of structures.
- Change a widget's view by reassigning
.settingswith a complete dict (in-place nested mutation is ignored). frames=/meta=are deprecated aliases forstructures=/metadata=.extract_propertiesdrops properties not present in every structure (with a warning).
Using this skill elsewhere
This skill is self-contained, portable, and harness-agnostic Markdown. In the chemiscope
repository the canonical copy lives at docs/skills/ (this SKILL.md plus the two
reference files); Claude Code also picks it up via the symlink
.claude/skills/chemiscope-python -> ../../docs/skills.
To reuse it in another project or agent:
- Claude Code — copy (or symlink) the three files into a named folder under
~/.claude/skills/<name>/(available in every project) or<project>/.claude/skills/<name>/(scoped to one project). - Other agents — point the agent at these files, e.g. from an
AGENTS.mdpointer or by referencing the path directly. The YAML frontmatter is Claude-specific metadata and is harmless to other tools.
Either way, pip install chemiscope (plus a backend like ase) in the working
environment.