Skip to content

FIX: unify propagator photon-count normalization - #89

Merged
mdw771 merged 5 commits into
mainfrom
propagator-fixes
Nov 16, 2026
Merged

mdw771 merged 5 commits into
mainfrom
propagator-fixes

Conversation

@mdw771

@mdw771 mdw771 commented Oct 29, 2026

Copy link
Copy Markdown
Collaborator

Features/fixes

Standardize propagation so squared wavefield magnitudes represent counts per pixel and lossless propagation preserves their sum.

  • Fourier propagation now uses fixed orthonormal normalization.
  • Fresnel and Fraunhofer use orthonormal transforms with unit-magnitude prefactors (values of the propagated wavefield array is now photon count per pixel, not per unit area).
  • Angular-spectrum normalization is unchanged.

Remove obsolete power-conversion helpers and FFT gradient corrections, simplify probe rescaling, and update preconditioner initialization. Document saved-probe migration and power-constraint units. Migrate BH and autodiff test settings and remove the incorrectly specified power constraints from the DM tests.

Related issues (optional)

#83

Mentions

@stevehenke

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?

@mdw771
mdw771 requested a review from stevehenke October 29, 2026 20:08
@stevehenke

Copy link
Copy Markdown
Collaborator

Thanks, Ming! I reviewed the branch against the discussion post, and the core change looks right to me.

What I verified

  • On a 48×63 grid with anisotropic pixels, all four propagators conserve Σ|ψ|² to float32 precision, forward and backward. I tested far-field, near-field and coarse near-field geometries.
  • propagate_backward inverts propagate_forward (relative error ~1e-7).
  • For z > 0, the Fresnel-transform, Fraunhofer and angular-spectrum outputs match an independent NumPy implementation of the same unitary convention to ~5e-8.
  • test_propagate.py, test_probe_normalization.py and test_bh_derivatives.py pass (182 tests).

Items the discussion doesn't cover

  1. Angular-spectrum runs get a different preconditioner start. PlanarObject.initialize_preconditioner (object.py:773) now uses the far-field weight sqrt(max_power) / (2*H*W) for every propagator. In 2.3.0, angular-spectrum runs used sqrt(max_power) / (2*sqrt(H*W)). Their initial preconditioner is now N times smaller relative to the illumination map, which is the 2.2.0 behavior. Fresnel-transform runs shift by (Fr/ar)². This contradicts the statement that angular-spectrum runs "need no conversion". If geometry independence is the intent, as test_preconditioner_is_independent_of_propagation_geometry suggests, please say so in the announcement. Otherwise, keep the 2.3.0 near-field weight.
  2. LSQML lambda_0 is still absolute. lsqml.py:779 sets lambda_0 = 1.2e-7 / (H*W), PtychoShelves' eps(single)/prod(Np_p), which was calibrated to the old far-field probe units. a11 and a22 scale with |P|², so the relative weight of lambda_0 drops by N in far field and changes by s_F² for Fresnel. This is probably negligible. If so, a comment saying so would help; otherwise, scale it relative to a11/a22.
  3. Minor: the position step size could stop depending on the propagator. The far-field position step needs dividing by N only because position gradients scale with probe amplitude. If scale_gradients normalized them by probe intensity, as it already normalizes object gradients by max |P|², tuned position step sizes would carry over between propagators. This would be a further behavior change, so it may belong in a follow-up.

@mdw771

mdw771 commented Oct 30, 2026

Copy link
Copy Markdown
Collaborator Author

Thanks for reviewing the changes and putting together these comments!

As I understand it, the goals we are pursuing are:

  • All propagators should conserve total intensity under lossless propagation.
  • Object transmission and its LSQML updates should retain their scale under a change of field units.
  • Probe values and updates should scale together. For the default Fourier propagator, this means they would both be scaled up by s = sqrt(HW) when replacing the unnormalized FFT with ortho.
  • The reconstruction routines should not need propagator-specific normalization corrections.

Regarding comment 1, I've removed the max_power and pixel-count factors and now initialize the preconditioner as C_0 = L, where L is the current probe illumination map:

preconditioner_seed = illumination_map

The previous factor came from our adaptation of PtychoShelves. Its load_from_p divides the actual reconstruction probe by 2 * sqrt(HW) * p.renorm to convert between CPU and GPU engine units. Then init_solver builds the illumination map from that probe, before optional initial probe rescaling. Our adaptation applied the conversion only to a temporary probe for preconditioning. Pty-Chi already stores the probe in its reconstruction units, so we can build the seed directly from it.

Under a consistent change of field units, scaling the probe by s scales both the raw object update direction and the illumination map by |s|². Their ratio therefore preserves the preconditioned object direction. Subsequent updates still average the preconditioner with the new illumination map, which preserves this scaling. The measured data continue to determine the residual and probe calibration; an additional max_power factor in the seed is unnecessary.

This intentionally changes the initialization heuristic for both far-field and near-field runs. Although LSQML's fitted step size compensates for a scalar change in the preconditioner, averaging maps from an evolving probe can change the spatial weighting and reconstruction trajectory. Angular-spectrum probes require no amplitude conversion, but their iteration histories can change through this initialization. I'll clarify in the announcement that the seed change affects both geometries.

For comment 2, I've removed lambda_0. The diagonal damping from lambda_lsq * mean(a_ii) remains and scales with the direction energies. Identically zero directions are handled explicitly to avoid singular solves.

For comment 3, I agree that position-gradient preconditioning belongs in a follow-up. The existing patterns.numel() / len(patterns) factor compensates for pixel averaging in the loss; the batch-averaging factor remains. The far-field step-size migration comes from removing the previous blanket division of gradients by HW. I'll leave the position-gradient hook unchanged in this PR and revisit its intensity and batch-size dependence separately.

These changes are pushed in 370c625. All 72 focused tests pass, including checks of actual object/probe updates across equivalent field representations. The GPU regression run has 21 passes and the existing affine-position failure, with a relative L2 error of 0.306% against its reference. Among the passing reconstruction comparisons, the largest relative L2 error is 0.0171%; object RMS amplitudes differ from the references by less than 0.001% across the run.

@stevehenke

Copy link
Copy Markdown
Collaborator

Thanks, Ming. 370c625 addresses all three points from my last review, and I think the code changes are correct. The reference tests show what still needs doing before merge.

What I verified

  • Preconditioner seed. Seeding with the current illumination map matches PtychoShelves. init_solver builds illum_sum_0 from the already converted probe, and the first ptycho_solver refresh averages it with the same map, which gives C₁ = L. The other consumers normalize the preconditioner (w / mnorm(w), position_weights / mean). So its absolute scale reaches only LSQML's preconditioned direction, where the solved step cancels it.
  • Removing lambda_0. The 2×2 system stays positive definite without it. The relative lambda_lsq damping makes the determinant at least d₁d₂ > 0, because |a12|² ≤ a11·a22. The zero-direction guards are correct. Restoring lambda_0 on HEAD left the reference results unchanged to ~1e-9 relative, so the removal is safe.
  • test_lsqml_scaling.py is a strong test, and all 780 unit tests pass.

Reference tests (current CI data at 120aed9, run on GPU)

Thirteen tests fail on the branch that pass at its base, 2d707d2:

  1. Expected; the references need regenerating:

    • test_2d_ptycho_dm and test_2d_ptycho_dm_position_correction. The object amplitude goes from ~0.003 to ~1.6, which is the corrected power constraint.
    • Seven LSQML tests, caused by the preconditioner seed and not by lambda_0. Mean |Δ| is 2e-5 to 1.5e-4:
      • test_2d_ptycho_lsqml
      • test_2d_ptycho_lsqml_no_epoch0_rescaling
      • test_2d_ptycho_lsqml_poscorr
      • test_2d_ptycho_lsqml_compact_no_epoch0_rescaling
      • test_2d_ptycho_opt_plan
      • test_data_on_gpu_lsqml
      • test_multislice_ptycho_lsqml_joint_step_size

    Please also add the seed change to the announcement's comparison section. It changes LSQML trajectories in every geometry. In 2.3.0, angular-spectrum runs weighted the seed by max_power / (4*H*W), which can be ~10⁴, so the old preconditioner stayed tied to the initial probe for several refreshes.

  2. Unmigrated test: test_multislice_ptycho_autodiff_slice_spacing_opt. I applied the table's far-field conversions (probe Adam lr and eps ×√N, position SGD step ÷N). It then matches the existing reference without any change to the reference data. The slice-spacing optimizer needs no conversion of its own. This also independently confirms the table.

  3. OPR drift, beyond the autodiff case already mentioned in the discussion. These come from the normalization commits, not the LSQML commit:

    • test_2d_ptycho_autodiff_opr: mean |Δ| 2.6e-3
    • test_2d_ptycho_epie_opr: 3.5e-5
    • test_2d_ptycho_lsqml_opr: 1.2e-4

    Two causes are ruled out:

    • OPR-weight Adam eps. Scaling it by N had no effect.
    • Eigenmode amplitude relative to the probe. add_additional_opr_probe_modes_to_probe uses unit RMS amplitude. Scaling the added modes by √N left ePIE and LSQML unchanged and made autodiff worse.

test_2d_ptycho_epie_orthogonalize_opr_and_incoherent_modes fails at the base as well, so it is unrelated to this branch.

Use unitary detector propagation, remove obsolete normalization corrections, and migrate reconstruction test settings. Document saved-probe conversion and verify power conservation, adjoints, and reconstruction behavior.

Validation: 516 focused CPU tests passed. GPU rerun after test migration: 8 passed, with affine-position LSQML and autodiff OPR reference mismatches remaining at approximately 0.31% and 0.33% relative L2 error.
@mdw771
mdw771 merged commit d1347f8 into main Nov 16, 2026
2 checks passed
@mdw771
mdw771 deleted the propagator-fixes branch November 16, 2026 17:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants