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

Basic Architecture

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

Java Architecture

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 is a robust protocol that manages communication with significant fault tolerance. This robustness translates to a highly robust execution environment for the final application.

The preceding remarks also apply to Python or other model logic coding using an appropriate server. Our experience with Java makes use of the Apache Tomcat server and the Eclipse J2EE design platform. Deploying Tomcat applications is particularly easy: the code is archived in a ".war" file and dropped into a Tomcat "webapp" directory (or, in the case of Elastic Beanstalk, uploaded to the server). Subsequent updates simply overwrite the archive. To reiterate, an external server is not needed if one uses Eclipse J2EE or installs a local Tomcat server. One part of the NWK project will eventually be an application to facilitate local deployment.

JavaScript Platform

JavaScript Architecture

The JavaScript platform requires no special server features inasmuch as the entire application is downloaded and run in the client. In this case we maintain the same communication regimen but replace the WebSocket with a local function callback protocol. Consequently the client/server and client/client configurations offer identical structures, which facilitates Numerus' obligation for program maintenance of these platforms.

Directory Structures

Java Platform

Java Directory Structure

The picture shows the directory structure of the Java platform, following the conventional layout used by Tomcat. Each subdirectory of the java directory contains files for implementing the model logic of that simulation. These are generally the only code files that are developed by the programmer. The subdirectories of webapp each contain the HTML code for the application and have the identical structure shown on the left.

Java Application Directory Structure

The 3 HTML files are automatically generated by the deployment app from data contained in the Project DNA file. The js subdirectory contains the Project DNA file itself (i.e., "life.js"). To reiterate, the model programmer generally does not have to edit these files.

Presentation and Dispatch Structures

The second picture on the left shows the JavaScript, CSS and image files used to implement the Presentation and Dispatch elements of the application. Among these, the file main.js contains the drivers for the dispatcher, input and visualization components. Code for particular components (e.g., lchart.js for linechart, etc.) are contained in their respective files. These are all contained in directories below common are are referenced by the entire set of application HTML files.

JavaScript Platform

JavaScript Directory Structure

The JavaScript platform is simpler as it does not require a separate directory region for model logic. The common directory is extended to include the JS model API, along with the same files used for Java Presentation support, with a small change to substitute callbacks for WebSocket interactions.

JavaScript Application Directory Structure

Looking at the JS application directory, we see the same 3 HTML files, but now the js subdirectory contains additional files implementing model logic. Note here that the Project DNA file is labeled life.prj, so that life.js identifies the main class file for the model logic component. It is worth noting once again that the deployment application creates these files under the guidance of the Project file, and generally need not concern the model author.