mirror of
https://github.com/JuliaFEM/JuliaFEM.jl.git
synced 2026-08-28 15:21:02 +00:00
Jukka Aho
be076d968a
Create 299-line focused design rationale explaining why type stability is essential
for CPU/GPU/MPI performance, without mandating specific storage patterns.
Executive summary (lines 16-26):
- v0.5.1 Dict{String,Any}: 9-92× performance degradation
- Type-unstable code CANNOT run on GPUs
- Significant MPI communication overhead
- Document does NOT prescribe storage location
- Demonstrates why type stability at access points is essential
- Key: Storage pattern matters less than type inference
Problem analysis (lines 28-67):
- Type instability definition: Runtime dispatch when type unknown at compile time
- Why it matters: 10-100× slower CPU, GPU compilation fails, MPI serialization
- Measured impact table: 9-92× speedup, 0 allocations with type stability
- Critical: Zero allocations required for GPU kernels
Design requirements (lines 69-136):
1. Type stability at access points (compiler must infer types)
- Fields could be element-local, global arrays, or arguments
- Access pattern must be type-stable regardless
2. Zero allocations in hot paths (GPU/MPI requirement)
- Assembly loop must allocate nothing
3. Contiguous memory layout (GPU/MPI optimization)
- CUDA transfers contiguous arrays directly
4. Immutable where possible (safe parallelism)
- Thread-safe reads without locks
Demonstrated solutions (lines 138-201) - EXAMPLES, not mandates:
1. NamedTuple container: Simple, type-stable, immutable
2. Struct with typed fields: Explicit, self-documenting
3. Passed as arguments: Maximum type stability, explicit dependencies
- All three achieve type stability
- Choice depends on use case, not performance
GPU and MPI rationale (lines 203-237):
- GPU execution: CUDA requires all code type-stable
- Mock demonstration in benchmarks/gpu_mpi_mock.jl
- MPI communication: Typed arrays use fast memcpy vs slow serialization
- Type stability enables identical code for CPU/GPU
Recommendations (lines 239-256):
- Use type-stable access patterns (REQUIRED)
- Prefer immutable data structures (threading/GPU)
- Pre-allocate caches (zero allocations)
- Use contiguous arrays (GPU/MPI transfer)
- Profile with @btime (verify zero allocations)
- Does NOT mandate: Storage location, container type, dynamic vs static
Validation (lines 258-275):
- benchmarks/field_storage_comparison.jl: 9-92× CPU speedup
- benchmarks/gpu_mpi_mock.jl: GPU/MPI patterns
- benchmarks/VALIDATION_RESULTS.md: Summary table
Conclusion (lines 277-299):
- Type stability is fundamental requirement, not implementation detail
- Enables: High CPU performance, GPU execution, efficient MPI, safe threading
- v1.0 must ensure type stability at access points
- Storage pattern is secondary concern (memory, cache, API)
- Next steps: Review, benchmark, choose pattern, implement, validate CUDA
Key difference from v1: Shorter (299 vs 1114 lines), focused on WHY not HOW,
explicitly states storage pattern is flexible, emphasizes GPU/MPI requirements.
Platform: Julia 1.12.1, November 9, 2025
Series: The JuliaFEM Book, Chapter 5
Status: Design rationale with validated measurements
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