mirror of
https://github.com/JuliaFEM/JuliaFEM.jl.git
synced 2026-09-24 03:07:53 +00:00
d676ab3bba720e49b401e3d739b688b2babc4cd5
13 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Jukka Aho
|
81f4f85f3e |
feat(gpu): Multi-GPU MPI benchmark with nodal assembly
Implements working GPU-accelerated nodal assembly with MPI domain decomposition: - Matrix-free matvec operation on GPU (y = A*x without assembling A) - 2-6× speedup vs CPU multi-threading (114-302 Mnodes/s) - Scales to 343K nodes / 1M DOFs with acceptable communication overhead - CSR format for GPU-friendly node-to-elements connectivity - Global-to-local index remapping for partition consistency Key components: - benchmarks/multigpu_mpi_benchmark.jl: Full MPI+CUDA implementation (555 lines) - benchmarks/multigpu_results_2025-11-09.md: Detailed performance analysis - docs/book/gpu_benchmark_milestone.md: Comprehensive tutorial documentation Performance results (NVIDIA RTX A2000 12GB, 2 MPI ranks): - 30³ mesh: 114.84 Mnodes/s, 29% communication overhead - 50³ mesh: 130.64 Mnodes/s, 61% communication overhead - 70³ mesh: 301.83 Mnodes/s, 51% communication overhead Architecture validated: Nodal assembly + matrix-free + GPU = fast and scalable. Foundation complete for production FEM solver (needs: real stiffness, GMRES, preconditioner). |
||
|
Jukka Aho
|
be076d968a |
docs(book): Add concise type-stability rationale for field storage
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
|
||
|
Jukka Aho
|
4809fe1633 |
docs(book): Add comprehensive zero-allocation field storage design
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)
|
||
|
Jukka Aho
|
f2b306f68e |
docs(book): Add nodal assembly and multi-GPU strategy document
New 588-line comprehensive strategic document explaining winning architecture: Executive Summary (lines 1-19): - Key results demonstrated on real hardware - 9-92× CPU speedup, GPU kernel compilation, MPI working, Krylov convergence - Multi-GPU workflow validated end-to-end Problem: Traditional FEM doesn't scale (lines 21-59): - v0.5.1 limitations: global matrix O(N²) memory, direct solver O(N³) time - Scalability ceiling ~100K DOF - Cannot scale: memory N², time N³ Solution: Nodal + Matrix-Free + Multi-GPU (lines 61-193): - Architecture diagram with MPI ranks and local GPUs - Three pillars: nodal assembly (row-by-row), matrix-free (matvec only), multi-GPU with MPI - Each pillar explained with code examples and advantages Why type stability required (lines 195-241): - GPU kernel compilation: concrete types required, abstract fails - MPI fast path: typed buffers vs slow serialization - Krylov solvers: matrix-free operators need concrete types - Demonstrated with code examples Performance characteristics (lines 243-289): - Complexity analysis: O(N²)→O(N) memory, O(N³)→O(N·k) time - Scalability comparison table: 10K→10M DOF - Demonstrated results: 10×10 system, 9 iterations, 7.73×10⁻¹⁴ error Contact mechanics killer app (lines 291-340): - Why nodal assembly natural for contact (contact is nodal not element-based) - Contact workflow: detect→assemble→solve→update - Element-based assembly is mismatch for contact Implementation strategy v1.0 (lines 342-407): - Phase 1: Foundation (complete) - type-stable design, GPU/MPI demos, Krylov validation - Phase 2: Core implementation - nodal assembly API, matrix-free operator, GPU accel, MPI distribution - Phase 3: Contact integration - detection, contribution to rows, iterative solve Comparison with other strategies (lines 409-455): - Global matrix assembly: dead end for scalability - Element-based matrix-free: works but suboptimal for contact - Nodal + matrix-free + multi-GPU (ours): best for large-scale contact Validation and evidence (lines 457-533): - Three demonstrations: gpu_mpi_demo, krylov_mpi_gpu_demo, field_storage_comparison - Real-world applicability: LAMMPS, GROMACS use similar patterns - Why traditional FEM codes don't do this: legacy constraints Conclusion (lines 535-588): - Five validated achievements proving path forward - Not speculation: working code on real hardware - Path is clear: type stability foundation, nodal assembly pattern, Krylov+MPI solver - Related documentation links Purpose: Strategic justification for v1.0 architecture with real evidence |
||
|
Jukka Aho
|
0cfe966063 |
docs(book): Add ADR-002 for topology without hardcoded node counts
Architecture Decision Record documenting topology/basis separation (292 lines):
- Explains decision to remove node counts from topology types
- Documents topology = pure geometry, basis determines node count
- Shows old Code Aster anti-pattern (TRIA3, TRIA6, QUAD4, QUAD8)
- Describes new design: Triangle + Lagrange{Triangle, P}
- Rationale: mathematical correctness, separation of concerns
- Enables edge/face DOFs (Nédélec, Raviart-Thomas)
- Eliminates combinatorial explosion (8 topologies vs hundreds)
- Consequences: extensible, correct, but breaking change
- Implementation strategy and migration plan
- Includes proper YAML front matter for book chapter
|
||
|
Jukka Aho
|
d8fc224c42 |
docs(book): Add ADR-002 for topology without hardcoded node counts
New Architecture Decision Record for the comprehensive book (292 lines):
- Documents decision to remove node counts from topology types
- Explains topology = pure geometry, basis determines node count
- Shows old Code Aster anti-pattern (TRIA3, TRIA6, QUAD4, QUAD8)
- Describes new design: Triangle + Lagrange{Triangle, P}
- Rationale: mathematical correctness, separation of concerns
- Enables edge/face DOFs (Nédélec, Raviart-Thomas)
- Eliminates combinatorial explosion (8 topologies vs hundreds)
- Consequences: extensible, correct, but breaking change
- Implementation strategy and migration plan
- Backwards compatibility via aliases and shims
|
||
|
Jukka Aho
|
5e210187d8 |
docs(architecture): Complete rewrite explaining topology vs basis separation
Major documentation update (380 additions, 167 deletions):
- Explained topology is pure geometry (NO hardcoded node counts)
- Clarified basis determines BOTH polynomial degree AND node count
- Distinguished node count (connectivity) vs DOF count (unknowns)
- Added examples: Nedelec (edge DOFs), Raviart-Thomas (face DOFs)
- Documented Lagrange{Topology, P} parametric architecture
- Showed why Tri3/Quad4/Tet10 names are anti-pattern
- Updated all code examples to use new architecture
- Explained Serendipity vs full Lagrange tensor products
- Added performance implications and trade-offs
- Showed how one Triangle topology works for P1/P2/P3/Nedelec/etc
|
||
|
Jukka Aho
|
31ecd6c0dc |
docs(book): Update Lagrange basis generation references
- Changed generator path: scripts/generate_lagrange_basis.jl → src/basis/lagrange_generator.jl - Updated execution command: now run directly with julia --project=. - Consolidated "See Also" section: removed duplicate generator reference - Clarified generator role: symbolic engine AND generation script in single file - Updated comment explaining basis functions are pregenerated (not runtime) |
||
|
Jukka Aho
|
6ca17e0569 |
Integrate topology/integration modules with comprehensive testing
INTEGRATION COMPLETE ✓
=======================
What's New:
-----------
- Integrated 17 topology types into main JuliaFEM module
- Integrated Gauss quadrature integration system
- Added comprehensive standalone test suite (36 tests, all passing)
- Documented topology coordinates for Hex20, Hex27, Pyr5, Quad8, Quad9, Tri7, Wedge6, Wedge15
Changes:
--------
src/JuliaFEM.jl:
- Added topology module includes (17 topology types)
- Added integration module includes (integration.jl, gauss.jl)
- Exported all topology and integration symbols
- Documented lagrange basis conflict (TODO for Phase 2)
test/test_topology_integration.jl (NEW):
- Comprehensive test suite for full JuliaFEM integration
- Tests all 17 topology types (1D, 2D, 3D)
- Tests integration point generation for all topologies
- Validates zero-allocation design
- 370+ lines of test coverage
test/test_topology_standalone.jl (NEW):
- Standalone validation tests (36/36 passing)
- Tests topology module independently
- Tests integration module independently
- Bypasses name conflicts with old basis system
- Proves core functionality correct
Topology Fixes:
- Hex20, Hex27: Added proper node numbering documentation
- Hex8: Fixed reference coordinates to match standard [-1,1]³
- Pyr5: Fixed apex coordinate to (0,0,1)
- Quad8, Quad9: Fixed midpoint coordinates
- Tri7: Added standard node order
- Wedge6, Wedge15: Fixed coordinate system
Documentation:
- Updated book README with integration status
- Updated contributor test fixes with topology integration notes
Test Results:
-------------
Topology standalone: 23/23 passed
✓ Seg2: nnodes, dim, coordinates
✓ Tri3: nnodes, dim, coordinates, edges
✓ Quad4: nnodes, dim, coordinates, edges
✓ Tet4: nnodes, dim, coordinates, edges, faces
✓ Hex8: nnodes, dim, coordinates, edges, faces
Integration standalone: 13/13 passed
✓ IntegrationPoint structure
✓ Gauss{1} + Tri3: 1 point at (1/3, 1/3), weight 0.5
✓ Gauss{3} + Tri3: 3 points, weights sum to 0.5
✓ Gauss{2} + Quad4: 4 points, weights sum to 4.0
✓ Gauss{1} + Tet4: 1 point (3D)
✓ Gauss{2} + Hex8: 8 points, weights sum to 8.0
Known Issue:
------------
Name conflict between topology types (Tri3 <: AbstractTopology) and
basis types (Tri3 <: AbstractBasis). Lagrange basis files currently
commented out to allow topology/integration to load. Will be resolved
in Phase 2 by renaming basis types (e.g., Tri3 -> Tri3Basis).
Zero-Allocation Design Verified:
---------------------------------
All topology and integration functions return tuples (immutable, stack-allocated).
No heap allocations in hot paths. Performance-critical design validated.
Next Steps:
-----------
1. Resolve name conflicts (rename basis types with *Basis suffix)
2. Refactor AbstractElement to accept separate topology/basis types
3. Run full test suite with integrated modules
4. Generate code coverage report
|
||
|
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.
|
||
|
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
|
||
|
Jukka Aho
|
1636e255fe |
docs: Add YAML front matter to all documentation files
**Purpose:** Prepare documentation for publishing as blog posts or book **YAML Headers Include:** - title: Document title - subtitle: Optional subtitle for context - description: Brief summary for SEO/indexing - date: Creation date - updated: Last update date (for status docs) - author: Jukka Aho - categories: Taxonomic classification - keywords: Search/indexing keywords - audience: Target reader (users/contributors/researchers) - level: Difficulty level (beginner/intermediate/advanced/expert) - type: Document type (manual/guide/theory/benchmark/status) - series: Which manual it belongs to - chapter: Book structure (for The JuliaFEM Book) - status: Current state (completed/work in progress/active maintenance) - math: Whether document contains mathematical notation - prerequisites: Required background knowledge - tools: Software/packages used (for benchmarks) - context: Background information **Files Updated:** - docs/README.md (main index) - docs/user/README.md (user manual index) - docs/contributor/README.md (contributor manual index) - docs/book/README.md (book index) - docs/contributor/testing_philosophy.md - docs/contributor/status.md - docs/contributor/test_fixes_needed.md - docs/book/lagrange_basis_functions.md - docs/book/benchmarks/shape_function_derivatives_ad_vs_manual.md - scripts/README.md **Benefits:** - Ready for static site generators (Jekyll, Hugo, MkDocs) - Can generate book with proper metadata - SEO-friendly with descriptions and keywords - Clear audience/level targeting - Trackable with dates and status - Organized by series and chapters **Compatible With:** - Jekyll (GitHub Pages) - Hugo (fast static site generator) - MkDocs (Python-based documentation) - Jupyter Book (interactive books) - Docusaurus (React-based docs) - Custom publishing scripts |
||
|
Jukka Aho
|
626266c990 |
docs: Reorganize documentation into three-tier structure
**Three Manuals for Three Audiences:** 1. **User Manual** (docs/user/) - "Just Get It Done" - For end users, engineers, students - Simple, practical, step-by-step - Quick start, tutorials, examples, troubleshooting - Philosophy: Show me how to solve my problem 2. **Contributor Manual** (docs/contributor/) - "Show Me the Code" - For developers, contributors, advanced users - Technical, detailed, design rationale - Testing, architecture, performance, CI/CD - Philosophy: Explain HOW and WHY 3. **The JuliaFEM Book** (docs/book/) - "Let Me Show You How I Think" - For researchers, theory nerds, and Jukka - Comprehensive, educational, opinionated, personal - Math foundations, design philosophy, history, research - Philosophy: Mix theory, code, and personal experience **Reorganization:** - Moved: TESTING_PHILOSOPHY.md → contributor/testing_philosophy.md - Moved: STATUS.md → contributor/status.md - Moved: TEST_FIXES_NEEDED.md → contributor/test_fixes_needed.md - Moved: lagrange_basis_functions.md → book/lagrange_basis_functions.md - Moved: benchmarks/ → book/benchmarks/ - Created: docs/README.md (main index explaining structure) - Created: README.md in each section explaining audience and contents - Updated: All references in scripts and source files **Naming:** All docs now lowercase (testing_philosophy not TESTING_PHILOSOPHY) **Benefits:** - Clear separation of concerns - Users don't get overwhelmed with implementation details - Contributors get technical depth - Book preserves deep theory and personal insights - Each manual optimized for its audience **Next:** Populate each section with appropriate content |