Feature/prefetching

[interim17]

DRAFT
Still sorting out the last details of keeping remote playback time in sync with local, and what to do when hitting the cache limit in various states

Time Estimate or Size

medium

long discussion below!

tl;dr is we can probably merge this feature with basic review, but this work might usefully branch into some deeper refactoring

Problem

Closes #423 advances #424

Solution

This is a working prototype or version of prefetching frames from networked/precomputed simulations. The primary idea here it to make explicit the difference between playback and streaming.

There are places now where the two are somewhat conflated, as in "pausing" means "pausing the stream of frames from the back end" and also means "stop advancing the rendered frame in the viewer"

• Previously in viewport: isPaused -> now: isStreaming and isPlaybackPaused
• Expose a callback in the cache to log changes and observe the growing size, first and last frame number, etc.
• Small component in test bed to print these logs
• Renaming controller methods to make explicit whether they relate to playback or streaming control

I had a chat with @toloudis and looked at this todo in the ISimulator:

    /**
     * Simulation Control
     *
     * Simulation Run Modes:
     *  Live : Results are sent as they are calculated
     *  Pre-Run : All results are evaluated, then sent piecemeal
     *  Trajectory File: No simulation run, stream a result file piecemeal
     *
     */
    // these should probably be abstracted to just "start"
    // and have a separate interface for initialization?
    // For example, "start" = initialize, and "resume" = play
    startRemoteSimPreRun(timeStep: number, numTimeSteps: number): void;
    startRemoteSimLive(): void;
    startRemoteTrajectoryPlayback(fileName: string): Promise<void>;
    sendModelDefinition(model: string): void;

I'd like to get some opinions and form a plan on touching up ISimulator and the websocket messaging protocol naming, in conjunction with the front end clarifying the naming of what is playback and what is streaming/communicating with the backend. This will be another step toward making live mode a reality, and building on the work @blairlyons and @ascibisz have been doing on the BioSimulators API.

There was also discussion of whether the SimulariumController, which was originally intended to expose controls that the website might access, is doing to many things, and some new abstractions for managing streaming and loading of trajectories would be in order.

I definitely don't want to charge into these APIs and start making a lot of changes, but looking at the todo above and chatting with @toloudis about it I do think its a good moment to step back and look at this! Maybe a good topic to touch on at PM meeting on 12/10 or go more in depth at dev meeting 12/17? Or bump to 2025.

Either way, this feature branch works, makes prefetching a thing, and can move forward independent of the discussion above, but it's all connected.

Steps to Verify:

1. Inspect the log outputs with the button at the bottom of the viewer controls, and how they relate to playback.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🔴	Statements	42.42% (+0.05% 🔼)	2181/5141
🔴	Branches	45.06% (-0.06% 🔻)	917/2035
🔴	Functions	38.99% (+0.04% 🔼)	455/1167
🔴	Lines	42.67% (+0.05% 🔼)	2092/4903

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🔴	... / VisData.ts	57.66% (-2.95% 🔻)	48.21% (-3.79% 🔻)	57.69% (-4.81% 🔻)	57.41% (-3.01% 🔻)
🟡	constants.ts	78.57% (-2.2% 🔻)	100%	53.85% (-4.49% 🔻)	77.78% (-2.22% 🔻)
🟢	... / VisDataCache.ts	80.15% (-0.68% 🔻)	70.27% (-1.29% 🔻)	86.11% (+0.4% 🔼)	81.45% (-0.85% 🔻)
🔴	viewport/index.tsx	13.95% (-0.05% 🔻)	10.39%	13.95%	13.51% (-0.05% 🔻)
🔴	... / index.ts	7.53%	7.14% (-0.12% 🔻)	5.69% (+0.05% 🔼)	7.5%

Test suite run success

144 tests passing in 16 suites.

Report generated by 🧪jest coverage report action from 9779253