The simulator

Generated from docs/simulator.md in fibsem-os at build time. Edit it there; changes here are overwritten.

manufacturer: Demo in a microscope configuration connects to DemoMicroscope: a full microscope in software. It has both beams, a fluorescence microscope, a stage with the same geometry model as the hardware drivers (pre-tilted shuttle or compustage), a sample holder with slots and, when configured, an autoloader magazine. Every workflow, task and UI runs against it unchanged, which is how most of fibsem-os is developed and tested.

With the sample scene on, the beams image a synthetic cryo-grid instead of noise: a mesh of bars and film with cells, contamination, ice and rips on it, that both beams and the fluorescence camera see through their own projections. The same world persists across stage moves, tilts, scan rotations and beam shifts, so navigation, tiling, alignment and milling can be exercised for real.

Turning the scene on

sim:
    sample:
        enabled: true
        coincidence_offset: 8.0e-6      # height error at boot (m)

Everything else has a default. The two development configurations that ship, sim-arctis  (compustage, with FM) and sim-iflm , have the scene on with the common keys spelled out; microscope-configuration.yaml (the shuttle Demo the tests run on) leaves it off, so its beams return noise.

What the beams see

The scene is one world on the sample plane. Each beam renders it through the same BeamStageProjection the app uses to draw saved positions and stitch overviews, so the FIB view is foreshortened by the beam’s angle to the surface, a height error shows as a vertical displacement between the views (what the coincidence alignment measures), scan rotation turns the content, and a beam shift moves it.

Contrast is per beam, not one image inverted for the other: holes, rips and trenches are dark in both (no material, no signal); cell bodies are bright mounds in the SEM and read slightly darker than the film in the FIB with a bright outline (the edge effect); the film brightens at grazing incidence.

Cell types

cell_type picks what grows on the film: mammalian (adherent, spread bodies with an off-centre nucleus and organelle speckle; the default), yeast (compact ovoids in clusters, some budding), bacteria (dense small rods), mixed, or none for bare film. Cell bodies are opaque: they hide the film, holes and bars under them.

Film, rips, ice and contamination

• Film: continuous by default, or holey for a Quantifoil-style lattice of round holes (hole_diameter, hole_pitch, a seeded few broken). The holey lattice is a 4 um periodic pattern the fine-pass coincidence correlator can alias on; see the note below.
• Rips: a seeded fraction of squares (rip_fraction) has the film torn away. Each rip is its own tear (size, orientation, where it starts, how ragged), a square beside a ripped one rips more readily, and a bright curled edge rings each rip.
• Ice (ice_density): flat bright plates with an irregular outline.
• Contamination (contamination_density): small bright specks over film and bars alike, the aperiodic content that breaks a mesh-pitch alias in real images.

Milling leaves marks

When milling runs, the drawn patterns are committed to the world as trenches (polygons on the surface, so a rectangle rotated in the FIB view lands where the surface has it). From then on every view, either beam, any tilt, shows them.

The fluorescence view

The FM camera images the same world through the FM projection, with a dye model keyed on the excitation line: reflection shows the grid (bars bright, holes and rips dark, cells faintly); a DAPI-like line lights nuclei and the fiducial; a GFP-like line the cell bodies; an mCherry-like line a seeded subset of cells (red_fraction). Anything else renders dark. The objective’s distance from focus blurs the frame. The panels are shown in the false colour a viewer gives each channel, and composited the way a CLEM overlay is.

One world, three views

The same stage position through the three projections: the SEM looks down on the surface, the FIB sees it foreshortened at its angle, and the FM camera images it through its own tilt and transform. A feature clicked in one view is where the other two say it is, because every view is drawn from one world through the app’s own projection code.

Grids at the holder’s slots

With grids_from_holder: true the scene places one grid at every holder slot that has a calibrated position and a loaded grid, centred where the slot’s stage position falls, and shows the holder between them. A grid’s content is seeded from its name, so exchanging grids between slots moves their cells with them. Off (the default), or with no such slot, there is one grid centred on the position the stage was at when it connected.

To set a two-grid shuttle up on the Demo: calibrate the two slots with the holder calibration wizard (Microscope tab, Sample Holder panel) at two stage positions a few millimetres apart, put a grid in each slot, and set grids_from_holder: true in the configuration’s sample: block. The holder file is shared by every configuration in the directory, which is why the option is per configuration.

Coincidence and stage geometry

coincidence_offset is the height error the stage boots with: the SEM view barely moves, the FIB view is displaced by the view tilt’s worth, and the coincidence alignment (Development menu) measures and removes it. tilt_axis_offset makes the stage non-eucentric: the surface sits that far above the tilt axis, so a tilt change swings it, which is what the tilt alignment corrects. beam_offset adds a persistent per-beam lateral misalignment, and current_offset_scale a seeded offset per beam current, so the milling-current alignment has something real to undo.

Keys

All keys of the sim: sample: block, by what they control, with their defaults. Angles are in degrees, ranges are two-element lists, lengths in metres.

Stage and coincidence

Beams

Grid and film

Cells

Rips, ice and contamination

Noise

Fluorescence

Holder

Reproducibility

Cost and limits

• A frame renders in about 0.3 s at 1536 x 1024 once a place has been imaged; the first frame somewhere new costs 0.4-2 s (the world is stamped into cached tiles, then sampled per view). The fluorescence view is stamped per frame, about 0.4 s.
• The holey film’s 4 um lattice defeats the fine-pass coincidence correlator (band refusals, a false convergence at large errors); keep the film continuous for alignment work until the measurement handles it.
• The scene is generated fresh from its seed on every connect. The same seed gives the same grid; milled trenches do not survive a reconnect.

The figures on this page are rendered with fiducial: true (a landmark for the eye; off by default) by render_simulator_examples.py from the current code, and the key tables are read from the scene’s defaults; rerun it after changing the simulator.