To the memory of my mentor, Nik Petrinic.
For the many nights we spent discussing finite elements, and the curiosity and passion for research you shared so generously. I cherish those conversations and carry their inspiration with me as I strive to become a better researcher.
WaveCore is an experimental explicit finite-element code for elastodynamics, wave propagation, and future fracture-mechanics research.
The repository currently contains a 9E77 tested finite-element core and the first explicit dynamics systems, including reusable simulation orchestration and scheduled output callbacks. A mesh loader is not yet implemented.
WaveCore uses a typed, data-oriented ECS model. Archetypes own components; relations own indexes between entities; systems join and update the data.
NodeArchetype
ElementArchetype<Element>
MaterialArchetype<Material>
GaussPointArchetype<Element, Material>
FrameArchetype<Dimension>
FrameConnectionArchetype
ElementNodeRelation
ElementGaussPointRelation
GaussPointMaterialRelation
FrameZoneNodeRelation
The archetypes have separate responsibilities:
NodeArchetypeowns nodal components such as coordinates, velocity, and forces.ElementArchetype<Element>owns element-level components such as properties.MaterialArchetype<Material>owns shared constitutive definitions and parameters.GaussPointArchetype<Element, Material>owns integration-point geometry and material history, including stress.FrameArchetype<Dimension>owns coupling-point coordinates, gathered mass, initial velocity, forces, and common acceleration in 2D or 3D.FrameConnectionArchetypeowns the connection weights.
Connectivity is not embedded in the element archetype. It is relational data:
ElementNodeRelation
element_id → node_ids[local_node]
ElementGaussPointRelation
element_id → gauss_point_ids[local_gauss_point]
GaussPointMaterialRelation
gauss_point_id → material_id
FrameZoneNodeRelation
connection_id → frame_point, zone, zone_local_node
This keeps archetypes as component stores and lets systems join them without creating ownership dependencies between archetypes.
Quad4 is a reusable element formulation and kernel. It owns no per-element
coordinates, connectivity, geometry, velocity, or material history. It
operates on caller-owned components:
element.refresh_geometry(nodes, connectivity, geometry);
element.gather_velocities(nodes, connectivity, velocities);
auto strain_rate = element.strain_rate_tensor(geometry, velocities);
auto forces = element.internal_force(stresses, properties, geometry);Material types similarly define constitutive behavior and state layout without owning the states. A new element or material implements its concept; the archetype and relation infrastructure remains generic.
Systems perform the joins and update components. For example:
GeometrySystem
NodeArchetype + ElementArchetype + ElementNodeRelation
→ GaussPoint geometry components
MaterialUpdateSystem
GaussPoint components + MaterialArchetype
→ GaussPoint material-state components
ForceAssemblySystem
GaussPoint stress/geometry + ElementNodeRelation
→ nodal internal forces
An archetype may be read or updated by multiple systems. The archetype does not know which systems use it.
The stress and constitutive history belong to Gauss-point entities, not shared material definitions. One material definition may therefore serve many Gauss points while every Gauss point retains independent history.
Node<Dimension>provides two- and three-dimensional nodal value types.Quad4implements a two-dimensional four-node quadrilateral with one centre Gauss point.LinearElasticPlaneStrainimplements isotropic small-strain plane-strain elasticity.ElementArchetype,MaterialArchetype, andGaussPointArchetypeprovide typed component storage.- Relation classes provide external element/node, element/Gauss-point, and Gauss-point/material indexes.
FrameArchetype,FrameConnectionArchetype, andFrameZoneNodeRelationprovide Frame components, weights, and flat zone-node connections.- Frame systems build coincident connections, gather mass/initial velocity/forces, and scatter common acceleration before the second half velocity update.
scatter_forceaccumulates local forces into shared nodes.
include/wavecore/archetypes/ Typed component stores
include/wavecore/relations/ External relationship indexes
include/wavecore/elements/ Element formulations and properties
include/wavecore/materials/ Material concepts and constitutive models
include/wavecore/mesh/ Node/Frame views and force scattering
include/wavecore/systems/ Finite-element, Frame, and dynamics systems
tests/ Component and numerical tests
apps/ Chiappa and split-domain benchmark executables
See architecture.md for the detailed ownership and system model.
See the benchmark guide for the full Chiappa setup, release-build run commands, expected errors, and saved figures.
The project uses CMake and requires a C++23 compiler.
cmake --preset gcc14-debug
cmake --build --preset gcc14-debug
ctest --preset gcc14-debug --output-on-failureThe Chiappa bulk-wave comparison can be generated with:
LSAN_OPTIONS=detect_leaks=0 build/gcc14-debug/apps/chiappa_bulk_wave \
artifacts/chiappa_bulk/chiappa_snapshot.csv 160
MPLCONFIGDIR=/tmp/wavecore-mpl python3 scripts/plot_chiappa_snapshot.py \
artifacts/chiappa_bulk/chiappa_snapshot.csv.71us.csv \
artifacts/chiappa_bulk/chiappa_snapshot.pngThe default mesh is 160 x 160; pass 320 for the refined comparison. Each run saves the domain at 71 microseconds, a point history through 470 microseconds, the final domain, and the direct nodal initial velocities. See the comparison instructions for matched-time domain and history plots for both meshes.
The one-point Quad4 run is a diagnostic comparison.
It intentionally has no hourglass control and should not yet be treated as a
production-accuracy result.
The tests cover concept conformance, material initialization, stateless element kernels, geometry and Jacobian calculations, force integration, thickness scaling, shared-node scattering, archetype storage, and relation indexes, 2D/3D Frame storage and matching, constrained gather/scatter, and coupled-versus-intact numerical equivalence.
The split bulk-wave example stores each zone in a separate NodeArchetype,
with separate element connectivity and Gauss-point history. The Frame builder
searches all zone nodes in reference coordinates and creates one independent
Frame point per coincident group. Each connection has weight 1.0.
Initialization gathers nodal masses and the arithmetic average of connected initial velocities, then scatters that velocity back to the nodes. At each force-evaluation stage, the Frame sums internal/external forces and computes common acceleration as net force divided by gathered mass. Acceleration is scattered before the second half kick, respecting each component's existing boundary constraint. This maintains common interface motion without a per-step velocity or displacement correction.
ExplicitDynamicsSystem::run_coupled coordinates all zones with a shared
timestep. Frame systems support 2D/3D nodal views; this first driver requires
matching element/material types and coincident, unit-weight connections.
The 160 x 160 coupled Chiappa run reproduces the intact numerical mesh to
floating-point roundoff: maximum displacement differences are 1.080e-20 m
at 71 microseconds and 3.125e-20 m at 470 microseconds. Interface displacement
and velocity jumps are zero at all 4,701 saved history samples. This verifies
coupling equivalence; the discretization error against the analytical solution
remains.
See the Frame benchmark guide for release-build commands, coupled/disconnected modes, output schemas, and reproducible verification. Saved domain comparisons: 71 microseconds and 470 microseconds.
The separate archetypes, external relations, stateless element kernel,
generic geometry/material/force systems, lumped-mass leapfrog systems, and the
Chiappa analytical bulk-wave benchmark are implemented. Frame connection
building, gather/scatter, and synchronous multi-zone coupling are also implemented.
ExplicitDynamicsSystem::run handles initialization and time integration;
the application supplies the mesh/material data, IC, BC, and final time.
Optional policies set a timestep cap and output schedule. The system triggers
output events; application callbacks decide what and how to write.
Current BC support is limited to stationary homogeneous constraints.
The next agreed step is a reproducible CPU profiling baseline, separating solver
time from analytical evaluation and output. GPU execution and measured layout/tile
tuning follow later; see the profiling roadmap.
General loads and prescribed motion, improved entity/index handling, and restart
support remain longer-term work.