Garfield 
 Help 
 algebra 
 Search 
 Index 
 Full text 
 Contents 

algebra

variables

In Garfield input, one makes frequent use of variables. For instance, when you make a contour plot of the electrostatic potential, you type 
PLOT CONTOUR V

The "V" in this statement is a local variable of the PLOT-FIELD command which equals the electrostatic potential at a given point. The name and value of these variables is not under your control. Moreover, you usually only have access to them in the context of the command being executed.

Garfield also has variables which are entirely under your control: you choose their name and value, you determine when expressions are to be evaluated, and you decide when and how to display their values. These are called global variables, or Globals for short. The name has been chosen to reflect the broader scope of globals, as compared to the local variables mentioned above. Local variables have a scope limited to one command, while global variables can be used across sections.

Global variables can be used for a variety of things:

Additional information on:

 

operator

A single operator symbol in Garfield can have a meaning which depends on the type of its operands - i.e. the operators can be overloaded. For instance, the "+" operator adds numbers, acts as 'or' between logicals, and concatenates strings.

There are also operators for certain kinds of mixed arithmetic, such as between numbers and histograms and between numbers and matrices. Mixed arithmetic of logicals and numbers is not permitted.

Garfield recognises the following binary operators:

Operator Acts on Gives Effect
+ -N-HM same addition
+ --L-- --L-- or
+ S---- S---- commutative concatenation
- -N-HM same subtraction
- --L-- --L-- exclusive or
* -N-HM same multiplication
* --L-- --L-- and
/ -N-HM same division
/ S---- S---- concatenate strings
**, ^ -N-HM same exponentiation
& --L-- --L-- and
& -N--M ----M concatenate matrices
& S---- S---- concatenate strings
| --L-- --L-- or
= SN-HM --L-- equality
= --L-- --L-- equivalence
#, <>, >< SN-HM --L-- non-equality
#, <>, >< --L-- --L-- non-equivalence
> SN-HM --L-- greater than
>=, => SN-HM --L-- greater than or equal to
< SN-HM --L-- less than
<=, =< SN-HM --L-- less than or equal to

Unary operators are treated like functions, and therefore have higher precedence than binary operators. As a result, '-x^2' is always positive. The following unary operators are currently known:

Operator Acts on Gives Effect
+ -N-HM same assignment
- -N-HM same negative
^, ~ --L-- --L-- not

Notes:

  1. The operators act element by element on variables of type Histogram and Matrix.
  2. The sorting sequence for characters in Strings depends on the computer system that is used.
  3. Mixed operations between Number and Histograms or between Numbers and Matrices result in Histograms and Matrices respectively.
  4. All operators can be applied to type Undefined, the result being Undefined.
  5. The equality and non-equality operators have a tolerance of 10\<SUP\>-4\</SUP\> on all computers except Cray where a tolerance of 10\<SUP\>-8\</SUP\> is used.
  6. Fortran users should be aware that the double slash stands for a comment in-line comment for Garfield, not for the string concatenation operator. Strings are concatenated in Garfield with a single slash.

functions

Garfield currently recognises the following intrinsic functions:

Function Acts on Gives Effect
ABS -N-HM same absolute value
ARCCOS -N-HM same arc cosine
ARCCOSH -N-HM same arc hyperbolic cosine
ARCSIN -N-HM same arc sine
ARCSINH -N-HM same arc hyperbolic sine
ARCTAN -N-HM same arc tangent
ARCTANH -N-HM same arc hyperbolic tangent
COS -N-HM same cosine
COSH -N-HM same hyperbolic cosine
ENTIER -N-HM same integer part
EXIST S---- --L-- existence of a file
EXP -N-HM same exponential
GAMMA -N-HM same \&Gamma;-function
GLOBAL S---- any global with name of the string
LANDAU -N-HM same Landau density function
LOG -N-HM same logarithm
LOG_GAMMA -N-HM same logarithm of \&Gamma;-function
MAXIMUM ---HM -N--- maximum of matrix or histogram
MEAN ---HM -N--- mean of a matrix or histogram
MINIMUM ---HM -N--- minimum of matrix or histogram
NOT --L-- --L-- negation of logical value
NUMBER S---M -N--- conversion to a number
ONES -N--- ----M row of 1's
PRODUCT ---HM -N--- product of matrix or histogram
REFERENCE S--HM -N--- reference of a given string etc
REF_HISTOGRAM -N--- ---H- histogram with given reference
REF_MATRIX -N--- ----M matrix with given reference
REF_STRING -N--- S---- string with given reference
REVERSE ----M ----M reverse order in a matrix
RMS ---HM -N--- RMS of a matrix or histogram
ROW -N--- ----M row of number 1 to argument
SIN -N-HM same sine
SINH -N-HM same hyperbolic sine
SIZE ----M -N--- total number of elements
SQRT -N-HM same square root
STRING SNLHM S---- conversion to string
SUM ---HM -N--- sum of matrix or histogram
TAN -N-HM same tangent
TANH -N-HM same hyperbolic tangent
TRAILING -N-HM same complement of ENTIER
TYPE SNLHM S---- type of the argument
ZEROES -N--- ----M row of 0's

In addition, the following random number generators are known:

Function Argument Effect
RND_EXPONENTIAL mean Exponential distribution with given mean
RND_FUNCTION - Random number according to a function
RND_GAMMA mean \&Gamma;-distribution with given mean
RND_GAUSS - Normal distribution N(0,1)
RND_HISTOGRAM histogram Random number according to an histogram
RND_LANDAU - Landau distribution
RND_LAPLACE width Laplace distribution
RND_POISSON mean Poisson distribution with given mean
RND_POLYA \&theta; Polya distribution with given \&theta;
RND_UNIFORM scaling Uniform distribution

Notes:

  1. The functions act element by element on arguments of type Histogram and Matrix.
  2. All functions can be applied to type Undefined, the result being Undefined.
  3. Further random number generators are available as procedures: RND_MULTIPLICATION and RND_VAVILOV.
  4. Further functions and random number generators can be added on request.
  5. More elaborate operations are available as procedures Calls.

Additional information on:

instruction_list

When a formula is pre-processed, it is translated into a series of instructions which are placed at the end of the instruction list.

The instruction list usually contains many pieces, identified by entry_points which can be executed independently.

The instruction list consists, as the name says, of a list of instructions.

Each instruction is made up of 4 integers:

  1. either a function specification code or an index in the array R;
  2. code for the operation;
  3. an index in the array R;
  4. the index for the outcome, in R for intermediate results, in the result list for final results

Additional information on:

 

entry_points

The instruction list consists of several sub-lists that are executed independently. The information about a sub-list (the first and last instruction, first and last constant, number of variables expected, number of results returned and a few flags) are stored in an entry point list. This list is used by the interpreting routines.

Each time you ask a function to be translated, this will be done in a new entry point. Similarly, when you enter the editor, you are assigned an entry point to store your instructions in. The entry point description for en edited entry point is updated when leaving the editor.

You can not change the description of an entry point but you can delete entry points, add new ones and see the description of one.

ADD-ENTRY-POINT

Performs an update of the entry point you were playing with sofar and then creates a new entry point that will become the current entry point.

Format: 

ADD-ENTRY-POINT

CLEAR-ENTRY-POINT

Removes an entry point from the entry point list. The storage associated with it can from then on be recovered by a garbage collect, which is automatically performed by the translation routine but which can also be requested by the user.

Format: 

CL-ENTRY [entry_reference]

Examples: 

CL-ENTRY
CL-ENTRY 5

In the first example, the current entry point (the one you are editing) is dropped. You may continue to modify it etc. and it can also be executed as long as no garbage collect is done.

In the second example, the entry point with reference number 5 is dropped. The reference number can be obtained from the MEMORY command, details about an entry point are provided by the DISPLAY-ENTRY-POINT command.

DELETE

Deletes instructions from the instruction list.

Format: 

DELETE [from [to|LAST]]

Example: 

DEL
DEL 1 LAST

(Both examples delete all instructions.)

DISPLAY-ENTRY-POINT

Shows full details about an entry point, such as the number of variables expected, the range of the instructions and constants. The output also shows whether the list has been dropped (but not yet been reclaimed), whether the list is executable (note that a list that has been edited is always marked executable) and which interpreter should be used for the execution (sequential or with jumps).

Note that the description of an entry point that is being edited is not always entirely up to date.

Format: 

DISPLAY-ENTRY-POINT [entry_reference]

Example: 

DISP-ENTRY

Shows details about your current entry point.

EXECUTE

Executes one or more lines in the instruction list sequentially, ignoring goto statements. This instruction is therefore mainly useful for debugging infinite loops.

Format: 

EXECUTE [from [to|LAST]]

Example: 

EXEC

(Execute the whole instruction list, skipping branching statements.)

EXIT

Leaves the editor.

Format: 

EXIT

FUNCTION

Translates the function provided in the argument into an instruction list. No need for quotes around the function, even if it contains blanks or commata etc.

Format: 

FUNCTION function

Example: 

F ARCTAN (EX/EY)

GARBAGE-COLLECT

Reclaims the storage in the instruction and constants buffer that is associated with sub-lists that have been cleared. The entry point list is updated to reflect the cleanup. Once the instruction list underwent a garbage collect, cleared entry points can no longer be executed.

Format: 

GARBAGE-COLLECT

INSERT

Inserts lines in the instruction list before the line given as argument. The lines to be input must be in raw format (4 integers per line) and they are roughly checked on correct syntax.

Format: 

INSERT before

LIST

Lists (part of) the instruction list in raw format.

Format: 

LIST [from [to|LAST]]

Example: 

LIST 5

(Lists line 5 only.)

MEMORY

Displays the memory occupation: number of registers, constants and instructions that are in use. The list of entry points is also shown, for more details about one of them, use the DISPLAY-ENTRY-POINT instruction.

This command can be used both in the algebra editor, which is entered by typing @ instead of a formula, or as part of regular input, provided the command is prefixed by a @ symbol.

Formats: 

MEMORY
@ MEMORY

OPTIONS

The local options described below may as usual be mixed with the global options, see the top level OPTIONS command.

The algebra OPTIONS can be set via a single-line command as shown in the example, and also from within the algebra editor which is entered by typing @ instead of a formula.

Format: 

OPTIONS [NO-SYNTAX-CHECK | ALGEBRA-SYNTAX-CHECK | ...
         PROCEDURE-SYNTAX-CHECK] ...
        [SIGNAL-EXPONENTIAL-UNDERFLOW | IGNORE-EXPONENTIAL-UNDERFLOW]

Examples: 

&SIGNAL
// insert avalanche, time resolution and other settings
Global phi0=10*pi/180
@opt ignore-exponential-underflow
signal ion-tail cross-induced noelectron-pulse ...
   ion-angles 20 angular-spread exp(-((phi/{phi0})^2))

Avalanches are spread around the wire with a standard deviation of 10\&deg;. This would lead to many underflows in the calculation and the spread would be rejected as a result. This is why the IGNORE-EXPONENTIAL-UNDERFLOW option is used. 

OPTION NO-SYNTAX-CHECK DEBUG

If you are confident you won't make typing errors\&nbsp;...

Additional information on:

 

PRINT

Prints (part of) the instruction list in a legible format.

Format: 

PRINT [from [to|LAST]]

Example: 

PRINT 2 10

(Prints lines 2 through 10.)

REGISTER

Displays (one argument) or modifies (two arguments) the contents of an element of the memory/register array.

You have access to the entire storage area, constant elements included.

Format: 

REGISTER array_index value

Examples: 

REG 5 10
REG 5

(First assign the value 10 to R(5), then check the value.)

RESET

Clears the algebra buffers: all instructions, constants and entry points are removed. This instruction should be used with care since there might be sub-lists around that other instructions still need.

Format: 

RESET

RESULTS

Displays the number of results expected by the calling section.

Format: 

RESULTS

SIMPLIFY

Simplifies the present instruction list.

During the simplification, constants are evaluated, complementary operations are cancelled, assignments are propagated and removed, equal subexpressions are identified and stored, steps that are not executed are dropped from the instruction list.

Some of these simplifications are skipped if the instruction list contains (un)conditional jumps since the jump address can not a priori be assumed to be known.

Format: 

SIMPLIFY

TEST

Executes the entire instruction list associated with the current entry point. The arguments of this command are used as values of the variables. There should be precisely one argument per variable declared in the entry point description.

This instruction differs from EXECUTE in that goto is executed. Loops, jumps and if's therefore work as usual.

Format: 

TEST var1 var2 ...

Example: 

TEST 2 3 6 10

(Execute the instruction list after substituting 2 for R(1), 3 for R(2), 6 for R(3) and 10 for R(4).)

VARIABLES

Lists the names of the valid variables.

Format: 

VARIABLES
Go to the top level, to algebra, to the topic index, to the table of contents, or to the full text.

Formatted on 21/01/18 at 16:55.