mirror of https://github.com/JuliaFEM/JuliaFEM.jl.git synced 2026-09-21 10:23:37 +00:00

Files

T

Jukka Aho c65abfa5cc docs: Add 'Roadmap to HPC' - justifying hard performance choices

**Purpose:** Comprehensive justification for all technical decisions prioritizing
performance over convenience.

**Key Principles:**
- Efficiency > Educativeness (when forced to choose)
- Type stability over everything (100× performance difference)
- No free lunch - Julia doesn't make miracles
- HPC requires discipline and trade-offs

**Core Decisions Justified:**

1. **No Dynamic Field System**
   - field["foo"] = x is 100× slower (Dict{String,Any})
   - Type-stable structs only
   - Sacrifice: Runtime flexibility
   - Gain: Performance

2. **Immutable Data Structures**
   - struct over mutable struct
   - Sacrifice: Convenient mutation
   - Gain: 2-10× speedup, thread-safety, stack allocation

3. **NTuple Over Vector**
   - Compile-time size → SIMD optimization
   - Sacrifice: Dynamic sizing
   - Gain: Zero allocations, type stability

4. **Monolithic Over Multi-Package**
   - Learned from 2015-2019 mistake
   - Sacrifice: Small dependencies
   - Gain: It actually works

5. **Manual Derivatives (hot paths)**
   - 30× faster than AD for Tet10
   - Sacrifice: More code
   - Gain: Assembly loops stay fast

6. **Matrix-Free Methods**
   - Design for 1M+ DOF from day 1
   - Cannot retrofit later

7. **Explicit Over Implicit**
   - No magic, show the steps
   - Debuggable and teachable

**Hierarchy of Values:**
1. Correctness
2. Performance
3. Maintainability
4. Educativeness
5. Convenience

**What We're Giving Up:**
- Runtime flexibility (no element["custom_field"])
- Dynamic problem definition (no runtime topology changes)
- Duck typing convenience
- Small dependencies
- Beginner-friendly magic

**What We're Getting:**
- 10× single-thread speedup target
- 1M DOF contact problems
- Thread/GPU/distributed scalability
- Real HPC capability

**The Hard Truth:**
From Issue #266: "Do like Python, be slow like Python. Know what you do
before compiling, and be fast like C. There's no free lunch."

**Success Metrics:**
- ✅ Zero allocations in assembly
- ✅ Type-stable hot paths
- 🎯 10× faster than v0.5.1
- 🎯 1M DOF in < 1 hour
- 🎯 100+ thread scaling

**Use Cases:**
- "Why can't I use Dict?" → Point here
- "Why immutable?" → Point here
- "Why manual derivatives?" → Point here
- Any "why not convenience?" → Point here

**Status:** Living document, updated as we learn

See: Issue #266, TECHNICAL_VISION.md, benchmark results

2025-11-09 05:01:34 +02:00

benchmarks

docs: Add YAML front matter to all documentation files

2025-11-09 04:45:12 +02:00

lagrange_basis_functions.md

docs: Add YAML front matter to all documentation files

2025-11-09 04:45:12 +02:00

README.md

docs: Add YAML front matter to all documentation files

2025-11-09 04:45:12 +02:00

roadmap_to_hpc.md

docs: Add 'Roadmap to HPC' - justifying hard performance choices

2025-11-09 05:01:34 +02:00

README.md

title, subtitle, description, date, author, categories, keywords, audience, level, type, status

title

subtitle

description

date

author

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?