Optionally, write an IIS when an xhatter hits an infeasible scenario (#356)

[DLWoodruff]

Resolves #356.

Motivation

An xhatter (incumbent-finder) fixes the first-stage (non-anticipative)
variables at a candidate xhat and solves every scenario subproblem. If a
scenario is infeasible at that xhat, the candidate is silently rejected and
the search moves on. That silence is right almost always — but it is the wrong
behavior when a model is supposed to have (relatively) complete recourse and,
because of a modeling subtlety or data issue, doesn't. The run can then spin a
long time finding no incumbent, with nothing to explain why.

As requested in the issue, this adds an opt-in option that, the first time an
xhatter rejects a candidate due to scenario infeasibility, writes an IIS
(irreducible infeasible set) for the offending subproblem via
pyomo.contrib.iis — "with these first-stage decisions, scenario X is
infeasible because of this handful of constraints."

What it does

A new SPOpt.write_iis_on_xhatter_infeasible() is called from the xhat
infeasibility-detection sites (XhatBase._try_one two-stage + stage2-EF
branches, _PreLoopXhatMixin._evaluate_xhat, Xhat_Eval.calculate_incumbent),
each before any _restore_nonants so the model still carries the infeasible
configuration the IIS re-solve needs. Calling it only from xhat paths scopes
the feature to incumbent-finders by construction; the PH/APH main loop (where
infeasibility is routine) is untouched.

It fires at most once per cylinder (per MPI rank). A guard, set before the
work, ensures the expensive IIS computation cannot repeat — and a failed or
expensive attempt is never retried. The emission is fail-soft: any error is
reported and the run continues. In a parallel run you may get up to one IIS
file per rank that hit an infeasible local scenario, each named by its
scenario (so concurrent writers never collide). Output naming mirrors the
--solver-log-dir convention via a shared _subproblem_file_stem helper:
<cylinder>_<scenario>.ilp / .iis.log.

Options (in popular_args, forwarded in cfg_vanilla.shared_options)

Flag	Default	Meaning
--xhatter-write-iis	off	enable the feature
--xhatter-iis-method	auto	ilp (write_iis, .ilp, commercial persistent solver) / explanation (compute_infeasibility_explanation, any solver) / auto (ilp for cplex/gurobi/xpress, else explanation)
--xhatter-iis-dir	cwd	output directory

The ilp path falls back to letting write_iis auto-pick a persistent solver
when the configured one's persistent interface isn't installed.

Tests

New mpisppy/tests/test_iis_on_infeasible.py (wired into run_coverage.bash
and test_pr_and_main.yml):

• config registration + cfg_vanilla forwarding;
• control flow against a stub (option gating, run-once guard, target
  selection, fail-soft) — no solver needed;
• helper logic (auto resolution, suffix stripping, file stem);
• synthetic end-to-end through the real Xhat_Eval.calculate_incumbent
  path on an incomplete-recourse model: an xhat optimal for one scenario is
  infeasible for another, and the test asserts the IIS file actually lands,
  the run-once guard holds across repeated infeasibilities, and a feasible
  xhat writes nothing. (Solver-gated; the .ilp case also gated on a
  persistent commercial interface.)

Docs

Dedicated doc/src/iis.rst (run-once semantics front and center), added to the
index and cross-referenced from generic_cylinders.rst and
xhat_from_file.rst. Design doc at doc/designs/iis_on_xhat_infeasible_design.md.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 98.52941% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 73.05%. Comparing base (a01c36c) to head (ae8f999).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
mpisppy/extensions/xhatbase.py	50.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #754      +/-   ##
==========================================
+ Coverage   72.98%   73.05%   +0.07%     
==========================================
  Files         165      165              
  Lines       21004    21071      +67     
==========================================
+ Hits        15329    15394      +65     
- Misses       5675     5677       +2     

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