phaserEM 0.1__tar.gz → 0.3.0__tar.gz

phaserem-0.3.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: phaserEM
+Version: 0.3.0
+Summary: Weapon of choice for electron ptychographic reconstructions
+Author-email: Colin Gilgenbach <hexane@mit.edu>
+License-Expression: MPL-2.0
+Project-URL: Repository, https://github.com/hexane360/phaser.git
+Project-URL: Documentation, https://hexane360.github.io/phaser/dev
+Keywords: science,atoms,materials,chemistry
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy<2.7,>=2.0
+Requires-Dist: scipy<1.19,>=1.7.0
+Requires-Dist: matplotlib~=3.8
+Requires-Dist: h5py~=3.8
+Requires-Dist: pyyaml>=5.3.1
+Requires-Dist: click~=8.1.0
+Requires-Dist: frozendict~=2.4.7
+Requires-Dist: rich<15,>=12.0.0
+Requires-Dist: tifffile>=2023.8.25
+Requires-Dist: optree>=0.13.0
+Requires-Dist: py-pane==0.11.7
+Requires-Dist: typing_extensions~=4.7
+Requires-Dist: platformdirs>=4.8.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: lxml>=5.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.2.4; extra == "dev"
+Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
+Requires-Dist: coveragepy-lcov>=0.1.1; extra == "dev"
+Provides-Extra: cupy11
+Requires-Dist: cupy-cuda11x>=12.0.0; extra == "cupy11"
+Requires-Dist: pynvml>=11.0.0; extra == "cupy11"
+Provides-Extra: cupy12
+Requires-Dist: cupy-cuda12x>=12.0.0; extra == "cupy12"
+Requires-Dist: pynvml>=11.0.0; extra == "cupy12"
+Provides-Extra: cupy13
+Requires-Dist: cupy-cuda13x>=12.0.0; extra == "cupy13"
+Requires-Dist: pynvml>=11.0.0; extra == "cupy13"
+Provides-Extra: jax
+Requires-Dist: jax<0.11,>=0.4.25; extra == "jax"
+Requires-Dist: optax>=0.2.2; extra == "jax"
+Provides-Extra: torch
+Requires-Dist: torch>=2.8.0; extra == "torch"
+Provides-Extra: web
+Requires-Dist: Quart>=0.20.0; extra == "web"
+Requires-Dist: backoff==2.2.1; extra == "web"
+Requires-Dist: requests>=2.31.0; extra == "web"
+Requires-Dist: anywidget>=0.11.0; extra == "web"
+Requires-Dist: jupyter-ws-tunnel==0.1.3; extra == "web"
+Requires-Dist: hypercorn==0.18.0; extra == "web"
+Provides-Extra: docs
+Requires-Dist: mkdocs==1.6.1; extra == "docs"
+Requires-Dist: mkdocs-material==9.6.11; extra == "docs"
+Requires-Dist: mkdocstrings[python]==0.29.1; extra == "docs"
+Requires-Dist: markdown-include==0.8.1; extra == "docs"
+Requires-Dist: mike==2.1.3; extra == "docs"
+Requires-Dist: black>=25.1.0; extra == "docs"
+Dynamic: license-file
+
+phaser: The weapon of choice for ptychographic reconstructions
+---
+[![][ci-badge]][ci-url] [![][commit-badge]][commit-url] [![][docs-dev-badge]][docs-dev-url] [![][binder-badge]][binder-url]
+
+
+`phaser` is a fully-featured package for multislice electron ptychography.
+See our [arXiv paper](https://arxiv.org/abs/2505.14372) for more details.
+
+## Features
+
+- ePIE, LSQ-MLs, and gradient descent algorithms
+- [`numpy`][numpy], [`cupy`][cupy], and [`jax`][jax] backends.
+- Single and multislice ptychography
+- Multiple incoherent probe modes
+- Probe position correction
+- Upsampled (sPIE) and segmented ptychography (work in progress)
+- Adaptive propagator correction (contributed by M Zhu)
+
+## Documentation
+
+Documentation on `phaser` can be found here: https://hexane360.github.io/phaser/dev/
+
+Documentation is still very much a work in progress, so please feel free to open an issue or email me if you have any questions!
+
+## Installation
+
+To install, first clone the repository from github.
+This can be done from GitHub Desktop, or from the git command line:
+
+```sh
+$ git clone https://github.com/hexane360/phaser
+# enter phaser directory
+$ cd phaser
+```
+
+We recommend using a conda environment or Python virtual environment to keep things clean, although this is not mandatory.
+
+`phaser` supports multiple computational backends. The simplest (and slowest) is `numpy`. `cupy` can be used for CUDA-accelerated. `jax` supports CPU and GPU acceleration, and is the only backend which supports the gradient descent engine.
+If you're unsure what engines to use, we recommend installing the `jax` engine.
+
+If you're using [`cupy`][cupy] or [`jax`][jax] with a GPU, start by following the installation instructions for those packages.
+Jax can be installed with or without CUDA support, if you're using CUDA make sure you install the correct version. Currently, Jax does not support CUDA on Windows.
+
+Before moving on to installing `phaser`, make sure those packages you've installed work:
+```sh
+$ python
+>>> import jax
+>>> jax.default_backend()
+'gpu'  # should be 'gpu' on cuda, 'cpu' otherwise
+>>> jax.numpy.array([1, 2, 3, 4]) + 1   # test a basic operation
+Array([2, 3, 4, 5], dtype=int32)
+
+>>> import cupy
+>>> cupy.array([1, 2, 3, 4]) + 1
+array([2, 3, 4, 5])
+```
+
+Then, install `phaser` using `pip`:
+
+```sh
+$ python -m pip install -e .
+```
+
+For the jax or cupy backend, or for the optional webserver, install with the corresponding options:
+
+```sh
+$ python -m pip install -e ".[jax,cupy12,web]" # for the 'jax', 'cupy12', and 'web' options
+```
+
+Depending on your command line, you may need to put double quotes around the options (as shown).
+
+Here are the supported installation options:
+
+- `jax`: For the [`jax`][jax] backend (required for the gradient descent engine)
+- `cupy11`: `cupy` for CUDA toolkit 11.x
+- `cupy12`: `cupy` for CUDA toolkit 12.x
+- `web`: For the web interface
+
+For [Optuna](https://optuna.org/) hyperoptimization, install it as well:
+
+```sh
+$ pip install optuna
+```
+
+## Running
+
+After installation, the `phaser` command should be available. Phaser can be run from the command line, or through a job server.
+
+To run a single reconstruction on the command line, call `phaser run <file>`, where `file` is the path to a reconstruction plan file.
+
+To run the webserver, call `phaser serve`. By default, the server serves on https://localhost:5050/, so navigate there in a web browser. The server interface can be used to start workers and schedule reconstruction jobs.
+
+To run a worker, call `phaser worker <url>`, where `url` is the URL of a running job server.
+
+## Sample data & Examples
+
+Sample data can be downloaded from the following dropbox link: https://www.dropbox.com/scl/fo/txm3k88ubrzvt541v23ir/AL-l_m6VnGlFxzHWZSSc0TA?rlkey=8qxtwnc8cwhpff6jpr5s40y6i&st=x9pbwke0&dl=0
+
+Copy the `sample_data` directory into the root code folder.
+
+```sh
+$ curl --output sample_data.zip -L 'https://www.dropbox.com/scl/fo/txm3k88ubrzvt541v23ir/AL-l_m6VnGlFxzHWZSSc0TA?rlkey=8qxtwnc8cwhpff6jpr5s40y6i&st=x9pbwke0&dl=1'
+$ unzip sample_data.zip -x / -d sample_data
+```
+
+Sample data includes simulated and experimental MoS2 data, simulated and experimental Si data, and experimental PrScO3 data.
+After the data is downloaded, any of the example reconstructions can be run as `phaser run examples/mos2_grad.yaml` (for example).
+
+## Alternatives
+
+Other notable ptychography packages:
+
+ - [`fold_slice`](https://github.com/yijiang1/fold_slice) branch of [PtychoShelves](https://www.psi.ch/en/sls/csaxs/software#coming-soon-ptychoshelves-a-versatile-high-level-framework-for-high-performance-analysis-of)
+ - [`py4DSTEM`](https://github.com/py4dstem/py4DSTEM)
+ - [`PtyLab.m/py/jl`](https://opg.optica.org/oe/fulltext.cfm?uri=oe-31-9-13763&id=529026)
+ - [PtyPy](https://ptycho.github.io/ptypy/)
+ - [PtyRAD](https://github.com/chiahao3/ptyrad)
+
+[numpy]: https://numpy.org/
+[cupy]: https://cupy.dev/
+[jax]: https://docs.jax.dev/en/latest/
+
+[ci-badge]: https://github.com/hexane360/phaser/workflows/Tests/badge.svg
+[ci-url]: https://github.com/hexane360/phaser/actions/workflows/ci.yaml
+[docs-dev-badge]: https://img.shields.io/badge/docs-dev-blue
+[docs-dev-url]: https://hexane360.github.io/phaser/dev/
+[commit-badge]: https://img.shields.io/github/last-commit/hexane360/phaser
+[commit-url]: https://github.com/hexane360/phaser/commits
+[binder-badge]: https://mybinder.org/badge_logo.svg
+[binder-url]: https://mybinder.org/v2/gh/hexane360/phaser/HEAD

phaserem-0.3.0/README.md

@@ -0,0 +1,130 @@
+phaser: The weapon of choice for ptychographic reconstructions
+---
+[![][ci-badge]][ci-url] [![][commit-badge]][commit-url] [![][docs-dev-badge]][docs-dev-url] [![][binder-badge]][binder-url]
+
+
+`phaser` is a fully-featured package for multislice electron ptychography.
+See our [arXiv paper](https://arxiv.org/abs/2505.14372) for more details.
+
+## Features
+
+- ePIE, LSQ-MLs, and gradient descent algorithms
+- [`numpy`][numpy], [`cupy`][cupy], and [`jax`][jax] backends.
+- Single and multislice ptychography
+- Multiple incoherent probe modes
+- Probe position correction
+- Upsampled (sPIE) and segmented ptychography (work in progress)
+- Adaptive propagator correction (contributed by M Zhu)
+
+## Documentation
+
+Documentation on `phaser` can be found here: https://hexane360.github.io/phaser/dev/
+
+Documentation is still very much a work in progress, so please feel free to open an issue or email me if you have any questions!
+
+## Installation
+
+To install, first clone the repository from github.
+This can be done from GitHub Desktop, or from the git command line:
+
+```sh
+$ git clone https://github.com/hexane360/phaser
+# enter phaser directory
+$ cd phaser
+```
+
+We recommend using a conda environment or Python virtual environment to keep things clean, although this is not mandatory.
+
+`phaser` supports multiple computational backends. The simplest (and slowest) is `numpy`. `cupy` can be used for CUDA-accelerated. `jax` supports CPU and GPU acceleration, and is the only backend which supports the gradient descent engine.
+If you're unsure what engines to use, we recommend installing the `jax` engine.
+
+If you're using [`cupy`][cupy] or [`jax`][jax] with a GPU, start by following the installation instructions for those packages.
+Jax can be installed with or without CUDA support, if you're using CUDA make sure you install the correct version. Currently, Jax does not support CUDA on Windows.
+
+Before moving on to installing `phaser`, make sure those packages you've installed work:
+```sh
+$ python
+>>> import jax
+>>> jax.default_backend()
+'gpu'  # should be 'gpu' on cuda, 'cpu' otherwise
+>>> jax.numpy.array([1, 2, 3, 4]) + 1   # test a basic operation
+Array([2, 3, 4, 5], dtype=int32)
+
+>>> import cupy
+>>> cupy.array([1, 2, 3, 4]) + 1
+array([2, 3, 4, 5])
+```
+
+Then, install `phaser` using `pip`:
+
+```sh
+$ python -m pip install -e .
+```
+
+For the jax or cupy backend, or for the optional webserver, install with the corresponding options:
+
+```sh
+$ python -m pip install -e ".[jax,cupy12,web]" # for the 'jax', 'cupy12', and 'web' options
+```
+
+Depending on your command line, you may need to put double quotes around the options (as shown).
+
+Here are the supported installation options:
+
+- `jax`: For the [`jax`][jax] backend (required for the gradient descent engine)
+- `cupy11`: `cupy` for CUDA toolkit 11.x
+- `cupy12`: `cupy` for CUDA toolkit 12.x
+- `web`: For the web interface
+
+For [Optuna](https://optuna.org/) hyperoptimization, install it as well:
+
+```sh
+$ pip install optuna
+```
+
+## Running
+
+After installation, the `phaser` command should be available. Phaser can be run from the command line, or through a job server.
+
+To run a single reconstruction on the command line, call `phaser run <file>`, where `file` is the path to a reconstruction plan file.
+
+To run the webserver, call `phaser serve`. By default, the server serves on https://localhost:5050/, so navigate there in a web browser. The server interface can be used to start workers and schedule reconstruction jobs.
+
+To run a worker, call `phaser worker <url>`, where `url` is the URL of a running job server.
+
+## Sample data & Examples
+
+Sample data can be downloaded from the following dropbox link: https://www.dropbox.com/scl/fo/txm3k88ubrzvt541v23ir/AL-l_m6VnGlFxzHWZSSc0TA?rlkey=8qxtwnc8cwhpff6jpr5s40y6i&st=x9pbwke0&dl=0
+
+Copy the `sample_data` directory into the root code folder.
+
+```sh
+$ curl --output sample_data.zip -L 'https://www.dropbox.com/scl/fo/txm3k88ubrzvt541v23ir/AL-l_m6VnGlFxzHWZSSc0TA?rlkey=8qxtwnc8cwhpff6jpr5s40y6i&st=x9pbwke0&dl=1'
+$ unzip sample_data.zip -x / -d sample_data
+```
+
+Sample data includes simulated and experimental MoS2 data, simulated and experimental Si data, and experimental PrScO3 data.
+After the data is downloaded, any of the example reconstructions can be run as `phaser run examples/mos2_grad.yaml` (for example).
+
+## Alternatives
+
+Other notable ptychography packages:
+
+ - [`fold_slice`](https://github.com/yijiang1/fold_slice) branch of [PtychoShelves](https://www.psi.ch/en/sls/csaxs/software#coming-soon-ptychoshelves-a-versatile-high-level-framework-for-high-performance-analysis-of)
+ - [`py4DSTEM`](https://github.com/py4dstem/py4DSTEM)
+ - [`PtyLab.m/py/jl`](https://opg.optica.org/oe/fulltext.cfm?uri=oe-31-9-13763&id=529026)
+ - [PtyPy](https://ptycho.github.io/ptypy/)
+ - [PtyRAD](https://github.com/chiahao3/ptyrad)
+
+[numpy]: https://numpy.org/
+[cupy]: https://cupy.dev/
+[jax]: https://docs.jax.dev/en/latest/
+
+[ci-badge]: https://github.com/hexane360/phaser/workflows/Tests/badge.svg
+[ci-url]: https://github.com/hexane360/phaser/actions/workflows/ci.yaml
+[docs-dev-badge]: https://img.shields.io/badge/docs-dev-blue
+[docs-dev-url]: https://hexane360.github.io/phaser/dev/
+[commit-badge]: https://img.shields.io/github/last-commit/hexane360/phaser
+[commit-url]: https://github.com/hexane360/phaser/commits
+[binder-badge]: https://mybinder.org/badge_logo.svg
+[binder-url]: https://mybinder.org/v2/gh/hexane360/phaser/HEAD

phaserem-0.3.0/phaser/__init__.py

@@ -0,0 +1 @@
+__version__ = '0.3.0'

{phaserem-0.1 → phaserem-0.3.0}/phaser/__main__.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
 
 if __name__ == '__main__':
-    from phaser.main import cli
+    from phaser.cli import cli
     cli()

phaserem-0.3.0/phaser/cli/__init__.py

@@ -0,0 +1,161 @@
+import abc
+import importlib
+from pathlib import Path
+import sys
+import typing as t
+
+import click
+
+class Dependency(abc.ABC):
+    @abc.abstractmethod
+    def check(self):
+        ...
+
+    @abc.abstractmethod
+    def install_instructions(self) -> str:
+        ...
+
+
+class ImportDependency(Dependency):
+    def __init__(self, ref: str, install: str) -> None:
+        self.ref = ref
+        self.install = install
+
+    def check(self):
+        importlib.import_module(self.ref)
+
+    def install_instructions(self) -> str:
+        return self.install
+
+
+def check_dependencies(command: str, dependencies: t.Sequence[str]):
+    for dependency in dependencies:
+        if (dep := _DEPENDENCIES.get(dependency)) is None:
+            raise RuntimeError(f"Unknown dependency '{dependency}'. This is likely a bug in the hook declaration.")
+
+        try:
+            dep.check()
+        except Exception as e:
+            raise RuntimeError(
+                f"Missing dependency '{dependency}' required for subcommand '{command}'.\n"
+                f"To install: {dep.install_instructions()}"
+            ) from e
+
+
+class MainCommand(click.MultiCommand):
+    def __init__(self, commands: t.Iterable[
+        t.Union[click.Command, t.Tuple[str, str], t.Tuple[str, str, t.Sequence[str]]]
+    ], **kwargs):
+        super().__init__(**kwargs)
+        # name: command or short_help
+        self.commands: t.Dict[str, t.Union[click.Command, str, None]] = {}
+        self.dependencies: t.Dict[str, t.Sequence[str]] = {}
+        for c in commands:
+            if isinstance(c, click.Command):
+                name = str(c.name)
+                self.commands[name] = c
+                self.dependencies[name] = ()
+                continue
+            self.commands[c[0]] = c[1]
+            if len(c) > 2:
+                self.dependencies[c[0]] = c[2]
+
+    def list_commands(self, ctx: click.Context):
+        return list(self.commands.keys())
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        from gettext import gettext
+
+        if len(self.commands):
+            limit = formatter.width - 6 - max(map(len, self.commands.keys()))
+
+            rows = []
+            for name, cmd in self.commands.items():
+                help = cmd.get_short_help_str(limit) if isinstance(cmd, click.Command) else cmd
+                rows.append((name, help))
+
+            if rows:
+                with formatter.section(gettext("Commands")):
+                    formatter.write_dl(rows)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> t.Optional[click.Command]:
+        name = cmd_name.lower()
+        val = (self.commands.get(name) or 
+               self.commands.get(name.replace('-', '_')))
+        if val is None:
+            return None
+        if isinstance(val, click.BaseCommand):
+            return val
+
+        check_dependencies(name, self.dependencies.get(name, ()))
+
+        # for now, assume `validate` command is `cli.validate:validate`
+        module = func = name
+        mod = __import__(module, globals(), fromlist=[func], level=1)
+        return getattr(mod, func)
+
+
+@click.command()
+@click.argument('path', type=click.Path(exists=True, dir_okay=False))
+def run(path: t.Union[str, Path]):
+    """Execute a reconstruction plan"""
+    from phaser.plan import ReconsPlan
+    from phaser.execute import execute_plan
+    plans = ReconsPlan.from_yaml_all(path)
+
+    for plan in plans:
+        execute_plan(plan)
+
+
+@click.command()
+@click.option('--host', type=str, default='localhost', help="Host to serve on")
+@click.option('--port', type=int, help="Port to serve on")
+@click.option('-v', '--verbose', count=True, help="Increase verbosity")
+@click.option('--debug', is_flag=True, help="Enable debug routes (/debug/*), for testing the web interface")
+def serve(host: str = 'localhost', port: t.Optional[int] = None, verbose: int = 0, debug: bool = False):
+    """Run phaser server"""
+    from phaser.web.server import server
+
+    if ':' in host:
+        (host, port_from_host) = host.rsplit(':', maxsplit=1)
+        try:
+            port_from_host = int(port_from_host)
+        except ValueError:
+            print(f"Invalid host '{host}:{port_from_host}'", file=sys.stderr)
+            sys.exit(1)
+
+        port = port or port_from_host
+
+    server.run(hostname=host, port=port, verbosity=verbose, debug=debug)
+
+
+@click.command()
+@click.argument('url', type=str, required=True)
+@click.option('--quiet/--loud', default=False, help="Whether to print output to stdout")
+def worker(url: str, quiet: bool = False):
+    """
+    Run phaser worker.
+
+    URL is the server URL to connect to.
+    """
+    from phaser.web.worker import run_worker
+
+    run_worker(url, quiet=quiet)
+
+
+_DEPENDENCIES = {
+    'rsciio': ImportDependency('rsciio', "'pip install rosettasciio' or 'conda install rosettasciio'"),
+}
+
+commands: t.List[t.Union[click.Command, t.Union[t.Tuple[str, str, t.Sequence[str]], t.Tuple[str, str]]]] = [
+    run, serve, worker,
+    # these will be looked up in the cli folder
+    ('validate', "Validate reconstruction plan file"),
+    ('process_empad', "Process EMPAD XML metadata"),
+    ('calc_drift', "Calculate and correct linear drift"),
+]
+
+
+@click.command(cls=MainCommand, commands=commands)
+def cli():
+    pass