xptycho 0.1.0__tar.gz

xptycho-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Charles A Bouman
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

xptycho-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: xptycho
+Version: 0.1.0
+Summary: Ptychographic reconstruction with PMACE in PyTorch
+Author: Charles A. Bouman, Brendt Wohlberg, Gregery T. Buzzard
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/cabouman/xptycho
+Project-URL: Documentation, https://xptycho.readthedocs.io
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: torch>=2.2
+Requires-Dist: h5py
+Requires-Dist: tifffile
+Requires-Dist: matplotlib
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx_book_theme; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinxext-opengraph; extra == "docs"
+Requires-Dist: sphinx-design; extra == "docs"
+Dynamic: license-file
+
+# xptycho
+
+xptycho: ptychographic reconstruction with projected multi-agent consensus
+equilibrium (PMACE) using [PyTorch](https://pytorch.org/).
+
+Features include:
+* Reconstruction of the complex object image, magnitude and phase, from far-field diffraction frames.
+* Estimation of the probe together with the object, with one or more probe modes.
+* Refinement of the probe positions.
+* Preprocessing of raw detector frames: dark subtraction, outlier removal, centering, and cropping.
+* One HDF5 file format for scans, samples, and reconstructions.
+* Demos on simulated data and on measured data, from raw file to image.
+* Seamless operation on 1 or more GPUs, Mac MPS, or CPU.
+
+Full documentation at [https://xptycho.readthedocs.io/](https://xptycho.readthedocs.io/)
+
+Design pages at [https://cabouman.github.io/xptycho/](https://cabouman.github.io/xptycho/)
+
+Install:
+```bash
+pip install xptycho
+```
+
+Reconstruct in a few lines:
+```python
+import xptycho as xpt
+scan = xpt.Scan.load('scan.h5')
+model = xpt.PtychoModel.from_scan(scan)
+recon = model.recon(scan)
+xpt.view_sample(recon)
+```
+
+xptycho implements the PMACE method of Qiuchen Zhai, Gregery T. Buzzard,
+Kevin Mertes, Brendt Wohlberg, and Charles A. Bouman.  For the papers to
+cite, the source of the demo data, and the funding support, see
+[Credits](https://xptycho.readthedocs.io/en/latest/credits.html).

xptycho-0.1.0/README.md

@@ -0,0 +1,36 @@
+# xptycho
+
+xptycho: ptychographic reconstruction with projected multi-agent consensus
+equilibrium (PMACE) using [PyTorch](https://pytorch.org/).
+
+Features include:
+* Reconstruction of the complex object image, magnitude and phase, from far-field diffraction frames.
+* Estimation of the probe together with the object, with one or more probe modes.
+* Refinement of the probe positions.
+* Preprocessing of raw detector frames: dark subtraction, outlier removal, centering, and cropping.
+* One HDF5 file format for scans, samples, and reconstructions.
+* Demos on simulated data and on measured data, from raw file to image.
+* Seamless operation on 1 or more GPUs, Mac MPS, or CPU.
+
+Full documentation at [https://xptycho.readthedocs.io/](https://xptycho.readthedocs.io/)
+
+Design pages at [https://cabouman.github.io/xptycho/](https://cabouman.github.io/xptycho/)
+
+Install:
+```bash
+pip install xptycho
+```
+
+Reconstruct in a few lines:
+```python
+import xptycho as xpt
+scan = xpt.Scan.load('scan.h5')
+model = xpt.PtychoModel.from_scan(scan)
+recon = model.recon(scan)
+xpt.view_sample(recon)
+```
+
+xptycho implements the PMACE method of Qiuchen Zhai, Gregery T. Buzzard,
+Kevin Mertes, Brendt Wohlberg, and Charles A. Bouman.  For the papers to
+cite, the source of the demo data, and the funding support, see
+[Credits](https://xptycho.readthedocs.io/en/latest/credits.html).

xptycho-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xptycho"
+description = "Ptychographic reconstruction with PMACE in PyTorch"
+readme = "README.md"
+license = { text = "BSD-3-Clause" }
+requires-python = ">=3.11"
+dynamic = ["version"]
+authors = [
+    { name = "Charles A. Bouman" },
+    { name = "Brendt Wohlberg" },
+    { name = "Gregery T. Buzzard" },
+]
+dependencies = [
+    "numpy",
+    "scipy",
+    "torch>=2.2",
+    "h5py",
+    "tifffile",
+    "matplotlib",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+docs = ["sphinx", "sphinx_book_theme", "sphinx-copybutton", "sphinxext-opengraph", "sphinx-design"]
+
+[project.urls]
+Homepage = "https://github.com/cabouman/xptycho"
+Documentation = "https://xptycho.readthedocs.io"
+
+[tool.setuptools.packages.find]
+include = ["xptycho*"]
+
+[tool.setuptools.dynamic]
+version = { attr = "xptycho.__version__" }

xptycho-0.1.0/setup.cfg

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

xptycho-0.1.0/tests/test_files.py

@@ -0,0 +1,34 @@
+"""A scan and a sample are groups of one HDF5 file and read back unchanged."""
+import numpy as np
+
+import xptycho as xpt
+from tiny import PIXEL_PITCH, make_model, make_object, make_probe
+
+
+def test_one_file_holds_a_scan_and_a_sample(tmp_path):
+    path = str(tmp_path / 'tiny.h5')
+    truth = xpt.Sample(make_object(), make_probe(), PIXEL_PITCH, name='tiny')
+    model = make_model()
+    scan = model.simulate(truth)
+    truth.save(path)
+    scan.save(path)                       # the same file; the sample is kept
+
+    sample, scan_back = xpt.Sample.load(path), xpt.Scan.load(path)
+    assert np.array_equal(sample.object, truth.object) and np.array_equal(sample.probe, truth.probe)
+    assert sample.pixel_pitch == PIXEL_PITCH and sample.name == 'tiny' and sample.run is None
+    assert np.array_equal(scan_back.frames, scan.frames) and scan_back.det_pixel_pitch == scan.det_pixel_pitch
+
+
+def test_a_reconstruction_keeps_the_record_of_its_run(tmp_path):
+    path = str(tmp_path / 'recon.h5')
+    model = make_model()
+    probe = make_probe()
+    scan = model.simulate(xpt.Sample(make_object(), probe, PIXEL_PITCH))
+    recon = model.recon(scan, probe=probe, iterations=3, verbose=0)
+    recon.save(path)
+    back = xpt.Sample.load(path)
+    assert np.array_equal(back.object, recon.object) and back.origin == recon.origin
+    assert back.run.iterations == 3 and back.run.data_error == recon.run.data_error
+    assert np.array_equal(back.run.coverage, recon.run.coverage)
+    assert [row['name'] for row in back.run.parameters] == [row['name'] for row in recon.run.parameters]
+    assert np.array_equal(back.scanned_region(), recon.scanned_region())

xptycho-0.1.0/tests/test_import.py

@@ -0,0 +1,6 @@
+import xptycho
+
+
+def test_version():
+    assert isinstance(xptycho.__version__, str)
+    assert xptycho.__version__

xptycho-0.1.0/tests/test_preprocess.py

@@ -0,0 +1,32 @@
+"""The preprocessing steps on small arrays with known answers."""
+import numpy as np
+
+import xptycho.preprocess as xpp
+
+
+def test_subtract_dark_clips_at_zero():
+    frames = np.array([[[5.0, 1.0]], [[3.0, 9.0]]])
+    dark = np.array([[[2.0, 2.0]], [[4.0, 4.0]]])           # mean dark is 3
+    assert np.array_equal(xpp.subtract_dark(frames, dark), [[[2.0, 0.0]], [[0.0, 6.0]]])
+
+
+def test_find_outlier_frames():
+    frames = np.ones((20, 4, 4))
+    frames[7] *= 3
+    outlier = xpp.find_outlier_frames(frames, threshold=2)
+    assert outlier.tolist() == [j == 7 for j in range(20)]
+
+
+def test_center_and_crop_put_the_pattern_at_the_frame_center():
+    frames = np.zeros((3, 21, 21))
+    frames[:, 12, 8] = 1.0                                   # every pattern at row 12, column 8
+    center = xpp.diffraction_center(frames)
+    assert center == (12.0, 8.0)
+    cropped = xpp.crop_frames(frames, center, 8)
+    assert cropped.shape == (3, 8, 8) and np.all(cropped[:, 4, 4] == 1) and cropped.sum() == 3
+
+
+def test_tukey_window():
+    window = xpp.tukey_window(64, 0.5)
+    assert window.shape == (64, 64) and window[32, 32] == 1 and window[0, 0] == 0
+    assert np.allclose(window, window.T) and window.min() >= 0 and window.max() == 1

xptycho-0.1.0/tests/test_refine_positions.py

@@ -0,0 +1,22 @@
+"""Position refinement finds whole-pixel errors in the positions."""
+import numpy as np
+
+import xptycho as xpt
+from tiny import PIXEL_PITCH, make_model, make_object, make_probe
+
+
+def test_refine_positions_recovers_shifts():
+    truth, probe = make_object(), make_probe()
+    model = make_model()
+    scan = model.simulate(xpt.Sample(truth, probe, PIXEL_PITCH))
+    true_positions = model.probe_positions.copy()
+
+    wrong = true_positions.copy()
+    wrong[10] += (PIXEL_PITCH, 0)          # one pixel down
+    wrong[30] += (0, -PIXEL_PITCH)         # one pixel left
+    model.set_params(probe_positions=wrong)
+    refined, misfit = model.refine_probe_positions(scan, truth, probe, max_shift=1)
+
+    assert np.allclose(refined, true_positions, atol=PIXEL_PITCH / 100)
+    assert misfit[10] > 0.5 and misfit[30] > 0.5
+    assert misfit[0] == 0

xptycho-0.1.0/tests/test_tiny_baseline.py

@@ -0,0 +1,44 @@
+"""The new code against the old ptycho_pmace code on the tiny problem,
+with a known probe, on one device and divided among several."""
+import json
+import os
+
+import numpy as np
+import pytest
+
+import xptycho as xpt
+from tiny import PIXEL_PITCH, make_model, make_object, make_probe
+
+BASELINE = json.load(open(os.path.join(os.path.dirname(__file__), 'data', 'tiny_baseline.json')))
+TOLERANCE = 1e-4     # relative; single precision agrees to about 1e-6
+
+
+def numbers(recon, truth):
+    est = xpt.match_scale(recon.object, truth)
+    return dict(frobenius=np.linalg.norm(est), sum_real=est.real.sum(), sum_imag=est.imag.sum(),
+                max_abs=np.abs(est).max(), nrmse_obj=xpt.nrmse(recon.object, truth),
+                nrmse_meas=recon.run.data_error[-1])
+
+
+@pytest.mark.parametrize('devices', [('cpu',), ('cpu', 'cpu'), ('cpu',) * 5])
+@pytest.mark.parametrize('iterations', [1, 5, 20])
+def test_matches_old_code(devices, iterations):
+    truth, probe = make_object(), make_probe()
+    model = make_model(devices, object_data_fit=BASELINE['obj_data_fit_prm'], relaxation=BASELINE['rho'],
+                       probe_weight_exponent=BASELINE['probe_exp'])
+    scan = model.simulate(xpt.Sample(truth, probe, PIXEL_PITCH))
+    recon = model.recon(scan, probe=probe, iterations=iterations, verbose=0)
+    mine, old = numbers(recon, truth), BASELINE['iterates'][str(iterations)]
+    for name in mine:
+        assert mine[name] == pytest.approx(old[name], rel=TOLERANCE), name
+
+
+def test_devices_agree():
+    """Five devices put block boundaries inside scan lines."""
+    truth, probe = make_object(), make_probe()
+    results = []
+    for devices in [('cpu',), ('cpu',) * 5]:
+        model = make_model(devices)
+        scan = model.simulate(xpt.Sample(truth, probe, PIXEL_PITCH))
+        results.append(model.recon(scan, probe=probe, iterations=10, verbose=0).object)
+    assert np.abs(results[0] - results[1]).max() < 1e-4 * np.abs(results[0]).max()

xptycho-0.1.0/tests/test_tiny_blind.py

@@ -0,0 +1,70 @@
+"""The new code against the old ptycho_pmace code on the tiny problem
+with two probe modes, the probe estimated and the second mode added at
+iteration 2, on one device and divided among several."""
+import json
+import os
+
+import numpy as np
+import pytest
+
+import xptycho as xpt
+from tiny import PIXEL_PITCH, make_model, make_object, make_probe, make_second_mode, numbers
+
+BASELINE = json.load(open(os.path.join(os.path.dirname(__file__), 'data', 'tiny_blind_baseline.json')))
+TOLERANCE = 1e-3     # relative; the first iterations agree to about 1e-5
+
+
+def setup(devices):
+    truth = make_object()
+    modes = np.stack([make_probe(), make_second_mode(scale=BASELINE['second_mode_scale'])])
+    model = make_model(devices, object_data_fit=BASELINE['obj_data_fit_prm'],
+                       probe_data_fit=BASELINE['probe_data_fit_prm'], relaxation=BASELINE['rho'],
+                       probe_weight_exponent=BASELINE['probe_exp'], mode_schedule=BASELINE['add_mode'],
+                       mode_energy_fraction=BASELINE['energy_ratio'])
+    model.set_params(probe_fresnel_radius_pixels=np.sqrt(model.wavelength * BASELINE['propagation_dist'])
+                     / model.sample_pixel_pitch)
+    model.num_probe_modes = 2
+    return model, model.simulate(xpt.Sample(truth, modes, PIXEL_PITCH)), truth
+
+
+def close(mine, old):
+    for name in old:
+        assert mine[name] == pytest.approx(old[name], rel=TOLERANCE, abs=1e-4), name
+
+
+def test_start_matches_old_code():
+    model, scan, _ = setup(('cpu',))
+    probe = model.initial_probe(scan)
+    close(numbers(probe[0]), BASELINE['init_probe'])
+    close(numbers(model.initial_object(scan, probe)), BASELINE['init_obj'])
+
+
+@pytest.mark.parametrize('devices', [('cpu',), ('cpu',) * 3])
+@pytest.mark.parametrize('iterations', [1, 3, 6])
+def test_matches_old_code(devices, iterations):
+    model, scan, truth = setup(devices)
+    recon = model.recon(scan, iterations=iterations, verbose=0)
+    old = BASELINE['iterates'][str(iterations)]
+    close(numbers(xpt.match_scale(recon.object, truth)), old['object'])
+    assert len(recon.probe) == len(old['probe'])
+    for mine, theirs in zip(recon.probe, old['probe']):
+        close(numbers(mine), theirs)
+    assert recon.run.data_error[-1] == pytest.approx(old['nrmse_meas'], rel=TOLERANCE)
+
+
+def test_orthogonalize_modes_keeps_the_fit():
+    """Making the modes orthogonal changes the modes, not the intensities
+    they predict."""
+    model, scan, _ = setup(('cpu',))
+    plain = model.recon(scan, iterations=BASELINE['add_mode'][0] - 1, verbose=0)      # stop before the addition
+
+    def after_addition(orthogonalize):
+        model.set_params(orthogonalize_modes=orthogonalize)
+        return model.recon(scan, init=plain, iterations=1, verbose=0)
+
+    model.set_params(mode_schedule=[1])            # add the mode in the first iteration of the continued run
+    off, on = after_addition(False), after_addition(True)
+    inner = abs(np.vdot(on.probe[0], on.probe[1])) / (np.linalg.norm(on.probe[0]) * np.linalg.norm(on.probe[1]))
+    inner_off = abs(np.vdot(off.probe[0], off.probe[1])) / (np.linalg.norm(off.probe[0]) * np.linalg.norm(off.probe[1]))
+    assert len(on.probe) == 2 and inner < inner_off
+    assert np.linalg.norm(on.probe[0]) >= np.linalg.norm(on.probe[1])

xptycho-0.1.0/xptycho/__init__.py

@@ -0,0 +1,24 @@
+"""xptycho: ptychographic reconstruction with PMACE in PyTorch.
+
+xptycho reconstructs the complex transmittance image of a thin object
+from a ptychographic scan: far-field diffraction patterns recorded
+while a focused X-ray probe steps across the object in overlapping
+positions.  A :class:`Scan` holds the measurement, a :class:`PtychoModel`
+holds the parameters and the forward model, and
+:meth:`PtychoModel.recon` returns a :class:`Sample`: the object and the
+probe.
+"""
+
+__version__ = '0.1.0'
+
+from .scan import Scan, energy_to_wavelength
+from .model import PtychoModel
+from .sample import Sample, RunRecord
+from .metrics import nrmse, match_scale
+from .view import view_scan, view_sample, save_figures
+from .datasets import download, scan_positions
+from . import operators
+from . import preprocess
+
+__all__ = ['Scan', 'PtychoModel', 'Sample', 'RunRecord', 'download', 'scan_positions', 'view_scan', 'view_sample', 'save_figures', 'nrmse',
+           'match_scale', 'energy_to_wavelength', 'operators', 'preprocess']

xptycho-0.1.0/xptycho/_sharding.py

@@ -0,0 +1,124 @@
+"""How a reconstruction is divided among devices, and the two operations
+that move data between them.  See the Computing page of the design.
+
+Three terms:
+
+block
+    The positions are sorted by the first row of their patch and cut into
+    one block per device, of nearly equal count.
+band
+    The rows of the object image are cut into one band per device, of
+    nearly equal height.  A device owns its band.
+window
+    The range of image rows that the patches of a device's block touch.
+"""
+import numpy as np
+import torch
+
+
+class Layout:
+    """The blocks, bands, and windows of one run.
+
+    Args:
+        devices (list of torch.device): one entry per shard.  The same
+            device may appear more than once, which is how the tests run
+            several shards on one CPU.
+        starts (ndarray): int ``(J, 2)``, the row and column of the first
+            pixel of each patch on the object grid.
+        frame_size (int): the patches are ``frame_size`` square.
+        object_shape (tuple of int): ``(rows, cols)`` of the object grid.
+
+    Attributes:
+        blocks (list of ndarray): for each device, the indices of its
+            positions in the scan's own order.
+        bands (list of tuple): for each device, the ``(first, stop)`` rows
+            it owns.
+        windows (list of tuple): for each device, the ``(first, stop)``
+            rows its patches touch.
+    """
+
+    def __init__(self, devices, starts, frame_size, object_shape):
+        self.devices = [torch.device(d) for d in devices]
+        n = len(self.devices)
+        rows = int(object_shape[0])
+        if n > len(starts):
+            raise ValueError('{} devices were asked for but the scan has only {} positions'.format(n, len(starts)))
+        if n > rows:
+            raise ValueError('{} devices were asked for but the object has only {} rows'.format(n, rows))
+        order = np.argsort(starts[:, 0], kind='stable')
+        self.blocks = np.array_split(order, n)
+        edges = np.linspace(0, rows, n + 1).round().astype(int)
+        self.bands = [(int(edges[g]), int(edges[g + 1])) for g in range(n)]
+        self.windows = [(int(starts[b, 0].min()), int(starts[b, 0].max()) + frame_size) for b in self.blocks]
+        self.object_shape = (rows, int(object_shape[1]))
+
+    def __len__(self):
+        return len(self.devices)
+
+    def _overlap(self, window, band):
+        first, stop = max(window[0], band[0]), min(window[1], band[1])
+        return (first, stop) if stop > first else None
+
+    def sum_to_owner(self, parts):
+        """Add the devices' partial sums onto the owners of the rows.
+
+        Args:
+            parts (list of Tensor): for each device, its partial sum over
+                its window, shape ``(..., window rows, cols)``.
+
+        Returns:
+            list of Tensor: for each device, the complete sum over its
+            band, shape ``(..., band rows, cols)``.  The pieces are added
+            in device order.
+        """
+        out = []
+        for g, band in enumerate(self.bands):
+            lead = parts[g].shape[:-2]
+            total = torch.zeros(lead + (band[1] - band[0], self.object_shape[1]),
+                                dtype=parts[g].dtype, device=self.devices[g])
+            for h, window in enumerate(self.windows):
+                rows = self._overlap(window, band)
+                if rows is not None:
+                    piece = parts[h][..., rows[0] - window[0]:rows[1] - window[0], :]
+                    total[..., rows[0] - band[0]:rows[1] - band[0], :] += piece.to(self.devices[g])
+            out.append(total)
+        return out
+
+    def copy_to_window(self, bands):
+        """Give each device the rows of its window, from their owners.
+
+        Args:
+            bands (list of Tensor): for each device, an array over its band.
+
+        Returns:
+            list of Tensor: for each device, the same array over its window.
+        """
+        out = []
+        for g, window in enumerate(self.windows):
+            pieces = []
+            for h, band in enumerate(self.bands):
+                rows = self._overlap(window, band)
+                if rows is not None:
+                    pieces.append(bands[h][..., rows[0] - band[0]:rows[1] - band[0], :].to(self.devices[g]))
+            out.append(torch.cat(pieces, dim=-2))
+        return out
+
+    def sum_small(self, parts):
+        """Add small partial sums on the first device, in device order."""
+        total = parts[0].clone()
+        for part in parts[1:]:
+            total += part.to(self.devices[0])
+        return total
+
+    def broadcast(self, x):
+        """A copy of a small array on every device."""
+        return [x.to(d) for d in self.devices]
+
+    def gather(self, bands):
+        """Join the bands into one image on the host, as numpy."""
+        return np.concatenate([b.cpu().numpy() for b in bands], axis=-2)
+
+    def split(self, image):
+        """Cut a host image into bands and place each on its owner."""
+        image = torch.as_tensor(image)
+        return [image[..., first:stop, :].to(d) for (first, stop), d in zip(self.bands, self.devices)]

xptycho-0.1.0/xptycho/datasets.py

@@ -0,0 +1,57 @@
+"""Tools for demos: a file download and simple scan patterns."""
+import os
+import subprocess
+import urllib.error
+import urllib.request
+
+import numpy as np
+
+
+def download(url, directory):
+    """Download a file into a directory, unless it is already there.
+
+    Args:
+        url (str): the address of the file.
+        directory (str): the local directory.  It is created if needed.
+
+    Returns:
+        str: the path of the local file, named as in the address.
+    """
+    path = os.path.join(directory, os.path.basename(url))
+    if os.path.isfile(path):
+        return path
+    os.makedirs(directory, exist_ok=True)
+    print('downloading {} to {}'.format(url, path))
+    partial = path + '.part'
+    try:
+        urllib.request.urlretrieve(url, partial)
+    except urllib.error.URLError:
+        # Some servers refuse Python's downloader or do not send their
+        # intermediate certificate, which Python cannot verify; curl works.
+        result = subprocess.run(['curl', '-L', '--fail', '-sS', '-o', partial, url], capture_output=True, text=True)
+        if result.returncode != 0:
+            raise RuntimeError('could not download {}: {}'.format(url, result.stderr.strip()))
+    os.replace(partial, path)
+    return path
+
+
+def scan_positions(grid, step, max_offset=0.0, seed=0):
+    """The positions of a rectangular scan, with a random offset at each.
+
+    Args:
+        grid (tuple of int): the number of positions along rows and columns.
+        step (float): meters between neighboring positions.
+        max_offset (float, optional): meters.  Each position is moved by a
+            uniform random amount up to this along each axis.  Defaults to 0.
+        seed (int, optional): the random seed of the offsets.
+
+    Returns:
+        ndarray: ``(grid[0] * grid[1], 2)``, row then column, in meters,
+        centered on zero.
+    """
+    rows = (np.arange(grid[0]) - (grid[0] - 1) / 2) * step
+    cols = (np.arange(grid[1]) - (grid[1] - 1) / 2) * step
+    probe_positions = np.stack(np.meshgrid(rows, cols, indexing='ij'), axis=-1).reshape(-1, 2)
+    if max_offset:
+        probe_positions = probe_positions + np.random.default_rng(seed).uniform(-max_offset, max_offset, probe_positions.shape)
+    return probe_positions

xptycho-0.1.0/xptycho/metrics.py

@@ -0,0 +1,39 @@
+"""Error metrics."""
+import numpy as np
+
+
+def match_scale(image, truth, region=None):
+    """Return ``image`` times the one complex number that brings it
+    closest to ``truth``.  A ptychographic reconstruction is determined
+    only up to a complex constant, so this is applied before comparing.
+
+    Args:
+        image (ndarray): complex, the reconstruction.
+        truth (ndarray): complex, the same shape.
+        region (ndarray, optional): only pixels where this is positive
+            are used; the result is zero elsewhere.
+    """
+    if region is not None:
+        mask = np.asarray(region) > 0
+        image, truth = image * mask, truth * mask
+    scale = np.sum(np.conj(image) * truth) / np.sum(np.abs(image) ** 2)
+    return (scale * image).astype(np.complex64)
+
+
+def nrmse(image, truth, region=None):
+    """The normalized root mean square error between a reconstruction and
+    its truth, after :func:`match_scale`.
+
+    Args:
+        image (ndarray): complex, the reconstruction.
+        truth (ndarray): complex, the same shape.
+        region (ndarray, optional): only pixels where this is positive
+            count, for example a reconstruction's ``scanned_region()``.
+
+    Returns:
+        float: ``||c * image - truth|| / ||truth||`` over the counted pixels.
+    """
+    scaled = match_scale(image, truth, region)
+    if region is not None:
+        truth = truth * (np.asarray(region) > 0)
+    return float(np.sqrt(np.sum(np.abs(scaled - truth) ** 2) / np.sum(np.abs(truth) ** 2)))