JuliaFEM.jl/src/README.md

# 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)