Major architectural refactoring: replace old field-based element system
with modern DOF-based design following Ciarlet's finite element triple.
- Redesign Element from Element{N,NIP,F,B} to Element{K,P,S,N}
- Replace connectivity with dof_indices (flat tuple of global DOF indices)
- Remove all old field system (sfields, dfields, fields, update_field!, etc.)
- Remove old constructors and compatibility shims
- Add compile-time DOF computation via @generated ndofs(K, S)
- Add field_dof_range for compile-time local DOF range computation
- Add local_to_global_map for type-stable DOF mapping
- Add topology_type, basis_type, dof_type query functions
- Add element_id, element_dofs, n_element_dofs, nnodes accessors
- Remove 593 lines of legacy code (963 → 370 lines)
- Simplify API: elements now store DOF indices, not node connectivity
- Support multi-field elements via DOFSet specifications
- Zero-allocation design with compile-time type information
- Changed Element(::Type{T}, connectivity) to use Lagrange{order} instead of Lagrange{base_topo,order}
- Commented out old API functions using Lagrange{T,P}: _create_topology_instance, jacobian, get_basis, get_dbasis (lines 680-761)
- Commented out get_integration_points_from_basis (lines 854-883)
- Restored get_base_topology function (needed by Element constructor)
- Updated comment explaining new API: topology passed separately, not in type parameter
Migrate element basis evaluation functions to use new topology-aware API.
Changes:
- Add _create_topology_instance() helper to construct topology from Lagrange{T,P}
- Update get_basis() to call get_basis_functions(topology, basis, xi)
- Update get_dbasis() to call get_basis_derivatives(topology, basis, xi)
- Add jacobian() function with embedding support (1D element in 2D/3D space)
- Constraint: B <: Lagrange added to method signatures
Migration from OLD API:
- eval_basis!(B, T, xi) → get_basis_functions(topology, basis, xi)
- eval_dbasis!(B, xi) → get_basis_derivatives(topology, basis, xi)
Maintains compatibility: still returns matrices/vectors for old code interface.
- get_integration_points_from_basis() maps Lagrange types to Gauss quadrature
- get_base_topology() maps deprecated names to base topology (Tri6→Triangle)
- Use get_gauss_points!() for zero-allocation integration
- Fix interpolate() to handle both AbstractField and raw data
- Fix Jacobian computation: preserve connectivity order in Dict→Vec conversion
- Support order parameter for increased quadrature accuracy
- Gauss orders 1-5 supported for all topologies
- Implement update() that returns new element (immutable pattern)
- Supports keyword arguments for ergonomic field updates
- Preserves backward compatibility with update!() (legacy)
- Dual-API approach: modern immutable + legacy mutable both supported
- 82 lines including documentation and examples
- See docs/book/fundamentals_element_creation.md for usage guide
Rewrote test_elasticity_1d.jl to follow immutable element pattern.
This is the first fully working test with the new architecture!
Changes:
1. test/test_elasticity_1d.jl:
- Convert Dict node data to element-local tuple format
- Wrap data in DVTI field objects (Discrete, Variable, Time-Invariant)
- Create element with fields at construction: Element(Seg2, conn; fields=(...))
- Fix Jacobian shape expectation (3×1 not 1×3 for 1D in 3D)
2. src/JuliaFEM.jl:
- Add minimal jacobian() function for AbstractBasis (non-parametric)
- Handles embedding (1D element in 3D space) correctly
- Returns Matrix instead of Tensor for flexibility
3. src/elements/elements.jl:
- Fix Jacobian computation to handle both Tuple and IntegrationPoint
- Fix detJ calculation logic for embedded elements (check m not size(JT,2))
- Correctly handle 1D elements: detJ = ||∂X/∂ξ||
Result: test_elasticity_1d.jl passes! ✓
This validates the immutable architecture:
- Element created with fields at construction
- No mutation needed during test
- Field system integration working (DVTI fields)
- Jacobian computation working for embedded elements
Implements compatibility layer to allow old test code to run with new
immutable element design (though fields won't actually update).
src/elements/elements.jl:
- Replaced has_dfield/get_dfield to work with new fields API
- Fixed get_sfield/get_dfield to handle empty Tuple{} fields
- All dfield functions now map to element.fields (immutable NamedTuple)
src/topology/*.jl (seg2, tri3, quad4, tet4, hex8):
- Added nnodes() implementation for each topology type
- Returns corner node count (backwards compatibility)
- Example: nnodes(::Triangle) = 3, nnodes(::Hexahedron) = 8
- Note: Actual node count depends on basis degree in new architecture
Test Results:
- test_topology_standalone.jl: 36/36 tests passing ✓
- Full test suite: 43 errors (same as before)
- Error breakdown:
* 40+ tests: Problem types not defined (Elasticity, Heat, Mortar)
* 2 tests: Mesh readers not defined (aster_read_mesh)
* 1 test: Tries to mutate empty element (test_elasticity_1d)
Next Steps:
- Tests that create empty elements then mutate need rewriting
- Pattern: Element(Seg2, (1,2)) + update!() → not compatible
- New pattern: Element(..., fields=(geometry=X, displacement=u))
- See docs/design/IMMUTABILITY.md for migration guide
- Commented out topology_to_basis() helper and old Element constructors
- These mapped old names (Tri3→Tri3Basis) which no longer exist
- Need to update for new Lagrange{Topology, P} parametric architecture
- Added TODO comment explaining migration needed
- Temporary measure until new Element constructors are implemented
Changed Point from 'mutable struct' to 'struct'.
The Dict for fields remains a reference type, so field updates via setindex!
and update! still work correctly. This change improves type stability and
enables better compiler optimizations.
Benefits:
- Better compiler optimizations (immutable types)
- Type stability improvements
- Stack allocation when possible
- No breaking changes (Dict fields still mutable)
Tests: All 157 tests passing
MAJOR PERFORMANCE REFACTORING:
1. Shape functions return tuples instead of allocating vectors:
- eval_basis!(): Returns NTuple{N,T} directly (zero allocations)
- eval_dbasis!(): Returns NTuple{N,Vec{D}} directly (zero allocations)
- API boundary (get_basis/get_dbasis) still returns vectors for compat
2. Element is now immutable with compile-time known structure:
- connectivity: Vector{UInt} → NTuple{N,UInt}
- integration_points: Vector{IP} → NTuple{NIP,IP}
- Element{N,NIP,M,B} parametrized by connectivity/IP count
- Changed from 'mutable struct' to 'struct'
3. Helper function for immutability:
- with_integration_points(element, ips) returns new element
- get_integration_points() returns tuple directly
Benefits:
- Zero allocations in hot paths (basis evaluation)
- Compile-time sizes enable better optimization
- Type stability improvements
- Stack allocation instead of heap
Breaking changes:
- Element.connectivity is now tuple (use collect() for vector)
- Element is immutable (use with_integration_points for updates)
Tests: All 157 tests passing
Gmsh returns node and element IDs as UInt64, so we should use unsigned
integers consistently throughout JuliaFEM to avoid unnecessary conversions.
Changes:
- Point.id: Int → UInt
- Element.id: Int → UInt
- Element.connectivity: Vector{Int} → Vector{UInt}
- Element constructors: Accept Integer (converts to UInt internally)
- Default element_id: -1 → 0 (UInt has no negative values)
Benefits:
- Direct compatibility with Gmsh.jl (no Int/UInt conversions)
- Semantically correct (node/element IDs are never negative)
- Slightly more efficient (no sign checks)
Tests: All 156 tests passing
Closes#267
Major architectural decision: Use Tensors.jl consistently everywhere
for geometric vectors, integration points, and coordinates.
Changes to src/elements/elements.jl:
- get_basis(): Convert ip to Vec, use Vector (not Matrix) for eval_basis!
- get_dbasis(): Convert ip to Vec
- jacobian evaluation: Convert geometry and ip.coords to Vec properly
- Handle both raw coordinates (Tuple) and IP struct transparently
New Tutorial 3: Numerical Integration and Jacobian (49 tests)
- Integration point structure and weights
- Jacobian determinant and matrix evaluation
- Numerical integration (constant, linear, quadratic functions)
- Multiple element types (Quad4, Seg2, Tri3)
Tests: 107 → 156 passing (49 new)
Runtime: ~7 seconds
Closes architectural standardization on Tensors.jl.
Related to Issue #250 (merge conflict resolution).
Why Tensors.jl:
- Type stability (100× performance vs Dict-based)
- Material science compatibility (stress tensors)
- Zero-cost abstractions
- Consistent API across all geometric calculations
Jukka Aho