LaTeX directive reference¶
Every MechDSL directive is a LaTeX comment that begins with % mechanics and sits on
its own line. This page documents the directives exercised by the canonical
compile_latex path. Examples here are taken from the runnable inputs in
examples/.
Authoritative grammar
The full DSL grammar (including planned directives) lives in
dev/design_docs/02-LATEX-DSL.md. This page focuses on what the current
compile_latex pipeline consumes, so the snippets you copy actually run.
General form¶
- Directives are processed in order; later ones may reference symbols defined earlier.
- Option values may be numbers, identifiers, quoted strings, or LaTeX-escaped Greek
(
\mu,\kappa,\sigma_y).
A complete minimal input¶
% mechanics dim 3
% mechanics cell hex8
% mechanics formulation total_lagrangian
% mechanics material svk --E 200e3 --nu 0.3
% mechanics boundary fix --type dirichlet --value 0 --components 0 1 2
% mechanics boundary load --type neumann --traction "0 0 -1000"
dim — spatial dimension¶
Sets the spatial dimension (2 or 3). Affects index ranges, Voigt sizes, and element
defaults. Declare it first.
cell — element type¶
| Value | Element | Tier |
|---|---|---|
hex8 |
8-node hexahedron | MVP-stable |
hex8r |
reduced-integration Hex8 (+ hourglass control) | experimental |
hex20 |
20-node hexahedron | experimental |
tet4 |
4-node tetrahedron | experimental |
tet10 |
10-node tetrahedron | experimental |
coord — coordinate systems¶
Small-strain problems need only spatial. Large-deformation formulations
(Total/Updated Lagrangian) require both spatial and material — that is what lets
the deformation gradient F_{iI} carry a spatial index i and a material index I on
separate manifolds.
formulation — kinematic formulation¶
| Value | Meaning | Tier |
|---|---|---|
total_lagrangian |
reference-config, PK2/Green–Lagrange | MVP-stable |
updated_lagrangian |
current-config | experimental |
material — constitutive model¶
% mechanics material svk --E 200e3 --nu 0.3
% mechanics material neo_hookean --mu \mu --kappa \kappa
% mechanics material j2_power_law --E 200e3 --nu 0.3 --sigma_y0 250 --K 500 --n 0.5
The first token after material is the model name; each --key value maps a parameter
to a value or symbol. See the constitutive model catalog for
the full parameter list per model. Model names available include svk, neo_hookean,
mooney_rivlin, ogden, hgo, j2_power_law, johnson_cook, perzyna, and
lemaitre.
boundary — boundary conditions¶
% mechanics boundary fix --type dirichlet --field u --components 0 1 2 --value 0
% mechanics boundary load --type neumann --traction "0 0 -1000"
The first token names the BC. Options:
| Option | Applies to | Meaning |
|---|---|---|
--type |
all | dirichlet, neumann |
--field |
all | solution field the BC acts on (default u) |
--components |
dirichlet | constrained DOF indices, e.g. 0 1 2 |
--value |
dirichlet | prescribed value |
--traction |
neumann | traction vector as a quoted string, e.g. "0 0 -1000" |
--surface |
neumann | named surface the traction acts on |
bc vs boundary
There is also a % mechanics bc <type> ... form (e.g. bc dirichlet --boundary left
--value 0, bc body_force --field u --value "0, -rho*g"). The boundary
<name> --type ... form used in the examples is the one wired through the canonical
compile_latex path — prefer it unless you specifically need body_force.
fiber — fiber directions (anisotropic materials)¶
Declares a fiber family direction for anisotropic models such as HGO. One directive per
family; the directions become per-element field data
(FiberFieldSpec).
constitutive — auto-generate a quantity¶
% mechanics constitutive Psi --strain_energy
% mechanics constitutive S --pk2
% mechanics constitutive sigma --cauchy
Tells the engine to auto-derive the named quantity from the material/energy:
--strain_energy differentiates Ψ to stress + tangent, --pk2 produces the PK2 stress,
--cauchy push-forwards to the Cauchy stress.
field — solution fields¶
% mechanics field u --type vector --space V --order 1
% mechanics field p --type scalar --space Q --order 0
Declares solution fields. --type is scalar or vector; --order sets the default
polynomial order for codegen.
verify — verification hooks¶
Marks the problem for a verification benchmark (e.g. constant-strain patch test). The verification harness compares generated output against reference solutions.
Deriving a model from a user-written energy¶
Directives compose with ordinary LaTeX math. Write Ψ as an equation and point a
constitutive directive at it:
% mechanics constitutive Psi --strain_energy
\Psi = \frac{\mu}{2}\left(\bar{I}_1 - 3\right) + \frac{\kappa}{2}\left(J - 1\right)^2
The parser locates the equation defining \Psi, parses it to SymPy, and hands it to the
symbolic layer for auto-differentiation — giving you a user-defined constitutive
model without touching the compiler source. See
Constitutive models → user-defined energies.