x=
x= sets the x-coordinate of every node in the region named by dom to the value of an expression, evaluated at that node.
Syntax
x= expression
x = expression
expression: an expression in the language of writing a script, over the node’s own valuesx,y,z,t1,t2,t3, its full indicesi,j,k, the part’s%maxrudi,%maxrudj,%maxrudk,%idxlist,%jdxlistand%kdxlist, any parameter, array or function of the script, numbers, the operators and the functions. The blanks around the=are optional. The expression runs to the end of the line;&as the last character of a line continues it on the next, and;ends one equation and begins another on the same line.
The five other equations, y=, z=, t1=, t2= and t3=, read exactly as this one.
What it does
At every node of the region that an active element uses, James evaluates the expression with the node’s own values and stores the result as the node’s x-coordinate. x, y and z are the node’s stored coordinates after every projection and smoother has acted: for a cylinder part they are the radius, the angle in degrees and the height, not Cartesian values. t1, t2 and t3 are three values kept per node, zero when the part opens, that an equation may set and a later equation read. i, j and k are the node’s full indices, counted from 1. %idxlist(n) is the n-th entry of the part’s i-list as the script holds it (%jdxlist and %kdxlist likewise for j and k): the full index of a partition, 0 for a gap and negative for a shell partition, as in a %idxlist(n) written elsewhere in the part, and %maxrudi counts those entries. So i .eq. %idxlist(2) is true on the nodes of the second partition when the list’s second entry is a solid partition, and abs(%idxlist(n)) gives a shell partition’s full index. A node that no element uses, inside a deleted region or on a gap, is left alone.
The equations of a part run in the order you wrote them, each over every node of its region before the next begins, so t1 = x, x = y, y = t1 swaps the two coordinates. A parameter %name takes the value it has when the equation is read; an array whose subscripts depend on the node, such as %height(i,j), is carried into the equation whole, and reading outside it at some node is E1503. rand and norm draw from generators the equation starts afresh, one stream for each seed: a stream starts at its seed, and every call that names that seed continues it, across the equation’s calls and across its nodes in the order the nodes are visited. So the same script gives the same mesh in every build, and z = z + 0.01*rand(7) + 0.01*norm(3,0,1) perturbs every node with two independent draws, one from the stream of seed 7 and one from the stream of seed 3. A call without a seed draws from seed 0, as rand(0) does, and 0 and -0 are one seed. An equation keeps up to 16 streams at once, the most recently used first; a seventeenth seed in play drops the stream used least recently, which starts again at its seed if it is named again. A seed computed at the node, such as rand(i), starts a stream for each value it takes; it does not push out the equation’s few constant seeds so long as they keep being called, but once more than 16 of its own values are in play the oldest starts again when it returns, so on a part more than 16 nodes wide rand(i) gives each column the same draw on every row: give such an equation a constant seed instead. A seed that is NaN draws from a stream that starts afresh at every call, so it gives the same value each time.
When James applies it
Step 20 of the hierarchy, the last: after every projection, interpolation and smoother, once, after the part’s last pass, and before the shell properties are applied. The equations are legal only in the Part phase.
Rules James adds
- An equation issued before a dom reads the whole part; each equation reads the last
domissued before it. - A function made with def may be called with constants but not with a value that changes from node to node (E1500); write its body into the equation instead.
mseqandlmseqafter an equation are accepted, as the TrueGrid examples issue them, andinsprtafter an equation renumbers thedomregions as it renumbers every region.- A number written in an equation, such as the
3ofi .eq. 3or the14of(j-14)/3, names a node of the part’s final lattice, so anmseq,lmseqorinsprtwritten after the equation changes which node it names.%idxlist(n)is the n-th entry of the final list, so it follows its partition through anmseqorlmseq, though aninsprtthat adds an entry before the n-th makes it name another partition. [...]is for a command’s arguments, not for an equation:x = x + [%r*2]is E0221. Writex = x + %r*2.- A division by zero or a function outside its domain at some node gives NaN there and one warning for the equation (E1501); a NaN stored in a coordinate stops the run (E1502).
- In a
cylinderpartxis the radius, and a negative radius written by an equation stops the run with the engine’s errornode (i, j, k) of part #n has a negative radius r, at the part’s opening command and with exit code 2 (messages from the engine). - An expression of more than 2048 instructions, or one that needs more than 256 places on its stack, is refused (E1500); TrueGrid’s own limit is 240 items.
Diagnostics
- E0221: the expression does not parse; the message names the equation.
- E0412: an equation outside a part.
- E1500: the expression parses but cannot become a program.
- E1501: illegal operations at some nodes, counted.
- E1502: a coordinate that is not finite after the equation.
- E1503: an array read outside its bounds at a node.
Example
The script tests/corpus/260-x-translate-p279/input.tg, which make test runs:
c the first example of Vol. 1, p. 279: translate the part in the x-direction
block 1 2;1 2;1 2;0 1 0 1 0 1
x = x + 1.0 $ translate the part in the x-direction
endpart
Every node’s x-coordinate grows by 1: the part moves one unit along x. The comment after $ is stripped before the expression is read.