Stochasm

Views

The header's View selector lists what the current model + mode offers. Each is drawn on the GPU. Two floating windows sit beside the View selector: View Settings (the eye icon) holds a view's display options (colours, trails, glow, phase axes), and Interaction & Paint (the brush icon) holds its tools: the paint brushes and, in the phase view, the Pan/Zoom tool. Both are detailed per model below.

Framing the phase view

Every Ensemble (phase-space) view shares two ways to frame the cloud. Smart zoom (on by default; toggle it in View Settings) opens the view zoomed onto where the systems actually are rather than showing the whole axis range with a speck in the middle, and it re-frames as the cloud spreads out. It has a built-in zoom-in limit, so a cloud collapsed onto a single point (an ensemble at the very start, before any structure develops) is centred and bounded instead of magnified to infinity. Switch it off and the camera simply freezes wherever it is: your pan and zoom stay put (double-click to return to the full phase space with its theoretical envelopes). For manual control, the Pan/Zoom tool (the default interaction mode) lets you drag to pan and scroll to zoom in and out at the cursor; a double-click resets to the auto-fit. A single click still samples the nearest system into the Sampler (the same as in Paint mode), so you can inspect systems without leaving Pan/Zoom. Panning or zooming by hand stands smart zoom down until you reset. To paint systems in phase space (Multi-Component Lattice), switch the tool to Paint in Interaction & Paint.

Split view

Split is an extra view that shows two views at once. Nothing is simplified: each half is the full view you would get on its own, drawn at half width, so it keeps its own axes, legend, camera, rendering and cursor. What the two halves are depends on the mode:

• Ensemble (all four models) — the Ensemble phase-space cloud beside the Cluster Graph. The cloud shows where the population sits in observable space; the graph shows the states the machine-learning layer has learned from it. Together you can see a region of the cloud and the node it belongs to at the same time.
• Single system (Multi-Component Lattice and Patchy Discs) — the Observables plot beside the system itself: the lattice, or the box of discs. Watch a curve move and see what the system is doing at that moment.

Both halves are configured from the one View Settings window, which splits into two collapsible sections named after the panes — Observables and Lattice/Particles in single mode, Ensemble and Graph in an ensemble.

The divider is draggable. A small grip sits at the middle of the seam between the two halves; hover anywhere along the seam — it brightens and the cursor becomes a resize arrow — then drag to give one view more room. Neither half can be squeezed below a third of the width, so the range runs from one-third/two-thirds to two-thirds/one-third. Each half re-fits as it resizes: axes rescale, the lattice or disc box re-centres, and the phase view's history trail is carried across rather than redrawn. The position is a proportion, not a pixel column, so it survives collapsing the control panel and resizing the window; Start Fresh returns it to even halves.

Each half keeps its own interactions, and they apply wherever you point. In single mode painting is confined to the system half, so dragging over the plot does nothing. In an ensemble, Pan/Zoom, scroll-to-zoom, double-click-to-reset and painting all act on the phase-space half, while clicking a node in the graph half selects that node — and either click feeds the same Sampler. Selecting in one half clears the other, so the Sampler always describes exactly one thing. (Single Particle has no per-system preview, so neither half samples there: its phase half paints and its graph half is for watching.)

Observables & statistics

Stochasm measures a feature vector for every system, every step: the same numbers that drive the phase-space axes, the plots, and the machine-learning layer. What’s measured is model-specific (detailed in the per-model sections below); how you read it is shared.

The Statistics window

The header's bars icon opens a floating window listing every currently-enabled observable, live. In single mode it describes the system; in Multi-Component Lattice and Patchy Discs ensembles it lives inside the Sampler and describes the selected system (the Ising ensemble's window reports population means instead).

The heavier observables can be switched off to save their compute cost: the Compute tab's Observables card (per model) toggles the optional groups live, and a disabled group's observables vanish everywhere: axes, plots, statistics, learning.

The Sampler

Ensembles show you ten thousand systems at once; the Sampler lets you hold one of them in your hand. Click any point in the Ensemble view (or any node in the Graph view) and the Sampler window opens. It has three yellow-headed sections: a Mode selector, a System View of the system's actual state (with its ID), and its full Statistics.

The Mode selector (at the top of the Sampler) chooses how the preview behaves:

• Sample near point (default): the Sampler cycles through systems near your click, a fresh one every third of a second, each shown as a frozen snapshot. The green rings mark the sampled spot; the green dot shows where the current sample actually sits.
• Follow one: hold a single system and watch it evolve live, its green dot riding along as it drifts through the cloud.

The selected system is immune to the phase brush, so you can paint around it without losing it. ✕ (or a click on empty space, or Reset Simulation) deselects; the neon green ring and sprite always mean "the selected system"; nothing else in the app uses that colour.

Machine Learning

The Machine Learning tab hosts Stochasm's learning layer, and works for any model's ensemble. Its first instrument is the cluster graph: every system's observables form a feature vector; the app standardises the features, clusters the ensemble, and draws the result as a force-directed graph: one node per community, sized by population, colour-coded (the palette deliberately avoids selection-green), with edges expressing similarity. Once you start it (see below) it learns in any view, sampling and re-clustering in step with the sampling cadence, so a low measurement rate means slower (never stale) learning, and the green follow-tracer glides between nodes at that cadence rather than snapping.

The learning is independent of the simulation. Play runs the physics; the cluster graph only learns while you have told it to, from the Run card in the Machine Learning tab — Start machine learning to begin, Pause to freeze it, Continue to pick up where it left off. The simulation carries on regardless. Because learning consumes measurements, it needs the simulation running: until you press Play the card simply says so, and pausing the simulation suspends learning until you resume — at which point it picks up on its own, exactly where it was.

Before you have started it, the Graph view says so and offers a button straight to those controls. To wipe what has been learned and begin again, use Reset learning in the same card. Resetting the simulation from the header clears the learning too, since a re-seeded ensemble makes the learned graph describe systems that no longer exist — and the view returns to its opening invitation.

The tab opens in Basic, with two dials. Detail is the fast/coarse → demanding/fine axis: it moves the node count, the reservoir and the number of tracked systems together, so the statistical ratios that make the graph trustworthy stay fixed and only the resolution changes. Its Balanced snap sits where there are as many nodes as there are systems per node — a good default, and where every new ensemble starts. History is the other axis: how far back the graph remembers, from tracking changes (short window, stale transitions fade) to whole run (everything accumulates). Its readout is in simulation time — sweeps, or τ_s — not wall-clock.

Advanced reveals the parameters those dials are driving: Granularity (nodes), Systems tracked (how much of the ensemble is assigned to nodes each measurement, which sets how precisely populations are known), Sampling Rate, Re-learn every, and the reservoir's Size and Memory. The two views are linked in both directions: move a Basic dial and watch the Advanced values follow; hand-edit an Advanced value and the Basic dials re-derive to match. Flipping between them is a good way to see what the intuitive controls are actually doing.

Detail's range is set by what the data can support, not by how fast your computer is: no finer than about 25 systems per node (below that, node sizes are noise) and no finer than the reservoir can place centroids in. Both limits move with the ensemble size and with how many observables are switched on — turning groups off in the Compute tab genuinely earns you more usable nodes.

Because sampling happens only when observables update, measuring often while simulating slowly yields many near-identical samples. What you actually care about is therefore coverage per unit of simulation progress — one Monte-Carlo sweep on the lattice models, and for Patchy Discs τ_s, the average single-particle relaxation time in the system: the time a disc takes to diffuse its own diameter and so break out of its cage (τ_s = σ²γ⁄4T for this Langevin engine, which is why it shifts when you change temperature or friction). Single Particle defines no such unit.

So Sampling Rate is scaled in exactly that: it runs up to 200% per sweep (or per τ_s), which puts 100% — covering the ensemble once per unit — at the midpoint, marked with a snap and used as the launch default. From there the rate follows you: change the measurement rate, the MC/MD speed, or patchy’s temperature or friction, and it re-scales itself so your chosen coverage is preserved. The handle stays put; only the per-measurement percentage above it moves.

Click a node to open a member system in the Sampler; repeated clicks cycle through distinct members, and a node whose members have all migrated elsewhere falls back to a stored specimen (titled Stored sample). Render options (physics of the layout, label style) sit in View Settings while the Graph view is active.

Toggling observable groups off changes the feature space, and the graph re-learns accordingly. To restart the learning by hand, use Reset learning in the Run card: it clears the communities, reservoir and learned features while the ensemble itself keeps running. More learning algorithms will join this tab over time.

Multi-Component Lattice

Observables

The lattice model's observables come in six classes, each with a Global (system-wide) value and, where meaningful, one value per site type:

The last three involve real work (union-find and correlation scans), so the Compute tab's Observables card lets you switch the Pair correlation and Union-Find groups off, dropping them (and their cost) from axes, plots, statistics and learning. Its checkmark matrix shows exactly what's available globally vs. per type.

The Observables view

The Observables view plots any of those classes as a live time-series: pick the class, toggle each global/per-type series, set the scrolling time window, and overlay dashed cumulative time-average curves.

Those dashed curves are worth understanding, because they answer a different question from the solid ones. At every instant a dashed curve shows that observable’s average up to then, so it smooths away the noise and tells you where a quantity is settling rather than where it happens to be. Time average picks which average: Full run is the mean of everything since launch, so it converges and then barely moves — the honest read on an equilibrium value; Time window is the trailing mean over the window set above, so it keeps up with a system that is still changing and will re-shape live as you drag that slider. Reset running averages restarts the Full-run accumulation from this moment, which is what you want after changing a parameter mid-run: the old mean described the old system. History already recorded keeps its old averages — they were true when they were measured.

Phase & lattice display

In the Ensemble view, the axis pickers (View Settings) put any two observables on the plane; when one axis is a site-type fraction and the other is same-type bond excess, amber dashed curves draw the provable Moore-8 envelopes (a phase-separated ceiling and an anti-clustered floor), with the no-go region shaded. Sprites colour by uniform tint or by each system's dominant type, and glow and history smearing are tunable. On the single Lattice view, each type also has display-only Blur and Alpha controls: Blur gives moving sites a fading trail (logarithmic: most travel is in the long-trail region near the top; at maximum the display becomes a pure occupancy heat-map), and Alpha sets the type's opacity. Neither touches the physics. The trail advances only as the simulation does: pausing freezes the smear in place, and painting, paused or mid-run, never advances it: the painted sites recolour immediately, and the rest of the smear changes only with the simulation's own motion.

2D Ising

The Ising ensemble is plotted as a magnetisation–energy cloud: the two observables that map its phase diagram. Below the critical temperature the cloud splits toward the ordered corners; above it, it pools near zero magnetisation. Amber dashed curves mark the exact phase-separated and Néel envelopes, with the forbidden region shaded, so you can watch the population press against the bounds statistical mechanics allows.

Single Particle

The single particle's home is the ensemble phase view over position × momentum. Thousands of walkers, released and thermalised, settle into a Boltzmann cloud whose shape is the equilibrium distribution of the chosen potential: a single Gaussian blob in a harmonic trap, a two-lobed cloud in a double well. Glow and history smearing trace the flow as walkers hop between wells.

Patchy Discs & Polymers

The Particles view

The Particles view draws the periodic box live, and the View Settings window (eye icon) controls how. Disc opacity and patch opacity set per-species and per-patch-type alphas (outlines fade with their fill). Periodic images toggles the wrapped copies at the box edges. Bound patches chooses how bonds are drawn (a neon dot between the bonded patches, the patches themselves turning neon, both, or nothing), and the Show bonds for tick matrix narrows the rendering to the patch-type pairs you care about. Binding renders are always full-opacity, so a favourite trick is to drop every opacity low and let only the bond network glow. Highlight bonded discs floods any disc with at least one bond in the highlight colour, and Bond trail leaves fading after-images of the binding renders: the history smear, patchy-style. The Bond highlight colour picker tunes the one colour every binding render uses: dots, neon patches, flooded discs, the trail, and the Sampler's bond strokes (default: toxic neon green).

Observables

Every patchy observable is now particle-type-specific: alongside each global value, the same quantity is measured per species (energy attributed half-per-endpoint, bonded slots, first-shell contacts, and same-species bond clusters, the MCL per-type convention). The Statistics listing shows each class as a header row (the global value) with per-species swatch chips under it, in single mode and in the ensemble Sampler alike, and the per-species variants are available everywhere the global ones are: phase axes, the Observables plot, and the machine-learning layer. A patchy ensemble's phase axes offer energy / disc, patch bond fraction and patch bonds / disc; the two union-find groups each contribute a largest cluster fraction and a mean cluster size (one over the patch-bond network, one over geometric contact); a polymer design adds ⟨Rg⟩ and ⟨Re⟩; and NPT adds packing fraction φ. Each system is an independent box of the designed molecules, so the cloud traces the self-assembly as bonds knit the discs into chains, networks, or micelles.

Alongside those bond-based measures are three geometric contact observables, the disc analog of the lattice’s same-type bond excess, measuring positional (not bonded) neighbours: contacts per disc (how many discs sit in a disc’s first coordination shell), same-type contacts per disc (of those, how many are the same species), and same-type contact excess (the same-type contact fraction minus the random-mixing baseline: zero for a random mix, positive when like discs cluster, negative when they alternate). Two discs count as neighbours when their centres fall within the first-shell cutoff times their contact distance; that cutoff is a live slider on the Compute tab, sitting above the groups it feeds, and the same card lets you switch each heavier group off to save computation.

The Union-Find group measures patch-bond clusters: groups of discs joined by patch–patch bonds, and only those. Disc–disc attractions and first-shell contacts never merge a cluster, so a dense contact-packed liquid with no bonds still reads as zero clusters. It reports the largest patch-bond cluster fraction (the biggest bonded assembly as a share of all discs), the mean patch-bond cluster size (average discs per bonded cluster, counting only clusters of two or more), and the patch-bond cluster-size variance (how unequal those assemblies are: near zero when they are uniform, large when one giant network coexists with small fragments). Per species, each of these measures clusters of that species bonded to itself.

The Union-Find (particle clusters) group asks the same three questions of a different kind of connection: discs that simply touch. Any two discs within the first-shell cutoff join the same cluster, bonded or not, so this is the geometric counterpart of the patch-bond group and it sees the things bonds miss: a jammed packing, a Lennard-Jones droplet, a demixed domain. It reports the largest contact cluster fraction, the mean contact cluster size and the contact cluster-size variance, each also per species (same-species contacts only). Connectivity is transitive, so a chain of discs is one cluster even though its two ends never touch, and tightening the cutoff slider fragments clusters while loosening it merges them. Because it does its own scan, you can run it with Contacts switched off, and vice versa.

Each Union-Find group starts switched on only when your design can actually produce that kind of cluster: the patch-bond group defaults off when there are no patch–patch rules (nothing could ever bond), and the particle group defaults off when there are no disc–disc attractions (nothing pulls discs together). Both are only defaults, so you can switch either on whenever you want to look.

A Polymer group appears whenever the design holds a bead-spring chain. It reports the two numbers that describe a chain’s conformation: the radius of gyration ⟨Rg⟩ (how far its beads spread from their own centre of mass — the chain’s size) and the end-to-end distance ⟨Re⟩ (how far its first bead is from its last). Both are averages over every chain in the system, and both walk the backbone unwrapped, so a chain draped across the periodic boundary reads the same as one sitting in the middle. Watch them together: they rise as chains swell and fall as chains collapse, and their ratio tells you the shape — a compact globule and a stretched worm have very different Re / Rg. Put ⟨Rg⟩ on a phase-space axis and a whole ensemble’s worth of coil–globule behaviour shows up at once.

One thing to know about the first-shell groups when you have chains: Contacts and the particle clusters deliberately skip a bead’s own backbone neighbours. Chain neighbours touch by construction, so counting them would add a constant to every coordination number and make each chain a cluster of its own making — telling you nothing. What you see instead is genuinely inter-molecular: how chains meet other chains.

NVT & NPT: the thermodynamic ensemble

The Simulation tab runs the discs in either ensemble. NVT (the default) holds the box fixed and thermostats the temperature. NPT lets the box breathe: a Martyna–Tobias–Klein barostat expands or compresses it until the internal pressure matches the Pressure you set, so the discs settle at whatever density that pressure implies: raise the pressure and the box shrinks (φ climbs); lower it and the box swells. The Barostat coupling slider sets how quickly the box responds (low = a snappy piston, high = slow and gentle). In single mode, watch the box side L and packing fraction φ drift live in the System section at the top of the Simulation tab; in ensemble mode every system's box breathes independently, so L and φ are per-system quantities: that readout keeps just the disc count and the Sampler reports the selected system's values. NPT also adds a packing fraction φ observable to the phase axes and the Observables view. Both ensembles work in single-system and ensemble mode; the choice is a live run setting, not saved in the config.

The Observables view

Single-system Patchy Discs also offers the Observables view (the seg beside Particles in the header): a live time-series through simulation time, with the same scrolling window and dashed time-average overlays as the lattice model’s. Pick an observable class from the dropdown and the series list below it offers the Global value plus one line per bead type, each with its own toggle and swatch — exactly as the lattice model plots per site type. It opens on Energy / disc with a 10,000-step window, and the history keeps recording whichever view you are watching.