APREPRO - Cubit - Sandia National Laboratories

4 downloads 10 Views 486KB Size Report
Jun 27, 2013 - Facsimile: (703) 605-6900. E-Mail: [email protected] Online ordering: .... 7.1 Units Systems and Corresponding Output Format–Metric . . . . . . . . . . . . . . . ...... is defined in terms of M/L3 which is mass/ length3. Table 7.3: ...

SANDIA REPORT SAND92-2291 Unlimited Release Printed June 27, 2013

APREPRO: An Algebraic Preprocessor for Parameterizing Finite Element Analyses Gregory D. Sjaardema Prepared by Sandia National Laboratories Albuquerque, New Mexico 87185 and Livermore, California 94550 Sandia National Laboratories is a multi-program laboratory managed and operated by Sandia Corporation, a wholly owned subsidiary of Lockheed Martin Corporation, for the United States Department of Energy’s National Nuclear Security Administration under Contract DE-AC04-94AL85000. Approved for public release; further dissemination unlimited.

Issued by Sandia National Laboratories, operated for the United States Department of Energy by Sandia Corporation. NOTICE: This report was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government, nor any agency thereof, nor any of their employees, nor any of their contractors, subcontractors, or their employees, make any warranty, express or implied, or assume any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represent that its use would not infringe privately owned rights. Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government, any agency thereof, or any of their contractors or subcontractors. The views and opinions expressed herein do not necessarily state or reflect those of the United States Government, any agency thereof, or any of their contractors. Printed in the United States of America. This report has been reproduced directly from the best available copy. Available to DOE and DOE contractors from U.S. Department of Energy Office of Scientific and Technical Information P.O. Box 62 Oak Ridge, TN 37831 Telephone: Facsimile: E-Mail: Online ordering:

(865) 576-8401 (865) 576-5728 [email protected] http://www.osti.gov/bridge

Available to the public from U.S. Department of Commerce National Technical Information Service 5285 Port Royal Rd Springfield, VA 22161 (800) 553-6847 (703) 605-6900 [email protected] http://www.ntis.gov/help/ordermethods.asp?loc=7-4-0#online

NT OF E ME N RT

GY ER

DEP A

Telephone: Facsimile: E-Mail: Online ordering:



ED

ER

U NIT

IC A



ST

A TES OF A

M

2

SAND92-2291 Unlimited Release Printed June 27, 2013

APREPRO: An Algebraic Preprocessor for Parameterizing Finite Element Analyses Gregory D. Sjaardema Simulation Modeling Sciences Department Sandia National Laboratories Albuquerque, NM 87185-0380

Abstract Aprepro is an algebraic preprocessor that reads a file containing both general text and algebraic, string, or conditional expressions. It interprets the expressions and outputs them to the output file along with the general text. The syntax used in Aprepro is such that all expressions between the delimiters { and } are evaluated and all other text is simply echoed to the output file. Aprepro contains several mathematical functions, string functions, and flow control constructs. In addition, functions are included that implement a units conversion system. Aprepro was written primarily to simplify the preparation of parameterized input files for finite element analyses at Sandia National Laboratories; however, it can process any text file that does not use the characters { }.

3

4

Contents 1 Introduction

7

2 Execution

8

2.1

Aprepro Execution and Program Options . . . . . . . . . . . . . . . . . . . . . . . .

8

2.2

Interactive Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8

3 Syntax

10

4 Operators

13

4.1

Arithmetic Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13

4.2

Assignment Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13

4.3

Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14

4.4

Boolean Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14

4.5

String Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14

5 Predefined Variables

16

6 Functions

17

6.1

Mathematical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17

6.2

Additional Functions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

21

6.2.1

[var] or [expression] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

21

6.2.2

File Inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

21

6.2.3

Conditionals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

21

6.2.4

Switch Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

22

6.2.5

Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

22

6.2.6

ECHO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

23

6.2.7

VERBATIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

23

6.2.8

IMMUTABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

23

5

6.2.9

Output File Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7 Units Conversion System

24 25

7.1

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

25

7.2

Defined Units Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

26

7.3

Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

28

7.4

Additional Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

29

8 Error, Warning, and Informational Messages

31

8.1

Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

31

8.2

Warning Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

32

8.3

Informational Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

32

9 Examples

33

9.1

Mesh Generation Input File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

33

9.2

Macro Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

34

9.3

Command Line Variable Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . .

34

9.4

Loop Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

35

9.5

If Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

35

9.6

Aprepro Test File Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

36

10 Aprepro Library Interface

43

10.1 Adding basic Aprepro parsing to your application . . . . . . . . . . . . . . . . . . .

43

10.2 Additional Aprepro parsing capabilities . . . . . . . . . . . . . . . . . . . . . . . .

43

10.2.1 Adding new variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

44

10.2.2 Adding new functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

44

10.2.3 Modifying Aprepro Execution Settings . . . . . . . . . . . . . . . . . . . . .

44

10.3 Aprepro Library Test/Example Program . . . . . . . . . . . . . . . . . . . . . . . . .

45

Bibliography

47

6

List of Tables 2.2

Key Bindings used in the interactive input to Aprepro . . . . . . . . . . . . . . . .

9

4.1

Arithmetic Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13

4.2

Assignment Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14

4.3

Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14

4.4

Boolean Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14

5.1

Predefined Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16

5.2

Effect of various output format specifications . . . . . . . . . . . . . . . . . . . . . .

16

6.1

Mathematical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17

6.1

Mathematical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

18

6.2

String Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

18

6.2

String Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

19

7.1

Units Systems and Corresponding Output Format–Metric . . . . . . . . . . . . . . .

25

7.2

Units Systems and Corresponding Output Format–English . . . . . . . . . . . . . . .

25

7.3

Defined Units Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

26

7

1 Introduction Aprepro is an algebraic preprocessor that reads a file containing both general text and algebraic expressions. It echoes the general text to the output file, along with the results of the algebraic expressions. The syntax used in Aprepro is such that all expressions between the delimiters { and } are evaluated and all other text is simply echoed to the output file. For example, if the following lines are input to Aprepro: $ Rad = {Rad = 12.0} Point 1 {x1 = Rad * sind(30.)} {y1 = Rad * cosd(30.)} Point 2 {x1 + 10.0} {y1}

The output would look like: $ Rad = 12 Point 1 6 Point 2 16

10.39230485 10.39230485

In this example, the algebraic expressions are specified by surrounding them with { and }, and the functions sind() and cosd() calculate the sine and cosine of an angle given in degrees. Aprepro has been used extensively for several years to prepare parameterized files for finite element analyses using the Sandia National Laboratories SEACAS system [1]. The units conversion capability has greatly increased the usability of Aprepro. Aprepro can also be used for non-finite element applications such as a powerful calculator and a general text processor for any file that does not use the delimiters { and }. The remainder of this document is organized as follows: • Chapter 2 documents the command line options for Aprepro and the text input, editing, and recall capabilities. • Chapter 3 documents the syntax recognized by Aprepro, • Chapters 4, 5, and 6 describe the operators, predefined variables, and functions, • Chapter 7 describes the units conversion system, • Chapter 8 describes the error messages output from Aprepro, and • Chapter 9 presents some examples of Aprepro usage.

8

2 Execution 2.1

Aprepro Execution and Program Options

Aprepro is executed with the command: aprepro [--parameters] [-dsviehMWCq] [-I path] [-c char] [var=val] filein fileout

The effects of the parameters are: –debug (-d) –statistics (-s) –version (-v) –comment char (-c char) –immutable (-X) –interactive (-i) –include path (-I path) –exit on (-e) –message (-M) –nowarning (-W) –copyright (-c) –quiet (-q) –help (-h) var=val

input file output file

Dump all variables, debug loops/if/endif Print hash statistics at end of run Print version number to stderr Change comment character to ’char’ All variables are immutable–cannot be modified Interactive use, no buffering of output. Include file or include path If this is enabled, Aprepro will exit when any of the strings EXIT, Exit, exit, QUIT, Quit, or quit are entered. Otherwise, Aprepro will exit at end of file. Print INFO messages. (See Chapter 8 for a list of INFO messages.) Do not print warning messages. (See Chapter 8 for a list of warning messages.) Print copyright message Do not anything extra to stdout Print this list Assign value val to variable var. This lets you dynamically set the value of a variable and change it between runs without editing the input file. Multiple var=val pairs can be specified on the command line. A variable that is defined on the command line will be an immutable variable whose value cannot be changed1 . specifies the file that contains the Aprepro input. If this parameter is omitted, Aprepro will run interactively. specifies the file Aprepro will write the processed data to. If this parameter is omitted, Aprepro will write the data to the terminal. (stdout)

The - followed by a single letter shown in the parameter descriptions above are optional shortoptions that can be specified instead of the long options. For example, the following two lines are equivalent: aprepro --debug --nowarning --statistics --comment # aprepro -dWsc#

Note that the short options can be concatenated.

2.2

Interactive Input

If no input file is specified when Aprepro is executed, then all input will be read from standard input; or in other words, typed in by the user. In this mode, there are a few command-line editing and recall capabilities provided. 1 Unless

the variable name begins with an underscore.

9

The command-line editing provides Emacs style key bindings and history functionality. The key bindings are shown in the following table. The syntax ^X indicates that the user should press and hold the “control” key and then press the X key. The syntax M-X indicates pressing the “meta” key followed by the X key. The meta key is sometimes escape, or sometimes “alt”, or some other key depending on the users keymap. Table 2.2: Key Bindings used in the interactive input to Aprepro Key ˆA/ˆE ˆF/ˆB ˆD ˆH ˆK ˆL ˆO

ˆP/ˆN ˆR/ˆS

ˆT ˆU ˆY M-F/M-B ˆSPC ˆW ˆX RETURN

Function Move cursor to beginning/end of the line. Move cursor forward/backward one character. Delete the character under the cursor. Delete the character to the left of the cursor. Kill from the cursor to the end of line. Redraw current line. Toggle overwrite/insert mode. Initially in insert mode. Text added in overwrite mode (including yanks) overwrite existing text, while insert mode does not overwrite. Move to previous/next item on history list. Perform incremental reverse/forward search for string on the history list. Typing normal characters adds to the current search string and searches for a match. Typing ˆR/ˆS marks the start of a new search, and moves on to the next match. Typing ˆH deletes the last character from the search string, and searches from the starting location of the last search. Therefore, repeated ˆH’s appear to unwind to the match nearest the point at which the last ˆR or ˆS was typed. If ˆH is repeated until the search string is empty the search location begins from the start of the history list. Typing ESC or any other editing character accepts the current match and loads it into the buffer, terminating the search. Toggle the characters under and to the left of the cursor. Kill from beginning to the end of the line. Yank previously killed text back at current location. Note that this will overwrite or insert, depending on the current mode. Move cursor forward/backward one word. Set mark. Kill from mark to point. Exchange mark and point. returns current buffer to the program.

10

3 Syntax Aprepro is in one of two states while it is processing an input file, either echoing or parsing. In the echoing state, Aprepro echoes every character that it reads to the output file. If it reads the character {, it enters the parsing state. In the parsing state, Aprepro reads characters from the input file and identifies the characters as tokens which can be function names, variables, numbers, operators, or delimiters. When Aprepro encounters the character }, it tries to interpret the tokens as an algebraic, string, or conditional expression; if it is successful, it prints the value to the output file; if it cannot evaluate the expression, it prints the message: Aprepro:

ERROR: parse error {filename}, line {line#}

to the terminal1 prints the value 0 to the output file. The rules that Aprepro uses when identifying functions, variables, numbers, operators, delimiters, and expressions are described below: Functions Function names are sequences of letters and digits and underscores ( ) that begin with a letter. The function’s arguments are enclosed in parentheses. For example, in the line atan2(a,1.0), atan2 is the function name, and a and 1.0 are the arguments. See Chapter 6 for a list of the available functions and their arguments. Variables A variable is a name that references a numeric or string value. A variable is defined by giving it a name and assigning it a value. For example, the expression a = 1.0 defines the variable a with the numeric value 1.0; the expression b= "A string" defines the variable b with the value A string. Variable names are sequences of letters, digits, colons (:), and underscores ( ) that begin with either a letter or an underscore. Variable names cannot match any function name and they are case-sensitive, that is, abc de and AbC dE are two distinct variable names. A few variables are predefined, these are listed in Chapter 5. Any variable that is not defined is equal to 0. A warning message is output to the terminal if an undefined variable is used, or if a previously defined variable is redefined. If the variable name begins with an underscore, no warning is output when the variable is redefined.2 . Immutable Variables An immutable variable is a variable whose value cannot be changed. An immutable variable name is follows the same rules as a regular variable except that the name cannot begin with an underscore. Immutable variables are created inside an IMMUTABLE(ON) block (See Section ??) or when Aprepro is executed with the --immutable or -X command line options (See Chapter 2). If the value of an immutable variable is attempted to be modified, an error message of the form: [Aprepro: (IMMUTABLE) Variable ’variable’ is immutable and cannot be modified (file, line line#)] will be output to the standard error stream and the expression containing the assignment to the immutable variable will return nothing. Numbers Numbers can be integers like 1234, decimal numbers like 1.234, or in scientific notation like 1.234E-26. All numbers are stored internally as floating point numbers. Strings Strings are sequences of numbers, characters, and symbols that are delimited by either single quotes (’this is a string’) or double quotes ("this is another string"). Strings that are delimited by one type of quote can include the other type of quote. For example, ’This is a valid "string"’. Strings delimited by single quotes can span multiple lines; 1 Error messages are printed to standard error. On UNIX systems they can be redirected to a file using your shells redirection syntax. See the man page for your shell for more information. 2 Warnings can be turned off with the -W or --warning option.

11

strings delimited by double quotes must terminate on a single line or a parsing error message will be issued. Operators Operators are any of the symbols defined in Chapter 4. Examples are + (addition), (subtraction), * (multiplication), / (division), = (assignment), and ˆ (exponentiation) Delimiters The delimiters recognized by Aprepro are: the comma (,) which separates arguments in function lists, the left curly brace ({) which begins an expression, the right curly brace (}) which ends an expression, the left parenthesis ( which begins a function argument list, the right parenthesis ) which ends a function argument list, the single quote (’) which delimits a multiline string, and the double quote (") which delimits a single-line string. If a left or right curly brace is needed in the processes output without being interpreted by Aprepro, precede the curly brace with a backslash. For example, \{ \}. Expressions An expression consists of any combination of numeric and string constants, variables, operators, and functions. Four types of expressions are recognized in Aprepro: algebraic, string, relational, and conditional. Algebraic Expressions Almost any valid FORTRAN or C algebraic expression can be recognized and evaluated by Aprepro. An expression of the form a=b+10/37.5 will evaluate the expression on the right-hand-side of the equals sign, print the value to the output file, and assign the value to the variable a. An expression of the form b+10/37.5 will evaluate the expression and print the value to the output file. If you want to assign a value to a variable without printing the result, the expression must be inside an ECHO(ON|OFF) block (see 23). Variables can also be set on the command line prior to reading any input files using the var=val syntax. An example of this usage is given in Section 9.3. Only a single expression is allowed within the { } delimiters. For example, {x=sqrt(y^2 + sin(z))}, {x=y=z}, and{x=y} {a=z} are valid expressions, but {x=y a=z} is invalid because it contains two expressions within a single set of delimiters. String Expressions Aprepro has limited string support. The only supported operations are (1) assigning a variable equal to a string (a = "This is a string"), (2) functions that return a string (See Table 6.2), and (3) concatenating two strings into another string (a = "Hello" // " " // "World"). Relational Expressions: Relational expressions are expressions that return the result of comparing two expressions. A relational expression is either true (returns 1) or false (returns 0). A relational expression is simply two expressions of any kind separated by a relational operator (See Section 4.3). Conditional Expressions Aprepro recognizes a conditional expression of the form: relational expression ? true exp :

false exp

where relational expression can be any valid relational expression, and true exp and false exp are two algebraic expressions or string expressions. If the relational expression is true, then the result of true exp is returned, otherwise the result of false exp is returned. For example, if the following command were entered: a = (sind(20.0) > cosd(20.0) ? 1 : -1)

then, a would be assigned the value -1 since the relational expression to the left of the question mark is false. Both true exp and false exp are always evaluated prior to evaluating the relational expression. Therefore, you should not write an equation such as sind(20.0*a) > cosd(20.0*a) ? a=sind(20.0) : a=cosd(20.0)

12

since the value of a can change during the evaluation of the expression. Instead, this equation should be written as: a = (sind(20.0*a) > cosd(20.0*a) ? sind(20.0) : cosd(20.0))

13

4 Operators The operators recognized by Aprepro are listed below. The letters a and b can represent variables, numbers, functions, or expressions unless otherwise noted. The tables below also list the precedence and associativity of the operators. Precedence defines the order in which operations should be performed. For example, in the expression: {3 * 4 + 6 / 2}

the multiplications and divisions are performed first, followed by the addition because multiplication and division have higher precedence (10) than addition (9). The precedence is listed from 1 to 14 with 1 being the lowest precedence and 14 being the highest. Associativity defines which side of the expressions should be simplified first. For example the expression: 3 + 4 + 5 would be evaluated as (3 + 4) + 5 since addition is left associative; in the expression a = b / c, the b/c would be evaluated first followed by the assignment of that result to a since equality is right associative

4.1

Arithmetic Operators

Arithmetic operators combine two or more algebraic expressions into a single algebraic expression. These have obvious meanings except for the pre- and post- increment and decrement operators. The pre-increment and pre-decrement operators first increment or decrement the value of the variable and then return the value. For example, if a = 1, then b=++a will set both b and a equal to 2. The post-increment and post-decrement operators first return the value of the variable and then increment or decrement the variable. For example, if a = 1, then b=a++ will set b equal to 1 and a equal to 2. The modulus operator % calculates the integer remainder. That is both expressions are truncated an integer value and then the remainder calculated. See the fmod function in Table 6.1 for the calculation of the floating point remainder. The tilde character ~ is used as a synonym for multiplication to improve the aesthetics of the unit conversion system (see Chapter 7). It is more natural for some users to type 12~metre than 12*metre. Table 4.1: Arithmetic Operators Syntax a+b a-b a*b, a~b a/b a^b, a**b a%b ++a, a++ --a, a--

4.2

Description Addition Subtraction Multiplication Division Exponentiation Modulus, (remainder) Pre- and Post-increment a Pre- and Post-decrement a

Precedence 9 9 10 10 12 10 13 13

Associativity left left left left right left left left

Assignment Operators

Assignment operators combine a variable and an algebraic expression into a single algebraic expression, and also set the variable equal to the algebraic expression. Only variables can be specified on

14

the left-hand-side of the equal sign. Table 4.2: Assignment Operators Syntax a=b a+=b a-=b a*=b a/=b aˆ=b, a**=b

4.3

Description The value of The value of The value of The value of The value of The value of

a a a a a a

is is is is is is

set set set set set set

equal equal equal equal equal equal

to to to to to to

b a+b a−b a∗b a/b ab

Precedence 1 2 2 3 3 4

Associativity right right right right right right

Relational Operators

Relational operators combine two algebraic expressions into a single relational expression. Relational expressions and operators can only be used before the question mark (?) in a conditional expression. Table 4.3: Relational Operators Syntax a < b a > b a = b a == b a != b

4.4

Description true if a is less than b true if a is greater than b true if a is less than or equal to b true if a is greater than or equal to b true if a is equal to b true if a is not equal to b

Precedence 8 8 8 8 8 8

Associativity left left left left left left

Boolean Operators

Boolean operators combine one or more relational expressions into a single relational expression. If la and lb are two relational expressions, then: Table 4.4: Boolean Operators Syntax la || lb la && lb !la

Description true if either la or lb are true. true if both la and lb are true. true if la is false.

Precedence 6 7 11

Associativity left left left

The evaluation of the expression is not short-circuited if the truth value can be determined early; both sides of the expression are evaluated and then the truth of the expression is returned.

4.5

String Operators

The only supported string operator at this time is string concatenation which is denoted by //. For example,

15

{a = "Hello"} {b = "World"} {c = a // " " // b}

sets c equal to "Hello World". Concatenation has precedence 14 and left associativity.

16

5 Predefined Variables A few commonly used variables are predefined in Aprepro1 . These are listed below. The default output format FORMAT is specified as a C language format string, see your C language documentation for more information. The default output format ( FORMAT) and comment ( C ) variables are defined with a leading underscore in their name so they can be redefined without generating an error message. Table 5.1: Predefined Variables Name PI PI 2 TAU SQRT2 DEG RAD E GAMMA PHI VERSION FORMAT C

Value 3.14159265358979323846 1.57079632679489661923 6.28318530717958623200 1.41421356237309504880 57.2957795130823208768 0.01745329251994329576 2.71828182845904523536 0.57721566490153286060 1.61803398874989484820 Varies, string value "%.10g" "$"

Description π π/2 2π √ 2 180/π degrees per radian π/180 radians per degree base of natural logarithm γ, euler-mascheroni constant √ golden ratio ( 5 + 1)/2 current version of Aprepro default output format default comment character

Note that the output format is used to output both integers and floating point numbers. Therefore, it should use the %g format descriptor which will use either the decimal (%d), exponential (%e), or float (%f) format, whichever is shorter, with insignificant zeros suppressed. The table below illustrates the effect of different format specifications on the output of the variable PI and the value 1.0 . See the documentation of your C compiler for more information. For most cases, the default value is sufficient. Table 5.2: Effect of various output format specifications Format %.10g %.10e %.10f %.10d

PI Output 3.141592654 3.1415926536e+00 3.1415926536 1413754136

1.0 Output 1 1.0000000000e+00 1.0000000000 0000000000

The comment character should be set to the character that the program which will read the processed file uses as a comment character. The default value of "$" is the comment character used by the SEACAS codes at Sandia National Laboratories. The -c command line option (described in Chapter 2) changes the value of the comment variable to match the character specified on the command line.

1 The

units system described in Chapter 7 also predefines several variables when it is activated

17

6 Functions Several mathematical 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.

6.1

Mathematical Functions

The following mathematical functions are available in Aprepro. Table 6.1: Mathematical Functions Syntax abs(x) acos(x) acosd(x) acosh(x) asin(x) asin(x) asinh(x) atan(x) atan2(x,y) atan2d(x,y) atand(x) atanh(x) ceil(x) cos(x) cosd(x) cosh(x) d2r(x) dim(x,y) dist(x1,y1, x2,y2) exp(x) floor(x) fmod(x,y) hypot(x,y) int(x), [x] julday(mm, dd, yy) juldayhms(mm, dd, yy, hh, mm, ss) lgamma(x) ln(x) log(x) log10(x)

Description Absolute value of x. |x|. Inverse cosine of x, returns radians. Inverse cosine of x, returns degrees. Inverse hyperbolic cosine of x. Inverse sine of x, returns degrees. Inverse sine of x, returns radians. Inverse hyperbolic sine of x. Inverse tangent of x, returns radians. Inverse tangent of y/x, returns radians. Inverse tangent of y/x, returns degrees. Inverse tangent of x, returns degrees. Inverse hyperbolic tangent of x. Smallest integer not less than x. Cosine of x, with x in radians Cosine of x, with x in degrees Hyperbolic cosine of x. Degrees to radians. x p− min(x, y) (x1 − x2 )2 + (y1 − y2 )2 Exponential ex Largest integer not greater than x. Floating-point remainder of x/y. p 2 2 x +y . Integer part of x truncated toward 0. Julian day corresponding to mm/dd/yy. Julian day corresponding to mm/dd/yy at hh:mm:ss log(Γ(x)). Natural (base e) logarithm of x. Natural (base e) logarithm of x. Base 10 logarithm of x.

18

Table 6.1: Mathematical Functions Syntax log1p(x) max(x,y) min(x,y) nint(x) polarX(r,a) polarY(r,a) r2d(x) rand(xl,xh) rand lognormal(m,s) rand normal(m,s) rand weibull(a, b) sign(x,y) sin(x) sind(x) sinh(x) sqrt(x) srand(seed)

strtod(svar) tan(x) tand(x) tanh(x) Vangle(x1,y1,x2,y2) Vangled(x1,y1,x2,y2) word count(svar,del)

Description log(1 + x) Accurate even for very small values of x Maximum of x and y. Minimum of x and y. Rounds x to nearest integer. < 0.5 down; >= 0.5 up. r ∗ cos(a), a is in degrees r ∗ sin(a), a is in degrees Radians to degrees. Random value between xl and xh; uniformly distributed. Random value with lognormal distribution with mean m and stddev s. Random value normally distributed with mean m and stddev s. Random value with weibull distribution with α = a and β = b. x ∗ sgn(y) Sine of x, with x in radians. Sine of x, with x in degrees. Hyperbolic sine of√x Square root of x. x Seed the random number generator with the given integer value. At the beginning of Aprepro execution, srand() is called with the current time as the seed. Returns a double-precision floating-point number equal to the value represented by the character string pointed to by svar. Tangent of x, with x in radians. Tangent of x, with x in radians. Hyperbolic tangent of x. Angle (radians) between vector x1ˆi + y1 ˆj and x2ˆi + y2 ˆj. Angle (degrees) between vector x1ˆi + y1 ˆj and x2ˆi + y2 ˆj. Number of words in svar. Words are separated by one or more of the characters in the string variable del.

Table 6.2: String Functions Syntax DUMP() DUMP FUNC() DUMP PREVAR() IO(x)

Units(svar) error(svar) execute(svar)

Description Output a list of all defined variables and their value. Output a list of all double and string functions recognized by Aprepro. Output a list of all predefined variables and their value. Convert x to an integer and then to a string. Can be used to output integer values if your output format ( FORMAT) is set to something that doesn’t output integers correctly. See Chapter 7. svar is one of the defined units systems: ’si’, ’cgs’, ’cgs-ev’, ’shock’, ’swap’, ’ft-lbf-s’, ’ft-lbm-s’, ’in-lbf-s’ Outputs the string svar to stderr and then terminates the code with an error exit status. svar is parsed and executed as if it were a line read from the input file.

19

Table 6.2: String Functions Syntax extract(s, b, e)

file to string(fn) get date() get iso date() get time() get word(n,svar,del

getenv(svar)

help() include path(path)

output(filename)

output append(fn) rescan(svar)

to lower(svar) tolower(svar) to string(x) tostring(x) to upper(svar) toupper(svar)

Description Return substring [b,e). b is included; e is not. If b not found, return empty; If e not found, return rest of string. If b empty, start at beginning; if e empty, return rest of string. Opens the file specified by fn and returns the contents as a multiline string. Returns a string representing the current date in the form YYYY/MM/DD. Returns a string representing the current date in the form YYYYMMDD. Returns a string representing the current time in the form HH:MM:SS. 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 Returns a string containing the value of the environment variable svar. If the environment variable is not defined, an empty string is returned. Tell how to get help on variables, functions, . . . Specify an optional path to be prepended to a filename when opening a file. Can also be specified via the -I command line option when executing aprepro. Creates the file specified by filename and sends all subsequent output from aprepro to that file. Calling output(¨ stdout¨ ) will close the current output file and return output to the terminal (standard output). If file with name fn exists, append output to it; otherwise create the file and send all subsequent output from aprepro to that file. The difference between execute(sv1) and rescan(sv2) is that sv1 must be a valid expression, but sv2 can contain zero or more expressions. Translates all uppercase characters in svar to lowercase. It modifies svar and returns the resulting string. Translates all uppercase characters in svar to lowercase. It modifies svar and returns the resulting string. Returns a string representation of the numerical variable x. The variable x is unchanged. Returns a string representation of the numerical variable x. The variable x is unchanged. Translates all lowercase character in svar to uppercase. It modifies svar and returns the resulting string. Translates all lowercase character in svar to uppercase. It modifies svar and returns the resulting string.

The following example shows the use of some of the string functions. The input: {t1 = "ATAN2"} {t2 = "(0, -1)"} {t3 = tolower(t1//t2)}

20

{execute(t3)}

produces the output: ATAN2 (0, -1) atan2(0, -1) 3.141592654

The variable t3 is equal to the string atan2(0,-1) 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 example, an expression is constructed by concatenating two strings together and converting the resulting string to lowercase. This string is then executed and simply prints the result of evaluating the expression. The following example uses the rescan function to illustrate a basic macro capability in Aprepro. The example calculates the coordinates of eleven points (Point1 . . . Point11) equally spaced about the circumference of a 180 degree arc of radius 10. {ECHO(OFF)} {num = 0} {rad = 10} {nintv = 10} {nloop = nintv + 1} {line = ’Define {"Point"//tostring(++num)}, {polarX(rad, (num-1) * 180/nintv)} {polarY(rad, (num-1)*180/nintv)}’} {ECHO(ON)} {loop(nloop)} {rescan(line)} {endloop}

Output: Define Define Define Define Define Define Define Define Define Define Define

Point1, Point2, Point3, Point4, Point5, Point6, Point7, Point8, Point9, Point10, Point11,

10 0 9.510565163 3.090169944 8.090169944 5.877852523 5.877852523 8.090169944 3.090169944 9.510565163 6.123233765e-16 10 -3.090169944 9.510565163 -5.877852523 8.090169944 -8.090169944 5.877852523 -9.510565163 3.090169944 -10 1.224646753e-15

Note the use of the ECHO(OFF|ON) block to suppress output during the initialization phase, and the loop construct to automatically repeat the rescan line. The variable num is converted to a string after it is incremented and then concatenated to build the name of the point. In the definition of the variable line, single quotes are first used since this is a multi-line string; double quotes are then used to embed another string within the first string. To modify this example to calculate the coordinates of 101 points rather than eleven, the only change necessary would be to set {nintv=100}.

21

6.2

Additional Functions

6.2.1

[var] or [expression]

Surrounding a variable or expression by square brackets will return the integer value of that variable or expression truncated toward zero. For example [sqrt(2)] will return the value 1.

6.2.2

File Inclusion

Aprepro can read input from multiple files using the include() and cinclude() functions. If a line of the form: {include("filename ")} {include(string variable)} is read, Aprepro will open and begin reading from the file filename. A string variable can be used as the argument instead of a literal string value. When the end of the file is reached, it will be closed and Aprepro will continue reading from the previous file. The difference between include() and cinclude() is that if filename does not exist, include() will terminate Aprepro with a fatal error, but cinclude() will just write a warning message and continue with the current file. The cinclude() function can be thought of as a conditional include, that is, include the file if it exists. Multiple include files are allowed and an included file can also include additional files. This option can be used to set variables globally in several files. For example, if two or more input files share common points or dimensions, those dimensions can be set in one file that is included in the other files. If ECHO(OFF) is in effect during in an included file, ECHO(ON) will automatically be executed at the end of the included file.

6.2.3

Conditionals

Portions of an input file can be conditionally processed through the use of the if(expression), elseif(expression), else, and endif construct.1 The syntax is: {if(expression)} ... Lines processed if ’expression’ is true or non-zero. {elseif(expression2)} ... Lines processed if ’expression’ is false and ’expression2’ is true. {else} ... Lines processed if both ’expression’ and ’expression2’ are false. {endif}

The elseif() and else are optional. Note that if expression is a simple variable, then its value will be zero or false if it is undefined; a zero value evaluates to false and a non-zero value is true. The if construct can be nested multiple levels. A warning message will be printed if improper nesting is detected. The if(expression), elseif(expression), else, and endif are the only text parsed on a line. Text that follows these on the same line is ignored. For example: {if(a > 10 && b < 10)} This will be ignored no matter what 1 The

Ifdef(expression) and Ifndef(expression) construct is deprecated. if(!expression) instead.

22

Please use if(expression) and

... Lines processed if a > 10 and b < 10. {endif}

6.2.4

Switch Statements

The switch statement is a control construct which allows the value of a variable or expression to change the control flow via a multiway branch. The construct is begun with a switch(expression) statement followed by one or more case(expression) statements and an optional default statement. The construct is ended with an endswitch statement. The expression in the switch(expression) statement is evaluated and compared to each case(expression) statement in order. If the values of the two expressions are equal, then the code following that case(expression) is evaluated up to the next case() or default statement. If the expressions in more than one case() match the initial switch() expression, only the first one will be activated. If none of the case() expressions match the switch() expression, then the code following the default command will be evaluated. An example of the syntax is: {a = 10*PI} {switch(10*PI + sin(0))} ... This is ignored since it is after the switch, but before any case() statements {case(1)} ... This is not executed since 1 is not equal to 10*PI+sin(0) {case(a)} ... This is executed since a matches the value of 10*PI+sin(0) {case(10*PI+sin(0))} ... This is not executed since a previous case was executed. {default} ... This is not executed since a previous case was executed. {endswitch} ... This is executed since the switch construct is finished.

Switch constructs cannot be nested, but a switch() can be used inside an if() construct and an if() can be used inside a case() construct. The switch(expression), case(expression), default, and endswitch are the only text parsed on a line. Text that follows these on the same line is ignored.

6.2.5

Loops

Repeated processing of a group of lines can be controlled with the loop(control), and endloop commands. The syntax is: {loop(variable)} ... Process these lines variable times {endloop}

Loops can be nested. A numerical variable or constant must be specified as the loop control specifier. You cannot use an algebraic expression such as {loop(3+5)}.

23

6.2.6

ECHO

The printing of lines to the output file can be controlled through the use of the ECHO(OFF) and ECHO(ON) commands. The syntax is: {ECHO(OFF)} ... These lines will be processed, but not printed to output {ECHO(ON)} ... These lines will be both processed and printed to output.

ECHO will automatically be turned on at the end of an included file. The commands ECHO and NOECHO are synonyms for ECHO(ON) and ECHO(OFF).

6.2.7

VERBATIM

The printing of all lines to the output file without processing can be controlled through the use of the VERBATIM(ON) and VERBATIM(OFF) commands. The syntax is: {VERBATIM(ON)} ... These lines will be printed to output, but not processed {VERBATIM(OFF)} ... These lines will be printed to output and processed

NOTE: there is a major difference between the ECHO/NOECHO commands, the Ifdef/Endif commands, and the VERBATIM(ON|OFF) commands: • ECHO(ON|OFF) Lines processed, but not printed if ECHO(OFF) • Ifdef/Endif Lines not processed or printed if in Ifndef block • VERBATIM(ON|OFF) Lines not processed, but are printed.

6.2.8

IMMUTABLE

Variables can either be created as mutable or immutable. By default, all variables created during a run of aprepro are mutable unless the --immutable or -X command line option is used to execute Aprepro. An IMMUTABLE block can also be used to change Aprepro such that all variables are created as immutable. The syntax is: {IMMUTABLE(ON)} ... All variables created will be immutable {IMMUTABLE(OFF)} ... The mutable/immutable state changes back to the default which is typically mutable unless Aprepro executed with the --immutable or -X options.

Note that any variables created as immutable are still immutable following the IMMUTABLE(OFF) command.

24

6.2.9

Output File Specification

The output function can be used to change the file to which Aprepro is outputting the processed data. The syntax is: {output("filename")}, where filename is the name of the new output file. A string variable can be used as the function argument. The previous output file is closed. An error message is written and the code terminates if the file cannot be opened. If output("stdout") is specified, then the current output file is closed and output is again written to the standard output which is where output is written by default.

25

7 Units Conversion System 7.1

Introduction

The units conversion system as implemented in Aprepro defines several variables that are abbreviations for unit quantities. For example, if the output format for the current unit system was inches, the variable foot would have the value 12. Therefore, an expression such as 8*foot would be equal to 96 which is the number of inches in 8 feet1 . Seven consistent units systems have been defined including four metric based systems: si, cgs, cgs-ev, and shock; and three english-based systems: in-lbf-s, ft-lbf-s, and ft-lbm-s. The output units for these unit systems are shown in Table 8 (metric) and Table 9 (english). A list of the defined units abbreviations is given in Table 10. In addition to the definition of the conversion factors, several string variables are also defined which describe the output format of the current units system. For example, the string variable dout defines the output format for density units. For the in-lbf-sec units system, dout = "lbf-sec^2/in^4" which is the output format for densities in this system. The string variables can be used to document the Aprepro output. The string variable names are listed in the last column of Table 8 and Table 9. Table 7.1: Units Systems and Corresponding Output Format–Metric Quantity Length Mass Time Temperature Velocity Acceleration Force Volume Density Energy Power Pressure

si metre kilogram second kelvin metre/sec metre/sec2 newton metre3 kg/m3 joule watt pascal

cgs centimetre gram second kelvin cm/sec cm/sec2 dyne cm3 g/cc erg erg/sec dyne/cm2

cgs-ev centimetre gram second eV cm/sec cm/sec2 dyne cm3 g/cc erg erg/sec dyne/cm2

shock centimetre gram micro-sec kelvin cm/usec cm/usec2 g-cm/usec2 cm3 g/cc g-cm2 /usec3 g-cm2 /usec4 Mbar

string lout mout tout Tout vout aout fout Vout dout eout Pout pout

Table 7.2: Units Systems and Corresponding Output Format–English Quantity Length Mass Time Temperature Velocity Acceleration Force Volume 1 This

in-lbf-s inch lbf-sec2 /in second rankine inch/sec inch/sec2 pound-force inch3

ft-lbf-s foot slug second rankine foot/sec foot/sec2 pound-force foot3

ft-lbm-s foot pound-mass second rankine foot/sec foot/sec2 poundal foot3

string lout mout tout Tout vout aout fout Vout

can also be written as 8˜foot since ˜ has been defined to be the same as ∗ (multiplication).

26

Density Energy Power Pressure

lbf-sec2 /in4 inch-lbf inch-lbf/sec lbf/in2

slug/ft3 foot-lbf foot-lbf/sec lbf/ft2

lbm/ft3 ft-poundal ft-poundal/sec poundal/ft2

dout eout Pout pout

The units definitions are accessed through the Units function in Aprepro: {Units("unit system")}

where unit system is one of the strings listed in the first row of the previous two tables.

7.2

Defined Units Variables

In the following table, the first column lists the variables that are defined in the Aprepro unit system and the second column is a short description of the unit. All units variables are defined in terms of the five SI Base Units metre (length), second (time), kilogram (mass), temperature (kelvin), and radian (angle)2 . The bolded rows delineate the type of unit variable and the base quantities used to define it where L is length, T is time, M is mass, and t is temperature. For example density is defined in terms of M/L3 which is mass/ length3 . Table 7.3: Defined Units Variables Length [L] m, meter, metre Metre (base unit) cm, centimeter, centimetre Metre / 100 Metre / 1,000 mm, millimeter, millimetre um, micrometer, micrometre Metre / 1,000,000 km, kilometer, kilometre Metre * 1,000 in, inch Inch ft, foot Foot yd, yard Yard mi, mile Mile mil Mil (inch/1000)

second, sec usec, microsecond msec, millisecond minute hr, hour day yr, year decade century

Time [T] Second (base unit) Second / 1,000,000 Second / 1,000 Minute Hour Day Year = 365.25 days 10 Years 100 Years Velocity [L/T]

2 The radian is actually a SI Supplementary Unit since it has not been decided whether it is a Base Unit or a Derived Unit. There are three other SI Base Units, the candela, ampere, and mole, but they are not yet used in the Aprepro units system.

27

mph kph mps kps fps ips

ga

kg g, gram lbm slug lbfs2pin

Miles per hour Kilometres per hour Metre per second Kilometre per second Foot per second Inch per second Acceleration [L/T 2 ] Gravitational acceleration Mass [M ] Kilogram (base unit) Gram Pound (mass) Slug Lbf-sec2 /in

gpcc kgpm3 lbfs2pin4 lbmpin3 lbmpft3 slugpft3

Density [M/L3 ] Gram / cm3 Kilogram / m3 Lbf-sec2 / in4 Lbm / in Lbm / ft3 Slug / ft3

N, newton dyne gf kgf lbf kip pdl, poundal ounce

Force [M L/T 2 ] Newton = 1 kg-m/sec2 Dyne = newton/10,000 Gram (force) Kilogram (force) Pound (force) Kilopound (force) Poundal Ounce = lbf / 16

J, joule ftlbf erg calorie Btu therm tonTNT kwh

Energy [M L2 /T 2 ] Joule = 1 newton-metre Foot-lbf Erg = 1e-7 joule International Table Calorie International Table Btu EEC therm Energy in 1 ton TNT Kilowatt hour

W, watt Hp

Power [M L2 /T 3 ] Watt = 1 joule / second Elec. Horsepower (746 W)

28

degK, kelvin degC degF degR, rankine eV

Pa, pascal MPa GPa bar kbar Mbar atm torr mHg mmHg inHg inH2O ftH2O psi ksi psf

liter gal, gallon

rad rev deg, degree arcmin arcsec grade

Temperature [t] Kelvin (Base Unit) Degree Celsius Degree Fahrenheit Degree Rankine Electron Volt Pressure [M/L/T 2 ] Pascal = 1 newton / metre2 Megapascal Gigapascal Bar Kilobar Megabar Standard atmosphere Torr = 1 mmHg Metre of mercury Millimetre of mercury Inch of mercury Inch of water Foot of water Pound per square inch Kilo-pound per square inch Pound per square foot Volume [L3 ] Metre3 / 1000 Gallon (U.S.) Angular Radian (base unit) Full circle = 360 degree Degree Arc minute = 1/60 degree Arc second = 1/360 degree Grade = 0.9 degree

The conversion expressions were obtained from References [2], [3], [4], and [5].

7.3

Usage

The following example illustrates the basic usage of the Aprepro units conversion utility. $ Aprepro Units Utility Example $ {ECHO(OFF)} ...Turn off echoing of the conversion factors $ {Units(‘‘shock’’)} ...Select the shock units system $ NOTE: Dimensions - {lout}, {mout}, {dout}, {pout} ...This will document what quantities are used in the file after it is run through Aprepro {len1 = 10.0 * inch} ...Define a length in an english unit (inches)

29

$ {len2 = 12.0~inch} ...~ is a synonym for * (multiplication) Material 1, Elastic Plastic, {1890~kgpm3} $ {dout} Youngs Modulus = {28.3e6~psi} $ pout Yield Stress = {30~ksi} Initial Veclocity = {10~mph} $ vout ...Define the density and material parameters in whatever units they are available End Point 100 {0.0} {0.0} Point 110 {len1} {0.0} Point 120 {len1} {len2} Point 130 {0.0} {len1}

The output from this example input file is: $ Aprepro Units Utility Example $ NOTE: Dimensions - cm, gram, $ 25.4 $ 30.48

g/cc,

Mbar

...The documentation of what quantities this file uses

Material 1, Elastic Plastic, 1.89 $ g/cc Youngs Modulus = 1.951216314 $ Mbar Yield Stress = 0.002068427188 ...All material parameters are now in consistent units Initial Velocity = 0.00044704 $ cm/usec End Point Point Point Point

100 110 120 130

0 0 25.4 0 25.4 30.48 0 25.4 ...Lengths have all been converted to centimetres

The same input file can be used to output in SI units simply by changing Units command from shock to si. The output in SI units is: $ Aprepro Units Utility Example $ NOTE: Dimensions - meter, kilogram, kg/m^3, ...Quantities are now output in standard SI units $ 0.254 $ 0.3048

Pa

Material 1, Elastic Plastic, 1890 $ kg/m^3 Youngs Modulus = 1.951216314e+11 $ Pa Yield Stress = 206842718.8 Initial Velocity = 4.4704 $ meter/sec End Point Point Point Point

7.4

100 110 120 130

0 0 0.254 0 0.254 0.3048 0 0.254 ...Lengths have all been converted to metres

Additional Comments

A few additional comments and warnings on the use of the units system are detailed below. 30

Omitting the {ECHO(OFF)} line prior to the {Units(“unit system”)} function will print out the contents of the units header and conversion files. Each line in the output will be preceded by the current comment character which is $ by default. The comment character can be changed by invoking Aprepro with the -c option. For example aprepro -c# input file output file will change the comment character at the beginning of the lines to #. The temperature conversions are only valid for relative temperatures, for example, 100˜degC is equal to 180˜degF, not 212˜degF. Since several variables are defined in the units system, it is possible to redefine one of the variable names in your input file. If the Aprepro warning messages are turned off, you will not be notified of the variable redefinition and erroneous results may occur. Therefore, you should not turn off Aprepro warning messages while using the units system, and you should investigate all redefined variable messages to ensure that you are getting the results you expect.

31

8 Error, Warning, and Informational Messages Several error, warning, and informational messages will be printed by Aprepro if certain conditions are encountered during the parsing of an input file. The messages are of the form: Aprepro:

Type:

Message

(file,

line

line#)

Where Type is ERROR for an error message, WARN for a warning message, or INFO for an informational message; Message is an explanation of the problem, file is the filename being processed at the time of the message, and line# is the number of the line within that file. Error messages are always output, Warning messages are output by default and can be turned off by using the -W or --warning command option, and Informational messages are turned off by default and can be turned on by using the -M or --message command option. (See Chapter refch:execution.)

8.1

Error Messages

Aprepro: ERROR: parse error (file, line line#) An unrecognized or ill-formed expression has been entered. Parsing of the file continues following this expression. Aprepro: ERROR: Can’t open ’file’: No such file or directory The file specified in the include command cannot be found or does not exist. Aprepro will terminate processing following this error message. Aprepro: ERROR: Can’t open ’file’: Permission denied The file specified in the include or output command could not be opened due to insufficient permission. Aprepro will terminate processing following this error message. Aprepro: ERROR: Improperly Nested ifdef/ifndef statements (file, line line#) An invalid ifdef/ifndef block has been detected. Typically this is caused by an extra endif or else statement. Aprepro: ERROR: Zero divisor (file, line line#) An expression tried to divide by zero. The expression is given the value of the dividend and parsing continues.

Aprepro: ERROR: Invalid units system type. Valid types are: ’si’, ’cgs’, ’cgs-ev’, ’shock’, ’swap’, ’ft-lbfThe units system specified in the command could not be found. This is most likely due to a misspelling of the units system name. Aprepro: ERROR: function (file, line line#) DOMAIN error: Argument out of domain The arithmetic function function has been passed an invalid argument. For example, the above error would be printed for each of the expressions: {sqrt(-1.0)}

{log(0.0)}

{asin(1.1)}

since the arguments are out of the valid domain for the function. The value returned by the function following an error is system-dependent. See the function’s man page on your system for more information.

32

8.2

Warning Messages

Aprepro: WARN: Undefined variable ’variable’ (file, line line#) A variable is used in an expression before it has been defined. The variable is set equal to zero or the null string ("") and parsing continues. Aprepro: WARN: Variable ’variable’ redefined (file, line line#) A previously defined variable is being set equal to a new value. Aprepro: (IMMUTABLE) Variable ’variable’ is immutable and cannot be modified (file, line line#) The value of a variable that was created as an immutable variable was modified. No value will be returned by the expression. See page 10 and page 6.2.8 for a description of immutable variables.

8.3

Informational Messages

Aprepro: INFO: Included File: ’filename’ (file, line line#) The file filename is being included at line line# of file file. This message will also be printed during the execution of a loop block since temporary files are used to implement the looping function, and during the execution of the units conversion and material database access routines.

33

9 Examples 9.1

Mesh Generation Input File

The first example shown in this section is the point definition portion of an input file for a mesh generation code. First, the locations of the arc center points 1, 2, and 5 are specified. Then, the radius of each arc is defined ( {Rad1}, {Rad2}, and {Rad5}). Note that the lines are started with a dollar sign, which is a comment character to the mesh generation code. Following this, the locations of points 10, 20, 30, 40, and 50 are defined in algebraic terms. Then, the points for the inner wall are defined simply by subtracting the wall thickness from the radius values. Title Example for Aprepro $ Center Points Point 1 {x1 = 6.31952E+01} {y1 = 7.57774E+01} Point 2 {x2 = 0.00000E+00} {y2 = -3.55000E+01} Point 5 {x5 = 0.00000E+00} {y5 = 3.62966E+01} $ Wth = {Wth = 3.0} ... Wall thickness $ Rad5 = {Rad5 = 207.00} $ Rad2 = {Rad2 = 203.2236} $ Rad1 = {Rad1 = Rad2 - dist(x1,y1; x2,y2)} $ Angle between Points 2 and 1: {Th12 = atan2d((y1-y2),(x1-x2))} Point 10 0.00 {y5 - Rad5} Point 20 {x20 = x1+Rad1} {y5-sqrt(Rad5^2-x20^2)} Point 30 {x20} {y1} Point 40 {x1+Rad1*cosd(Th12)} {y1+Rad1*sind(Th12)} Point 50 0.00 {y2 + Rad2} $ Inner Wall (3 mm thick) $ {Rad5 -= Wth} $ {Rad2 -= Wth} $ {Rad1 -= Wth} ... Rad1, Rad2, and Rad5 are reduced by the wall thickness Point 110 0.00 {y5 - Rad5} Point 120 {x20 = x1+Rad1} {y5-sqrt(Rad5^2-x20^2)} Point 130 {x20} {y1} Point 140 {x1+Rad1*cosd(Th12)} {y1+Rad1*sind(Th12)} Point 150 0.00 {y2 + Rad2}

The output obtained from processing the above input file by Aprepro is shown below. Title Example for Aprepro $ Center Points Point 1 63.1952 75.7774 Point 2 0 -35.5 Point 5 0 36.2966 $ Rad5 = 207 $ Rad2 = 203.2236 $ Rad1 = 75.2537088 $ Angle between Points 2 and 1: Point 10 0.00 -170.7034 Point 20 138.4489088 -117.5893956 Point 30 138.4489088 75.7774

60.40745947

34

Point 40 100.3576382 141.214957 Point 50 0.00 167.7236 $ Inner Wall (3 mm thick) $ 204 $ 200.2236 $ 72.2537088 Point 110 0.00 -167.7034 Point 120 135.4489088 -116.2471416 Point 130 135.4489088 75.7774 Point 140 98.87615226 138.6062794 Point 150 0.00 164.7236

9.2

Macro Examples

Aprepro can also be used as a simple macro definition program. For example, a mesh input file may have many lines with the same number of intervals. If those lines are defined using a variable name for the number of intervals, then preprocessing the file with Aprepro will set all of the intervals to the same value, and simply changing one value will change them all. The following input file fragment illustrates this $ {intA = 11} {intB = int(intA / 2)} line 10 str 10 20 0 {intA} line 20 str 20 30 0 {intB} line 30 str 30 40 0 {intA} line 40 str 40 10 0 {intB}

Which when processed looks like: $

11

line line line line

9.3

5 10 20 30 40

str str str str

10 20 30 40

20 30 40 10

0 0 0 0

11 5 11 5

Command Line Variable Assignment

This example illustrates the use of assigning variables on the command line. While gener-ating a complicated 2D or 3D mesh, it is often necessary to reposition the mesh using GREPOS. If the following file called shift.grp is created: Offset Exit

X

{xshift}

Y

{yshift}

then, the mesh can be repositioned simply by typing: Aprepro xshift=100.0 yshift=-200.0 shift.grp Grepos input.mesh output.mesh temp.grp

35

temp.grp

9.4

Loop Example

This example illustrates the use of the loop construct to print a table of sines and cosines from 0 to 90 degrees in 5 degree increments. Input: $ Test looping - print sin, cos from 0 {angle = -5} {Loop(19)} {angle += 5} {sind(angle)} {cosd(angle)} {EndLoop}

to

90

by

5

Output: $ Test looping - print sin, -5 0 0 1 5 0.08715574275 0.9961946981 10 0.1736481777 0.984807753 15 0.2588190451 0.9659258263 20 0.3420201433 0.9396926208 25 0.4226182617 0.906307787 30 0.5 0.8660254038 35 0.5735764364 0.8191520443 40 0.6427876097 0.7660444431 45 0.7071067812 0.7071067812 50 0.7660444431 0.6427876097 55 0.8191520443 0.5735764364 60 0.8660254038 0.5 65 0.906307787 0.4226182617 70 0.9396926208 0.3420201433 75 0.9659258263 0.2588190451 80 0.984807753 0.1736481777 85 0.9961946981 0.08715574275 90 1 6.123233765e-17

9.5

cos

from

If Example

This example illustrates the if conditional construct. {diff = sqrt(3)*sqrt(3) - 3} $ Test if - else lines {if(sqrt(3)*sqrt(3) - 3 == diff)} complex if works {else} complex if does not work {endif} {if (sqrt(4) == 2)} {if (sqrt(9) == 3)} {if (sqrt(16) == 4)} square roots work {else}

36

0

to 90

by

5

sqrt(16) does not work {endif} {else} sqrt(9) does not work {endif} {else} sqrt(4) does not work {endif} {v1 = 1} {v2 = 2} {if (v1 == v2)} Bad if {if (v1 != v2)} should not see {else} should not see {endif} should not see {else} {if (v1 != v2)} good nested if {else} bad nested if {endif} good make sure it is {endif}

(1) (2) (3)

still good

The output of this is: -4.440892099e-16 $ Test if - else lines complex if works square roots work 1 2 good nested if good make sure it is still good

9.6

Aprepro Test File Example

The input below is from one of the aprepro test files. It illustrates looping, assignments, trigonometric functions, ifdefs, string processing, and many other Aprepro constructs. $ Test program for Aprepro $ Test number reprsentations {1} {10e-1} {10.e-1} {.1e+1} {.1e1} {1} {10E-1} {10.E-1} {.1E+1} {.1E1} Test assign statements: {_a = 5} {b=_a} $ Should print 5 5

37

{_a {_a {_a {_a {_a {_a

+=b} -=b} *=b} /=b} ^=b} = b}

{_a} $ Should print 10 10 {_a} $ Should print 5 5 {_a} $ Should print 25 25 {_a} $ Should print 5 5 {_a} $ Should print 3125 3125 {_a**=b} {_a} $ Should print 5 3125 3125

Test trigonometric functions (radians) {pi = d2r(180)} {atan2(0,-1)} {4*atan(1.0)} $ Three values of pi {_a = sin(pi/4)} {pi-4*asin(_a)} $ sin(pi/4) {_b = cos(pi/4)} {pi-4*acos(_b)} $ cos(pi/4) {_c = tan(pi/4)} {pi-4*atan(_c)} $ tan(pi/4) Test trigonometric functions (degrees) {r2d(pi)} {pid = atan2d(0,-1)} {4 * atand(1.0)} {ad = sind(180/4)} {180-4*asind(ad)} $ sin(180/4) {bd = cosd(180/4)} {180-4*acosd(bd)} $ cos(180/4) {cd = tand(180/4)} {180-4*atand(cd)} $ tan(180/4) Test max, min, sign, dim, abs {pmin = min(0.5, 1.0)} {nmin = min(-0.5, -1.0)} $ Should {pmax = max(0.5, 1.0)} {nmax = max(-0.5, -1.0)} $ Should {zero = 0} {sign(0.5, zero) + sign(0.5, -zero)} $ Should {nonzero = 1} {sign(0.5, nonzero) + sign(0.5, -nonzero)} {dim(5.5, 4.5)} {dim(4.5, 5.5)} $ Should be 1 0 $ Test ifdef lines {ifyes = 1} {ifno = 0} {Ifdef(ifyes)} This line should be echoed. (a) {Endif} This line should be echoed. (b) {Ifdef(ifno)} This line should not be echoed {Endif} This line should be echoed. (c) {Ifdef(ifundefined)} This line should not be echoed {Endif} This line should be echoed. (d) $ Test if - else lines {Ifdef(ifyes)} This line should be echoed. (1) {Else} This line should not be echoed (2) {Endif} {Ifdef(ifno)} This line should not be echoed. (3) {Else} This line should be echoed (4) {Endif} $ Test if - else lines {Ifndef(ifyes)}

38

be 0.5, -1 be 1.0, -0.5 be 0 1 $ Should be 1 0

This line should not be echoed. (5) {Else} This line should be echoed (6) {Endif} {Ifndef(ifno)} This line should be echoed. (7) {Else} This line should not be echoed (8) {Endif} $ Lines a, b, c, d, 1, 4, 6, 7 should be echoed $ Check line counting -- should be on line 74: {Parse Error} {ifdef(ifyes)} {This should be an error} {endif} $ Test int and [] (shortcut for int) {int(5.01)} {int(-5.01)} {[5.01]} {[-5.01]} $ Test looping - print sin, cos from 0 to 90 by 5 {_angle = -5} {Loop(19)} {_angle += 5} {_sa=sind(_angle)} {_ca=cosd(_angle)} {hypot(_sa, _ca)} {EndLoop} $$$$ Test formatting and string concatenation {_i = 0} {_SAVE = _FORMAT} {loop(20)} {IO(++_i)} Using the format {_FORMAT = "%." // tostring(_i) // "g"},PI = {PI} {endloop} Reset format to default: {_FORMAT = _SAVE} $$$$ Test string rescanning and executing {ECHO(OFF)} {Test = ’This is line 1: {a = atan2(0,-1)} This is line 2: {sin(a/4)} This is line 3: {cos(a/4)}’} {Test2 = ’This has an embedded string: {T = "This is a string"}’} {ECHO(ON)} Original String: {Test} Rescanned String: {rescan(Test)} Original String: {Test2} Print Value of variable T = {T} Rescanned String: {rescan(Test2)} Print Value of variable T = {T} Original String: {t1 = "atan2(0,-1)"} Executed String: {execute(t1)} string = {_string = " one two, three"} delimiter "{_delm = " ,"}" word count = {word_count(_string,_delm)}

39

second word = "{get_word(2,_string,_delm)}" string = {_string = " (one two, three * four - five"} delimiter "{_delm = " ,(*-"}" word count = {word_count(_string,_delm)} second word = "{get_word(2,_string,_delm)}"

string = {_string = " one two, three"} delimiter "{_delm = " ,"}" word count = { iwords = word_count(_string,_delm)} {_n = 0} {loop(iwords)} word {++_n} = "{get_word(_n,_string,_delm)}" {endloop} $ Check parsing of escaped braces... \{ int a = b + {PI/2} \} \{ \}

When processec by Aprepro, there will be two warning messages and one error message: Aprepro: WARN: Undefined variable ’Parse’ (test.inp_app, line 74) Aprepro: ERROR: syntax error (test.inp_app, line 74) Aprepro: WARN: Undefined variable ’T’ (test.inp_app, line 106)

The processed ouput from this example is: $ Aprepro (Revision: 2.28) Mon Jan 21 10:58:23 2013 $ Test program for Aprepro $ Test number reprsentations 1 1 1 1 1 1 1 1 1 1 Test assign statements: 5 5 $ Should print 5 5 10 10 $ Should print 10 10 5 5 $ Should print 5 5 25 25 $ Should print 25 25 5 5 $ Should print 5 5 3125 3125 $ Should print 3125 3125 5 3125 3125 $ Should print 5 3125 3125 Test trigonometric functions (radians) 3.141592654 3.141592654 3.141592654 $ Three values of pi 0.7071067812 4.440892099e-16 $ sin(pi/4) 0.7071067812 0 $ cos(pi/4) 1 0 $ tan(pi/4) Test trigonometric functions (degrees) 180 180 180 0.7071067812 2.842170943e-14 $ sin(180/4) 0.7071067812 0 $ cos(180/4) 1 0 $ tan(180/4)

40

Test max, min, sign, dim, abs 0.5 -1 $ Should be 0.5, -1 1 -0.5 $ Should be 1.0, -0.5 0 1 $ Should be 0 1 1 0 $ Should be 1 0 1 0 $ Should be 1 0 $ Test ifdef lines 1 0 This line should be This line should be This line should be This line should be

echoed. echoed. echoed. echoed.

(a) (b) (c) (d)

$ Test if - else lines This line should be echoed. (1) This line should be echoed (4) $ Test if - else lines This line should be echoed (6) This line should be echoed. (7) $ Lines a, b, c, d, 1, 4, 6, 7 should be echoed $ Check line counting -- should be on line 74: $ Test int and [] (shortcut for int) 5 -5 5 -5 $ Test looping - print sin, cos from 0 to 90 by 5 -5 0 0 1 1 5 0.08715574275 0.9961946981 1 10 0.1736481777 0.984807753 1 15 0.2588190451 0.9659258263 1 20 0.3420201433 0.9396926208 1 25 0.4226182617 0.906307787 1 30 0.5 0.8660254038 1 35 0.5735764364 0.8191520443 1 40 0.6427876097 0.7660444431 1 45 0.7071067812 0.7071067812 1 50 0.7660444431 0.6427876097 1 55 0.8191520443 0.5735764364 1 60 0.8660254038 0.5 1 65 0.906307787 0.4226182617 1 70 0.9396926208 0.3420201433 1 75 0.9659258263 0.2588190451 1 80 0.984807753 0.1736481777 1 85 0.9961946981 0.08715574275 1 90 1 6.123233996e-17 1 $$$$ Test formatting and string concatenation 0 %.10g 1 Using the format %.1g,PI = 3 2 Using the format %.2g,PI = 3.1

41

3 Using the format %.3g,PI = 3.14 4 Using the format %.4g,PI = 3.142 5 Using the format %.5g,PI = 3.1416 6 Using the format %.6g,PI = 3.14159 7 Using the format %.7g,PI = 3.141593 8 Using the format %.8g,PI = 3.1415927 9 Using the format %.9g,PI = 3.14159265 10 Using the format %.10g,PI = 3.141592654 11 Using the format %.11g,PI = 3.1415926536 12 Using the format %.12g,PI = 3.14159265359 13 Using the format %.13g,PI = 3.14159265359 14 Using the format %.14g,PI = 3.1415926535898 15 Using the format %.15g,PI = 3.14159265358979 16 Using the format %.16g,PI = 3.141592653589793 17 Using the format %.17g,PI = 3.1415926535897931 18 Using the format %.18g,PI = 3.14159265358979312 19 Using the format %.19g,PI = 3.141592653589793116 20 Using the format %.20g,PI = 3.141592653589793116 Reset format to default: %.10g $$$$ Test string rescanning and executing Original String: This is line 1: a = atan2(0,-1) This is line 2: sin(a/4) This is line 3: cos(a/4) Rescanned String: This is line 1: 3.141592654 This is line 2: 0.7071067812 This is line 3: 0.7071067812 Original String: This has an embedded string: T = "This is a string" Print Value of variable T = 0 Rescanned String: This has an embedded string: This is a string Print Value of variable T = This is a string Original String: atan2(0,-1) Executed String: 3.141592654 string = one two, three delimiter " ," word count = 3 second word = "two" string = (one two, three * four - five delimiter " ,(*-" word count = 5 second word = "two"

string = one two, three delimiter " ," word count = 3

42

0 word 1 = "one" word 2 = "two" word 3 = "three" $ Check parsing of escaped braces... { int a = b + 1.570796327 } { }

43

10 Aprepro Library Interface The previous chapters have described the standalone version of Aprepro. The functionality provided in the standalone version can also be provided to other programs through the Aprepro library C++ interface. The Aprepro library provides a SEAMS::Aprepro class which has three methods for parsing the input: 1. Read from stdin, echo data to stdout. At end of input, the parsed output is available in the Aprepro::parsing results() stream. 2. Read and parse a file. The entire file will be parsed with no output. After the file is parsed, the parsed output is available in the Aprepro::parsing results() stream. 3. Read and parse a string containing the Aprepro input. The results from parsing the string are returned in the Aprepro::parsing results() stream. Note that when using this method, you cannot use loops, if blocks, verbatim, and echo.

10.1

Adding basic Aprepro parsing to your application

The Aprepro capability is provided as a set of C++ classes. The main SEAMS::Aprepro class defined in the aprepro.h include file is the main interface used by external programs. The basic method for using the SEAMS::Aprepro class is: • create a SEAMS::Aprepro object • parse the data • retrieve the parsed data. An example of this is shown below: 1 2 3 4 5 6 7 8 9

#include i n t main ( i n t argc , char ∗ argv [ ] ) { SEAMS : : Aprepro a p r e p r o ; bool r e s u l t = a p r e p r o . p a r s e s t r e a m ( i n f i l e , argv [ argc − 1 ] ) ; if ( result ) { s t d : : c o u t info = "Return the successor to d"; ptr->syntax = "succ(d)";

Following this, the user can use the succ(d) command in the same way as any of the other Aprepro functions. This can be used to provide functions that access data internal to your program. The function will also appear in the DUMP FUNC() function list.

10.2.3

Modifying Aprepro Execution Settings

The standalone Aprepro can be executed with several command line options which change the behavior of Aprepro as defined in Chapter 2. Similar behavior modifications are available in the Aprepro library via the set option() command. The syntax is: void set option(const std::string &option);

Where option is one of: --debug --version --nowarning --copyright --message --immutable --trace --interactive --exit on --include=file or path --help

Dump all variables, debug loops/if/endif Print version number to stderr. Do not print warning messages. Print copyright message to stderr. Print INFO messages. All variables are immutable. Trace program execution. Primarily for aprepro developer. Interactive use; do not buffer output. End with Exit or EXIT or exit or Quit or QUIT or quit encountered in parsing stream. If a path is specified, then optionally prepend it to all included filenames; if a file is specified, the process the contents of the file before processing input files. Output the following text: 45

APREPRO PREPROCESSOR OPTIONS: --debug or -d: Dump all variables, debug loops/if/endif --version or -v: Print version number to stderr --immutable or -X: All variables are immutable--cannot be modified --interactive or -i: Interactive use, no buffering --include=P or -I=P: Include file or include path : If P is path, then optionally prepended to all include filenames : If P is file, then processed before processing input file --exit on or -e: End when ’Exit|EXIT|exit’ entered --help or -h: Print this list --message or -M: Print INFO messages --nowarning or -W: Do not print WARN messages --copyright or -C: Print copyright message Units Systems: si, cgs, cgs-ev, shock, swap, ft-lbf-s, ft-lbm-s, in-lbf-s Enter DUMP FUNC() for list of functions recognized by aprepro Enter DUMP PREVAR() for list of predefined variables in aprepro ->->-> Send email to [email protected] for aprepro support.

For additional functions that are rarely used, see the aprepro.h include file.

10.3

Aprepro Library Test/Example Program

A test program is provided with the Aprepro library which provides examples of the three parsing methods, defining variables, and defining functions. This is defined in the apr test.cc file in the Aprepro library distribution. The contents of this file are shown below: 1 2

#include #include

3 4

#include ” a p r e p r o . h”

5 6 7 8 9 10

// This f u n c t i o n i s used b e l o w i n t h e example sho wing how an // a p p l i c a t i o n can add i t s own f u n c t i o n s t o an a p r e p r o i n s t a n c e . double s u c c ( double i ) { return ++i ; }

11 12 13 14

i n t main ( i n t argc , char ∗ argv [ ] ) { bool r e a d f i l e = f a l s e ;

15 16

SEAMS : : Aprepro a p r e p r o ;

17 18 19 20 21 22

// EXAMPLE: Add a f u n c t i o n t o a p r e p r o . . . SEAMS : : symrec ∗ p t r = a p r e p r o . putsym ( ” s u c c ” , SEAMS : : Aprepro : : FUNCTION, 0 ) ; ptr−>v a l u e . f n c t p t r d = s u c c ; ptr−>i n f o = ” Return t h e s u c c e s s o r t o d” ; ptr−>s y n t a x = ” s u c c ( d ) ” ;

23 24 25 26

// EXAMPLE: Add a c o u p l e v a r i a b l e s . . . a p r e p r o . a d d v a r i a b l e ( ” Greg ” , ” I s t h e a u t h o r o f t h i s code ” , true ) ; aprepro . a d d v a r i a b l e ( ” BirthYear ” , 1 9 5 8 ) ;

46

// Make i t immutable

27

f o r ( i n t a i = 1 ; a i < a r g c ; ++a i ) { s t d : : s t r i n g a r g = argv [ a i ] ; i f ( a r g == ”− i ” ) { // Read from c i n and echo each l i n e t o c o u t A l l r e s u l t s w i l l // a l s o be s t o r e d i n Aprepro : : p a r s i n g r e s u l t s ( ) stream i f needed // a t end o f f i l e . a p r e p r o . a p o p t i o n s . i n t e r a c t i v e = true ; bool r e s u l t = a p r e p r o . p a r s e s t r e a m ( s t d : : c i n , ” s t a n d a r d i n p u t ” ) ; if ( result ) { s t d : : c o u t