Adamastor: Getting started

Getting started: the model, a first run, and the header bar

What this is

Adamastor is a browser-based weather model. It includes QG Cyclones, two to eight layers of quasi-geostrophic flow on a doubly periodic plane, a walled channel or a hemispheric polar cap. A zonal jet with vertical shear is baroclinically unstable, so a small perturbation grows into a train of wave cyclones that interact, merge and are eventually arrested by bottom friction. The model generalises pyqg’s two-layer model to N layers and is held to the reference’s own numbers by the test suite. Its physics and parameters are documented in docs/models/qg-cyclones.md.

The solver is written in C, compiled to WebAssembly and embedded in the page. It runs entirely in the browser. Nothing is uploaded, and once loaded the app works offline. Play integrates the state forward. The clock reports model time, and every displayed field is diagnosed from the solver’s current state.

The app is plain static files with no build step. It consists of adamastor.html, app.js and the ui/ kit beside them.

Quick start

Open adamastor.html. The launcher card appears on the left. Serving the folder over HTTP (node serve.js from the repository root, then http://localhost:4173/adamastor.html) enables the Preset picker, which browsers block on file://, and the multi-core kernel, which needs cross-origin isolation headers that only a server sends. Import works offline either way.
Choose a source. Select a Preset, paste a saved design as JSON under Import, or start from Blank. The stage shows a live preview of the design.
Press Next. The Builder opens. Step 1 sets the domain and step 2 the vertical column. A hemispheric domain adds a third step, the Compute card. Next advances a step, Back returns one, and the Setup control at the top left of the stage returns to the Launcher from any step. An import whose snapshot is kept skips the design steps. A kept hemispheric snapshot stops at the Compute card, where there is no Back.
Press Initialize on the final step, or in the Launcher itself for a flat design launched from a kept snapshot. The panel becomes the control panel and the viewport opens to full size.
Explore the run. Switch views with Map, Observables and Split in the header. The eye opens View Settings. The tool pill selects Pan/Zoom, Perturbations or Terrain. A brush tool’s controls occupy the display dock along the bottom of the window, beside the Projection column and, under Perturbations, the Land column with its Show land tick.

The header bar

Stage label	Reads START in the Launcher and BUILDER in the Builder. After Initialize it shows the model’s name.
View	Switches between Map, Observables and Split, which places the Observables beside the Map.
Tool pill	Sets what the pointer does on the map. Under Pan/Zoom a drag pans, the wheel zooms, a double-click resets the view, a stationary click samples the map and opens a Sample window, and a right-drag or an Alt-drag pivots the polar cap or moves the Winkel Tripel cut. Under Perturbations a left click drops a vortex or a thermal patch in the layer the dock’s Layer stepper names. Under Terrain a left drag paints the type the dock’s Terrain type pill selects. In both brush tools the right button pans, Alt with a right-drag pivots, and the wheel zooms. A brush tool’s controls replace the display dock’s view columns. The Projection column, shown on a hemispheric domain, stays under both, and the Land column with its Show land tick stays under Perturbations. Terrain pauses the run, disables Play and the View Settings buttons, hides the fields and the sea ice, and draws a flat blue sea. The pill is disabled in the Observables view and under the Orthographic projection, and the tool returns to Pan/Zoom.
Eye	Opens View Settings, which governs how the current view draws. For the Map that is the General card (Sync layer choice, grid lines, projection, periodic images, the land’s look and the climatology readout), the shading, two contour sets, the shape layer, crosshatching, tracers and overlays. For the Observables view it is the observable class, the per-series ticks, the Time window, the Time average choice, Reset running averages and grid lines. Disabled under Terrain.
Bars	Shows and hides the floating Statistics window.
Expand	Full screen for the stage and the control panel. The panel hides and reappears when the pointer reaches the right edge, and the display dock does the same at the bottom edge. `Esc` exits.
Sliders	Shows and hides the control panel.
Home	Start Fresh. Returns to the Launcher as it was last initialised, with the view and the tool at their defaults and the display settings at their defaults, or at the source’s look where a Preset stores view settings or an Import’s view box is ticked.
Back to Builder	Discards the run and returns to the Builder. Edit the design, then Initialize starts a new run. For a run launched from a kept snapshot the button reads Back to Launcher and returns to the Launcher.
Reset Simulation	Rebuilds the initial state from the current design, or restores the saved state for a run launched from a kept snapshot, returns the clock to zero and pauses.
User Guide	Opens this guide in a new tab. It is a labelled button before Initialize and the ? icon afterwards.
Play / Pause	Advances the clock. The button at the far right, or `Space` anywhere except while a field, dropdown or button has focus. Disabled under Terrain.

Adamastor — a browser-based quasi-geostrophic weather model.