mirror of
https://github.com/JuliaFEM/JuliaFEM.jl.git
synced 2026-09-22 10:48:32 +00:00
Jukka Aho
ebf823b5c6
New 125-line README documenting: - Two main demonstrations (GPU+MPI and Krylov solver) - Requirements (Julia 1.9+, MPI, optional CUDA) - Key insights: type stability required for GPU/MPI/Krylov - Nodal assembly pattern explanation - Architecture validation (v0.5.1 vs v1.0 comparison) - References to benchmarks and design docs - Contributing guidelines for new demos
126 lines
3.5 KiB
Markdown
126 lines
3.5 KiB
Markdown
# JuliaFEM Technology Demonstrations
|
||
|
||
This directory contains demonstrations of key technologies and architectural decisions for JuliaFEM v1.0.
|
||
|
||
## Overview
|
||
|
||
These demos validate that type-stable field storage enables modern high-performance computing patterns: GPU execution, MPI communication, and Krylov iterative solvers.
|
||
|
||
## Demonstrations
|
||
|
||
### 1. GPU and MPI Communication (`gpu_mpi_demo.jl`)
|
||
|
||
**Purpose:** Prove that type-stable data structures flow efficiently to GPU and MPI.
|
||
|
||
**What it demonstrates:**
|
||
|
||
- Real CUDA GPU kernel execution
|
||
- MPI data transfer between processes
|
||
- Combined GPU+MPI workflow
|
||
|
||
**Run:**
|
||
|
||
```bash
|
||
mpiexec -np 2 julia --project=. demos/gpu_mpi_demo.jl
|
||
```
|
||
|
||
**Documentation:** [README_GPU_MPI.md](README_GPU_MPI.md)
|
||
|
||
### 2. Multi-GPU MPI Krylov Solver (`krylov_mpi_gpu_demo.jl`)
|
||
|
||
**Purpose:** Complete distributed FEM solver workflow with nodal assembly.
|
||
|
||
**What it demonstrates:**
|
||
|
||
- Nodal assembly pattern (row-by-row matrix construction)
|
||
- Distributed matrix-vector products
|
||
- Conjugate Gradient solver with MPI
|
||
- Multi-GPU execution
|
||
- Solution verification (10×10 SPD system)
|
||
|
||
**Run:**
|
||
|
||
```bash
|
||
mpiexec -np 2 julia --project=. demos/krylov_mpi_gpu_demo.jl
|
||
```
|
||
|
||
**Documentation:** [README_KRYLOV_DEMO.md](README_KRYLOV_DEMO.md)
|
||
|
||
**Results:**
|
||
|
||
- Converges in 9 iterations
|
||
- Relative error: 7.73 × 10⁻¹⁴
|
||
- Validates complete distributed solving workflow
|
||
|
||
## Requirements
|
||
|
||
### Required
|
||
|
||
- Julia 1.9+
|
||
- MPI installation (e.g., OpenMPI, MPICH)
|
||
- MPI.jl package
|
||
|
||
### Optional (for GPU demos)
|
||
|
||
- CUDA-capable GPU
|
||
- CUDA.jl package
|
||
|
||
If CUDA is not available, demos will fall back to CPU execution while still demonstrating the distributed computing patterns.
|
||
|
||
## Key Insights
|
||
|
||
### Type Stability is Not Optional
|
||
|
||
These demos prove that type-stable field storage is **required** (not just "nice to have") for:
|
||
|
||
| Feature | Why Type Stability Required |
|
||
|---------|----------------------------|
|
||
| GPU execution | CUDA kernels cannot compile with abstract types |
|
||
| Fast MPI | Typed buffers avoid serialization overhead |
|
||
| Krylov solvers | Matrix-free operators need concrete types |
|
||
| CPU performance | 9-92× speedup measured (see CPU benchmarks) |
|
||
|
||
### Nodal Assembly Pattern
|
||
|
||
The Krylov demo shows row-by-row matrix construction (`get_row()` abstraction), which:
|
||
|
||
- Aligns naturally with contact mechanics (nodal constraints)
|
||
- Enables domain decomposition (each rank owns nodes)
|
||
- Supports matrix-free solving (never form global matrix)
|
||
- Scales to large problems (O(N) memory vs O(N²))
|
||
|
||
### Architectural Validation
|
||
|
||
These demos validate the design decisions for JuliaFEM v1.0:
|
||
|
||
**v0.5.1 (2019):**
|
||
|
||
- Dict-based fields → Type instability
|
||
- Element assembly → Global matrix
|
||
- Direct solvers → O(N³) time, O(N²) memory
|
||
- Single-threaded CPU
|
||
|
||
**v1.0 (target, validated here):**
|
||
|
||
- Type-stable fields → GPU/MPI capable
|
||
- Nodal assembly → Distributed construction
|
||
- Krylov solvers → O(N·iter) time, O(N) memory
|
||
- Multi-GPU + MPI
|
||
|
||
## References
|
||
|
||
- **CPU benchmarks:** See `benchmarks/field_storage_comparison.jl` for 9-92× speedup measurements
|
||
- **Design documentation:** See `docs/book/zero_allocation_fields_v2.md` for architectural rationale
|
||
- **Session notes:** See `llm/sessions/2025-11-09_gpu_mpi_validation.md` for development history
|
||
|
||
## Contributing
|
||
|
||
These demos are educational and meant to be:
|
||
|
||
- **Clear:** Understand what's being demonstrated
|
||
- **Minimal:** No unnecessary complexity
|
||
- **Runnable:** Work on typical hardware (fall back to CPU if needed)
|
||
- **Validated:** Compare against exact solutions
|
||
|
||
When adding new demos, follow this pattern and document thoroughly.
|