WebKit Users Guide
Numerus WebKit (NWK) is a technology for building powerful simulations that run in a Web browser. It consists of applications and APIs that support the design of models along the lines of NetLogo (NL) and Stella, but using conventional languages such as Java, JavaScript (JS) and Python.[1] These applications are deployed either from a remote server, such as Amazon Web Services (AWS) Elastic Beanstalk (AWSEB), (or, in Java mode, any other server that supports WebSockets, or in JS mode, from any conventional Web or Cloud server); alternatively, they can be run locally without using any network connectivity using a localhost server. JS development only requires text editing, and Java development can take advantage of the Eclipse J2EE (Jakarta) platform using the Apache Tomcat server.
This Guide will introduce the NWK user interface (UI) and the many useful functions that enhance and support the user's experience. A separate document, the WebKit Authors Guide, is under development.
Nomenclature
- Model
- A system that is initialized parametrically to an start state and is sequentially clocked to produce a new state and output vector on each clock strobe. NWK supports System Dynamic (SD), Spatial and Individual-based (IB) models. Models in NWK are currently implemented either in Javascript or Java.
- Simulation
- A model in execution. Simulations are managed from the UI.
- Project
- A single unit deploying 1 or more simulations, usually employing a single Web page. Projects are specified using a project file, containing JSON code detailing the UI and at least providing parameters for the model. Small SD models may be specified in the project file.
- "Factory Settings"
- Projects are delivered with parameters and settings determined by the author. Users may change parameters and override some setting, however factory settings can always be recovered.
- "The Drawer"
- The NWK screen has a sliding partition on the right-hand side, controlled by the user, that reveals documentation and other features detailed below when slid leftward.
- Presets
- NWK provides a storage facility to record and recall various choices for settings and parameters. The presets are like "radio buttons" selecting various alternative sets of configurations.
- RAMs
- RAMs (Runtime alterable modules) allow the author to provide the means for selecting sets of alternative algorithms used by the model. Authors may also use the RAM facility to enable a user to completely specify some model (these are called UberRAMs, or URAMs).
- "numml"
- numml (Numerus Modeling Language) is a small, simple, domain-specific language (dsl) that serves 2 functions: 1) to specify the algorithm or model in RAMs and URAMs; and 2) to assert configuration changes to factory settings.
- Analysis Platforms
- These are special tabs used in some projects to enable such facilities as sensitivity analysis, curve fitting, MCMC, etc.
- CSV
- This refers to the option of saving data from a graph to a comma separated list.
Platform Overview
This image shows the browser window running the sample individual-based project "Rock Paper Scissors". The features are all described later in this guide.
- Model Inputs
- These sliders set parameters for the simulation. Changes are forwarded even while the simulation is running and may have immediate effect.
- Timers
- These windows show the current model time. The left window counts up from 0. If the simulation is designed to run for a fixed time period, the right timer window will be initialized to that time and will count down.
- Operating Buttons
- The Connect/Disconnect buttons activate/deactivate the connection between the UI and the model logic. Disconnecting and Connecting is one way to restart the application; reloading the page is another.
- The Reset, Step and Start/Stop buttons operate the simulation. Step executes a single time step, Start/Stop bring about continuous operation, and Reset restores the initial state and resets the timers. Double-clicking Reset also reinitializes the application.
- Speed Control
- This determines the real-time interval between steps.
- Displays
- A spatial or agent-based simulation will include a "SimWorld" display that uses graphic cues to show the current state of the model. Among these cues are location and color, for both cells and agents, and, additionally, size and shape for agents.
- Other displays such as Spys (showing a single current value) graphs, tables, etc. are specified in the Project file (see below).
- Side Panel
- The browser page has a side panel contained in a "drawer". Use
to toggle it open and closed, or pull on the lavender bar to adjust its location. The drawer contains model documentation, the preset display, a configuration window, and a log window for status reports. If the project uses RAMs the side panel will be wider and will contain access to RAM controls.
- System Dynamics
- The third image shows the sample SD Lotka-Volterra project. An SD project will display the current choices for dt and integration method (Euler or RK4). These can be overridden from factory settings using the configuration window.
WebKit Tutorial
In this section we elaborate on the platform's features, and illustrate with one or more of the sample projects in the model library. The full model library can be found in the WebKit Examples document. Note that we will be looking at the Javascript model implementation only at this time, as some of the features described here are only available with this implementation.
Model Initialization and Using Presets with Conway's Game of Life
Conway's Game of Life (CGOL) uses a 128 x 128 board with solid edge and an initial configuration consisting of the "R-pentomino". (Try it!) With NWK you can:
- "Draw" and execute a new initial configuration;
- Save your configuration in the Presets.
Drawing a new initial configuration
To alter the initial configuration, press or click the left mouse button on any black or white cell to toggle that cell to the opposite color. If you press the mouse button, you can drag the mouse to change dragged-over cells to the new color. When done, click the Reset button once; clicking Run will execute the simulation with the new configuration, and single clicks on Reset will restore your initial configuration. Double-clicking Reset restores factory settings.
Preset Basics
The Preset feature provides a quick way to save and restore a configuration, modeled on the "radio buttons" found in cars. The Preset
- ↑ This API is under development.