Numerus WebKit

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), but using conventional languages such as Java, JavaScript (JS) and Python. 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 document describes the NWK architecture, APIs and applications. Tutorials and documents describing example models are forthcoming.

NWK Architecture

NWK architecture revolves around 4 major structures:

• The Project structure (or Project "DNA"), a JSON structure contained in the project file that provides configuration data for all parts of the project.

• The Presentation structure, which supports visualization and user inputs in the browser. This structure is usually constructed directly in the Presentation API from the data contained in the Project structure.

• The Simulation structure, which contains the "business logic" for the model. This consists of 2 parts: the simulation API, which defines the data structures and methods used in the model, and the model itself. The simulation API supports the "turtle/patch" abstraction for agent-based models (ABMs), familiar from NL, but contains some additional capabilities, such as a network basis that substitutes for the patch abstraction, and support for system dynamics models using stocks and flows that can integrate with the ABMs. The simulation API is also configured directly by the Project DNA structure. Model designers can focus entirely on the model structure.

• The Dispatcher, code that facilitates communication between the Presentation and Simulation structures. Depending upon the choice of platform, this will involve the use of WebSockets, or simply function callbacks.

Definitions

This terminology will be used here to define various elements of the system. Refer to the diagram on the right to understand the organization of these items.

Simulator

For our purposes a simulator is a process that maintains a global state that evolves as the simulation is strobed over time. A simulation is initialized to some initial state, and incurs state changes following successive strobes from an external source (the clock). The state may consist of a single data value or multiple data values mapped out over the internal structure of the simulation. An example of the former is a simple simulation of exponential growth, where the current population is the only value of interest. The latter is exemplified by a spatial or agent based model where simulation state is distributed over individual agents or cells. One crucial property that we will insist be maintained is that changes to all parts of the state occur simultaneously. In other words, any algorithm used to determine one part of a new state only relies on the current or past state of itself and any other part of the state, so that the order in which different parts of the state are computed is immaterial to the outcome.

Clock

Clock refers to an external module that provides signals or strobes to the simulation for it to update its state. The clock is controlled from the user console in the browser and can be programmed so that the interval between strobes represents a particular interval of model time (called dt).

Presentation

All elements of the project pertaining to the visualization and input portal required by the project. These include the agent/cell display (the "display"), graphs, tables, etc. Specifications for this aspect are almost always covered by the contents of the Project file and require no attention from the model programmer.

Project file

A textfile containing a JSON object specifying the parameters that configure the elements of both the simulation and the presentation. Further details will be given below. Creating a project file is the first obligation of the model programmer with beginning a new project. The Project file is also read by the Deployment application for creating the directory structure and templates for the new project.

Dispatcher

This unit facilitates communication between presentation and simulation elements of the application. When a project is loaded into the browser and communication is established, the dispatcher initializes a new simulator with its required parameters. The dispatcher communicates control signals from the presentation to operate the simulator, and any parameter changes that result from user gestures on sliders, switches or other input components. In response, the simulator uses the dispatcher to forward data (called a status report) to the presentation that it needs to update its visual elements.

Architecture in Client/Server and Client/Client Modes

Depending upon the language chosen for programming the model, this architecture is mapped out either across the client and server platforms, or is contained entirely in the client.

Java Platform

Since Java is not native to the browser, programming the model in Java requires server-side support that can be provided using WebSockets. As shown in the illustration, the dispatcher is divided into two asynchronous units operating separately to serve the simulator and the presentation. The WebSocket