From 487f977dea623923e85db26ac19ecc7d476b7f90 Mon Sep 17 00:00:00 2001 From: Jukka Aho Date: Sat, 9 May 2026 16:30:28 +0300 Subject: [PATCH] refactor(src): update README.md src/README.md | 597 ++++++---------------------------------------------------- 1 file changed, 61 insertions(+), 536 deletions(-) --- src/README.md | 597 ++++++-------------------------------------------- 1 file changed, 61 insertions(+), 536 deletions(-) diff --git a/src/README.md b/src/README.md index 4409ee4..fe94d24 100644 --- a/src/README.md +++ b/src/README.md @@ -1,536 +1,61 @@ -# JuliaFEM Source Code Architecture - -**Purpose:** This document defines the role and responsibility of each subdirectory in `src/`. Every directory must have a clear, single reason to exist. - ---- - -## ๐ŸŽฏ Core Architecture Principle - -**Clean separation of concerns:** Each module has ONE job. If a directory's purpose isn't clear, it should be merged or deleted. - ---- - -## โœ… Active Modules (Clear Purpose, Keep) - -### `topology/` - Element Geometry -**Purpose:** Reference element definitions (node positions, edges, faces) - -**Responsibility:** -- Define topology types: `Segment`, `Triangle`, `Quadrilateral`, `Tetrahedron`, `Hexahedron`, `Pyramid`, `Wedge` -- Provide reference coordinates in parent space -- Define connectivity (edges, faces) -- **Zero-allocation design** (tuples, immutable) - -**Files:** 9 files -**Exports:** Topology types + aliases (Tri3, Quad4, Hex8, etc.) -**Status:** โœ… Modern, complete (Nov 9, 2025) - -**Key insight:** Topology โ‰  Basis. `Triangle` is geometry. Node count comes from basis (Lagrange{Triangle,1} = 3 nodes, Lagrange{Triangle,2} = 6 nodes). - ---- - -### `basis/` - Shape Functions -**Purpose:** Interpolation schemes for finite element approximation - -**Responsibility:** -- Evaluate basis functions N(ฮพ,ฮท,ฮถ) at reference points -- Evaluate basis derivatives โˆ‚N/โˆ‚ฮพ, โˆ‚N/โˆ‚ฮท, โˆ‚N/โˆ‚ฮถ -- Support Lagrange and Serendipity families -- Generate basis code from symbolic definitions - -**Files:** 12 files (including generator) -**Exports:** `AbstractBasis`, `Lagrange{T,P}`, `Serendipity{T,P}`, `eval_basis!`, `eval_dbasis!` -**Status:** โœ… Modern, parametric types (Nov 20, 2025) - -**Design:** `basis_generator.jl` creates `basis_generated.jl` with all Lagrange families. Run: `julia --project=. src/basis/basis_generator.jl` - ---- - -### `quadrature/` - Numerical Integration -**Purpose:** Gauss quadrature rules for integration - -**Responsibility:** -- Provide integration points (ฮพ, ฮท, ฮถ, weight) for all topologies -- Support multiple orders (1-5 typically) -- Map high-level schemes (`Gauss{3}`) to low-level point tables -- **Zero-allocation API** (returns tuples) - -**Files:** 10 files -**Exports:** `Gauss{order}`, `integration_points(scheme, topology)`, `IntegrationPoint` -**Status:** โœ… Modern API (Nov 20, 2025) - -**Architecture:** `api.jl` defines interface, `gauss.jl` maps schemes, `gl_*.jl` contain point data. - ---- - -### `mesh/` - Mesh Data Structures -**Purpose:** Mesh representation (nodes, connectivity, sets) - -**Responsibility:** -- Define `Mesh{N,T}` parametric type (type-stable) -- Store node coordinates, element connectivity -- Manage element/node sets (for BCs and material regions) -- Provide inverse connectivity (node โ†’ elements) for nodal assembly -- Mesh creation (structured, circular, Gmsh interface) -- Mesh refinement (convergence studies) -- Graph ordering (RCM bandwidth minimization) - -**Files:** 7 files -**Exports:** `Mesh`, `AbstractMesh`, `create_structured_box_mesh`, `refine`, `LongestEdgeBisection` -**Status:** โœ… Complete, documented (Nov 21, 2025) -**README:** โœ… `mesh/README.md` (complete architecture doc) - ---- - -### `materials/` - Constitutive Models -**Purpose:** Material behavior (stress-strain relationships) - -**Responsibility:** -- Define material types: `LinearElastic`, `PerfectPlasticity`, `FiniteStrainPlasticity` -- Compute stress ฯƒ from strain ฮต -- Compute tangent stiffness ๐”ป (โˆ‚ฯƒ/โˆ‚ฮต) -- Manage internal state variables (plasticity, damage) -- Trait-based dispatch for different material behaviors - -**Files:** 6 files -**Exports:** `AbstractMaterial`, `LinearElastic`, `PerfectPlasticity`, `compute_stress`, `compute_tangent` -**Status:** โœ… Modern trait-based API (Nov 19, 2025) - -**Design:** Three material behavior traits: -- `StatelessConstantTangent` (linear elastic) -- `StatelessStrainDependent` (hyperelastic) -- `StatefulStrainDependent` (plasticity, damage) - ---- - -### `assemblers/` - Assembly Strategies -**Purpose:** Build global matrices/vectors from element contributions - -**Responsibility:** -- Provide assembly caches (COO, CSC, nodal) -- Scatter element blocks to global system -- Support symmetric and non-symmetric matrices -- Element-based and node-based assembly -- **Zero-allocation design** with pre-allocated caches - -**Files:** 20 files -**Exports:** `COOCache`, `CSCCache`, `NodalCache`, `assemble!`, `ElementBasedCOOAssembler`, `NodeBasedCOOAssembler` -**Status:** โœ… Refactored into modular caches (Nov 20, 2025) - -**Architecture:** Split from monolithic `caches.jl` into: -- `coo_cache.jl`, `csc_cache.jl`, `nodal_cache.jl` - Cache types -- `element_cache.jl`, `geometry_cache.jl`, `material_cache.jl` - Domain-specific caches -- `scatter_*.jl` - Scatter strategies (symmetric, direct, force vector) - ---- - -### `domains/` - Physics Kernels -**Purpose:** Problem-specific formulations (continuum, beams, plates, shells, trusses) - -**Responsibility:** -- Implement weak form integrals for different physics -- Provide kernel types that encapsulate formulation + material -- Handle domain-specific DOF mappings (displacement, rotation, etc.) -- Compute element stiffness and force contributions - -**Subdirectories:** -- `continuum/` - 3D solid mechanics (displacement-based) -- `beams/` - 1D beam elements (Euler-Bernoulli, Timoshenko) -- `plates/` - 2D plate bending (Kirchhoff, Reissner-Mindlin, DKT) -- `shells/` - 2D shell elements (membrane + bending) -- `trusses/` - 1D truss elements (axial only) -- `common/` - Shared utilities - -**Files:** 16 files across 6 subdirectories -**Exports:** `ContinuumKernel`, `PlateKernel`, `BeamKernel`, etc. -**Status:** โœ… Continuum complete with two-phase assembly (Nov 19, 2025) - -**Key innovation:** Two-phase assembly architecture (Phase 1: material state, Phase 2: assembly) enables 4-64ร— performance improvement. - ---- - -### `solvers/` - Linear System Solvers -**Purpose:** Solve Ku = f (direct, iterative, matrix-free) - -**Responsibility:** -- Direct solvers (Cholesky, LU) -- Iterative solvers (CG, GMRES) -- Matrix-free operators (for contact, large deformations) -- Nonlinear solvers (Newton-Raphson, line search) - -**Files:** 1 file (needs expansion) -**Exports:** TBD -**Status:** ๐Ÿ”„ Minimal (needs Krylov.jl integration) - -**Roadmap:** Implement Newton-Krylov with GMRES per golden standard (`docs/book/multigpu_nodal_assembly.md`). - ---- - -### `physics/` - High-Level Problem Definition -**Purpose:** User-facing problem setup (boundary conditions, loads, constraints) - -**Responsibility:** -- Define `Physics` type (wraps kernel + mesh + BCs) -- Dirichlet boundary conditions (prescribed displacement) -- Neumann boundary conditions (surface tractions) -- Constraint equations (MPC, contact) -- Coordinate problem assembly and solve - -**Files:** 7 files -**Exports:** `Physics`, `DirichletBC`, `NeumannBC`, `apply_bc!` -**Status:** โœ… Interface defined, implementations partial - ---- - -### `fields/` - Field Storage on Elements -**Purpose:** Store and interpolate field variables (displacement, temperature, etc.) - -**Responsibility:** -- Field definition and evaluation -- Interpolation at arbitrary points -- Time-dependent fields -- Field arithmetic - -**Files:** 2 files -**Exports:** `Field`, `eval_field` -**Status:** โš ๏ธ Needs redesign (see `llm/FIELDS_DESIGN.md`) - -**Blocker:** Old Dict-based design causes type instability. Must be resolved for v1.0. - ---- - -### `elements/` - Legacy Element Interface -**Purpose:** Old element abstraction (Element type with fields) - -**Responsibility:** -- Element struct with topology + connectivity + fields -- `update()` function (immutable API) -- Integration with old FEMBase API - -**Files:** 3 files -**Exports:** `Element`, `update` -**Status:** โš ๏ธ Legacy compatibility, dual API (modern + old) - -**Decision:** Keep for backward compatibility but encourage direct mesh/kernel usage. - ---- - -### `geometry/` - Geometric Calculations -**Purpose:** Jacobian, coordinate transformations, strain computation - -**Responsibility:** -- Compute Jacobian matrix J = โˆ‚x/โˆ‚ฮพ -- Physical derivatives โˆ‚N/โˆ‚x = Jโปยน โˆ‚N/โˆ‚ฮพ -- Strain tensor from displacement gradient -- Deformation gradient F - -**Files:** 2 files -**Exports:** `compute_jacobian`, `physical_derivatives`, `compute_strain` -**Status:** โœ… Core functionality complete - ---- - -### `backend/` - Execution Backend (CPU/GPU) -**Purpose:** Abstract backend for CPU vs GPU execution - -**Responsibility:** -- Backend abstraction (`CPUBackend`, `CUDABackend`) -- Array type selection (Array vs CuArray) -- Backend-specific optimizations - -**Files:** 2 files -**Exports:** `AbstractBackend`, `CPUBackend` -**Status:** โœ… Abstract interface defined, CPU complete, GPU planned - ---- - -### `io/` - Mesh Import/Export -**Purpose:** Read/write mesh files (Abaqus, Code Aster, Gmsh) - -**Responsibility:** -- Read Abaqus `.inp` files -- Read Code Aster `.med` files -- Read Gmsh `.msh` files -- Write VTK for visualization (planned) - -**Files:** 4 files -**Exports:** `abaqus_read_mesh`, `aster_read_mesh` -**Status:** โœ… Basic readers implemented - ---- - -### `sparse/` - Sparse Matrix Utilities -**Purpose:** Sparse matrix data structures and operations - -**Responsibility:** -- Sparse matrix CSC format -- Dictionary-of-keys (DOK) format -- Sparse vector utilities -- Conversion between formats - -**Files:** 3 files -**Exports:** `SparseDOK`, sparse utilities -**Status:** โœ… Utility module, may be replaceable by SparseArrays.jl - ---- - -## ๐Ÿ”„ Transition/Legacy Modules (Needs Decision) - -### `legacy/` - Old API Compatibility -**Purpose:** Deprecated FEMBase API for backward compatibility - -**Responsibility:** -- Old `Problem` type (deprecated) -- Old `update!` mutable API (replaced by `update()`) -- Old assembly system (replaced by assemblers/) -- Deprecation warnings - -**Files:** 18 files -**Status:** โš ๏ธ Keep for compatibility, remove in v2.0 - -**Decision:** Maintain for existing code but discourage use. Document migration path. - ---- - -### `readers/` - Legacy Mesh Readers -**Purpose:** Old mesh reading infrastructure from vendor packages - -**Responsibility:** -- Duplicate of `io/` functionality -- More complex reader infrastructure -- Keyword parsing system - -**Files:** 9 files -**Status:** โš ๏ธ **DUPLICATES `io/`** - Should consolidate - -**Action:** Merge best code into `io/`, delete `readers/`. - ---- - -### `assembly/` - Old Assembly System -**Purpose:** Pre-refactor assembly code (element-based) - -**Responsibility:** -- Element assembly (replaced by nodal assembly in `assemblers/`) -- Old problem-based API -- Framework code (superseded) - -**Files:** 7 files -**Status:** โŒ **NOT INCLUDED IN MODULE** - Dead code - -**Evidence:** Not in `src/JuliaFEM.jl` includes, not in test suite. - -**Action:** DELETE after confirming `domains/` and `assemblers/` supersede functionality. - ---- - -### `prototype/` - Experimental Physics API -**Purpose:** Testing new physics abstraction designs - -**Files:** -- `physics_modern.jl` -- `physics_modern_v2.jl` - -**Status:** โŒ **EXPERIMENTAL CODE** - Not in module - -**Action:** If superseded by `domains/` โ†’ DELETE. If still relevant โ†’ move to `llm/archive/prototypes/`. - ---- - -## ๐Ÿ—‘๏ธ Empty/Dead Directories (Delete) - -### `problems/` -**Files:** 0 -**Status:** โŒ Empty directory -**Action:** DELETE (old Problem API is in `legacy/`) - ---- - -### `utils/` -**Files:** 0 -**Status:** โŒ Empty directory -**Action:** DELETE - ---- - -## ๐Ÿ”€ Duplicate Functionality (Needs Consolidation) - -### `plates/` vs `domains/plates/` -**Current state:** -- `plates/` - 3 files (api.jl, dkt.jl, test_dkt.jl) -- `domains/plates/` - Integrated domain - -**Status:** โš ๏ธ **DUPLICATION** - -**Investigation needed:** -1. Which has more recent code? -2. Is `plates/` superseded by `domains/plates/`? -3. If yes โ†’ delete `plates/`, if no โ†’ merge into `domains/plates/` - ---- - -### `io/` vs `readers/` -**Current state:** -- `io/` - 4 files (simple readers) -- `readers/` - 9 files (complex reader infrastructure) - -**Status:** โš ๏ธ **DUPLICATION** - -**Action:** -1. Compare functionality -2. Keep best implementation -3. Merge into single `io/` directory -4. Delete `readers/` - ---- - -## ๐Ÿ“‹ Module Dependency Order - -Understanding the include order in `src/JuliaFEM.jl`: - -``` -1. topology/ # Geometry (no dependencies) -2. quadrature/ # Integration points (needs topology) -3. basis/ # Shape functions (needs topology) -4. geometry/ # Jacobian (needs basis) -5. mesh/ # Mesh structure (needs topology) -6. materials/ # Constitutive models (standalone) -7. fields/ # Field storage (needs elements) -8. assemblers/ # Assembly (needs geometry, mesh) -9. domains/ # Physics kernels (needs materials, geometry, assemblers) -10. solvers/ # Linear solvers (needs assemblers) -11. physics/ # User API (needs everything) -12. backend/ # Execution backend (orthogonal) -13. io/ # Mesh I/O (needs mesh) -``` - ---- - -## ๐ŸŽฏ Cleanup Action Plan - -### Phase 1: Delete Dead Code (Immediate) - -```bash -# Empty directories -rm -rf src/problems/ src/utils/ - -# Dead experimental code (after verification) -rm -rf src/assembly/ # Verify superseded by assemblers/ -rm -rf src/prototype/ # Move to llm/archive if needed -``` - -### Phase 2: Consolidate Duplicates (This Week) - -**Task 1: io/ vs readers/** -1. Compare implementations -2. Merge best code into `io/` -3. Delete `readers/` -4. Update imports - -**Task 2: plates/ vs domains/plates/** -1. Determine canonical version -2. Merge if needed -3. Delete duplicate -4. Update includes in `JuliaFEM.jl` - -### Phase 3: Document Each Module (Ongoing) - -Create `README.md` in each directory explaining: -- Purpose (one sentence) -- Key files and their roles -- Exports -- Usage examples -- Dependencies - -**Priority order:** -1. โœ… `mesh/README.md` (done) -2. `topology/README.md` -3. `basis/README.md` -4. `quadrature/README.md` -5. `domains/README.md` (umbrella doc) -6. `assemblers/README.md` -7. `materials/README.md` - ---- - -## ๐Ÿ“Š Directory Health Status - -| Directory | Status | Files | Action | -|-----------|--------|-------|--------| -| `topology/` | โœ… Excellent | 9 | Document | -| `basis/` | โœ… Good | 12 | Document | -| `quadrature/` | โœ… Excellent | 10 | Document | -| `mesh/` | โœ… Excellent | 7 | โœ… Documented | -| `materials/` | โœ… Good | 6 | Document | -| `assemblers/` | โœ… Good | 20 | Document | -| `domains/` | โœ… Good | 16 | Document | -| `solvers/` | ๐Ÿ”„ Minimal | 1 | Expand | -| `physics/` | ๐Ÿ”„ Partial | 7 | Complete | -| `fields/` | โš ๏ธ Needs redesign | 2 | Redesign (blocker) | -| `elements/` | โš ๏ธ Legacy | 3 | Keep for compat | -| `geometry/` | โœ… Good | 2 | Document | -| `backend/` | โœ… Good | 2 | Expand for GPU | -| `io/` | โœ… Good | 4 | Consolidate readers/ | -| `sparse/` | โœ… Utility | 3 | Review necessity | -| `legacy/` | โš ๏ธ Deprecated | 18 | Keep until v2.0 | -| `readers/` | โŒ Duplicate | 9 | **DELETE** (merge to io/) | -| `assembly/` | โŒ Dead | 7 | **DELETE** | -| `prototype/` | โŒ Experimental | 2 | **DELETE** (archive) | -| `plates/` | โš ๏ธ Duplicate? | 3 | **CONSOLIDATE** | -| `beams/` | ๐Ÿ”„ Stub | 1 | In `domains/beams/` | -| `shells/` | ๐Ÿ”„ Stub | 1 | In `domains/shells/` | -| `trusses/` | โš ๏ธ Duplicate? | 3 | In `domains/trusses/` | -| `problems/` | โŒ Empty | 0 | **DELETE** | -| `utils/` | โŒ Empty | 0 | **DELETE** | -| `formulations/` | ๐Ÿ”„ Stub | 1 | Merge to domains? | - ---- - -## ๐Ÿ† Design Principles - -1. **Single Responsibility:** Each directory has ONE clear purpose -2. **No Duplication:** Merge or delete duplicates -3. **Documentation:** Every directory has README.md -4. **Dependency Order:** Lower-level modules have fewer dependencies -5. **Type Stability:** Modern API throughout (no Dicts in hot paths) -6. **Zero Allocation:** Pre-allocated caches, tuple returns -7. **Testing:** Every module has corresponding `test/` subdirectory - ---- - -## ๐Ÿ”ฎ Future Architecture (v2.0) - -**Clean module structure:** -``` -src/ -โ”œโ”€โ”€ topology/ # Element geometry -โ”œโ”€โ”€ basis/ # Shape functions -โ”œโ”€โ”€ quadrature/ # Integration -โ”œโ”€โ”€ mesh/ # Mesh structures -โ”œโ”€โ”€ materials/ # Constitutive models -โ”œโ”€โ”€ geometry/ # Jacobian, strain -โ”œโ”€โ”€ assemblers/ # Assembly strategies -โ”œโ”€โ”€ domains/ # Physics kernels -โ”‚ โ”œโ”€โ”€ continuum/ -โ”‚ โ”œโ”€โ”€ beams/ -โ”‚ โ”œโ”€โ”€ plates/ -โ”‚ โ”œโ”€โ”€ shells/ -โ”‚ โ””โ”€โ”€ trusses/ -โ”œโ”€โ”€ solvers/ # Linear/nonlinear solvers -โ”œโ”€โ”€ physics/ # User API (BCs, problems) -โ”œโ”€โ”€ backend/ # CPU/GPU execution -โ””โ”€โ”€ io/ # Mesh I/O -``` - -**Removed:** -- `legacy/` (deleted in v2.0) -- `elements/` (merged into mesh/domains) -- `fields/` (redesigned and merged) -- All duplicate directories - ---- - -**Maintainer:** JuliaFEM Team -**Last Updated:** November 21, 2025 -**Next Review:** After consolidation phase (December 2025) - +# src/ + +Top-level layout of the JuliaFEM source tree. The package is **0.x**; the +repository is in the middle of a deliberate architectural reset toward a +**stable 1.0**. The directories below list what is currently active and where +the boundary with the legacy code lies. + +For the canonical, up-to-date architecture summary read `AGENTS.md` in +the repository root. For per-module details, follow the README files +inside each subdirectory. + +## Active modules + +| Directory | Responsibility | +|-----------------|------------------------------------------------------------------------------------------------------------------------------| +| `topology/` | Reference shapes and topological entities (`Triangle`, `Tetrahedron`, `Hexahedron`, `Vertex`, `Edge`, `Face`, `Cell`, โ€ฆ). | +| `basis/` | Shape-function families (`Lagrange{P}`, `Serendipity{P}`, plate bases) plus the symbolic generator that produces them. | +| `quadrature/` | Gauss-Legendre integration points for every supported topology. | +| `geometry/` | Jacobians, physical derivatives, strain tensors. | +| `mesh/` | Type-stable `Mesh{N, Topo}`, structured/circular generators, refinement, RCM ordering, gmsh wrapper. | +| `dofs/` | `DOF{Quantity, Entity}`, `@DOFSet`, `DOFHandler`, DOF connectivity and the field/dof-extraction infrastructure. | +| `elements/` | `Element{K, P, S, N}` template, compile-time `local_dof_layout`, DOF-extraction and field-interpolation utilities. | +| `materials/` | `LinearElastic`, `NeoHookean`, `PerfectPlasticity`, `HeatConductivity` and the trait-based dispatch used by the kernels. | +| `assemblers/` | Assembly caches, `ElementBasedAssembler` (COO/CSC) and `DOFBasedCOOAssembler`, the matrix-free `apply_K!`/`apply_M!` path. | +| `domains/` | Physics kernels per discipline: `continuum/`, `heat/`, `thermo_elastic/`. See `domains/README.md`; each subdirectory implements an `AbstractKernel`. | +| `physics/` | `AbstractPhysics` tag (`Elasticity{Dim}`, `Thermal{Dim}`), microkernel contract for the DOF-based path, formulation helpers and strain extraction. | +| `io/` | Mesh readers (Gmsh by default; Abaqus + Aster live in the optional `Legacy` submodule). | +| `sparse/` | Lightweight sparse-matrix utilities (DOK / COO). | +| `fields/` | `AbstractField` (`Displacement`, `Temperature`, `DisplacementRotation`) and the `LocalField` interpolation type. | + +## Top-level files + +- `JuliaFEM.jl` is the package entry point. It pulls in everything above + in dependency order and is the source of truth for the export list. + +## Legacy + +`legacy/` contains the older pre-reset framework code (`Problem` / `Solver` / +`Analysis`, the Dict-based field types `DCTI` / `DVTI` / `DCTV` / `DVTV`, +the `Element(Poi1, ...)` constructor family, the Abaqus mesh-reader +stack, the FEMBase-style `update!` shims, โ€ฆ). It is wrapped in +`module Legacy` and is loaded only when the environment variable +`JULIAFEM_ENABLE_LEGACY=1` is set at module-load time. Names live under +`JuliaFEM.Legacy.` and are not re-exported at the top level. + +The legacy gate is evaluated when the precompile cache is built, so +switching modes requires `Pkg.precompile()` after toggling the variable +(or deleting the cache under `~/.julia/compiled/v$VERSION/JuliaFEM/`). + +New development should not extend `legacy/`. + +## Conventions + +- File names are `lowercase_with_underscores.jl`. +- Modules avoid in-source markdown documents; sub-READMEs are the only + exception. Architectural notes and design proposals belong in `llm/`. +- Hot-path code must remain zero-allocation and type-stable; the + regression for this lives in + `test/assemblers/test_dof_based_zero_alloc.jl`. +- Greek letters are not used in code identifiers (`u`, `v`, `w` + for reference coordinates). They are fine in comments and docstrings.