radia 1.3.15__tar.gz → 1.3.16__tar.gz

{radia-1.3.15/src/radia.egg-info → radia-1.3.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: radia
-Version: 1.3.15
+Version: 1.3.16
 Summary: Radia 3D Magnetostatics with NGSolve Integration and OpenMP Parallelization
 Home-page: https://github.com/ksugahar/Radia_NGSolve
 Author: Pascal Elleaume

{radia-1.3.15 → radia-1.3.16}/docs/API_REFERENCE.md

@@ -307,6 +307,113 @@ rel_change = |B_new - B_old| / B_sat
 
 This method provides fast Newton-Raphson convergence and matches industry-standard solvers.
 
+### Solver Tolerance Parameters
+
+Radia provides three tolerance parameters for controlling solver behavior:
+
+```python
+# 1. Nonlinear iteration tolerance (outer loop)
+#    Set via Solve() - controls when Newton-Raphson iterations stop
+rad.Solve(obj, nonl_tol, max_iter, method)  # nonl_tol = 0.001 recommended
+
+# 2. BiCGSTAB inner loop tolerance
+#    Set via SetBiCGSTABTol() BEFORE Solve() - controls linear system accuracy
+rad.SetBiCGSTABTol(bicg_tol)  # Default: 1e-4
+
+# 3. H-matrix ACA tolerance (Method 2 only)
+#    Set via SetHACApKParams() BEFORE Solve() - controls low-rank approximation
+rad.SetHACApKParams(hmat_eps, leaf_size, eta)  # Default: 1e-4, 10, 2.0
+```
+
+| Parameter | API | Default | Description |
+|-----------|-----|---------|-------------|
+| `nonl_tol` | `rad.Solve(obj, nonl_tol, ...)` | 0.001 | Nonlinear convergence threshold |
+| `bicg_tol` | `rad.SetBiCGSTABTol(tol)` | 1e-4 | BiCGSTAB relative residual tolerance |
+| `hmat_eps` | `rad.SetHACApKParams(eps, ...)` | 1e-4 | H-matrix ACA compression tolerance |
+
+**Example - Full solver configuration:**
+
+```python
+import radia as rad
+
+# Configure tolerances BEFORE Solve()
+rad.SetBiCGSTABTol(1e-4)           # BiCGSTAB tolerance
+rad.SetHACApKParams(1e-4, 10, 2.0) # H-matrix: eps=1e-4, leaf=10, eta=2.0
+
+# Solve with nonlinear tolerance
+rad.Solve(grp, 0.001, 100, 2)      # nonl_tol=0.001, max_iter=100, method=2 (HACApK)
+```
+
+### SetBiCGSTABTol - BiCGSTAB Inner Loop Tolerance
+
+```python
+rad.SetBiCGSTABTol(tol)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `tol` | float | 1e-4 | Relative residual tolerance for BiCGSTAB |
+
+**Notes:**
+- Affects Method 1 (BiCGSTAB) and Method 2 (HACApK)
+- Lower values = higher accuracy but more iterations
+- Call BEFORE `rad.Solve()`
+
+### SetHACApKParams - H-Matrix Parameters (Method 2)
+
+```python
+rad.SetHACApKParams(eps, leaf_size, eta)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `eps` | float | 1e-4 | ACA+ compression tolerance |
+| `leaf_size` | int | 10 | Minimum cluster size in elements |
+| `eta` | float | 2.0 | Admissibility parameter |
+
+**Notes:**
+- Only affects Method 2 (HACApK H-matrix solver)
+- Lower `eps` = higher accuracy, larger ranks, more memory
+- Call BEFORE `rad.Solve()`
+
+**Parameter Rationale:**
+
+| Parameter | Default | Rationale |
+|-----------|---------|-----------|
+| `eps` | 1e-4 | Balance between accuracy and compression. Lower values (1e-6, 1e-8) for higher accuracy, higher values (1e-3) for faster computation. |
+| `leaf_size` | 10 | Minimum cluster size. Smaller values allow deeper tree but increase H-matrix overhead. 10 provides good balance for typical element counts. ELF-compatible default. |
+| `eta` | 2.0 | Standard admissibility criterion: clusters are "well-separated" when `dist(c1,c2) >= eta * max(diam(c1), diam(c2))`. eta=2.0 is conservative, ensuring accurate low-rank approximations. Lower values (1.0) allow more aggressive compression but may reduce accuracy. |
+
+### SetRelaxParam - Under-Relaxation Coefficient
+
+```python
+rad.SetRelaxParam(relax)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `relax` | float | 0.0 | Under-relaxation coefficient (0.0-1.0) |
+
+**Notes:**
+- Affects all solver methods (0=LU, 1=BiCGSTAB, 2=HACApK)
+- `relax=0.0`: Full Newton step (default, fastest convergence when stable)
+- `relax>0.0`: Damped update: `chi_new = chi_new*(1-relax) + chi_old*relax`
+- Use under-relaxation (e.g., 0.2-0.5) when:
+  - Convergence is slow or oscillating
+  - Material has steep B-H curve
+  - Problem is highly nonlinear
+- Call BEFORE `rad.Solve()`
+
+**Example:**
+```python
+# For difficult nonlinear problems, use under-relaxation
+rad.SetRelaxParam(0.3)  # 30% damping
+rad.Solve(container, 0.001, 100, 1)
+
+# Reset to full step for normal cases
+rad.SetRelaxParam(0.0)
+```
+
 ### BiCGSTAB Performance
 
 Typical solve times (nonlinear BH curve material):

{radia-1.3.15 → radia-1.3.16}/examples/cube_uniform_field/linear/benchmark_conditions.py

@@ -33,7 +33,7 @@ CHI = MU_R - 1       # For reference/calculations only
 # =============================================================================
 # External Field
 # =============================================================================
-H_EXT = 50000.0      # External H field magnitude [A/m]
+H_EXT = 200000.0     # External H field magnitude [A/m] (same as nonlinear benchmark)
 B_EXT = MU_0 * H_EXT  # External B field magnitude [T]
 
 # =============================================================================
@@ -49,8 +49,8 @@ MAX_ITERATIONS = 1000       # Maximum iterations
 # Tetrahedron: maxh = CUBE_SIZE / n_div (approximate correspondence)
 
 # Standard mesh sizes for comparison
-STANDARD_N_DIVS = [3, 4, 5, 6, 7, 8]
-STANDARD_MAXH = [0.5, 0.4, 0.35, 0.3, 0.25, 0.2]
+STANDARD_N_DIVS = [5, 10, 15]
+STANDARD_MAXH = [0.35, 0.25, 0.2, 0.15, 0.1]
 
 def n_div_to_maxh(n_div):
     """Convert hexahedron n_div to approximate tetrahedral maxh."""

radia-1.3.16/examples/cube_uniform_field/nonlinear/README.md

@@ -0,0 +1,229 @@
+# Nonlinear Material Benchmark
+
+Benchmark for Radia's nonlinear solver with saturable BH curves using MSC (Magnetic Surface Charge) method.
+
+## Problem Setup
+
+- **Geometry**: 1.0 m x 1.0 m x 1.0 m cube centered at origin
+- **Material**: Nonlinear BH curve (soft iron with saturation)
+- **External Field**: Hz = 200,000 A/m (uniform field along z-axis)
+
+## Element Types
+
+| Element | Mesh Tool | DOF | Benchmark Script |
+|---------|-----------|-----|------------------|
+| Hexahedron MSC | ObjPolyhdr | 6 (sigma per face) | `benchmark_hexahedron_msc.py` |
+| Tetrahedron MSC | Netgen | 3 (Mx, My, Mz) | `benchmark_tetrahedron_msc_netgen.py` |
+
+## BH Curve (Soft Iron)
+
+```
+H [A/m]     B [T]
+0           0.0
+100         0.1
+200         0.3
+500         0.8
+1000        1.2
+2000        1.5
+5000        1.7
+10000       1.8
+50000       2.0
+100000      2.1
+```
+
+- Initial permeability: mu_r ~= 800
+- Saturation onset: B ~= 1.5 T
+
+---
+
+## Hexahedron MSC Benchmarks
+
+Results stored in `hexahedron_msc/{lu,bicgstab,hacapk}/` directories.
+
+### Solver Methods
+
+| Method | Description | Complexity |
+|--------|-------------|------------|
+| LU | Dense LU decomposition | O(N^3) |
+| BiCGSTAB | Iterative BiCGSTAB | O(N^2) per iteration |
+| HACApK | H-matrix accelerated BiCGSTAB | O(N log N) per iteration |
+
+### LU Solver Results (H_ext = 200,000 A/m)
+
+| N | Elements | DOF | Time (s) | Iter | M_avg_z (A/m) | Memory (MB) |
+|---|----------|-----|----------|------|---------------|-------------|
+| 5 | 125 | 750 | 0.30 | 6 | 702,132 | 49 |
+| 10 | 1,000 | 6,000 | 46.26 | 13 | 716,281 | 1,174 |
+
+**Note**: LU solver for N >= 15 is prohibitively slow (O(N^6) time complexity for nonlinear).
+
+### BiCGSTAB Solver Results (H_ext = 200,000 A/m)
+
+| N | Elements | DOF | Time (s) | Iter | M_avg_z (A/m) | Memory (MB) |
+|---|----------|-----|----------|------|---------------|-------------|
+| 5 | 125 | 750 | 0.24 | 3 | 702,114 | 35 |
+| 10 | 1,000 | 6,000 | 17.95 | 5 | 716,316 | 344 |
+
+**Note**: BiCGSTAB uses previous solution as initial guess (ELF-compatible). Iteration count matches ELF.
+
+### HACApK Solver Results (H_ext = 200,000 A/m, eps = 1e-4)
+
+| N | Elements | DOF | Time (s) | Iter | M_avg_z (A/m) | Memory (MB) | Compression | Leaves |
+|---|----------|-----|----------|------|---------------|-------------|-------------|--------|
+| 5 | 125 | 750 | 0.14 | 4 | 701,757 | 35 | 0.0219 | 184 |
+| 10 | 1,000 | 6,000 | 6.09 | 5 | 715,885 | 208 | 0.0059 | 3,190 |
+
+### Speedup: HACApK vs LU
+
+| N | LU Time (s) | HACApK Time (s) | Speedup |
+|---|-------------|-----------------|---------|
+| 5 | 0.30 | 0.14 | 2.1x |
+| 10 | 46.26 | 6.09 | 7.6x |
+| 15 | (est. hours) | - | >>10x |
+| 20 | (impractical) | - | >>100x |
+
+---
+
+## Radia vs ELF/MAGIC Comparison
+
+Comparison of Radia and ELF/MAGIC solvers on identical hexahedral mesh (1.0m cube, H_ext = 200,000 A/m).
+
+### Magnetization Accuracy (M_avg_z)
+
+| N | Elements | Radia LU | ELF LU | Radia HACApK | ELF HACApK | Difference (%) |
+|---|----------|----------|--------|--------------|------------|----------------|
+| 5 | 125 | 702,132 | 702,132 | 701,757 | 702,110 | < 0.1% |
+| 10 | 1,000 | 716,281 | 716,281 | 715,885 | 716,360 | < 0.1% |
+
+**Note**: LU results match exactly. Small differences in HACApK are due to H-matrix compression (eps=1e-4).
+
+### Performance Comparison
+
+#### LU Solver
+
+| N | Elements | Radia Time (s) | ELF Time (s) | Radia Iter | ELF Iter |
+|---|----------|----------------|--------------|------------|----------|
+| 5 | 125 | 0.30 | 0.13 | 6 | 6 |
+| 10 | 1,000 | 46.26 | 13.42 | 13 | 13 |
+
+**Note**: ELF LU is faster due to Fortran LAPACK optimizations. Iteration counts match exactly.
+
+#### BiCGSTAB Solver
+
+| N | Elements | Radia Time (s) | ELF Time (s) | Radia Iter | ELF Iter |
+|---|----------|----------------|--------------|------------|----------|
+| 5 | 125 | 0.24 | 0.08 | 3 | 3 |
+| 10 | 1,000 | 17.95 | 4.93 | 5 | 4 |
+
+**Note**: Radia BiCGSTAB now uses previous solution as initial guess, matching ELF's convergence behavior.
+
+#### HACApK Solver (eps = 1e-4)
+
+| N | Elements | Radia Time (s) | ELF Time (s) | Radia Iter | ELF Iter |
+|---|----------|----------------|--------------|------------|----------|
+| 5 | 125 | 0.14 | 0.15 | 4 | 3 |
+| 10 | 1,000 | 6.09 | 4.07 | 5 | 4 |
+
+**Note**: HACApK performance is comparable. Both use ACA+ compression with identical parameters.
+
+### Key Observations
+
+1. **Accuracy**: LU results are identical between Radia and ELF (M_avg_z matches to all digits)
+2. **Convergence**: Both use similar Newton-Raphson (mucal2) convergence with B-field criterion
+3. **HACApK**: Performance is comparable; Radia's H-matrix overhead is similar to ELF
+4. **BiCGSTAB**: Iteration counts now match ELF (3-5 iterations vs previous 50)
+
+---
+
+## Tetrahedron MSC Benchmarks
+
+Results stored in `tetrahedron_msc/{lu,bicgstab,hacapk}/` directories.
+
+### HACApK Solver Results (H_ext = 200,000 A/m, eps = 1e-4)
+
+| maxh | Elements | DOF | Time (s) | Iter | M_avg_z (A/m) | Memory (MB) | Leaves |
+|------|----------|-----|----------|------|---------------|-------------|--------|
+| 0.40 | 104 | 312 | 0.29 | 2 | 588,673 | 66 | 172 |
+| 0.20 | 627 | 1,881 | 12.50 | 2 | 568,973 | 134 | 2,098 |
+| 0.15 | 2,211 | 6,633 | 135.86 | 2 | 587,299 | 775 | 14,386 |
+| 0.10 | 4,994 | 14,982 | 757.65 | 2 | 570,603 | 3,298 | 36,475 |
+
+**Note**: 3DOF tetrahedra require pre-computed dense InteractMatrix (O(N^2) memory), which is the performance bottleneck. H-matrix is used for MatVec acceleration only.
+
+---
+
+## Convergence Criterion
+
+Radia v1.3.15+ uses **B-field based convergence** (mucal2) for nonlinear materials, matching the Newton-Raphson method used in industry-standard solvers.
+
+### Convergence Methods
+
+| Method | Stage | Formula | Description |
+|--------|-------|---------|-------------|
+| **mucal0** | Initialization | `chi = B[1] / (mu_0 * H[1]) - 1` | Initial chi from 2nd BH point |
+| mucal1 | Iteration | `rel_change = |chi_new - chi_old| / chi_old` | Legacy relaxation method |
+| **mucal2** | Iteration | `rel_change = |B_new - B_old| / B_sat` | Newton-Raphson, fast convergence |
+
+---
+
+## Solver Methods
+
+Radia provides three solver methods:
+
+| Method | Name | Description | Recommendation |
+|--------|------|-------------|----------------|
+| 0 | LU | Direct LU decomposition | Small problems (N < 12) |
+| 1 | BiCGSTAB | Iterative solver | Medium problems |
+| 2 | HACApK | H-matrix accelerated BiCGSTAB | Large problems (N >= 10) |
+
+```python
+# Method 0: Direct LU solver
+res = rad.Solve(grp, 0.001, 1000, 0)
+
+# Method 1: BiCGSTAB iterative solver
+res = rad.Solve(grp, 0.001, 1000, 1)
+
+# Method 2: HACApK (H-matrix + BiCGSTAB)
+rad.SetHACApKParams(1e-4, 10, 2.0)  # eps, leaf_size, eta
+res = rad.Solve(grp, 0.001, 1000, 2)
+```
+
+### When to Use Each Method
+
+| Problem Size | Recommended Solver | Rationale |
+|--------------|-------------------|-----------|
+| N < 10 (< 1,000 elem) | LU (Method 0) | Fast, direct solution |
+| 10 <= N < 15 | HACApK (Method 2) | 8x faster than LU |
+| N >= 15 | HACApK (Method 2) | Only practical option |
+
+---
+
+## Usage
+
+### Hexahedron Benchmarks
+
+```bash
+# Run specific solver
+python benchmark_hexahedron_msc.py --lu 5 10
+python benchmark_hexahedron_msc.py --bicgstab 5 10
+python benchmark_hexahedron_msc.py --hacapk 5 10 15 20
+
+# Custom ACA tolerance
+python benchmark_hexahedron_msc.py --hacapk --eps 1e-3 5 10
+```
+
+### Tetrahedron Benchmarks
+
+```bash
+# Run specific solver
+python benchmark_tetrahedron_msc_netgen.py --lu 0.4 0.2
+python benchmark_tetrahedron_msc_netgen.py --hacapk 0.4 0.2 0.15 0.10
+
+# Custom ACA tolerance
+python benchmark_tetrahedron_msc_netgen.py --hacapk --eps 1e-3 0.15
+```
+
+---
+
+**Last Updated**: 2025-12-24
+**Author**: Claude Code

{radia-1.3.15 → radia-1.3.16}/examples/cube_uniform_field/nonlinear/benchmark_conditions.py

@@ -25,7 +25,7 @@ CUBE_HALF = 0.5      # Half of cube edge [m]
 # =============================================================================
 # External Field
 # =============================================================================
-H_EXT = 50000.0      # External H field magnitude [A/m]
+H_EXT = 200000.0     # External H field magnitude [A/m] (unified with linear benchmark)
 B_EXT = MU_0 * H_EXT  # External B field magnitude [T]
 
 # =============================================================================

{radia-1.3.15 → radia-1.3.16}/examples/cube_uniform_field/nonlinear/benchmark_hexahedron_msc.py

@@ -17,11 +17,13 @@ Solver types:
 Usage:
     python benchmark_hexahedron_msc.py --lu 5 10 15 20
     python benchmark_hexahedron_msc.py --bicgstab 5 10 15 20
-    python benchmark_hexahedron_msc.py 5 10 15 20  # runs both
+    python benchmark_hexahedron_msc.py --hacapk 5 10 15 20
+    python benchmark_hexahedron_msc.py --hacapk --eps 1e-3 5 10 15  # custom ACA tolerance
 
 Examples:
     python benchmark_hexahedron_msc.py --lu 5 10 15 20
     python benchmark_hexahedron_msc.py --bicgstab 5 10 15 20
+    python benchmark_hexahedron_msc.py --hacapk --eps 1e-4 5 10 15  # ELF-compatible default
 """
 
 import sys
@@ -132,14 +134,18 @@ def create_hexahedron_msc_mesh(n_div):
     return elements
 
 
-def benchmark_hexahedron_msc(n_div, solver_method=1, use_hmatrix=False):
+def benchmark_hexahedron_msc(n_div, solver_method=1, use_hmatrix=False,
+                             hmat_eps=1e-4, leaf_size=10, eta=2.0, relax=0.0):
     """
     Benchmark hexahedral MSC mesh with specified solver.
 
     Args:
         n_div: Number of divisions per edge
-        solver_method: 0=LU, 1=BiCGSTAB
+        solver_method: 0=LU, 1=BiCGSTAB, 2=HACApK
         use_hmatrix: Enable H-matrix acceleration (BiCGSTAB only)
+        hmat_eps: ACA tolerance for HACApK solver (default: 1e-4)
+        leaf_size: Minimum cluster size in elements (default: 10)
+        eta: Admissibility parameter (default: 2.0)
     """
     rad.FldUnits('m')
     rad.UtiDelAll()
@@ -147,6 +153,8 @@ def benchmark_hexahedron_msc(n_div, solver_method=1, use_hmatrix=False):
     # Determine solver name
     if solver_method == 0:
         solver_name = 'lu'
+    elif solver_method == 2:
+        solver_name = 'hacapk'
     elif use_hmatrix:
         solver_name = 'bicgstab_hmatrix'
     else:
@@ -175,30 +183,52 @@ def benchmark_hexahedron_msc(n_div, solver_method=1, use_hmatrix=False):
     ext = rad.ObjBckg([0, 0, B_ext])
     grp = rad.ObjCnt([container, ext])
 
-    # Configure H-matrix if requested
-    # Note: H-matrix API may vary - check if available
+    # Configure H-matrix if using HACApK (method=2)
     hmatrix_enabled = False
-    if use_hmatrix and solver_method == 1:
+    hmatrix_stats = None
+    if solver_method == 2:
         try:
-            rad.SolverHMatrixEnable()
+            # Set HACApK parameters
+            # eps: ACA tolerance (lower = more accurate, higher = faster)
+            # leaf_size: minimum cluster size in elements
+            # eta: admissibility parameter
+            rad.SetHACApKParams(hmat_eps, leaf_size, eta)
             hmatrix_enabled = True
-            print('H-matrix: Enabled')
+            print(f'H-matrix: Enabled (eps={hmat_eps:.0e}, leaf_size={leaf_size}, eta={eta})')
         except AttributeError:
             print('H-matrix: Not available (API not found)')
 
+    # Tolerance parameters (all explicitly set for reproducibility)
+    NONL_TOL = 0.001     # Nonlinear iteration tolerance (outer loop)
+    BICG_TOL = 1e-4      # BiCGSTAB inner loop tolerance (Method 1 and 2)
+    MAX_ITER = 100       # Maximum nonlinear iterations
+
+    # Set BiCGSTAB inner loop tolerance explicitly (ELF-compatible default)
+    rad.SetBiCGSTABTol(BICG_TOL)
+
+    # Set under-relaxation coefficient (0.0 = full step, 0.0-1.0 = under-relaxation)
+    rad.SetRelaxParam(relax)
+
     # Solve
-    print(f'Solving...')
+    relax_str = f', relax={relax:.1f}' if relax > 0 else ''
+    print(f'Solving... (nonl_tol={NONL_TOL:.0e}, bicg_tol={BICG_TOL:.0e}{relax_str})')
     t_solve_start = time.time()
-    result = rad.Solve(grp, 0.001, 1000, solver_method)
+    result = rad.Solve(grp, NONL_TOL, MAX_ITER, solver_method)
     t_solve = time.time() - t_solve_start
 
     # Measure peak memory after solve
     peak_memory_mb = get_peak_memory_mb()
 
-    # Disable H-matrix after solve
+    # Get H-matrix statistics if HACApK was used
     if hmatrix_enabled:
         try:
-            rad.SolverHMatrixDisable()
+            hmatrix_stats = rad.GetHACApKStats()
+            if hmatrix_stats:
+                print(f'H-matrix stats:')
+                print(f'  Leaf nodes: {hmatrix_stats["n_leaves"]} (low-rank: {hmatrix_stats["n_lowrank"]}, dense: {hmatrix_stats["n_dense"]})')
+                print(f'  Max rank: {hmatrix_stats["max_rank"]}')
+                print(f'  Compression: {hmatrix_stats["compression"]:.4f}')
+                print(f'  Build time: {hmatrix_stats["build_time"]:.4f} s')
         except AttributeError:
             pass
 
@@ -208,7 +238,7 @@ def benchmark_hexahedron_msc(n_div, solver_method=1, use_hmatrix=False):
     M_avg_z = np.mean([m[2] for m in M_list]) if M_list else 0.0
 
     n_iter = int(result[3]) if result[3] else 0
-    converged = n_iter < 1000
+    converged = n_iter < MAX_ITER
     residual = result[0] if result[0] else 0.0
 
     print(f'Time: {t_solve:.3f} s')
@@ -230,6 +260,13 @@ def benchmark_hexahedron_msc(n_div, solver_method=1, use_hmatrix=False):
         't_solve': t_solve,
         'solver_method': solver_method,
         'solver_name': solver_name,
+        # Tolerance parameters (all explicitly recorded)
+        'nonl_tol': NONL_TOL,        # Nonlinear iteration tolerance (outer loop)
+        'bicg_tol': BICG_TOL,        # BiCGSTAB inner loop tolerance
+        # H-matrix parameters (Method 2 only)
+        'hmat_eps': hmat_eps if solver_method == 2 else None,
+        'leaf_size': leaf_size if solver_method == 2 else None,
+        'eta': eta if solver_method == 2 else None,
         'hmatrix_enabled': hmatrix_enabled,
         'converged': converged,
         'residual': residual,
@@ -238,6 +275,23 @@ def benchmark_hexahedron_msc(n_div, solver_method=1, use_hmatrix=False):
     }
     if peak_memory_mb is not None:
         result_data['peak_memory_mb'] = peak_memory_mb
+    if hmatrix_stats is not None:
+        hmatrix_data = {
+            'n_lowrank': hmatrix_stats['n_lowrank'],
+            'n_dense': hmatrix_stats['n_dense'],
+            'max_rank': hmatrix_stats['max_rank'],
+            'compression_ratio': hmatrix_stats['compression'],
+            'build_time': hmatrix_stats['build_time'],
+            'nlf': hmatrix_stats['n_leaves'],
+        }
+        # Add timing statistics if available (v1.3.16+)
+        if 't_hmatrix_build' in hmatrix_stats:
+            hmatrix_data['t_hmatrix_build'] = hmatrix_stats['t_hmatrix_build']
+        if 't_linear_solve' in hmatrix_stats:
+            hmatrix_data['t_linear_solve'] = hmatrix_stats['t_linear_solve']
+        if 'linear_iterations' in hmatrix_stats:
+            hmatrix_data['linear_iterations'] = hmatrix_stats['linear_iterations']
+        result_data['hmatrix'] = hmatrix_data
     return result_data
 
 
@@ -245,15 +299,25 @@ def main():
     parser = argparse.ArgumentParser(description='Hexahedron MSC benchmark (Radia)')
     parser.add_argument('--lu', action='store_true', help='Run LU solver benchmark')
     parser.add_argument('--bicgstab', action='store_true', help='Run BiCGSTAB solver benchmark')
+    parser.add_argument('--hacapk', action='store_true', help='Run HACApK (H-matrix) solver benchmark')
+    parser.add_argument('--eps', type=float, default=1e-4,
+                       help='ACA tolerance for HACApK (default: 1e-4, lower=accurate, higher=fast)')
+    parser.add_argument('--leaf_size', type=int, default=10,
+                       help='Minimum cluster size in elements (default: 10)')
+    parser.add_argument('--eta', type=float, default=2.0,
+                       help='Admissibility parameter (default: 2.0)')
+    parser.add_argument('--relax', type=float, default=0.0,
+                       help='Under-relaxation coefficient (default: 0.0 = full step, 0.0-1.0)')
     parser.add_argument('sizes', nargs='*', type=int, default=[5, 10, 15, 20],
                        help='Mesh sizes (N values, default: 5 10 15 20)')
 
     args = parser.parse_args()
 
-    # Default to both if none specified
-    any_solver = args.lu or args.bicgstab
+    # Default to LU only if none specified
+    any_solver = args.lu or args.bicgstab or args.hacapk
     run_lu = args.lu or not any_solver
-    run_bicgstab = args.bicgstab or not any_solver
+    run_bicgstab = args.bicgstab
+    run_hacapk = args.hacapk
 
     script_dir = os.path.dirname(os.path.abspath(__file__))
 
@@ -263,10 +327,15 @@ def main():
     print('Cube size: 1.0 m')
     print('H_ext: %.0f A/m' % H_EXT)
     print('N values: %s' % args.sizes)
+    if args.relax > 0:
+        print('Relaxation: %.2f (under-relaxation)' % args.relax)
+    if run_hacapk:
+        print('HACApK: eps=%.0e, leaf_size=%d, eta=%.1f' % (args.eps, args.leaf_size, args.eta))
     print()
 
     results_lu = []
     results_bicgstab = []
+    results_hacapk = []
 
     for n in args.sizes:
         # LU Benchmark
@@ -278,7 +347,7 @@ def main():
             output_dir = os.path.join(script_dir, 'hexahedron_msc', 'lu')
             os.makedirs(output_dir, exist_ok=True)
 
-            result = benchmark_hexahedron_msc(n, solver_method=0, use_hmatrix=False)
+            result = benchmark_hexahedron_msc(n, solver_method=0, use_hmatrix=False, relax=args.relax)
             results_lu.append(result)
 
             filename = 'msc_N%d_results.json' % n
@@ -296,7 +365,7 @@ def main():
             output_dir = os.path.join(script_dir, 'hexahedron_msc', 'bicgstab')
             os.makedirs(output_dir, exist_ok=True)
 
-            result = benchmark_hexahedron_msc(n, solver_method=1, use_hmatrix=False)
+            result = benchmark_hexahedron_msc(n, solver_method=1, use_hmatrix=False, relax=args.relax)
             results_bicgstab.append(result)
 
             filename = 'msc_N%d_results.json' % n
@@ -305,6 +374,25 @@ def main():
                 json.dump(result, f, indent=2)
             print('Saved: %s\n' % filepath)
 
+        # HACApK Benchmark (Method 2)
+        if run_hacapk:
+            print('\n' + '=' * 70)
+            print('HACApK SOLVER: N=%d (eps=%.0e, leaf=%d, eta=%.1f)' % (n, args.eps, args.leaf_size, args.eta))
+            print('=' * 70 + '\n')
+
+            output_dir = os.path.join(script_dir, 'hexahedron_msc', 'hacapk')
+            os.makedirs(output_dir, exist_ok=True)
+
+            result = benchmark_hexahedron_msc(n, solver_method=2, use_hmatrix=False,
+                                              hmat_eps=args.eps, leaf_size=args.leaf_size, eta=args.eta, relax=args.relax)
+            results_hacapk.append(result)
+
+            filename = 'msc_N%d_results.json' % n
+            filepath = os.path.join(output_dir, filename)
+            with open(filepath, 'w') as f:
+                json.dump(result, f, indent=2)
+            print('Saved: %s\n' % filepath)
+
     # Summary
     print('\n' + '=' * 70)
     print('SUMMARY')
@@ -330,6 +418,21 @@ def main():
                 r['nonl_iterations'], r['M_avg_z'],
                 'Yes' if r['converged'] else 'No'))
 
+    if results_hacapk:
+        print('\nHACApK Solver (hexahedron_msc/hacapk/):\n')
+        print('%-6s %8s %10s %8s %10s %10s %8s %10s' % (
+            'N', 'Elements', 'Time (s)', 'Nonl It', 'M_avg_z', 'Compress', 'Leaves', 'Conv'))
+        print('-' * 85)
+        for r in results_hacapk:
+            hm = r.get('hmatrix', {})
+            compression = hm.get('compression_ratio', 0.0)
+            n_leaves = hm.get('nlf', 0)
+            print('%-6d %8d %10.3f %8d %10.0f %10.4f %8d %10s' % (
+                r['n_div'], r['n_elements'], r['t_solve'],
+                r['nonl_iterations'], r['M_avg_z'],
+                compression, n_leaves,
+                'Yes' if r['converged'] else 'No'))
+
     print('=' * 70)