quartic2d.HarmonicTransform.converge_parameters#

classmethod HarmonicTransform.converge_parameters(decomposition, *, rtol=0.0001, atol=1e-12, q_tail_rtol=0.001, method='simpson', interpolator='cubic', subdivisions=(1, 2, 4, 8, 16, 32), pilot_subdivisions=2, verbose=True)#

Find harmonic-transform parameters that meet explicit numerical tolerances.

This is the expensive, opt-in calibration path. Normal transforms do not call it. The routine refines three independent numerical choices:

  1. q_max – how far the momentum-space transform must be followed before the omitted q-space norm is small;

  2. n_q – how many samples are needed to interpolate the transform accurately between q-grid points;

  3. radial quadrature resolution – how finely the PETAL2D radial profiles must be integrated.

Parameters:

  • decomposition (petal2d.PolarDecomposition) – Retained PETAL2D angular harmonics and their radial profiles.

  • rtol (float, default=1e-4) – Internal self-convergence threshold for q-grid interpolation and radial quadrature on the represented q interval. Acceptance uses both relative L2 change <= rtol and maximum absolute change <= atol + rtol * peak. Relative Linf change is retained as a diagnostic only. This criterion does not determine how much q-space may be omitted and is not an independent reference-error guarantee.

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

  • q_tail_rtol (float, default=1e-3) – Maximum relative L2 norm allowed outside the selected q_max for every retained harmonic. This is a momentum-support/truncation tolerance, not a quadrature tolerance. The default is validated by the interaction benchmark; choose a smaller value when the form factors themselves require stricter tail control.

  • method ({'trapezoid', 'simpson', 'gl4', 'gl8'}, default='simpson') – Radial quadrature method to calibrate. Simpson is the release default; validation evidence for the tested workload portfolio is reported separately in the numerical-method and validation pages.

  • interpolator ({'linear', 'cubic', 'pchip'}, default='cubic') – Interpolation used for the sampled PETAL2D radial profiles and the tabulated form factors. Cubic q-space interpolation uses not-a-knot end conditions.

  • subdivisions (iterable of int, default=(1, 2, 4, 8, 16, 32)) – Candidate refinements for finite-grid radial quadrature. A value of 4, for example, inserts three intermediate integration points inside each original PETAL2D radial interval. Larger values increase the radial integration cost approximately linearly.

  • pilot_subdivisions (int, default=2) – Initial radial refinement used by the canonical Simpson pilot that converges q support and q-grid density. Sampling is a property of the represented transform rather than of the production quadrature backend. If the requested backend requires a finer radial refinement, only the canonical sampling study is repeated at that finer resolution before returning the selected parameters.

  • verbose (bool, default=True) – Print one compact convergence report. Set to False for batch jobs; the returned result still contains the full diagnostics.

Returns:

Calibration result containing the selected parameters and full refinement diagnostics. Check result.converged before using result.transform(decomposition) to build a production transform.

Return type:

HarmonicConvergenceResult

Notes

Convergence is intentionally separate from the ordinary constructor so that production transforms pay only for the requested calculation.