Two reference guides on vcell.org have gone stale: six statements no longer match the client

Open
  • Is something wrong?
#2,069 0 comments 0 reactions 2 assignees View on GitHub

Maintainers usually reply within 1 day

@vcellmike is already working on this.

Since Sep 7, 2026.

Assessment

This issue has not been assessed yet.

Description

User Materials

Six statements in the two reference guides on vcell.org no longer match the client. They were found by driving a current client and checking each claim, not by reading — the checks are quickstart.sh and spatial-rule-based.sh in #2067, and both print exactly which claims hold and which do not.

VCell_Quickstart_7_Biomodel.pdf (2019)

1. "diffusion constants… default to zero for each molecular species" — the one worth fixing first.

A new volume species in a spatial application defaults to 10.0 µm²·s⁻¹; a membrane species to 0.1. Nothing defaults to zero. The tip goes on to say that zero "is always illegal when a molecule is involved in a membrane flux", so a reader who believes it goes looking for a problem that does not exist — and may "fix" a diffusion constant that was already fine.

2. "a spherical cell with a 10 micron diameter is 523.33 micrometers cubed"

(4/3)·π·5³ = 523.5988. Low by about 0.05%. Small, but it is a worked example that readers copy, and it is the one claim in the document checkable without opening VCell at all.

3. "VCell supports VCML and SBML files" (describing File > Import)

The import filter now reads .xml .vcml .sbml .vfrap .bngl .omex .sedml .ssld — eight formats. Not wrong so much as long out of date, and .bngl in particular is worth naming: it is the only way to build a rule-based model without going through the graphics editor (see #2068).

SpatialRuleBasedGuide.pdf (2017)

This document has a structural problem as well as three factual ones. The July 2025 refresh produced 7.7 rewrites of the two single-compartment rule-based tutorials but not this one, so spatial rule-based modelling is the only rule-based topic with no current document — and this nine-year-old file is where a reader lands.

4 & 5. It sends readers to two tutorial models that are no longer there.

It says to compare against Mix_Reactions_Rules ("one can mix reactions and reaction rules") and RB_Enzyme_Kinetics ("one can put expressions depending on Species as forward and reverse rates"). Neither is in the Tutorials folder. Rule-based_Ran_transport, the model the guide is built around, is still there.

6. "Only mass-action kinetic laws are supported" — this limitation has been lifted, at least in part.

The guide lists it under "Limitations compared to stand-alone tools (temporary, will be lifted in future releases of VCell)". Selecting a reaction rule today offers two kinetic types:

Mass Action ( for each reaction: Kf⋅Π reactants - Kr⋅Π products )
Henri-Michaelis-Menten (Irreversible) [μM/s]

Because this is the only current document on the topic, it is the only place a reader would learn otherwise — so the stale limitation is doing real work here.

The other limitations in that list were not all checked. "Molecules cannot have identical sites" still holds, and VCell says so plainly when you try: "Site 's' already exists in Molecule 'Twin'! Multiple identical Sites not supported witin a Molecule." The 800-species / 2,000-reaction caps were not checked.

Still true, for the record

Four panes; the Fast checkbox on the reaction specifications; MatLab and PDF among the document export formats; Quick Run without saving to the database; the units-and-volume prompt on BNGL import; and BNGL import creating two applications (now named BioNetGen app and NFSim app, not the bare BioNetGen and NFSim the guide uses). New Application still offers Deterministic, Stochastic and Network-Free — and SpringSaLaD, which the 2017 guide predates.

Not checked, deliberately

STL, AVS and GIF export. The Quick Start attributes these to the geometry surface viewer and the physiology cartoon, which are separate panels with their own export actions. They are absent from the document export list, but that list is the wrong place to look, and reporting them missing on that basis would be wrong.

Two other things worth knowing for anyone re-checking this: the export format list is content-dependent (an empty BioModel is offered five formats, one with content ten), and the MatLab claim is conditional on a compartmental application — it reads as false against a spatial-only model. Both produced confident wrong answers before the checks were corrected.

Minor and separate, noted so it is not lost: VCell's own error message above has a typo — "not supported witin a Molecule".

Dominant language
Java
Stars
140
Forks
35
Avg merge
11h 28m
Merged PRs (30d)
19

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from virtualcell/vcell

All issues in virtualcell/vcell

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.