The JSim "Loops" feature allows users to observe the effects of changing model parameter values.
Prerequisites:
Contents:
- Basic Loops
- Looping on Function Generator Parameters
- Looping on Solver Control Parameters
- The Next Loop Function
- Bugs and Limitations
- Comments or Questions?
A video designed to accompany this document may be found here .
Basic Loops
JSim Loops are configured within a model's "Loops" sub-tab. An inner loop and an outer loop are provided, allowing 2 levels of nesting. Within either loop, any number of model parameters (model input variables, function generator parameters or solver settings) may be varied. The upper third of the Loops sub-tab configures the inner loop, the middle third configures the outer loop, and the lower third gives status information. A model must be compiled before loops can be configured. Once the loops are configured, the menubar "Run" button runs the model once for each iteration. Once run, each model variable or expression selected within a plot page will generate multiple data sets, one for each iteration.
Inner and outer loops are configured by entering the parameter name to vary in the "Parameter" column, either by typing the name, or selecting from the pull-down list. When a valid parameter name is entered the box blackens and the "Start" column shows the current value for that variable, which may be adjusted if required. In the first iteration, the parameter takes the value in the "Start" column. In subsequent iteration values are specified in the "Other Values" column. The simplest form for "Other Values" is a comma-separated list of values to be assumed by the parameter, for example "10,20,30" (do not type the quote marks). Alternatively, the "@" syntax, described below, may be used.
The Loops "@" syntax allows the user to enter one of the following special values in the "Other Values" column:
- @+number (linear increase)
- @-number (linear decrease)
- @*number (geometric increase)
- @/number (geometric decrease)
When the "@" syntax is used, the first character must be the @ sign, the second character must an arithmetical operator, and what follows must be a real number (e.g. 10, 1.53e8, .0123). Arbitrary algebraic expressions using @ are not supported. The "Start" column for this parameter must contain a real number (i.e. arbitrary algebraic expressions are not allowed). For example, if a parameter has "100" in the start column, and "@+10" in the "Other Values" column, the values assumed would be 100, 110, 120, 130, etc. With "@/2" in the "Other Values" column, the values assumed would be 100, 50, 25, 12.5, etc.
When a proper entry is made in the "Other Values" column, the box blackens. Both the "Parameter" and "Other Values" boxes are blackened for a loop parameter to be properly configured. When this happens a checkbox will appear in the OK column. Unchecking this box will temporarily suppress this parameter line during a loops run. If the parameter line is incompletely configured, a question mark button will appear in the OK column. Clicking this button will show a message stating what is incomplete about the line's configuration. Any number of parameters may be varied in each loop. The number of parameters corresponds to the number of check marks in the OK column.
The number of loop iterations is determined in different ways, depending upon the mode (auto or manual). In manual mode, the number of iterations is set explicitly by the user via the "# times" control. In auto mode, mode number of iterations is determines from the longes value in the "Other Values" column. If no lists are specified (i.e. only the "@" syntax is used) the number of values must be specified by the user in the "# times" field that will appear under such circumstances.
The total number of loop iterations will be the product of the number in the inner and outer loops.
Looping on Function Generator Parameters
Looping over function generator parameters allow users to compare model behaviour over a range of input waveforms (e.g. varying sine wave periods). These parameters are not currently shown in the loops control "Parameter" column pull-down menu, and so must be entered via the keyboard. Function generator parameter names are of the form:
FGNAME.FUNC.PARM
where
- FGNAME is the name of the function generator assigned by the user (e.g. fgen_1)
- FUNC is the waveform selected via the "Function" menu (e.g. SineTrain)
- PARM is the name of the parameter within the specified function (e.g. period).
Combining the above rules, the name for the SineTrain period parameter for a function generator name "fgen_1" would be "fgen_1.SineTrain.period". As with all JSim parameters, function generator parameter names are case sensitive.
For complete details on function generator parameters, see Using Function Generators in JSim.
Looping on Solver Control Parameters
Solver control parameters control the behaviour of JSim's numeric solvers. Looping of such parameters can allow users to optimize numeric methods for their model. As with function generator parameters, solver control parameters are not yet available in the loops control pulldown menus, and so must be typed in by hand.
Solver control parameters names are of the form
solver.CLASS_SOLVERNAME_PARMNAME
where:
- CLASS is "ode" (ordinary differential equation solver), "pde" (partial differential equation solver) or "fzero" (implicit equation solver, or zero finder);
- SOLVERNAME is the name of the solver used, e.g. Dopri5;
- PARMNAME is the name of the parameter within SOLVERNAME, e.g. reltol.
Combining the above examples, the full name for the Dopri5 relative tolerance parameter is "solver.Dopri5.reltol". As with all JSim parmaeters, solver control parameter names are case sensitive.
Names for solver control parameters are not yet completely documented. A document is currently in preparation stages.
The Next Loop Function
When running loops in the JSim GUI, the run status popup (which includes a progress meter) allows the user the "Next Loop" option. Pressing this button will terminate the current model calculation loop and move on the the next. If multiprocessing is enabled, several loops may be calculated simultaneously. In this case, the next loop function skips the loop that has been running the longest.
The Next Loop function is available in JSim releases 2.13 and above.
Bugs and Limitations
Bugs and Limitations
There is no "Next Loop" button, skipping ahead before the current loop is completed.
Comments or Questions?
Model development and archiving support at https://www.imagwiki.nibib.nih.gov/physiome provided by the following grants: NIH U01HL122199 Analyzing the Cardiac Power Grid, 09/15/2015 - 05/31/2020, NIH/NIBIB BE08407 Software Integration, JSim and SBW 6/1/09-5/31/13; NIH/NHLBI T15 HL88516-01 Modeling for Heart, Lung and Blood: From Cell to Organ, 4/1/07-3/31/11; NSF BES-0506477 Adaptive Multi-Scale Model Simulation, 8/15/05-7/31/08; NIH/NHLBI R01 HL073598 Core 3: 3D Imaging and Computer Modeling of the Respiratory Tract, 9/1/04-8/31/09; as well as prior support from NIH/NCRR P41 RR01243 Simulation Resource in Circulatory Mass Transport and Exchange, 12/1/1980-11/30/01 and NIH/NIBIB R01 EB001973 JSim: A Simulation Analysis Platform, 3/1/02-2/28/07.