Pop1

This very simple Ramp introduces the advanced features.

Obtaining Pop1

Fig 1. Studio after installing Pop1

1. Download the file Pop1.xml from here.
2. Launch Numerus Studio and select the File | Open Ramp(s)...; navigate to the folder containing Pop.xml and select it.
3. When you are done Pop1 should appear on the Numerus Studio dashboard. (Fig. 1)

"Discovering" Pop1

1. Launch Pop1, resulting in the application shown here:

Fig 2. Pop1 Ramp

2. Open Help | About This Ramp... to learn about the model and its structure, as shown here:

Fig 3. Pop1 Documentation

The document provides a description of the model and its salient parameters, variables, etc.; use this to familiarize yourself with the model. A link appearing in the title section will lead to more in-depth documentation.

This model of population growth uses a variable deriv (airport code DDT) to encode the derivative of population change. The default version produces exponential growth using a growth rate parameter r (airport code RTE) which can be set using a slider.

The Ramp includes 3 RAMs that provide alternate growth schemes. These include one for logistic growth, and two more that encode respectively exponential and logistic growth using a random rate that is selected at the beginning of the run and is fixed throughout the run. This random rate uses the identifier rand, (airport code RND) and is selected from the interval [0, r).

3. You now have an opportunity to test what you learn from the documentation by possibly running the simulation several times with different parameter values.

Fig 4. Pop1 Default Run

Using RAMs

The documentation points out that a RAM exists for overriding the default definition of deriv.

4. Visit the RAM page either by double-clicking on the blue text of the RAM entry, or by clicking the Op On/Off button.

Fig 5. RAM Management Portal

The left pane of the RAM portal gives a general description of the element being altered. The 4 alternatives are viewed by clicking the radio buttons. Above each alternative is a description of the effect of that alternative. The first (default) implements exponential and the second logistic growth. Both use parameter r as growth rate; the second has a fixed carrying capacity of 50. It is apparent that the code used to implement these two models closely follow the equations; note, however, that each element appears as a function of 0 arguments. This is the standard approach used for coding in the Numerus Designer.

RAMs 3 and 4 are variations on 1 and 2, respectively, substituting rand for r. Recall that rand represents a random value selected from [0, r) at the beginning of each run and fixed for the duration of that run.

A definition in red indicates that the code has not yet been compiled; i.e., translated into runnable form. The default RAM is compiled when the Ramp is launched. Clicking the compile button performs this translation on override RAMs, following which the new version of the model is ready for use. Compilation of RAMs is generally handled automatically when you first click the Reset button before running the model with a RAM other than the default.

You may add your own RAM to the set by clicking on the + button. As a point of departure you can insert the default definition by clicking the Default button. You should make sure that your code compiles before attempting to use it. You can also test the RAM directly with the Test button, and compare its result with a test of the default RAM and any other defined RAM. A keyword entered here will appear on the RAM dashboard to remind you of the change in the model brought about by the RAM. You can also include your own documentation in plain text above the definition.

Here is a new RAM that defines the derivative as r * Pop^1/2.

Fig 6. Adding a new RAM

When you are ready to proceed, close the RAM portal. The RAM selection dashboard uses a spinner to select the RAM to be used in the next run. It also shows the keyword associated with the RAM and its status (red for uncompiled, green for compiled.) Never run a model showing a red RAM in the dashboard. Clicking the Reset button will attempt to compile the RAM. If the dashboard entry remains red, then the RAM contains errors and should be fixed.

If you add a RAM to the collection be sure to save your Ramp's settings (or save the workspace) or else your new RAM will be lost

RPL Scripting

5. Open the Scripting Portal using the button S On/Off. It contains the following script:

Fig 7. Scripting Portal

Let's consider each entry in the script:

reset

Resets the simulator; this should be the first statement of any script.

set DDT 1

DDT is the airport code for the deriv RAM. Index 1 is assigned to the logistic growth model.

restart

This command needs to follow the change in model. It re-initializes the simulation.

compare_on PCT

Sets the graph (airport code PCT) to comparison mode, in case it wasn't already.

clear PCT

Empties the graph of earlier runs, if necessary.

set RTE 0.01

Initializes the rate parameter (RTE) to 0.01

run_for 200

Executes the simulation for 200 steps.

restart

plus RTE 0.01

run_for 200

restart clears the simulation without returning the parameters to their pre-script values;
plus RTE 0.01 increments the rate parameter;
run_for 200 runs with the new settings for 200 steps.
This sequence is repeated 4 times.

Try running the script. Turning on logging shows each command as it is executed. You can also try stepping through the script line by line.

The result of running the script is shown below:

Fig 7. Script Run

Exercise: What single change do you have to make to the script to produce similar results using the exponential growth model?

Using Javascript

Javascript is an important programming language used extensively for scripting Web applications. Numerus Studio includes a Javascript runtime engine for executing more sophisticated scripts than can easily be run using the RPL portal directly. The latter is useful when developing in Javascript to test various RPL codes before incorporating them in a full Javascript program.

Fig 8. Javascript Example

Opening the Javascript portal you will find a program designed to accomplish the same task as our previous example, but more expressive in several ways. First, instead of necessarily repeating lines of code in the RPL example to perform the same task with a different rate parameter, we use a looping structure (lines 6 through 10). Secondly, we abstract the inline RPL program into a Javascript function with parameters mode len and runs; the mode parameter can be 0, 1, 2, or 3 depending on which RAM we want to use. The runs> parameter determines the length of the run, len the number of runs, and <r> value of the r parameter. If these parameters are omitted, the program defaults to exponential growth with a runtime of 200 and 4 runs. The default choice of r depends on whether we are running a deterministic (modes 0 or 1) or nondeterministic (modes 2 and 3) simulation. Similarly, incrementing r depends on the same choice of mode. Notice that the same set of RPL commands is used (accessed through the $$ object) as in the direct RPL version.

Our go function, which facilitates a default operation, is set up to run identically to the RPL script.

This program also illustrates the two ways one can reference RPL commands from Javascript, using the $$ object. Line 4 shows a call to $$.dispatch containing a sequence of initializing RPL commands represented in a single string. Lines 5 and 7-9 call individual RPL operators using their equivalent $$ entries.

Exercise: run different variations of this program by typing runit(...) with different values for mode, len, runs and r.

Using R

As described in the User Guide, the RPL API can be access remotely from most other platforms; including R, Javascript and Python. Numerus has simplified integration with the R platform through the nmbR package downloadable from the Studio Website.

Below is a demo program Pop1.R using nmbR' that duplicates the functionality of the Javascript program described above, adding to it data retrieval after the run, and computation and plotting of mean ± standard deviation.

Fig. 7 R program

The runit function duplicates the Javascript function of the same name. The key element providing the interaction between R and the Pop1 Ramp is the nmbR package function nmbR$iterate_v on line 25. This function captures the behavior of the Javascript looping structure. Parameters prelude, interlude and postlude represent RPL instruction strings that are sent, respectively, at the beginning of the run, between each loop, and at the end of run (if any are NULL nothing is sent). At the end of the run the time sequence of one or more variables is retrieved and represented as an R dataframe. You can view this result by loading Pop1.R and executing runit(), with zero or more choices for mode, etc. Also try runit_mstd and plot_mstd.

Fig. 7 Graph of plot_mstd(mode=3)

Conclusion

This simple population model has been used to demonstrate the various novel features of Numerus Studio as a simulation platform. Successful use of Numerus Studio requires good documentation. Ramp designers are expected to provide such documentation either on board or through supplemental documents.

• When opening a new Ramp always visit the About This Ramp... documentation to understand the landscape of the underlying model.
• If RAMs are included, visit the RAM portal to view their descriptions.
• If RPL and/or Javascript and/or R scripts are included, they should be documented, either in the on-board documentation or in a supplemental document reached by the Ramp URL.

---