Jukka Aho
9a55257ba7
Create 415-line blog post combining technical demonstration with philosophical vision for JuliaFEM v1.0 nodal assembly architecture. Content structure: - Lines 1-32: Why Krylov+nodal is brilliant for contact mechanics * Contact is inherently nodal (constraints at nodes, not elements) * Krylov only needs matvec (never forms global matrix) * Nodal assembly provides natural row-by-row interface * O(N) memory vs O(N²) for traditional element assembly - Lines 34-73: Controversial hypothesis about nodal material modeling * Claims material state should be at nodes, not integration points * Argues integration points constrain physics to numerical method * Variational consistency, physical meaning, scalability arguments * "I will show them they're wrong" - experimental vision - Lines 75-95: GMRES advantage for unsymmetric systems * Material nonlinearity, contact, large deformation all unsymmetric * GMRES solves positive definite unsymmetric systems * O(N·iter) time, O(N) memory vs O(N³)/O(N²) for direct solvers - Lines 97-415: Working GMRES demonstration on 10×10 unsymmetric system * Problem setup: Positive definite but unsymmetric matrix (lines 105-145) * Nodal assembly pattern: get_row() interface (lines 147-193) * Simplified GMRES implementation (lines 195-282) * Execution and verification (lines 284-318) * Results: Converged in 10 iterations, 6.28×10⁻¹⁶ relative error * Key insights section explaining significance (lines 320-365) * Development roadmap: Immediate → Near-term → Long-term → Vision (lines 367-401) * Conclusion: Philosophical statement about nodal correctness (lines 403-415) Technical validation: - Matrix: 10×10, eigenvalues [9.94, 38.06], condition number 3.83 - Nodal matvec: 1.59×10⁻¹⁴ error vs direct computation - GMRES: 10 iterations to convergence - Solution accuracy: 1.23×10⁻¹⁴ absolute error, 6.28×10⁻¹⁶ relative Dependencies: LinearAlgebra, Random, Printf Format: Literate.jl (# # for section headers, # for narrative) Target: Blog post for JuliaFEM v1.0 development documentation Tone: Opinionated, controversial, technically rigorous
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