From d1fb022fccdd57d6323f86eeebfbbac8af847619 Mon Sep 17 00:00:00 2001
From: Jukka Aho <ahojukka5@gmail.com>
Date: Mon, 15 Dec 2025 06:17:34 +0200
Subject: [PATCH] feat(materials): add material trait system foundation

New 88-line material trait system:
- supported_physics(): returns tuple of supported physics types
- required_field_types(): returns tuple of required field types
- required_state_variables(): returns tuple of state variable types
- Type-level dispatch support for @generated functions
- Extensible trait system for material implementations
- Already integrated in JuliaFEM.jl (line 430)

Provides foundation for compositional material trait system.
---
 src/materials/traits.jl | 88 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 src/materials/traits.jl

diff --git a/src/materials/traits.jl b/src/materials/traits.jl
new file mode 100644
index 0000000..9881979
--- /dev/null
+++ b/src/materials/traits.jl
@@ -0,0 +1,88 @@
+# This file is a part of JuliaFEM.
+# License is MIT: see https://github.com/JuliaFEM/JuliaFEM.jl/blob/master/LICENSE.md
+
+"""
+Material trait functions using compositional state variable design.
+"""
+
+# Note: This file defines trait functions but doesn't implement them for specific materials.
+# Material implementations (linear_elastic.jl, perfect_plasticity.jl, etc.) will
+# implement these traits for their specific material types.
+
+# ============================================================================
+# PHYSICS SUPPORT TRAITS
+# ============================================================================
+
+"""
+    supported_physics(material)
+
+Returns tuple of physics types that this material supports.
+"""
+function supported_physics end
+
+"""
+    required_field_types(material)
+
+Returns tuple of field types required by this material.
+"""
+function required_field_types(material)
+    physics_tuple = supported_physics(material)
+    # Extract field types from each physics
+    map(p -> required_field_type(p), physics_tuple)
+end
+
+# ============================================================================
+# STATE VARIABLE TRAITS
+# ============================================================================
+
+"""
+    required_state_variables(material)
+
+Returns tuple of state variable types required by this material.
+"""
+function required_state_variables end
+
+# Type-level dispatch for required_state_variables (for @generated functions)
+required_state_variables(::Type{T}) where {T<:AbstractMaterial} = required_state_variables(T())
+
+# ============================================================================
+# MATERIAL-SPECIFIC TRAIT IMPLEMENTATIONS
+# ============================================================================
+
+# NOTE: Trait implementations for specific materials (LinearElastic, PerfectPlasticity, etc.)
+# are defined in their respective material files (linear_elastic.jl, perfect_plasticity.jl, etc.)
+# This keeps the trait system extensible - new materials just implement these three traits:
+#   - supported_physics(::MyMaterial)
+#   - required_state_variables(::MyMaterial)
+# and the rest (required_field_types, etc.) is automatically derived.
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+"""
+    get_state_variable_types(material)
+
+Returns tuple of concrete types for all state variables.
+"""
+function get_state_variable_types(material)
+    vars = required_state_variables(material)
+    map(v -> state_variable_type(v), vars)
+end
+
+"""
+    get_state_variable_symbols(material)
+
+Returns tuple of default symbols for all state variables.
+"""
+function get_state_variable_symbols(material)
+    vars = required_state_variables(material)
+    map(v -> default_symbol(v), vars)
+end
+
+"""
+    is_stateful(material)
+
+Returns true if material has state variables, false otherwise.
+"""
+is_stateful(material) = !isempty(required_state_variables(material))