mirror of https://github.com/JuliaFEM/JuliaFEM.jl.git synced 2026-09-18 09:41:31 +00:00

Files

T

Jukka Aho ee02f9f37a feat: Separation of concerns architecture with zero-allocation foundation

**Architecture Decision: Element = Topology + Interpolation + Integration + Fields**

This commit establishes the architectural foundation for separating orthogonal concerns
in finite element implementation, preventing Abaqus-style combinatorial explosion.

## New Modules (Not Yet Integrated)

### src/topology/
Reference element geometries (pure mathematical objects):
- topology.jl: Abstract interface for reference elements
- tri3.jl: 3-node triangle reference element
- quad4.jl: 4-node quadrilateral reference element

**Zero-allocation design:**
- reference_coordinates() → NTuple{N, NTuple{D, Float64}}
- edges() → NTuple{Ne, Tuple{Int, Int}}
- faces() → NTuple{Nf, NTuple{Nn, Int}}

All topology queries return compile-time sized tuples (stack allocated, no heap).

### src/integration/
High-level integration scheme abstraction:
- integration.jl: Abstract types and IntegrationPoint struct
- gauss.jl: Gauss-Legendre quadrature wrapper around existing src/quadrature/

**Zero-allocation design:**
- integration_points() → Tuple{Vararg{IntegrationPoint{D}}}
- IntegrationPoint.ξ → NTuple{D, Float64}

**Key Insight:** Integration rules already exist in src/quadrature/ (consolidated from
FEMQuad.jl). New code is a thin architectural wrapper, not reimplementation.

## Documentation

### docs/book/element_architecture.md (NEW - 650+ lines)
Complete book chapter explaining:
- What is an Element? (composition of 4 orthogonal concerns)
- The Abaqus anti-pattern (C3D8, C3D8R, C3D8I explosion)
- JuliaFEM approach: Topology + Interpolation + Integration separation
- Type system enforcement
- Performance implications (100× speedup from type stability)
- Extending the system (adding new topologies/bases/quadrature)
- Comparison with Gridap.jl, Ferrite.jl, Deal.II

### llm/ARCHITECTURE.md (UPDATED)
Added "Architectural Decision: Separation of Concerns" section at top:
- Problem statement
- Anti-pattern example
- JuliaFEM solution
- Directory structure rationale
- Type system design
- Migration strategy

### scripts/generate_lagrange_basis.jl (UPDATED)
Added architectural context explaining Lagrange bases are INTERPOLATION SCHEMES
(not topologies, not integration rules).

## Performance: Zero-Allocation Foundation

**Why tuples matter:**
1. **Zero heap allocations** - All data stack-allocated
2. **Compile-time sizes** - Compiler can unroll loops
3. **Cache friendly** - Contiguous memory layout
4. **Type stable** - Concrete tuple types enable optimization
5. **Immutable** - No accidental mutation, thread-safe

**Example impact:**
```julia
# Compiler knows at compile time:
# - Tri3 has exactly 3 edges
# - Each edge has exactly 2 nodes
# → Loop unrolling, no bounds checks, SIMD vectorization

for edge in edges(Tri3())  # Tuple iteration, fully unrolled!
    node1, node2 = edge
    # ... assembly code (zero allocations)
end
```

**Principle from Roadmap to HPC:**
> "Zero allocations in hot paths" - Strategic Decision #2

Topology/integration queries happen billions of times in assembly loops.
Even small Vector allocations accumulate to GC pressure and cache misses.

**Rule:** If size known at compile time → use Tuple, not Vector

## Benefits

✅ Clear separation of mathematical concepts
✅ Mix-and-match: Tri3 + Lagrange + Gauss, Tri3 + Hierarchical + Lobatto, etc.
✅ Type system enforces correctness at compile time
✅ Compiler generates specialized code for each combination → 100× speedup
✅ Zero allocations in topology/integration queries
✅ No code duplication (each concern in one place)
✅ Educational: teaches proper software engineering

## Status

- **NOT YET INTEGRATED**: New modules not included in src/JuliaFEM.jl
- **SAFE**: Package loads successfully (verified with `using JuliaFEM`)
- **READY**: Architecture documented, zero-alloc foundation established

## Next Steps

1. Create remaining topology files (Tet4, Tet10, Hex8, Hex20, etc.)
2. Update src/JuliaFEM.jl to include new modules
3. Refactor existing Element to use new separation
4. Run generation script with new architecture
5. Integrate with existing codebase

## References

- Abaqus documentation (anti-pattern example)
- Gridap.jl (alternative approach)
- Ferrite.jl (mixed approach)
- Deal.II (C++ template approach)
- llm/ROADMAP_TO_HPC.md (performance philosophy)

See: docs/book/element_architecture.md for complete rationale and examples.

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

benchmarks

feat: Separation of concerns architecture with zero-allocation foundation

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

element_architecture.md

feat: Separation of concerns architecture with zero-allocation foundation

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

lagrange_basis_functions.md

feat: Separation of concerns architecture with zero-allocation foundation

2025-11-09 05:46:34 +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?