Chemiscope JSON file format

This page documents the JSON file format used by chemiscope. These are the fields that appear in the final JSON output file generated by Python functions like chemiscope.write_input() or when manually constructing JSON data.

For instructions on how to create these JSON files using Python, see the Input creation with Python page.

The chemiscope JSON file consists of these top-level entries:

Key	Description	Required?
meta	Dataset metadata (name, authors, etc.)	No
structures	List of atomic structures (coordinates, cell, bonds)	Yes
properties	Properties mapped to atoms/structures (energy, forces, PCA, etc)	Yes
shapes	Custom shapes (spheres, arrows) to visualize in structures	No
settings	Default visualization settings (map axes, colors, etc.)	No
environments	Atom-centered neighborhoods	No
parameters	Parameters for multidimensional properties (e.g., time series)	No

Below is the detailed description of the values types and examples for each entry.

Metadata (meta)

Optional. Contains description of your dataset. The fields will be rendered as markdown.

Metadata fields

Field	Type	Description	Required	Example
name	string	Short title of your dataset	Yes	"XXX dataset"
description	string	Detailed explanation of content/origin	No	"A dataset from ..."
authors	string[]	List of dataset authors	No	["Author 1", "Author 2"]
references	string[]	Citations/links (one per array item)	No	["DOI:10.1234/abc", "'A new molecular construction', Journal of Random Words 19 (1923) pp 3333, DOI: 10.0000/0001100", "'nice website' http://example.com"]

Example:

"meta": {
  "name": "MAD PCA",
  "description": "1000 validation structures from the *MAD dataset* under PCA",
  "authors": ["Author 1"],
  "references": ["https://arxiv.org/abs/2506.19674"]
}

Structures (structures)

Required. Contains all atomic configurations in your dataset. Each structure is represented as an object with the following fields:

Structure fields

Field	Type	Description	Required	Example
size	integer	Number of atoms in the structure	Yes	5
names	string[]	Chemical symbols (length must match size)	Yes	["H", "O", "H"]
x	number[]	X coordinates (Å)	Yes	[0.0, 1.5]
y	number[]	Y coordinates (Å)	Yes	[0.0, 0.0]
z	number[]	Z coordinates (Å)	Yes	[0.0, -1.5]
cell	number[9]	Unit cell vectors as [ax, ay, az, bx, by, bz, cx, cy, cz] (Å)	No	[10, 0, 0, 0, 10, 0, 0, 0, 10]
pbc	bool[3]	Periodic boundary conditions for x, y, z.	No	[true, true, true]
bonds	integer[][3]	List of bonds as [[i, j, order], ...] (0-based atom indices).	No	[[0, 1, 1], [1, 2, 1]]
elements	string[]	Optional alternative to names for element symbols	No	["C", "H", "H", "O"]
resnames	string[]	Residue names (useful for biomolecules)	No	["GLY", "GLY", "HOH"]
resids	integer[]	Residue indices corresponding to each atom	No	[1, 1, 2]
chains	string[]	Chain identifiers for biomolecules	No	["A", "A", "B"]
hetatom	bool[]	Marks heteroatoms (non-standard or non-biopolymer atoms)	No	[false, false, true]

Example:

{
  "size": 3,
  "names": ["O", "H", "H"],
  "x": [0.0, 0.76, -0.76],
  "y": [0.0, 0.59, 0.59],
  "z": [0.0, 0.0, 0.0]
}

Properties (properties)

Required. Defines all dataset properties to be available for a display inside the widget. The field is an object where each key is the property name (e.g., "energy", "charge") and each value is the property definition.

Each property is an object with the following fields:

Property fields

Field	Type	Description	Required	Example
target	string	Scope of the property: "atom" or "structure"	Yes	"atom"
values	number[] | string[] | number[][]	Values (scalars or arrays; see shapes below)	Yes	[1.2, 3.4]
units	string	Physical units of the values	No	"eV/Å"
description	string	Property description	No	"DFT-calculated forces"
parameter	string[]	For multidimensional: single parameter name (links to parameters top-level)	If multidimensional properties	["time"]

Example:

properties = {
    "something": {
        "target": "atom",
        "values": [0.1, 0.0, -0.1, 0.2, -0.1, 0.0],
        "units": "Cd / mol",
        "description": "some description"
    }
}

Value types and shapes

Supported value formats

Type	Format	Details	Example
Scalar	Array of numbers	Length must match the number of atoms (for target="atom") or the number of structures (for target="structure").	[0.1, 0.2, 0.3]
Multi-dimensional	Array of arrays of numbers	Used for parameterized properties; outer array length must match the number of atoms (for target="atom") or the number of structures (for target="structure"), while the inner arrays length must match the linked parameter length.	[[0.1, 0.2], [0.3, 0.4]]
Categorical	Array of strings	Used for symbols setting	["H", "O", "O"]

Parameters (parameters)

Optional. Defines the variables for multidimensional properties. This is required when properties use the parameters field in the properties.

The parameters field is an object where each key is a name (referenced in property parameters), and the value is the parameter definition.

Parameter definition

Each parameter is an object with the following fields:

Parameter fields

Field	Type	Description	Required	Example
values	number[]	Array of values (length must match the second dimension of linked properties)	Yes	[0, 10, 20]
name	string	Display name	No	"Time steps"
units	string	Units	No	"fs"

Example

"parameters": {
  "time": {
    "values": [0, 10, 20, 30],  // matches length in linked property
    "name": "Simulation time",
    "units": "fs"
  }
}

// linked property (from properties section)
"properties": {
  "energy": {
    "target": "structure",
    "values": [[-1.0, -1.1, -1.2, -1.3], /* ... */],
    "parameters": ["time"],
    "units": "eV"
  }
}

Environments (environments)

Optional. Specifies atom-centered environments for datasets where properties are associated with specific atoms rather than entire structures. Omitting this field defaults to structure-level visualization only.

The environments field is an array of objects, each defining an environment. To generate, use helper function chemiscope.all_atomic_environments().

Environment definition

Each environment is an object with:

Environment fields

Field	Type	Description	Required	Example
structure	integer	0-based index of the structure in structures	Yes	0
center	integer	0-based index of the central atom in the structure	Yes	8
cutoff	number	Spherical cutoff radius (in Å; must be > 0)	Yes	3.5

Examples

"environments": [
  {"structure": 0, "center": 0, "cutoff": 3.5},
  {"structure": 0, "center": 1, "cutoff": 3.5},
  {"structure": 0, "center": 2, "cutoff": 3.5}
]

Shapes (shapes)

Optional. Defines custom 3D shapes (e.g., spheres, arrows) to overlay in the structure viewer. This is useful for visualizing additional features like atomic forces (as arrows), uncertainty ellipsoids, or custom meshes.

The shapes field is an object where each key is a shape group name (e.g., “forces”), and the value is the shape group definition. Multiple groups can be defined for different visualizations.

Shape group definition

Each shape group is an object with the following fields:

Shape group fields

Field	Type	Description	Required	Example
kind	string	Shape type: "sphere", "ellipsoid", "cylinder", "arrow", or "custom"	Yes	"arrow"
parameters	object	Parameters at different levels: "global" (all shapes), "structure" (per structure), "atom" (per atom/environment)	Yes	See below

Parameter levels

Parameters are specified in nested objects and merged from general to specific:

• global: Object containing the default parameters applied to all shapes in the group.

• structure: array of objects, one per structure. Overrides global for that structure.

• atom: array of objects, one per atom. Overrides structure and global for that atom.

Common parameters

These apply to any shape kind:

Common parameters

Parameter	Type	Description	Required
position	number[3]	Center position (defaults to structure origin or atom position)	No
scale	number	Scaling factor for size	No
orientation	number[4]	Rotation quaternion (x, y, z, w); ignored for cylinder and arrow	No
color	string | hex	Color (e.g., "red" or 0xFF0000)	No

Kind-specific parameters

Each shape kind supports additional parameters (in addition to the common ones above).

Sphere

Parameter	Type	Description	Required
radius	number	Sphere radius.	Yes

Ellipsoid

Parameter	Type	Description	Required
semiaxes	number[3]	Semi-axes lengths along x, y, z.	Yes

Cylinder

Parameter	Type	Description	Required
vector	number[3]	Direction and length; tip at vector end.	Yes
radius	number	Cylinder radius.	Yes

Arrow

Parameter	Type	Description	Required
vector	number[3]	Direction and length; tip at vector end.	Yes
baseRadius	number	Shaft radius.	Yes
headRadius	number	Arrowhead radius.	Yes
headLength	number	Arrowhead length; may extend beyond base if the vector is short.	Yes

Custom

Parameter	Type	Description	Required
vertices	number[N][3]	array of vertex positions.	Yes
simplices	integer[M][3]	Mesh triangulation indices.	No

Examples

1. Global spheres (same for all structures/atoms):

"shapes": {
  "highlight_spheres": {
    "kind": "sphere",
    "parameters": {
      "global": {"radius": 0.5, "color": "red"}
    }
  }
}

2. Per-atom arrows (e.g., for forces):

"shapes": {
  "forces": {
    "kind": "arrow",
    "parameters": {
      "global": {"baseRadius": 0.1, "headRadius": 0.2, "headLength": 0.3},
      "atom": [  // length = total atoms
        {"vector": [1.0, 0.0, 0.0]},
        {"vector": [0.0, 1.0, 0.0]},
        /* ... */
      ]
    }
  }
}

3. Custom mesh with per-structure scaling:

"shapes": {
  "tetrahedron": {
    "kind": "custom",
    "parameters": {
      "global": {
        "vertices": [[0,0,0], [1,0,0], [0,1,0], [0,0,1]],
        "simplices": [[0,1,2], [0,1,3], [0,2,3], [1,2,3]]
      },
      "structure": [  // length = number of structures
        {"scale": 1.0},
        {"scale": 2.0},
        /* ... */
      ]
    }
  }
}

Settings (settings)

Optional. Preconfigures the default visualization settings for the dataset, such as map axes, colors, and structure viewer options. The settings field is an object with top-level keys for different panels.

Top-level settings

Top-level settings

Field	Type	Description	Example
target	string	Default view: "atom" or "structure" (requires environments for "atom")	"atom"
map	object	Map panel settings (axes, colors, etc.)	See below
structure	array[object]	Structure viewer settings (one object per viewer; up to 9)	See below
pinned	integer[]	Indices of environments/structures to pin in viewers (up to 9; defaults to [0])	[0, 5, 10]

Map settings (map)

Configures the scatter plot. Sub-keys for axes (x/y/z), color, size, etc.

Map settings

Field	Type	Description	Example
x / y / z	object	Axis config: {"property": "<name>", "scale": "linear"|"log", "min": number, "max": number}	{"property": "PCA[1]", "scale": "linear"}
color	object	Color config: like axis, plus "palette" option for colormap selection, and `"opacity" to make traces transparent. Supported palettes: "inferno", "magma", "plasma", "viridis", "cividis", "seismic", "brg", "bwr", "rwg", "twilight (periodic)", "twilight dark (periodic)", "hsv (periodic)", "tab10", "tab20", "tab20b", "tab20bc". Opacity range: 1-100.	{"property": "energy", "palette": "viridis", "opacity": 100}
size	object	Size config: {"property": "<name>", "mode": "constant"|"linear"|"log"|"sqrt"|"inverse", "factor": 1–100, "reverse": bool}	{"property": "volume", "mode": "sqrt", "factor": 50}
symbol	string	Property name for categorical symbols (string values)	"phase"
markerOutline	bool	Thin black outline on markers	true
joinPoints	bool	Connect points with a thin black line (e.g., for trajectories)	false

Structure settings (structure)

Array of objects (one per viewer).

Structure settings

Field	Type	Description	Example
bonds	bool	Show bonds	true
atoms	bool	Show atoms	true
spaceFilling	bool	Use space-filling representation	false
atomLabels	bool	Show atom labels	false
labelsProperty	string	An environment property value for the atom labels	element
unitCell	bool	Show unit cell	true
supercell	integer[3]	Repetitions in a/b/c directions	[2, 2, 2]
rotation	bool	Auto-rotate molecule	false
axes	string	Axis system: "none"|"xyz"|"abc"	"xyz"
keepOrientation	bool	Maintain orientation when changing structures	true
playbackDelay	integer	Delay between frames in milliseconds when playing back structures	50
environments	object	Environment options: {"activated": bool, "center": bool, "cutoff": number, "bgStyle": "licorice"|"ball-stick"|"cartoon"|"hide", "bgColor": "grey"|"CPK"|"property"}	{"activated": true, "cutoff": 3.5}
color	object	Atom coloring: {"property": "element"|"<name>", "transform": "linear"|"log10"|"sqrt"|"inverse", "min": number, "max": number, "palette": "bwr"}	{"property": "charge", "palette": "bwr"}

Examples

1. Basic 2D map with color:

"settings": {
  "map": {
    "x": {"property": "PCA[1]"},
    "y": {"property": "PCA[2]"},
    "z": {"property": ""},
    "color": {"property": "energy"}
  }
}

2. Trajectory mode with pinned structures:

"settings": {
  "target": "structure",
  "map": {"joinPoints": true},
  "structure": [{
    "keepOrientation": true,
    "playbackDelay": 50
  }],
  "pinned": [0, 10, 20]
}