Add QBXRefinementMode enum, deprecate _disable_refinement

[Copilot]

_disable_refinement was a blunt boolean with no way to detect when refinement would be needed without actually doing it. Replaces it with a proper enum supporting three modes.

New API

from pytential.qbx import QBXRefinementMode, QBXRefinementNeededError

# Default: refine as needed (unchanged behavior)
lpot = QBXLayerPotentialSource(..., refinement_mode=QBXRefinementMode.REFINE)

# Skip refinement silently (replaces _disable_refinement=True)
lpot = QBXLayerPotentialSource(..., refinement_mode=QBXRefinementMode.NO_REFINEMENT)

# Run checks, raise QBXRefinementNeededError if refinement would be required
lpot = QBXLayerPotentialSource(..., refinement_mode=QBXRefinementMode.COMPLAIN)

Changes

• pytential/qbx/refinement.py: Added QBXRefinementMode enum (REFINE, NO_REFINEMENT, COMPLAIN) and QBXRefinementNeededError exception. Updated _refine_qbx_stage1 and _refine_qbx_stage2 to check refinement_mode; the COMPLAIN path runs all criteria checks and raises with a message identifying the violated criteria if any refinement would be triggered.

• pytential/qbx/__init__.py: Replaced _disable_refinement: bool attribute with refinement_mode: QBXRefinementMode. Both __init__ and copy() accept the new refinement_mode parameter. _disable_refinement is retained as a deprecated parameter that maps to the equivalent mode with a DeprecationWarning. QBXRefinementMode and QBXRefinementNeededError are exported from pytential.qbx.

• test/extra_int_eq_data.py: Updated to use refinement_mode instead of _disable_refinement.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add a refinement mode: don't refine, but error if stage-1 or stage-2 refinement is needed</issue_title>
<issue_description>Do this by deprecating _disable_refinement and adding an enum for "refinement mode", with "no refinement", "complain", and "refine" as modes.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add a refinement mode: don't refine, but error if stage-1 or stage-2 refinement is needed #309

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.