Explain tier 1 kernel numeric work, tier 2 warmed assembly drivers, and tier 3
IO/UI flexibility orthogonal to the dependency-layer diagram.
- Add definitions, an allocations policy table mapped to `src/` folders, and a
short glossary tying tiers to hot-path expectations.
Spell out that SPDX tags must use native comments (`#` in code and TOML,
HTML comments in Markdown/Quarto) and call out formats like JSON that cannot
carry in-file blocks.
- Add an SPDX section with concrete examples and the strict-JSON caveat.
Explain next to the one-file workflow that message depth should follow patch
size—grouped bullets on large or multi-concern commits.
- Adds one bullet under coding rules pointing readers at `.github/prompts/commit.prompt.md`.
Introduce root-level AGENTS.md as the architecture and workflow summary for
humans and coding agents. Add docs/src/repository_layout.md as a placement
and anti-pattern reference for sources, tests, scripts, and gitignored trees.
- AGENTS.md links deep docs and states 2.0 invariants
- repository_layout.md includes .cursor/ as gitignored local tooling
Replace outdated badges and roadmap prose with the current 2.0 focus areas,
installation notes, and pointers to AGENTS.md. Rewrite CONTRIBUTING as a
concise fork/test/layer-contract checklist aligned with the repo layout.
- README: drop stale Travis/Gitter stack; document legacy module caveat
- CONTRIBUTING: remove Quarto front matter; link architecture_layers checker
Runnable 4×4×4 Hex8 linear elasticity assembly used as the Documenter/README
minimal example source of truth; returns (; ndofs, nnz_stiffness).
- Intended for @literalinclude, test/docs, and scripts/verify_docs_quickstart.jl
Reorganize API documentation with organized sections for better
navigation and discoverability.
- Add structured sections: Elements, Physics, Fields, Formulations,
Materials, Mesh, Topology, Basis Functions, DOF System, Solvers
- Include key types and functions in each section
- Change title from "API documentation" to "API Reference"
- Keep index at the end for complete reference
Simplify documentation build script to generate API docs only.
Remove legacy code for generating examples, packages, and guides.
- Replace complex build system with simple Documenter.jl setup
- Generate markdown output for Quarto integration
- Build directly to juliafem.github.io/api/ directory
- Remove functions: copy_docs, add_page!, generate_* functions
- Use DocumenterMarkdown format instead of HTML
Remove documentation files from docs/ directory as they have
been moved to juliafem.github.io/ according to the website
structure. Manual documentation now lives in the website
repository directly.
Removed files:
- docs/book/adr-004-integration-points-api.md
- docs/book/adr-005-element-integration-point-indices.md
- docs/book/deformation_gradient_implementation.md
- docs/book/design/backend_transparent_architecture.md
- docs/book/design/gmres_algorithm_gpu.md
- docs/book/design/matrix_free_dirichlet_bc.md
- docs/book/element_assembly_implementation.md
- docs/book/linear_elastic_implementation.md
- docs/book/migration-guide-basis-api.md
- docs/book/neo_hookean_implementation.md
- docs/book/perfect_plasticity_implementation.md
Remove docs/src/book directory as it has been moved to another
repository
- Remove docs/src/book/ directory and all contents
- 40 files removed including documentation and design docs
Major revision of ADR-002 based on implementation experience.
Decision change:
- OLD (Nov 9): Topology without node count (pure geometry)
- NEW (Nov 13): Topology with node count type parameter
Rationale:
Node count comes from MESH FILES, not from basis choice. When reading
Abaqus .inp, Code Aster .med, or GMSH .msh files, the mesh explicitly
specifies node count in element connectivity:
- Hex element (1,2,...,8) → 8 nodes
- Hex element (1,2,...,20) → 20 nodes
- Hex element (1,2,...,27) → 27 nodes
The mesh reader knows node count BEFORE basis functions are selected.
Therefore, topology must include node count: Hexahedron{N}.
New design:
struct Hexahedron{N} <: AbstractTopology end
const Hex8 = Hexahedron{8}
const Hex20 = Hexahedron{20}
This maintains type stability (N known at compile time) while
acknowledging that N originates from mesh data, not basis choice.
Supersedes: ADR-002 (November 9, 2025)
- Complete cantilever beam example from mesh to visualization
- Gmsh mesh creation with physical groups for BCs
- Material definition (Young's modulus and Poisson's ratio)
- Dirichlet (fixed) and Neumann (pressure) boundary conditions
- ElasticityPhysics problem setup and solve!() call
- Results visualization with stress and displacement
- 361 lines: Step-by-step user tutorial for beginners
- 4 design documents for GPU implementation (2588 lines total)
- gpu_physics_architecture.md: Physics{Elasticity} GPU-first design
- gpu_cpu_backend_architecture.md: Backend selection and dispatch
- gpu_cpu_migration_guide.md: Migration from old API to new
- gpu_elasticity_refactoring.md: Complete refactoring strategy
- Zero CPU-GPU transfer during solve, matrix-free CG
- Elements store geometry, no mesh dependency
- Breaking changes allowed for GPU performance
- Design principle: users never see CPU/GPU differences
- Three-layer architecture: User API / Backend Abstraction / Implementations
- Auto() backend selection based on hardware availability
- Physics{ElasticityPhysicsType} as single problem type
- Internal conversion between CPU arrays and GPU arrays
- solve!() with automatic dispatch to CPU or GPU backend
- 611 lines: Complete architecture design proposal
- get_basis_functions() and get_basis_derivatives() recommended
- Separation of concerns: topology and basis as separate parameters
- Side-by-side examples for all common element types
- Complete assembly example showing migration path
- Type-stable implementation with no performance penalty
- 302 lines: Comprehensive migration documentation
- Alternative to element-by-element assembly for GPU/matrix-free
- Node-by-node loop eliminates atomic operations on GPU
- Spider pattern: nodes couple with 10-30 neighbors not all N
- NodeToElementsMap: inverse connectivity (node → elements)
- get_node_spider() finds coupled nodes for sparse stiffness
- NodalStiffnessContribution: 3×3 blocks per node
- 307 lines: Experimental architecture with working prototype
- Compressible Neo-Hookean strain energy function
- Automatic differentiation for stress and tangent computation
- Dual constructor: Lamé (μ,λ) or engineering (E,ν)
- Total Lagrangian formulation with 2nd Piola-Kirchhoff stress
- Zero-allocation AD via Tensors.jl
- When to use: rubber, large deformation, contact mechanics
- 571 lines: Complete AD-based material model documentation
- Complete mathematical foundation of Hooke's law in tensor form
- Lamé parameters derived from Young's modulus and Poisson's ratio
- compute_stress() implementation achieving ~25 ns execution
- Fourth-order elasticity tensor with symmetries
- Zero-allocation SIMD-optimized implementation
- Physical constraints and thermodynamic admissibility
- 736 lines: Authoritative implementation documentation
- Reference implementation of element-by-element assembly
- ElementAssemblyData and ElementContribution data structures
- Sparse matrix assembly in COO then CSC format
- scatter_to_global!() adds local to global system
- Penalty method for Dirichlet BCs
- Matrix-vector product interface for GMRES
- 479 lines: Complete documentation with examples and tests
- Mathematical derivation of F = I + ∇u for finite strain
- Zero-allocation implementation achieving 34 ns median
- LLVM IR analysis confirms 0 heap allocations
- 92 SIMD vector operations detected
- Small strain vs finite strain formulations
- Comparison with old deprecated eval_dbasis!() API
- 502 lines: Complete performance analysis with benchmarks
Document decision to store integration point indices instead of data in Element struct.
Key rationale: Elements should store relationships (indices), not data, for memory
efficiency and consistency with node connectivity pattern. Aligns with nodal assembly
approach and GPU-friendly architecture.
Architectural Decision Record documenting design of integration points
API for high-performance finite element assembly.
Decision: Compile-time function returning tuple of (weight, Vec{D})
matching eval_basis! zero-cost abstraction pattern.
Problem context:
- OLD API: Runtime dispatch with mutable struct containing Dict
- Performance penalty: ~50× slower due to type instability
- Allocations: New struct created every query
- Impact: Millions of calls during assembly
Solution properties:
- Compile-time generation (fully inlined)
- Vec{D} from Tensors.jl for FEM math
- Zero allocation (tuples, stack-only)
- Type-stable (all types known at compile time)
- GPU compatible (no heap allocations)
API signature:
get_gauss_points!(::Type{Topology}, ::Type{Gauss{order}})
→ NTuple{N, Tuple{Float64, Vec{D}}}
Alternatives rejected:
- Plain tuples (less convenient for FEM math)
- Store in element (overhead, less flexible)
- Global constants (not composable)
- Runtime dispatch (type-unstable, slow)
Status: Accepted, implemented in src/integration/ (193 lines)
- Delete docs/blog/ directory (files moved to docs/src/book/blog/)
- Delete docs/design/ directory (files moved to docs/src/book/design/)
- Cleanup after three-tier documentation reorganization
- Old locations no longer needed after migration to docs/src/ structure
- Relocate docs/contributor/ to docs/src/contributor/
- Add three GPU quickstart guides (renamed from UPPERCASE to snake_case):
- gpu_elasticity_quickstart.md
- gpu_nodal_assembly_quickstart.md
- quick_reference_gpu.md
- Part of three-tier docs reorganization following Documenter.jl standard
- All files now under docs/src/ for automatic rendering
- Relocate docs/blog/immutability_performance.md to docs/src/book/blog/
- Comprehensive guide on immutable material models with Tensors.jl
- Covers LinearElastic, NeoHookean, PerfectPlasticity implementations
- Includes full benchmarks: 5× speedup for linear, 21× for plasticity
- Zero allocation performance validated
- Part of three-tier docs reorganization under standard docs/src/ structure
- Relocate docs/book/README.md to docs/src/book/README.md
- Follows standard Julia documentation structure where all source files live under docs/src/
- File contains YAML header and book philosophy/structure overview
- Part of three-tier documentation reorganization (user/contributor/book)
- Converted header metadata to YAML frontmatter format
- Added categories and tags for documentation site compatibility
- Preserved all existing content (only header format changed)
- Status: IMPLEMENTED, Phase: Phase 1B
- Links to benchmark: element_immutability_benchmark.jl
New 139-line quick-reference article covering:
- Side-by-side code comparisons (mutable vs immutable)
- 130x speedup summary with key metrics
- Type stability explanation with timing breakdown
- Compiler optimization differences
- Real-world impact table (2.4s → 0.02s)
- Mental model shift (1990s C++ → 2025 modern compilers)
- Quick command to run benchmark
- Links to full article for details
Jukka Aho