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.

Project File Contents

We now provide a brief overview of the Project DNA file. Contents will vary depending on the specific needs of the simulation application, so this is merely a cursory look. Designers will benefit from existing Project DNA files when building JSON structures for their applications. The following descriptions refer to the sample Project DNA file shown at here. Note that the order of entries is immaterial.

Lines 1 - 9: Title, Directories and Frame Size

Lines 2-3, Name, Title

The Name will be used as a prefix for all model logic files generated by the deployment app. The Title is the title of the HTML main frame and appears at the top of the page.

Lines 4-7, Directory Specifications

The jroot and jsroot entries point respectively to the Java and JS root directories of the application. The jbase and jsbase entries are subdirectories representing Eclipse projects that hold 1 or more related applications. The deployment application uses these entries to construct directories, HTML files and model logic templates.

Lines 8-9, Width and Height Specifications

These specify the size of the main frame in the browser. They can be adjusted as need as the application takes shape.

Line 10, VisitMode

This is used by the model API to configure the main loop of the program. It will be discussed in detail later.

Lines 11-17, Cell Specifications

These configure the cell matrix of a spatial or agent-based model.

Line 12, cellSize

cellSize indicates the number of pixels used by each cell in the display. In the coordinate system of the cell matrix each cell occupies a 1 by 1 square. CellSize maps that to specific spatial coordinates on the screen, making it easy to re-scale the visual display.

Line 13, palette

The palette is a list of CSS colors using the "#xxxxxxyy" format. Row and column dimensions define the operational space of the model (lines 14, 15).