Stochasm: Saving & sharing

Saving & sharing: the configuration format, per model

Saving & sharing

A Stochasm system is a single JSON document. The Export tab of the control panel shows the running system’s configuration in a read-only text area, with a Copy to clipboard button and, for the lattice model in single-system mode, an Include lattice snapshot (current state) checkbox. The Launcher’s Import source accepts such a document back. The shipped presets are files in this same format, held in presets/<model_type>/ and listed by path in the presets/index.json manifest the app reads at start-up.

Two models carry enough structure to serialise, the Multi-Component Lattice and Patchy Discs & Polymers. 2D Ising and Single Particle in 1D Potential have no configuration export.

A configuration stores the design only, so an import restores the design exactly and takes everything else from the Builder defaults. The seed settings are excluded, namely the lattice size unless a snapshot is stored and pinned, the number of systems, the disc count and the packing fraction. The live run controls are excluded too, namely temperature, MC or MD speed, friction, thermodynamic ensemble and measurement rate. Colours, trail decay and opacity are part of the design and are stored, as is the lattice coordination number.

The envelope

Every configuration has the same three-part shape, whatever the model.

Structure

Key	Contents
`name`	Optional display name. For the lattice model it is bound to the free-text Name field in the Simulation stage’s System section.
`model.type`	Either `multi_component_lattice` or `patchy_discs`. It routes a preset file to its model’s picker. A pasted configuration is validated against the model it is being imported under and is rejected with a message naming the correct model if it does not match.
`model.configuration`	The model-specific structure, detailed below.
`snapshot`	Optional saved stage state, an object so that it can hold several pieces. Only the lattice model writes one at present, as `snapshot.lattice`. Omit it for a freshly generated start.

The two sections below specify each model’s configuration and, where it has one, its snapshot. The complete field-by-field reference is kept with the source, in the README.md section The model configuration format.

Multi-Component Lattice format

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

configuration

Field	Meaning
`coordination_number`	4 (von Neumann) or 8 (Moore, the default). The neighbour shell.
`types[]`	The site-type palette, at most 10 entries. The Builder’s own minimum is 2.
`rules[]`	The transformation rules. Above 50 the compiled core cannot run the configuration and the JavaScript engine takes over.

snapshot (optional)

Field Meaning

lattice A two-dimensional array of type ids whose shape is the lattice size. It becomes the initial state only while the Builder’s Set lattice to initial state stored in JSON config. checkbox is selected, which also fixes the lattice size to the array’s dimensions and makes Reset Simulation return to this state. Cleared, or absent, the Builder’s size slider sets the dimensions and the lattice seeds from each type’s default_initial_relative_amount.

Field	Meaning
`lattice`	A two-dimensional array of type ids whose shape is the lattice size. It becomes the initial state only while the Builder’s Set lattice to initial state stored in JSON config. checkbox is selected, which also fixes the lattice size to the array’s dimensions and makes Reset Simulation return to this state. Cleared, or absent, the Builder’s size slider sets the dimensions and the lattice seeds from each type’s `default_initial_relative_amount`.

Each type

Field	Meaning
`name`, `color`	Label and hex colour.
`immobile`	true prevents swap rules from displacing the type. Default false.
`masquerade_as`	The type id this one imitates for facilitation counting, or -1 for none.
`field`	The type’s energetic bias, in k_BT.
`default_initial_relative_amount`	Its relative share when the lattice is seeded randomly. Absent means equal shares.
`persistence`, `alpha`	Display-only trail decay and opacity.

Each rule

Field	Meaning
`name`	A label for the rule. Always written on export.
`kind`	One of irreversible_flip · reversible_flip · swap · site_site_interaction.
`a`, `b`	The two endpoint type ids. -1 is the any-site wildcard.
`param`	For a flip or swap, the rule’s rate in [0, 1], which multiplies the Metropolis acceptance and appears as the Rate slider. For a site-site interaction, the coupling in k_BT over [-10, 10], which appears as Coupling J. Negative values attract.
`disabled`, `ignore_energetics`	The rule’s disable flag, which retains the rule but stops it being applied, and a flag that bypasses all fields and interactions. Both default to false.
`facilitation` (optional)	A `{ "number": n, "site": t }` node on a flip rule. The flip fires only where at least n of the site’s neighbours are of type t, counting types that masquerade as t. Swap and site-site rules take no facilitation.

Patchy Discs & Polymers format

For a patchy configuration model.type is "patchy_discs" and model.configuration describes the patch types, the bead-type palette, the molecules populating the box, and the interaction rules. The # of discs and Packing fraction φ are Builder settings, defaulting to 100 discs at φ 0.50, and are not stored. Patchy Discs writes no stage snapshot, so it omits snapshot.

configuration

Field	Meaning
`patch_bond_stiffness`	The spring constant of every bond, both formed patch bonds and polymer backbones.
`patch_types[]`	The bonding patch species, 0 to 8 entries. It may be absent or empty, which gives a bare-disc design.
`species[]`	The bead-type palette, 1 to 8 entries. A species states what a bead is, never how many there are.
`molecules[]`	Required. The population, 1 to 16 entries.
`rules[]`	The interaction rules.

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 is in `molecules`.
`radius`	The bead radius.
`patches[]`	Each rim patch as `{ "angle", "patch_type" }`, the angle in degrees and the patch type an index into `patch_types`. At most 8, and an empty list gives a bare disc.
`smoothness`, `polydispersity`	Shape distribution. Bumpiness, where 1 is a perfect disc, and the relative spread of the base radii. Written only when non-default.
`angular_stiffness`	The bending stiffness κ a chain feels at a bead of this type, where 0 is freely jointed. Written only when non-zero.

Each molecule

Field	Meaning
`architecture`	`"disc"` for a free bead, `"homopolymer"`, one of the two-component chain sequences (`"diblock"`, `"multiblock"`, `"gradient"`, `"random"`), or `"custom"` for a chain written out bead by bead.
`species`	The bead type the molecule is made of, an index into `species`, or `[a, b]` for a two-component sequence, with A the head block and the subject of the composition. A custom chain takes none, since its `sequence` names every bead.
`block_fraction`, `block_beads`, `composition`	The sequence parameter, one per architecture. The diblock’s A-share, the multiblock’s beads per block (1 gives a strictly alternating chain), and the random chain’s per-bead probability of A. A gradient takes none, running linearly from A to B.
`sequence`	A custom chain’s bead string. One letter per bead type by palette position (`A` is the first), each optionally followed by a repeat count, so `"A6B12A6"` is an ABA triblock. It fixes the length, so a custom chain takes no `beads`. Export run-length encodes runs of three or more, so `"AAABBB"` is written back as `"A3B3"` while `"ABAB"` is preserved.
`relative_abundance`	The molecule’s share of the discs in the box, not of the molecule count. At least one molecule must be greater than zero.
`beads`, `bead_polydispersity`	Non-custom chains only. The mean beads per chain, an integer in [2, 200], and the relative spread of that length, default 0. A custom molecule must carry neither.
`name`	An optional label.

Each rule

Field	Meaning
`name`	A label for the rule.
`kind`	`"patch_patch"`, the default when absent, a bond formed and broken between two patches. Or `"disc_disc"`, an isotropic Lennard-Jones attraction between two bead types.
`a`, `b`	The rule’s two endpoints. Patch-type indices for a `patch_patch` rule, species indices for a `disc_disc` rule.
`strength`	The well depth ε, in k_BT.
`attempt_rate`	Bind and unbind attempts per MD step, per patch, in (0, 1] and defaulting to 0.1. It applies to `patch_patch` rules only. A disc–disc attraction is pure molecular dynamics with no bonds to attempt, and omits the field.
`disabled`	The rule’s disable flag, default false.