API Reference
Plotting
FerriteTikz.tikzgrid — Function
tikzgrid(grid::AbstractGrid; kwargs...) -> TikzPicture
tikzgrid(grid::AbstractGrid, u::AbstractVector; scale = 1.0, reference = nothing, kwargs...)
tikzgrid(dh::DofHandler, u::AbstractVector; field = :u, scale = 1.0, reference = nothing, kwargs...)Draw a Ferrite grid as a TikzPictures.TikzPicture. Grids embedded in one or two spatial dimensions are supported; a one-dimensional grid is drawn along the x axis.
Area cells (Triangle, Quadrilateral and their quadratic variants) are drawn as filled outlines with shared edges stroked once. Line elements (Line, QuadraticLine, in either 1D or 2D space) enclose no area, so they are stroked one per cell and their cell colour becomes the stroke colour rather than a fill. A grid may mix both.
The result renders inline in VSCode, Pluto and IJulia and can be written to disk with the usual TikzPictures machinery:
save(PDF("grid"), p) # standalone PDFsave(SVG("grid"), p) # standalone SVGsave(TEX("grid"), p) # standalone .tex documentsave(TEX("grid"; limit_to = :picture), p) # just the tikzpicture, for \inputDeformed configuration
Passing a displacement vector draws the deformed configuration x_i + scale * u_i:
- with a
DofHandler,uis the global solution vector and the nodal displacements offieldare extracted withFerrite.evaluate_at_grid_nodes; - with a bare grid,
uis either aVector{Vec{2}}of lengthgetnnodes(grid)or a flatVector{<:Real}of length2 * getnnodes(grid).
scale is the displacement magnification factor.
Overlaying the reference configuration
reference draws the undeformed grid underneath the deformed one. Pass a NamedTuple or a GridStyle with the style it should be drawn in; it inherits every option not given explicitly from the main style, except that it is never filled and carries no labels by default:
tikzgrid(dh, u; scale = 20, cellcolor = "blue!15", reference = (linecolor = "gray", linestyle = "dashed"))Pass reference = true to use the defaults, or leave it at nothing to draw the deformed configuration alone.
Styling
Everything else is forwarded to GridStyle — colours (cellcolor, cellsetcolors, linecolor), line appearance (linewidth, linestyle), markers and labels (drawnodes, nodelabels, celllabels) and geometry (scale of the picture via picturescale, bezier).
FerriteTikz.tikzcode — Function
tikzcode(grid; kwargs...) -> String
tikzcode(grid, u; scale = 1.0, kwargs...) -> String
tikzcode(dh::DofHandler, u; field = :u, scale = 1.0, kwargs...) -> StringThe raw TikZ code for a grid, i.e. the body of the tikzpicture environment, without the \definecolor statements (those live in the preamble of the TikzPictures.TikzPicture built by tikzgrid). Useful for composing pictures by hand.
All keyword arguments are documented in GridStyle. See tikzgrid for the meaning of u, scale, field and reference.
Styling
FerriteTikz.GridStyle — Type
GridStyle(; kwargs...)Styling options for tikzgrid and tikzcode. All keyword arguments of tikzgrid that are not listed in its own docstring are forwarded here.
Geometry
scale = 1.0: TikZscale=factor, i.e. how many TikZ units one grid unit corresponds to.bezier = true: draw curved edges for cells with a quadratic geometric interpolation. Set tofalseto draw every edge as a straight line between its corner nodes.digits = 5: number of digits coordinates are rounded to in the emitted TikZ code.
Lines
linewidth = "thin": TikZ line width key ("ultra thin","thin","thick", …, or something like"line width=0.6pt").linecolor = "black": wireframe colour, seeTikzColor.linestyle = "": extra TikZ options for the wireframe, e.g."dashed"or"densely dotted".drawcells = true: draw the wireframe at all.falsegives a fills-only picture.
Cell fills (flat/constant per cell)
cellcolor = nothing: uniform fill colour for all cells.nothingmeans no fill.cellsetcolors = []: cell set names (seeFerrite.getcellset) mapped to colours, given as a vector of pairs (["steel" => "blue!20", "rubber" => colorant"#e31a1c"]) or as aDict. Cells in one of these sets are filled with the corresponding colour instead ofcellcolor. If a cell belongs to several listed sets, the last matching pair wins, so pass a vector when the order matters.fillopacity = 1.0: opacity of the cell fills.
Nodes and labels
drawnodes = false: draw a marker at every node.nodestyle = "circle, fill=black, inner sep=0pt, minimum size=0.08cm": TikZ options for node markers.nodelabels = false: print the global node number next to every node.celllabels = false: print the global cell number at every cell centroid.labelstyle = "font=\\scriptsize": TikZ options for the labels.labeloffset = 0.06: offset of node labels from the node, in grid units.
FerriteTikz.TikzColor — Type
TikzColorAnything that can be used as a colour in FerriteTikz: an xcolor expression given as a String (e.g. "blue!20", "black") or any Colors.Colorant (e.g. colorant"#a6cee3", RGB(0.2, 0.4, 0.9)). Colorants are emitted as \definecolor statements, Strings are passed through to TikZ verbatim.
Deformation
FerriteTikz.deformedcoordinates — Function
deformedcoordinates(grid, u; scale = 1.0) -> Vector{Vec{2}}
deformedcoordinates(dh::DofHandler, u; scale = 1.0, field = :u) -> Vector{Vec{2}}The node coordinates of the deformed configuration, x_i + scale * u_i. The displacements u are resolved by nodedisplacements, so all of its input formats are accepted.
FerriteTikz.nodedisplacements — Function
nodedisplacements(dh::DofHandler, u::AbstractVector; field = :u) -> Vector{Vec{2}}
nodedisplacements(grid, u::AbstractVector{<:Vec}) -> Vector{Vec{2}}
nodedisplacements(grid, u::AbstractVector{<:Real}) -> Vector{Vec{2}}The displacement of every grid node, in node order, lifted to two dimensions.
Given a DofHandler and a global solution vector, the nodal values of field are obtained with Ferrite.evaluate_at_grid_nodes, i.e. by evaluating the shape functions of the field at the reference coordinates of the nodes. The field must have as many components as the grid has spatial dimensions. Nodes on which field is not defined come back as NaN from Ferrite and are reported as zero displacement together with a warning.
Alternatively the displacements can be handed over directly, either as a vector of Vec of length getnnodes(grid) or as a flat vector of length sdim * getnnodes(grid) laid out as [u1x, u1y, u2x, u2y, ...], where sdim = Ferrite.getspatialdim(grid).
On a grid embedded in one spatial dimension the displacements may still be given as Vec{2}, which draws the deflection of a one-dimensional mesh transverse to its axis.
Composing several grids into one picture
tikzgrid already draws a reference and a deformed configuration together. For more layers than that — a load history, a sequence of refinements, several patches side by side — build the picture up one grid at a time between setupMultiPlot and drawMultiPlot:
io, reg = setupMultiPlot()gridcode!(io, reg, grid, coords_0, GridStyle(linecolor = "gray", linestyle = "dashed"))gridcode!(io, reg, grid, coords_1, GridStyle(linecolor = "blue"))gridcode!(io, reg, grid, coords_2, GridStyle(linecolor = "red"))p = drawMultiPlot(io, reg; picturescale = 2)Each gridcode! call appends one layer, in drawing order, with its own GridStyle. Sharing the one registry is what keeps a Colors.Colorant used by several layers down to a single \definecolor statement.
FerriteTikz.setupMultiPlot — Function
setupMultiPlot() -> (io, registry)Start a picture that several grids are drawn into, and return the IOBuffer and the ColorRegistry to hand to gridcode!. Close the picture with drawMultiPlot.
tikzgrid already draws a reference and a deformed configuration together; use this when you need more than those two layers, for example a whole load history:
io, reg = setupMultiPlot()gridcode!(io, reg, grid, coords_0, GridStyle(linecolor = "gray", linestyle = "dashed"))gridcode!(io, reg, grid, coords_1, GridStyle(linecolor = "blue"))gridcode!(io, reg, grid, coords_2, GridStyle(linecolor = "red"))p = drawMultiPlot(io, reg; picturescale = 2)Sharing one registry across the calls is what keeps a Colors.Colorant used by several layers to a single \definecolor statement.
FerriteTikz.drawMultiPlot — Function
drawMultiPlot(io, registry; picturescale = 1.0) -> TikzPicture
drawMultiPlot((io, registry); picturescale = 1.0) -> TikzPictureClose a picture started with setupMultiPlot and return it as a TikzPictures.TikzPicture, ready for save(PDF(...), p) or inline display. The buffer is emptied, so call this once.
FerriteTikz.gridcode! — Function
gridcode!(io, reg::ColorRegistry, grid, coords, style::GridStyle)Write the TikZ body for one grid (fills, wireframe, node markers, labels) to io, registering any Colorants in reg. Call this repeatedly with the same io and reg to compose several grids into one picture; setupMultiPlot and drawMultiPlot open and close such a picture for you.
The pieces those two functions wrap, should you want to drive the process yourself:
FerriteTikz.ColorRegistry — Type
ColorRegistry()Collects the Colorants used by a picture and assigns them stable TikZ names so that they can be emitted as \definecolor statements ahead of the drawing commands.
FerriteTikz.tikzcolor — Function
tikzcolor(reg::ColorRegistry, c) -> StringReturn the TikZ colour expression for c, registering a new \definecolor name when c is a Colorant.
FerriteTikz.definecolors — Function
definecolors(reg::ColorRegistry) -> StringThe \definecolor preamble for every Colorant registered in reg.
FerriteTikz.setproperties — Function
setproperties(style::GridStyle; kwargs...) -> GridStyleCopy of style with the given fields replaced. Used to derive the reference-configuration style from the deformed one.
FerriteTikz.cellfills — Function
cellfills(grid, style::GridStyle) -> Vector{Union{Nothing, TikzColor}}Resolve the constant fill colour of every cell of grid: style.cellcolor by default, overridden by style.cellsetcolors for cells contained in one of the named cell sets.
Geometry
FerriteTikz.checksupported — Function
checksupported(grid)Throw a descriptive error if grid cannot be plotted by FerriteTikz. Grids embedded in one or two spatial dimensions are supported; 3D is not implemented yet.
FerriteTikz.isline — Function
isline(cell) -> BoolWhether cell is a line element, i.e. a cell of reference dimension one such as Line or QuadraticLine. Line elements are drawn as stroked paths rather than filled areas, and their celledges is the cell itself.
FerriteTikz.to2d — Function
to2d(x) -> Vec{2}Lift a coordinate or displacement to two dimensions, placing one-dimensional data on the x axis. Two-dimensional input is returned unchanged.
A bare Real is accepted because Ferrite.evaluate_at_grid_nodes returns plain scalars for one-component fields, which is how a displacement field on a one-dimensional grid is usually declared.
FerriteTikz.nodecoordinates — Function
nodecoordinates(grid) -> Vector{Vec{2, T}}The coordinates of all nodes of grid, in node order, lifted to two dimensions. Grids embedded in one spatial dimension are drawn along the x axis, i.e. a node at x becomes (x, 0).
FerriteTikz.celledges — Function
celledges(cell) -> Vector{NTuple{N, Int}}The global node ids of every edge of cell, in local edge order. Each entry holds the two end nodes first, followed by the interior nodes of that edge, i.e. (n1, n2) for a linear edge and (n1, n2, nmid) for an edge with a quadratic geometric interpolation.
For an area cell the edges are its facets, resolved through Ferrite.facetdof_indices. This is the same pattern Ferrite itself uses when writing facet sets to VTK, so higher-order cells are handled without a per-cell-type lookup table.
For a line element (see isline) the facets are its two end points, which are not edges at all — the drawable edge is the cell itself, so its node ids are returned as a single entry. Ferrite orders those as (start, end) and (start, end, mid), which already matches the convention above.
FerriteTikz.edgekey — Function
edgekey(edge) -> NTuple{2, Int}Orientation-independent identity of an edge, used to draw shared edges only once.
FerriteTikz.beziercontrolpoints — Function
beziercontrolpoints(p1, p2, pm) -> (c1, c2)The two cubic Bezier control points that reproduce exactly the quadratic Bezier curve through the end points p1, p2 with mid-side node pm at the parametric mid point.
The quadratic control point is q = 2pm - (p1 + p2)/2; degree elevation to a cubic gives c1 = p1 + 2/3 (q - p1) and c2 = p2 + 2/3 (q - p2). TikZ only speaks cubic Beziers (.. controls (c1) and (c2) ..), hence the elevation.
FerriteTikz.EdgeSegment — Type
EdgeSegmentA single edge of a cell, resolved to coordinates and ready to be emitted as TikZ.
from,to: the corner points of the edge.controls:nothingfor a straight edge, or the two cubic Bezier control points.
FerriteTikz.edgesegment — Function
edgesegment(coords, edge; bezier = true) -> EdgeSegmentResolve the node ids in edge (see celledges) against the coordinate vector coords. Edges with exactly one interior node are drawn as curves when bezier is true; edges with more interior nodes than that are not representable by a single cubic Bezier and fall back to a straight line.
FerriteTikz.celledgesegments — Function
celledgesegments(grid, coords, cellid; bezier = true) -> Vector{EdgeSegment}The boundary of cell cellid as a closed, consecutively ordered sequence of edge segments.
FerriteTikz.cellcentroid — Function
cellcentroid(grid, coords, cellid) -> Vec{2}The centroid of cell cellid, obtained by mapping the centroid of the reference nodes through the geometric interpolation of the cell. This places the point inside the cell also for curved and non-convex elements, and is where cell labels are anchored.
Code generation internals
FerriteTikz.coordstring — Function
coordstring(p::Vec{2}, digits::Int) -> StringA single TikZ coordinate (x,y) with the components rounded to digits digits.
FerriteTikz.appendsegment! — Function
appendsegment!(io, seg::EdgeSegment, digits; moveto = false)Append the path fragment for seg to io. With moveto = true the starting point is emitted as well, otherwise the fragment continues an existing path.
FerriteTikz.cellpath — Function
cellpath(grid, coords, cellid, style) -> StringThe closed TikZ path around cell cellid, used for the cell fill.
FerriteTikz.optionstring — Function
optionstring(parts...) -> StringJoin non-empty TikZ options with ", ".