Skip to content

PtyLab Documentation - API Documentations - #102

Merged
ShantanuKodgirwar merged 21 commits into
PtyLab:mainfrom
cliulucien:initial_doc_changes
Sep 30, 2026
Merged

ShantanuKodgirwar merged 21 commits into
PtyLab:mainfrom
cliulucien:initial_doc_changes

Conversation

@cliulucien

@cliulucien cliulucien commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

No description provided.

@cliulucien
cliulucien marked this pull request as draft September 23, 2026 09:58
@ShantanuKodgirwar

ShantanuKodgirwar commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

HI @cliulucien, looks like some serious bugs. If you see them, please report it separately under issues and if you fix those, please do so with a separate PR tagging those issues.

Comment thread PtyLab/ExperimentalData/ExperimentalData.py Outdated
Chang Liu added 2 commits September 25, 2026 16:56
- implement dtype matching used by convert2single()
- return linear and area overlap metrics from getOverlap()
- use normalized probe-amplitude autocorrelation for area-overlap estimation
The method requires JAX, which is imported when the function is
called.
"""
import jax

@ShantanuKodgirwar ShantanuKodgirwar Sep 29, 2026 •

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.

How did jax get here? If this requires some AD stuff, we need to rethink how to place this function correctly. Looking at the code below, we can use existing dependencies for this. Maybe if you could add this as an issue along with other issues/bugs you found, that would be great.

Display the measured ptychogram stack on a logarithmic intensity scale.

The diffraction patterns are clipped to non-negative values, converted to
``log10(I + 1)`` for visualization, and displayed with an interactive

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.

We could use xp.log1p(I) to avoid adding this 1. Not as important but feel free to make that edit in the below code if you like

@cliulucien cliulucien changed the title Initial doc changes PtyLab Documentation - API Documentation Sep 30, 2026
@cliulucien cliulucien changed the title PtyLab Documentation - API Documentation PtyLab Documentation - API Documentations Sep 30, 2026
@cliulucien

Copy link
Copy Markdown
Contributor Author

What and why

This PR improves the API documentation for the main reconstruction engines
and shared reconstruction utilities.

Current finished module:

  • ExperimentalData
  • 'Reconstruction'
  • BaseEngine
  • 'ePIE'
  • 'mPIE'

The main changes include:

  • expanded BaseEngine docstrings for shared reconstruction utilities and
    constraints
  • documented the standard ePIE object and probe update rules
  • documented the mPIE/rPIE regularized object and probe update rules
  • documented momentum acceleration in mPIE
  • documented optional TV regularization and its relationship to
    objectTVregSwitch, objectTVfreq, and objectTVregStepSize
  • clarified position correction, probe constraints, orthogonalization, and
    other switch-controlled reconstruction behavior
  • added references for reconstruction algorithms where appropriate
  • improved selected ExperimentalData API descriptions

The goal is to make the API reference useful for both users who want to
configure reconstructions and developers who want to understand how the
corresponding algorithms are implemented.

How it was tested

The documentation was built locally with MkDocs and checked through the
rendered API reference.

Docstrings were reviewed for:

  • correct MkDocs / mkdocstrings rendering
  • correct equation rendering
  • valid cross-references between engines and shared BaseEngine methods
  • consistency between documented behavior and the current implementation

Relevant reconstruction tests were also run while documenting and refactoring
the affected engine functionality.

Notes

This PR mainly changes documentation and docstrings.

Some implementation issues and cleanup opportunities were identified while
reviewing the code and are being handled separately, including consolidation
of duplicated reconstruction-engine functionality.

Several Params options still require dedicated API documentation so that
their switches, numerical values, and corresponding implementation methods
can be described in one place.

@cliulucien
cliulucien marked this pull request as ready for review September 30, 2026 14:47
Comment thread pyproject.toml Outdated
@@ -34,6 +34,7 @@ dev = [
gpu = ["cupy-cuda12x[ctk]"]

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.

Could you please change this line to gpu = ["cupy-cuda12x[ctk]; sys_platform != 'darwin'"]

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.

cupy does not support mac

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.

added

Comment thread pyproject.toml
module-name = "PtyLab"
module-root = ""

[tool.uv]

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.

Maybe also mention all the devices instead of just windows. Pyqt5 is an annoying dependency

[tool.uv]
# Platforms the lockfile must be installable on. Wheel-only packages (pyqt5-qt5,
# cupy, torch) are checked against each; uv falls back to older versions if needed.
required-environments = [
    "sys_platform == 'linux' and platform_machine == 'x86_64'",
    "sys_platform == 'win32' and platform_machine == 'AMD64'",
    "sys_platform == 'darwin' and platform_machine == 'arm64'",
]

@ShantanuKodgirwar

Copy link
Copy Markdown
Contributor

LGTM!

@ShantanuKodgirwar
ShantanuKodgirwar merged commit d879aba into PtyLab:main Sep 30, 2026
3 checks passed
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