feat(palace): expose the Gmsh 3D algorithm and thread counts

[Alisama20]

Summary

Stacked on #287: the first commit of this branch is that PR, and only the second one, feat(palace): expose the Gmsh 3D algorithm and thread counts, is new here. Its tests use the mesh hash and the recorded Gmsh options of #287.

#283 asks for the Gmsh thread and algorithm controls to be exposed separately from the Palace solver settings, for a way to keep the mesh identical when that matters, and for the limits to be documented. gsim set none of them: Gmsh ran single-threaded with its default 3D algorithm, and there was no way to change either.

This adds three options to MeshConfig, sim.mesh(), sim.preview() and generate_mesh():

sim.mesh(preset="default", algorithm_3d="delaunay", threads=4, surface_threads=1)

Option	Gmsh options set	Default
algorithm_3d ("delaunay" or "hxt")	Mesh.Algorithm3D = 1 or 10	"delaunay"
threads	General.NumThreads, Mesh.MaxNumThreads3D	1
surface_threads	Mesh.MaxNumThreads1D, Mesh.MaxNumThreads2D	1

They need a Gmsh with per-dimension thread limits (Mesh.MaxNumThreads1D/2D/3D, which the 4.11.1 manual already lists; I did not check earlier versions, and gmsh is not pinned in pyproject.toml). They are applied right after generate_mesh() initializes Gmsh, and the effective values are recorded with the mesh hash from #287, so the settings behind a hash can be read next to it. A simulation that already has a mesh_config keeps its values unless sim.mesh() overrides them, like the curve-fit and high-order settings.

Defaults change nothing. They are what Gmsh did already, one thread and Delaunay, now set explicitly. On the lumped CPW of the notebooks (135,380 tetrahedra) and on the 800 µm CPW of #283 (90,055), the mesh hash is identical with and without this change.

Which combinations keep the mesh. From the runs behind #283 (Windows 10, Intel i7-9750H, Gmsh 4.15.2; the Apple M4 in the issue shows the same for Delaunay, which is the only algorithm it varied threads for beyond one HXT run):

algorithm_3d	threads / surface_threads	Same mesh as one thread?	Repeats run to run?	Meshing time
delaunay	1 / 1, 4 / 1, 12 / 1	yes	yes	5.7 s, no gain
delaunay	4 / 4	no	no, a different mesh each run	3.5 s
hxt	1 / 1		yes	14.3 s
hxt	4 / 1	no	yes, at that count	8.8 s

So the way to get the same mesh whatever the thread count is Delaunay with surface_threads=1, which is the default; it does not make meshing faster. That HXT repeats itself at a fixed thread count was seen on the Windows machine only, in every repeat there; it is worth confirming on another host before relying on it. Parallel surface meshing is the only combination that sped meshing up with Delaunay, and it gives a different mesh each time, also with Mesh.Reproducible=1 and a fixed seed. gsim logs a warning for the two combinations that lose the mesh (surface_threads > 1, and HXT with several threads); the same guidance is in the MeshConfig and generate_mesh docstrings, which the API docs render.

Part of #283.

Test Plan

New tests/palace/test_mesher_controls.py, 18 tests:

• the defaults, and rejection of threads=0, surface_threads=0 and an unknown algorithm;
• apply_mesher_options sets every Gmsh option it should, for both algorithms;
• no warning for Delaunay with 1 or 8 threads, or HXT with one; exactly one for surface_threads=4 and one for HXT with 4 threads;
• sim.mesh() applies the options and records them in the mesh stats, defaults to one thread, and a simulation with a mesh_config keeps its controls unless sim.mesh() overrides them;
• Delaunay with serial surfaces gives the same mesh hash for 1 and 4 threads;
• sim.preview() forwards the options to generate_mesh();
• the options are set on the gmsh that generate_mesh() itself uses. A first version put this in gmsh_utils, which uses the real Gmsh, and it broke test_generate_mesh_forwards_curve_fit_and_decimation whenever an earlier test had not left Gmsh initialized, because that test replaces generator.gmsh with a fake. It only showed up with all the branches merged, so the helper lives in generator.py now.

I broke each link on purpose (not calling apply_mesher_options, not keeping the previous config, applying the surface count to 3D, not passing threads through, dropping the HXT warning, a wrong HXT code, preview() not forwarding, and using the real Gmsh instead of the generator's) and in every case the matching test failed.

On the real 800 µm CPW of #283, run through sim.mesh() itself:

API call	Tets	Mesh hash	Warnings
no new arguments	90,055	db3edef2cdc04142	0
delaunay, 1 / 1	90,055	db3edef2cdc04142	0
delaunay, 4 / 1	90,055	db3edef2cdc04142	0
delaunay, 12 / 1	90,055	db3edef2cdc04142	0
delaunay, 4 / 4 (twice)	90,018 and 90,000	03d9de97… and 73b45d15…	1 each
hxt, 1 / 1 (twice)	73,007	86335bafc65c9623 both	0
hxt, 4 / 1 (twice)	72,950	37a3afd023a65c05 both	1 each

The classes are the same as in the earlier runs that patched Gmsh directly. The meshes have 90,055 (Delaunay) and 73,007 (HXT) tetrahedra because gsim samples the distance field at 200 points by default, not the 1600 of the recipe in #283, which gives 98,112 and 79,230.

Full suite: 1476 passed, 6 skipped, 4 xpassed (the 1434 that pass on main plus the 24 of #287 and the 18 new tests). pre-commit: all hooks pass.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 65.89%. Comparing base (2b7124a) to head (9a84d03).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #290      +/-   ##
==========================================
+ Coverage   65.54%   65.89%   +0.35%     
==========================================
  Files         110      110              
  Lines       16836    16934      +98     
  Branches     3323     3342      +19     
==========================================
+ Hits        11035    11159     +124     
+ Misses       4743     4728      -15     
+ Partials     1058     1047      -11     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.