quartic2d.Interaction.converge_parameters#

classmethod Interaction.converge_parameters(deltas, field1, field2, U_q, *, rtol=0.0001, atol=1e-12, method='gl4', interpolator='cubic', subdivisions=(1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048), n_values=(128, 256, 512, 1024, 2048, 4096), bias=-0.5, bias_values=(-0.65, -0.6, -0.55, -0.5, -0.45, -0.4, -0.35), hstart=0.05, hdecrement=2.0, maxiter=20, ogata_n_values=(64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536, 131072, 262144, 524288), ogata_verification_levels=4, q_boundary_check=True, q_boundary_taper_fraction=0.1, q_boundary_budget_fraction=0.5, verbose=True)#

Calibrate the assembled interaction for explicit numerical criteria.

This is the recommended quantitative convergence entry point for Interaction. It selects method-specific numerical parameters from self-convergence tests of the assembled interaction over the supplied displacement set. The requested rtol is therefore a refinement criterion, not an independent reference-error guarantee.

Finite-grid rules use their known asymptotic order together with a three-resolution Richardson check. FFTLog must stabilize with both transform length and a local bias window. Ogata is calibrated directly on the assembled interaction in the coupled (N, h) space. When an input HarmonicTransform carries automatic q-sampling metadata, an optional downstream q-boundary probe also tests sensitivity to the finite represented support.

Parameters:

  • deltas (array_like, shape (D, 2)) – Cartesian displacement vectors included in the convergence study. The selected parameters are justified for this tested displacement domain; extending the domain can require recalibration.

  • field1 (HarmonicTransform) – Momentum-space transition fields used by the interaction.

  • field2 (HarmonicTransform) – Momentum-space transition fields used by the interaction.

  • U_q (callable) – Scalar radial interaction kernel in momentum space.

  • rtol (float, default=1e-4) – Relative self-convergence threshold applied to successive interaction values. Acceptance is paired with the peak-scaled absolute condition controlled by atol. For finite-grid rules the internal search uses a safety margin before reporting success.

  • atol (float, default=1e-12) – Absolute floor in the peak-scaled maximum-change condition.

  • method ({'fftlog', 'trapezoid', 'simpson', 'gl4', 'gl8', 'ogata'}, default='gl4') – Interaction integration method to calibrate.

  • interpolator ({'linear', 'cubic', 'pchip'}, default='cubic') – Interpolator used for the sampled momentum-space harmonics.

  • subdivisions (iterable of int, optional) – Ordered candidate finite-rule subdivision counts. Used by trapezoid, simpson, gl4, and gl8.

  • n_values (iterable of int, optional) – Ordered FFTLog sequence lengths used for resolution refinement.

  • bias (float, default=-0.5) – Preferred FFTLog bias around which robustness is tested.

  • bias_values (iterable of float, optional) – FFTLog bias values used to establish a local robust window. An n-stable but bias-sensitive result is not accepted.

  • hstart (float, default=0.05) – Initial Ogata resolution parameter used by the coupled search.

  • hdecrement (float, default=2.0) – Multiplicative refinement factor applied to the Ogata h search.

  • maxiter (int, default=20) – Maximum number of Ogata h refinements per tested node count.

  • ogata_n_values (iterable of int, optional) – Ordered Ogata node counts tested during coupled (N, h) calibration.

  • ogata_verification_levels (int, default=4) – Number of subsequent Ogata resolution levels required to remain stable after the first accepted candidate.

  • q_boundary_check (bool, default=True) – If True and either input carries automatic q-sampling metadata, test the assembled interaction against a smooth taper near the outer represented q boundary.

  • q_boundary_taper_fraction (float, default=0.1) – Fraction of the represented q interval over which the robustness probe applies its half-cosine taper. Must satisfy 0 < value < 1.

  • q_boundary_budget_fraction (float, default=0.5) – Fraction of the requested rtol/atol budget allocated to the q-boundary robustness probe. Must satisfy 0 < value <= 1.

  • verbose (bool, default=True) – Print one compact convergence report. Set to False for batch calculations; the returned object retains the complete search.

Returns:

Reusable convergence result containing selected parameters and the full method-specific search history. Use result.interaction(deltas, field1, field2, U_q) to construct a production interaction without rerunning calibration.

Return type:

InteractionConvergenceResult

Raises:

ValueError – If method-specific controls or q-boundary settings are invalid.

Notes

result.converged describes the configured internal refinement and robustness criteria for the supplied represented inputs. It does not assert pointwise or global agreement with an unknown exact solution. When an independent analytic or high-accuracy reference is available, evaluate that error separately.