mirror of
https://github.com/JuliaFEM/JuliaFEM.jl.git
synced 2026-08-06 04:21:33 +00:00
refactor(docs): update index.md
docs/src/index.md | 132 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 90 insertions(+), 42 deletions(-)
This commit is contained in:
Jukka Aho
+89
-41
@@ -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/<topic>/`.
|
||||
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`.
|
||||
|
||||
Reference in New Issue
Block a user