HarmonicTransform#

HarmonicTransform converts the radial angular harmonics retained by PETAL2D into the momentum-space form factors used by the four-center interaction. The ordinary constructor evaluates one explicit numerical representation; HarmonicTransform.converge_parameters() provides an explicit convergence search when a numerical criterion is required.

class quartic2d.HarmonicTransform(decomposition, q_max=None, *, n_q=None, q_grid=None, method='simpson', interpolator='cubic', subdivisions=2, N=2048, h=None, check=True)#

Transform retained PETAL2D angular harmonics to momentum space.

In ordinary use only the PETAL2D decomposition is required:

transformed = HarmonicTransform(decomposition)

QUARTIC2D then uses benchmarked, scale-aware defaults for the momentum range and q-grid density, performs each Hankel transform once, and runs inexpensive sanity checks on the result. These checks never launch a second transform. If they detect signs of insufficient support or sampling, a concise warning recommends the explicit convergence helper.

Parameters:

  • decomposition (petal2d.PolarDecomposition) – Polar harmonic decomposition produced by PETAL2D. QUARTIC2D uses its retained radial profiles and per-harmonic cutoff_radius values.

  • q_max (float or None, optional) – Largest momentum represented by the transform. None uses a fast, scale-aware estimate based on the RMS momentum content of the retained radial profiles, capped safely below the momentum Nyquist limit implied by the PETAL2D radial spacing. Supply a value when a downstream model requires a specific q range. The fast diagnostics warn if the selected range appears too short; converge_parameters performs the explicit q-support refinement study when needed.

  • n_q (int or None, optional) – Number of uniformly spaced momentum samples between 0 and q_max. None chooses a conservative grid from the retained real-space support, bounded between 64 and 512 points for predictable cost. This controls how accurately the tabulated form factors can be interpolated; it does not change the radial quadrature itself. Ignored as a grid generator when q_grid is supplied, but if both are supplied it must equal len(q_grid).

  • q_grid (array_like or None, optional) – Explicit strictly increasing momentum grid beginning at zero. This is primarily used by converge_parameters to reuse its directly converged adaptive q grid in production. Supplying an explicit grid does not weaken interpolation checks; the convergence helper verifies every final interval against direct Hankel evaluations before returning it.

  • method ({'trapezoid', 'simpson', 'gl4', 'gl8', 'ogata'}, default='simpson') – Numerical rule used for the radial Hankel integral. Simpson is the release default. Method-specific validation and performance evidence are documented separately from this API contract.

  • interpolator ({'linear', 'cubic', 'pchip'}, default='cubic') – Interpolation used between the PETAL2D radial samples. Cubic interpolation of the resulting q-space form factors uses not-a-knot end conditions, which avoid imposing an artificial zero second derivative at q=0.

  • subdivisions (int, default=2) – Radial integration refinement for finite-grid methods. A value of 2 splits every original PETAL2D radial interval once before composite Simpson integration. Larger values cost approximately linearly and are available when a case requires explicit convergence. Validation of the release default is reported separately from this parameter definition.

  • N (int, default=2048) – Number of Ogata quadrature nodes when method='ogata'. Larger values provide a denser Ogata representation at higher computational cost. This parameter is ignored by finite-grid methods.

  • h (float or None, optional) – Ogata spacing/resolution parameter. None uses pi/N. Smaller values resolve finer transform structure but generally require more effective work. This parameter is ignored by finite-grid methods.

  • check (bool, default=True) – Run fast post-transform fault detectors and emit one concise warning if the result shows signs of inadequate q support or sampling. The checks only inspect arrays already computed by the transform; they do not run convergence studies or additional Hankel transforms.

F_q#

Momentum-space harmonic profiles keyed by angular index m.

Type:

dict[int, ndarray]

diagnostics#

Results of the inexpensive sanity checks. diagnostics.healthy is True when no fault detector was triggered.

Type:

HarmonicTransformDiagnostics

See also

HarmonicTransform.converge_parameters

Opt-in, quantitative convergence of q support, q-grid interpolation, and radial quadrature.

Typical workflow#

Start from a PETAL2D decomposition, inspect the default transform, then run an explicit convergence search when the calculation needs a recorded numerical criterion:

field = HarmonicTransform(decomposition)
field.plot_harmonics()

result = HarmonicTransform.converge_parameters(
    decomposition,
    rtol=1e-4,
    q_tail_rtol=1e-3,
)
if not result.converged:
    raise RuntimeError("harmonic-transform convergence search did not converge")
field = result.transform(decomposition)
field.plot_convergence()

The convergence plots visualize the internal refinement tests. They do not replace an independent reference comparison when one is available.

Advanced mutation and low-level convergence#

These methods are useful for controlled numerical studies. They are not a substitute for the full q-support plus quadrature workflow provided by HarmonicTransform.converge_parameters().

set_method(method, *[, subdivisions, N, h])

Select the radial quadrature and recompute all retained harmonics.

set_interpolator(interpolator)

Select the radial interpolator and recompute all retained harmonics.

converge(*[, rtol, atol, subdivisions, ...])

Converge only the radial quadrature on the current q grid.