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)
JuliaFEM.jl - an open source solver for both industrial and academia usage
The JuliaFEM project develops open-source software for reliable, scalable, distributed Finite Element Method.
The JuliaFEM software library is a framework that allows for the distributed processing of large Finite Element Models across clusters of computers using simple programming models. It is designed to scale up from single servers to thousands of machines, each offering local computation and storage. The basic design principle is: everything is nonlinear. All physics models are nonlinear from which the linearization are made as a special cases.
At the moment, users can perform the following analyses with JuliaFEM: elasticity, thermal, eigenvalue, contact mechanics, and quasi-static solutions. Typical examples in industrial applications include non-linear solid mechanics, contact mechanics, finite strains, and fluid structure interaction problems. For visualization, JuliaFEM uses ParaView which prefers XDMF file format using XML to store light data and HDF to store large data-sets, which is more or less the open-source standard.
Vision
On one hand, the vision of the JuliaFEM includes the opportunity for massive parallelization using multiple computers with MPI and threading as well as cloud computing resources in Amazon, Azure and Google Cloud services together with a company internal server. And on the other hand, the real application complexity including the simulation model complexity as well as geometric complexity. Not to forget that the reuse of the existing material models as well as the whole simulation models are considered crucial features of the JuliaFEM package.
Recreating the wheel again is definitely not anybody's goal, and thus we try to use and embrace good practices and formats as much as possible. We have implemented Abaqus / CalculiX input-file format support and maybe will in the future extend to other FEM solver formats. Using modern development environments encourages the user towards fast development time and high productivity. For developing and creating new ideas and tutorials, we have used Jupyter notebooks to make easy-to-use handouts.
The user interface for JuliaFEM is Jupyter Notebook, and Julia language itself is a real programming language. This makes it possible to use JuliaFEM as a part of a bigger solution cycle, including for example data mining, automatic geometry modifications, mesh generation, solution, and post-processing and enabling efficient optimization loops.
Installing JuliaFEM
Inside Julia REPL, type:
Pkg.add("JuliaFEM")
Initial road map
JuliaFEM current status: project planning
| Version | Number of degree of freedom | Number of cores |
|---|---|---|
| 0.1.0 | 1 000 000 | 10 |
| 0.2.0 | 10 000 000 | 100 |
| 1.0.0 | 100 000 000 | 1 000 |
| 2.0.0 | 1 000 000 000 | 10 000 |
| 3.0.0 | 10 000 000 000 | 100 000 |
We strongly believe in the test driven development as well as building on top of previous work. Thus all the new code in this project should be 100% tested. Also other people have wisdom in style as well:
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Errors should never pass silently.
Citing
If you like using our package, please consider citing our article
@article{frondelius2017juliafem,
title={Julia{FEM} - open source solver for both industrial and academia usage},
volume={50},
url={https://rakenteidenmekaniikka.journal.fi/article/view/64224},
DOI={10.23998/rm.64224},
number={3},
journal={Rakenteiden Mekaniikka},
author={Frondelius, Tero and Aho, Jukka},
year={2017},
pages={229-233}
}
Contributing
We welcome contributions! JuliaFEM encourages good practices, starting from unit testing and continuing to full integration testing across platforms.
Interested in contributing? Please read:
- Contributing Guide - Quick start for contributors
- Coding Standards - Required reading (includes important rules like "no Greek letters in code")
- Contributor Manual - Technical details and architecture
Key requirements:
- ✅ Type-stable code (performance critical)
- ✅ Tests included with all changes
- ✅ Follow coding standards (use
u, v, wnot ξ, η, ζ) - ✅ Clean commit messages
Questions? Open a GitHub Discussion or issue - we're happy to help!