Skip to content

Add complete three-step formulas to reconstruction network docstrings - #323

Merged
nducros merged 18 commits into
masterfrom
copilot/add-formula-to-dcnet
Jan 24, 2026
Merged

nducros merged 18 commits into
masterfrom
copilot/add-formula-to-dcnet

Conversation

Copilot AI commented Jan 19, 2026 •

Copy link
Copy Markdown
Contributor

Summary: Add formulas to reconstruction network docstrings ✅

Completed Changes:

  • Added complete three-step formulas to DCNet class docstring

    • Step 1: Preprocessing m̃ = By
    • Step 2: Tikhonov regularization with actual implementation formula x^Tik = x₀ + F⁻¹[m₁; m₂] and its relationship to the minimization problem x^Tik = argmin ||m̃ - GFx||²_{Σ_α^{-1}} + ||F(x - x₀)||²_{Σ^{-1}}
    • Step 3: Neural network x̂ = G_θ(x^Tik)
  • Added complete three-step formulas to PinvNet class docstring

    • Step 1: Preprocessing m̃ = By
    • Step 2: Pseudo-inverse x† = H†m̃
    • Step 3: Neural network x̂ = G_θ(x†)
    • Added mathematical symbols to Args section (𝒩∘A, B, 𝒢_θ)
  • Added complete three-step formulas to TikhoNet class docstring

    • Step 1: Preprocessing and Tikhonov reconstruction
    • Step 2: Neural network denoising
  • Verified LearnedPGD already has complete formula

  • Updated notation from D_θ to G_θ for consistency with Optics Express paper

  • Added paper reference to all three reconstruction networks

  • Updated DCNet header to match PinvNet structure and formatting

  • Fixed Tikhonov formula and spelling errors

  • Fixed PinvNet denoi attribute description

  • Added mathematical symbols to PinvNet Args section

  • Updated DCNet step 2 with actual Tikhonov formula showing the implementation details (m₁, m₂, D₁, Σ decomposition) and its approximation relationship to the minimization problem

Reference: JFJP Abascal, T Baudier, R Phan, A Repetti, N Ducros, "SPyRiT 3.0: an open source package for single-pixel imaging based on deep learning," Optics Express, Vol. 33, Issue 13, pp. 27988-28005 (2025). https://doi.org/10.1364/OE.559227

Original prompt

This section details on the original issue you should resolve

<issue_title>Add formula to DCNet</issue_title>
<issue_description>and more generally to all reconstruction networks...</issue_description>

<agent_instructions>Add formula in docstring</agent_instructions>

Comments on the Issue (you are @copilot in this section)


💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: nducros <22100601+nducros@users.noreply.github.com>
Copilot AI changed the title [WIP] Add formula to DCNet and reconstruction networks Add mathematical formulas to reconstruction network docstrings Jan 19, 2026
Copilot AI requested a review from nducros January 19, 2026 16:27
@nducros

nducros commented Jan 19, 2026

Copy link
Copy Markdown
Member

@copilot PinvNet, DCNet, and TikhoNet are two-step methods. The added formulas are fine, but they only correspond to the first step. The second step is a learnable step (neural network) that applies to the output of the first step. They are formally describes by Equation 4 and 5 of the open access paper here: https://doi.org/10.1364/OE.559227

Update docstrings for PinvNet, DCNet, and TikhoNet to explicitly describe
both steps: (1) analytical reconstruction and (2) learnable denoising.
The formulas now show x̃ for the first step output and x̂ for the final
output after denoising with D_θ.

Co-authored-by: nducros <22100601+nducros@users.noreply.github.com>

Copilot AI commented Jan 19, 2026 •

Copy link
Copy Markdown
Contributor Author

@copilot PinvNet, DCNet, and TikhoNet are two-step methods. The added formulas are fine, but they only correspond to the first step. The second step is a learnable step (neural network) that applies t...

Updated the docstrings to clarify the two-step nature of these reconstruction methods. The formulas now show:

  1. First step: Analytical reconstruction (pseudo-inverse or Tikhonov) producing x̃
  2. Second step: Learnable denoising D_θ(x̃) producing final output x̂

Changes in commit 5d6af03.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • doi.org
    • Triggering command: /usr/bin/curl curl -s REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Copilot AI changed the title Add mathematical formulas to reconstruction network docstrings Add complete two-step formulas to reconstruction network docstrings Jan 19, 2026
@nducros

nducros commented Jan 19, 2026

Copy link
Copy Markdown
Member

@copilot Replace D (learnable denoising) by G for consistency with the Optics Express paper. Also reference the Optics Express paper.

Change learnable operator notation from D_θ to G_θ for consistency with
Optics Express paper. Add reference to the paper in all three
reconstruction network docstrings (PinvNet, DCNet, TikhoNet).

Co-authored-by: nducros <22100601+nducros@users.noreply.github.com>

Copilot AI commented Jan 19, 2026

Copy link
Copy Markdown
Contributor Author

@copilot Replace D (learnable denoising) by G for consistency with the Optics Express paper. Also reference the Optics Express paper.

Updated notation from D to G (G_θ) in all three reconstruction networks and added paper reference to the docstrings. Changes in commit e9e43c1.

@tbaudier

Copy link
Copy Markdown
Collaborator

pre-commit.ci autofix

pre-commit-ci Bot and others added 2 commits January 20, 2026 09:11
Updated the OS and Python versions in the CI workflow matrix, removing older macOS versions not supported by Github and adding macOS 15 and Python 3.14.
@nducros
nducros marked this pull request as ready for review January 20, 2026 11:18
@nducros

nducros commented Jan 23, 2026

Copy link
Copy Markdown
Member

@copilot Update the header of DCnet in accodance with the header of PinvNet (see my last commit)

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This pull request adds comprehensive mathematical formulas to the docstrings of three reconstruction network classes (PinvNet, DCNet, TikhoNet) that implement two-step reconstruction methods combining analytical reconstruction with learnable neural networks. However, the PR also includes unrelated CI/CD workflow changes.

Changes:

  • Added detailed two-step mathematical formulations to PinvNet, DCNet, and TikhoNet docstrings showing both analytical reconstruction (Step 1) and neural network refinement (Step 2)
  • Added paper references to all three reconstruction network classes
  • Enhanced PinvNet docstring with additional examples
  • Modified CI/CD workflows to test Python 3.14 (which does not exist) instead of 3.9, and changed macOS test runners

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File Description
spyrit/core/recon.py Added mathematical formulas and paper references to PinvNet, DCNet, and TikhoNet docstrings; enhanced examples for PinvNet
.github/workflows/main.yml Updated Python version matrix (removing 3.9, adding 3.14) and macOS runner versions (unrelated to PR purpose)

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread spyrit/core/recon.py Outdated
:attr:`pinv` (:class:`spyrit.core.inverse.PseudoInverse`): Pseudo inverse operator :math:`H^\dagger`.

:attr:`denoi` (:obj:`torch.nn.Module`): Image denoising operator.
:attr:`denoi` (:obj:`torch.nn.Module`): Image denoising operator :math:`\mathcal{G}_\theta\circ H^\dagger \circ B`.

Copilot AI Jan 23, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The denoi attribute description incorrectly states it represents the full composition 𝒢_θ∘H†∘B. However, based on the code structure and the three-step process described above, denoi should only represent 𝒢_θ (the neural network component), not the entire reconstruction pipeline. The full composition 𝒢_θ∘H†∘B is what recon_modules represents, which is correctly described on line 368.

Suggested change
:attr:`denoi` (:obj:`torch.nn.Module`): Image denoising operator :math:`\mathcal{G}_\theta\circ H^\dagger \circ B`.
:attr:`denoi` (:obj:`torch.nn.Module`): Image denoising operator :math:`\mathcal{G}_\theta`.

Copilot uses AI. Check for mistakes.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in commit 4499488. The denoi attribute now correctly represents only G_θ.

Restructure DCNet docstring header to follow the same pattern as PinvNet:
- More concise opening line
- Describe measurement simulation first
- Present signal estimation as three numbered steps
- Use consistent notation (x^Tik for Tikhonov output)
- Match the formatting and structure of PinvNet

Co-authored-by: nducros <22100601+nducros@users.noreply.github.com>

Copilot AI commented Jan 23, 2026

Copy link
Copy Markdown
Contributor Author

@copilot Update the header of DCnet in accodance with the header of PinvNet (see my last commit)

Updated DCNet header to match PinvNet structure. The docstring now follows the same format with measurement simulation first, then three numbered steps for signal estimation. Changes in commit 9ed8496.

- Correct Tikhonov formula to use m̃ instead of GFm̃ in first term
- Fix spelling: 'Tikhonv' -> 'Tikhonov'
- Fix spelling: 'regularizaiton' -> 'regularization'

Co-authored-by: nducros <22100601+nducros@users.noreply.github.com>
Copilot AI changed the title Add complete two-step formulas to reconstruction network docstrings Add complete three-step formulas to reconstruction network docstrings Jan 23, 2026
@nducros

nducros commented Jan 23, 2026

Copy link
Copy Markdown
Member

@copilot As for PinvNet: Add mathematical

Correct denoi attribute to only represent G_θ (the neural network),
not the full composition G_θ∘H†∘B which is represented by recon_modules.

Co-authored-by: nducros <22100601+nducros@users.noreply.github.com>

Copilot AI commented Jan 23, 2026

Copy link
Copy Markdown
Contributor Author

@copilot As for PinvNet: Add mathematical

Your comment appears incomplete ("As for PinvNet: Add mathematical"). Could you clarify what mathematical content you'd like me to add to PinvNet?

Copilot stopped work on behalf of nducros due to an error January 23, 2026 19:13
@nducros

nducros commented Jan 23, 2026

Copy link
Copy Markdown
Member

@copilot As for PinvNet: Add corresponding mathematical symbols for arguments and attributes.

Add corresponding mathematical symbols (𝒩∘A, B, 𝒢_θ) to the Args section
to match the formulas and Attributes section.

Co-authored-by: nducros <22100601+nducros@users.noreply.github.com>

Copilot AI commented Jan 23, 2026

Copy link
Copy Markdown
Contributor Author

@copilot As for PinvNet: Add corresponding mathematical symbols for arguments and attributes.

Added mathematical symbols to PinvNet Args section in commit 160091a. The args now include the corresponding mathematical notation (𝒩∘A, B, 𝒢_θ) matching the formulas and Attributes section.

@nducros

nducros commented Jan 23, 2026

Copy link
Copy Markdown
Member

@copilot Update step 2 two by providing the actual formula implemented in the class, which is given in the TikhonovMeasurementPriorDiag.forward docstring. Then mention this is an approximation of the minimization problem already referenced. Make sure all notations are consistent and all mathematical symbols defined.

Add the actual Tikhonov formula implemented in TikhonovMeasurementPriorDiag
showing x^Tik = x₀ + F⁻¹[m₁; m₂] with m₁ and m₂ definitions. Clarify this
is an approximation to the minimization problem. Define all mathematical
symbols consistently.

Co-authored-by: nducros <22100601+nducros@users.noreply.github.com>

Copilot AI commented Jan 23, 2026

Copy link
Copy Markdown
Contributor Author

@copilot Update step 2 two by providing the actual formula implemented in the class, which is given in the TikhonovMeasurementPriorDiag.forward docstring. Then mention this is an approximation of the ...

Updated DCNet step 2 in commit d7d8129. The docstring now shows:

  1. The actual formula implemented: x^Tik = x₀ + F⁻¹[m₁; m₂] with definitions for m₁, m₂, D₁, and Σ decomposition
  2. Clarification that this approximates the minimization problem
  3. All mathematical symbols are consistently defined throughout

@nducros
nducros merged commit ce204e5 into master Jan 24, 2026
26 checks passed
@nducros
nducros deleted the copilot/add-formula-to-dcnet branch January 24, 2026 14:23
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.

Add formula to DCNet

4 participants