Using Function Generators in JSim

Function generators allow JSim models to be driven by test signals or experimental reference data.

Prerequisites:

Contents:

  • Adding a function generator to a model
  • Function generator preview
  • Advanced Usage
  • Pulses and Wave Trains
    • Pulse1
    • Pulse2
    • Pulse3
    • ExtendedPulse3
    • Ramp
    • SquareWaveTrain
    • SawtoothTrain
    • SineTrain
  • Probability Density Functions (PDFs)
    • Exponential
    • Gaussian
    • LagNormal
    • LongTail
    • GammaVar
    • Poisson
    • RandomWalk
  • DataCurve
  • Comments or Questions?
    Give feedback

Adding a Function Generator to a model

Here is a simple example of a JSim model to which we will add a Function Generator:

// function generator tutorial
math fgen1 {
  realDomain t; t.min=0; t.max=60; t.delta=0.1;
  extern real Cin(t);  // we'll assign a function generator to Cin
  real Cout(t) = Cin^2; // calculates the square of the input
}
Download Project10.71 KB
 

 First select the model tab. The main "Run Time" page will appear which shows all input and output variables. The variable Cin is eligible for function generator assignment, as denoted by the icon to the right of the assigment field. Click on this icon. A dialog will open allowing you create a function generator and assign it to Cin. Modify the default name (fgen_1) if you desire, then press OK. The new function generator page will appear. Modify parameters of the function as you desire. Clicking on the "Function" control, whose default value is "Pulse1", will show a complete list of available functions. Functions and parameters are described in the remainder of this document. After you have set the function generator to a desirable wave-shape, return to the main run-time page by using the "Pages" menu, or the "Next" button. You will note that Cin assignment box now contains the name of the new function generator. From now on, clicking on the icon next to Cin will take you directly to the associated function generator page.

Completed version: If you follow the above instructions correctly, the result will be similar to the model below:

Download Project18.24 KB
 

Function Generator Preview

In the JSim GUI, a preview graph is provided with JSim best guess as to the shape of the curve to be generated at run-time. This allows the user to get quick feedback from changes in parameter settings without having to wait for a full model run. However, the proper domain range is only available to the preview graph if the domain minimum and maximum values are model input variables, that is, they are neither private nor calculated from other variables. If the domain minimum or maximum is not available to the preview graph, the graph makes a arbitrary choice for them, and so the graph may differ in shape from that calculated during a subsequent model run.

Advanced Usage

Function are described with reference to the time domain, but they can be used for any independent variable domain (length, voltage, etc.) Example:

  • WebModel 0364: Uses function generators over spatial domain x to provide initial concentrations, and to generate a spatially dependent consumption profile G(x).

Each function generator can also generate a train of the same function--i.e.,the function can be repeated after some specified interval as many times as necessary.

You may create any number of function generators in a model. If you have more than one when you click on the function generator icon for an unassigned variable, you will be asked if you wish to reuse one of the existing generators, or create a new one.

Input variables may be assigned to any algebraic expression involving function generators, e.g. "fgen_1", "2*(fgen_1-3)", "fgen_1+fgen_2". This allows you to build very complex input functions, should you so desire. You may create additional function generators for this purpose with the "New function generator" item in the "Pages" menu. If there are multiple domains in your model (e.g. time and length), you will need to make sure function generator "Domain" control is set appropriately.

Function generators available under JSim

Pulses and Wave Trains:

  • Pulse 1 Generate a single pulse
  • Pulse 2 Generate two different pulses
  • Pulse 3 Generate three different pulses
  • Ramp Generate a power function ramp
  • Square Wave Train Generate a square wave train
  • Sawtooth Wave Train Generate a sawtooth wave train
  • Sine Wave Train Generate a sine wave train

A variety of Probability Density Functions (PDFs) are available in the JSim function generator. They can be used to generate a train of such functions. All are unimodal (with the exception of Longtail). The PDF provides the shape of the function which is then scaled to be an appropriate model input.

  • Common Parameters for PDF's Common Parameter's for PDF's
  • Exponential Generate a decaying exponential PDF
  • Gaussian Generate a Gaussian PDF
  • LagNormal Generate a Lagged Normal PDF (similar to Gaussian)
  • Longtail Generate a long tailed PDF (unimodal or bimodal)
  • GammaVar Generate a gamma variate PDF
  • Poisson Generate a Poisson-like PDF
  • RandomWalk Generate a first traversal of a random walk PDF

 

Pulse 1

This function is a single pulse or a train of pulses.

Parameters:

  • startTime: The start time, when the function has the value "amplitude+offset."
  • duration: Duration of the pulse.
  • amplitude: Value added to offset during the duration of the pulse.
  • offset: The offset or base value for the function for all time.
  • timeToRepeat: If timeToRepeat is greater than zero, the signal generated from time equals 0 to timeToRepeat is repeated every timeToRepeat interval. Hence, this function can be used to generate a train of pulses.

Pulse 2

This function is a double pulse or mixed pulse train. It is similar to Pulse1 with two sets of parameters, but only one offset parameter.

Parameters:

  • p1Start: The start time of the first pulse. The function has the value "p1Amplitude+offset+contribution from the second pulse."
  • p1Duration: Duration of the first pulse.
  • p1Amplitude: Value added to p1offset during the duration of the pulse.
  • offset: The offset or base value for the function for all time.
  • p1TimeToRepeat: If p1TimeToRepeat is greater than zero, the first pulse signal generated from time equals 0 to p1TimeToRepeat is repeated every p1TimeToRepeat interval. Hence, this function can be used to generate a train of mixed pulses.

  • p2Start: The start time of the second pulse, when the function has the value "p2Amplitude+contribution of the first pulse."
  • p2Duration: Duration of the second pulse.
  • p2Amplitude: Value added to the function during the duration of the second pulse.
  • p2TimeToRepeat: If p2TimeToRepeat is greater than zero, the second pulse generated during time equals 0 to p2TimeToRepeat is repeated every p2TimeToRepeat interval. Hence, this function can be used to generate a train of mixed pulses.

Pulse 3

This function is a triple pulse or mixed pulse train. It is similar to Pulse2, but has three sets of parameters, but only one offset parameter.

Parameters:

  • p1Start: The start time of the first pulse. The function has the value "p1Amplitude+offset+contribution from the second and third pulses."
  • p1Duration: Duration of the first pulse.
  • p1Amplitude: Value added to p1offset during the duration of the pulse.
  • offset: The offset or base value for the function for all time.
  • p1TimeToRepeat: If p1TimeToRepeat is greater than zero, the first pulse signal generated from time equals 0 to p1TimeToRepeat is repeated every p1TimeToRepeat interval. Hence, this function can be used to generate a train of mixed pulses.

  • p2Start: The start time of the second pulse, when the function has the value "p2Amplitude+contribution of the first and third pulses."
  • p2Duration: Duration of the second pulse.
  • p2Amplitude: Value added to the function during the duration of the second pulse.
  • p2TimeToRepeat: If p2TimeToRepeat is greater than zero, the second pulse generated during time equals 0 to p2TimeToRepeat is repeated every p2TimeToRepeat interval. Hence, this function can be used to generate a train of mixed pulses.

  • p3Start: The start time of the third pulse, when the function has the value "p3Amplitude+contribution of the first and second pulses."
  • p3Duration: Duration of the third pulse.
  • p3Amplitude: Value added to the function during the duration of the third pulse.
  • p3TimeToRepeat: If p3TimeToRepeat is greater than zero, the third pulse generated during time equals 0 to p3TimeToRepeat is repeated every p3TimeToRepeat interval. Hence, this function can be used to generate a train of mixed pulses.

Extended Pulse 3

This function is used to generate up to three different pulses in a set. When the set is repeated, the amplitude of each pulse can be increased or decreased. The amplitudes of the pulses in each set depend on all the parameters.

Parameters:

  • offset: The constant offset of this function. The value of the function is "offset + a function( of the other specified parameters)."
  • timeToRepeat: How often to repeat a sequence of three pulses. The duration and start time of each pulse relative to the timeToRepeat does not change .

  • p1Start: The start time of pulse 1.
  • p1Amplitude: The initial amplitude of pulse 1.
  • p1Duration: The duration of pulse 1.
  • p1LoopCnt: Number of times pulse 1 amplitude will be incremented or decremented. A value of 0 is treated as 1.
  • p1AmpIncr: Amplitude Increment or decrement for pulse 1.

  • p2Start: The start time of pulse 2.
  • p2Amplitude: The initial amplitude of pulse 2.
  • p2Duration: The duration of pulse 2.
  • p2LoopCnt: Number of times pulse 2 amplitude will be incremented or decremented. A value of 0 is treated as 1. A value of p2LoopCnt>1 causes the amplitude of the first pulse to be repeated p2LoopCnt times in the first p2LoopCnt sets before it is incremented.
  • p2AmpIncr: Amplitude Increment or decrement for pulse 2.

  • p3Start: The start time of pulse 3.
  • p3Amplitude: The initial amplitude of pulse 3.
  • p3Duration: The duration of pulse 3.
  • p3LoopCount: Number of times pulse 3 amplitude will be incremented or decremented. A value of 0 is treated as 1. A value of p3LoopCount>1 causes the amplitude of the second pulse to be repeated p3LoopCnt times before being incremented, and the amplitude of the first pulse to be repeated p3LoopCnt multiplied by p2LoopCnt times before being incremented.
  • p3AmpIncr: Amplitude Increment or decrement for pulse 3.

Ramp

This function is a power function ramp of the form:

Value=offset+amplitude*[(startTime-t)/(tdur)]^exponent

when t is greater than startTime and less than or equal to duration.

Parameters:

  • startTime: Start time of the ramp.
  • duration: Duration of the ramp.
  • amplitude: Height of ramp when exponent greater than or equal to zero. Amplitude may be negative.
  • offset: The offset or base value for the function during the duration off the ramp (similar to usage in square wave, but different from usage in Pulse1, Pulse2, and Pulse3.
  • exponent: The exponent for the power function of the ramp. Negative exponents can cause large magnitudes at beginning of ramp. Value of zero resembles Pulse1 but treatment off offset is different.
  • timeToRepeat: If timeToRepeat is greater than zero, the signal generated from time equals 0 to timeToRepeat is repeated every timeToRepeat interval. Hence, this function can be used to generate a train of ramps.

Square Wave Train

This function is generates a train of square waves and can be used to generate a single pulse. It's usage overlaps with Pulse1, but has some significant differences as noted below.

Parameters:

  • startTime: The start time, when the Square Wave train begins.
  • duration: Duration of the square wave train.
  • amplitude: Value = amplitude+offset during duration when square wave train is "on"
  • offset: The offset or base value for the function during duration when square wave train is in "off" mode. This is different from the offset in Pulse1, Pulse2, and Pulse3 which is present for all time.
  • shapeFactor: 1 for "on" for entire period (value=amplitude+offset), 0 for "off" for entire period (value=offset), 0.25 "on" for the first quarter of the period followed by "off" for the last three quarters of the period. Any value less the zero will be defaulted to zero. Any value greater than 1 will be defaulted to 1.
  • phase: fraction of period to shift wave train. All integer values have same effect (specifically, no effect).
  • timeToRepeat: If timeToRepeat is greater than zero, the signal generated from time equals 0 to timeToRepeat is repeated every timeToRepeat interval. Hence, this function can be used to generate a train of square wave trains.

Sawtooth Wave Train

This function is generates a train of sawtooths. It's parameters are the same as the Square Wave , where shapeFactor controls the fraction of the period the sawtooth is rising and falling.

Parameters:

  • startTime: The start time, when the sawtooth train begins.
  • duration: Duration of the sawtooth train.
  • amplitude: Value = amplitude*(startTime-t)/tdur +offset during period when sawtooth is rising.
  • offset: The offset or base value for the function during duration of sawtooth.
  • shapeFactor: 1 for sawtooth always rising over entire period, 0 for always falling over entire period, 0.25 sawtooth rises in maximum value in 1st quarter of period, falls to offset value over last three quarters of period. A value less the zero will be defaulted to zero. Any value greater than 1 will be defaulted to 1.
  • phase: fraction of period to shift wave train. All integer values have same effect (specifically, no effect).
  • timeToRepeat: If timeToRepeat is greater than zero, the signal generated from time equals 0 to timeToRepeat is repeated every timeToRepeat interval. Hence, this function can be used to generate a train of sawtooth wave trains.

Sine Wave Train

This function generates a train of sine waves. It has all but one of the parameters used for the square and sawtooth wave trains (doesn't use ShapeFactor.)

Parameters:

  • startTime: The start time, when the sine train begins.
  • duration: Duration of the sine train.
  • amplitude: Amplitude of the sine wave.
  • offset: The offset or base value for the function during duration
  • phase: fraction of period to shift sine wave. All integer values have same effect (specifically, no effect). A value of -0.25 makes this a cosine wave.
  • period: Period of 1 cycle of the sine wave.
  • timeToRepeat: If timeToRepeat is greater than zero, the signal generated from time equals 0 to timeToRepeat is repeated every timeToRepeat interval. Hence, this function can be used to generate a train of sine wave trains.

Common Parameters for PDF's

There are several parameters that are used for most of the PDF's. They include area, tMean, rd, skewn, frPeak, and timeToRepeat.

  • area: The area of the PDF function. If less than or equal to zero, it is defaulted to a value of 1. Formally it is the integral from start time (usually take to be zero) to infinity of PDF(t)*dt where t is the independent variable and PDF(t) is a function of the independent variable. area is used to scale the PDF so it is an appropriate model input.
  • tMean: The mean transit time of the PDF relative to the start time, t.min, where t is the independent realDomain variable. It is approximately the difference between the start time and when the peak of the PDF occurs. Formally, it is the integral from start time to infinity of PDF(t)tdt/area where t is the independent variable and PDF(t) is the PDF as a function of the independent variable
  • rd: Relative dispersion of the PDF is the standard deviation of the PDF divided by the mean transit time. Formally, it is the square root of the integral from the start time (usually taken to be zero) to infinity (usually taken to be some large finite time) of PDF(t)(t-tMean)(t-tMean)*dt, all of which is divided by tMean.
  • skewn: The skewness of the PDF.
  • frPeak: fraction of the peak or maximum value of a PDF after which the PDF is truncated (set to zero). Normally defaulted to 1.0E-06. It causes truncation only after the peak. Usage is different for the Longtail PDF.
  • timeToRepeat: If not zero, the curve from time=0 to timeToRepeat is repeated every timeToRepeat interval. This parameter is used to generate a train of PDF pulses.

Exponential

This function generates an exponential PDF which abruptly rises from zero to its maximum value, then decays.

Parameters:

  • area, tmean, rd, frPeak, timeToRepeat see Common Parameters for PDF's .

Gaussian

This function generates a Gaussian PDF.

Parameters:

  • area, tmean, rd, frPeak, timeToRepeat see Common Parameters for PDF's .

LagNormal

This function generates a Lagged Normal PDF. It is similar to a Gaussian , but with positive skewness (skewness of a Gaussian is zero.) See model lndc (lagged normal density curve) model for more information.

Parameters:

  • area, tmean, rd, skewn, frPeak, timeToRepeat see Common Parameters for PDF's .
  • upslope: choice of Regular or Linear (early part of rise of PDF replaced by linear approximation.
  • CAVEATS: 2 < skewn <= 0. When skewn = 0, the Gaussian PDF will be used and no Linear upslope. When skewn approaches 2, the Exponential PDF will be used.

Longtail

This function is a combination of one of the several of the other PDFs to which on the down slope side of the PDF is joined either a sum of decaying exponentials or power law functions.

Parameters:

  • PDF: The PDFs which may be selected are LagNormal, Gaussian, Poisson, Random Walk, and Gamma Variate.
  • area, tmean, rd, skewn, frPeak, upslope, timeToRepeat: See the individual PDFs for usage and limitations. skewn is not used by either Gaussian or Poisson. upslope is only used by LagNormal. Appropriate value for frPeak is 1E-06.
    SPECIAL NOTE: These parameters are used to define the PDF before the long tail replaces the end of the curve. The total curve, PDF+long tail, will be normalized to area. frPeak is also the cutoff for the long tail.
  • tORfr, tJoin, frJoin: This is a choice between either setting the time, tJoin, where the long tail will join the PDF or setting the fraction of the peak, frJoin, where the long tail will join the PDF. For convenience, the time when frJoin occurs will be referred to also as tJoin in the following two formulas.
  • expORpow: This is a choice between either using a sum of decaying exponentials or a sum of decaying power law functions.
  • nexp, w1, w2, w3, w4, k1, k2, k3, and k4 are the parameters for a sum of decaying exponential functions which comprise the long tail. 
                               /nExp                           \
                           |-----                          |
                           | \                             |
                  T(t) = a |  )   w  exp(-b k  (t - tJoin))|
                           | /     i         i             |
                           |-----                          |
                           \i = 1                          / 
for t>=tJoin
    where a and b are parameters which scale the sum of exponentials and are calculated so that the above function matches the PDF value and derivative at tJoin (or the time when frJoin occurs). Note that the wi's and the ki's are relative weights and decay rates. It is customary to list the ki's in decreasing value.
  • nPow, wpow1, wpow2, wpow3, wpow4, beta1, beta2, beta3, and beta4 are the parameters for a sum of decaying power law functions which comprise the long tail. 
                               /nPow                               \
                           |-----                              |
                           | \                           -beta |
                  T(t) = a |  )   wpow  (t - tJoin + ts )     i|
                           | /        i                i       |
                           |-----                              |
                           \i = 1                              / 
for t>=tJoin
    where a and tsi are calculated so that the above function matches the PDF value and derivative at tJoin (or the time when frJoin occurs). Note that the wpowi's are relative weights.

GammaVar

This function generates a gamma variate PDF. It has some similarities to the LagNormal PDF.

Parameters:

  • area, tmean, rd, skewn, frPeak, timeToRepeat see Common Parameters for PDF's .
  • CAVEATS: skewn is defaulted from a minimum of 0.267 to a maximum of 1.999 if it exceeds these limits. The actual rd used is the smaller of rd and skewn/2.01.

Poisson

This function generates a Poisson-like PDF using a scaled Poisson equation in which lambda is allowed to vary continuously and n is fixed. This curve represents the transport of a tracer through n identical well mixed compartments.

Parameters:

  • area, tmean, rd, frPeak, timeToRepeat see Common Parameters for PDF's .

Random Walk

This function generates a first traversal of a random walk PDF.

Parameters:

  • area, tmean, rd, skewn, frPeak, timeToRepeat see Common Parameters for PDF's .
  • CAVEAT: The actual skewness used is the maximum of skewn and 3.001*rd.

Data Curve

This function is an interpolation of a Data Curve. It is imported as a file using the Project tab, then the Add button, selecting Import data file (.tac +).

Parameters:

  • dataSet: a choice button listing tac files.
  • name: the curve designation in the tac file.

Comments or Questions?

Give feedback

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.