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.
New 91-line state variable trait system:
- AbstractStateVariable: base type for state variables
- state_variable_type(), default_symbol(): state variable traits
- PlasticStrain, Backstress, EquivalentPlasticStrain: example implementations
- Compositional design: state variables are independent building blocks
- Already integrated in JuliaFEM.jl (line 425)
Provides extensible state variable system for material state management.
New 362-line material cache system:
- GlobalMaterialCache{StateType}: stores state variables at all IPs/elements
- material_state_type(): infer state NamedTuple type from material traits
- create_global_material_cache(): factory function with automatic type inference
- create_zero_state(): zero-initialize state NamedTuples
- Supports stateless (empty NamedTuple) and stateful materials
- Type-stable NamedTuple-based storage
- Zero-allocation state updates (functional style)
- Already integrated in JuliaFEM.jl (line 437)
Provides persistent state storage for time-stepping and material state management.
New 140-line material field trait system:
- required_material_fields(): define fields required by physics (Elasticity, Thermal)
- material_field_type(): infer field NamedTuple type from material's supported physics
- compose_field_types(): compose multiple NamedTuple types for multi-physics
- Supports Elasticity (σ, 𝔻) and Thermal (q, k) physics
- Type-stable field type inference
- Already integrated in JuliaFEM.jl (line 431)
Provides compositional field design for material-physics coupling.
Removed verbose documentation sections:
- Removed extensive theory documentation (yield function, flow rule, hardening law, consistency condition)
- Removed detailed algorithm step-by-step explanations (radial return mapping)
- Removed type hierarchy, construction examples, and derived properties
- Removed performance notes and timing information
- Removed detailed function documentation with algorithm steps
Simplified docstrings to essential information about material parameters and function signatures.
Removed verbose documentation sections:
- Removed detailed theory explanations and strain energy formulas from module docstring
- Removed type hierarchy, properties, and construction examples
- Removed detailed function documentation with usage examples
- Removed performance notes and automatic differentiation explanations
- Removed stress conversion formulas and notes
Simplified docstrings to essential formulas (strain energy, stress computation) and function signatures.
Removed verbose documentation sections:
- Removed detailed theory explanations and formulas from module docstring
- Removed type hierarchy and properties sections
- Removed usage examples from function docstrings
- Removed performance notes and implementation details
- Simplified docstrings to essential formulas (Hooke's law, elasticity tensor)
Kept core mathematical formulas and function signatures.
Removed verbose documentation sections:
- Removed detailed theory references (Simo & Hughes)
- Removed algorithm step-by-step explanations
- Removed performance notes and timing information
- Removed detailed field descriptions and invariants
- Simplified docstrings to essential information about fields and function signatures
Kept core information about multiplicative decomposition and material parameters.
Removed extensive documentation from material API docstrings:
- Removed detailed interface requirements sections
- Removed type hierarchy explanations
- Removed design philosophy sections
- Removed usage examples and 'See Also' references
- Kept only essential type and function descriptions
This simplifies the API documentation while maintaining core information
about material types and their behavior traits.
Replace monolithic PlasticityState struct with compositional NamedTuple
state system and add new material trait system support.
- Remove PlasticityState struct (now using NamedTuple composition)
- Add supported_physics trait (Elasticity{3})
- Add required_state_variables trait (PlasticStrain, Backstress, EquivalentPlasticStrain)
- Change compute_stress to use NamedTuple for state_old and state_new
- Use get() with defaults for state extraction (handles empty initial state)
- Update state creation to use NamedTuple syntax (ε_p, α, κ)
- Remove state_type trait (replaced by required_state_variables)
Update LinearElastic to support new material trait system and
compositional state design with NamedTuple instead of Nothing.
- Add supported_physics trait (Elasticity{3})
- Add required_state_variables trait (empty tuple for stateless)
- Change state_old parameter to Union{Nothing,NamedTuple}
- Return NamedTuple() instead of nothing for state update
- Support compositional state system in compute_stress
Update AbstractMaterialState and EmptyState docstrings to reference
new AssemblyMaterialWorkspace and GlobalMaterialCache instead of
old MaterialStateCache API.
Replace function stub declaration with comment pointing to canonical definition in materials/api.jl. Preserves comprehensive documentation about stress computation interface.
Eliminates documentation replacement warning while maintaining API contract documentation.
- Add material_behavior(::PerfectPlasticity) = StatefulStrainDependent()
- Enables generic integration with state variable handling
- Requires displacement field and state for tangent computation
- Single line trait declaration, zero code duplication
- Add material_behavior(::NeoHookean) = StatelessStrainDependent()
- Enables generic integration to compute tangent at each IP
- Requires displacement field for strain-dependent tangent
- Single line trait declaration, zero code duplication
- Add material_behavior(::LinearElastic) = StatelessConstantTangent()
- Enables generic integration to optimize constant tangent case
- Single line trait declaration, zero code duplication
- Integration computes tangent once and reuses for all IPs
- Define MaterialBehavior abstract type for material classification
- Add StatelessConstantTangent trait for linear elastic materials
- Add StatelessStrainDependent trait for hyperelastic materials
- Add StatefulStrainDependent trait for plastic materials
- Implement material_behavior() trait function interface
- Add needs_deformation() and needs_state() helper queries
- Document trait system with comprehensive examples
- Enable generic integration without material-specific code duplication
- 148 lines of trait definitions and documentation
Why: Solves the problem of replicating compute_block! for each material type.
With 100 materials, we'd have 100 copies of integration code. Traits provide
a standardized interface that integration code can query at compile time.
- Change return type from Tensor{4,3} to SymmetricTensor{4,3}
- Construct full 81-component tensor then convert to symmetric form
- Matches NeoHookean return type for API consistency
- Properly encodes material symmetry (C_ijkl = C_jikl = C_ijlk = C_klij)
Convert elasticity_tensor() to compile-time generation.
Before (672 bytes in test context):
- Runtime array comprehension for 81 tensor components
- Tuple conversion caused allocations
- Type instability from generic Tensor{4,3} constructor
After (0 bytes):
- @generated function pre-computes all 81 components at compile time
- Returns concrete Tensor{4,3,Float64,81} type
- Zero runtime allocations
Algorithm:
- Compute symbolic expressions for C_{ijkl} at compile time
- Generate optimized code with only λ_val, μ_val runtime parameters
- Tensor construction happens entirely at compile time
Result: 672 bytes → 0 bytes (100% reduction)
Note: This was part of the optimization but not the primary fix.
The main issue was ips::Any type instability in ElementCache.
Create src/materials/api.jl defining material-specific abstractions:
- AbstractMaterial base type for all material models
- AbstractElasticMaterial for stateless materials (no history)
- AbstractPlasticMaterial for stateful materials (history-dependent)
- compute_stress() interface (strain → stress + tangent + updated state)
- elasticity_tensor() for elastic constitutive relations
Material models use Tensors.jl (no Voigt notation). Elastic materials
are stateless (LinearElastic, NeoHookean). Plastic materials have internal
state (plastic strain εᵖ, backstress α, hardening κ, damage).
Interface returns (σ, 𝔻, state_new) where 𝔻 is the material tangent ∂σ/∂ε.
Part of systematic modular API architecture.
Add elasticity_tensor(material::LinearElastic) function that returns
the 4th-order elasticity tensor C_{ijkl} for assembly.
Formula: C_{ijkl} = λ δ_{ij} δ_{kl} + μ (δ_{ik} δ_{jl} + δ_{il} δ_{jk})
Returns Tensor{4,3,Float64} for direct use in stiffness assembly:
K_ij^{αβ} = ∫ (∂N_i/∂x_γ) C_{αβγδ} (∂N_j/∂x_δ) dV
This eliminates need for Voigt notation and B-matrices in assembly,
enabling pure tensor mathematics (Tensors.jl).
Used by CPU backend (src/backend/cpu.jl) in compute_element_stiffness().
Foundation for GPU implementation (same tensor approach).
Comment out AbstractMaterial, AbstractElasticMaterial, and
AbstractPlasticMaterial definitions in abstract_material.jl.
These types are now defined in src/api.jl which is included first,
avoiding forward reference and circular dependency issues.
Documentation and concrete implementations remain in this file.
This fixes include order problems where materials needed to be defined
before physics_api.jl but physics_api.jl needed the abstract types.
New file src/materials/finite_strain_plasticity.jl implementing J2 plasticity for large deformations:
- FiniteStrainPlasticityState storing F_p (plastic deformation gradient), α_bar (backstress), κ
- FiniteStrainPlasticity struct with E, ν, σ_y, H parameters
- Hyperelastic stress response using Neo-Hookean
- Exponential map integration for plastic flow
- Pull-back/push-forward operations for intermediate configuration
- Consistent algorithmic tangent for Newton convergence
- 293 lines with comprehensive finite deformation theory
New file src/materials/neo_hookean.jl implementing simplest hyperelasticity:
- NeoHookean struct with shear modulus μ and Lamé parameter λ
- Convenience constructor from E and ν engineering constants
- strain_energy() computes ψ = μ/2·(I₁-3) - μ·ln(J) + λ/2·ln²(J)
- Stress S = 2·∂ψ/∂C via automatic differentiation
- Tangent 𝔻 = 4·∂²ψ/∂C² via automatic differentiation
- Uses Tensors.jl built-in AD (no ForwardDiff dependency)
- Total Lagrangian formulation with 2nd PK stress
- 253 lines with comprehensive theory documentation
New file src/materials/abstract_material.jl defining material model architecture:
- AbstractMaterial base type for all materials
- AbstractElasticMaterial for stateless materials (no history)
- AbstractPlasticMaterial for stateful materials (plastic strain, etc.)
- compute_stress() interface: (material, ε, state_old, Δt) → (σ, 𝔻, state_new)
- State management convention for Newton iterations
- Thread-safe and GPU-compatible design principles
- 229 lines with comprehensive documentation and examples
Jukka Aho