Reproduce the outdated vcell.org tutorials as replayable scripts

[jcschaff]

The tutorial PDFs at vcell.org/webstart/VCell_Tutorials/ are screenshot decks shot against VCell 6.1–7.2. Six were refreshed in July 2025 (the 7.7/ subtree); ten still describe a client that has moved on.

This extracts a storyline from each of those ten — what the document teaches, in prose, with its exact parameter values — and turns four of them into scripts that rebuild the model against a current client, run it, and read the results back.

What runs

tools/debug-bridge/launch-client.sh
tools/debug-bridge/scenarios/tutorials/simple-frap.sh      # or moving-boundary.sh,
                                                           # frap-with-binding.sh, phgfp.sh

Tutorial	State
SimpleFRAP_7.2.pdf	reproduced, 0 errors — also a 59-step replayable recording
MovingBoundaries.pdf	reproduced, 0 errors, through the Kinematics tab
FRAPBinding_7.2.pdf	reproduced in full, 0 errors — both applications, run locally
PHGFP_7.2.pdf	reproduced in full, 0 errors — both applications, run locally
MultiAppTransport	image segmentation — genuinely out of reach
PathwayCommons	depends on a third-party service, current state unverified
2 × 6.1 rule-based	superseded by the 7.7 rewrite — don't reinvest
Quickstart, SpatialRuleBasedGuide	reference guides, nothing to script

No script touches File > Save or the green Run button: saving needs an account and Run dispatches a real job to shared compute. They use Native Quick Run instead, which executes with the bundled local solvers and saves nothing — so a scripted tutorial produces real results without an account and without putting anything on the server.

Reading results back is what makes the two multi-stage tutorials reachable. Each takes the steady state of its compartmental run as the initial conditions of its spatial one, the way the PDF's reader does — off the results table:

• FRAP with binding reads the end of the time course. Worth checking rather than trusting: rB equals rfB because RAN and RAN-FITC start at 5.0 each and compete symmetrically for the same sites; rf + rfB is exactly 5.0 and BS + rB + rfB exactly 20.0. Both conservation laws hold.
• PH-GFP must not read the end: an event fires at t = 5 s, so the last row is a stimulated state. It reads t = 5, the instant before the stimulus. A variable-time-step integrator picks its own output times, so there is no row number to hard-code — result_row_at_time binary-searches the monotonic time column, about nine reads, and cannot land on the wrong instant.

PH-GFP is also where the compartment rules earn their keep. PIP2_PM + PH_GFP_Cyt -> PIP2_PHGFP_PM joins a membrane species to a volume species, so the reaction belongs on PM — the interface where they meet — not in either compartment. Nothing in the UI enforces that, and typing the equation into a model that does not already have those species would have created all three in the reaction's own structure, silently and with no error.

The canvas problem

Every tutorial builds its physiology by drawing on the Reaction Diagram — "hover on the dotted black lines so they turn green". Those are pixel gestures on a custom-painted canvas, and the recorder deliberately never stores coordinates.

The way round it is that the diagram is not the only route. The Quick Start guide says so outright: species "can be specified and edited in both Structure and Reaction Diagram views". So the scripts drive the table views, where "type 20 in the Diffusion Constant column" is a sentence a script can say literally.

Most of this diff is bridge fixes, not scripts

simple-frap.sh did not work against the bridge as it stood. Each of these reported success while changing nothing:

• setText never committed. Much of the older GUI reads a field from a focusLost handler rather than on Enter (TimeBoundsPanel, the mesh and output panels). setText moves no focus, so mesh size, ending time and maximum time step were displayed and then discarded — the dialog reopened showing the old numbers. Fixed by calling the focus listeners directly; a synthetic FOCUS_LOST via dispatchEvent is dropped by AWT for a component that never held focus.
• doClick() never closed a menu. A real click dismisses the pop-up on its way to firing the action. The stale "New Application" submenu then shadowed the next text= lookup, and the failure surfaced several steps later, nowhere near its cause.
• click used doClick(), which invokes only the action listeners — the Kinematics "New" button shows its pop-up from MouseAdapter.mousePressed, so nothing opened. Buttons now get a real press/release.
• The recorder never stored which table column was clicked, and replay could not send one. Every tutorial sets values in named columns, so every recording replayed its edit into the wrong cell.
• Row text was the raw model object — Feature@4d973a55(name=EC), an identity hash that differs every launch — where findRow, setCell, the recorder and the /tree dump all meant "what the row displays". Replay silently fell back to positional indices.
• findRow only ever matched column 0. A spatial process's parameter table leads with a prose description and carries velocityX in the next column. Now findrow … --in Parameter.
• Tabs replayed by index, though the application tab strip differs between spatial (4 tabs) and non-spatial (5).
• text= selectors resolved in /find but nowhere else — pop-up items are exactly the components that need them, since VCell builds them without names. Added text=, type=, and active-window preference.
• trow is selectTableRow — on a JTree it returns {"selected": false} and does nothing. Two steps in the first version of the FRAP script were silent no-ops that only worked because the Geometry tab happened to already be selected.
• bridge.sh findrow word-split its query, so findrow "Analytic Equations (2D)" searched for Analytic and quietly selected the 1D row.
• A panel's columns arrive before its rows, so col succeeded while row returned -1. Lookups now retry rather than trusting a fixed sleep.
• Committing a field is still not enough for Edit Simulation. That dialog clones the simulation, edits the clone, and replaces the original only on OK — so a focusLost writes into the clone and closing the dialog is what writes the clone back. Leaving it open discards the lot, silently.
• /tree truncates a table to 25 rows, which is right for reading a UI and useless for reading a result: a steady state is the last row of a series hundreds long. Hence readCell — a row index (negative counts back) and a column by header.
• The results data table is not "showing". The results window opens on the plot with the spreadsheet as a hidden card that still holds the data, and two PlotDataTables exist — the document window has its own, empty one. Resolved by path within the results window.
• Copying an application copies its simulations, which keep the source's solver; and adding a geometry leaves the generated math stale, after which VCell refuses to open Edit Simulation at all. RefreshMathButton settles both.
• setCell could not tick a checkbox. The value arrives as text but a checkbox column's model casts it straight to Boolean, so a String threw on the EDT and the caller saw only a cell that had not changed. PH-GFP needs it: Stim has to be Clamped before its initial condition may depend on t.

No scripted verb drives the physical mouse any more. rrow, rclick, drow, dtrow and click's non-button branch all issued java.awt.Robot clicks at absolute screen coordinates — moving the user's real cursor, breaking if the window moved, and silently failing when the app could not be activated. They now dispatch AWT events. glide and robotClick keep the Robot; that is their purpose.

_common.sh's must helper stops a run when the bridge reports a step did not take. Most of the list above was found by it.

Naming debt, fixed at source

ScrollPaneTable and SortTable were each used by eight or more panels, so a lookup could land on the wrong table. SpatialProcessPropertyPanel called itself "SpatialObjectPropertyPanel" — a copy-paste slip giving two panels the same name. Named: the five model editor tables, SubVolumesTable, StructureMappingTable, SimulationsTable, SpatialObjectsTable, SpatialProcessesTable and their New/Delete buttons, SpatialProcessParametersTable, SpatialObjectQuantitiesTable, subdomainShapeComboBox, ten shape fields in AddShapeJPanel, the kinetics and plot-data tables, and — for the two later tutorials — EventsTable, EventActionsTable, EventSingleTimeTextField, OutputFunctionsTable, FunctionDomainComboBox, PreviousButton and FinishButton. Nothing looked any of these up by name.

A finding for whoever owns the tutorials

Simple FRAP never tells you to map the membrane. Mapping only EC and Cyt leaves PM reading Unmapped while the model still reports 0 errors — but VCell then picks SundialsPDE rather than Fully-Implicit. Followed literally, the tutorial can produce a different simulation than the one it is teaching. The script maps it and asserts the mapping resolved.

PH-GFP's spatial half is built with every diffusion constant left at its default, and the PDF never mentions them. Not something the script should fix by inventing numbers, but worth an author's attention: the whole point of that application is that the fluorescent signal spreads.

Separately: SpatialRuleBasedGuide is the only rule-based topic the 7.7 refresh did not cover — the gap in the current documentation set.

Running it without the window in your face (macOS)

VCELL_UI_BACKGROUND=true tools/debug-bridge/launch-client.sh adds -Dapple.awt.UIElement=true: no Dock icon, never becomes the active application, so it cannot pull you to its Space when a modal dialog opens. Verified by sampling the frontmost process through a full run. It does not hide the window, and /iconify reports a state the window server has not honoured in that mode — worth knowing before trusting the flag.

Verification

• All four scripts exit 0 with 0 model errors, each from a clean client. The FRAP simulation ends up with mesh 51×51, End Time 3.0, max step 0.01, output 0.05, and both Moving Boundary processes carry velocityX = 4, velocityY = 5*sin(10*t).
• PH-GFP's final state was read back and checked field by field: five structures mapped (PM → Cyt_EC_membrane, NM → Cyt_Nuc_membrane), the three analytic subdomains, Stim clamped with ((t > 5.0) && (t < 6.0)), the spatial simulation on Fully-Implicit at 20.0 s every 0.2 s, and Fluorescence = (IP3_PHGFP_Cyt + PH_GFP_Cyt) defined in Cyt.
• The recording replays from a clean client and rebuilds the same model.
• Existing scenarios unaffected: smoke.sh, detach-window.sh (18/18), detach-window-recorded.sh (15/15).
• mvn test -pl vcell-client -am -Dgroups=Fast: 606 run, 0 failures, 1 error — VCellDataTest, failing on ModuleNotFoundError: No module named 'vtkmodules', the missing-Poetry-env failure documented in CLAUDE.md, in a module this branch does not touch.

Note for reviewers

The bridge changes are behind -Dvcell.debugBridge=true and ship inert. The setName additions and the two renamed panels are the only changes to production UI code; setName is an identifier only, and files under vcell-client are CRLF with the additions preserving that.

🤖 Generated with Claude Code

https://claude.ai/code/session_019HAnpFxkzf9LmxBayDSANf