Variables

User-Defined Variables

Aside from the global variables built into VSim (see Globals), you can also establish your own variables. They are defined through assignment, similar to many other programming languages. The syntax for defining a variable with an expression is:

$ VARIABLE = EXPRESSION

where VARIABLE is the name of your variable and EXPRESSION represents any valid expression. (See Expression Evaluation for more details.)

Note

Each line defining a variable must begin with a dollar sign ($).

VSim’s Python preprocessor will not try to substitute a variable on the left hand side of an equal sign (=). For example, the following code snippet:

$ charge = 1.6e-19
charge = charge

results in

charge = 1.6e-19

You can also use existing variables to define your variables. For example, you can use the length and number of cells along the x direction of your simulation in your definition of DX, as shown below:

$ DX = LX/NX

You still must place a dollar sign ($) in front of the variable you want to define.

Scoping and Evaluation

Variables in XSim are scoped. This means that the effect of a variable’s definition is confined to the macro or block in which that variable is defined. Whenever XSim enters a macro or a new input block, it enters a new scope.

In the case in which a variable is defined in multiple scopes, Vorpal ignores the previously-defined variable for the duration of the current scope. If the variable is defined more than once in the current scope, the new value overrides the previous value defined in the current scope.

A scope is closed once XSim leaves the block or macro. That is, the variable’s definition no longer has an effect once XSim has used the variable’s value in the macro or block where it is defined and then proceeded to a different block or macro. Scoping allows the next block to be free to redefine the value of the variable for its own purposes.

Mathematical Expressions

You can put mathematical expressions directly in an input file’s blocks by encapsulating them between dollar signs ($ math $). When you validate an input file, the expressions within the dollar signs are evaluated.

For example, in the esPtclInCell.pre file, there exists a variable that is defined as:

$ NX1 = NX + 1

and it appears in a vector describing the upper bounds of the simulation, [NX1 0 0]. However, you can also just use a mathematical expression directly in the bound definition, so you’d have:

[$NX + 1$ 0 0]

instead of the separate lines defining the variable and the upper bound.

Expression Evaluation

XSim evaluates expressions by interpreting them as Python expressions, which are composed of tokens. A token is a single element of an expression, such as a constant, identifier, or operation. The preprocessor breaks the expression into individual tokens, then performs recursive substitution on each token. Once a token is no longer substitutable, the preprocessor tries to evaluate it as a Python expression. The result of this evaluation will then be used as the value of this token. All the token values are subsequently concatenated and again evaluated as a Python expression. This result will then be assigned to the symbol.

Tokenizing, the act of breaking a string into tokens, is performed according to the lexical rules of Python. This means that white spaces are used to delimit tokens, but are otherwise entirely ignored.

Note

A string within matching quotes is treated as a single token with the matching quotes removed.

The processed input files generated by XSim are sensitive to white spaces; as a result, XSim has to re-introduce white spaces in the translation process. By default, tokens are joined without any white spaces. However, if both tokens are of type string, then a white space is introduced. Also, tokens inside an array (delineated by [ ]) are delimited by a white space.

See the Python documentation on the official Python website (http://www.python.org) for more information about Python expression.

Parameters

Parameters can be integers, floating-point numbers, or text strings. The format of the parameter value determines the type of parameter. For example:

• x = 10 indicates an integer

• x = 10.0 indicates a floating-point integer

• x = ten indicates a text string

Some parameters accept any text string (within reason). Other parameters accept only a choice of text strings.

Use a decimal point to specify a floating point number. You must write floating-point numbers with a decimal point so that they will not be interpreted as integers. If you want to assign a floating-point value to an integer parameter, make sure you write it as 3. (with a decimal point) rather than only the numeral 3 (without a decimal point). If you write the number as an integer, XSim will interpret it as such. This will likely produce unexpected results.

If XSim can parse a value, such as 42, as an integer, it will do so. If XSim cannot parse the value as an integer, it will attempt to parse it as a floating-point number. If XSim cannot parse the value as either an integer or floating-point number, it will parse it as a string of text.

Check that you have correctly defined parameter values. If you incorrectly define a parameter that has a default value, the default value will be used and potentially produce unsatisfactory results. If you incorrectly define a parameter that does not have a default value, the computational engine may crash, fail to compute the physics of the simulation, or ignore the incorrectly defined parameter and give you unsatisfactory results.

Do not specify a parameter twice. If you do, the second occurrence of the parameter in the processed .in file (produced from the .pre file) will be used. Although parameters and input blocks can be defined in many different sequences, if you follow the recommendations in this guide, you should not have a problem with specifying parameters twice.

Vectors of Parameters

Vectors of parameters are enclosed by brackets [ ] with white space used as separators. For example:

• x = [10 10 10] indicates a vector of integers

• x = [10. 10. 10] indicates a vector of floats