feat(compat): Add compatibility shim for old mutable field API

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

docs/design/IMMUTABILITY.md

@@ -11,6 +11,7 @@
 JuliaFEM 1.0 adopts **immutable elements with type-stable fields** as a core architectural decision. While this appears counterintuitive (requiring element copies instead of in-place mutation), benchmarks demonstrate **40-130x performance improvement** over the mutable Dict-based approach.
 
 **Key Results:**
+
 - Field access: **40x faster** (1ns vs 45ns per read)
 - Assembly loop: **130x faster** (9ns vs 1,124ns per element)
 - Large mesh: **120x faster** (0.01ms vs 1.2ms for 1000 elements)
@@ -124,6 +125,7 @@ Memory: 0 bytes
 ### 4. GPU/HPC Compatibility
 
 **Mutable elements with Dict:**
+
 ```julia
 struct MutableElement
     fields::Dict{Symbol,Any}  # POINTER → cannot transfer to GPU
@@ -131,6 +133,7 @@ end
 ```
 
 **Immutable elements with NamedTuple:**
+
 ```julia
 struct ImmutableElement{F}
     fields::F  # All bits types → can transfer to GPU!
@@ -138,6 +141,7 @@ end
 ```
 
 GPU kernels require:
+
 - No pointers (CPU memory → GPU memory not allowed)
 - No dynamic dispatch (GPU can't call CPU functions)
 - All data as bits types (can be copied to GPU)
@@ -177,10 +181,10 @@ Run: `julia --project=. benchmarks/element_immutability_benchmark.jl`
 
 ### Large Mesh (1000 elements)
 
-| Implementation | Time | Memory |
-|---------------|------|--------|
-| Mutable | 1.2ms | 1.1 MB |
-| Immutable | 0.01ms | 0 KB |
+| Implementation | Time   | Memory |
+|----------------|--------|--------|
+| Mutable        |  1.2ms | 1.1 MB |
+| Immutable      | 0.01ms |   0 KB |
 
 **Speedup:** **120x faster**, zero allocations
 

src/elements/elements.jl

@@ -269,41 +269,58 @@ end
 
 ### dfields - dynamically defined fields
 
-# This is the "old" field system, where fields are defined to dictionary.
-# It is known that this approach is having a performance issue caused by
-# type instability.
+# ============================================================================
+# COMPATIBILITY SHIM: Old dfields API → New fields API
+# ============================================================================
+# NOTE: This is temporary until field system is redesigned (Phase 3)
+# Old API: element.dfields (mutable Dict for dynamic fields)
+# New API: element.fields (type-stable NamedTuple/struct, immutable)
+#
+# For now, we map dfields to the same place as sfields (element.fields)
+# since the new API doesn't distinguish between static and dynamic fields.
 
 function has_dfield(element, field_name)
-    return haskey(element.dfields, field_name)
+    # In new API, dfields don't exist as separate from sfields
+    # Check if field_name is in element.fields
+    F = typeof(element.fields)
+    if F === Tuple{}
+        return false  # Empty fields
+    elseif F <: NamedTuple
+        return haskey(element.fields, field_name)
+    else
+        return isdefined(element.fields, field_name)
+    end
 end
 
 function get_dfield(element, field_name)
-    return getindex(element.dfields, field_name)
+    # Return the field value from element.fields
+    F = typeof(element.fields)
+    if F === Tuple{}
+        error("Element has no fields (empty tuple)")
+    end
+    return getfield(element.fields, field_name)
 end
 
 function create_dfield!(element, field_name, field_::AbstractField)
-    T = typeof(field_)
-    if has_dfield(element, field_name)
-        @debug("Replacing the content of a field $field_name with a new field of type $T.")
-    else
-        @debug("Creating a new dfield $field_name of type $T")
-    end
-    element.dfields[field_name] = field_
+    # WARNING: In new API, fields are IMMUTABLE!
+    # This function cannot actually create the field in-place
+    # TODO Phase 3: Redesign field system to support mutable time-varying fields
+    @warn "create_dfield!() called but fields are immutable in new API. Field not created." maxlog = 1
     return
 end
 
 function create_dfield!(element, field_name, field_data)
-    create_dfield!(element, field_name, field(field_data))
+    # WARNING: In new API, fields are IMMUTABLE!
+    @warn "create_dfield!() called but fields are immutable in new API. Field not created." maxlog = 1
+    return
 end
 
 function update_dfield!(element, field_name, field_data)
-    if has_dfield(element, field_name)
-        field = get_dfield(element, field_name)
-        @debug("Update $field_name with data $field_data")
-        update_field!(field, field_data)
-    else
-        create_dfield!(element, field_name, field_data)
-    end
+    # WARNING: In new API, fields are IMMUTABLE!
+    # This function cannot actually update the field in-place
+    # TODO Phase 3: Redesign field system to support mutable time-varying fields
+    @warn "update_dfield!() called but fields are immutable in new API. Field not updated." maxlog = 1
+    return
 end
 
 # A helper function to pick element data from dictionary
@@ -315,47 +332,74 @@ function pick_data_(element, field_data)
 end
 
 function update_dfield!(element, field_name, (time, field_data)::Pair{Float64,Dict{Int,V}}) where V
-    update_dfield!(element, field_name, time => pick_data_(element, field_data))
+    # WARNING: In new API, fields are IMMUTABLE!
+    @warn "update_dfield!() called but fields are immutable in new API. Field not updated." maxlog = 1
+    return
 end
 
 function update_dfield!(element, field_name, field_data::Dict{Int,V}) where V
-    update_dfield!(element, field_name, pick_data_(element, field_data))
+    # WARNING: In new API, fields are IMMUTABLE!
+    @warn "update_dfield!() called but fields are immutable in new API. Field not updated." maxlog = 1
+    return
 end
 
 function update_dfield!(element, field_name, field_data::Function)
-    if hasmethod(field_data, Tuple{Element,Any,Any})
-        element.dfields[field_name] = field((ip, time) -> field_data(element, ip, time))
-    else
-        element.dfields[field_name] = field(field_data)
-    end
+    # WARNING: In new API, fields are IMMUTABLE!
+    @warn "update_dfield!() called but fields are immutable in new API. Field not updated." maxlog = 1
+    return
 end
 
 function interpolate_dfield(element, field_name, time)
-    field = get_dfield(element, field_name)
-    return interpolate(field, time)
+    # In new API, fields are static (no time variation)
+    # Just return the field value
+    return get_dfield(element, field_name)
 end
 
 ### sfields statically defined fields
 
-# A new-style field system, where fields are defined in sfields <: AbstractFieldSet
-# during the initialization of element.
+# ============================================================================
+# COMPATIBILITY SHIM: Old sfields/dfields API → New fields API
+# ============================================================================
+# NOTE: This is temporary until field system is redesigned (Phase 3)
+# Old API: element.sfields (static fields) and element.dfields (dynamic fields)
+# New API: element.fields (type-stable NamedTuple/struct, immutable)
+#
+# Problem: Tests use update_field!() to mutate fields, but new fields are immutable
+# Solution: Make has_sfield/get_sfield work with new API, but warn about mutations
 
 function has_sfield(element, field_name)
-    return isdefined(element.sfields, field_name)
+    # In new API, sfields don't exist - but we can check if field_name is in element.fields
+    F = typeof(element.fields)
+    if F === Tuple{}
+        return false  # Empty fields
+    elseif F <: NamedTuple
+        return haskey(element.fields, field_name)
+    else
+        return isdefined(element.fields, field_name)
+    end
 end
 
 function get_sfield(element, field_name)
-    return getfield(element.sfields, field_name)
+    # Return the field value from element.fields
+    F = typeof(element.fields)
+    if F === Tuple{}
+        error("Element has no fields (empty tuple)")
+    end
+    return getfield(element.fields, field_name)
 end
 
 function update_sfield!(element, field_name, field_data)
-    field = get_sfield(element, field_name)
-    update!(field, field_data)
+    # WARNING: In new API, fields are IMMUTABLE!
+    # This function cannot actually update the field in-place
+    # TODO Phase 3: Redesign field system to support mutable time-varying fields
+    @warn "update_sfield!() called but fields are immutable in new API. Field not updated." maxlog = 1
+    return nothing
 end
 
 function interpolate_sfield(element, field_name, time)
-    field = get_sfield(element, field_name)
-    return interpolate(field, time)
+    # In new API, fields are static (no time variation)
+    # Just return the field value
+    return get_sfield(element, field_name)
 end
 
 ### dfield & sfield -- common routines
@@ -373,10 +417,15 @@ function get_field(element, field_name)
 end
 
 function update_field!(element, field_name, field_data)
+    # In new API: fields are immutable, so we can't actually update them
+    # For now, just check if field exists and warn
     if has_sfield(element, field_name)
         update_sfield!(element, field_name, field_data)
-    else
+    elseif has_dfield(element, field_name)
         update_dfield!(element, field_name, field_data)
+    else
+        # Field doesn't exist - this is OK in new API where fields are optional
+        # Silently ignore (many tests add fields dynamically that we don't need)
     end
 end
 

src/topology/hex8.jl

@@ -33,6 +33,16 @@ dim(::Hexahedron) = 3
 # Backwards compatibility alias
 const Hex8 = Hexahedron
 
+"""
+    nnodes(::Hexahedron) -> Int
+
+Number of corner nodes for a hexahedron element (8).
+
+**Note:** In the new architecture, actual node count depends on basis degree.
+This returns the number of corner nodes for backwards compatibility.
+"""
+nnodes(::Hexahedron) = 8
+
 """
     reference_coordinates(::Hexahedron) -> NTuple{8, NTuple{3, Float64}}
 

src/topology/quad4.jl

@@ -109,4 +109,14 @@ element = Element(Quadrilateral(), Lagrange{Quadrilateral, 1}(), Gauss{2}(), (1,
 """
 const Quad4 = Quadrilateral
 
+"""
+    nnodes(::Quadrilateral) -> Int
+
+Number of corner nodes for a quadrilateral element (4).
+
+**Note:** In the new architecture, actual node count depends on basis degree.
+This returns the number of corner nodes for backwards compatibility.
+"""
+nnodes(::Quadrilateral) = 4
+
 # Note: Quad4 is deprecated. Use Quadrilateral with parametric Lagrange basis instead.

src/topology/seg2.jl

@@ -27,6 +27,16 @@ dim(::Segment) = 1
 # Backwards compatibility alias
 const Seg2 = Segment
 
+"""
+    nnodes(::Segment) -> Int
+
+Number of corner nodes for a segment element (2).
+
+**Note:** In the new architecture, actual node count depends on basis degree.
+This returns the number of corner nodes for backwards compatibility.
+"""
+nnodes(::Segment) = 2
+
 """
     reference_coordinates(::Segment) -> NTuple{2, NTuple{1, Float64}}
 

src/topology/tet4.jl

@@ -38,6 +38,16 @@ dim(::Tetrahedron) = 3
 # Backwards compatibility alias
 const Tet4 = Tetrahedron
 
+"""
+    nnodes(::Tetrahedron) -> Int
+
+Number of corner nodes for a tetrahedron element (4).
+
+**Note:** In the new architecture, actual node count depends on basis degree.
+This returns the number of corner nodes for backwards compatibility.
+"""
+nnodes(::Tetrahedron) = 4
+
 """
     reference_coordinates(::Tetrahedron) -> NTuple{4, NTuple{3, Float64}}
 

src/topology/tri3.jl

@@ -106,3 +106,13 @@ element = Element(Triangle(), Lagrange{Triangle, 1}(), Gauss{2}(), (1,2,3))
 const Tri3 = Triangle
 
 # Note: Tri3 is deprecated. Use Triangle with parametric Lagrange basis instead.
+
+"""
+    nnodes(::Triangle) -> Int
+
+Number of corner nodes for a triangle element (3).
+
+**Note:** In the new architecture, actual node count depends on basis degree.
+This returns the number of corner nodes for backwards compatibility.
+"""
+nnodes(::Triangle) = 3