Parts

A part is what block or cylinder opens: a structured grid of one or more blocks of elements, described by three lists of node indices and three lists of coordinates. This chapter explains the six lists, how blocks are deleted to carve the topology, how partitions are inserted and element counts changed after the fact, and how a part ends.

The chapter assumes you have read the concepts chapter for reduced indices, regions and the three phases.

The six lists

block takes six lists. The first three are index lists, one for i, one for j and one for k. The last three are coordinate lists, one for x, one for y and one for z.

block i_index_list ; j_index_list ; k_index_list ;
      x_list [ ; ] y_list [ ; ] z_list [ ; ]

An index list says where the partition lines of a direction lie in node numbering. A coordinate list says where they lie in space. The two lists of a direction have the same length: one coordinate for each index entry.

The script tests/corpus/030-block-ends-open-part/input.tg, which make test runs, opens two parts. The second block closes the first part without an endpart, and that is the point of the case.

block 1 3; 1 3; 1 2; 0 1; 0 1; 0 1;
pb 2 2 1 2 2 1 x 5
block 1 2; 1 2; 1 2; 0 1; 0 1; 0 1;
endpart

Read the first line from left to right.

  • 1 3; is the i index list. It has two entries, so the part has two reduced indices in i. Node 1 and node 3 lie on partition lines, so the region between them holds two elements.
  • 1 3; is the j index list, read the same way. It holds two elements.
  • 1 2; is the k index list. It holds one element.
  • 0 1; is the x list. The partition line at reduced index 1 lies at x = 0 and the one at reduced index 2 lies at x = 1.
  • 0 1; and 0 1; are the y and z lists.

The first part is a unit cube of 2 x 2 x 1 elements and 3 x 3 x 2 nodes. The pb line on the second line moves the vertex at reduced index (2, 2, 1) to x = 5, and it belongs to this part. The second block then closes the part, as endpart would, and opens a second part of one element.

The rules of the lists are these.

  • Each index list starts at 1. A list that starts at another number is E0401.
  • Each entry exceeds the one before it (E0402).
  • A coordinate list has as many numbers as its index list (E0403).
  • The ; that ends an index list is required. The ; that ends a coordinate list may be left out. James then splits the run of numbers by the lengths of the index lists.
  • A reduced index is a position in a list, not a node number. The i list 1 3 has reduced indices 1 and 2.

A 0 in an index list marks a gap: the slab between the partitions on either side of it holds no element, so the part is not connected across it. A 0 in a coordinate list is only the number zero. A negative entry marks a shell partition, a layer of four-node shell elements on that partition’s plane. Both are built since version 0.6.0; the section on shells below says how, and a 0 that does not stand between two partitions is E0413. The script tests/corpus/117-block-gap/input.tg, which make test runs, has a gap between its two partitions in i:

block 1 0 3; 1 3; 1 2;
0 1 2; 0 1; 0 1;
endpart

The command pages for block and cylinder hold the syntax.

Cylinder parts

cylinder takes the same six lists, but its coordinate lists are radius, angle and height. The first direction runs out from the axis, the second runs around it and the third runs along it. The angle is in degrees.

All the work on a cylinder part is done in radius, angle and height. The vertices that pb, mb and mbi move move in those coordinates. When the part ends, James converts every node to Cartesian coordinates:

  • x = r cos(theta)
  • y = r sin(theta)
  • z = z

The merge phase and the output files see Cartesian coordinates only. The script examples/ring.tg, which make test runs, makes a whole turn:

c A ring about the z axis, r 1 to 2, a whole turn in eight intervals. The
c part's faces at 0 and at 360 degrees are one face in space, and stp merges
c them: 81 nodes become 72.
c
c   james ring.tg --format exodus -o ring.exo
cylinder 1 3;1 9;1 3;1 2;0 360;0 1;
endpart
merge
stp .0001
write

The part has 3 nodes along the radius, 9 around the turn and 3 up the height, 81 in all. The angles 0 and 360 give the same place in space, so stp merges the nine nodes at 360 degrees into the nine at 0. James writes 72 nodes and 32 elements.

Three rules follow from the conversion.

  • A negative radius is refused. A negative entry in the radius list stops the run with exit code 2. So does a node whose radius turns negative when the part ends, for example after an mb with a large negative offset in the first direction. Zero is legal, so a solid slice may touch its axis.
  • Angles interpolate as ordinary numbers. A part that runs from 350 to 10 degrees through 0 writes 350 370, not 350 10.
  • An angle past 360 degrees is neither wrapped nor refused. It passes through unchanged and converts periodically when the part ends, so 390 degrees lands where 30 does.

The script tests/golden/016-cylinder-angle-wrap/input.tg shows the last rule:

c A cylinder part whose j = 2 vertex at r = 1 is pushed by mb 300 degrees past
c its 90: the angle passes through unchanged and converts periodically at
c endpart, so the vertex lands at 30 degrees, below its neighbour at 90,
c and the one element folds (vertex-positioning.md, Decisions, M7).
cylinder 1 2;1 2;1 2;1 2;0 90;0 1;
mb 1 2 1 1 2 1 y 300
merge
neutral
write

The mb pushes the vertex at radius 1 and 90 degrees by 300 degrees, to 390. James writes it at (0.866, 0.5, 0), which is 30 degrees. It now lies before the vertex at 90 degrees and the element folds, so James warns. The warning is in tests/golden/016-cylinder-angle-wrap/input.diag.txt:

input.tg:5:1: warning: part #0 has 1 element with a negative Jacobian
james: 0 errors, 1 warning

Changing what the lists mean

Two commands change how the next part reads its lists. Both are session state: they apply to every later part, and neither is used up by the part that follows.

partmode

After partmode i the index lists hold element counts in place of node indices. Each entry is the number of elements in one region, so an index list has one entry fewer than its coordinate list. partmode s returns to node indices, which is the default. The script tests/corpus/164-partmode-i-element-counts/input.tg, which make test runs:

c partmode i reads element counts, which the IR shows as node indices.
partmode i
block 3 2;4;1 1;0 1 2;0 2;0 1 2;
endpart

The i list 3 2 is two regions of 3 and 2 elements. James converts it when it reads the block, and the IR shows the node indices [1 4 6] with the coordinates [0 1 2]. The j list 4 becomes [1 5] and the k list 1 1 becomes [1 2 3]. See partmode.

meshscal

meshscal n multiplies the element count of every region of every part by the whole number n. The coordinates do not change, so the shape stays and the elements get smaller. It comes before every part. After a part has ended it is E0409. The script tests/corpus/114-meshscal-scales-part/input.tg:

meshscal 2
block 1 2;1 2;1 2;0 1;0 1;0 1;
endpart

The part has one element in each direction as written. The IR shows each index list as [1 3]: two elements in each direction. See meshscal.

Carving a part: de and dei

A part is a box of elements. de deletes the elements inside a region of reduced indices, and dei deletes the elements of an index progression. The i in dei means the command takes a progression. It does not mean inverse.

Deleted elements carry no conditions, appear in no output and take no part in the merge. The nodes stay in the part, and James writes only the nodes that a remaining element uses. Pass --write-unref-nodes to write them all.

The script tests/golden/018-notched-plate/input.tg, which make test runs, cuts two notches from a square plate:

c A notched plate: a 3 by 3 grid of blocks, the top and bottom blocks of
c the middle column deleted by one progression with a union, and the
c outer faces of what remains projected onto a cylinder, so the square
c plate becomes a round one with two rectangular notches cut in from the
c rim.
sd 1 cyli 0 0 0 0 0 1 4
block 1 4 7 10;1 4 7 10;1 3;-3 -1 1 3;-3 -1 1 3;0 1;
dei 2 3;1 2 0 3 4;;
sfi -1 -4;;;sd 1
sfi ;-1 -4;;sd 1
endpart
merge
neutral
write

The block has four reduced indices in i and in j, so three regions in each. The plate runs from -3 to 3 in x and y.

In the progression 2 3;1 2 0 3 4;;, the 2 3 in i is the region between reduced indices 2 and 3, the middle column. In j, the 1 2 is the region between reduced indices 1 and 2, the 3 4 is the region between 3 and 4, and the 0 joins them into a union. The empty k list means the whole range. The progression expands to two regions, the bottom and top blocks of the middle column. James’s IR shows them as [2 1 1 3 2 2] and [2 3 1 3 4 2]. The command deletes them. The part that is left has seven blocks, 264 nodes and 126 elements. The two sfi commands then project the outer faces onto the cylinder, and the plate becomes round with two notches cut in from the rim.

Two rules about what de selects.

  • A region that holds no element is not an error. A face, an edge or a vertex holds no element. James warns that the de selects no element and names the region, and the part is unchanged.
  • A part whose every element is deleted is kept. James warns, and writes none of its nodes unless you pass --write-unref-nodes.

The warning for an empty part is in tests/corpus/147-part-all-deleted-warns/expected.diag.txt. A reduced index outside the part is E0404. See de and dei.

Changing the topology: insprt, mseq and lmseq

Three commands change a part after its block line. They work on the part’s lists at once and are not steps of the hierarchy, so every later command sees the new numbering.

insprt

insprt adds one partition to a direction, next to a reduced index. Its four arguments are a sign, a type from 1 to 6, a reduced index and the number of elements of the new region. The type picks the direction and the side: 1 and 2 are i left and right, 3 and 4 are j, 5 and 6 are k. A sign of -1 makes the new partition a shell partition, as a negative entry of a block list does; the shells and gaps section gives the rules.

The new partition adds a reduced index to the direction. Every command already given for the part has its regions renumbered, so each still names the partition it named before. A command given after the insprt reads the new numbering. The script tests/corpus/165-insprt-renumbers-later-pb/input.tg:

c The pb names reduced i 2; the insprt that follows renumbers it to i 3.
block 1 3 5;1 3;1 2;0 1 2;0 1;0 1;
pb 2 1 1 2 2 1 z 0.5
insprt 1 1 2 1
endpart

The pb names reduced index 2 in i. The insprt puts one new element to the left of reduced index 2, so the i list becomes [1 2 3 5] with the coordinates [0 0.5 1 2]. The IR shows the pb region as 3 1 1 3 2 1: the same vertices, now at reduced index 3. The renumbering reaches de and dei too.

An insertion that splits a region takes its elements from that region, so the count must be smaller than the region’s (E0405). See insprt.

mseq

mseq adds a signed whole number to the element count of every region of one direction. It takes the direction, then one number for each region. The script tests/corpus/166-mseq-doubles-j/input.tg:

c mseq j adds two elements to each j region, so 1 3 5 becomes 1 5 9.
block 1 3;1 3 5;1 2;0 1;0 1 2;0 1;
mseq j 2 2
endpart

The j list 1 3 5 has two regions of two elements. The 2 2 adds two to each, and the IR shows the j list as [1 5 9]. A count of values that is not the number of regions is E0406. See mseq.

lmseq

lmseq changes one region. It takes the direction, the reduced index on the left of the region and the signed change. The script tests/corpus/115-lmseq-folds-single-region/input.tg:

block
1 3 5 7;1 3;1 6 8 13;
1 3 5 7;1 3;1 3 5 7;
lmseq k 2 4
endpart

lmseq k 2 4 adds 4 elements to the k region that starts at reduced index 2. The k list 1 6 8 13 becomes [1 6 12 17]: the region’s right end and every entry after it grow by 4. A change that would leave a region with fewer than one element is E0407. See lmseq.

update is not supported in this version, and James refuses it with E0100; the section on the coordinate equations below says why. mseq and lmseq after a coordinate equation are accepted: the equation runs at step 20 over the part’s lists as they stand at the end, and TrueGrid’s own examples issue mseq after a z= (the TrueGrid Examples manual, pages 56 to 58).

Ending a part

A part ends in one of these ways. End of input is covered below.

  • endpart ends the part and returns to the Control phase. A cylinder part is converted to Cartesian coordinates now.
  • control does the same and names the phase. It is for a script that reads better that way. The script tests/corpus/167-control-then-second-part/input.tg ends one part with it, defines a surface in the Control phase and opens a second part.
  • A block or cylinder closes the open part as endpart would and opens another part, so the session stays in the Part phase. A merge closes it and enters the Merge phase. endpart is often unnecessary between parts.
  • abort throws the part away, with every command given for it, and returns to the Control phase.

Each of endpart, control and abort is legal in the Part phase only. In the Merge phase James refuses them with E0411, and there is no way back from the Merge phase except a new part.

The script tests/corpus/031-abort-discards-part/input.tg:

block 1 3; 1 3; 1 2; 0 1; 0 1; 0 1;
pb 2 2 1 2 2 1 x 5
abort
block 1 2; 1 2; 1 2; 0 1; 0 1; 0 1;
endpart

The first part and its pb are discarded, and the IR holds the second part alone. See endpart, control, abort and merge.

A part that is still open when end is read, or when the input ends, is closed as endpart would close it and kept. James warns so that a forgotten endpart shows. The script tests/corpus/133-part-open-at-end-of-input/input.tg:

block 1 2;1 2;1 2;0 1;0 1;0 1;
pb 1 1 1 1 1 1 x 2

James prints the warnings in tests/corpus/133-part-open-at-end-of-input/expected.diag.txt:

input.tg:2:18: warning [E0416]: part 1 was still open at end of input; closed as if by endpart
input.tg:1:1: warning: part #0 has 1 element with a negative Jacobian
james: 0 errors, 2 warnings

The first line is E0416. The second is about the pb, which moves a vertex to x = 2 and turns the element inside out. The part is kept.

Two things that can surprise you

A part whose lists fail still opens. James reports each bad list, then reads the later commands of the part against lists it has repaired, so one mistake in a block line gives one diagnostic and no cascade. The part adds nothing to the mesh.

A list with one entry makes one node in its direction and no elements. James meshes such a part, warns that it has no element, and writes none of its nodes unless you pass --write-unref-nodes.

Shells and gaps

A negative entry in an index list of block or cylinder, or an insprt with the sign -1, marks a shell partition. Its plane carries a layer of four-node shell elements, one per cell of the plane, and a solid element stands in a cell of the grid only when both partitions bounding the cell in every direction are positive. So block 1 -3 5;1 3;1 3; holds no solid at all, since every cell lies beside the shell partition at 3, and carries four shells on its plane; the spherical shell of the TrueGrid Examples manual, every list -1 5 -9, is six shell faces and nothing inside; and a list such as -1 2 5 -6, whose end partitions coincide with the next ones, puts a skin of shells on each end face of a solid, with its own nodes. de and dei remove the shells whose four corners lie in their region as they remove solids, and mt and mti give them material numbers.

A 0 in an index list marks a gap: the slab between the partitions on either side holds no element, so the part is not connected across it, and a shell partition’s plane has no element over the gap’s cells. A gap consumes one coordinate, which James ignores, and one reduced index, so a region or progression counts it as TrueGrid does. It must lie between two partitions (E0413), and mseq and lmseq are refused in a direction that holds a gap (E0419); on a list with shell partitions and no gap they change the magnitudes and keep the signs.

The four corners of a shell follow its plane’s index directions: on a k partition, (i, j), (i+1, j), (i+1, j+1), (i, j+1), whose right-hand rule gives the normal along +k when the part’s lattice is right-handed; on an i partition the corners cycle j then k, normal along +i; on a j partition k then i, normal along +j. The normal runs along the increasing index whatever the lattice’s hand. A part with one or three decreasing coordinate lists, or one placed by a reflecting cycorsy or tr (a negative scale factor, for instance), is a mirrored lattice, and James swaps the second and fourth corners of its shells so the normal stays on the side the index names, as it reorders the corners of a mirrored part’s solid elements: block 1 3;1 3;-1;2 0 0 2 0, the mirror image of block 1 3;1 3;-1;0 2 0 2 0, has every shell on the k partition facing +z as the original does. Two decreasing lists make a rotation and nothing is swapped. James decides the hand from the part’s own shells, by a vote over them, so one folded cell does not turn the others; a shell n turned toward or away from a point keeps that side, and orpt flip is still the inverse of the default. orpt and n turn the normal of a region’s shells toward or away from a point, or flip it, by swapping the second and fourth corners. thic gives the part’s shells a thickness, th and thi give a region’s shells one, four equal corner values, and ssf and ssfi place a region’s shell nodes on an intp surface and give each corner the thickness the two surfaces measure there. A shell no command gives a thickness is written with zero, and the write warns once with the count. Every node of a shell is a surface node under st and stp, so two shells merge edge to edge and a shell merges onto a solid’s face. The output chapter says how each format carries a shell.

The octant of the TrueGrid manual’s n entry, three shells on the unit sphere, is the script tests/corpus/222-shell-octant-p412/input.tg, which make test runs:

c the n entry's example, Vol. 1, p. 412: an octant of three shells on the unit sphere
block 1 -2;1 -2;1 -2;0 1 0 1 0 1
sd 1 sp 0 0 0 1
sfi 1 -2; 1 -2; 1 -2;sd 1
endpart

Each list’s second entry is a shell partition, so the one cell holds no solid and the three far faces of the cube carry one shell each, projected onto the sphere, their normals along +i, +j and +k, away from the origin.

The coordinate equations

After every projection, interpolation and smoother has acted, a part can be reshaped by algebra. The six equations x=, y=, z=, t1=, t2= and t3= each set one value at every node of a region: the node’s coordinate, or one of three temporaries t1, t2 and t3 that are kept per node for the equations’ own use and are zero when the part opens. The right side is an expression in the language of writing a script over the node’s own values x, y, z, t1, t2, t3, its full indices i, j, k, the part’s %maxrudi, %maxrudj, %maxrudk, %idxlist, %jdxlist and %kdxlist, and any parameter, array or function of the script. The script tests/corpus/261-swap-xy-p279/input.tg, which make test runs, exchanges two coordinates through a temporary:

c the swap of Vol. 1, p. 279: the x- and y-coordinates exchanged through t1
block 1 3 5;1 2;1 2;0 1 2 0 1 0 1
t1 = x
x = y
y = t1
endpart

Exchanging two coordinates mirrors the part, so every element comes out inverted: James writes the part with its corners reordered and says so in a note, part #0 is inverted; its 4 elements are written with their corners reordered.

The equations run at step 20 of the hierarchy, once, after the part’s last pass, in the order you wrote them, each over every node of its region before the next begins. dom names the region: each equation reads the last dom issued before it, and the whole part when none was. A node that no element uses, inside a deleted region or on a gap, is left alone. In a cylinder part the equations read and write the stored radius, angle in degrees and height, so x = x + 0.1*z widens the part with height and y = y + 10 turns it. The trigonometric functions take and give degrees. rand and norm draw from generators that every equation starts afresh, one stream for each seed, each started at its seed and continued across the equation’s calls and nodes, so the same script gives the same mesh in every run and every build. An equation with two seeds, such as z = z + 0.01*rand(7) + 0.01*norm(3,0,1), perturbs every node with two independent draws, one from each seed’s stream.

Three rules the pages of x= and dom spell out:

  • A division by zero or a function outside its domain gives NaN at that node and one warning for the equation (E1501). A NaN that reaches a coordinate stops the run (E1502); a temporary may hold one.
  • An array subscripted by the node, such as %height(i,j), is read at every node, and a subscript outside the array is E1503.
  • A function made with def can be called with constants but not with a value that changes from node to node (E1500); write its body into the equation instead.

update is the command TrueGrid pairs with the equations, and James does not build it. The manual’s own page says: “This command is almost never needed and interferes with the Command Hierarchy. Its usage is strongly discouraged and should only be used by experts. It was implemented to permit successive projections.” (the TrueGrid User’s Manual, volume 1, page 197). James refuses it with E0100. The one use the manual pairs it with, project the mesh and then apply equations to the result, needs no update here: the equations already run after every projection.

What James refuses in this version

  • update (E0100); the section on the coordinate equations quotes the manual’s own warning against it.

The compatibility chapter says why it waits.


James 0.8.0.

This site uses Just the Docs, a documentation theme for Jekyll.