B. CONSTANTS, FUNCTIONS, AND EXPRESSIONS

B.1 Constants

GAMBIT provides the following predefined constants for use in any value expression.

Constant	Value	Description
PI	3.141592653590
TWOPI	6.283185307180
DEG2RAD	0.0174532925199	Degree-to-radian conversion factor
RAD2DEG	57.29577951308	Radian-to-degree conversion factor

B.2 Functions

GAMBIT provides the following types of interpreter functions:

• Math
• String
• System
• Model

The following sections describe the functions listed above.

B.2.1 Math Functions

GAMBIT provides two types of math functions: trigonometric and general.

Trigonometric Functions

General Math Functions

Function	Description
ABS (x)	Absolute value of x,
EXP (x)	Exponential of x,
INT (x)	Integer truncation of x
LOG (x)	Natural logarithm of x,
LOG10 (x)	Base-10 logarithm of x,
MAX ()	Maximum of x or y
MIN ()	Minimum of or
MOD ()	Modulo or remainder:
POW ()	x raised to the power y,
SIGN (x)	-1.0 if x is negative, else 1.0
SQRT (x)	Square root of x

NOTE (1): The arguments x and y in the functions listed above represent any valid value expression—that is, a number, constant, function, arithmetic expression, or parameter.

NOTE (2): All trigonometric functions require and return values expressed in degrees.

B.2.2 String Functions

The string functions available in GAMBIT are as follows.

The follow subsections describe and show examples of each of the functions listed above.

(=)—String Assignment

String assignment allows the user to assign a string value to a parameter in GAMBIT. Assigned strings may be literal strings enclosed in double quotation marks or other string parameters.

Examples

$X = "STRING"

$Y = $X

(+)—String Concatenation

String concatenation allows the user to concatenate string values in parameters in GAMBIT. Literal strings and string parameters can be concatenated in any combination.

Examples

$X = "ABC" + "DEF"

$X = $Y + "DEF"

CSTRCMP—Case-Insensitive String Compare

CSTRCMP performs a character-by-character comparison of two strings—string1 and string2—and ignores the case of each character until a difference is found or the end of string1 is reached. CSTRCMP returns a numeric value that indicates whether string1 is greater than, equal to or less than string2. The value indicates the logical relationship between string1 and string2 as follows.

Format

CSTRCMP(string1, string2)

Example

The following function call returns the numeric value of zero (0) in parameter X, indicating that string1 and string2 are equal:

$X = CSTRCMP("ABCDEFGHI", "abcdefghi")

CSTRNCMP—Case-Insensitive Substring Compare

CSTRNCMP performs a character-by-character comparison of two strings—string1 and string2—and ignores the case of each character until a difference is found or a specified number of characters (length) have been compared. CSTRNCMP returns a numeric value indicating whether length characters in string1 are greater than, equal to or less than length characters in string2. The value indicates the logical relationship between string1 and string2 as follows.

Format

CSTRNCMP(string1, string2, length)

Example

The following function call returns the numeric value zero (0) in parameter X, indicating that the first four characters in string1 are equal to the first four characters in string2:

$X = CSTRNCMP("ABCDEFGH", "abcdwxyz", 4)

DIRNAME—Directory Path

DIRNAME returns the directory path portion of a file name which contains a directory path by searching for a "/" or "\" in a file name (filename) and returning the portion of filename from the beginning of filename up to but not including the last "/" or "\" found. If no "/" or "\" is found in filename, the function returns an empty string.

Format

DIRNAME(filename)

Example

The following function call returns the string value "/users/prob1" in parameter X:

$X = DIRNAME("/users/prob1/prob1.dbs")

DIRPLUSFILE—Directory Path and File Name

DIRPLUSFILE returns a string consisting of the directory name (directory) and filename combined with the appropriate "/" or "\" characters where necessary.

Format

DIRPLUSFILE(filename, filename)

Example

The following function call returns the string value "/users/prob1/ prob1.dbs" in parameter X:

$X = DIRPLUSFILE("/users/prob1", "prob1.dbs")

DIRPLUSSUBDIR returns the directory path name consisting of the directory name (directory) and subdirectory name (subdirectory) combined with the appropriate "/" or "\" characters placed where necessary.

Format

DIRPLUSSUBDIR(filename, filename)

Example

The following function call returns the string value "/users/prob1" in parameter X:

$X = DIRPLUSSUBDIR("/users", "prob1")

FILENAME returns only the file name portion of a file name containing a directory path. FILENAME searches for the last occurrence of "/" or "\" in filename and returns the portion of filename to the right of the last "/" or "\" found. If no "/" or "\" is found in filename, FILENAME returns an empty string.

Format

FILENAME(filename)

Example

The following function call returns the string value "prob1.dbs" in parameter X:

$X = FILENAME("/users/prob1/prob1.dbs")

FILEPREFIX returns the prefix of a file name by searching for a "." in filename and returning the portion of filename to the left of the "." including the path if a path is specified. If no "." is found in filename, FILEPREFIX returns an empty string.

Format

FILEPREFIX(filename)

Example

The following function call returns the string value "prob1" in parameter X:

$X = FILEPREFIX("prob1.dbs")

FILESUFFIX returns the suffix of a file name by searching for a "." in filename and returning the portion of filename to the right of the ".". If no "." is found in filename, FILEPREFIX returns an empty string.

Format

FILESUFFIX(filename)

Example

The following function call returns the string value "dbs" in parameter X:

$X = FILESUFFIX("prob1.dbs")

NTOS—Numeric-to-String Representation Conversion

NTOS converts a numeric value (number) to its string representation and returns the corresponding string. NTOS supports scientific notation for the numeric representation but expands the number in the resulting string representation.

Format

NTOS(number)

Example

The following function call returns the string value "12300" in parameter X:

$X = NTOS(123E+2)

STON—String-to-Numeric Representation Conversion

STON converts a string (string) to its numeric representation and returns the corre­sponding numeric value. STON ignores leading blanks and only converts the numeric characters up to the first non-numeric character encountered starting from the left of string.

Format

STON(string)

Example

The following function call returns the numeric value 127 in the scalar parameter X:

$X = STON("127")

STRCMP—Case-Sensitive String Compare

STRCMP performs a character-by-character comparison of two strings—string1 and string2—taking into account the case of each character until a difference is found or the end of string1 is reached. STRCMP returns a numeric value indicating whether string1 is greater than, equal to or less than string2. The value indicates the logical relationship between string1 and string2 as follows.

Format

STRCMP(string1, string2)

Example

The following function call returns the numeric value 0 in parameter X indicating that string1 and string2 are equal:

$X = STRCMP("ABCDEFGHI", "ABCDEFGHI")

STRFMT—String Formatting

STRFMT formats a set of arguments according to the contents of a format specifier and returns the results as a string value. The format specifier may include any combination of literals and C style format specifiers. There must be a separate format specifier for each argument in the argu­ment list and each format specifier must be the correct type or a syntax error will occur. The available format specifiers is as follows.

Format

STRFMT(specifier, [ ,argument1[, argument2[, ... ]]])

Example

The following function call returns the string value "The value of Y: 10" in parameter X:

$Y = 10
$X = STRFMT ( "The value of Y: %d" , $Y )

STRLEN—Number of Characters in a String

STRLEN returns the number of characters in a string (string), including blanks.

Format

STRLEN(string)

Example

The following function call returns the numeric value 8 in parameter X:

$X = STRLEN("boundary")

STRNCMP—Case-Sensitive Substring Compare

STRNCMP performs a character-by-character comparison of two strings—string1 and string2 taking into account the case of each character until a difference is found or a specified number (length) characters have been compared. STRNCMP returns a numeric value indicating whether string2 characters in string1 are greater than, equal to or less than length characters in string2. The value indicates the logical relationship between string1 and string2 as follows.

Format

STRNCMP(string1, string2, length)

Example

The following function call returns the numeric value 0 in parameter X indicating that the first four characters in string1 are equal to the first four characters in string2:

$X = STRNCMP("ABCDEFGH", "ABCDWXYZ", 4)

STRRSTR—Offset of Last Substring Within a String

STRRSTR returns the numeric value of the starting character position in a string variable (string) where the last occurrence of a substring (substring) is found—or returns zero (0) if substring is not found in string .

Format

STRRSTR(string, substring)

Example

The following function call returns the numeric value 10 in parameter X:

$X = STRRSTR("ABCDEFABCDEF", "DE")

STRSTR—Offset of First Substring Within a String

STRSTR returns the starting character position in a specified string (string) where the first occurrence of substring is found.

Format

STRSTR(string, substring)

Example

The following function call returns the numeric value four (4) in parameter X:

$X = STRSTR("ABCDEFABCDEF", "DE")

STRTOLC—Convert a String to Lower Case

STRTOLC converts the alphabetic characters string to lower case.

Format

STRTOLC(string)

Example

The following function call returns the string value "abcdef" in parameter X:

$X = STRTOLC("ABCDEF")

STRTOUC—Convert a String to Upper Case

STRTOUC converts the alphabetic characters string to upper case.

Format

STRTOUC(string)

Example

The following function call returns the string value "ABCDEF" in parameter X:

$X = STRTOUC("abcdef")

SUBSTR—Substring Extraction

SUBSTR extracts a substring from a string (string) starting from a specified position (position) and continuing for a specified number of characters (length) and returns the substring value.

Format

SUBSTR(string, position, length)

Example

The following function call returns the string value "DEF" in parameter X:

$X = SUBSTR("ABCDEFGHI", 4, 3)

B.2.3 System Functions

The system functions available in GAMBIT are as follows.

The follow subsections describe and show examples of each of the functions listed above.

FILEEXISTS—File Existence Flag

FILEEXISTS returns a numeric value of 0 or 1 to indicate whether or not a specified file exists.

• If the file exists, GAMBIT returns a value of one (1).
• If the file does not exist, GAMBIT returns a value of zero (0).

Format

FILEEXISTS(filename)

Example

If a file named "model_01.jou" exists in the current working directory, the following function call returns the numeric value of 1 in parameter X:

$X = FILEEXISTS("model_01.jou")

GETCWD—Current Working Directory

GETCWD returns a string that represents the current GAMBIT working directory.

Format

GETCWD()

Example

If the current problem is being run in "/users/ prob1", the following function call returns the string value "/users/prob1" in parameter X:

$X = GETCWD()

GETENV—Environment Variable

Format

GETENV(env_variable)

Example

If the GAMBITROOT environment variable is set to "/usr/local/GAMBIT", the following function call returns the string value "/usr/local/GAMBIT" in parameter X:

$X = GETENV("GAMBITROOT")

UNAME—Operating System Name

UNAME returns the name of the current operating system.

Format

UNAME()

Example

If GAMBIT is running on an HP-UX system, the following function call returns the string value "HP-UX" in parameter X:

$X = UNAME()

B.2.4 Model Functions

GAMBIT provides the following modeling functions.

ARCLEN—Arc Length

ARCLEN returns a numeric value that represents the length of a specified edge. If you do not specify an edge name, ARCLEN returns the length of the shortest edge in the model.

Format

ARCLEN(edge)

Example

The following function call returns the length of an edge named, edge.17.

$X = ARCLEN("edge.17")

BBOX—Bounding Box

BBOX returns a numeric array of six values that define the Cartesian coordinates of diagonally opposed corners on a rectangular box that bounds an individual entity (vertex, edge, face, volume, or group) or the entire model. The array values are reported in the order: x_min, y_min, z_min, x_max, y_max, z_max. If you specify an entity name, GAMBIT returns values that define the box bounding the specified entity. If you do not specify an entity name, GAMBIT returns values that define a box bounding the entire model.

Format

BBOX(entity)

Example

The following function call returns an array of six values that define the corner coordinates of a box bounding an entity named, volume.3.

$X = BBOX("volume.3")

ENT2LOC—Entity Location

ENT2LOC returns a numeric array of three values that represent the Cartesian coordinates (x,y,z) of the center point of a specified entity (vertex, edge, face, or volume).

Format

ENT2LOC(entity)

Example

$X = ENT2LOC("face.13")

GETIDENT—Current GAMBIT Database Identifier

GETIDENT returns the current GAMBIT problem identifier.

Format

GETIDENT()

Example

If the current problem identifier is "prob1", the following function call returns the string value "prob1" in parameter X:

$X = GETIDENT()

GETNORMAL—Face Normal Vector

GETNORMAL returns the components of a unit vector that constitutes the normal at a specified location on a face. The GETNORMAL function requires four arguments and includes an optional fifth argument:

• One string argument (face) specifies the face for which the normal is to be computed.
• Three numeric arguments (x,y,z) specify the Cartesian coordinates (x,y,z) of the point on the face at which the normal is to be determined. (NOTE: If you specify a location that does not exist on the face, GAMBIT projects the location onto the face and determines the normal at that point.)
• (Optional) One string argument (volume) specifies a volume to which the face is attached. If you specify the volume argument, GAMBIT computes the normal vector such that it points away from the specified volume.

Format

GETNORMAL(face, x, y, z, [volume])

Example

The following function call returns the components of a unit normal vector for a face named "face.3" pointing away from an attached volume named "volume.4" at the point: x, y, z = 1,13,89.

$X = GETNORMAL("face.3", 1, 13, 89, "volume.4")

GETSCR—Current Scratch Directory

GETSCR returns the current GAMBIT scratch directory.

Format

GETSCR()

If the current scratch directory is "/users/prob1", the following function call returns the string value "/users/prob1" in parameter X:

$X = GETSCR()

GETTANGENT—Edge Tangent Vector

GETTANGENT returns the components of a unit vector that constitutes the tangent vector for an edge at a specified location. The GETTANGENT function requires either two or four arguments, as follows:

• One string argument (edge) specifies the edge for which the tangent is to be computed.
• Either one numeric argument (u) specifies the fractional position or three numeric arguments (x,y,z) specify the Cartesian coordinates (x,y,z) of the point on the edge at which the tangent is to be determined. (NOTE: If you specify a location that does not exist on the edge, GAMBIT projects the location onto the edge and determines the tangent at that point.)

Format

GETTANGENT(edge, x, y, z)

GETTANGENT(edge, u)

The following function call returns the components of a unit tangent vector for an edge named "edge.3" at its midpoint (using the u argument).

$X = GETTANGENT("edge.3", 0.5)

INTERSECTING—Geometry Intersection Flag

INTERSECTING returns a numeric array of six values that indicate whether or not two entities of a specified type intersect. The available types are as follows.

Format

INTERSECTING(entity_type, entity1, entity2)

Examples

If two volumes, labeled volume.9 and volume.121, intersect, the following function call returns a six-element array parameter, X, each element of which contains a zero (0):

$X = INTERSECTING(t_vo, "volume.9", "volume.121")

LASTID—Last Entity Identifier

LASTID returns the last identification number used in the model for a specified entity type. The available types are as follows.

Format

LASTID(entity)

Examples

If the most recently created face in a model is labeled face.5, the following function call returns the value five (5) to the parameter X:

$X = LASTID(t_fa)

LISTENTITY—Entity List

LISTENTITY returns a string array containing a filtered list of entities, zone definitions, coordinate systems, boundary layers, or size functions of a specified type currently existing in the model. For a list of available types, see the LASTID function, above.

The LISTENTITY function requires three arguments:

• return_type—Specifies the type of entity to be returned in the string array
• filter_type—Specifies the type of entity that serves as the filtering element
• filter_entity—Specifies the particular entity with which the returned entities are associated

Format

LISTENTITY(return_type, filter_type, filter_entity)

Examples

The following function call returns a string array containing all edges associated with face.5.

$X = LISTENTITY(t_ed, t_fa, "face.5")

$X = LISTENTITY(t_bl)

LOC2ENT—Nearest Entity

LOC2ENT returns a string representing the name of the entity in closest proximity to a specified coordinate location. The LOC2ENT function requires four arguments:

• One string argument (return_type) that specifies the type of entity to be located
• Three numeric arguments that represent the Cartesian coordinates (x,y,z) of the search point

Format

LOC2ENT(return_type, x, y, z)

Example

$X = LOC2ENT(t_fa, 116, 57, 209)

MINCLEARANCE—Minimum Clearance

MINCLEARANCE returns a numeric array of six real values. The values constitute two sets of Cartesian coordinates at the points of minimum clearance for two entities of a specified type. The available types are as follows.

Format

MINCLEARANCE(entity_type, entity1, entity2)

Examples

If the shortest distance between two faces, labeled face.3 and face.10, can be represented by a straight line with the endpoint coordinates (0,1,0) on face.3 and (3,25,9) on face.10, the following function call returns the values 0, 1, 0, 3, 25, and 9 to elements 1 through 6, respectively, of array parameter X:

$X = MINCLEARANCE(t_fa, "face.3", "face.10")

NDEFAULT—Numeric Default Value

NDEFAULT returns a numeric value that represents the current default value of a numeric GAMBIT default variable. For a complete list of GAMBIT default variables, see Section 6.1 of the GAMBIT Command Reference Guide.

Format

NDEFAULT(numeric_default)

Example

$X = NDEFAULT("MESH.INTERVAL.COUNT")

OPERERR—Error Flag

OPERERR returns a numeric value of 0 or 1 to indicate whether or not the most recently attempted operation was successful.

• If the operation succeeded, the returned value is zero (0).
• If the operation failed, the returned value is one (1).

Format

OPERERR()

Example

$X = OPERERR()

PARAMSIZE—Parameter Array Size

PARAMSIZE returns a scalar value representing the size of a specified one-dimensional array parameter (parameter_name). (NOTE: The PARAMSIZE function does not apply to multiply dimensioned arrays and returns a value of zero (0) for scalars.)

Format

PARAMSIZE(parameter_name)

Example

$X = PARAMSIZE("Y2")

QUALITY—Mesh Element Quality

The QUALITY function returns the number of mesh elements the quality of which is above or below a specified value. It requires the following arguments:

• metric—Metric used to evaluate element quality
• direction—Domain relative to the specified value
• n—Specified value
• entity—(Optional) Entity for which mesh element quality is to be reported

The available direction values are as follows.

Format

QUALITY(metric, direction, n, entity)

Example

The following function call returns the number of mesh elements in an entity named "volume.1" for which the aspect ratio metric is less than 0.65:

$X = QUALITY(q_aspr, q_lt, 0.65, "volume.1")

RETLABEL—Last n'th Entity Name

RETLABEL returns the last n^th entity name used in the model for a specified entity type. The available types are as follows.

Format

RETLABEL(entity_type, n)

Examples

If the second most recently created vertex in a model is labeled vertex.28, the following function call returns the string "vertex.28" to the parameter X:

$X = RETLABEL(t_ve, 2)

SDEFAULT—String Default Value

SDEFAULT returns a string value that represents the current default value of a GAMBIT string default variable. For a complete list of GAMBIT default variables, see Section 6.1 of the GAMBIT Command Reference Guide.

Format

SDEFAULT(string_default)

Example

$X = SDEFAULT("LABEL.FACE.PREFIX")

B.3 Expressions

GAMBIT allows you to use two types of expressions in parameter definitions and journal files:

• Arithmetic expressions
• Logical expressions

Arithmetic expressions evaluate to a numeric value and can be used wherever a numeric value is expected-for example, a keyword value, a data record entry, or a DO loop control variable. Logical expressions evaluate to true or false and are used in IF blocks and DO loops. (For descriptions of the use of IF blocks and DO loops in GAMBIT, see Appendix A.)

B.3.1 Arithmetic Expressions

GAMBIT arithmetic expressions are of the form:

sA₁ AOP sA₂

where s is a sign (+ or -) and A₁ and A₂ are arithmetic expressions that are related to each other by means the arithmetic operator, AOP.

The following table lists valid arithmetic operators.

Operators may not be placed immediately adjacent to each other. Parentheses may be used to determine a hierarchy of operations or for clarity. When parentheses are not used the order of operations is ^, *, /, + and -.

The expressions A₁ and A₂ may consist of a numerical values, constants, functions, parameters, or other arithmetic expressions of the form sA₁ AOP sA₂. There is no limit to the level of nesting of arithmetic expressions. Examples of valid arithmetic expressions are as follows:

-5.0*SIN($a)
2*(PI+(TAN($x+5)/($y-5)))
3^3.5 + 4*$rad*RAD2DEG
SQRT(2+MAX($a,$b))

Logical expressions consist of two types of operations:

• Relational
• Logical

Relational operations consist of comparisons made between arithmetic expressions. Logical operations consist of comparisons made between logical expressions.

Relational Operations

The general syntax for GAMBIT relational operations is as follows:

A₁ ROP A₂

where A₁ and A₂ are arithmetic expressions, and ROP is a relational operator that defines the comparison between the expressions. The following table lists the valid relational operators available in GAMBIT.

ROP	Description
.GT.	Greater than ( )
.GE.	Greater than or equal to ()
.LT.	Less than ( )
.LE.	Less than or equal to ( )
.EQ.	Equal to (=)
.NE.	Not equal to ( )

Logical Operations

The general syntax for GAMBIT logical operations is as follows:

L₁ LOP L₂

where L₁ and L₂ are arithmetic expressions, and LOP is a logical operator that defines the comparison between the expressions.

GAMBIT allows you to use any of the following logical operators:

• .AND.
• .OR.
• .NOT.

© Fluent, Inc. 12/10/01