APREPRO Functions

Several mathematical, Cube-it and string functions are implemented in APREPRO.

To cause a function to be used, you enter the name of the function followed by a list of zero or more arguments in parentheses. For example

sqrt(min(a,b*3))

uses the two functions sqrt() and min(). The arguments a and b*3 are passed to min(). The result is then passed as an argument to sqrt(). The functions in APREPRO are listed below along with the number of arguments and a short description of their effect.

1. Mathematical Functions

The following mathematical functions are available in APREPRO. Check current APREPRO documentation for any updates to this list of functions.

Table 1. Mathematical Functions

Syntax

Description

abs(x)

Calculates the absolute value of x. |x|

acos(x)

Calculates the inverse cosine of x, returns radians

acosd(x)

Calculates the inverse cosine of x, returns degrees

acosh(x)

Calculates the inverse hyperbolic cosine of x

asin(x)

Calculates the inverse sine of x, returns radians

asind(x)

Calculates the inverse sine of x, returns degrees

asinh(x)

Calculates the inverse hyperbolic sine of x

atan(x)

Calculates the inverse tangent of x, returns radians

atan2(y,x)

Calculates the inverse tangent of y/x, returns radians

atan2d(y,x)

Calculates the inverse tangent of y/x, returns degrees

atand(x)

Calculates the inverse tangent of x, returns degrees

atanh(x)

Calculates the inverse hyperbolic tangent of x

ceil(x)

Calculates the smallest integer not less than x

cos(x)

Calculates the cosine of x, with x in radians

cosd(x)

Calculates the cosine of x, with x in degrees

cosh(x)

Calculates the hyperbolic cosine of x

d2r(x)

Converts degrees to radians.

dim(x,y)

Calculates x - min(x,y).

dist(x1,y1, x2,y2)

Calculates distance from x1,y1 to x2,y2

exp(x)

Calculates ex (Exponential)

floor(x)

Calculates the largest integer not greater than x.

fmod(x,y)

Calculates the floating-point remainder of x/y.

hypot(x,y)

Calculates sqrt(x2+y2)

int(x), [x]

Calculates the integer part of x truncated toward 0.

julday(mm, dd, yy)

Calculates the Julian day corresponding to mm/dd/yy.

juldayhms (mm, dd, yy, hh, mm, ss)

Calculates the Julian day corresponding to mm/dd/yy at hh:mm:ss

lgamma(x)

Calculates log(G(x))

ln(x), log(x)

Calculates the natural (base e) logarithm of x.

log1p(x)

Calculates log(1+x)

log10(x)

Calculates the base 10 logarithm of x.

max(x,y)

Calculates the maximum of x and y.

min(x,y)

Calculates the minimum of x and y.

polarX(r,a)

Calculates r ´ cos(a), a is in degrees

polarY(r,a)

Calculates r ´ sin(a), a is in degrees

r2d(x)

Converts radians to degrees.

rand(xl,xh)

Calculates a random number between xl and xh.

sign(x,y)

Calculates x ´ sgn(y)

sin(x)

Calculates the sine of x, with x in radians.

sind(x)

Calculates the sine of x, with x in degrees.

sinh(x)

Calculates the hyperbolic sine of x

sqrt(x)

Calculates the square root of x.

tan(x)

Calculates the tangent of x, with x in radians.

tand(x)

Calculates the tangent of x, with x in degrees.

tanh(x)

Calculates the hyperbolic tangent of x.

Vangle(x1,y1, x2,y2)

Calculates the angle between the vector x1i + y1j and x2i + y2j. Returns radians.

Vangled(x1,y1, x2,y2)

Calculates the angle between the vector x1i + y1j and x2i + y2j. Returns degrees.

2. Cube-it Functions

The following Cube-it Functions are available:

Table 2. Cube-it Functions

Syntax Description
BlockAttributeName(id, index)

Returns the name for the specified attribute index in the block within the given id

BlockAttributeValue(id, index)

Returns the value for the specified attribute index in the block within the given id

NumBlocks Returns the number of blocks defined
NumSidesets Returns the number of sidesets defined
NumNodesets Returns the number of nodesets defined
FileExists(filename) Checks if the given file exists. Returns non-zero if it does
GeometryEngineVersion(engine name) Get the geometry version for the specified geometry engine
get_error_count() Gets the current error count in Cube-it
set_error_count(val) Sets the error count in Cube-it to given value
get_warning_count() Gets the current warning count in Cube-it
HasFeature(feature_name)

Checks if the feature "feature_name" is available and returns nonzero if the feature is enabled

set_warning_count(val) Sets the warning count in Cube-it to value
Id("type") Returns the ID of the entity most recently created with the specified type. Acceptable types include: "body", "volume", "surface", "curve", "vertex", "group", "node", "edge", "quad", "face", "tri", "hex", "tet", or "pyramid".
GroupMemberId("group_name",
"entity_type", index)
Returns the ID of "entity_type" in group "group_name" at the specified index. If the group contains multiple entity types the index will only be relevant for the entity type specified and will behave as if the group only contained that entity type.
IntNum(id) Returns the number of intervals on a curve with the given id.
IntNum(x, y, z, ord) Returns the number of intervals on a curve identified by the given center point coordinates and ordinal value.
IntSize(id) Returns the interval size on a curve with the given id.
IntSize(x, y, z, ord) Returns the interval size on a curve identified by the given center point coordinates and ordinal value.
Volume(id) Gets the geometric volume of the volume with the given id.
Volume(x, y, z, ord) Gets the geometric volume of the volume identified by the given center point coordinates and ordinal value.
SurfaceArea(id) Returns the surface area of the surface with the given id.
SurfaceArea(x, y, z, ord) Returns the surface area of the surface  identified by the given center point coordinates and ordinal value.
Length(id) Returns the length of the curve with the given id.
Length(x, y, z, ord) Returns the length of the curve identified by the given center point coordinates and ordinal value.
Radius(id) Returns the radius of the curve at its midpoint.
Radius(x, y, z, ord) Returns the radius of the curve identified by the given center point coordinates and ordinal value.
MinVolumeMeshQuality(id, "metric") Returns the worst value of the specified element quality metric of all elements in the volume with the given id.

Acceptable metrics include:
shape
aspect ration bet
aspect ratio gam
aspect ratio
condition no
diagonal ratio
dimension
distortion
element volume
jacobian
relative size
scaled jacobian
shape and size
shear and size
shear
skew
stretch
taper

MinVolumeMeshQuality(x, y, z, ord, "metric") Returns the worst value of the specified element quality metric of all elements in the volume identified by the given center point coordinates and ordinal value.
  
Acceptable metrics include:
shape
aspect ration bet
aspect ratio gam
aspect ratio
condition no
diagonal ratio
dimension
distortion
element volume
jacobian
relative size
scaled jacobian
shape and size
shear and size
shear
skew
stretch
taper
MinSurfaceMeshQuality(id, "metric") Returns the worst value of the specified element quality metric of all elements on the given surface.

Acceptable metrics include:
shape
aspect ratio
condition no
distortion
element area
jacobian
maximum angle
minimum angle
relative size
scaled jacobian
shape and size
shear and size
shear
skew
stretch
taper
warpage

MinSurfaceMeshQuality(x, y, z, ord, "metric") Returns the worst value of the specified element quality metric of all elements on the surface identified by the given center point coordinates and ordinal value.

Acceptable metrics include:
shape
aspect ratio
condition no
distortion
element area
jacobian
maximum angle
minimum angle
relative size
scaled jacobian
shape and size
shear and size
shear
skew
stretch
taper
warpage

MeshVolume(id) Returns the total volume of all mesh elements in the volume with the given id. This will vary from the actual geometric volume since the mesh approximates curved boundaries with linear mesh edges.
MeshVolume(x, y, z, ord) Returns the total volume of all mesh elements in the volume identified by the given center point coordinates and ordinal value. This will vary from the actual geometric volume since the mesh approximates curved boundaries with linear mesh edges.
HexVolume(id) Returns the volume of the hex with the given id.
HexVolume(x, y, z, ord) Returns the volume of the hex identified by the given center point coordinates and ordinal value.
TetVolume(id) Returns the volume of the tet with the given id.
TetVolume(x, y, z, ord) Returns the volume of the tet identified by the given center point coordinates and ordinal value.
FaceArea(id) Returns the area of the face with the given id.
FaceArea(x, y, z, ord) Returns the area of the face identified by the given center point coordinates and ordinal value.
TriArea(id) Returns the area of the tri with the given id.
TriArea(x, y, z, ord) Returns the area of the tri identified by the given center point coordinates and ordinal value. .
MeshSurfaceArea(id) Returns the total area of all triangle or quadrilateral elements on the surface with the given id. This will vary from the geometric surface area since the mesh approximates the boundary with linear mesh edges.
MeshSurfaceArea(x, y, z, ord) Returns the total area of all triangle or quadrilateral elements on the surface  identified by the given center point coordinates and ordinal value. This will vary from the geometric surface area since the mesh approximates the boundary with linear mesh edges.
EdgeLength(id) Returns the length of the edge with the given id.
EdgeLength(x, y, z, ord) Returns the length of the edge identified by the given center point coordinates and ordinal value.
MeshLength(id) Gets the length of the meshed curve with the given id.
MeshLength(x, y, z, ord) Gets the length of the meshed curve identified by the given center point coordinates and ordinal value.
Nx(id), Ny(id), Nz(id) Gets the x, y or z coordinate of node with the given id.
Nx(x, y, z, ord)
Ny(x, y, z, ord)
Nz(x, y, z, ord)
Gets the x, y or z coordinate of node identified by the given center point coordinates and ordinal value.
Vx(id), Vy(id), Vz(id) Gets the x, y or z coordinate of vertex with the given id.
Vx(x, y, z, ord)
Vy(x, y, z, ord)
Vz(x, y, z, ord)
Gets the x, y or z coordinate of vertex identified by the given center point coordinates and ordinal value.
NumInGrp("groupname") Returns the number of entities in the given group.
NumTypeInGroup("group_name",
"entity_type")
Returns the number of "entity_type" in group "group_name".
NumEdgesOnCurve(id) Returns the number of edges on the curve with the given id.
NumEdgesOnCurve(x, y, z, ord) Returns the number of edges on the curve identified by the given center point coordinates and ordinal value.
NumElemsOnSurface(id) Returns the number of elements on the surface with the given id.
NumElemsOnSurface(x, y, z, ord) Returns the number of elements on the surface identified by the given center point coordinates and ordinal value.
NumElemsInVolume(id) Returns the number of elements in the volume with the given id.
NumElemsInVolume(x, y, z, ord) Returns the number of elements in the volume identified by the given center point coordinates and ordinal value.
NumVolumes() Returns the number of volumes in the model.
NumSurfaces() Returns the number of surfaces in the model.
NumCurves() Returns the number of curves in the model.
NumVertices() Returns the number of vertices in the model.
NumVolsInPart("part_name") Returns the number of volumes assigned to the part with the specified name.
PartInVol(id) Returns the name and instance number of the part that the volume has been assigned to.
SessionId() Returns a unique ID for each Cube-it session.
DUMP() Returns a list of all APREPRO variables with their values.
delete("var") Deletes the APREPRO variable with the name var.
GeomCentroid_X("type", id) Returns the x coordinate of the centroid of the specified geometric entity. "type" can be "volume" or "group". If “volume” it calculates the centroid for the volume with the given id (single volume). If “group” it must be a group of volumes and it will calculate the combined centroid for the whole group with the given id.
GeomCentroid_Y("type", id) Returns the y coordinate of the centroid of the specified geometric entity. "type" can be "volume" or "group". If “volume” it calculates the centroid for the volume with the given id (single volume). If “group” it must be a group of volumes and it will calculate the combined centroid for the whole group with the given id.
GeomCentroid_Z("type", id) Returns the z coordinate of the centroid of the specified geometric entity. "type" can be "volume" or "group". If “volume” it calculates the centroid for the volume with the given id (single volume). If “group” it must be a group of volumes and it will calculate the combined centroid for the whole group with the given id.
MeshCentroid_X("type", id) Returns the x coordinate of the centroid of the specified mesh entity. “type” can be “volume”, “block”, or “group”. If “volume” it calculates the centroid of the 3D elements in the volume with the given id. If “block” it calculates the centroid of the elements in the block with the given id. If “group” it must be a group of volumes and it calculates the centroid of the group with the given id.
MeshCentroid_Y("type", id) Returns the y coordinate of the centroid of the specified mesh entity. “type” can be “volume”, “block”, or “group”. If “volume” it calculates the centroid of the 3D elements in the volume with the given id. If “block” it calculates the centroid of the elements in the block with the given id. If “group” it must be a group of volumes and it calculates the centroid of the group with the given id.
MeshCentroid_Z("type", id) Returns the z coordinate of the centroid of the specified mesh entity. “type” can be “volume”, “block”, or “group”. If “volume” it calculates the centroid of the 3D elements in the volume with the given id. If “block” it calculates the centroid of the elements in the block with the given id. If “group” it must be a group of volumes and it calculates the centroid of the group with the given id.
BBox_XMin("type", id) Returns the xmin value of the bounding box of the specified geometric entity. “type” can be “volume”, “surface”, “curve”, “vertex”, or “group”. If “volume”, “surface”, “curve”, or “vertex” it will calculate the bounding box for the entity with the given id. If “group” it will calculate the combined bounding box for the group. A group can have any of the geometry types (vol, surf, curve, vert) in it and can be of mixed types.
BBox_XMax("type", id) Returns the xmax value of the bounding box of the specified geometric entity. “type” can be “volume”, “surface”, “curve”, “vertex”, or “group”. If “volume”, “surface”, “curve”, or “vertex” it will calculate the bounding box for the entity with the given id. If “group” it will calculate the combined bounding box for the group. A group can have any of the geometry types (vol, surf, curve, vert) in it and can be of mixed types.
BBox_YMin("type", id) Returns the ymin value of the bounding box of the specified geometric entity. “type” can be “volume”, “surface”, “curve”, “vertex”, or “group”. If “volume”, “surface”, “curve”, or “vertex” it will calculate the bounding box for the entity with the given id. If “group” it will calculate the combined bounding box for the group. A group can have any of the geometry types (vol, surf, curve, vert) in it and can be of mixed types.
BBox_YMax("type", id) Returns the ymax value of the bounding box of the specified geometric entity. “type” can be “volume”, “surface”, “curve”, “vertex”, or “group”. If “volume”, “surface”, “curve”, or “vertex” it will calculate the bounding box for the entity with the given id. If “group” it will calculate the combined bounding box for the group. A group can have any of the geometry types (vol, surf, curve, vert) in it and can be of mixed types.
BBox_ZMin("type", id) Returns the zmin value of the bounding box of the specified geometric entity. “type” can be “volume”, “surface”, “curve”, “vertex”, or “group”. If “volume”, “surface”, “curve”, or “vertex” it will calculate the bounding box for the entity with the given id. If “group” it will calculate the combined bounding box for the group. A group can have any of the geometry types (vol, surf, curve, vert) in it and can be of mixed types.
BBox_ZMax("type", id) Returns the zmax value of the bounding box of the specified geometric entity. “type” can be “volume”, “surface”, “curve”, “vertex”, or “group”. If “volume”, “surface”, “curve”, or “vertex” it will calculate the bounding box for the entity with the given id. If “group” it will calculate the combined bounding box for the group. A group can have any of the geometry types (vol, surf, curve, vert) in it and can be of mixed types.
NodeAt(x, y, z) Returns the id of the node closest to the xyz location.
NodeAt(x, y, z, ordinal) Returns the id of the Node with the idless reference, x,y,z,ordinal.
EdgeAt(x, y, z, ordinal) Returns the id of the edge with the idless reference, x,y,z,ordinal.
FaceAt(x, y, z, ordinal) Returns the id of the quad face with the idless reference, x,y,z,ordinal.
TriAt(x, y, z, ordinal) Returns the id of the triangle with the idless reference, x,y,z,ordinal.
HexAt(x, y, z, ordinal) Returns the id of the hexahedra element with the idless reference, x,y,z,ordinal.
TetAt(x, y, z, ordinal) Returns the id of the tetraheral element with the idless reference, x,y,z,ordinal.
WedgeAt(x, y, z, ordinal) Returns the id of the wedge element with the idless reference, x,y,z,ordinal.
PyramidAt(x, y, z, ordinal) Returns the id of the pyramid element with the idless reference, x,y,z,ordinal.
VertexAt(x, y, z, ordinal) Returns the id of the vertex with the idless reference, x,y,z,ordinal.
CurveAt(x, y, z, ordinal) Returns the id of the curve with the idless reference, x,y,z,ordinal.
SurfaceAt(x, y, z, ordinal) Returns the id of the surface with the idless reference, x,y,z,ordinal.
VolumeAt(x, y, z, ordinal) Returns the id of the volume with the idless reference, x,y,z,ordinal.

3.String Functions

A few useful string functions are available:

Table 3. String Functions

Syntax

Description

tolower(svar)

Translates all uppercase characters in svar to lowercase. It modifies svar and returns the resulting string.

toupper(svar)

Translates all lowercase character in svar to uppercase. It modifies svar and returns the resulting string.

execute(svar)

svar is parsed and executed as if it were a line read from the input file. For example,

if svar="b=sqrt(25.0)", then
#{execute(svar)}

returns the value 5 and sets b = 5. The expression svar is enclosed in delimiters prior to being executed, and it must be a valid expression or an error message will be printed.

rescan(svar)

Similar to execute(svar), except that svar is not enclosed in delimiters prior to being executed. For example,

if svar = "Create Vertex {1+5} {sqrt(5)} {sqrt(6)}", then
#{rescan(svar)}

would print:

Create Vertex 6 2.236067977 2.449489743.

The difference between execute(sv1) and rescan(sv2) is that sv1 must be a valid expression, but sv2 can contain zero or more expressions.

getenv(svar)

Returns a string containing the value of the environment variable svar. If the environment variable is not defined, an empty string is returned.

get_word(n,svar,del)

Returns a string containing the nth word of svar. The words are separated by one or more of the characters in the string variable del

word_count(svar,del)

Returns the number of words in svar. Words are separated by one or more of the characters in the string variable del

strtod(svar)

Returns a double-precision floating-point number equal to the value represented by the character string pointed to by svar.

Print(msg) Prints msg
PrintError(svar) Outputs the string svar to stderr.
error(svar) Outputs the string svar to stderr and then terminates the code with an error exit status
Quote(svar) Returns the string svar, enclosed in single quotes.
TimerStart() Starts the CPU timer
TimerStop() Stops the CPU timer
Type(entity name) Returns the type of the entity with the given name
Units(svar) Sets variables useful for working in a unit system. See APREPRO Units.

The following example shows the use of some of the string functions.

#{t1 = "ATAN2"} {t2 = "(0, -1)"}

#{t3 = tolower(t1//t2)}

...The variable t3 is equal to the string atan2(0, -1)

#{execute(t3)}

...t3 = 3.141592654

The result is the same as executing {atan2(0, -1)}

This is admittedly a very contrived example; however, it does illustrate the workings of several of the functions. In the first example, an expression is constructed by concatenating two strings together and converting the resulting string to lowercase. This string is then executed.

The following example uses the rescan function to illustrate a basic macro capability in APREPRO. The example creates vertices in Cube-it equally spaced about the circumference of a 180 degree arc of radius 10. Note that the macro is 5 lines long (3 of the lines start with #, with the exception of the looping constructs - the actual journal file for this would not continue lines but would put each one on one long line).

#{num = 0} {rad = 10} {nintv = 10} {nloop = nintv + 1}

#{line = 'Create Vertex {polarX(rad, (++num-1) * 180/nintv)} {polarY(rad, (num-1) * 180/nintv)}'}

#{loop(nloop)}

#{rescan(line)}

#{endloop}

Output:

Create Vertex 10 0

Create Vertex 9.510565163 3.090169944

Create Vertex 8.090169944 5.877852523

Create Vertex 5.877852523 8.090169944

Create Vertex 3.090169944 9.510565163

Create Vertex 6.123233765e-16 10

Create Vertex -3.090169944 9.510565163

Create Vertex -5.877852523 8.090169944

Create Vertex -8.090169944 5.877852523

Create Vertex -9.510565163 3.090169944

Create Vertex -10 1.224646753e-15

Note the loop construct to automatically repeat the rescan line. To modify this example to calculate the coordinates of 101 points rather than eleven, the only change necessary would be to set {nintv=100}.