From 083b158d1b8aec8b566b9957f932222fb2b0c195 Mon Sep 17 00:00:00 2001 From: Jukka Aho Date: Wed, 12 Nov 2025 01:09:13 +0200 Subject: [PATCH] docs(demos): Add assembly comparison demo documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - cantilever_cpu_comparison.jl research demo explained - Warning: NOT user-facing, low-level performance research - Documents element vs nodal assembly comparison - Results: nodal 4.7× faster, 2× fewer CG iterations - Points users to proper examples (linear_static.jl) - Direct use of ElementAssemblyData and NodeToElementsMap --- demos/README.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/demos/README.md b/demos/README.md index e73ddad..e8aabbb 100644 --- a/demos/README.md +++ b/demos/README.md @@ -8,6 +8,33 @@ These demos validate that type-stable field storage enables modern high-performa ## Demonstrations +### Assembly Strategy Comparison (`cantilever_cpu_comparison.jl`) + +**Purpose:** Algorithm-level comparison of assembly strategies (RESEARCH). + +⚠️ **NOT a user-facing example!** This is low-level performance research. + +**What it demonstrates:** + +- Element-by-element assembly (traditional FEM) +- Node-by-node assembly (GPU-friendly, contact-ready) +- Matrix-free iterative solvers +- Direct comparison: assembly time, iterations, accuracy + +**Why low-level:** + +- Uses `ElementAssemblyData` and `NodeToElementsMap` structures directly +- Manually constructs element stiffness matrices +- Not representative of user workflow + +**For users:** See `examples/linear_static.jl` or `cantilever_gmsh_gpu.jl` instead. + +**Results (135 Tet4 elements):** + +- Nodal assembly: 4.7× faster than element assembly +- Nodal CG: 2× fewer iterations (215 vs 417) +- All methods give identical displacements + ### 1. GPU and MPI Communication (`gpu_mpi_demo.jl`) **Purpose:** Prove that type-stable data structures flow efficiently to GPU and MPI.