New 197-line module for DOF field information:
- DOFFieldInfo struct: field, entity, component, node index
- decode_local_dof(): decodes local DOF indices to field/entity/component
- Supports single-field and multi-field DOF specifications
- Helper functions: flatten_dof_indices, fill_dof_buffer!
- Zero-allocation buffer operations
- Required dependency for dof_based_coo.jl
Enables DOF-based assembly to decode which field/entity/component each DOF represents.
New 37-line scatter function for element-based force assembly:
- Scatters element force vector to global force vector in-place
- Zero-allocation guarantee (modifies global vector directly)
- Legacy format support
- Required dependency for element_based_coo.jl
Provides core force scattering functionality for COO assembly.
New 63-line scatter function for element-based COO assembly:
- Scatters element stiffness matrix to triplet arrays (I, J, V)
- In-place operation with zero-allocation guarantee
- Capacity checking to prevent overflow
- Required dependency for element_based_coo.jl
Provides core scattering functionality for COO format assembly.
Major refactoring: replace material state cache with compositional
workspace using NamedTuple fields for better flexibility and zero-allocation.
- Rename MaterialStateCache to AssemblyMaterialWorkspace
- Change from M<:AbstractMaterialState to FieldType, StateType parameters
- Use AoS pattern: fields::Vector{FieldType} instead of separate σ, 𝔻 vectors
- Add zero-allocation field access via @generated functions
- Add extract_tangent! for type-stable zero-allocation tangent extraction
- Add get_tangent_vector, get_stress_vector helper functions
- Add @field_vector macro for compile-time field access
- Add get_stress, get_tangent, get_field accessor functions
- Update reset! to use create_zero_field and create_zero_state
- Update create_material_cache to use trait system for type inference
- Add backward compatibility alias create_assembly_workspace
- Add extensive documentation for zero-allocation usage patterns
Update kernel interface to use new material workspace API and improve
zero-allocation performance.
- Change ip.ξ to ip.coords in compute_element_stiffness!
- Add @inline to get_dof_mapping! for better inlining
- Optimize get_dof_mapping! to use indexed access instead of iteration
- Remove compute_node_contribution! function (unused)
- Update docstrings to use material_workspace instead of material_cache
- Update compute_all_blocks! example to use get_tangent_vector
- Add FIXME comment about removing B matrix computation functions
Update geometry cache to use coords field from QuadraturePoint
instead of deprecated ξ field.
- Change ip.ξ to ip.coords in create_geometry_cache function
- Update both gradient computation and detJ*w computation
Remove unused NodeCache code and simplify integration points call in
element cache creation.
- Remove NodeCache struct and create_node_cache function
- Simplify integration_points call to use auto-selected quadrature
- Remove integration_scheme parameter from create_element_cache
Refactor element-based COO assembler to use new material workspace API
and add support for GlobalMaterialCache alongside legacy API.
- Add new assemble_element! overload using GlobalMaterialCache (NEW API)
- Add new assemble! overload using GlobalMaterialCache (NEW API)
- Update legacy assemble_element! to use material_workspace and
𝔻_vec_buffer parameter
- Update legacy assemble! to use material_workspace and 𝔻_vec_buffer
- Change counter from Ref{Int} to Int for zero-allocation access
- Use extract_tangent! with pre-allocated buffer for zero-allocation
tangent extraction
- Add imports for GlobalMaterialCache and tangent extraction functions
- Update all function signatures and docstrings to reflect new API
Refactor COOCache to use AssemblyMaterialWorkspace and improve
zero-allocation performance.
- Add FieldType and StateType type parameters to COOCache struct
- Change material_cache to material_workspace field name
- Change counter from Ref{Int} to Int for zero-allocation access
- Add 𝔻_vec_buffer for pre-allocated tangent vector extraction
- Update constructor to infer FieldType and StateType from workspace
- Update reset! and extract_system to use direct counter access
- Add Tensors import and AssemblyMaterialWorkspace import
Add new DOF-by-DOF assembler and refactor material state cache type
parameters for better flexibility.
- Add DOFBasedCOOAssembler struct with comprehensive documentation
- Change AbstractMaterialStateCache from M<:AbstractMaterialState to
FieldType, StateType parameters
- Update material cache docstring to reflect new type structure
- Clarify purpose as per-element workspace vs persistent storage
Replace function stub declaration with comment pointing to canonical definition in fields/api.jl. This eliminates documentation replacement warning while preserving documentation context.
- Changed 'ξ = Vec{3}(ip.ξ)' to 'ξ = ip.ξ' in two locations
- First occurrence in ∇N_data_tuple computation
- Second occurrence in detJ_w_tuple computation
- No conversions needed since ip.ξ is now already Vec{3}
direct array parameters instead of cache structs:
- ∇N_data::Matrix{Vec{3,Float64}} - shape function gradients
- detJ_w::Vector{Float64} - integration weights
- 𝔻::Vector{SymmetricTensor{4,3,Float64,36}} - material tangent
Eliminates field access overhead from geometry_cache and material_cache.
Renamed local variable detJ_w → w to avoid shadowing parameter.
Renamed local variable 𝔻 → D to avoid shadowing parameter.
Updated docstrings with new signatures and argument descriptions.
Maintains zero-allocation performance (verified via benchmarks).
New file: src/assemblers/scatter_blocks_to_triplets_symmetric_direct.jl (124 lines)
Features:
- scatter_blocks_to_triplets_symmetric_direct!(I, J, V, counter, capacity, K_blocks, dofs, N)
- Direct array access bypassing cache indirection
- Returns counter as Int (not Ref{Int})
- Zero dynamic dispatch (verified with @code_llvm)
BREAKTHROUGH OPTIMIZATION:
- Cache struct indirection causes dispatch (cache.I[idx])
- Direct array access enables full optimization (I[idx])
- Result: 18 → 0 dispatch sites, 500K elem/s achieved
Implementation:
- Same algorithm as symmetric version
- Takes raw arrays I, J, V instead of cache
- Counter passed by value, returned as Int
- All operations @inbounds and @inline
Performance impact:
- Eliminated ALL dynamic dispatch in assembly loop
- Key to achieving zero allocations
- Critical for 500K elem/s throughput
This is the PRODUCTION version used in element_based_coo.jl.
Other scatter functions kept for reference/alternative use cases.
New file: src/assemblers/scatter_blocks_to_triplets_symmetric.jl (92 lines)
Features:
- scatter_blocks_to_triplets_symmetric!(cache, K_blocks, dofs, N)
- Exploits matrix symmetry (only store upper triangle + diagonal)
- Reduces triplet count by ~50%
- Uses cache for I, J, V, counter
Implementation:
- Outer loop: k in 1:N
- Inner loop: l in k:N (only k ≤ l, upper triangle)
- Store both (i,j) and (j,i) entries for off-diagonal
- Store only (i,i) for diagonal
Optimization over general scatter:
- Half the triplets for symmetric matrices
- Lower memory usage
- Faster sparse matrix construction
Original cache-based version before direct scatter optimization.
New file: src/assemblers/scatter_blocks_to_triplets.jl (74 lines)
Features:
- scatter_blocks_to_triplets!(I, J, V, counter, capacity, K_blocks, dofs, N)
- General scatter for unsymmetric matrices
- Stores all N×N blocks as triplets
- Returns updated counter
Implementation:
- Double loop over node pairs (N × N)
- Triple loop over DOF pairs (3 × 3 per block)
- Direct triplet storage: I[idx], J[idx], V[idx]
- Capacity checking with bounds validation
Not currently used (symmetric version preferred), but available
for unsymmetric problems like convection or non-symmetric contact.
New file: src/assemblers/scatter_blocks_to_force.jl (54 lines)
Features:
- scatter_blocks_to_force!(f_global, f_blocks, dofs, N)
- Scatters element force blocks to global force vector
- Handles 3 DOFs per node (displacement field)
- Uses @inbounds and @inline for performance
Implementation:
- Double loop over nodes (N × 3 DOFs)
- Direct vector indexing f_global[dof] += f_i[component]
- Zero allocations, zero dispatch
Part of the direct scatter strategy that achieved zero-allocation
assembly. Critical for 500K elem/s performance.
New file: src/assemblers/node_based_coo.jl
Features:
- assemble! implementation for nodal assembly
- Assembles contributions node-by-node instead of element-by-element
- Uses node_to_elements connectivity
- Accumulates blocks for all elements touching each node
Architecture:
- Outer loop over nodes (not elements)
- Inner loop over elements containing each node
- Natural for contact mechanics (contact is nodal)
Status: Experimental, proof-of-concept implementation.
Not yet optimized like element-based assembly.
New file: src/assemblers/nodal_cache.jl
Features:
- NodalCache struct with NodeCache
- Node-based assembly pattern (alternative to element-based)
- Includes reset!, extract_system functions
- create_node_cache constructor
Use case:
- Nodal assembly (assemble node-by-node, not element-by-element)
- Experimental architecture for contact mechanics
- Potential for better parallelization and domain decomposition
Status: Framework in place, not yet optimized like COO assembly.
New file: src/assemblers/material_cache.jl (247 lines)
Features:
- Parametric MaterialStateCache{StateType}
- Stores stress tensors (σ)
- Stores tangent modulus tensors (𝔻)
- Stores material state history (state, state_new)
- update_material_cache! function
State management:
- EmptyState for stateless materials (LinearElastic)
- Custom state types for plasticity (J2PlasticityState, etc.)
- State evolution tracked across load increments
Type parameter:
- StateType: Material state type (EmptyState, J2PlasticityState, etc.)
- Enables type-stable state access
Also includes ImmutableMaterialStateCache for read-only views
with @inline accessor functions.
New file: src/assemblers/element_cache.jl
Features:
- Parametric struct ElementCache{Topo, Basis, IPs}
- Stores element stiffness blocks (K_blocks)
- Stores element force blocks (f_blocks)
- Stores DOF mapping (dofs)
- create_element_cache constructor
Type parameters:
- Topo: Element topology type (Tet4, Hex8, etc.)
- Basis: Basis function type (Lagrange{Tet4,1}, etc.)
- IPs: Integration points tuple type
This cache is reused across all elements, updated once per element
in the assembly loop. Part of three-phase cache update pattern.
New file: src/assemblers/csc_cache.jl
Features:
- CSCCache with pre-allocated sparse matrix structure
- Faster than COO for fixed sparsity patterns
- Includes reset!, extract_system functions
- Uses build_sparsity_pattern for initialization
Use case:
- Problems with known, unchanging sparsity pattern
- Faster assembly than COO (no sorting overhead)
- Lower memory usage (no duplicate entries)
New file: src/assemblers/coo_cache.jl (184 lines)
Features:
- Parametric struct COOCache{EC<:ElementCache, MC<:MaterialStateCache}
- Eliminates type instability from cache field accesses
- Stores triplets (I, J, V) for sparse matrix construction
- Includes reset! and extract_system functions
Performance impact:
- Enables zero allocations in assembly loop
- Required for achieving 500K elem/s throughput
- Critical optimization for type stability
Documentation includes:
- COO format explanation
- Performance characteristics
- Use cases and trade-offs
Major changes:
- Replaced cache-based scatter with direct array scatter
- Extract counter once before loop, write once after loop
- Use scatter_blocks_to_triplets_symmetric_direct! for zero dispatch
- Use scatter_blocks_to_force! for force vector assembly
- Removed Ref{Int} indirection in counter management
Performance improvements:
- Zero allocations in assembly loop (verified with benchmarks)
- Zero dynamic dispatch (verified with @code_llvm)
- 500K elements/second throughput (5× baseline improvement)
Three-phase cache update pattern:
- update_element_cache! for DOF mapping
- update_geometry_cache! for Jacobian and gradients
- update_material_cache! for stress and tangent modulus
- Added includes for coo_cache.jl, csc_cache.jl, nodal_cache.jl
- Removed old COOCache, CSCCache, NodalCache definitions (now in separate files)
- Removed old ElementCache, NodeCache definitions (moved to element_cache.jl)
- Kept only high-level cache coordination logic
Jukka Aho