Troubleshooting
Missing regions or wrong dimensions
Check that every material, Ω, Γ and support group exists in the current Gmsh model. Structured helpers document their generated names. Do not reuse a field descriptor after replacing its model/mesh; reconstruct descriptors and matrix patterns for the new mesh.
Singular or indefinite systems
Check essential constraints, rigid modes, disconnected regions and a pressure reference in mixed incompressible problems. Symmetric(K) declares symmetry; it does not make an indefinite matrix positive definite. Use a suitable direct solver for saddle-point systems before considering specialized iteration.
Field shape or coefficient errors
Inspect P.dim, P.pdim, isNodal(f), isElementwise(f) and column counts. A 2D tensor field still stores nine components. Match element supports and component ordering before combining fields. Some assembly paths require nodal scalar coefficients; convert explicitly where required by the method.
Local loads and constraints
With coordSys, ordinary RHS components and prescribed values are local. Wrap Cartesian loads in Global(f). In mixed systems bind each essential condition with field=P. See coordinate systems.
Missing optional solver/material packages
Load IterativeSolvers for CG/GMRES; automatic incomplete Cholesky/ILU requires Preconditioners/IncompleteLU. ARPACK eigen solves require Arpack and energy differentiation requires Tensors. No optional package is loaded implicitly. Existing installed extensions become active after using them.
Eigenvalue selection
shift is a one-sided real lower bound; ARPACK sigma is a shift-invert target and may select modes from both sides. They cannot be combined. Use output=:raw for complete complex eigenpairs, or part=:both for real/imaginary fields. Do not interpret every eigenvalue as a vibration frequency.
Known interface inconsistencies
See the public API audit for exported undefined names, Adv(P), and tangent component-order compatibility. These are documented limitations; this documentation update does not change executable source.