ESLScriptingReference.htmlTEXTR*chëΔCµ‡óªµ‡óªÅÅ“Ï CESLab 3.0 ESL Scripting Reference Manual

CESLab 3.0
ESL Scripting Reference Manual

Mark Stevans
CESI
http://www.cesinst.com

September 9, 2000

Data Types

Integer

An integer, capable of holding values in the range -231 to 231-1.

Float

A floating-point number, capable of holding values less than 10200 in magnitude with IEEE double-precision accuracy.

String

Capable of holding text strings of arbitrary length.

Boolean

Capable of holding the values True and False only.

Logical Operators

The logical operators are listed in order of decreasing precedence. Parentheses may be used in the conventional manner to group subexpressions for evaluation as a unit.

Unary ! Operator

Performs unary complementation of a Boolean Value.

Example

    benchvar speedIsNotPositive = ! (theSpeed > 0);

Binary && Operator

Performs a logical "AND" operation.

Example

    if (theSpeed > 0 && theSpeed < 10)
        StartNewTrial();

Binary || Operator

Perform a logical "OR" operation.

Example

    if (theSpeed < 0 || theSpeed > 10)
        return;

Binary ==, !=, >, >=, <, <= Operators

Perform arithmetic comparisons.

Example

    if (theSpeed < 0 || theSpeed >= 10 && theFlag == 3)
        return;

Arithmetic Operators

The arithmetic operators are listed in order of decreasing precedence. Parentheses may be used in the conventional manner to group subexpressions for evaluation as a unit.

Unary - Operator

Performs arithmetic negation.

Example

    benchvar negativeNine = - (3 ^ 2);

Binary ^ Operator

Performs exponentiation.

Example

    benchvar aNine = 3 ^ 2;

Binary * And / Operators

Perform multiplication and division. Note that integer division truncates the result to an Integer.

Example

    benchvar theValue = (3 / 4.0 + 1) * theSpeed;

Binary + And - Operators

Perform addition and subtraction. Addition of a String and any other value causes the other value to be converted to a String, and the two Strings concatenated.

Example

    benchvar theNewSpeed = 4 + theSpeedDelta - theOldSpeed;
    
    StartNewTrial("New Speed is " + theNewSpeed);

Variable Declarations

appvar Statement

Description

Defines/redefines a variable to be associated with this instance of the CESLab application across all Benches.

Example

    benchvar theValue = Sin(3.14159 / 12);

benchvar Statement

Description

Defines/redefines a variable to be associated with the Current Bench.

Example

    benchvar theValue = Sin(3.14159 / 12);

funvar Statement

Description

Defines/redefines a variable local to the enclosing function.

Example

    appfun Cube(inValue) {
    
        funvar theAnswer = inValue ^ 3;
        
        LogMessage("The answer is " + theAnswer);
        
        return theAnswer;
    }

User-Defined Functions

appfun Statement

Description

Defines/redefines a function to be associated with this instance of the CESLab application across all Benches.

Example

    appfun Cube(inValue) {
    
        return inValue ^ 3;
    }

benchfun Statement

Description

Defines/redefines a function to be associated with the Current Bench.

Example

    benchfun Cube(inValue) {
    
        return inValue ^ 3;
    }

Flow Control Statements

break Statement

Description

Exits from the nearest enclosing while loop.

Example

    funvar theDelay = 0;

    while (True) {
        
        theDelay = theDelay + .1;
        
        // Exit from the loop if delay greater than .5 seconds.
        
        if (theDelay > .5)
            break;
        
        StartNewTrial();
    }

continue Statement

Description

Returns to beginning of the nearest enclosing while loop.

Example

    funvar theDelay = 0;

    while (theDelay < 1) {
        
        theDelay = theDelay + .1;
        
        // Skip the trial if the delay is less than .5 seconds.
        
        if (theDelay < .5)
            continue;
        
        StartNewTrial();
    }

if/else Statement

Description

Performs conditional execution of one (or two) statements.

Example

    if (theSpeed < 0)
        StartNewTrial();
    else
        DisplayErrorAlert("The speed is negative!");

return Statement

Description

Returns (optionally with a value) from a user-defined function.

Example

    benchfun Cube(theValue) {
    
        return theValue ^ 3;
    }

while Statement

Description

Executes the target statement repeatedly as long as a condition is held.

Example

    funvar theDelay = 0;

    while (theDelay < 1) {
    
        SetTissueTypeJunctionalDelay("Ventricular Myocardial Tissue Type",
                theDelay);
        
        StartNewTrial("Delay is " + theDelay);
        
        theDelay = theDelay + .1;
    }

Electrophysiology Query Functions

GetSubtissueConductionSpeedFactor

Arguments

Description

Returns the current conduction speed factor for the given Subtissue.

Example

    // Save the old atrial conduction speed factor and set it to .2.
    
    benchvar theOldFactor = GetSubtissueConductionSpeedFactor(
            "Atrial Myocardium");
    
    SetSubtissueConductionSpeedFactor("Atrial Myocardium", .2);

GetDefaultInteractivationInterval

Arguments

None.

Description

Returns the current Default Interactivation Interval for the Bench.

Example

    benchvar theOldInterval = GetDefaultInteractivationInterval();	

GetSubtissueExcitationThreshold

Arguments

Description

Returns the current Excitation Threshold of the given Subtissue.

Example

    benchvar theThreshold = GetSubtissueExcitationThreshold("AV Node");

Electrophysiology Modification Functions

SetModulatorLevel

Arguments

Description

Sets the current level for the given Modulator to the given value.

Example

    SetModulatorLevel("Caffeine", .7);

SetTimeSegmentationInterval

Arguments

Description

Sets the Time Segmentation interval to the given value.

Example

    SetTimeSegmentationInterval(.01);

SetEnableTimeSegmentation

Arguments

Description

Enables/disables Time Segmentation for the current Bench.

Example

    SetEnableTimeSegmentation(True);

SetStopStaticTrials

Arguments

Description

Enables/disables automatic termination of Static Trials.

Example

    SetStopStaticTrials(False);

SetEnableAutomaticCellRetriggering

Arguments

Description

Enables/disables Automatic Cell retriggering. If enabled, then Automatic Cells will be periodically triggered throughout the duration of a given Trial; else Automatic Cells will be automatically activated a maximum of once per Trial.

Example

    SetEnableAutomaticCellRetriggering(True);

SetEnableDecrementalConduction

Arguments

Description

Enables/disables modelling of Decremental Conduction Effects.

Example

    SetEnableDecrementalConduction(False);

SetEnableIntervalDurationEffects

Arguments

Description

Enables/disables modelling of Interval/Duration Effects.

Example

    SetEnableIntervalDurationEffects(False);

SetEnableIntervalPotentialEffects

Arguments

Description

Enables/disables modelling of Interval/Potential Effects.

Example

    SetEnableIntervalPotentialEffects(True);

StimulateSubtissue

Arguments

Description

When executed during Trial, this function applies a simulated stimulating current to all Cells of the given Subtissue. This causes all Cells of the given Subtissue that are currently in Activation Phases 3RRP or 4 to immediately enter Phase 0.

Example

    SetEnableTimeSegmentation(True);
    SetTimeSegmentationInterval(.1);
    StartNewTrial();
    StimulateSubtissue("Myocardial Cell Set", "Right Ventricular Free Wall");
    SetEnableTimeSegmentation(False);
    ContinueTrial();

SetDefaultInteractivationInterval

Arguments

Description

Sets the Default Interactivation Interval to the given value.

Example

    SetDefaultInteractivationInterval(.75);

SetNumGAndSIterations

Arguments

Description

Sets the number of iterations of the procedure of Gelernter and Swihart to be applied during Surface Potential Transfer Coefficient computation to the given value.

Example

    SetNumGAndSIterations(0);

SetDSLExclusionRadius

Arguments

Description

Sets the Regional Dipole Exclusion Radius to the given value.

Example

    // Set DSL Exclusion Radius to 2 cm.

    SetDSLExclusionRadius(.02);

SetCellSetCellSize

Arguments

Description

Sets the Cell Size for the given Cell Set to the given value.

Example

    // Set the Purkinje cell size to 2 mm.

    SetCellSetCellSize("Purkinje Cell Set", .002);

SetPolyhedronMaxFacetSize

Arguments

Description

Sets the Maximum Facet Size for the given polyhedron to the given value.

Example

    // Set the maximum facet size for the outer torso to 1 cm.

    SetPolyhedronMaxFacetSize("Outer Torso Polyhedron", .01);

SetPolyhedronEmployment

Arguments

Description

Sets the Employment status of the given polyhedron to the given value.

Example

    // Do not use the left ventricular intracavitary polyhedron in trials.

    SetPolyhedronEmployment("Left Ventricular Intracavitary Polyhedron", False);

SetPolyhedronEnableSPM

Arguments

Description

Enables/disables Surface Potential Mapping for the given polyhedron.

Example

    // Enable surface potential mapping for the left atrial intracavitary polyhedron.

    SetPolyhedronEnableSPM("Left Atrial Intracavitary Polyhedron", True);

SetSubtissueFiberAngles

Arguments

Description

Sets the inner/outer fiber angles for the given subtissue.

Example

    // Vary the RVFW angles between -30 to 45 degrees.

    SetSubtissueFiberAngles("Right Ventricular Free Wall", -30, 45);

SetSubtissueGeneratesDipole

Arguments

Description

Enables/disables Current Dipole generation for the target Subtissue.

Example

    // Disable dipole generation in the atria.

    SetSubtissueGeneratesDipole("Atrial Myocardial Subtissue", False);

SetSubtissueIntramuralPhase2DurationGradient

Arguments

Description

Sets the Intramural Phase 2 Duration Gradient of the given Subtissue to the given value.

Example

    // Set the intramural gradient to -.4 V/m for the LV.

    SetSubtissueIntramuralPhase2DurationGradient("Left Ventricular Myocardium", -.4);

SetVerticalPhase2DurationGradient

Arguments

Description

Sets the Preparation-wide Vertical Phase 2 Duration Gradient to the given value. Note that this gradient only effects Subtissues of Tissue Types which have been set to obey this gradient.

Example

    // Set the vertical phase 2 duration gradient to -.3 V/m.

    SetVerticalPhase2DurationGradient(-.3);

SetObeysVerticalPhase2DurationGradient

Arguments

Description

Enables/disables the effects of the Preparation-wide Vertical Phase 2 Duration Gradient for the given Tissue Type.

Example

    // Enable vertical phase 2 duration gradients for the ventricles.

    SetObeysVerticalPhase2DurationGradient("Ventricular Myocardial Tissue Type", True);

SetSubtissueIsAutomatic

Arguments

Description

Enables/disables automaticity for Cells of the specified Subtissue.

Example

    // Disable automaticity of SA Node focus number 2.

    SetSubtissueIsAutomatic("SA Node 2", False);

SetSubtissueAutomaticPeriod

Arguments

Description

Sets the Automatic Period of the given Subtissue to the given value.

Example

    // Change the automatic period to 700 ms for SA Node focus 3.

    SetSubtissueAutomaticPeriod("SA Node 3", .7);

SetSubtissueCouplingInterval

Arguments

Description

Sets the Coupling Interval of the given Subtissue to the given value.

Example

    // Change the coupling interval to 15 ms for SA Node focus 1.

    SetSubtissueCouplingInterval("SA Node 1", .015);

SetSubtissueConductionSpeedFactor

Arguments

Description

Sets the Conduction Speed Factor for the Subtissue to the given value.

Example

    // Set the conduction speed factor of the Left Fascicle to .17.

    SetSubtissueConductionSpeedFactor("Left LBB Fascicle", .17);

SetSubtissueExcitability

Arguments

Description

Enables/disables Excitability for Cells of the specified Subtissue.

Example

    // Simulate RBBB by disabling the Right Bundle Branch.

    SetSubtissueExcitability("Right Bundle Branch", False);

SetSubtissueExcitationThreshold

Arguments

Description

Sets the Excitation Threshold of the given Subtissue to the given value.

Example

    // Set the excitation threshold of the AV Node to 65 mV.

    SetSubtissueExcitationThreshold("AV Node", .065);

SetTissueTypeConductivity

Arguments

Description

Sets the conductivity of the specified Tissue Type to the given value.

Example

    // Set the lung conductivity to .8 S/m.
    
    SetTissueTypeConductivity("Lung Tissue Type", .8);

SetTissueTypeConductionSpeedRatio

Arguments

Description

Sets the axial/transverse conduction speed ratio for the given Tissue Type to the given value.

Example

    // Set the longitudinal/transverse conduction speed ratio to 2.6 for
    // the atrial tissue.
    
    SetTissueTypeConductionSpeedRatio("Atrial Myocardial Tissue Type", 2.6);

SetTissueTypeJunctionalDelay

Arguments

Description

Sets the Junctional Delay for the given Tissue Type to the given value.

Example

    // Set the Purkinje junctional delay to 9 milliseconds.
    
    SetTissueTypeJunctionalDelay("Purkinje Tissue Type", .009);

ResetMatrix

Arguments

Description

Sets the given Matrix back to an identity matrix.

Example

    ResetMatrix("Heart Transformation Matrix");

RotateMatrix

Arguments

Description

Rotates the given matrix about the given axis by the specified value.

Example

    RotateMatrix("Heart Transformation Matrix", X_AXIS, 30);

RescaleMatrix

Arguments

Description

Rescales the given Matrix along each axis by the associated scalar factor.

Example

    // Double the height of the torso.
    
    RescaleMatrix("Torso Transformation Matrix", 1, 2, 1);

TranslateMatrix

Arguments

Description

Translates the matrix along each axis by the corresponding magnitude.

Example

    // Move the heart 1 cm to the right.
    
    RescaleMatrix("Heart Transformation Matrix", -.01, 0, 0);

ReflectMatrix

Arguments

Description

Reflects the given matrix about the given axis.

Example

    // Reflect the torso about the X axis (right-to-left).
    
    ReflectMatrix("Torso Transformation Matrix", X_AXIS);

SetTissueTypeHasOrientedFibers

Arguments

Description

Enables/disables fiber orientations for the given Tissue Type.

Example

    // Enable fiber orientations for the atria.
    
    SetTissueTypeHasOrientedFibers("Atrial Myocardial Tissue Type", True);

Interpreter Control Functions

AbortInterpretation

Arguments

None.

Description

Immediately aborts script interpretation, returning control to the user.

Example

    // If the speed is less than zero, abort the script.
    
    if (theSpeed < 0)
        AbortInterpretation();

LogMessage

Arguments

Description

Logs the given message in the Bench Log.

Example

	benchvar theSpeed = .47;
	
    LogMessage("Speed is " + theSpeed);

DisplayErrorAlert

Arguments

Description

Displays the given text in an error alert box.

Example

    // If the speed is negative, display an error alert.
    
    if (theSpeed < 0)
        DisplayErrorAlert("Speed is negative!");

DisplayWarningAlert

Arguments

Description

Displays the given text in a warning alert box.

Example

    // If the speed is negative, display a warning.
    
    if (theSpeed < 0)
        DisplayWarningAlert("Speed is negative!");

Trial Control Statements

StartNewTrial

Arguments

Description

Starts a new Trial.

Example

    // Run a trial without the left lung.
    
    SetPolyhedronEmployment("Left Lung Polyhedron", False);
    StartNewTrial("Without Left Lung");

ContinueTrial

Arguments

None.

Description

Continues an existing trial.

Example

    // Run a trial for 100 milliseconds, notify the user, and then finish
    // the trial.
    
    SetEnableTimeSegmentation(True);
    SetTimeSegmentationInterval(.1);
    StartNewTrial();
    DisplayWarningAlert("100 ms trial time expired.");
    SetEnableTimeSegmentation(False);
    ContinueTrial();

Report Generation Functions

ReportTrialStatistics

Arguments

None.

Description

Writes various Trial statistics to the Bench Log.

Example

    // Run a trial, and then log the trial statistics.
    
    StartNewTrial();
    ReportTrialStatistics();

CheckFacetProximities

Arguments

None.

Description

Writes various facet proximity statistics to the Bench Log.

Example

    // Log facet proximities.
    
    CheckFacetProximities();

ReportActionDurations

Arguments

None.

Description

Writes the action durations from the last Trial to the Bench Log.

Example

    // Run a trial, and then log the action durations.
    
    StartNewTrial();
    ReportActionDurations();

ReportETC

Arguments

None.

Description

Writes the prevailing Electrode Transfer Coefficients to the Bench Log.

Example

    // Log the electrode transfer coefficients.
    
    ReportETC();

Mathematical Functions

Exp

Arguments

Description

Returns the exponentiation of the given value, equal to e ^ value.

Example

    // Compute the exponentiation of the log of 7 (which should be 7).
    
    benchvar shouldBeSeven = Exp(Log(7));

Log

Arguments

Description

Returns the natural logarithm of the given value.

Example

    // Compute the natural log of e, which should be one.
    
    benchvar shouldBeOne = Log(Exp(1));

Log10

Arguments

Description

Returns the base-10 logarithm of the given value.

Example

    // Compute the base-10 logarithm of 100 (which should be 2).
    
    benchvar shouldBeTwo = Log10(100);

Sin

Arguments

Description

Returns the sine of the given angle.

Example

    // Compute the sine of (approximately) "pi".
    
    benchvar theSine = Sin(3.14159);

Cos

Arguments

Description

Returns the cosine of the given angle.

Example

    // Compute the cosine of (approximately) "pi".
    
    benchvar theCosine = Cos(3.14159);

Tan

Arguments

Description

Returns the tangent of the given angle.

Example

    // Compute the tangent of (approximately) "pi".
    
    benchvar theTan = Tan(3.14159);

Sqrt

Arguments

Description

Returns the square root of the given value.

Example

    // Compute the square root of two.
    
    benchvar theRoot = Sqrt(2);

Random

Arguments

None.

Description

Returns a random Float between zero and one.

Example

    // Log a random number.
    
    benchvar theRand = Random();
    LogMessage(theRand + " is a random number.");

Scripting Query Functions

AppVarIsDefined

Arguments

Description

Returns a Boolean Value indicating whether an Application Variable by the given name currently exists.

Example

    // Start a trial only the first time this code is executed.
    
    if (AppVarIsDefined("StopIt")) {
    
        StartNewTrial();
        
        appvar StopIt;
    }

BenchVarIsDefined

Arguments

Description

Returns a Boolean Value indicating whether an Bench Variable by the given name currently exists.

Example

    // Start a trial only the first time this code is executed in a bench.
    
    if (BenchVarIsDefined("StopIt")) {
    
        StartNewTrial();
        
        benchvar StopIt;
    }

Data Type Conversion Functions

Int

Arguments

Description

Returns an Integer corresponding to the given value. If the value is a Float, it is truncated towards zero; if it is a String, it is assumed to contain the text representation of an Integer.

Example

    // Convert 3.47 to an integer, which should round it down to 3.

    benchvar shouldBeThree = Int(3.47)

Float

Arguments

Description

Returns a Float corresponding to the given value. If the value is a String, it is assumed to contain the text representation of a Float.

Example

    // Compute one-half, making sure to avoid integer arithmetic truncations.
    
    benchvar shouldBeOneHalf = 1 / Float(2);

String

Arguments

Description

Returns a String corresponding to the given value.

Example

    // Convert the integer 333 to the string "333".
    
    benchvar aStringWithThreeThrees = String(333);
2 Mark Stevans2;}¶0í2STR ø„ˇˇ;}ô»