docs: Reorganize documentation into three-tier structure

**Three Manuals for Three Audiences:** 1. **User Manual** (docs/user/) - "Just Get It Done" - For end users, engineers, students - Simple, practical, step-by-step - Quick start, tutorials, examples, troubleshooting - Philosophy: Show me how to solve my problem 2. **Contributor Manual** (docs/contributor/) - "Show Me the Code" - For developers, contributors, advanced users - Technical, detailed, design rationale - Testing, architecture, performance, CI/CD - Philosophy: Explain HOW and WHY 3. **The JuliaFEM Book** (docs/book/) - "Let Me Show You How I Think" - For researchers, theory nerds, and Jukka - Comprehensive, educational, opinionated, personal - Math foundations, design philosophy, history, research - Philosophy: Mix theory, code, and personal experience **Reorganization:** - Moved: TESTING_PHILOSOPHY.md → contributor/testing_philosophy.md - Moved: STATUS.md → contributor/status.md - Moved: TEST_FIXES_NEEDED.md → contributor/test_fixes_needed.md - Moved: lagrange_basis_functions.md → book/lagrange_basis_functions.md - Moved: benchmarks/ → book/benchmarks/ - Created: docs/README.md (main index explaining structure) - Created: README.md in each section explaining audience and contents - Updated: All references in scripts and source files **Naming:** All docs now lowercase (testing_philosophy not TESTING_PHILOSOPHY) **Benefits:** - Clear separation of concerns - Users don't get overwhelmed with implementation details - Contributors get technical depth - Book preserves deep theory and personal insights - Each manual optimized for its audience **Next:** Populate each section with appropriate content
2026-09-23 02:59:52 +00:00 · 2025-11-09 04:38:28 +02:00
parent 5141fd6de5
commit 626266c990
12 changed files with 298 additions and 5 deletions
@@ -0,0 +1,82 @@
+# The JuliaFEM Book
+
+**Audience:** Advanced researchers, theory nerds, those who want to understand the "why" and "how" at a deep level. And Jukka.
+
+This is the **JuliaFEM Bible** - a comprehensive manual mixing theory, philosophy, software design, and personal experience. It's educational, opinionated, and unapologetically deep.
+
+## What's Here
+
+- **Mathematical Foundations:** Lagrange basis functions, weak forms, contact mechanics
+- **Design Philosophy:** Why JuliaFEM exists, what problems it solves (and doesn't)
+- **Technical Vision:** Strategic mistakes from 2015-2019, lessons learned
+- **Research Directions:** Experimental ideas (nodal assembly, matrix-free, etc.)
+- **Personal Notes:** The journey, the failures, the "aha!" moments
+- **Theory + Code:** How mathematics becomes software
+
+## What's NOT Here
+
+- "How do I install?" (see `docs/user/`)
+- "How do I add a feature?" (see `docs/contributor/`)
+- Short answers (everything here is DEEP)
+
+## Philosophy
+
+**"Let me show you how I think about FEM."**
+
+This is:
+- **Educational:** Teach FEM through implementation
+- **Personal:** Written in Jukka's voice, reflecting 8+ years of experience
+- **Opinionated:** Strong views on what works and what doesn't
+- **Comprehensive:** From first principles to cutting-edge research
+- **Honest:** Documents failures as much as successes
+
+We assume you:
+- Love mathematics AND programming
+- Want to understand WHY, not just HOW
+- Have time to read deeply
+- Are curious about unconventional approaches
+- Might be me, 5 years from now, trying to remember why I did this
+
+## Structure
+
+### Part I: Foundations
+- Finite Element Method (brief review)
+- Lagrange Basis Functions (deep dive)
+- Assembly and Solving
+- Contact Mechanics
+
+### Part II: Software Design
+- Type Stability and Performance
+- Zero-Allocation Design
+- Immutability and Composition
+- Field System Architecture
+
+### Part III: History and Vision
+- Strategic Mistakes (2015-2019)
+- Why JuliaFEM is Different
+- Contact Mechanics Focus
+- Laboratory Philosophy
+
+### Part IV: Research
+- Nodal Assembly (experimental)
+- Matrix-Free Methods
+- Automatic Differentiation
+- GPU Acceleration
+
+### Part V: The Journey
+- Personal Reflections
+- Lessons Learned
+- Future Directions
+- Open Questions
+
+## Reading Guide
+
+- **For Theory:** Start with Part I
+- **For Design Rationale:** Start with Part II
+- **For History:** Start with Part III
+- **For Research Ideas:** Start with Part IV
+- **For Philosophy:** Read Part V first, then everything else
+
+---
+
+**Start here:** [Mathematical Foundations](foundations.md) | [Strategic Mistakes](strategic_mistakes.md) | [Why JuliaFEM?](philosophy.md)
@@ -0,0 +1,213 @@
+# Shape Function Derivatives: Hand-Calculated vs Automatic Differentiation
+
+**Date:** November 9, 2025  
+**Author:** JuliaFEM Development Team  
+**Context:** Major zero-allocation refactoring (immutable Element, tuple-based APIs)
+
+## The Question
+
+Is it worth calculating shape function derivatives by hand, or should we just use Automatic Differentiation (AD)?
+
+This is a fundamental design decision for JuliaFEM. Traditionally, FEM codes pre-calculate derivatives analytically and hard-code them. But with modern Julia AD tools (ForwardDiff.jl, built into Tensors.jl), we might get comparable performance with zero maintenance burden.
+
+**We benchmark Tet10** (10-node tetrahedral element) - one of the most important 3D elements.
+
+## Background
+
+### Traditional Approach (Hand-Calculated)
+```julia
+# Shape functions for Tet10
+N1(u,v,w) = (1-u-v-w)*(1-2*u-2*v-2*w)
+N2(u,v,w) = u*(2*u-1)
+# ... 8 more functions
+
+# Derivatives (calculated by hand, error-prone)
+dN1_du(u,v,w) = 4*u + 4*v + 4*w - 3
+dN1_dv(u,v,w) = 4*u + 4*v + 4*w - 3
+# ... many more derivatives
+```
+
+**Pros:** Potentially fastest (pre-computed)  
+**Cons:** Error-prone, maintenance burden, inflexible
+
+### AD Approach (Tensors.jl / ForwardDiff.jl)
+```julia
+# Just shape functions
+N1(ξ) = (1-ξ[1]-ξ[2]-ξ[3])*(1-2*ξ[1]-2*ξ[2]-2*ξ[3])
+# ... 9 more functions
+
+# Derivatives computed automatically
+using ForwardDiff
+dN = ForwardDiff.gradient(N1, ξ)
+```
+
+**Pros:** Zero maintenance, no human errors, flexible  
+**Cons:** Runtime overhead?
+
+## Implementation Strategy
+
+We'll implement **three versions** of Tet10 basis evaluation:
+
+1. **Manual**: Hand-calculated derivatives (current JuliaFEM approach)
+2. **AD-Naive**: Compute gradients with ForwardDiff at each call
+3. **AD-Optimized**: Use dual numbers efficiently with Tensors.jl
+
+Then we benchmark the hottest operation: **evaluating all shape functions and derivatives at an integration point**.
+
+## Benchmark Setup
+
+```julia
+using BenchmarkTools
+using ForwardDiff
+using Tensors
+using StaticArrays
+
+# Integration point (ξ, η, ζ) in reference element
+const ξ_test = Vec(0.25, 0.25, 0.25)
+
+# Allocate output buffers for fair comparison
+const N_buffer = zeros(10)
+const dN_buffer = [zero(Vec{3}) for _ in 1:10]
+```
+
+## Results
+
+**Benchmarks run on:** AMD Ryzen 9 / Julia 1.12.1 / November 9, 2025
+
+| Method | Time (ns) | Allocations | Relative Speed |
+|--------|-----------|-------------|----------------|
+| Manual | **8.7** | 0 | 1.0× (baseline) |
+| AD (Tensors.jl) | **268.1** | 0 | **30.7×** slower |
+
+### Key Findings
+
+1. **Both methods achieve zero allocations** ✅
+   - Tensors.jl gradient() is allocation-free
+   - No performance penalty from GC pressure
+
+2. **AD has 30× compute overhead** ❌
+   - Manual: 8.7 nanoseconds
+   - AD: 268 nanoseconds
+   - This is significant in assembly loops (millions of evaluations)
+
+3. **Why is AD so much slower?**
+   - Dual number arithmetic: Every operation becomes a tuple of (value, gradient)
+   - Chain rule evaluation: Must track derivatives through all operations
+   - 10 basis functions × 3 gradient components = 30 derivative evaluations
+   - Cannot fully optimize away the dual number overhead
+
+4. **Assembly loop impact:**
+   - Typical problem: 100K elements × 4 integration points × 100 Newton iterations
+   - Extra cost: (268 - 8.7) ns × 40M calls = **10 seconds per solve**
+   - For large problems, this adds up quickly
+
+## Analysis
+
+### Performance Factors
+
+1. **Compiler Optimization**: Both approaches are fully inlined and optimized
+2. **Dual Number Overhead**: ~30× cost - every arithmetic operation becomes dual number arithmetic
+3. **SIMD**: Manual derivatives can be better vectorized by LLVM
+4. **Constant Propagation**: Both benefit equally
+
+### Memory Considerations
+
+✅ **Both achieve zero allocations** - Tensors.jl gradient() is very well optimized for memory
+
+### Decision Tree
+
+**For assembly loops (hot path):**
+- ❌ **Do NOT use AD** - 30× overhead is unacceptable
+- ✅ **Use hand-coded derivatives** - keep them for Tet10, Hex8, Quad4, Tri3
+- ✅ **Verify with AD in unit tests** - catch human errors
+
+**For prototyping/research:**
+- ✅ **Use AD freely** - development velocity matters more
+- ✅ **Profile before optimizing** - maybe it's not the bottleneck
+
+**For rare elements:**
+- ⚠️ **Consider symbolic generation** - SymPy/Symbolics.jl once, use forever
+- ✅ **Unit test against AD** - verify correctness
+
+**For exotic bases (NURBS, splines):**
+- ✅ **Must use AD** - hand derivatives are intractable
+- ⚠️ **Accept performance cost** - no alternative
+
+## Recommendations
+
+### Short Term (Current JuliaFEM)
+
+**Keep manual derivatives for common elements:**
+- Tet4, Tet10 (3D volume)
+- Hex8, Hex20, Hex27 (3D volume)
+- Quad4, Quad8, Quad9 (2D, shells)
+- Tri3, Tri6 (2D, shells)
+- Seg2, Seg3 (1D, beams)
+
+These elements cover **>95% of real-world usage**. The 30× speedup justifies maintenance.
+
+**Use AD for everything else:**
+- Pyramid elements (rare)
+- Wedge elements (rare)
+- Research elements
+- NURBS-based isogeometric analysis
+
+### Long Term (v2.0+)
+
+**Symbolic derivative generation:**
+```julia
+using Symbolics
+
+# Define basis symbolically once
+@variables ξ η ζ
+N1_sym = (1 - ξ - η - ζ) * (2*(1 - ξ - η - ζ) - 1)
+
+# Generate Julia code for derivatives
+dN1_dξ = Symbolics.derivative(N1_sym, ξ)
+code = Symbolics.build_function(dN1_dξ, [ξ, η, ζ])
+
+# Store in basis/generated/Tet10.jl
+# Zero human error, zero AD overhead!
+```
+
+**Benefits:**
+- Hand-level performance
+- Zero human errors (symbolic math is exact)
+- Easy to add new elements (just define basis symbolically)
+- Unit test against AD to verify symbolic engine
+
+## Conclusion
+
+**The data is clear:** For JuliaFEM's performance-critical code (element assembly), **manual derivatives are 30× faster** than AD.
+
+**Recommended strategy:**
+1. ✅ Keep hand-coded derivatives for common elements (Tet10, Hex8, Quad4, etc.)
+2. ✅ Use AD for prototyping and rare elements
+3. ✅ Add unit tests comparing manual vs AD (catch human errors)
+4. 🎯 Future: Generate derivatives symbolically (best of both worlds)
+
+**Why not AD everywhere?**
+- Assembly loops: millions of evaluations per solve
+- 30× overhead = 10+ seconds per solve on realistic problems
+- Users will notice the performance difference
+
+**Why not abandon AD?**
+- Excellent for prototyping
+- Required for exotic bases (NURBS)
+- Perfect for unit testing manual derivatives
+- Zero allocations makes it usable in inner loops (if needed)
+
+The zero-allocation achievement is impressive, but compute overhead dominates. **Performance-critical code still needs hand-tuned derivatives.**
+
+---
+
+## References
+
+1. ForwardDiff.jl documentation
+2. Tensors.jl gradient() implementation
+3. "Automatic Differentiation in FEM" - various papers
+4. JuliaFEM Issue #XXX: Zero-allocation refactoring
+
+## Appendix: Code Listings
+
+See `benchmarks/tet10_derivatives_benchmark.jl` for full implementations.
@@ -0,0 +1,226 @@
+# Lagrange Basis Functions in JuliaFEM
+
+**Date:** November 9, 2025  
+**Author:** JuliaFEM Development Team
+
+## Introduction
+
+Lagrange basis functions are the foundation of the Finite Element Method. They provide a systematic way to construct polynomial interpolation functions that satisfy the **Kronecker delta property**: the basis function associated with node $i$ equals 1 at that node and 0 at all other nodes.
+
+$$N_i(\mathbf{x}_j) = \delta_{ij} = \begin{cases} 1 & \text{if } i = j \\ 0 & \text{if } i \neq j \end{cases}$$
+
+This property makes it trivial to interpolate field values: $u(\mathbf{x}) = \sum_i u_i N_i(\mathbf{x})$ where $u_i$ are nodal values.
+
+## Mathematical Foundation
+
+### Vandermonde Matrix Method
+
+Given:
+
+- $n$ nodes with coordinates $\{\mathbf{x}_1, \mathbf{x}_2, \ldots, \mathbf{x}_n\}$ in reference element
+- A polynomial basis (ansatz) $\{p_1(\mathbf{x}), p_2(\mathbf{x}), \ldots, p_n(\mathbf{x})\}$
+
+We seek coefficients $\alpha_{ij}$ such that:
+
+$$N_i(\mathbf{x}) = \sum_{j=1}^{n} \alpha_{ij} p_j(\mathbf{x})$$
+
+The Kronecker delta property gives us:
+
+$$N_i(\mathbf{x}_k) = \sum_{j=1}^{n} \alpha_{ij} p_j(\mathbf{x}_k) = \delta_{ik}$$
+
+This is a linear system: $\mathbf{V} \boldsymbol{\alpha}_i = \mathbf{e}_i$
+
+Where the **Vandermonde matrix** is:
+
+$$V_{kj} = p_j(\mathbf{x}_k)$$
+
+And $\mathbf{e}_i$ is the $i$-th unit vector.
+
+### Example: 1D Linear Element (Seg2)
+
+**Ansatz:** $p(\xi) = 1 + \xi$ (complete linear polynomial)
+
+**Nodes:** $\xi_1 = 0$, $\xi_2 = 1$
+
+**Vandermonde matrix:**
+
+$$\mathbf{V} = \begin{bmatrix}
+p_1(\xi_1) & p_2(\xi_1) \\
+p_1(\xi_2) & p_2(\xi_2)
+\end{bmatrix} = \begin{bmatrix}
+1 & 0 \\
+1 & 1
+\end{bmatrix}$$
+
+**Solve for $N_1$:** $\mathbf{V} \boldsymbol{\alpha}_1 = [1, 0]^T$
+
+$$\begin{bmatrix} 1 & 0 \\ 1 & 1 \end{bmatrix} \begin{bmatrix} \alpha_{11} \\ \alpha_{12} \end{bmatrix} = \begin{bmatrix} 1 \\ 0 \end{bmatrix}$$
+
+Solution: $\alpha_{11} = 1$, $\alpha_{12} = -1$
+
+Therefore: $N_1(\xi) = 1 \cdot 1 + (-1) \cdot \xi = 1 - \xi$ ✓
+
+**Solve for $N_2$:** $\mathbf{V} \boldsymbol{\alpha}_2 = [0, 1]^T$
+
+Solution: $\alpha_{21} = 0$, $\alpha_{22} = 1$
+
+Therefore: $N_2(\xi) = 0 \cdot 1 + 1 \cdot \xi = \xi$ ✓
+
+**Verification:**
+- $N_1(0) = 1$, $N_1(1) = 0$ ✓
+- $N_2(0) = 0$, $N_2(1) = 1$ ✓
+- $N_1(\xi) + N_2(\xi) = 1$ (partition of unity) ✓
+
+## Polynomial Completeness
+
+The ansatz polynomial must be **complete** to the desired order:
+
+| Order | 1D | 2D | 3D | Nodes Required |
+|-------|----|----|-----|----------------|
+| Linear | $1 + \xi$ | $1 + \xi + \eta$ | $1 + \xi + \eta + \zeta$ | $d+1$ |
+| Quadratic | $1 + \xi + \xi^2$ | $1 + \xi + \eta + \xi^2 + \xi\eta + \eta^2$ | ... | $(d+1)(d+2)/2$ |
+
+**Example for 2D Triangle (Tri3):**
+
+Ansatz: $p(\xi, \eta) = 1 + \xi + \eta$ (complete linear in 2D)
+
+This is the **minimal** complete polynomial for 3 nodes.
+
+## Implementation in JuliaFEM
+
+### Automatic Generation Process
+
+```julia
+# 1. Define element geometry
+coords = [(0.0, 0.0), (1.0, 0.0), (0.0, 1.0)]  # Tri3 nodes
+
+# 2. Define ansatz polynomial
+ansatz = :(1 + u + v)  # Complete linear in 2D
+
+# 3. Build Vandermonde matrix
+V[i,j] = eval_polynomial_term(ansatz_terms[j], coords[i])
+
+# 4. For each node i:
+coeffs = V \ e_i  # Solve linear system
+N_i = sum(coeffs[j] * ansatz_terms[j])  # Construct basis function
+
+# 5. Symbolic differentiation
+∂N_i/∂ξ = differentiate(N_i, :u)
+∂N_i/∂η = differentiate(N_i, :v)
+```
+
+### Why This Works
+
+1. **Completeness:** Ansatz spans full polynomial space of given order
+2. **Linear Independence:** Vandermonde matrix is non-singular for distinct nodes
+3. **Interpolation Property:** Follows directly from $\mathbf{V} \boldsymbol{\alpha}_i = \mathbf{e}_i$
+
+### Derivatives
+
+Once we have $N_i(\xi, \eta, \zeta)$ symbolically, derivatives are straightforward:
+
+$$\frac{\partial N_i}{\partial \xi}, \frac{\partial N_i}{\partial \eta}, \frac{\partial N_i}{\partial \zeta}$$
+
+These are computed **once** symbolically, then **pre-compiled** into efficient Julia code.
+
+## Standard Lagrange Elements in JuliaFEM
+
+### 1D Elements
+- **Seg2**: Linear (2 nodes)
+- **Seg3**: Quadratic (3 nodes, mid-edge node)
+
+### 2D Elements
+- **Tri3**: Linear triangle (3 corner nodes)
+- **Tri6**: Quadratic triangle (6 nodes: 3 corners + 3 mid-edges)
+- **Quad4**: Bilinear quadrilateral (4 corner nodes)
+- **Quad8**: Serendipity quadrilateral (8 nodes: 4 corners + 4 mid-edges)
+- **Quad9**: Biquadratic quadrilateral (9 nodes: 4 corners + 4 mid-edges + 1 center)
+
+### 3D Elements
+- **Tet4**: Linear tetrahedron (4 corner nodes)
+- **Tet10**: Quadratic tetrahedron (10 nodes: 4 corners + 6 mid-edges)
+- **Hex8**: Trilinear hexahedron (8 corner nodes)
+- **Hex20**: Serendipity hexahedron (20 nodes: 8 corners + 12 mid-edges)
+- **Hex27**: Triquadratic hexahedron (27 nodes: full tensor product)
+- **Pyr5**: Linear pyramid (5 nodes)
+- **Wedge6**: Linear wedge/prism (6 nodes)
+- **Wedge15**: Quadratic wedge (15 nodes)
+
+## Pre-Generation vs Runtime Generation
+
+### Historical Approach (JuliaFEM ≤ 0.5.1)
+
+```julia
+# At package load time:
+create_basis_and_eval(:Tet10, "...", coords, ansatz)
+# - Builds Vandermonde matrix
+# - Solves n linear systems
+# - Symbolic differentiation
+# - Simplification
+# - Code generation with eval()
+# Result: __precompile__(false) - slow loading
+```
+
+**Problems:**
+- ❌ Symbolic math every package load (100+ ms)
+- ❌ Cannot precompile (`eval()` at module scope)
+- ❌ Opaque code generation
+- ❌ Hard to debug
+
+### Modern Approach (JuliaFEM ≥ 1.0)
+
+```julia
+# Once, during development:
+scripts/generate_lagrange_basis.jl
+# - Computes all bases symbolically
+# - Writes clean Julia code to src/basis/lagrange_generated.jl
+
+# At package load time:
+include("basis/lagrange_generated.jl")
+# - Just parses pre-written Julia code
+# - Fully precompilable
+# - Zero symbolic computation
+```
+
+**Benefits:**
+- ✅ Instant package loading
+- ✅ Full precompilation
+- ✅ Readable generated code
+- ✅ Easy to debug
+- ✅ Version controlled (can review changes)
+
+## Numerical Stability
+
+### Vandermonde Matrix Conditioning
+
+The Vandermonde matrix can be ill-conditioned for:
+- High-order polynomials ($p > 5$)
+- Poorly distributed nodes
+- Reference elements far from unit cube/simplex
+
+**JuliaFEM's approach:**
+- Use canonical reference elements (unit cube $[-1,1]^d$ or unit simplex)
+- Lagrange elements rarely exceed order 3 in practice
+- For high-order: Consider hierarchical bases (not Lagrange)
+
+### Verification
+
+Generated basis functions are verified by:
+1. **Kronecker delta property:** $N_i(\mathbf{x}_j) = \delta_{ij}$
+2. **Partition of unity:** $\sum_i N_i(\mathbf{x}) = 1$ everywhere
+3. **Derivative correctness:** Compare symbolic vs AD
+
+See `test/test_basis_functions.jl` for comprehensive tests.
+
+## References
+
+1. Hughes, T.J.R., "The Finite Element Method: Linear Static and Dynamic Finite Element Analysis", Dover, 2000
+2. Zienkiewicz, O.C. and Taylor, R.L., "The Finite Element Method", Volumes 1-3, Butterworth-Heinemann, 2000
+3. Szabó, B. and Babuška, I., "Finite Element Analysis", Wiley, 1991
+
+## See Also
+
+- `scripts/generate_lagrange_basis.jl` - Generation script
+- `src/basis/lagrange_generated.jl` - Generated code (do not edit manually)
+- `src/basis/lagrange_generator.jl` - Generator functions (symbolic engine)
+- `benchmarks/tet10_derivatives_benchmark.jl` - Performance analysis (manual vs AD)