Session-based remote API, notebook testing, and usability improvements

[jcschaff]

Summary

Session-based remote API

• Add vc.connect() as single entry point — anonymous by default, vc.connect(login=True) for authenticated access
• VCellSession with run_sim(), start_sim(), save_biomodel(), load_biomodel(), list_biomodels()
• SimulationJob (from start_sim()) with .status, .wait(), .export(), .result() for non-blocking control
• Remove module-level remote functions from vc.* — all remote ops go through a session
• Split export_n5 internally into _submit_export / _await_export for future non-blocking export

Notebook testing infrastructure

• Lint (mypy) all example notebooks automatically
• Tiered execution tests: default, --run-interactive (trame), --run-remote (VCell auth)
• Fix broken notebooks: fielddata_trame, _internal_data_demo, _internal_vcell_publications
• Guide notebook tests now respect --run-remote flag

API usability improvements

• Field.expression property — generates vcField() strings, composable in formulas
• Field.__init__ with defaults — direct construction without circular create_fields() pattern
• Application.get_species_mapping(name) — convenience accessor
• SegmentedImageGeometry.get_mask(name) — boolean mask by subvolume name
• Fix to_segmented_image() to use subvolume names for image-based geometries

Trame widget

• Fix time slider bug (get_data expects time value, not index)
• Refactor state management: preserve valid selections across re-runs
• Add status bar, error handling, configurable iframe height

New examples

• image_field_data_demo notebook and script — synthetic microscopy image as simulation initial conditions
• docs/project-overview.md — project summary for presentations

Breaking changes

• vc.login(), vc.run_remote(), vc.save_and_start(), vc.wait_for_simulation(), vc.export_n5(), vc.load_biomodel(), vc.list_biomodels() removed from public API
• All remote operations now require a session: session = vc.connect() or session = vc.connect(login=True)

Usage

import pyvcell.vcml as vc

# Anonymous — public data
session = vc.connect()
biomodel = session.load_biomodel("279851639")

# Authenticated — full access
session = vc.connect(login=True)
store = session.run_sim(biomodel, "sim1")

# Non-blocking start, then explicit blocking calls
job = session.start_sim(biomodel, "sim1")
print(job.status)                            # polls once, non-blocking
job.wait()                                   # blocks until sim completes
store = job.export()                         # blocks until export completes
# alternatively: store = job.result()        # blocks for both (wait + export)

# Image data as initial conditions
field = vc.Field(data_name="microscopy", data_nD=image_data)
app.get_species_mapping("s0").init_conc = field.expression
result = vc.simulate(biomodel, sim.name, fields=[field])

Test plan

• make check (lint, mypy, deptry) passes
• poetry run pytest tests -v — all tests pass
• poetry run pytest tests -v --run-remote — authenticated remote tests
• poetry run pytest tests -v --run-interactive — trame/display tests
• Manual: run image_field_data_demo.ipynb in Jupyter, verify Trame widget

🤖 Generated with Claude Code