feat(palace): expose Palace's advanced wave-port eigensolver controls

[Alisama20]

Item 2 of #228: "Expose Palace advanced wave-port solver controls in gsim
and benchmark SLEPc versus ARPACK, solver tolerances, and subspace sizing."

What's missing

WavePortConfig only ever produces a bare
Index/Mode/Offset/Excitation/Attributes entry for numeric wave
ports - there is nowhere to set Palace's own per-port eigensolver controls
(SolverType, EigenTol, KSPTol, MaxSize, Verbose), all marked
x-palace-advanced in Palace's own JSON schema
(awslabs/palace, scripts/schema/config-schema.json, $defs.WavePort).

The change

Five new optional fields on WavePortConfig
(eigensolver_type/eigensolver_tol/eigensolver_ksp_tol/
eigensolver_max_size/eigensolver_verbose), threaded through
Simulation.add_wave_port() -> configure_wave_port() -> PalacePort ->
the emitted WavePort config entry in generate_palace_config. Each field
is only emitted when set, matching the existing R/L/C "only if not None"
pattern already used for lumped ports a few lines above the change in
config_generator.py.

Naming note: WavePortConfig already has a field called max_size -
a bool meaning "fill the full simulation domain" (geometry sizing).
Palace's own MaxSize (eigensolver subspace dimension) is an unrelated
int, so the new field is eigensolver_max_size to avoid the collision,
and the same eigensolver_ prefix is used on all five new fields for
consistency.

Verification

Not just unit-tested in isolation - ran the real
generate_palace_config() end to end on a two-port config with all five
fields set on one port and left at their defaults on the other:

ports = [
    PalacePort(name="o1", port_type=PortType.WAVEPORT, layer="metal",
               eigensolver_type="SLEPc", eigensolver_tol=1e-6,
               eigensolver_ksp_tol=1e-8, eigensolver_max_size=40,
               eigensolver_verbose=2),
    PalacePort(name="o2", port_type=PortType.WAVEPORT, layer="metal", excited=False),
]

emits exactly:

{"Index": 1, "Mode": 1, "Offset": 0.0, "Excitation": 1, "Attributes": [6],
 "SolverType": "SLEPc", "EigenTol": 1e-06, "KSPTol": 1e-08, "MaxSize": 40, "Verbose": 2}
{"Index": 2, "Mode": 1, "Offset": 0.0, "Excitation": false, "Attributes": [7]}

• all five keys present with the right values on the configured port, none
  of them present on the default one.

The full existing tests/palace/ suite (314 tests, cloud-marked ones
excluded) passes unmodified against these changes. 5 new tests added
(tests/palace/test_waveport_eigensolver_controls.py) covering: model
defaults, the max_size/eigensolver_max_size field independence,
all-five-emitted, none-emitted-when-unset, and per-port independence
across two ports with different settings.

Scope

This is item 2 only - it does not itself benchmark SLEPc vs ARPACK or
change any default solver behaviour (every field defaults to None,
Palace's own default is unchanged unless a caller opts in). It also
doesn't touch item 3's WavePortPEC work (#251, merged) or attempt item 6
(port-mode interpolation/ROM) - see the comment on #228 itself for a
closed-form prototype of that direction. MaxIts (GMRES iteration cap,
also x-palace-advanced in Palace's schema, alongside the five here) was
deliberately left out - happy to add it in this PR or a follow-up,
whichever you'd prefer.

Refs #228

[mdmaas]

Hi, Ali! Nice.

Maybe we could use sim.set_numerical(eigensolver_type = ...) instead of the PalacePort API, which is more focused on the physics?

[Alisama20]

Hi Martin, thanks - and I think you're right about the API.

The port call is already awkward with this in it: add_wave_port(max_size=True, eigensolver_max_size=20) has two max_size that mean entirely different things, one a domain-filling flag and one an eigensolver subspace size. That on its own is a good argument for keeping numerics off the physics API.

One wrinkle worth flagging: Palace defines these per wave port, not globally. From its own schema (scripts/schema/config-schema.json, $defs/WavePort), SolverType, EigenTol, KSPTol, MaxSize, MaxIts and Verbose all live inside each Boundaries.WavePort[] entry. So a purely global setter can't express a model whose ports need different treatment - which is a real case when the ports have quite different cross-sections and the 2D eigenproblems are conditioned differently.

So what I'd propose, if it suits you: defaults on set_numerical(...) exactly as you suggest, and keep an optional per-port override for when they diverge. The port API then carries nothing numerical unless someone explicitly asks for it, and we still cover the schema.

Also: MaxIts is in the schema and I did not expose it. I can add it in the same pass.

Happy to restructure it that way - just say which you prefer.

[mdmaas]

Yeah, leaving the per-waveport numerics as optional settings is a good idea.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.02%. Comparing base (ead7c4f) to head (0c17654).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #253      +/-   ##
==========================================
+ Coverage   61.62%   62.02%   +0.39%     
==========================================
  Files         105      106       +1     
  Lines       15304    15427     +123     
  Branches     3029     3041      +12     
==========================================
+ Hits         9431     9568     +137     
+ Misses       4882     4871      -11     
+ Partials      991      988       -3     

☔ 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.