algebra


argument

  The instruction to assign a register to a subroutine argument reads:

  Description                     Codes
  -----------                     -----

  R(j) -> Arg(k)                  i  8  j  k

  The first code (i) can have the values 0 and 1, 1 requests
  the originating register not to be changed on return from
  the call.

arithmetic

  Instruction list codes for arithmetical operations.

  Numerical binary arithmetic:

  Description                     Codes
  -----------                     -----

  R(i) + R(j) -> R(k)             i  1  j  k
  R(i) - R(j) -> R(k)             i  2  j  k
  R(i) * R(j) -> R(k)             i  3  j  k
  R(i) / R(j) -> R(k)             i  4  j  k
  R(i) ** R(j) -> R(k)            i  5  j  k

  Comparison of numbers resulting in a logical:

  Description                     Codes
  -----------                     -----

  R(i) equal to R(j) -> R(k)      i 10  j  k
  R(i) not equal to R(j) -> R(k)  i 11  j  k
  R(i) less R(j) -> R(k)          i 12  j  k
  R(i) less or equal R(j) -> R(k) i 13  j  k
  R(i) greater R(j) -> R(k)       i 14  j  k
  R(i) gr. or equal R(j) -> R(k)  i 15  j  k

  Logical binary arithmetic:

  Description                     Codes
  -----------                     -----

  R(i) and R(j) -> R(k)           i 16  j  k
  R(i) or R(j) -> R(k)            i 17  j  k

calls

  The instruction to call a procedure which has n arguments and
  has the identification code m, reads:

  Description                     Codes
  -----------                     -----

  Call procedure m with n args    m  9  n  0

  The procedures are listed under the help item CALL.

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.

goto

  The jump instruction reads:

  Description                     Codes
  -----------                     -----

  If R(i) Goto Ins(R(j))          i  7  j  0

  The first code (i) can of course be set to -1 in order to do the
  jump under all conditions or to 0 to jump never.

  A value out of range for R(j) (typically 0) generates a RETURN.
  No direct jump instruction code is provided at present. You are
  allowed to modify the value of R(j) during execution.

intrinsics

  Codes for the various intrinsic functions.

  Numerical functions:

  Description                    Codes            Name
  -----------                    -----            ----
  trailing R(i) -> R(j)          -11  6  i  j     TRAILING
  arctanh R(i) -> R(j)            -9  6  i  j     ARCTANH
  arccosh R(i) -> R(j)            -8  6  i  j     ARCCOSH
  arcsinh R(i) -> R(j)            -7  6  i  j     ARCSINH
  - R(i) -> R(j)                  -6  6  i  j     -
  square root R(i) -> R(j)        -5  6  i  j     SQRT
  arctan R(i) -> R(j)             -4  6  i  j     ARCTAN
  arccos R(i) -> R(j)             -3  6  i  j     ARCCOS
  arcsin R(i) -> R(j)             -2  6  i  j     ARCSIN
  log R(i) -> R(j)                -1  6  i  j     LOG
  exp R(i) -> R(j)                 1  6  i  j     EXP
  sin R(i) -> R(j)                 2  6  i  j     SIN
  cos R(i) -> R(j)                 3  6  i  j     COS
  tan R(i) -> R(j)                 4  6  i  j     TAN
  | R(i) | -> R(j)                 5  6  i  j     ABS
  + R(i) -> R(j)                   6  6  i  j     -
  sinh R(i) -> R(j)                7  6  i  j     SINH
  cosh R(i) -> R(j)                8  6  i  j     COSH
  tanh R(i) -> R(j)                9  6  i  j     TANH
  Entier R(i) -> R(j)             11  6  i  j     ENTIER
  Sum H_R(i) -> R(j)              13  6  i  j     SUM
  Product H_R(i) -> R(j)          14  6  i  j     PRODUCT
  Landau R(i) -> R(j)             18  6  i  j     LANDAU
  Minimum R(i) -> R(j)            19  6  i  j     MINIMUM
  Maximum R(i) -> R(j)            20  6  i  j     MAXIMUM

  Logical functions:

  Description                    Codes            Name
  -----------                    -----            ----
  not R(i) -> R(j)                10  6  i  j     NOT

  Type conversions:

  Description                    Codes            Name
  -----------                    -----            ----
  string R(i) -> number R(j)     -12  6  i  j     NUMBER
  num/log R(i) -> string R(j)     12  6  i  j     STRING
  number R(i) -> histogram R(j)   15  6  i  j     REFERENCE, HISTOGRAM
  name global R(i) -> string R(j) 16  6  i  j     GLOBAL
  type of R(i) -> string R(j)     17  6  i  j     TYPE

  Random numbers:

  Description                    Codes            Name
  -----------                    -----            ----
  Uniform random number -> R(j)   21  6  -  j     RND_UNIFORM
  Gaussian random number -> R(j)  22  6  -  j     RND_GAUSS, RND_NORMAL
  Exp. random number -> R(j)      23  6  i  j     RND_EXPONENTIAL, RND_EXP
  Poisson random number -> R(j)   24  6  i  j     RND_POISSON
  Landau random number -> R(j)    25  6  i  j     RND_LANDAU

  The random number generators RND_EXPONENTIAL and RND_POISSON
  have the mean of the distribution as argument. The argument
  of RND_POLYA is the "theta" parameter.

logicals

  The logical values for TRUE and FALSE are represented as
  1 and 0 respectively. ALGPRE makes any occurence of these
  point to the registers R(-5) and R(-4) respectively.

  In an expression where a logical is expected, values of
  0 and 1 (up to a precision of 1E-4) are acceptable.

matrices

  You can, during a Garfield run, create matrices, carry out simple
  operations on them, store them for later use etc.

  Matrices are usually created by calls to BOOK_MATRIX, but some
  instructions produce matrices also as part of their output.

  The usual arithmetic (+, -, *, /, **, functions) can be applied to
  matrices as if they were numbers. Mixed arithmetic between numbers
  and matrices is permitted and results in a matrix.

  Parts of matrices can be addressed as illustrated in the following
  examples. Keep in mind that the number of dimensions does not change,
  A[;1] is a 2-dimensional matrix ! Use RESHAPE_MATRIX if you wish to
  transform a 1xn-matrix to an n-matrix, or use the NUMBER function to
  change a 1x1x...x1-matrix to a number.

  1-dimensional matrix:
       A = (9 8 7)     A[1,2,3,1] = (9 8 7 9)

  2-dimensional matrix:
           ( 1 2 3 )             ( 3 2 )
       A = ( 2 4 6 )   A[3,2;] = ( 6 4 )     A[;1] = ( 1 2 3 )
           ( 3 6 9 )             ( 9 6 )

  Note 1: Addressing outside the array bounds is not permitted.
  Note 2: A 2x3-Matrix is not, as in Fortran, equivalent to a
          6-Matrix - one has to use both indices in a 2x3-Matrix
          and only a single index in a 6-Matrix.

mode

  The mode of a variable can either be:

  Description       mode
  -----------       ----
  Undefined            0
  String               1
  Number               2
  Logical              3
  Histogram            4
  Matrix               5

  ALGEXE and its auxiliary routines take care of mode
  propagation to the results.

results

  The instruction to assign a register to an output variable reads:

  Description                     Codes
  -----------                     -----

  R(i) -> output variable (j)     0  0  i  j

return

  To return to the calling procedure, to stop procedure execution,
  and to stop program execution, the following instructions can be
  used:

  Description                     Codes
  -----------                     -----

  Return to calling procedure     i -9  0  0
  Stop procedure execution        i -9  1  0
  Stop program execution          i -9  2  0

  These instructions are referred to as Return, Exit and Quit.
  The statement is executed if R(i) has the value 1, if R(i) is
  0, the statement is skipped, otherwise an error condition is
  raised.

storage

  All Histograms, Logicals, Matrices, Numbers and Strings whether
  they are constants, variables or intermediate results, are
  accessed through an array R. The value of Numbers and Logicals
  is stored directly in R, while for Histograms, Matrices and
  Strings a reference number is kept in R. Each element of R has
  a mode attached to it.

  All R's from R(0) downwards are assumed to be constants that are
  not affected by the execution of the instruction list. Although
  changing them is by itself not prevented, the "jump always" code
  will for instance not work if R(-1) is set to something else
  than the value 1. Similar trouble can arise from changing R(0),
  R(-2) and R(-3), respectively assumed to be 0, 2 and pi.

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.
  GOTOs, IFs etc are skipped. This instruction is therefore mainly
  useful for debugging infinite loops.

  Format:

  EXECUTE [from [to|LAST]]

  Example:

  EXEC

  (Execute the whole instruction list, skipping GOTO and IF.)

EXIT

  Leaves the editor.

  Format:

  EXIT

FUNCTION

  Translates the function provided in the argument into an instruction
  list. Quotes are not needed around the function, even if it contains
  blanks or commas 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.

  Format:

  MEMORY

OPTIONS

  The local options described below may as usual be mixed with
  the global options.

  Format:

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

  Examples:

  &SIGNAL
  (avalanche, time resolution and other settings)
  Global phi0=10*pi/180
  @
  opt ignore-underflow
  exit
  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 degrees. This would lead to many underflows
  in the calculation and the spread would be rejected as a
  result. This is why the IGNORE-UNDERFLOW option is used.

  OPTION NO-SYNTAX-CHECK DEBUG

  If you are confident you won't make typing errors ...

Additional Information on:

  • SYNTAX-CHECK
  • IGNORE-UNDERFLOW

  • 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 and unexecutable
      steps 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's etc are also
      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
    

    Keyword index. Formatted on 10/11/98.