mirror of
https://github.com/JuliaFEM/JuliaFEM.jl.git
synced 2026-09-24 11:16:47 +00:00
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
This commit is contained in:
Jukka Aho
@@ -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.
|
||||
Reference in New Issue
Block a user