Shaping a part
Once a part’s blocks exist, the script shapes them: vertices are moved, edges are attached to curves and their nodes spaced along them, vertices, edges and faces are projected onto surfaces, and the interior is interpolated. James applies these commands in a fixed order of steps, whatever order they have in the script, and the steps interleave the kinds of command: vertices are projected before edges are laid out, edges before faces, faces before the interior. The concepts chapter gives the steps. This chapter goes by the kind of command, in the order a script most often uses them: vertices, then edges and their spacing, then projection, then interpolation, then smoothing.
| Section | Steps it covers |
|---|---|
| Placing vertices | 1iii |
| Edges and their spacing | 2, 4 and 5 |
| Projecting onto surfaces | 3, 6 and 9 |
| Interpolating the interior | 7, 8, 10, 14, 15 and 16 |
| Smoothing | 11 to 13, 17 and 18 |
| Reshaping with the equations | 20 |
The steps run in numeric order within a pass, so a vertex is projected (step 3) before an edge is spaced (steps 4 and 5) and an edge is projected (step 6) before a face is interpolated (steps 7 and 8). Steps 1 to 3 run once. Steps 4 to 19 and 21 form a pass, and James repeats the pass when the part has not settled; step 20, the equations, runs once after the last pass. The section on interpolation says how.
A part keeps its shape in two layers. The vertices and the edge curves (except curf) are starting positions, and later steps may move what they set. A projection is different. It stays in force, and James projects a node again whenever a later step moves it.
Placing vertices
A block is a grid of nodes, and its vertices are the corner points that the block lists name. block and cylinder give every vertex a first position (step 1i). The vertex commands then move them (step 1iii). The nodes between the vertices follow later, by interpolation.
| Command | What it does to the vertices of its region |
|---|---|
| pb | sets the coordinates you name |
| mb | adds an offset to the coordinates you name |
| q | copies all three coordinates of one vertex onto another |
| tr | moves the vertices by a transformation built from operators |
| ilin | sets the interior vertices of a region from its boundary vertices |
pb and mb name the coordinates they touch with a component keyword: x, y, z, xy, xz, yz or xyz. You write one value for each letter, in the order of the letters. The coordinates that the keyword does not name keep their values. In a cylinder part the three coordinates are the radius, the angle in degrees and the height.
tr builds one transformation from a list of operators and applies it to every vertex of the region. There are thirteen operators. mx, my and mz translate along an axis, v translates by a vector, rx, ry and rz rotate about an axis through the origin, raxis rotates about an axis you give, inv inverts the transformation so far, csca scales all three coordinates and xsca, ysca and zsca scale one. The list ends in ;. In a cylinder part tr works in Cartesian coordinates and converts back.
mbi, tri and ilini are mb, tr and ilin with an index progression in place of the region. The i means the command takes a progression. It never means inverse. A vertex that several regions of one progression reach is changed once.
James applies the vertex commands in the order the script wrote them, each on top of what the earlier ones left. A later command on the same vertex wins. A later pb on a vertex that ilin set replaces the interpolated position, and a later ilin replaces what an earlier pb set in its interior.
The script tests/corpus/169-tr-rotates-face-about-z/input.tg, which make test runs, rotates a face:
c tr rotates the i = 1 face by 15 degrees about the z axis.
block 1 3 5;1 3 5;1 2;1 2 3;0 1 2;0 1;
tr 1 1 1 1 3 2 rz 15;
endpart
The region 1 1 1 1 3 2 is the face at the lowest reduced i. The tr rotates its vertices by 15 degrees about the z axis. In the mesh, node 1 moves from (1, 0, 0) to (0.9659, 0.2588, 0). The nodes between the face and the others follow by interpolation.
The script tests/corpus/171-ilin-face-region/input.tg uses pb and ilin together:
c pb lifts one boundary vertex; ilin pulls the face interior toward it.
block 1 3 5;1 3 5;1 2;0 1 2;0 1 2;0 1;
pb 2 1 1 2 1 1 z 0.4
ilin 1 1 1 3 3 1
endpart
The pb lifts the middle vertex of one edge of the k = 1 face by 0.4. The ilin sets the one interior vertex of that face from the face boundary, and it rises to z = 0.2. James takes the weights of an ilin from the full indices, the node counts between the vertices, and not from distances in space.
A q collapses an edge or makes two corners coincide, which is how a block becomes a wedge. q takes two vertices, six numbers in all, and a seventh is refused. The page of q shows the error.
Edges and their spacing
Each edge of the part’s grid is a row of nodes between two vertices. James places the nodes of every edge in three steps. Step 2 attaches an edge to a curve if you asked. Step 4 lays out the edges that a command reached: lin on an edge region, and the four spacing commands. Step 5 spaces every other edge equally along the straight line between its end vertices.
Putting an edge on a curve
A 3D curve comes from curd, which the geometry chapter explains. An edge command names a region that is an edge, two of its three pairs of indices equal, and a curve number.
| Command | Where the edge goes |
|---|---|
| cur | the end vertices move to the closest points of the curve, and the nodes lie along the curve between them |
| curf | as cur, and the nodes are then frozen |
| cure | the end vertices go to the two ends of the curve, whatever their own positions |
| curs | a composite edge, one that spans several blocks: every vertex goes to its closest point, and each simple edge is placed as cur places it |
| splint | for a region of any class and a direction, one cubic spline through the vertices of each edge of the region along that direction, as they stand, with no curve number |
James spaces the nodes by arc length along the curve. On a closed curve, cur and curf take the shorter arc between the ends of the edge, while cure on a loop curve covers the whole loop.
cur, cure and curs place the edge and leave it a starting position. A later step may project a vertex of the edge off the curve, and the edge is not pulled back. curf holds the edge. Step 3 projects none of its vertices: the two end vertices are frozen as soon as step 2 places them, and a vertex between them, on an edge that crosses several blocks, is held through step 3. The nodes between the ends are frozen once the placement of the edge is complete, after step 5, so that a spacing command is honoured along the curve first. No later step moves a frozen node. Projection, every interpolation and the smoothers skip it and use its position as boundary data for the nodes around it.
The script tests/corpus/173-curf-freezes-edge/input.tg shows the rule:
c curf freezes the i edge on curve 1; the sfi that follows leaves its interior nodes alone.
curd 1 lp3 0 0 0 1 0.3 0 2 0 0;;
sd 1 plan 0 0 0.2 0 0 1
block 1 5 9;1 3;1 2;0 1 2;0 1;0 1;
curf 1 1 1 3 1 1 1
sfi ;;-1;sd 1
endpart
The curve is a polyline that rises from (0, 0, 0) through (1, 0.3, 0) to (2, 0, 0), and the plane is z = 0.2. The sfi projects the k = 1 face onto the plane. The edge crosses two blocks, so it has three vertices. Step 3 projects none of them, and all nine nodes of the edge stay on the polyline at z = 0, for example node 3 at (0.5, 0.15, 0) and the middle vertex at (1, 0.3, 0). Without the curf, every node of the edge lands at z = 0.2.
edge puts an edge on a side of a surface, as cur puts it on a curve: the end vertices move to the closest points of the side and the nodes lie along it by arc length. patch does it for the four edges of a face at once and projects the face. Only a surface that has sides takes either; the geometry chapter says which kinds do and how James numbers the sides. A curve made of a side, curd with the type sdedge, takes cur, curf and curs like any other.
Spacing the nodes along an edge
Four commands set where the nodes of an edge lie between its ends. Each takes a region, a direction i, j or k, and numbers.
| Command | What you give | Result |
|---|---|---|
| res | one ratio | the intervals form a geometric series, each interval the ratio times the one before it, counted from the end with the lowest index |
| drs | two ratios | one series from each end, meeting in the middle |
| as | a flag and a size | the first interval (flag 0) or the last (flag 1) has the size, and the others follow one geometric series |
| das | two sizes | the first and the last interval have the sizes, and two series grow toward the middle |
James scales each series so that it fills the edge. A ratio of 1 is equal spacing, which is the default. For an edge of length 7 cut into three intervals, a ratio of 2 gives the nodes 0, 1, 3 and 7.
The script tests/corpus/076-drs-both-ends/input.tg spaces an edge from both ends:
block 1; 1; 1 5;
0;
0;
0 17;
drs 1 1 1 1 1 2 k 2 3
endpart
The edge runs along k from 0 to 17 in four intervals. The ratio 2 from the low end and the ratio 3 from the high end give the intervals 3, 6, 6 and 2, and the nodes at 0, 3, 9, 15 and 17. James wrote those nodes when merge, neutral and write were added to the script and --write-unref-nodes was on the command line. The flag is needed because the part has no element.
A region that spans several blocks along the direction is one composite edge. James ignores the blocks inside the span, and the vertices inside it slide to their places in the series.
A spacing command works along the edge as it stands, so an edge attached to a curve is spaced along the curve. James spaces an edge again after step 6 projects it onto a surface, along the projected edge and by the same rule, and repeats until the nodes settle.
Two rules guard the sizes. A ratio or a size that is zero or negative is an error. For das, gap1 plus gap2 may not exceed the length of the edge. A sum equal to the length is accepted and leaves every interval between the two gaps at zero length. James checks the sum against the edge’s current length each time it spaces the edge, so a projected edge is held to it too. The script tests/corpus/079-das-gap-sum-exceeds-rejected/input.tg gives gaps of 6 and 8 on an edge of length 11:
block 1; 1 5; 1;
0;
0 11;
0;
das 1 1 1 1 2 1 j 6 8
endpart
James prints the error that tests/corpus/079-das-gap-sum-exceeds-rejected/expected.diag.txt holds:
input.tg:5:1: error [E0903]: das gap1 + gap2 exceeds the edge's total arc length
james: 1 error, 0 warnings
nds asks for spacing by a density function that ndd would define. James does not have ndd, so it reads every nds and refuses it.
On a cylinder part James measures an edge in the part’s own coordinates. Along an edge in the angle direction, a size or a gap counts degrees, not a distance.
lin on an edge region also acts at step 4. It places the nodes on the straight chord between the end vertices, spaced by the rule in force for the edge. The next sections come back to lin.
Projecting onto surfaces
A projection moves a node to the nearest point of a surface. Three commands project.
| Command | What it projects |
|---|---|
| sf | a vertex, an edge or a face onto one surface |
| sfi | the regions of an index progression, each as sf does |
| ms | one face per reduced index along a direction, each onto its own surface of a sequence |
A surface comes from sd and is named by number or name, or it is defined on the spot inside the command. The geometry chapter explains the 36 kinds. A vertex is projected at step 3, the nodes of an edge at step 6 and the nodes of a face at step 9. A command that names a face therefore also projects the face’s edges and vertices, at their own steps. A region that is a block is an error, because projecting a solid has no meaning. Name its faces.
The nearest-point rule
James does not map the mesh onto the surface. It takes each node where it stands and moves it to the point of the surface closest to it. The segment from the old position to the new one meets the surface at a right angle.
That rule decides which way a face bulges, and it decides it by where the surface’s own centre lies. Take a sphere. The nearest point of a sphere to a node lies on the ray from the sphere’s centre through the node. A node inside the sphere moves outward along that ray. A node outside moves inward. A flat face that lies between the centre and the sphere, at a distance from the centre smaller than the radius, therefore bulges away from the centre, toward the sphere, and its middle moves farthest. If the centre lies on the same side as the bulge you wanted, the face bulges the wrong way. Place the centre of the sphere on the side of the mesh opposite to the bulge you want.
The lens
A lens shows the rule. Its top and bottom faces are spheres of radius 4 and its sides are a cylinder of radius 2. The script tests/golden/017-lens/input.tg, which make test runs, is:
c A lens: one block part, its top and bottom faces projected onto two
c spheres and its four sides onto a cylinder, so the square block becomes a
c round biconvex lens 0.6 thick at the rim and 1.67 at the centre. The mesh
c is written twice, as the neutral file and as Exodus II.
sd 1 cyli 0 0 0 0 0 1 2
sd 2 sphe 0 0 3.164 4
sd 3 sphe 0 0 -3.164 4
block 1 7;1 7;1 5;-1.4 1.4;-1.4 1.4;-0.6 0.6;
sfi -1 -2;;;sd 1
sfi ;-1 -2;;sd 1
sfi ;;-1;sd 2
sfi ;;-2;sd 3
endpart
merge
neutral
write
exodusii
write
The part is one block, a square slab 2.8 across and 1.2 thick. The cylinder sd 1 has radius 2 and the two sfi commands that name it pin i and j to their lowest and highest reduced index, so they cover the four side faces. The sphere sd 2 has its centre at z = 3.164, above the slab. The sfi ;;-1; command takes the face at the lowest reduced k, the bottom face at z = -0.6, and projects it onto that sphere. The face lies between the centre and the sphere’s lower pole, so it bulges away from the centre, downward. The sphere sd 3 is the mirror image, with its centre at z = -3.164, and it carries the top face upward.
James wrote the mesh with the neutral file’s lines, 245 nodes and 144 elements. The column of nodes on the axis runs from z = -0.836 to z = 0.836, so the lens is 1.672 thick at its centre. The nodes of the rim lie on the cylinder and on a sphere at once, at z = -0.300 and z = 0.300, so the rim is 0.600 thick. The rim is thinner than the slab’s 1.2 because the rim and corner nodes lie outside the sphere, at a distance from its centre greater than the radius, so they move toward the centre, as a node outside a sphere does. A face that lies wholly outside a sphere dishes toward the centre in the same way. The script writes the mesh twice, as the neutral file and as Exodus II, so james input.tg -o lens makes the files lens and lens.0001.
Two and three surfaces at a node
A node that several projection commands reach is projected onto all of its surfaces at once.
- One surface: the node goes to the nearest point of that surface.
- Two surfaces: the node goes to a point on both, on the curve where they cross.
- Three surfaces: the node goes to the point where the three meet.
A node carries at most three surfaces. James counts the distinct surfaces that reach one vertex, in the order of the commands, and a composite surface from sds counts as one. A fourth is an error, reported once per part for the first vertex that reaches it. The reason is geometric: three independent surfaces fix a point, and a fourth would over-determine it.
The script tests/corpus/066-sf-two-surface-intersection/input.tg puts an edge on two planes:
sd 1 plan 0 0 0 0 0 1
sd 2 plan 0 0 0 1 0 0
block 1 2 3;1 2 3;1 2 3; 0 1 2; 0 1 2; 0 1 2;
sf 1 1 1 1 3 1 sd 1
sf 1 1 1 1 3 1 sd 2
endpart
Both sf commands name the edge 1 1 1 1 3 1, which runs along j on the line where the planes z = 0 and x = 0 cross. Every node of the edge carries two surfaces. The edge already lies on both planes, so nothing moves.
An inline surface that you repeat is a second surface, because James does not recognise a repeat. A surface meant for several commands is defined once with sd and named.
The shorthands of ms stand for a whole sequence of surfaces. The script tests/corpus/140-ms-shorthand-planes/input.tg projects three faces onto three planes:
block 1 2 3;1 2;1 2 3;0 1 2;0 1;0 1 2;
ms 1 1 1 3 2 3 i ppx 0 1 2
ms 1 1 1 3 2 3 k pon 0 0 0 0 0 2 0 1 2
endpart
The first ms spans three i faces, and ppx 0 1 2 gives them the planes x = 0, 1 and 2. The second spans three k faces, and pon gives them the planes z = 0, 1 and 2. The number of surfaces must equal the number of faces.
A projection that cannot be solved stops the run with an error that names the node and the part. A node at the centre of a sphere is the usual case, since every point of the sphere is equally near. James never turns such a failure into a warning.
spp projects along rays through a template mesh. James reads every argument and then refuses it, because the command tmplt that would define the template does not exist in this version.
Interpolating the interior
After the edges and the projections, James places the nodes inside faces and blocks. It always interpolates, and a script may choose which kind.
| Where | Edges | Faces | Blocks |
|---|---|---|---|
| Default, automatic | step 5, the chord | step 8, modified bilinear | step 15, trilinear |
lin | step 4 | step 7 | step 14 |
tf | refused | step 10 | step 16 |
The default needs no command. A face is filled from its four bounding edges by a bilinear blend that James modifies where an edge row pinches, and a block is filled from its six faces by the trilinear blend, with no pinch correction. The hierarchy names step 15 “default modified tri-linear”, but this version applies no correction in 3D. lin asks for the linear kind on a region you name. tf asks for transfinite interpolation, which places each node by its relative arc length along the boundary edges, so the spacing you gave the edges shapes the interior. James does no smoothing unless you ask for it, and a boundary that folds the arc-length map gives inverted elements. The smoothing section shows a fold and the relax that clears it.
lin and tf take a region that may span several blocks. James treats the region as one edge, face or block, takes its outer boundary and ignores the blocks inside. The nodes at the boundary never move. A lin over several blocks places their interior partition lines and faces as interior nodes, and a node that a surface constrains is projected onto its surface again afterwards. James chooses the step from the shape of the region and from nothing else, so lini and tfi can place the members of one progression at different steps.
A lin over a region that is already one block, face or edge changes nothing under the default intyp 1, because the default is the same blend. intyp chooses the default. Under intyp 2 the default for every face and block is transfinite, and then a tf over one simple region changes nothing, while a lin over one simple region forces the linear blend and changes the nodes. The page of intyp describes the setting.
The script tests/corpus/178-lin-face-region/input.tg shows lin over a whole face:
c lin over a face region whose centre vertex pb lifted
block 1 3 5;1 3 5;1 2;0 1 2;0 1 2;0 1;
pb 2 2 1 2 2 1 z 0.4
lin 1 1 1 3 3 1
endpart
The part has 2 by 2 blocks in i and j and is one layer thick. The pb lifts the centre vertex of the k = 1 face to z = 0.4. The region 1 1 1 3 3 1 is the whole face, so James stores the lin for step 7. The centre vertex is an interior vertex of that region, so lin recomputes it from the outer boundary. With the lin, the centre node returns to z = 0, and so do the four nodes beside it, which sat at z = 0.2, and the four diagonal nodes, which sat at z = 0.1. Without it they stay lifted.
The script tests/corpus/180-tfi-face-progression/input.tg shows transfinite interpolation over two faces:
c tfi over the two k faces of a part of two blocks
block 1 3 5;1 3;1 3;0 1 2;0 1;0 1;
pb 2 2 1 2 2 1 xy 1.2 1.1
tfi ;;-1 -2;
endpart
The progression ;;-1 -2; pins k to 1 and 2, so James expands it to the two k faces and stores each for step 10. The pb moves the vertex 2 2 1 to x = 1.2, y = 1.1, and the tfi moves the interior nodes of both faces a little. Node 7 goes from (0.55, 0.525, 0) to (0.54996, 0.52293, 0). A node that tf moves is projected again onto the surfaces that constrain it.
On a cylinder part James interpolates the angle as an ordinary number, as you wrote it. Boundary angles of 350 and 10 interpolate through 180. To go the short way, write 370.
Passes
Some parts need more than one run of the interpolation and projection steps, because one region’s boundary can lie inside another region, and each needs the other’s result. A pass is steps 4 to 19 and 21; step 20, the equations, runs once after the last pass. James runs a pass, compares every node with its place after the pass before, and runs another while any node still moves by more than a small tolerance. mxp sets the most passes, 4 by default. A part that settles sooner stops sooner. A part that has not settled after mxp passes keeps the last result, with no error and no warning. Steps 1 to 3 run once, whatever mxp says. Raising mxp costs time only.
Smoothing
An interpolated mesh can be skewed or uneven, and a transfinite mesh can fold. A smoother moves the interior nodes of a face or a block, iteration by iteration, with the region’s own boundary nodes as fixed data. Four commands do it.
| Command | Takes |
|---|---|
| relax | one face, a list of faces joined by &, or one block |
| relaxi | an index progression, each member smoothed on its own |
| tme | one face or one block |
| tmei | an index progression, each member smoothed on its own |
A region that is an edge or a vertex has no interior and is an error (E1300).
Which smoother
relax makes the elements even. It solves the equations that make the mesh lines equipotential lines of the boundary, so a skewed or folded interior straightens out. The price is that the spacing you gave the edges inside the region is lost, and the spacing along the boundary does not reach inward.
tme carries the spacing of the boundary inward and turns the mesh lines toward a right angle where they meet the boundary. It solves the same equations with a control term in each direction, which James works out once from the spacing along the fixed sides. Where the sides are even, tme gives what relax gives. Where they are graded, the grading crosses the region.
Pick relax for an even mesh, or to clear a fold. Pick tme when the boundary’s spacing is what you designed, a graded edge for example. The two combine: relax runs at step 11 and tme at step 12, so tme comes after relax and restores what the boundary asks for.
The script tests/golden/027-tme-face/input.tg, which make test runs, grades a slab and smooths it both ways:
c tme on a face. A slab whose two j edges are graded by res toward y = 0.
c relax (five iterations) first evens the interior out and loses the
c grading; tme then carries the sides' spacing back across each k face,
c since its control functions are computed from the fixed sides alone.
block 1 9;1 13;1 2;0 4;0 6;0 .5;
res 1 1 1 1 2 2 j 1.2
res 2 1 1 2 2 2 j 1.2
relaxi ;;-1 0 -2; 5 0 1
tmei ;;-1 0 -2; 400 0 1
endpart
merge
neutral
write
The two res commands grade the j edges of the slab, so the first interval along each is 0.152 and the last is 1.126. The relaxi of five iterations evens the interior out and partly loses the grading: the first interval of the middle line is 0.194 and the last 1.049. The tmei then carries the sides’ spacing back across each k face. The line of nodes up the middle of the slab ends with the same intervals as its edges, 0.152 first and 1.126 last. Run relaxi alone to 400 iterations instead, and the middle line’s first interval is 0.308 and its last 0.860.
The three numbers
Every smoother ends with three numbers after its region or progression: iterations min_change weight.
iterationsis the most iterations to run, a positive integer (E1302).min_changeends the run early once no coordinate of any node moved by more than it in one iteration. It is zero or more (E1303), in the part’s own coordinates, and zero ends the run early only if an iteration moves no node at all.weightis the fraction of the way a node moves from its old position to its new one in each iteration. It is above 0 and at most 1 (E1304). A weight of 1 suits most meshes, and a smaller one only slows the run.
Each iteration moves every node from the positions the iteration before left, so the result does not depend on the order in which James visits the nodes. A run of a million elements for ten iterations takes about a second.
A list against a progression
A relax list joins faces with & and smooths them as one system. The edges the faces share move, and so does a block’s corner where three listed faces meet. A node moves only where the listed faces close around it in one ring. The list holds faces only (E1301), and tme takes one region, so a list is relax’s alone.
A progression, in relaxi and tmei, is expanded to regions, and each member is smoothed on its own, one after the other, at the step its class gives it. A face smoothed on its own keeps its boundary where it is. A progression can hold a face and a block, and then the command acts at two steps. A pair of negatives in a progression list is an interval with both ends pinned, so -1 -2;-1 -2;-1 -2; is the six faces of a block. The concepts chapter gives the rule.
Faces stay on their surfaces
A face that a surface constrains stays on it. In every iteration James puts each face node back on its surfaces, and a node that lies on two surfaces slides along their intersection. The interior nodes of a block are not projected. A list of faces is for faces on surfaces: an edge two listed faces share is held to its shape only by the surfaces under it, and with none, as on the flat faces of a block, nothing holds the edge, and relax draws it inward and cuts the block’s corner. A list whose faces close on themselves and lie on no surface, the six faces of a block, has nothing to hold it and collapses toward its centre. Take a unit block of ten elements a side: after 200 iterations every coordinate lies between 0.427 and 0.573, and James prints no warning. Smooth flat faces one by one. min_change is tested before the projection, so on a curved face the change seldom falls below it and the run usually does all its iterations.
A frozen node, one that curf holds, and a node next to a deleted region never move.
Where smoothing sits in the steps
A face smoothed by relax runs at step 11 and by tme at step 12. A block runs at steps 17 and 18. Commands at one step run in the order you wrote them.
A region that spans several blocks moves the vertices and edges inside it, so the nodes around it must be placed again. Step 13 does that. It holds every node of the smoothed regions, their boundaries included, lays out again the edges that have a moved end, a graded edge with its grading, interpolates again the faces that have a moved edge and projects them again. An edge laid out again is laid out piece by piece between the vertices a smoother held, each piece keeping the grading’s ratio. An edge that cur put on a curve keeps its nodes, so hold the vertex at its end with curf if a smoothed face would move it. Steps 14 to 16 then fill the solids from the smoothed faces. A part with no step 11 or 12 command skips step 13.
The smoothing steps give the same result in every pass. A later pass starts the smoothing again from the same interpolated mesh, so the iteration count is yours whatever mxp is, and raising mxp does not smooth more.
A cylinder part
In a cylinder part a smoother works on the stored radius, angle and height as three numbers, as the interpolations do, and min_change is in those units. The equations then mix lengths with an angle in degrees. In the script tests/golden/029-relax-cylinder-part/input.tg, an edge pulled to radius 2.3 and angle 25 comes back to radius 2 and angle 30.
The cube on a sphere
TrueGrid’s manual has a cube whose six faces lie on a sphere as its example. The script tests/golden/022-cube-on-sphere/input.tg, which make test runs, builds it with no smoothing, ten elements a side:
c The manual's cube on a sphere (Vol. 1, p. 227), ten elements a side, as a
c solid block with its six faces on the unit sphere and no smoothing. The
c pair of negatives in each list is an interval with both ends pinned, so
c the one sfi names the six faces. A block's corner on a smooth surface is
c nearly flat, and the eight corner elements are inverted: the twin of case
c 023, which relaxes the six faces.
sd 1 sp 0 0 0 1
block 1 11;1 11;1 11;-1 1;-1 1;-1 1;
sfi -1 -2;-1 -2;-1 -2;sd 1
endpart
merge
neutral
write
The one sfi names the six faces, because the pair -1 -2 in each list is an interval with both ends pinned. James spaces the nodes evenly along each cube edge and interpolates the faces from them. A cube’s corner on a smooth surface is nearly flat, and James warns about the eight corner elements, which are inverted. It prints what tests/golden/022-cube-on-sphere/input.diag.txt holds:
input.tg:8:1: warning: part #0 has 8 elements with a negative Jacobian
james: 0 errors, 1 warning
The script tests/golden/023-cube-on-sphere-relaxed/input.tg adds one relax over the six faces, as one list:
c The manual's cube on a sphere with its six faces relaxed together (Vol. 1,
c p. 228): relax over a list joined by & smooths the faces as one system,
c the twelve edges they share and the eight corners included, and every
c node stays on the sphere. The mesh lines draw in toward the corners, and
c the eight corner elements that case 022 writes inverted are sound here.
c The second write is the Exodus II file.
sd 1 sp 0 0 0 1
block 1 11;1 11;1 11;-1 1;-1 1;-1 1;
sfi -1 -2;-1 -2;-1 -2;sd 1
relax 1 1 1 1 2 2 & 2 1 1 2 2 2 &
1 1 1 2 1 2 & 1 2 1 2 2 2 &
1 1 1 2 2 1 & 1 1 2 2 2 2
200 .0001 1
endpart
merge
neutral
write
exodusii
write
The list is one system, so the twelve edges the faces share and the eight corners move too, and every node stays on the sphere. The mesh lines draw in toward the corners. In the unsmoothed cube every element edge along a cube edge is 0.123 long. After relax the edge at the corner is 0.0788 and the edge in the middle of a cube edge is 0.1498, and the eight corner elements are sound. James prints no warning. The same script with 30 elements a side and 200 iterations is the one the manual prints a number for: the edge of the corner element is 0.018319095 in James where the manual prints 0.018319121.
A fold
A transfinite face can fold where two edges bow toward each other. The script tests/golden/024-tf-fold/input.tg builds one, and James warns that four elements are inverted. Its twin, tests/golden/025-tf-fold-relaxed/input.tg, adds relaxi for twenty iterations on each k face, and the warning is gone.
What stays refused, and a warning to expect
unifm, unifmi, neu and neui stay refused because the report their method comes from has not been found, esm and esmp because no page and no cited work says what the two parameters of esm do, and hyr because it is no option of a command James builds. The compatibility chapter says why for each. tme refuses a region with a hole, a deleted element inside the block or a quadrilateral of the face with no element on either side (E1305); relax smooths around one.
relax does not promise sound elements. Where the boundary has a sharp corner that juts into the mesh, an element beside the corner can end inverted, and the warning about elements with a negative Jacobian, described in the next section, reports it. Take a slab of 10 by 10 by 1 elements whose corner vertex is pulled in to (6, 6):
block 1 11;1 11;1 2;0 10;0 10;0 1;
pb 1 1 1 1 1 1 xy 6 6
relax 1 1 1 2 2 1 200 0 1
endpart
The interpolated slab has 10 elements with a negative Jacobian. After the relax, one is left, beside the corner, and James prints part #0 has 1 element with a negative Jacobian. Pulled only to (5, 5), the corner leaves no inverted element with or without the relax.
Reshaping with the equations
When no projection, interpolation or smoother gives the shape you want, the six equations x=, y=, z=, t1=, t2= and t3= set a coordinate or a temporary at every node from an expression over the node’s own coordinates, its full indices and the script’s parameters, and dom names the region they read and write. They run at step 20, once, after the smoothers and after the part’s last pass, so no projection or smoother ever sees their result, and a relax written after an equation still runs before it. In a cylinder part the equations read and write the stored radius, angle in degrees and height, which is how the manual twists a cylinder. The script tests/golden/042-cylinder-twist/input.tg, which make test runs, perturbs the radius of a tube of shells, 36 around by 10 high:
c The cylinder of Vol. 1, p. 276: x, y and z of a cylinder part are its radius,
c angle in degrees and height, so x= perturbs the radius: twelve lobes whose
c phase turns them 20 degrees about the axis per unit height (40 over the part),
c and a 4*k term spanning 4 to 44 degrees on 10 elements, a taper of .056 and
c not the page's ripple (70 elements, 4 to 284 degrees). The 290 by 70 shells are
c 36 by 10, with a thickness the page lacks; the seam is merged; the second write is Exodus II.
cylinder -1;1 37;1 11;1 0 360 0 2
x=x+.1*cos(12*y+z*240)+.2*cos(4*k)
thic .1
endpart
merge
st .001
neutral
write
exodusii
write
The parts chapter describes the equations, their variables and their diagnostics, and the page of x= their rules.
Reading the lines about inverted elements
An element is right-handed when the triple product of its edges at a corner is positive, which means its volume has a positive sign. James numbers the corners of every element in one order. The first four corners are the k face, counterclockwise as seen from the k + 1 side, and the last four are the k + 1 face in the same order. The merge and output chapter draws it. An element whose corners fall in a different handedness has a negative sign, and James calls it inverted.
When James builds a part, it tests every element. A part in which every element is inverted gets a note, and James writes it with the corners of every element reordered, so that the file is right-handed:
part #n is inverted; its k elements are written with their corners reordered
A part in which some elements are inverted gets a warning, and James writes them as they are:
part #n has k elements with a negative Jacobian
The number after # is the part’s position in the script, counted from zero, so part #0 is the first part. A part with one inverted element reads has 1 element, and a one-element part that is inverted gets the note. The line has the position of the part’s opening command.
The script tests/corpus/041-pb-two-same-vertex/input.tg moves one vertex past its neighbour:
block 1 2;1 2;1 2;0 1;0 1;0 1;
pb 1 1 1 1 1 1 x 1.0
pb 1 1 1 1 1 1 x 2.0
endpart
The second pb wins, so the vertex ends at x = 2, past the vertex at x = 1 beside it, and the element folds. James prints the warning that tests/corpus/041-pb-two-same-vertex/expected.diag.txt holds:
input.tg:1:1: warning: part #0 has 1 element with a negative Jacobian
james: 0 errors, 1 warning
A warning with a count of one or a few means a vertex or a curve pushed an element through its neighbour, as above, or an interpolation folded where the boundary bends sharply, which tf can do. James writes such an element as it is and does not stop. A solver reads the file’s corner order, so the part needs fixing before the file is used.
The note means the part is inverted as a whole: every active element has no corner with a positive triple product and at least one with a negative one. A collapsed corner, whose product is zero, decides nothing. The usual cause is a coordinate list in a block that decreases, so that the i, j, k axes of the grid make a left-handed system. One decreasing list inverts every element of the part, and so do three. Two decreasing lists cancel, because each reverses one axis and the grid is right-handed again, and James prints nothing. The script tests/golden/020-inverted-one-list/input.tg holds a block of eight elements with a decreasing x list:
c One decreasing coordinate list: the x list runs 2 1 0, so the i axis of
c the grid points down x and every one of the eight elements has a negative
c Jacobian at every corner. James writes the part positive, each element's
c k faces exchanged, and says so in a note in place of the warning.
block 1 2 3;1 2 3;1 2 3;2 1 0;0 1 2;0 1 2;
endpart
merge
neutral
write
James prints the note that tests/golden/020-inverted-one-list/input.diag.txt holds:
input.tg:5:1: note: part #0 is inverted; its 8 elements are written with their corners reordered
The reordering exchanges the k face and the k + 1 face of every element of the part, so each element reads right-handed in the file. The nodes keep their numbers and positions. Golden case 021-inverted-two-lists, the same block with decreasing x and y lists, prints nothing, since the two reversals cancel. James does not reorder a part in which only some elements are inverted: that would hide a fold. Write the coordinate lists in increasing order when you can, and read the note as a reminder that the script’s axes are left-handed.
An element can also come out with zero volume after a merge, which has its own warning. The merge and output chapter covers it.