mirror of
https://github.com/JuliaFEM/JuliaFEM.jl.git
synced 2026-09-09 20:43:33 +00:00
Jukka Aho
4809fe1633
Create 1114-line design document exploring type-stable field storage to eliminate
Dict{String,Any} performance penalty from JuliaFEM v0.5.1.
Executive summary (lines 16-34):
- Measured results: 9-92× speedup over Dict, zero allocations in hot paths
- Constant field: 19.2ns → 2.1ns (9× faster, 0 allocs)
- Nodal field: 262ns, 3 allocs → 6.5ns, 0 allocs (40× faster)
- Cached interpolation: 2.6μs, 50 allocs → 53ns, 0 allocs (49× faster)
- Assembly (1000 elem): 109μs, 4000 allocs → 1.2μs, 0 allocs (92× faster)
- Type stability enables GPU execution and efficient MPI
- Validation: benchmarks/field_storage_comparison.jl
Problem analysis (lines 36-90):
- v0.5.1 Dict{String,Any} causes type instability
- Runtime dispatch overhead: ~50ns per access
- Interpolation: 127 allocations from type conversions
- Root cause: Any type prevents compiler optimization
- Impact: 100× slower than type-stable equivalent
Design constraints (lines 92-158):
1. Type stability - Julia must infer types at compile time
2. Zero allocations in hot paths (assembly loop critical)
3. Immutability for thread-safety by default
4. Preserve interpolation philosophy (nodal → Gauss points)
5. Element sets share properties (not per-element)
Solution 1: NamedTuple + Typed Fields (lines 160-456) - RECOMMENDED
- Field types: ConstantField{T}, NodalField{T}, ElementField{T,N}, TimeField{T,F}
- Zero-size constants, Matrix{T} for nodal, SVector for DG elements
- Accessor functions: value(f::ConstantField), value(f::NodalField, node_ids)
- Benchmarks: 9× (constant), 40× (nodal), 59× (interp), 49× (cached), 92× (assembly)
- Complete implementations with @inline, @view for zero allocation
- InterpolationCache struct for zero-allocation hot path
Solution 2: Macro-Generated Structs (lines 458-611)
- @fields macro for generating typed field containers
- Explicit field definitions with @constant, @nodal, @element, @temporal
- Generated constructors, accessors, validation
- Pros: Self-documenting, optimal code, extensible
- Cons: More complex, maintenance burden
- Decision: Start with NamedTuple, add macro if needed
Solution 3: Element Set Architecture (lines 613-774)
- ElementSet{E,F} groups elements sharing common properties
- Fields belong to sets, not individual elements
- Matches mesh organization and user mental model
- Zero-allocation assembly with shared fields
- Benchmark: 10× faster than per-element Dict, near-zero allocations
Implementation strategy (lines 776-940):
- Phase 1: Prototype and benchmark (week 1)
* BenchmarkTools suite with performance assertions
* Target: <5ns field access, <100ns interpolation, 0 allocs assembly
- Phase 2: Integration (weeks 2-3)
* Update Element struct (remove fields, belongs to ElementSet)
* Update Problem struct (vector of ElementSets)
* Update assembly functions
- Phase 3: Migration and deprecation (week 4)
* Deprecation warnings for old API
* Update all examples to typed fields
* Performance verification
- Phase 4: Documentation (week 5)
* Architecture docs, tutorials, migration guide
Validation checklist (lines 942-974):
- Field type prototypes, access benchmarks (<5ns, 0 allocs)
- Interpolation benchmarks (<100ns, 0 allocs)
- Assembly benchmarks (0 allocs in loop)
- Threading tests, DG tests, vs v0.5.1 comparison (10× faster)
- Update Element/Problem structs, implement ElementSet
- Examples, CI benchmarks, documentation
Decision record (lines 976-1004):
- Decision: Use NamedTuple of typed field structs for v1.0
- Rationale: 10-50× speedup, type stability, simple (~200 LOC), immutable
- Breaking change: element.fields[name] deprecated
- Migration: Use ElementSet with NamedTuple fields
- Performance requirements: <5ns access, <100ns interp, 0 allocs assembly
- Status: Proposal ready for implementation
Complete benchmark suite (lines 1006-1114):
- Full executable benchmark code with 5 tests
- OLD (Dict) vs NEW (Typed) comparisons
- Mock element and basis functions
- Interpolation with/without cache
- Assembly loop (1000 elements)
- Summary showing 9-92× speedup validation
- Reproduction instructions
Platform: Julia 1.12.1, November 9, 2025
Series: The JuliaFEM Book, Chapter 5
Status: Proposal (validated by benchmarks)
title, subtitle, description, date, author, categories, keywords, audience, level, type, status
| title | subtitle | description | date | author | categories | keywords | audience | level | type | status | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| The JuliaFEM Book | A comprehensive manual mixing theory, software design, and personal experience | Deep dive into FEM theory, design philosophy, and research directions | 2025-11-09 | Jukka Aho |
|
|
researchers and theory enthusiasts | expert | book | work in progress |
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 | Strategic Mistakes | Why JuliaFEM?