The Ramp API

The Ramp API (Application Programming Interface) uses a simple language called RPL to manage and operate Ramp simulations and retrieve data for remote processing. It can be used in three ways: directly, through the RPL Scripting Portal (S On/Off button); indirectly through the Javascript RPL Portal (JS On/Off button); and remotely from other platforms such as the R Statistical language.

Using RPL

Fig 1. RPL Scripting Portal

RPL is simple bytecode with instructions for adjusting parameter values, controlling runs, and retrieving data. There are RPL instructions to perform virtually any task a user might perform directly by changing sliders, adjusting runtimes or saving data to CSV files. RPL scripts are saved as part of the saved Ramp settings and workspace settings.

The RPL Portal contains left and right windows. The left window is an RPL interpreter, which executes a sequence of RPL commands. The right window is an editor for creating scripts that can be loaded and run by that interpreter. Scripts can be loaded in their entirety and run, or executed line by line. Improperly formed commands are not executed and there is no error report.

The Logging window (below the interpreter), when enabled, shows the actions taken by the system for each command. It is especially useful when using the API remotely.

The RPL Reference sheet can be viewed using the Command Reference button on the RPL Scripting Portal. It is shown below in Fig 2.

Each instruction in RPL consists of an op code followed by 0 or more arguments. The XXX arguments refer to Airport Codes, as described in the Ramp User Guide. Fig. 3 reproduces the Notes on the reference sheet.

Scripts entered into the RPL Scripting Portal can saved and reloaded.

Example

Fig4a. Script Before Execution

Fig4b. Script After Execution

Fig4c. Resulting Graph

One particular use of the Scripting Portal is for managing multiple runs with different parameters. The example shown in Fig. 4a is a script for the Pop Ramp that flips the graph into comparison mode and runs the simulation 5 times, incrementing the rate parameter by 0.01 each time. Clicking Run Script executes the script line-by-line (Fig 4b) and produces the graph shown in Fig 4c.

Note: the operation restart rather than reset is used between runs. Reset returns the parameters to their values before the script was run.

Using Javascript

Fig. 5 Javascript RPL Portal with Script

The RPL Scripting Portal is especially useful for building and testing scripts. However since the RPL language contains no control structures, the Javascript RPL Portal provides a richer programming environment for scripting Ramps. The console (left window) in this portal is a complete Javascript runtime extended by an object bound to $$. This object contains functions corresponding to each of the RPL operators, plus the function dispatch, which can be used to invoke a sequence of RPL commands as strings. Both usages are shown in Fig. 5, which executes the same script as in the previous section but using a loop structure to achieve greater economy. The use of $$.dispatch shows how command can be sequenced in one line.

The Go button provides a convenient way of executing a script. If the entry point of the script is defined as the function go(), clicking the button will invoke the script, so that typing into the console is not necessary.

Note: If a JS script fails to execute the first time after being loaded, click Reset Console and reload the script.

As with RPL scripts, JS Scripts can be saved and loaded, and any script left in the editor will be part of the Ramp settings.

Remote API Access

When a Ramp is launched it uses your computer's internet facility to listen for and respond to RPL commands as if they were coming from the RPL Scripting or Javascript Portals. Any other program running on your machine can address the Ramp using the port number that appears on the Scripting Portal.

Each Ramp launched from Numerus Studio is assigned a distinct port number, beginning with the base port shown on the Studio dashboard. The number assigned is either the base port or the smallest number larger than any port currently in operation. The port number also appears on the title bar of the Ramp. Note that if only a single Ramp is launched it will always be assigned the base port number. Numerus Studio is distributed with base port 8585. In the unlikely situation that this port is already in use on your computer for other purposes you can change the base port on the Studio dashboard, and subsequent launches will use the new base port.

Remote API access enables integration of Numerus Ramps with other programming platforms such as Python, Ruby, etc. and in the future could allow Ramps to communicate with each other. The R statistical platform is an obvious partner for operating and analyzing Ramp simulations. Details are in the next section.

R Integration

To facilitate integration with R we have created the nmbR package which can be downloaded from Numerus and installed into the R environment. To install the R package execute

install.packages(".../nmbR_0.1.0.tar.gz", repos = NULL, type = "source")

where ... is the path to the tar.gz file obtained from the download.

Here is the current list of nmbR functions, taken from the "help" page for the package:

The principal function in this package is nmbR$dispatch(s), where s is a string of RPL commands. This function sends the RPL string to the Ramp and returns the Ramp's reply.

The function nmbR$frame is used to retrieve data from the Ramp and return it in the form of an R dataframe. Similarly, nmbr$graph will graph these data as a time series.

Please refer to the example R scripts downloadable from Numerus for further details. Examples also appear in the package's "help" page.

This package will likely grow in size in future releases as more is learned about ways that R and Ramp simulations can interact.

---