diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..82e5068 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,118 @@ +# JuliaFEM Documentation + +Welcome! JuliaFEM documentation is organized into **three manuals** for three different audiences: + +--- + +## 📘 [User Manual](user/) - "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](user/README.md)** if you want to run simulations. + +--- + +## 🔧 [Contributor Manual](contributor/) - "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](contributor/README.md)** if you want to contribute code. + +--- + +## 📖 [The JuliaFEM Book](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](book/README.md)** 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](user/) +- **Add a new element type** → [Contributor Manual](contributor/) +- **Understand Lagrange basis functions** → [Book: Lagrange Basis](book/lagrange_basis_functions.md) +- **Learn about testing** → [Contributor: Testing Philosophy](contributor/testing_philosophy.md) +- **See benchmark results** → [Book: Benchmarks](book/benchmarks/) +- **Understand the design philosophy** → [Book: Philosophy](book/) +- **Report a bug** → GitHub Issues +- **Ask a question** → GitHub Discussions + +--- + +## Documentation Philosophy + +### Why Three Manuals? + +Different readers have different needs: + +1. **Users** don't care about implementation details - they just want working code. +2. **Contributors** need technical depth but not necessarily all the theory. +3. **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](contributor/) for guidelines. + +--- + +**License:** MIT (same as code) +**Questions?** Open an issue or discussion on GitHub diff --git a/docs/book/README.md b/docs/book/README.md new file mode 100644 index 0000000..71b05d3 --- /dev/null +++ b/docs/book/README.md @@ -0,0 +1,82 @@ +# 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](foundations.md) | [Strategic Mistakes](strategic_mistakes.md) | [Why JuliaFEM?](philosophy.md) diff --git a/docs/benchmarks/shape_function_derivatives_ad_vs_manual.md b/docs/book/benchmarks/shape_function_derivatives_ad_vs_manual.md similarity index 100% rename from docs/benchmarks/shape_function_derivatives_ad_vs_manual.md rename to docs/book/benchmarks/shape_function_derivatives_ad_vs_manual.md diff --git a/src/lagrange_basis_functions.md b/docs/book/lagrange_basis_functions.md similarity index 100% rename from src/lagrange_basis_functions.md rename to docs/book/lagrange_basis_functions.md diff --git a/docs/contributor/README.md b/docs/contributor/README.md new file mode 100644 index 0000000..e27e763 --- /dev/null +++ b/docs/contributor/README.md @@ -0,0 +1,53 @@ +# JuliaFEM Contributor Manual + +**Audience:** Developers, contributors, advanced users who want to extend or modify JuliaFEM. + +This manual is **technical and detailed** - it explains HOW the code works and WHY we made certain design choices. + +## What's Here + +- **Testing Philosophy:** How and why we test +- **Code Style:** Conventions and best practices +- **Architecture:** Module structure, data flow, key abstractions +- **Performance:** Zero-allocation design, profiling, benchmarking +- **Adding Elements:** How to implement new element types +- **CI/CD:** Continuous integration, releases, versioning +- **Git Workflow:** Branching, commits, pull requests + +## What's NOT Here + +- User tutorials (see `docs/user/` for that) +- Deep mathematical theory (see `docs/book/` for that) +- "How do I solve problem X?" (that's user docs) + +## Philosophy + +**"Show me the code AND tell me why."** + +We assume you: +- Know Julia reasonably well +- Understand FEM basics +- Want to add features or fix bugs +- Care about performance and correctness +- Need to understand design rationale + +## Before Contributing + +1. Read [Testing Philosophy](testing_philosophy.md) +2. Understand [Architecture](architecture.md) +3. Follow [Code Style](code_style.md) +4. Check [Performance Guidelines](performance.md) +5. Review [Git Workflow](git_workflow.md) + +## Key Principles + +- **Type stability:** No `Any`, no `Dict` without types +- **Zero allocations:** Hot paths should allocate nothing +- **Immutability:** Prefer `struct` over `mutable struct` +- **Composition:** Use tuples and free functions, not OOP hierarchies +- **Explicit:** No magic, user knows what happens +- **Test first:** Write tests before fixing bugs + +--- + +**Start here:** [Testing Philosophy](testing_philosophy.md) | [Architecture Overview](architecture.md) diff --git a/docs/STATUS.md b/docs/contributor/status.md similarity index 100% rename from docs/STATUS.md rename to docs/contributor/status.md diff --git a/docs/TEST_FIXES_NEEDED.md b/docs/contributor/test_fixes_needed.md similarity index 100% rename from docs/TEST_FIXES_NEEDED.md rename to docs/contributor/test_fixes_needed.md diff --git a/docs/TESTING_PHILOSOPHY.md b/docs/contributor/testing_philosophy.md similarity index 100% rename from docs/TESTING_PHILOSOPHY.md rename to docs/contributor/testing_philosophy.md diff --git a/docs/user/README.md b/docs/user/README.md new file mode 100644 index 0000000..eca1274 --- /dev/null +++ b/docs/user/README.md @@ -0,0 +1,40 @@ +# JuliaFEM User Manual + +**Audience:** End users, engineers, students who want to run simulations and get results. + +This manual is designed to be **simple and practical** - get you from zero to running simulations as quickly as possible. + +## What's Here + +- **Quick Start:** Installation and first simulation in 5 minutes +- **Tutorials:** Step-by-step guides for common problems +- **Examples:** Pre-built simulations you can run and modify +- **API Reference:** Function documentation (what does this do?) +- **Troubleshooting:** Common errors and how to fix them + +## What's NOT Here + +- Deep theory (see `docs/book/` for that) +- How to contribute code (see `docs/contributor/` for that) +- Internal architecture details + +## Philosophy + +**"Just show me how to solve my problem."** + +We assume you: +- Have a problem to solve (heat transfer, elasticity, contact) +- Want working code, not lectures +- Will read theory when YOU need it, not when WE think you should + +## Getting Help + +1. Start with the Quick Start +2. Find an example similar to your problem +3. Modify it to fit your needs +4. If stuck, check Troubleshooting +5. Still stuck? Ask on GitHub Discussions + +--- + +**Next:** Start with [Quick Start](quickstart.md) or browse [Examples](../examples/) diff --git a/scripts/README.md b/scripts/README.md index 0b41c9d..41c50c1 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -35,7 +35,7 @@ julia --project=. scripts/generate_lagrange_basis.jl - `src/basis/lagrange_generated.jl` (commit this file!) **Theory:** -See `src/lagrange_basis_functions.md` for mathematical foundation. +See `docs/book/lagrange_basis_functions.md` for mathematical foundation. **Architecture:** @@ -130,6 +130,6 @@ Pre-compute stiffness matrices for simple elements. **See also:** -- `src/lagrange_basis_functions.md` - Mathematical theory +- `docs/book/lagrange_basis_functions.md` - Mathematical theory - `src/basis/lagrange_generator.jl` - Symbolic generation engine - `llm/VISION_2.0.md` - Overall project architecture diff --git a/scripts/generate_lagrange_basis.jl b/scripts/generate_lagrange_basis.jl index 4def54e..c989a43 100755 --- a/scripts/generate_lagrange_basis.jl +++ b/scripts/generate_lagrange_basis.jl @@ -21,7 +21,7 @@ # - After modifying lagrange_generator.jl # # THEORY: -# See src/lagrange_basis_functions.md for full mathematical details +# See docs/book/lagrange_basis_functions.md for full mathematical details # # ============================================================================== @@ -617,7 +617,7 @@ println(output, "# cd /path/to/JuliaFEM.jl") println(output, "# julia --project=. scripts/generate_lagrange_basis.jl") println(output, "#") println(output, "# Theory:") -println(output, "# See src/lagrange_basis_functions.md") +println(output, "# See docs/book/lagrange_basis_functions.md") println(output, "#") println(output, "# Generator:") println(output, "# src/basis/lagrange_generator.jl (symbolic engine)") diff --git a/src/basis/lagrange_generator.jl b/src/basis/lagrange_generator.jl index b8e9fe3..7967e2c 100644 --- a/src/basis/lagrange_generator.jl +++ b/src/basis/lagrange_generator.jl @@ -45,7 +45,7 @@ # - Version control shows what changed # # SEE: -# - src/lagrange_basis_functions.md (mathematical explanation) +# - docs/book/lagrange_basis_functions.md (mathematical explanation) # - scripts/generate_lagrange_basis.jl (generation script) # - src/basis/lagrange_generated.jl (output - do not edit manually!) #