JuliaFEM.jl: Instructions file for Codex

AGENTS.md: Quick guide for AI coding agents working on JuliaFEM.jl

This file is the entry point for any AI agent (Cursor, Copilot, Codex, …) that opens this repository. Read it first; then jump to the linked, authoritative documents for details.

The package version is 0.x (see Project.toml); the repository is in the middle of a deliberate architectural reset toward a stable 1.0 (monorepo, type-stable, zero-allocation, GPU-ready). Many older files, README.md sections, and design notes still describe the previous API. When in doubt, trust the code and this file over older READMEs.

---

1. What this project is

JuliaFEM.jl is an open-source finite element framework written in Julia. It is being rebuilt from first principles around four ideas:

1. Ciarlet's triple as a type. Element{K, P, S, N} encodes the reference domain K, polynomial space P, DOF specification S and total DOF count N purely at the type level. The element instance carries only id and dof_indices::NTuple{N, UInt64}.
2. Element as template, not bag of fields. Heavy structural information (which local DOF is which field/entity/component) is produced by @generated functions over the element type, so the compiler can fold it into constants. The canonical example is local_dof_layout(::Type{Element{K,P,S,N}}) returning an NTuple{N, DOFLayoutEntry}.
3. Microkernels. Assembly is built from small evaluate-style functions that compute a single scalar (or block) and are dispatched at compile time. No Dict, no Any, no boxing.
4. Zero-allocation hot paths. Pre-allocated caches plus trait-based material dispatch let the inner loops run with zero GC allocation sites in the optimized LLVM IR.

The long-term vision (parallelism, GPU, Newton–Krylov, multiphysics, billions of DOF) is documented in llm/vision/vision_2.0.md. The filename is historical only; version numbering here is 0.x toward a stable 1.0, and that note captures stretch goals beyond the first stable release rather than a separate product line.