Hierarchical and truncated hierarchical splines
using TinyGismousing TinyGismo: basis, degreeUniform refinement enlarges the space everywhere, which is wasteful when only a small part of the domain needs resolving: halving the mesh of a bivariate basis quadruples the number of functions however local the feature is. Hierarchical splines refine locally — a coarse tensor basis is the first level, and finer levels are added only where they are needed.
TinyGismo exposes two flavours, THBSplineBasis (truncated) and HBSplineBasis (not). They are constructed and refined identically; the difference shows up in the basis functions themselves, and is the subject of the last section.
Building a hierarchical basis
A hierarchical basis starts as a tensor basis, which becomes its coarsest level. Here is a quadratic basis on a 4×4 element grid:
kv = KnotVector([0.0, 0.0, 0.0, 0.25, 0.5, 0.75, 1.0, 1.0, 1.0])tensor = TensorBSplineBasis{2}(kv, kv)thb = THBSplineBasis{2}(tensor)(size(thb), numLevels(thb), Int(numElements(thb)))(36, 1, 16)With a single level it is exactly the tensor basis it was built from — same functions, same elements. numLevels counts levels 1-based, so level 1 is the coarsest.
Refining elements
refineElements! refines an exactly named set of elements, written as a RefinementBox. One convention does all the work here and is worth stating plainly:
A box names the level the region is set to, and its corners are indexed on that same level's grid.
Each level halves the cells of the one before it, so cell k on level l is cells 2k-1:2k on level l+1. To take the first coarse cell — the square $[0, 0.25]^2$ — down one level, name level 2 and give its corners on level 2's grid:
refineElements!(thb, RefinementBox(2, 1:2, 1:2))(size(thb), numLevels(thb), Int(numElements(thb)))(39, 2, 19)One element became four, and the basis grew by three functions rather than by the 45 that a uniform refinement would have added. getLevelAtPoint confirms the refinement landed where it was asked to and nowhere else:
[getLevelAtPoint(thb, p) for p in ([0.125, 0.125], [0.375, 0.125], [0.125, 0.375], [0.875, 0.875])]4-element Vector{Int32}:
2
1
1
1Refinement composes — refining again inside the refined region adds a third level:
refineElements!(thb, RefinementBox(3, 1:2, 1:2))(size(thb), numLevels(thb), getLevelAtPoint(thb, [0.0625, 0.0625]))(42, 3, 3)Refining by coordinates instead
When the region of interest is known as a parametric box rather than as element indices, refine! takes corner coordinates directly — a d × 2k matrix, each consecutive pair of columns one box. It refines each box one level deeper than the level it currently sits at:
byCoords = THBSplineBasis{2}(tensor)refine!(byCoords, [0.0 0.25; 0.0 0.25])(size(byCoords), getLevelAtPoint(byCoords, [0.125, 0.125]))(39, 2)This matches the element-box refinement above. The optional third argument refExt widens every box by that many cells first, which keeps a refinement from hugging a feature too tightly.
unrefine! and unrefineElements! go the other way. The level in a box means the same thing there — the level the region is set to — so undoing the refinement above names level 1:
unrefineElements!(byCoords, RefinementBox(1, 1:1, 1:1))(size(byCoords), getLevelAtPoint(byCoords, [0.125, 0.125]))(36, 1)Inspecting the elements
knotSpans is not available for hierarchical bases; elementBoxes replaces it, returning a 2d × numElements matrix whose columns hold each element's lower and upper corner:
boxes = toMatrix(elementBoxes(thb))size(boxes)(4, 22)The elements partition the parameter domain, so their areas sum to one:
lower, upper = boxes[1:2, :], boxes[3:4, :]sum(prod(upper .- lower; dims = 1))1.0This is the loop an adaptive scheme hangs off — evaluate an error indicator per element, then feed the worst ones back into refineElements!.
Hierarchical geometries
A THBSpline pairs a hierarchical basis with control points. Any tensor B-spline geometry can be lifted into the hierarchical setting unchanged, which is the usual starting point:
rect = createBSplineRectangle()geo = THBSpline{2}(rect)(numCoefs(geo), toVector(_eval(geo, [0.4, 0.4])))(9, [0.39999999999999997, 0.39999999999999997])Refining a geometry carries its control points along, so it gains resolution without moving:
before = toVector(_eval(geo, [0.4, 0.4]))refineElements!(geo, RefinementBox(2, 1:1, 1:1))after = toVector(_eval(geo, [0.4, 0.4]))(numCoefs(geo), before ≈ after)(16, true)Refining a basis on its own leaves any coefficients you hold beside it stale, since the number of functions changed. refineElements_withCoefs! updates both together and returns the new coefficients:
b = THBSplineBasis{2}(tensor)coefs = [Float64(i + j) for i in 1:size(b), j in 1:3]newCoefs = toMatrix(refineElements_withCoefs!(b, coefs, RefinementBox(2, 1:2, 1:2)))(Base.size(coefs, 1), Base.size(newCoefs, 1))(36, 39)convertToBSpline goes back to a tensor B-spline by refining the whole domain to the finest level present. The result is the same map, and usually far larger — that size difference is exactly what hierarchical refinement buys. thb from earlier carries three levels over a domain that is coarse almost everywhere:
deep = THBSpline{2}(thb, [Float64(i + j) for i in 1:size(thb), j in 1:3])flattened = convertToBSpline(deep)(numCoefs(deep), coefsSize(flattened))(42, 324)Nearly an eightfold difference, for a geometry refined in one corner. deep itself is untouched — convertToBSpline carries no !.
Both describe the same surface:
toVector(_eval(deep, [0.6, 0.6])) ≈ toVector(_eval(flattened, [0.6, 0.6]))trueTruncation
This is the one place the two flavours part company. Refine the same region in both:
truncated = THBSplineBasis{2}(tensor)plain = HBSplineBasis{2}(tensor)refineElements!(truncated, RefinementBox(2, 1:2, 1:2))refineElements!(plain, RefinementBox(2, 1:2, 1:2))(size(truncated), size(plain))(39, 39)The two spaces have the same dimension and span the same functions, but over the refined region the coarse functions overlap the fine ones and only the truncated basis subtracts that overlap back out. The simplest possible test shows it — whether the basis functions sum to one:
u = [0.125, 0.125] # inside the refined region(sum(toMatrix(_eval(truncated, u))), sum(toMatrix(_eval(plain, u))))(1.0, 1.1875)The truncated basis is a partition of unity; the untruncated one over-counts. Away from the refinement both agree, since there is no overlap to correct:
v = [0.875, 0.875](sum(toMatrix(_eval(truncated, v))), sum(toMatrix(_eval(plain, v))))(1.0, 1.0)Partition of unity is what makes coefficients behave like control points and keeps the basis well-conditioned, so THBSplineBasis is the default choice unless you want the untruncated functions.
Reading and writing
Hierarchical bases and geometries round-trip through the G+Smo XML format and export to Paraview like any other type:
writeParaview(thb, joinpath(tempdir(), "thb_basis"), 100)writeParaview(geo, joinpath(tempdir(), "thb_geometry"), 100)readFile takes the type to read as its first argument:
basis = readFile(THBSplineBasis{2}, "thbs_basis_02.xml")geometry = readFile(THBSpline{2}, "thbs_face_3levels.xml")