Difference between revisions of "Ramp User Guide"
Jump to navigation
Jump to search
| (25 intermediate revisions by the same user not shown) | |||
| Line 7: | Line 7: | ||
*Access to selected operator definitions used by the model, permitting user-defined alternatives to the model algorithm (RAMs). | *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. | 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== | ==The Ramp Application== | ||
[[File: Ramp1.png|thumb| | ===Controls and Features=== | ||
[[File: Ramp2.png|thumb| | [[File: Ramp1.png|thumb|280px|Fig 1. Ramp App]] | ||
Each Ramp implements a single model using a common GUI platform, as shown in Figs. 1 and 2. | [[File: Ramp2.png|thumb|280px|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. | :'''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. | :'''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. See [[Using RAMs]]. | :'''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. | :'''Model Displays''' Graphs and other displays used by the particular Ramp. | ||
:'''Remaining Model Time''' Remaining model time in the run. | :'''Remaining Model Time''' Remaining model time in the run. | ||
| Line 23: | Line 28: | ||
:'''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. | :'''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''' | |||
[[File: csv.png|thumb|280px|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. | |||
[[File: doc.png|thumb|280px|Ramp Doc]] | |||
'''Help Menu''' | |||
:'''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. | |||
<br clear="all"> | |||
==Miscellaneous== | |||
==="Airport" Codes=== | |||
The Ramp designer may assign codes consisting of 3 capital letters and/or digits to parameters and other elements of the Ramp, similar to the codes assigned to uniquely identify airports. These codes are used primarily by operators in the API to similarly specify these elements for various actions. Airport codes are ''not'' used in RAM code specifications. | |||
A complete list of airport codes is contained in the '''About This Ramp''' document discussed above. | |||
===Ramp Window Size=== | |||
Adjusting the size of the Ramp window will cause the display and sliders to change their layout. Ramp window dimensions are store as part of the workspace settings and will be used when those settings are reloaded. | |||
The following links describe Ramp special features | |||
==[[The Ramp API]]== | |||
===[[The Ramp API#Using Javascript|Using Javascript]]=== | |||
===[[The Ramp API#Remote API Access|Remote API Access]]=== | |||
===[[The Ramp API#R Integration|R Integration]]=== | |||
==[[Using RAMs]]== | |||
===[[Using RAMs#What Is A RAM?|What Is A RAM?]]=== | |||
Latest revision as of 18:11, 18 February 2022
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
Controls and Features
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
- 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.
Help Menu
- 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.
Miscellaneous
"Airport" Codes
The Ramp designer may assign codes consisting of 3 capital letters and/or digits to parameters and other elements of the Ramp, similar to the codes assigned to uniquely identify airports. These codes are used primarily by operators in the API to similarly specify these elements for various actions. Airport codes are not used in RAM code specifications.
A complete list of airport codes is contained in the About This Ramp document discussed above.
Ramp Window Size
Adjusting the size of the Ramp window will cause the display and sliders to change their layout. Ramp window dimensions are store as part of the workspace settings and will be used when those settings are reloaded.
The following links describe Ramp special features