samuel(1)

Expressions

An expr can be any of the following:

integer

Any sequence of decimal digits; thus, always non-negative. They can be as big as you want.

\literal

An identifier preceded by a backslash represents a literal. In some cases, the backslash can be omitted; see the discussion below.

?variable

Read the value of a variable. In some cases, the question mark can be omitted, see below. If no such variable exists, an error is returned.

^variable

The current value of variable is returned, and then the variable is destroyed. If there was no variable with this name, an error is returned.

identifier

Return the value of the identifier. There is some magic involved here. In "normal" mode, the identifier is assumed to be a variable if there is one with this name, and a literal otherwise; moreover, subscripted identifiers will be handed to the induce(1) program, unless the option -i has been chosen. In "explicit-variables" mode, a naked identifier will always be interpreted as a literal.

tensorid!number

Defines a tensor of order one with one coordinate (this will work only if you have enabled tensors via the -t option; otherwise, you'll get type conflict errors very quickly). You can add and multiply these basic blocks to obtain tensors of any order. The tensorid can be any identifier (even bracketed or subscripted) and the number must be a small non-negative integer representing the coordinate number.

lvalue = expr

The value of expr is stored into the lvalue and returned; as in C, assignments are a special case of expressions. The lvalue can be a variable (if no such variable existed, it is created, otherwise the previous value is overwritten), but also a file or a pipe, with similar semantics:

“filename” and “|command”

Any sequence of characters between double quotes. It is assumed to be a pipe if the first character is a `|', and a file otherwise. If they appear in the right-hand side of an expression, the file (or the output of the command) is read and parsed, and some value is returned. If they appear as the left-hand side of an assignment, the value of the right-hand side will be copied into the file or the pipe.

function(expr, expr...)

A function can be any C identifier; the arguments are evaluated, and are passed as command-line arguments to the external program called `fn_function' (it must be in your path). The output of the program is then read and parsed, and some value is returned. For instance, `foo(-n,x+1)' is equivalent to

    "|fn_foo '-n' '+1+x'"

in an expression. The program fn_foo can be anything, but you should be extremely careful if it is a shell script; for instance, echo "$1" will not give `-n' (as you might expect) in this example.

expr bop expr

Where bop can be any of `+' (addition), `-' (substraction), `*' or `.' (multiplication), `/' (division), `&' (greatest common divisor). The result of the operation is returned.

uop expr

Where uop can be `+' or `-'.

(expr, subst, subst...)

Applies a list of substitutions to expr. Each substitution has the form `unary to expr', where unary is any expression which evaluates to a unary monomial, and to is either `->' for a simple substitution, or `>>' for a repeated substitution (we apply it until we reach a fixed point); for instance `x^2.y -> (x-z)*2' is a valid substitution. The list of substitutions can be empty, in this case you simply get the value of the parenthesised expression.

Another kind of substitution, which only applies to tensors, is `tensorid1 => tensorid2'; it maps the first tensorid to the second one, maybe causing a contraction. If the first tensorid doesn't appear in expr, an error is returned.

expr^number

Raises the expression to a non-negative power. Feature: 0^0 returns one.

expr:elit

Differentiates expr with respect to elit, where elit is any expression which evaluates to a literal.

~elit(expr,expr)

Returns the resultant of the two polynomials with respect to elit; this can be used to eliminate a literal between two equations.

| expr, expr... |

The number of expressions between the bars must be a perfect square. If there are n^2 of them, samuel will consider them as the elements of a n*n matrix, and will return the determinant of this matrix.

expr ~~ (expr,elit)

Computes the remainder of the first expression modulo the second one, with respect to some literal. For now, this construction is only syntactic sugar for modulo(E1,E2,L) so it will fail if fn_modulo is not in your path.

Precedence of Operators

All operators are left-associative, except the assignment which is right-associative. Here is the list of priorities, from the highest to the lowest:

(1)

power `^' and derivation `:';

(2)

unary plus and minus;

(3)

multiplication and division;

(4)

binary plus and minus;

(5)

greatest common divisor `&';

(6)

modulo `~~'

(7)

assignment `='.

Interpolation of subscripted identifiers

Samuel accepts three kinds of identifiers:

(1)

C identifiers, i.e., any sequence of letters, digits and underscores, the first character being a non-digit.

(2)

Subscripted C identifiers; as above, followed by a comma-separated list of integers between brackets, like `foo_bar[-1,3]'.

(3)

Bracketed identifiers, a la FORM: any sequence of characters between brackets; opening and closing brackets must match, like `[foo[bar]+2]'.

Without the -i and -e options, subscripted C identifiers are handed to the induce(1) program. They will be replaced ("interpolated") in the input stream by the appropriate pipe. For instance, the following substitution would take place:

    foo[-1,3] --> "|induce -q foo[-1,3]"

Note that it only affects "naked" identifiers, i.e. not preceded by a backslash or a question mark (nor in the LHS of an assignment); still, this behaviour can be undesirable; you can disable it with the -i option.

Interpolation is also disabled in "explicit-variables" mode, i.e., when the -e option is set. You don't want this kind of magic in batch mode, for obvious reliability reasons.

Variables and Literals

It is perfectly possible for a variable and a literal to have the same name, so there must be some way to distinguish them. You can prepend a \ or a ? before every identifier to remove ambiguity, but usually it's not needed; the naked identifier will be "correctly" interpreted. This interpretation depends on the mode samuel is running in:

(1)

Normal mode. If the identifier contains subscripts, it will be interpolated. Otherwise, if there's a variable with this name, its value will be returned. Otherwise, it's assumed to be a literal.

(2)

Normal mode without interpolation. This is what you get with the -i option. Like (1) but with interpolation disabled.

(3)

Explicit-variables mode. Activated by the -e option. A naked identifier will always represent a literal. This is the only way to ensure that samuel will run in a reliable and deterministic way with expressions containing arbitrary literals. Without this precaution, there might be name clashes between literals and temporary variables.