Stochasm: Saving & sharing

Saving & sharing: the configuration format, per model

Saving & sharing

A Stochasm system is a single JSON document. The Export tab shows the running system's JSON (with an option to include the current lattice as a pinned snapshot, in single mode); copy it to a file. The Launcher's Import pastes one back, with exactly its settings. The presets are these same files, served from the app's presets/ folder.

Two of the models carry a rich enough structure to serialise: the Multi-Component Lattice and Patchy Discs (Ising and the single particle have no config export).

The envelope

Every config is the same extensible three-part shape, whatever the model:

Structure

Key	What it holds
`name`	A display name for the system (optional).
`model.type`	Which model: `multi_component_lattice` or `patchy_discs`. It routes a pasted config to the right model, and a preset file to its picker.
`model.configuration`	The model-specific structure: site types & rules, or the patchy design. Detailed per model below.
`snapshot`	An optional saved stage state: an object, so it can hold several pieces at once. Today only the lattice writes one (`snapshot.lattice`); omit it for a freshly-generated start.

The two sections below spell out each model’s configuration (and, where it has one, its snapshot); the complete field-by-field specification lives in the project README ("The model configuration format").

Multi-Component Lattice format

For a lattice config, model.type is "multi_component_lattice" and model.configuration holds the coordination number, the site types, and the rules. The saved initial state, when present, lives in snapshot.lattice.

configuration

Field	Meaning
`coordination_number`	4 (von Neumann) or 8 (Moore): the neighbour shell.
`types[]`	The site-type palette (below).
`rules[]`	The transformation rules (below).

snapshot (optional)

Field	Meaning
`lattice`	A 2D array of type ids whose shape is the lattice size: a pinned initial state. Omit the whole `snapshot` and the Builder's size slider decides the dimensions, seeded from each type's `default_initial_relative_amount`.

Each type

Field	Meaning
`name`, `color`	Label and hex colour.
`immobile`	true ⇒ swap rules cannot displace it.
`masquerade_as`	Type id this one imitates for facilitation counting (or −1 = none).
`field`	The type's energetic bias, in k_BT.
`default_initial_relative_amount`	Its relative share when the lattice is seeded randomly.
`persistence`, `alpha`	Display-only trail decay and opacity.

Each rule

Field	Meaning
`kind`	One of irreversible_flip · reversible_flip · swap · site_site_interaction.
`a`, `b`	The two endpoint type ids (−1 = the any-site wildcard).
`param`	The attempt-weight (flips/swaps) or interaction energy (site-site).
`disabled`, `ignore_energetics`	Rule enable flag; bypass all fields & interactions.
`facilitation` (optional)	A `{ "number": n, "site": t }` node: the flip needs n neighbours of type t.

Patchy Discs & Polymers format

For a patchy config, model.type is "patchy_discs" and model.configuration describes the patch types, the bead-type palette, the molecules that populate the box, and the interaction rules (patch–patch bonds and disc–disc attractions). The disc count and packing fraction are chosen in the Builder (defaulting to 100 discs at φ 0.5); like the lattice size, they are not stored in the config. Patchy has no stage snapshot yet, so it omits snapshot.

configuration

Field	Meaning
`patch_bond_stiffness`	The spring constant of every bond — formed patch bonds and polymer backbones alike.
`patch_types[]`	The bonding patch species (below).
`species[]`	The bead-type palette: what a bead is (below).
`molecules[]`	The population: what stands in the box (below).
`rules[]`	The bond rules (below).

Each patch type & bead type (species)

Field	Meaning
patch type: `name`, `color`	Label and hex colour of a bonding patch.
species: `name`, `color`	Label and hex colour of a bead type. A species carries no count — the population lives in `molecules`.
`radius`	The bead radius.
`patches[]`	Each rim patch as `{ "angle", "patch_type" }`: the angle in degrees, the patch type an index into `patch_types`.
`smoothness`, `polydispersity`	Shape distribution: bumpiness (1 = perfect disc) and the spread of the base radii. Written only when non-default.
`angular_stiffness`	Bending stiffness κ a chain feels at a bead of this type (0 = freely jointed). Written only when non-zero.

Each molecule

Field	Meaning
`architecture`	`"disc"` (a free bead), `"homopolymer"`, a two-component chain sequence (`"diblock"`, `"multiblock"`, `"gradient"`, `"random"`), or `"custom"` — a chain you write out bead by bead.
`species`	Which bead type this molecule is made of — an index into `species`, or `[a, b]` for a two-component sequence (A first: the head block, the composition’s subject). A custom chain has none: its `sequence` names every bead.
`block_fraction`, `block_beads`, `composition`	The sequence parameter, per architecture: the diblock’s A-share, the multiblock’s beads per block (1 = alternating), the random chain’s per-bead probability of A. A gradient has none (linear A → B).
`sequence`	A custom chain’s bead string: a letter per bead type by palette position (`A` = the first), each optionally followed by a repeat count — `"A6B12A6"` is an ABA triblock. It fixes the length, so a custom chain takes no `beads`.
`relative_abundance`	The molecule’s share of the discs in the box.
`beads`, `bead_polydispersity`	Chains only: mean beads per chain and the relative spread of that length.
`name`	An optional label.

Each rule

Field	Meaning
`name`	A label for the rule.
`kind`	`"patch_patch"` (the default if absent) — a bond formed and broken between two patches — or `"disc_disc"`, an isotropic Lennard-Jones attraction between two disc species.
`a`, `b`	The rule’s two endpoints: patch-type indices for a `patch_patch` rule, species indices for a `disc_disc` one.
`strength`	The well depth ε, in k_BT.
`attempt_rate`	Bind/unbind attempts per MD step, per patch. `patch_patch` only — a disc–disc attraction is pure molecular dynamics, with no bonds to attempt, and omits the field.
`disabled`	Rule enable flag.