fast-acbf 0.7.0__tar.gz

fast_acbf-0.7.0/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

fast_acbf-0.7.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: fast-acbf
+Version: 0.7.0
+Summary: GPU-based Bright-field Ptychography Solver for tcBF and acBF built on PtyRAD
+Author-email: Chia-Hao Lee <cl2696@cornell.edu>
+License-Expression: LGPL-3.0
+Project-URL: Repository, https://github.com/chiahao3/fast-acbf
+Project-URL: Changelog, https://github.com/chiahao3/fast-acbf/blob/main/CHANGELOG.md
+Project-URL: PtyRAD, https://github.com/chiahao3/ptyrad
+Keywords: Ptychography
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: h5py
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: psutil
+Requires-Dist: scipy
+Requires-Dist: torch>=2.4
+Requires-Dist: torchvision
+Requires-Dist: ptyrad
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: zarr>=3.0; extra == "dev"
+Dynamic: license-file
+
+# GPU-accelerated tcBF and acBF
+
+This repository provides a fast GPU implementation of aberration-corrected bright-field 4D-STEM (tcBF/acBF) reconstruction.
+
+It is designed to serve as the seed for:
+
+1. Future native integration of tcBF and acBF into [PtyRAD](https://github.com/chiahao3/ptyrad) pipeline
+2. Real-time visualization during 4D-STEM data acquisition
+
+The underlying imaging theory and initial CPU implementation of **acBF** were developed by Dr. Desheng Ma and Dr. Steven Zeltmann [1, 2], while the **tcBF** method has a longer history; readers are encouraged to read this paper by Dr. Yue Yu [3].
+
+This implementation (**fast-acBF**) was developed independently focusing on GPU acceleration and integration with the PtyRAD reconstruction framework. It is shared as a working research implementation; interfaces may change as development continues.
+
+## Installation guide
+
+**Major Dependencies:**
+- python >=3.10
+- pytorch >=2.4
+- ptyrad
+
+### 1. Get the fast-acBF code from GitHub
+You can either download the repository as a .zip file and extract it, or use the following command if you have `git` installed.
+
+```bash
+git clone https://github.com/chiahao3/fast-acbf
+```
+
+### 2. Create and Activate the Python Environment
+Assuming you're using conda, you can create an independent environment and install the packages with these commands:
+
+```bash
+# Enter the commands one by one
+conda create -n fast-acbf python=3.12 -y
+conda activate fast-acbf
+cd fast-acbf
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126
+pip install -e .
+```
+
+If you prefer a legacy version of PyTorch, or a different version of CUDA runtime other than CUDA 12.6, see instruction [here](https://pytorch.org/get-started/previous-versions/).
+
+## Get Started
+
+1. Download the demo tBL-WSe2 data "Figure 4.zip" from the [Zenodo link](https://doi.org/10.5281/zenodo.15283331)
+2. Run the `get_acBF.ipynb` Jupyter notebook to reconstruct tcBF / acBF images
+
+## Data Pipeline Defaults
+
+`BFSolver` is the main user entry point. By default it uses
+`pipeline="balanced"` with automatic policy resolution:
+
+```python
+from fast_acbf import BFSolver, Dataset4D
+
+dataset = Dataset4D.from_hdf5("scan.h5", key="array")  # lazy by default
+
+solver = BFSolver(
+    dataset=dataset,
+    max_alpha=25.0,
+    scan_step_size=0.43,
+    dk=0.04,
+    wavelength=0.04176,
+    device="cuda",
+)
+```
+
+The solver consumes `ImageFFT` chunks internally. The policy controls where that
+FFT cache lives, when it is filled, and how virtual BF images are extracted from
+the raw 4D data.
+
+| Pipeline | Intended use | Default behavior |
+| --- | --- | --- |
+| `speed` | Small data that can afford temporary materialization | Prefer device ImageFFT and, when raw 4D can be materialized and fit in VRAM with vBF/ImageFFT, do a whole-pass `device_mask` precompute. |
+| `balanced` | General default | Cache ImageFFT on device if it fits, otherwise host RAM, otherwise stream. Avoids raw-on-device extraction for lazy disk data unless explicitly requested. |
+| `memory` | Largest data / lowest persistent memory | Keep `imagefft_storage="none"` and compute on the fly, using disk extraction for lazy data. |
+
+Advanced users can override the resolved policy:
+
+```python
+solver = BFSolver(
+    dataset=dataset,
+    ...,
+    pipeline="balanced",
+    imagefft_storage="host",     # auto | device | host | none
+    imagefft_fill="precompute",  # auto | precompute | lazy | on_the_fly
+    extractor_strategy="auto",   # auto | device_mask | host_mask | disk_*
+)
+```
+
+Impossible or wasteful combinations are rejected early with memory/path guidance.
+For example, `extractor_strategy="device_mask"` requires persistent ImageFFT
+storage and `imagefft_fill="precompute"` because it is a whole-pass route:
+temporarily move raw 4D to the compute device, extract all vBF images, precompute
+ImageFFT, then release raw/vBF intermediates.
+
+## References
+
+[1] Ma, Desheng, et al. "Information in 4D-STEM: Where it is, and How to Use it." Ultramicroscopy (2026). https://doi.org/10.1016/j.ultramic.2026.114351
+
+[2] Ma, Desheng, David A. Muller, and Steven E. Zeltmann. "Using Aberrations to Improve Dose-Efficient Tilt-corrected 4D-STEM Imaging." Microscopy and Microanalysis (2026). https://doi.org/10.1093/mam/ozag008
+
+[3] Yu, Yue, et al. "Dose-efficient cryo-electron microscopy for thick samples using tilt-corrected scanning transmission electron microscopy." Nature Methods (2025). https://doi.org/10.1038/s41592-025-02834-9
+
+## Relevant Repositories
+
+- [tcBF-STEM](https://github.com/yyu2017/tcBFSTEM)
+- [acBF-STEM](https://github.com/dsmagiya/acBF-STEM)
+- [PtyRAD](https://github.com/chiahao3/ptyrad)
+- [py4DSTEM](https://github.com/py4dstem/py4DSTEM)
+- [quantem](https://github.com/electronmicroscopy/quantem)
+
+## Author 
+
+Chia-Hao Lee (cl2696@cornell.edu)
+
+Developed at the Muller Group, Cornell University.
+
+

fast_acbf-0.7.0/README.md

@@ -0,0 +1,118 @@
+# GPU-accelerated tcBF and acBF
+
+This repository provides a fast GPU implementation of aberration-corrected bright-field 4D-STEM (tcBF/acBF) reconstruction.
+
+It is designed to serve as the seed for:
+
+1. Future native integration of tcBF and acBF into [PtyRAD](https://github.com/chiahao3/ptyrad) pipeline
+2. Real-time visualization during 4D-STEM data acquisition
+
+The underlying imaging theory and initial CPU implementation of **acBF** were developed by Dr. Desheng Ma and Dr. Steven Zeltmann [1, 2], while the **tcBF** method has a longer history; readers are encouraged to read this paper by Dr. Yue Yu [3].
+
+This implementation (**fast-acBF**) was developed independently focusing on GPU acceleration and integration with the PtyRAD reconstruction framework. It is shared as a working research implementation; interfaces may change as development continues.
+
+## Installation guide
+
+**Major Dependencies:**
+- python >=3.10
+- pytorch >=2.4
+- ptyrad
+
+### 1. Get the fast-acBF code from GitHub
+You can either download the repository as a .zip file and extract it, or use the following command if you have `git` installed.
+
+```bash
+git clone https://github.com/chiahao3/fast-acbf
+```
+
+### 2. Create and Activate the Python Environment
+Assuming you're using conda, you can create an independent environment and install the packages with these commands:
+
+```bash
+# Enter the commands one by one
+conda create -n fast-acbf python=3.12 -y
+conda activate fast-acbf
+cd fast-acbf
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126
+pip install -e .
+```
+
+If you prefer a legacy version of PyTorch, or a different version of CUDA runtime other than CUDA 12.6, see instruction [here](https://pytorch.org/get-started/previous-versions/).
+
+## Get Started
+
+1. Download the demo tBL-WSe2 data "Figure 4.zip" from the [Zenodo link](https://doi.org/10.5281/zenodo.15283331)
+2. Run the `get_acBF.ipynb` Jupyter notebook to reconstruct tcBF / acBF images
+
+## Data Pipeline Defaults
+
+`BFSolver` is the main user entry point. By default it uses
+`pipeline="balanced"` with automatic policy resolution:
+
+```python
+from fast_acbf import BFSolver, Dataset4D
+
+dataset = Dataset4D.from_hdf5("scan.h5", key="array")  # lazy by default
+
+solver = BFSolver(
+    dataset=dataset,
+    max_alpha=25.0,
+    scan_step_size=0.43,
+    dk=0.04,
+    wavelength=0.04176,
+    device="cuda",
+)
+```
+
+The solver consumes `ImageFFT` chunks internally. The policy controls where that
+FFT cache lives, when it is filled, and how virtual BF images are extracted from
+the raw 4D data.
+
+| Pipeline | Intended use | Default behavior |
+| --- | --- | --- |
+| `speed` | Small data that can afford temporary materialization | Prefer device ImageFFT and, when raw 4D can be materialized and fit in VRAM with vBF/ImageFFT, do a whole-pass `device_mask` precompute. |
+| `balanced` | General default | Cache ImageFFT on device if it fits, otherwise host RAM, otherwise stream. Avoids raw-on-device extraction for lazy disk data unless explicitly requested. |
+| `memory` | Largest data / lowest persistent memory | Keep `imagefft_storage="none"` and compute on the fly, using disk extraction for lazy data. |
+
+Advanced users can override the resolved policy:
+
+```python
+solver = BFSolver(
+    dataset=dataset,
+    ...,
+    pipeline="balanced",
+    imagefft_storage="host",     # auto | device | host | none
+    imagefft_fill="precompute",  # auto | precompute | lazy | on_the_fly
+    extractor_strategy="auto",   # auto | device_mask | host_mask | disk_*
+)
+```
+
+Impossible or wasteful combinations are rejected early with memory/path guidance.
+For example, `extractor_strategy="device_mask"` requires persistent ImageFFT
+storage and `imagefft_fill="precompute"` because it is a whole-pass route:
+temporarily move raw 4D to the compute device, extract all vBF images, precompute
+ImageFFT, then release raw/vBF intermediates.
+
+## References
+
+[1] Ma, Desheng, et al. "Information in 4D-STEM: Where it is, and How to Use it." Ultramicroscopy (2026). https://doi.org/10.1016/j.ultramic.2026.114351
+
+[2] Ma, Desheng, David A. Muller, and Steven E. Zeltmann. "Using Aberrations to Improve Dose-Efficient Tilt-corrected 4D-STEM Imaging." Microscopy and Microanalysis (2026). https://doi.org/10.1093/mam/ozag008
+
+[3] Yu, Yue, et al. "Dose-efficient cryo-electron microscopy for thick samples using tilt-corrected scanning transmission electron microscopy." Nature Methods (2025). https://doi.org/10.1038/s41592-025-02834-9
+
+## Relevant Repositories
+
+- [tcBF-STEM](https://github.com/yyu2017/tcBFSTEM)
+- [acBF-STEM](https://github.com/dsmagiya/acBF-STEM)
+- [PtyRAD](https://github.com/chiahao3/ptyrad)
+- [py4DSTEM](https://github.com/py4dstem/py4DSTEM)
+- [quantem](https://github.com/electronmicroscopy/quantem)
+
+## Author 
+
+Chia-Hao Lee (cl2696@cornell.edu)
+
+Developed at the Muller Group, Cornell University.
+
+

fast_acbf-0.7.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fast-acbf"
+dynamic = ["version"]
+authors = [
+  { name="Chia-Hao Lee", email="cl2696@cornell.edu" },
+]
+description = "GPU-based Bright-field Ptychography Solver for tcBF and acBF built on PtyRAD"
+keywords = ["Ptychography"]
+readme = "README.md"
+license = "LGPL-3.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "h5py",
+    "matplotlib",
+    "numpy",
+    "psutil",
+    "scipy",
+    "torch>=2.4",
+    "torchvision",
+    "ptyrad"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "fast_acbf.__version__"}
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "zarr>=3.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+markers = [
+    "regression: tests requiring real data fixtures (skip with -m 'not regression')",
+]
+filterwarnings = ["ignore::UserWarning"]
+
+[project.urls]
+Repository = "https://github.com/chiahao3/fast-acbf"
+Changelog = "https://github.com/chiahao3/fast-acbf/blob/main/CHANGELOG.md"
+"PtyRAD" = "https://github.com/chiahao3/ptyrad"

fast_acbf-0.7.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fast_acbf-0.7.0/src/fast_acbf/__init__.py

@@ -0,0 +1,24 @@
+from .solver import BFSolver
+from .core.aberrations import AberrationState
+from .optimization.metrics import QualityMetrics
+from .data.dataset4d import Dataset4D
+from .data.bf_extractor import BFExtractor
+from .data.geometry import DetectorGeometry, ScanGeometry, CoordinateTransform
+from .data.imagefft import ImageFFT
+from .recon.pipeline import PipelineManager, PipelineResolution
+
+__version__ = "0.7.0" # 2026.07.30
+
+__all__ = [
+    "BFSolver",
+    "AberrationState",
+    "QualityMetrics",
+    "Dataset4D",
+    "BFExtractor",
+    "DetectorGeometry",
+    "ScanGeometry",
+    "CoordinateTransform",
+    "ImageFFT",
+    "PipelineManager",
+    "PipelineResolution",
+]