FEAT: real space scaling optimization

[mdw771]

Features/fixes

Added support for far-field detector-scale refinement through a new RealSpaceScaling reconstruction parameter. This parameter is now part of the standard ParameterGroup alongside the object, probe, probe positions, and OPR weights, and is initialized as a scalar tensor of shape (1,) with default value 1.0. The feature is disabled by default so existing reconstructions remain unchanged unless explicitly enabled. When enabled, Pty-Chi applies a multiplicative real-space scaling to the exit wave before detector propagation, matching the detector-scale correction strategy used in PtychoShelves. For analytical reconstructors, the corresponding adjoint scaling is applied on the backward pass so the modified forward and inverse propagation operators remain consistent. The update rule in RealSpaceScaling follows the PtychoShelves geometry-refinement formulation: it uses object gradients, Tukey-window-weighted spatial coordinates, and probe weighting to estimate a scalar correction from the current exit-wave residual. In far-field reconstructions, this gives a direct way to refine detector pixel scale, and equivalently sample-to-detector distance, within the non-autodiff reconstruction framework.

The API exposes this through real_space_scaling_options. A typical setup looks like:

import ptychi.api as api

options = api.LSQMLOptions()
options.data_options.data = data
options.object_options.initial_guess = obj0
options.object_options.pixel_size_m = pixel_size_m
options.probe_options.initial_guess = probe0
options.probe_position_options.position_x_px = positions_px[:, 1]
options.probe_position_options.position_y_px = positions_px[:, 0]

options.real_space_scaling_options.optimizable = True
options.real_space_scaling_options.initial_guess = 1.0
options.real_space_scaling_options.step_size = 1e-3
options.real_space_scaling_options.optimizer = api.Optimizers.SGD

task = api.PtychographyTask(options)
task.run()

scale = task.get_data_to_cpu("real_space_scaling", as_numpy=True)
print("Refined real-space scaling:", scale[0])

To avoid double-counting the same far-field geometry ambiguity, the API now warns if real_space_scaling is enabled at the same time as affine probe-position refinement with AffineDegreesOfFreedom.SCALE, which is the Pty-Chi equivalent of the mutual-exclusion warning in PtychoShelves.

Checklist (Don't skip!)

To check a checklist item, change the space in the backets with an x, i.e., [ ] -> [x].

Have you...

• Formatted your code properly adhering to PEP-8? Considering using RUFF to format your code automatically (https://docs.astral.sh/ruff/installation/).
• Cleaned up your code to remove large commented-out blocks?
• Properly documented any new API knobs and functions with non-trivial signatures?
• Resolved all merge conflicts with the main branch?
• Checked the diffs between your branch and the main branch to ensure that your changes are not introducing any regressions or unnecessary/irrelevant changes?
• Checked the diffs to ensure your PR only includes one feature/fix? Multiple features/fixes/changes should be split into different PRs.
• Added unit tests for new features if necessary?