diff --git a/docs/src/index.md b/docs/src/index.md index e9a5944..8597d1d 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,63 +1,111 @@ -# JuliaFEM.jl +# [JuliaFEM.jl](@id home) -JuliaFEM.jl is an open-source finite element method (FEM) framework written in Julia, designed for reliable, scalable, and distributed finite element analysis. +JuliaFEM.jl is an open-source finite element framework written in Julia. +The package is **0.x**; the repository is in the middle of a deliberate +architectural reset toward a **stable 1.0** with a type-stable, zero-allocation, +GPU-friendly assembly pipeline. -## Overview +**Broader documentation** (book, user/developer guides, examples) lives in the +same repository under **`juliafem.github.io/`** (Quarto). Start from +**`juliafem.github.io/learning_path.md`** and **`juliafem.github.io/docs/documentation-map.md`** +to see how this Documenter site relates to that material. -JuliaFEM.jl provides a modern, type-safe API for finite element analysis with support for: +This page is a short, current-API quick start. The +[API Reference](@ref) lists exported symbols. -- **Multiple element types**: Triangles, quadrilaterals, tetrahedra, hexahedra, and more -- **Various physics**: Linear and nonlinear elasticity, heat transfer, and more -- **GPU acceleration**: CUDA support for high-performance computing -- **Distributed computing**: Multi-GPU and MPI support for large-scale problems - -## Key Features - -- **Type-safe element system**: Elements are parameterized by topology, basis functions, and DOF specifications -- **Modern physics API**: Clean separation between mesh, material, field, and formulation -- **Flexible material models**: Linear elastic, Neo-Hookean, perfect plasticity, and more -- **Efficient assembly**: COO and CSC sparse matrix formats with GPU support +For a maintainer-oriented summary of the current architecture and the +non-negotiable invariants, see `AGENTS.md` in the repository root. +For per-module developer notes, see the `README.md` files under +`src//`. +For a logical layer diagram and an explicit dependency contract between +those layers, see [Architecture layers](@ref). ## Installation -Install JuliaFEM.jl using Julia's package manager: - ```julia using Pkg Pkg.add("JuliaFEM") ``` -## Quick Start +## A modern minimal example -```julia -using JuliaFEM +The following sets up a unit-cube linear-elasticity problem, builds an +`Element{K, P, S, N}` template with a compile-time DOF layout, assembles +the stiffness via the matrix-free-friendly DOF-based assembler, and +extracts the assembled `K` and right-hand side `f`. -# Create a mesh -mesh = create_unit_cube_mesh(Hex8, 10, 10, 10) +The listing is included verbatim from +`docs/src/snippets/minimal_elasticity_quickstart.jl`. That file is executed in +`Pkg.test()` (`test/docs/runtests.jl`) and in CI (`scripts/verify_docs_quickstart.jl`) +so the example cannot drift from the package. -# Define a physics problem -physics = Physics( - name = "elasticity", - mesh = mesh, - element_set = :all, - field = Displacement{3}(), - formulation = ContinuumFormulation{FullThreeD}(), - material = LinearElastic(; E=200e9, ν=0.3) -) - -# Assemble and solve -assemble!(physics) -solve!(physics) +```@literalinclude +snippets/minimal_elasticity_quickstart.jl ``` -## Documentation +## Multi-field elements -- [API Reference](@ref) - Complete API documentation +`@DOFSet` accepts more than one field, and the rest of the pipeline is +multi-field aware (see `local_dof_layout` and the thermo-elastic kernel +in `src/domains/thermo_elastic/`). A longer walkthrough with a runnable +block lives on [Thermo-elastic walkthrough](@ref thermo_elastic_walkthrough). -## Contributing +```julia +S = @DOFSet{T::DOF{Temperature, Vertex}, + u::DOF{Displacement{3}, Vertex}} +``` -Contributions are welcome! Please see the [GitHub repository](https://github.com/JuliaFEM/JuliaFEM.jl) for guidelines. +## Matrix-free path -## License +The same `cache` and `kernel` drive the matrix-free +`apply_K!` / `apply_M!` operators in `src/assemblers/`: -JuliaFEM.jl is licensed under the MIT License. +- Dirichlet: `PenaltyDirichlet`, `EliminatedDirichlet` +- Linear MPC: `LinearMPC` +- Neumann loads: `NodalForce`, `UniformBodyForce`, + `SurfaceLoad` +- Preconditioners: `JacobiPreconditioner`, + `BlockJacobiPreconditioner`, + `ICholPreconditioner` +- Generalized eigensolve: `lowest_eigenpairs`, `solve_eigenproblem` + +`matrix_free_op(cache, asm, kernel, mesh; dirichlet, mpc)` returns a +closure that wraps `apply_K!` with constraint hooks; it composes with +any `LinearOperator`/Krylov stack. + +## Inspecting the compile-time DOF layout + +`local_dof_layout(::Type{Element{K,P,S,N}})` is a `@generated` function +that returns an `NTuple{N, DOFLayoutEntry}` describing +`(field_idx, entity_local, component)` for each local DOF. The compiler +folds it into a constant at the call site, so DOF decoding is a tuple +lookup with no runtime arithmetic. + +```julia +S = @DOFSet{u::DOF{Displacement{3}, Vertex}} +ET = Element{Hex8, Lagrange{1}, S, 24} +local_dof_layout(ET) +``` + +## Where to look next + +- Elements, DOFs, traits, mixed fields: + [Elements and multiphysics](@ref elements_multiphysics_teaser) +- Coupled thermo-elasticity (multi-field): + [Thermo-elastic walkthrough](@ref thermo_elastic_walkthrough) +- Assembler trade-offs: + [Choosing an assembler](@ref assembler_choice) +- Legacy API (optional `Legacy` submodule): + [Legacy module](@ref legacy_module) +- API reference: [API Reference](@ref) +- Repository layout: [Repository layout](@ref) (see also the pointer + `docs/repository_layout.md` on GitHub). +- Changelog (0.x): `docs/NEWS.md` in the project root. +- Architecture: `AGENTS.md` in the project root, plus + `src/README.md` for a per-module overview. +- Tests as documentation: + `test/assemblers/test_dof_based_*.jl`, + `test/assemblers/test_eigensolve.jl`, + `test/assemblers/test_linear_mpc.jl`, + `test/assemblers/test_surface_load.jl`, + `test/assemblers/test_ichol_preconditioner.jl`.