[jimsweeney]

Adds optional nonlinear refinement for XRay linear-prediction modes, with residual-spectrum initialization for missing modes and batched NumPy/CuPy solves. Fit results include reconstruction, convergence and local uncertainty estimates; benchmark reports retain convergence counts and residual quality. The lpmr command writes an offline comparison page with the actual noise-free input, fitted modes and solver status.

The tools use an unconstrained damped-mode model and remain experimental, alongside the existing constrained production fitter. The guide explains initialization, uncertainty assumptions, convergence limits and timing boundaries. Validation supplies a known mode count; production detector acceptance and end-to-end speedup remain separate work. Includes the corrected diagnostics from #2, which should land first.

Validation: 2,970 full CPU tests, 69 focused refinement/visualization tests including CuPy, and all nine CI-selected GPU cases passed. An independent numerical review and a 114-trace comparison covered noise, close/coincident modes, difficult starts, distortions and long records; expected nonconvergence and local minima are retained in the results. Full lint/hooks and an isolated final-wheel CLI/offline-render smoke passed. The existing GPU CI job now includes three XRay time-scale parity cases.

Refs #1, #2.

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one): 1

• ai-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: NVIDIA/cuPhoton/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 4cfa22d5-9c47-4265-b96d-569a029c70de

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[tpn]

@coderabbitai full review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[tpn]

/ok to test 4150197

[melo-gonzo]

Please check convergence after the final accepted step and add a regression at the iteration limit. The returned parameters and residual include that step, but converged still describes the previous iterate. The example below returns identical parameters for max_iter=5 and 6, yet reports False and True despite both satisfying the stopping criterion. Recompute the final stationarity flag before returning.

Minimal reproducer

Run against this revision with NumPy 2.5.2 and SciPy 1.18.0.

import numpy as np
from cuphoton.xray.mode_refinement_batched import (
    refine_modes_batched, model_and_jacobian_batched,
)
from cuphoton.xray.synthetic_validation import synthetic_modes_trace, modes_to_theta

f = synthetic_modes_trace(96)
x = modes_to_theta(f.modes, f.constant)[None, :]
x[:, [2, 6]] *= 1.05
fits = []
for limit in (5, 6):
    fit = refine_modes_batched(np, f.time, f.clean[None, :], x, 2, max_iter=limit)
    model, jac = model_and_jacobian_batched(np, fit.theta, f.time, 2)
    r = model - f.clean
    scale = np.linalg.norm(jac, axis=1)
    j = jac / np.where(scale > 0, scale, 1)[:, None, :]
    g = np.max(np.abs(np.einsum('bnp,bn->bp', j, r)))
    expected = g <= 1e-9 * max(np.linalg.norm(r), 1)
    print(limit, bool(fit.converged[0]), bool(expected), f'{g:.3e}')
    fits.append(fit)
print('same parameters:', np.array_equal(fits[0].theta, fits[1].theta))

Observed (limit, returned flag, expected flag, gradient):

5 False True 5.650e-11
6 True True 5.650e-11
same parameters: True

The first returned flag should also be True.

[melo-gonzo]

Please fix the final-step convergence status before merging. The returned fit can satisfy the documented stopping criterion while reporting converged=False.

[jimsweeney]

Fix for the final-step convergence flag is on fix-refine-final-convergence in my fork (one commit on top of f342338): it rechecks stationarity on the returned iterate when max_iter is exhausted, plus a regression at the iteration limit using Carmelo's case. @tpn, feel free to cherry-pick it, or I can push it to this branch if you prefer.