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 \input

Deformed configuration

Passing a displacement vector draws the deformed configuration x_i + scale * u_i:

  • with a DofHandler, u is the global solution vector and the nodal displacements of field are extracted with Ferrite.evaluate_at_grid_nodes;
  • with a bare grid, u is either a Vector{Vec{2}} of length getnnodes(grid) or a flat Vector{<:Real} of length 2 * 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).

Note

The picture scale is exposed as picturescale in tikzgrid because scale is taken by the displacement magnification. GridStyle itself calls it scale.

source
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...) -> String

The 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.

source

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: TikZ scale= 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 to false to 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, see TikzColor.
  • linestyle = "": extra TikZ options for the wireframe, e.g. "dashed" or "densely dotted".
  • drawcells = true: draw the wireframe at all. false gives a fills-only picture.

Cell fills (flat/constant per cell)

  • cellcolor = nothing: uniform fill colour for all cells. nothing means no fill.
  • cellsetcolors = []: cell set names (see Ferrite.getcellset) mapped to colours, given as a vector of pairs (["steel" => "blue!20", "rubber" => colorant"#e31a1c"]) or as a Dict. Cells in one of these sets are filled with the corresponding colour instead of cellcolor. 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.
source
FerriteTikz.TikzColor — Type
TikzColor

Anything 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.

source

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.

source
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.

source

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.

source
FerriteTikz.drawMultiPlot — Function
drawMultiPlot(io, registry; picturescale = 1.0) -> TikzPicture
drawMultiPlot((io, registry); picturescale = 1.0) -> TikzPicture

Close 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.

Note

The scale field of the individual GridStyles passed to gridcode! is not used — a picture has a single scale, given here as picturescale. Every other style option applies per layer as usual.

source
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.

source

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.

source
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.

source

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.

source
FerriteTikz.isline — Function
isline(cell) -> Bool

Whether 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.

source
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.

source
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).

source
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.

source
FerriteTikz.edgekey — Function
edgekey(edge) -> NTuple{2, Int}

Orientation-independent identity of an edge, used to draw shared edges only once.

source
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.

source
FerriteTikz.EdgeSegment — Type
EdgeSegment

A single edge of a cell, resolved to coordinates and ready to be emitted as TikZ.

  • from, to: the corner points of the edge.
  • controls: nothing for a straight edge, or the two cubic Bezier control points.
source
FerriteTikz.edgesegment — Function
edgesegment(coords, edge; bezier = true) -> EdgeSegment

Resolve 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.

source
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.

source

Code generation internals

FerriteTikz.coordstring — Function
coordstring(p::Vec{2}, digits::Int) -> String

A single TikZ coordinate (x,y) with the components rounded to digits digits.

source
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.

source
FerriteTikz.cellpath — Function
cellpath(grid, coords, cellid, style) -> String

The closed TikZ path around cell cellid, used for the cell fill.

source