mirror of
https://github.com/JuliaFEM/JuliaFEM.jl.git
synced 2026-08-28 15:21:02 +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, description, date, author, categories, keywords, type
| title | description | date | author | categories | keywords | type | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| JuliaFEM Documentation | Three-tier documentation structure for users, contributors, and researchers | 2025-11-09 | Jukka Aho |
|
|
index |
JuliaFEM Documentation
Welcome! JuliaFEM documentation is organized into three manuals for three different audiences:
📘 User Manual - "Just Get It Done"
For: End users, engineers, students who want to run simulations.
Style: Simple, practical, step-by-step.
Contents:
- Quick start and installation
- Tutorials and examples
- API reference
- Troubleshooting
Philosophy: Show me how to solve my problem, skip the lectures.
👉 Start Here if you want to run simulations.
🔧 Contributor Manual - "Show Me the Code"
For: Developers, contributors, advanced users who want to extend JuliaFEM.
Style: Technical, detailed, design rationale.
Contents:
- Testing philosophy
- Code style and architecture
- Performance guidelines
- How to add elements
- CI/CD and git workflow
Philosophy: Explain HOW the code works and WHY we made these choices.
👉 Start Here if you want to contribute code.
📖 The JuliaFEM Book - "Let Me Show You How I Think"
For: Advanced researchers, theory nerds, those who want to understand deeply. And Jukka.
Style: Comprehensive, educational, opinionated, personal.
Contents:
- Mathematical foundations (Lagrange basis, contact mechanics, etc.)
- Design philosophy and technical vision
- Strategic mistakes and lessons learned (2015-2019)
- Research directions (nodal assembly, matrix-free, etc.)
- Personal reflections on the journey
Philosophy: Mix theory, software design, and personal experience. Teach FEM through implementation.
👉 Start Here if you love deep dives and want to understand the "why" behind everything.
Quick Navigation
I want to...
- Solve a heat transfer problem → User Manual
- Add a new element type → Contributor Manual
- Understand Lagrange basis functions → Book: Lagrange Basis
- Learn about testing → Contributor: Testing Philosophy
- See benchmark results → Book: Benchmarks
- Understand the design philosophy → Book: Philosophy
- Report a bug → GitHub Issues
- Ask a question → GitHub Discussions
Documentation Philosophy
Why Three Manuals?
Different readers have different needs:
- Users don't care about implementation details - they just want working code.
- Contributors need technical depth but not necessarily all the theory.
- Researchers (and Jukka) want to understand everything from first principles.
Mixing these audiences in one manual makes it too complex for users and too shallow for researchers.
Design Principles
- User Manual: Optimize for time-to-first-result
- Contributor Manual: Optimize for correctness and maintainability
- Book: Optimize for understanding and education
Cross-References
Manuals link to each other when appropriate:
- User manual links to theory when deeper understanding helps
- Contributor manual links to book for design rationale
- Book links to code examples and practical guides
Contributing to Documentation
Documentation improvements are always welcome!
- User docs: Fix errors, add examples, improve clarity
- Contributor docs: Update for new features, clarify architecture
- Book: Add theory, share insights, document research
See Contributor Manual for guidelines.
License: MIT (same as code)
Questions? Open an issue or discussion on GitHub