Ramp User Guide

Ramp Platform Overview

The Numerus Ramp (Runtime Alterable Model Platform) is a well-documented packaged simulation program with added features for runtime control and operations. These include:

• An API language for managing runtime properties such as parameter values and run operations.
• An onboard Javascript interpreter extended to access the API, allowing the creation of scripts to control operation.
• A local server enabling remote control of the API. This permits full integration with the R statistical platform when using the nmbR library package, also available from Numerus.
• Access to selected operator definitions used by the model, permitting user-defined alternatives to the model algorithm (RAMs).

Ramps are created using the Numerus Designer, a new version of the Numerus Model Builder that uses a visual GUI-based design platform for specifying models in the system dynamics, spatial, agent-based, network and event-driven paradigms. The Numerus Designer presents a more compact and simpler approach to model-building than earlier versions by providing powerful components to implement simulation actions. An entirely Java-based runtime engine implements more efficient and less resource intensive operation than before.

The Ramp Application

Fig 1. Ramp App

Fig 1. Ramp Controls

Each Ramp implements a single model using a common GUI platform, as shown in Figs. 1 and 2. Here is a description of the features of that platform:

Elapsed Model Time The current time in model time units.

Runtime Features These include pages for the following:

• S On/Off Displays/hides the API Script page. See Using API Scripts
• Op On/Off Displays/hides the RAM operator override page See Using RAMs
• JS On/Off Displays/hides the Javascript page. See Using Javascript

Parameter Sliders Use these to control input values. Values may be entered directly into the slider windows.

RAM Controls Use these to control the use of RAMs (runtime alternative modules). Double-click to access the RAM page for the selected RAM. See Using RAMs.

Model Displays Graphs and other displays used by the particular Ramp.

Remaining Model Time Remaining model time in the run.

The following may or may not be included depending on the Ramp.

Random Number Generator Seed and Restart Policy The user may optionally include a seed value (an integer) for the random number generator (RNG). When the RNG is restarted it will produce the same sequence of random numbers. The RNG is restarted when a new seed is entered or when the Reset button is double-clicked. If the Restart RNG on Reset box is ticked, then the RNG is restarted each time the Ramp is reset. RNG restart is indicated by a flash of yellow in the Seed text field.

Integration Method Used by system dynamics. Available methods are Runge-Kutta 4 (RK4) and Euler. There is also a Discrete method which is equivalent to Euler with DT = 1.

DT Interval of numerical integration. Models not using system dynamics will set the Integration Method to Discrete, which in turn sets DT to 1.

Simulation Speed Used to slow operation if needed.

Operating Buttons These consist of:

• Reset Sets the clock to 0 and restores initial values.
• Step Performs a single simulation step, advancing the clock by DT.
• Run Initiates steps in sequence and toggles to Stop. Clicking the Stop button halts operation. Subsequent clicks to the Run button continue the simulation from the stopping point until total model time has elapsed. A reset restores the simulation to initial conditions.

Remaining Model Time This field is initially set to the length of the run and counts down as operation proceeds.

Menu Items

File Menu:

Settings Ramps are delivered with "factory" settings determined by the Ramp designer. Settings determine the values of sliders, selections of RAMs to be used, contents of the script page, and simulation parameters such as DT and integration method (if appropriate). It also determines CSV properties, as discussed below. Users may make changes as needed to any of these properties, and such changes become part of the state of the workspace.

The current workspace state may be saved in two ways:

• Using a named settings file with Save Settings (or Save As...) for subsequent reloading with Load Settings. These settings will be automatically reloaded in the next session unless New Settings is selected.
• Using Save Workspace Image to ~/.Ramp. NMBStudio creates this directory in the users home directory to hold workspace settings. The image is automatically reloaded when the Ramp is next launched. (Users will be prompted to save workspace settings when exiting the Ramp if any changes have been made).

Reset to Default Config restores the factory settings provided by the designer. All changes by the user will be lost, and the factory workspace will be saved to the workspace directory.

CSV Menu

CSV selection

The Ramp designer can designate particular components and graphs as being available for saving to a CSV (comma separated values) file. The CSV selection window lets the user choose which components to save, the sampling interval, and the directory for the CSV file. Selected components are listed in separate columns in the CSV file.

If Autosave is selected, CSV files will be saved after each run. A CSV file is given a unique filename containing the name of the Ramp with date and time. Otherwise the user must explicitly save the CSV file after a run or the data will be lost.

Ramp Doc

Help

About This Ramp opens a documentation window that describes parameters and other elements of the model, as detailed by the Ramp designer, and may contain a link to more extensive documentation. It should be viewed by all users of the Ramp. See the example shown here.