From 88243804994c04dab7983d1f36cfa6079a39f844 Mon Sep 17 00:00:00 2001 From: James Le Houx <37665786+jameslehoux@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:36:24 +0000 Subject: [PATCH 1/3] =?UTF-8?q?feat:=20BraggTrack=20v0.4.0=20=E2=80=94=20a?= =?UTF-8?q?utonomous=20DFXM=20Scout-and-Zoom,=20operando=20sync,=20uncerta?= =?UTF-8?q?inty=20&=20batched=20DINOv2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/release.yml | 90 +++++ CHANGELOG.md | 19 + CITATION.cff | 16 +- README.md | 30 +- braggtrack/__init__.py | 4 +- braggtrack/autonomous/__init__.py | 17 + braggtrack/autonomous/replay.py | 328 ++++++++++++++++ braggtrack/autonomous/streaming.py | 327 ++++++++++++++++ braggtrack/autonomous/trigger.py | 396 +++++++++++++++++++ braggtrack/cli/_utils.py | 2 +- braggtrack/cli/embed_dataset.py | 21 +- braggtrack/cli/report_dataset.py | 33 ++ braggtrack/cli/run_pipeline.py | 40 +- braggtrack/cli/watch_autonomous.py | 220 +++++++++++ braggtrack/io/__init__.py | 12 + braggtrack/io/nexus.py | 93 ++++- braggtrack/io/operando_log.py | 453 ++++++++++++++++++++++ braggtrack/segmentation/dino_segment.py | 10 +- braggtrack/segmentation/features.py | 19 + braggtrack/semantic/dino.py | 141 +++++-- braggtrack/tracking/__init__.py | 3 +- braggtrack/tracking/assignment.py | 31 ++ braggtrack/tracking/kinematics.py | 215 ++++++++-- braggtrack/tracking/lifecycle.py | 38 +- braggtrack/tracking/precursors.py | 201 +++++++--- braggtrack/viz/__init__.py | 2 + braggtrack/viz/html_report.py | 75 +++- braggtrack/viz/operando.py | 241 ++++++++++++ docs/architecture.md | 30 +- docs/benchmarks.md | 60 ++- docs/figures/operando_autonomous_zoom.png | Bin 0 -> 268687 bytes docs/positioning.md | 118 ++++++ paper.bib | 83 ++++ paper.md | 169 +++++--- pyproject.toml | 3 +- tests/test_autonomous_zoom.py | 264 +++++++++++++ tests/test_ci_report.py | 1 + tests/test_dino_batching.py | 67 ++++ tests/test_kinematics.py | 11 + tests/test_kinematics_uncertainty.py | 153 ++++++++ tests/test_nexus_darfix.py | 88 +++++ tests/test_operando_log.py | 127 ++++++ 42 files changed, 3975 insertions(+), 276 deletions(-) create mode 100644 .github/workflows/release.yml create mode 100644 braggtrack/autonomous/__init__.py create mode 100644 braggtrack/autonomous/replay.py create mode 100644 braggtrack/autonomous/streaming.py create mode 100644 braggtrack/autonomous/trigger.py create mode 100644 braggtrack/cli/watch_autonomous.py create mode 100644 braggtrack/io/operando_log.py create mode 100644 braggtrack/viz/operando.py create mode 100644 docs/figures/operando_autonomous_zoom.png create mode 100644 docs/positioning.md create mode 100644 tests/test_autonomous_zoom.py create mode 100644 tests/test_dino_batching.py create mode 100644 tests/test_kinematics_uncertainty.py create mode 100644 tests/test_nexus_darfix.py create mode 100644 tests/test_operando_log.py diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..a0fecdc --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,90 @@ +name: Release + +on: + push: + tags: + - "v*.*.*" + workflow_dispatch: + +permissions: + contents: write + +jobs: + build-and-verify: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install build & verification dependencies + run: | + python -m pip install --upgrade pip build twine ruff pytest + python -m pip install -e ".[notebook]" + + - name: Verify lint and unit test suite + run: | + ruff check braggtrack/ tests/ scripts/ + pytest tests/ -q + + - name: Build sdist and wheel + run: python -m build + + - name: Validate distribution metadata with Twine + run: twine check dist/* + + - name: Verify clean wheel installation in isolated venv + run: | + python -m venv /tmp/release-smoke-venv + /tmp/release-smoke-venv/bin/pip install dist/*.whl + /tmp/release-smoke-venv/bin/braggtrack-inspect --help + /tmp/release-smoke-venv/bin/braggtrack-watch --help + /tmp/release-smoke-venv/bin/braggtrack-run --help + + - name: Upload distribution artifacts + uses: actions/upload-artifact@v4 + with: + name: python-package-distributions + path: dist/ + + github-release: + needs: build-and-verify + if: startsWith(github.ref, 'refs/tags/v') + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Download distribution artifacts + uses: actions/download-artifact@v4 + with: + name: python-package-distributions + path: dist/ + + - name: Create GitHub Release + uses: softprops/action-gh-release@v2 + with: + files: dist/* + generate_release_notes: true + + publish-pypi: + needs: build-and-verify + if: startsWith(github.ref, 'refs/tags/v') && vars.ENABLE_PYPI_PUBLISH == 'true' + runs-on: ubuntu-latest + environment: + name: pypi + url: https://pypi.org/p/braggtrack + permissions: + id-token: write + steps: + - name: Download distribution artifacts + uses: actions/download-artifact@v4 + with: + name: python-package-distributions + path: dist/ + + - name: Publish distribution to PyPI via Trusted Publisher + uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 6fffb35..dbeeb31 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,25 @@ All notable changes to BraggTrack will be documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.4.0] - 2026-11-17 + +### Added +- **Analytical Poisson + quantization centroid/strain uncertainties & ancestor-referenced kinematics (`braggtrack.segmentation.features`, `braggtrack.tracking.kinematics`, `braggtrack.tracking.assignment`)**: + - Emits per-spot `centroid_mu_err`, `centroid_chi_err`, and `centroid_d_err` combining Poisson photon-counting variance and `1/12` voxel quantization variance. + - Propagates `strain_err` ($\sigma_\varepsilon$), ancestor-referenced `root_track_id`, `lineage_strain`, and `lineage_strain_err` across `1 -> 2+` fracture splits, plus causal velocities (`rate_mu`, `rate_chi`, `rate_d`, `strain_rate`) and Hungarian runner-up `assignment_margin`. +- **Operando electrochemistry & external stimulus synchronization (`braggtrack.io.operando_log`, `braggtrack.viz.operando`)**: + - Parses `.csv`/`.tsv` and Biologic EC-Lab `.mpt` potentiostat logs (`load_operando_log`, `synchronize_stimulus_to_scans`), computing Savitzky–Golay regularized differential capacity $\mathrm{d}Q/\mathrm{d}V$ and per-grain electro-strain susceptibility `d_strain_d_v` ($\partial\varepsilon/\partial V$). + - Added 3-panel publication plot `plot_operando_strain_and_events` and wired `--operando-log` / `--operando-tz-offset` into `braggtrack-report`, `braggtrack-run`, and `report.html`. +- **Batched `DINOv2` ViT inference & zero-config `darfix` / ESRF BLISS NeXus auto-calibration (`braggtrack.semantic.dino`, `braggtrack.io.nexus`)**: + - Added `embed_batch` and `extract_patch_features_batch` across `MultiviewEncoder` and `PatchFeatureEncoder` (with CPU L3-friendly micro-batching), accelerating `braggtrack-embed-dataset`, `compute_fracture_precursors`, and `segment_dino` while guaranteeing bit-identical cosine parity. + - Added `NXdata` `@default` / `@signal` / `@axes` (`darfix` processed HDF5) and ESRF BLISS `instrument/positioners` auto-calibration in `discover_primary_volume_path` and `extract_axis_calibration`. +- **Online causal streaming & autonomous DFXM "Scout-and-Zoom" engine (`braggtrack.autonomous`, `braggtrack-watch`)**: + - Added `CausalStreamingTracker` (`streaming.py`) with strictly causal trailing-window Otsu stabilisation and $O(1)$-volume-RAM cached ROI precursors. + - Added `ZoomTriggerPolicy`, `ZoomTarget`, and `select_zoom_targets` (`trigger.py`) with velocity-extrapolated diffractometer setpoint prediction, uncertainty-aware rocking-window sizing, and `bliss_dfxm_zoom.v1` JSONL serialization (`zoom_triggers.jsonl`). + - Added `evaluate_causal_replay` (`replay.py`) benchmarking autonomous pre-fracture recall, electrochemical lead ($\Delta E$), and setpoint hit rate against `brightest_intensity`, `strain_only`, and `random` policies, exposed via the 10th CLI entry point `braggtrack-watch` (`--mode watch` and `--mode replay`). +- **Ecosystem positioning, verified bibliography & release workflow (`docs/positioning.md`, `.github/workflows/release.yml`)**: + - Added `docs/positioning.md` comparing `BraggTrack` against `darfix`, `ImageD11`, `HEXRD`, `BraggNN`, `TrackMate 7`, and `LapTrack`, updated `paper.md` and `paper.bib` with verified DOIs (`@GarrigaFerrer2023`, `@Isern2025`, `@Bernier2011`, `@Liu2022`, `@Fukai2023`, `@Ershov2022`), bumped metadata to `0.4.0`, and added tag-triggered sdist/wheel + Twine + GitHub Release / PyPI Trusted Publisher workflow. + ## [0.3.0] - 2026-11-17 ### Added diff --git a/CITATION.cff b/CITATION.cff index 8d1e56b..a2f1b07 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -2,21 +2,25 @@ cff-version: 1.2.0 message: "If you use this software, please cite it as below." title: "BraggTrack" type: software -version: 0.3.0 +version: 0.4.0 date-released: "2026-05-16" license: MIT repository-code: "https://github.com/BASE-Laboratory/BraggTrack" url: "https://github.com/BASE-Laboratory/BraggTrack" abstract: >- - Semantic 4D kinematics, multi-scan gap closing, and chemomechanical - fracture tracking for operando X-ray diffraction. BraggTrack segments - Bragg reflections in 3D reciprocal-space volumes, tracks trajectories - and split/merge lineage using classical crystallography and - vision-transformer embeddings, and exports ImageD11, NeXus HDF5, and + Semantic 4D kinematics, multi-scan gap closing, chemomechanical fracture + tracking, operando electrochemistry synchronization, and online autonomous + Dark-Field X-ray Microscopy (DFXM) target selection for operando X-ray + diffraction. BraggTrack segments Bragg reflections in 3D reciprocal-space + volumes, tracks trajectories and split/merge lineage with analytical + uncertainties using classical crystallography and batched vision-transformer + embeddings, and exports ImageD11, NeXus HDF5, BLISS zoom triggers, and interactive HTML 4D lineage reports. keywords: - X-ray diffraction + - dark-field X-ray microscopy - operando crystallography + - autonomous experiments - 3D segmentation - object tracking - grain fracture diff --git a/README.md b/README.md index d61abd5..daf0df6 100644 --- a/README.md +++ b/README.md @@ -12,15 +12,16 @@ Semantic 4D kinematics, multi-scan beam-dropout gap closing, grain lineage (`1 - ## Key Capabilities -- **Beamline-scale NeXus/HDF5 I/O, lazy ROI streaming & crystallographic mapping (`braggtrack.io`)** — Auto-discovers 3D detector cubes across standard NeXus paths, ESRF-ID03 LIMA files (`/entry_0000/ESRF-ID03/pco_nf/data`), and arbitrary HDF5 trees (`auto_discover=True`). Streams `z`-slabs via `LazyVolume` (`otsu_threshold_chunked`, `read_roi`), calibrates `(mu, chi, d)` via `AxisCalibration`, maps transmission geometry `(2theta, eta, d, |Q|)` via `DetectorGeometry`, and exports directly to **`ImageD11` (`.flt`)** and **NeXus `NXprocess` HDF5 (`.nxs`)**. -- **Stabilised 3D Bragg reflection segmentation (`braggtrack.segmentation`)** — Streaming Otsu foreground masking with cross-scan rolling-median smoothing (`smooth_thresholds`), 3D LoG peak enhancement, robust `h`-maxima seeding, 3D watershed, nearby-basin merging, and physical or voxel-space covariance/eigenvalue extraction. Includes an experimental dense patch-feature + HDBSCAN slice-stitching segmenter (`--method dino`). -- **Multi-view foundation vision descriptors (`braggtrack.semantic`)** — Orthogonal $(\mu, \chi, d)$ maximum-intensity projections (MIPs) encoded with ungated **`facebook/dinov2-small`** by default (zero HuggingFace login required), drop-in support for **DINOv3** (`facebook/dinov3-vitb16-pretrain-lvd1689m`), or a deterministic zero-GPU `mock` backend for CI. -- **4D grain kinematics, multi-scan gap closing, split/merge lineage & precursors (`braggtrack.tracking`)** — Vectorised geometry + semantic Hungarian association, Jaqaman-style multi-scan gap closing (`--max-gap`) across transient beam dropouts, per-grain lattice strain ($\Delta d / d_0$) and angular misorientation ($\Delta\mu$, $\Delta\chi$), intensity-partitioned `1 -> 2+` split and `2+ -> 1` merge DAG edges, and persistent multi-scan fracture precursor ranking combining 3D shape anisotropy, covariance spread growth, and spot ROI sub-peak / DINO patch-token dispersion. -- **Publication figures & offline interactive HTML 4D Explorer (`braggtrack.viz`, `braggtrack-report`)** — Generates Okabe–Ito styled lineage DAGs, strain/misorientation dashboards, precursor heatmaps, 3-view MIP cards, and a single-file interactive `report.html` with embedded base64 MIP thumbnails that opens offline on air-gapped beamline networks. -- **One-command reproducible pipeline (`braggtrack-run`)** — Runs validation, segmentation, semantic embedding, tracking, kinematics, fracture event analysis, HTML reporting, and `ImageD11`/NeXus export end-to-end, emitting SHA-256 input checksums, stage timings, and `run_manifest.json`. +- **Beamline-scale NeXus/HDF5 I/O, `darfix`/BLISS auto-calibration & operando sync (`braggtrack.io`)** — Auto-discovers 3D detector cubes across `darfix` `NXdata` (`@default` / `@signal` / `@axes`), ESRF-ID03 LIMA files (`/entry_0000/ESRF-ID03/pco_nf/data`), ESRF BLISS `instrument/positioners`, and arbitrary HDF5 trees (`auto_discover=True`). Streams `z`-slabs via `LazyVolume`, synchronizes external potentiostat / load-frame logs (`CSV`/`TSV` and Biologic EC-Lab `.mpt`, regularized $\mathrm{d}Q/\mathrm{d}V$, $\partial\varepsilon/\partial V$), maps transmission geometry `(2theta, eta, d, |Q|)` via `DetectorGeometry`, and exports directly to **`ImageD11` (`.flt`)** and **NeXus `NXprocess` HDF5 (`.nxs`)**. +- **Stabilised 3D Bragg reflection segmentation (`braggtrack.segmentation`)** — Streaming Otsu foreground masking with cross-scan rolling-median smoothing (`smooth_thresholds`), 3D LoG peak enhancement, robust `h`-maxima seeding, 3D watershed, nearby-basin merging, analytical Poisson + quantization centroid uncertainties (`centroid_*_err`), and physical or voxel-space covariance/eigenvalue extraction. Includes an experimental batched dense patch-feature + HDBSCAN slice-stitching segmenter (`--method dino`). +- **Batched multi-view foundation vision descriptors (`braggtrack.semantic`)** — Orthogonal $(\mu, \chi, d)$ maximum-intensity projections (MIPs) encoded in batched forward passes (`embed_batch`, `extract_patch_features_batch`) with ungated **`facebook/dinov2-small`** by default (zero HuggingFace login required), drop-in support for **DINOv3** (`facebook/dinov3-vitb16-pretrain-lvd1689m`), or a deterministic zero-GPU `mock` backend for CI. +- **4D grain kinematics, uncertainty propagation, split/merge lineage & precursors (`braggtrack.tracking`)** — Vectorised geometry + semantic Hungarian association with runner-up `assignment_margin`, Jaqaman-style multi-scan gap closing (`--max-gap`), local strain ($\Delta d / d_0$), ancestor-referenced `lineage_strain` across splits, propagated $\sigma_\varepsilon$, causal angular/lattice velocities (`rate_mu`, `rate_chi`, `rate_d`, `strain_rate`), intensity-partitioned `1 -> 2+` split and `2+ -> 1` merge DAG edges, and persistent multi-scan fracture precursor ranking. +- **Online causal streaming & autonomous DFXM "Scout-and-Zoom" (`braggtrack.autonomous`, `braggtrack-watch`)** — Strictly causal trailing-window Otsu streaming tracker (`CausalStreamingTracker`) with $O(1)$-volume-RAM cached ROI precursors, velocity-extrapolated diffractometer setpoint prediction during rapid phase transitions (e.g., Ni92 `H2 -> H3` collapse), `bliss_dfxm_zoom.v1` JSONL trigger emission (`zoom_triggers.jsonl`), and offline causal replay benchmarking against naive baselines. +- **Publication figures, operando $\mathrm{d}Q/\mathrm{d}V$ dashboards & offline HTML 4D Explorer (`braggtrack.viz`, `braggtrack-report`)** — Generates Okabe–Ito styled lineage DAGs, strain/misorientation dashboards, 3-panel operando electrochemistry + fracture synchronization plots, precursor heatmaps, 3-view MIP cards, and a single-file interactive `report.html` that opens offline on air-gapped beamline networks. +- **One-command reproducible pipeline (`braggtrack-run`)** — Runs validation, operando stimulus sync, segmentation, semantic embedding, tracking, kinematics, fracture event analysis, HTML reporting, and `ImageD11`/NeXus export end-to-end, emitting SHA-256 input checksums, stage timings, and `run_manifest.json`.

- BraggTrack v0.3.0 Quantitative 4D Diffraction Benchmark Suite + BraggTrack Quantitative 4D Diffraction Benchmark Suite

--- @@ -67,7 +68,7 @@ Produces: - `artifacts/pipeline/results.nxs` & `artifacts/pipeline/peaks.flt` - `artifacts/pipeline/run_manifest.json` (SHA-256 input checksums, git SHA, config, stage timings) -### Stage-by-stage CLI commands (9 Entry Points) +### Stage-by-stage CLI commands (10 Entry Points) | CLI Entry Point | Module Equivalent | Purpose | |---|---|---| @@ -75,11 +76,12 @@ Produces: | `braggtrack-validate` | `python -m braggtrack.cli.validate_dataset` | Validate sequence ordering, monotonic timestamps, and axis contracts | | `braggtrack-segment-synthetic` | `python -m braggtrack.cli.segment_synthetic` | Run fast synthetic 3D segmentation smoke test | | `braggtrack-segment-dataset` | `python -m braggtrack.cli.segment_dataset` | Segment 3D Bragg spots via chunked Otsu + smoothed thresholds & optional calibration | -| `braggtrack-embed-dataset` | `python -m braggtrack.cli.embed_dataset` | Stream lazy 3D spot ROIs & compute orthogonal MIP embeddings (`auto`, `mock`, `torch`) | +| `braggtrack-embed-dataset` | `python -m braggtrack.cli.embed_dataset` | Stream lazy 3D spot ROIs & compute batched MIP embeddings (`auto`, `mock`, `torch`) | | `braggtrack-track-dataset` | `python -m braggtrack.cli.track_dataset` | Build trajectory DAG (`--max-gap`), export `tracks.csv`, `kinematics.csv`, `.flt`, `.nxs` | -| `braggtrack-events` | `python -m braggtrack.cli.detect_events` | Resolve `1 -> 2+` splits, `2+ -> 1` merges, and lazy-ROI fracture precursors | -| `braggtrack-report` | `python -m braggtrack.cli.report_dataset` | Render publication PNG/PDF figures and self-contained interactive `report.html` | -| `braggtrack-run` | `python -m braggtrack.cli.run_pipeline` | Execute the full pipeline with optional `--config config.json`, `--report`, and exports | +| `braggtrack-events` | `python -m braggtrack.cli.detect_events` | Resolve `1 -> 2+` splits, `2+ -> 1` merges, and batched lazy-ROI fracture precursors | +| `braggtrack-report` | `python -m braggtrack.cli.report_dataset` | Render publication PNG/PDF figures (`--operando-log`) and self-contained `report.html` | +| `braggtrack-watch` | `python -m braggtrack.cli.watch_autonomous` | Live causal streaming watcher (`--mode watch`) & autonomous DFXM replay (`--mode replay`) | +| `braggtrack-run` | `python -m braggtrack.cli.run_pipeline` | Execute the full pipeline with optional `--config`, `--operando-log`, `--report`, and exports | --- @@ -162,9 +164,9 @@ python scripts/pre_pr_check.py ## Repository Layout & Contributing -- **`braggtrack/`** — Installable Python library (`io`, `segmentation`, `semantic`, `tracking`, `viz`, `cli`). +- **`braggtrack/`** — Installable Python library (`io`, `segmentation`, `semantic`, `tracking`, `autonomous`, `viz`, `cli`). - **`data/sample_operando/`** — Bundled ESRF-ID03 operando test scans (`scan0001`–`scan0003`). -- **`docs/`** — [Architecture](docs/architecture.md), [Benchmarks](docs/benchmarks.md), [Coding Practices](docs/coding-practices.md), and publication figures (`docs/figures/`). +- **`docs/`** — [Ecosystem Positioning & Autonomous DFXM Guide](docs/positioning.md), [Architecture](docs/architecture.md), [Benchmarks](docs/benchmarks.md), [Coding Practices](docs/coding-practices.md), and publication figures (`docs/figures/`). - **`scripts/`** — 9 acceptance gates, 5-scenario benchmark suite (`benchmark_suite.py`), semantic α/β ablation (`ablation_semantic.py`), and CI runner (`ci_report.py`). - **`artifacts/`** — Generated pipeline outputs (gitignored; never commit). diff --git a/braggtrack/__init__.py b/braggtrack/__init__.py index 14eeacb..6a570d3 100644 --- a/braggtrack/__init__.py +++ b/braggtrack/__init__.py @@ -5,6 +5,6 @@ try: __version__ = version("braggtrack") except PackageNotFoundError: - __version__ = "0.3.0.dev0" + __version__ = "0.4.0.dev0" -__all__ = ["io", "segmentation", "semantic", "tracking", "viz"] +__all__ = ["autonomous", "io", "segmentation", "semantic", "tracking", "viz"] diff --git a/braggtrack/autonomous/__init__.py b/braggtrack/autonomous/__init__.py new file mode 100644 index 0000000..d44cf62 --- /dev/null +++ b/braggtrack/autonomous/__init__.py @@ -0,0 +1,17 @@ +"""Online causal streaming and autonomous DFXM "Scout-and-Zoom" engine.""" + +from .replay import PolicyReplayMetrics, ReplayBenchmarkResult, evaluate_causal_replay +from .streaming import CausalStreamingTracker, StreamingStepResult +from .trigger import ZoomTarget, ZoomTriggerPolicy, compute_target_geometry, select_zoom_targets + +__all__ = [ + "CausalStreamingTracker", + "PolicyReplayMetrics", + "ReplayBenchmarkResult", + "StreamingStepResult", + "ZoomTarget", + "ZoomTriggerPolicy", + "compute_target_geometry", + "evaluate_causal_replay", + "select_zoom_targets", +] diff --git a/braggtrack/autonomous/replay.py b/braggtrack/autonomous/replay.py new file mode 100644 index 0000000..ef0f3b3 --- /dev/null +++ b/braggtrack/autonomous/replay.py @@ -0,0 +1,328 @@ +"""Closed-loop retrospective causal replay benchmark for autonomous DFXM zoom. + +Replays a recorded 4D operando diffraction dataset strictly scan-by-scan through +:class:`CausalStreamingTracker` and evaluates whether autonomous zoom triggers fire +*before* actual ``1 -> 2+`` grain fracture events, whether velocity-extrapolated +motor setpoints accurately capture the grain at ``t + 1``, and how ``BraggTrack`` +compares against naive beamline trigger baselines (``random``, ``brightest_intensity``, +and ``strain_only``) under an identical zoom acquisition budget. +""" + +from __future__ import annotations + +from collections.abc import Sequence +from dataclasses import dataclass +from pathlib import Path +from typing import TYPE_CHECKING, Any + +import numpy as np + +from braggtrack.tracking.precursors import PrecursorConfig + +from .streaming import CausalStreamingTracker, StreamingStepResult +from .trigger import ZoomTarget, ZoomTriggerPolicy, compute_target_geometry + +if TYPE_CHECKING: + from braggtrack.io.crystallography import DetectorGeometry + from braggtrack.io.models import AxisCalibration + from braggtrack.io.operando_log import ScanStimulusPoint + from braggtrack.semantic.dino import BackendName + + +@dataclass(frozen=True) +class PolicyReplayMetrics: + """Quantitative closed-loop zoom performance for one trigger policy.""" + + policy_name: str + n_zooms_fired: int + n_fracture_lineages_total: int + n_fracture_lineages_captured_pre_split: int + fracture_capture_recall: float + fracture_capture_precision: float + mean_lead_scans_before_split: float + mean_lead_voltage_mv: float | None + setpoint_hit_rate_next_scan: float + static_centroid_hit_rate_next_scan: float + + def to_dict(self) -> dict[str, Any]: + return { + "policy_name": self.policy_name, + "n_zooms_fired": int(self.n_zooms_fired), + "n_fracture_lineages_total": int(self.n_fracture_lineages_total), + "n_fracture_lineages_captured_pre_split": int(self.n_fracture_lineages_captured_pre_split), + "fracture_capture_recall": round(float(self.fracture_capture_recall), 4), + "fracture_capture_precision": round(float(self.fracture_capture_precision), 4), + "mean_lead_scans_before_split": round(float(self.mean_lead_scans_before_split), 3), + "mean_lead_voltage_mv": ( + round(float(self.mean_lead_voltage_mv), 2) if self.mean_lead_voltage_mv is not None else None + ), + "setpoint_hit_rate_next_scan": round(float(self.setpoint_hit_rate_next_scan), 4), + "static_centroid_hit_rate_next_scan": round(float(self.static_centroid_hit_rate_next_scan), 4), + } + + +@dataclass(frozen=True) +class ReplayBenchmarkResult: + """Complete causal replay trajectory, zoom triggers, and baseline comparison table.""" + + n_scans: int + mean_step_latency_sec: float + max_step_latency_sec: float + steps: list[StreamingStepResult] + zoom_targets: list[ZoomTarget] + policy_comparison: dict[str, PolicyReplayMetrics] + + def to_dict(self) -> dict[str, Any]: + return { + "n_scans": int(self.n_scans), + "mean_step_latency_sec": round(float(self.mean_step_latency_sec), 4), + "max_step_latency_sec": round(float(self.max_step_latency_sec), 4), + "n_zoom_targets": len(self.zoom_targets), + "zoom_targets": [t.to_bliss_command() for t in self.zoom_targets], + "policy_comparison": {k: v.to_dict() for k, v in self.policy_comparison.items()}, + "steps": [s.to_dict() for s in self.steps], + } + + +def _score_trigger_events( + policy_name: str, + triggers: list[tuple[int, int, tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]]], + *, + split_scan_by_root: dict[int, int], + obs_by_scan_and_root: dict[tuple[int, int], list[tuple[float, float, float]]], + voltage_by_scan: dict[int, float], +) -> PolicyReplayMetrics: + """Evaluate a list of ``(scan_idx, root_tid, cur_c, pred_c, half_w)`` zoom actions.""" + n_frac_total = len(split_scan_by_root) + captured_roots: dict[int, int] = {} + pre_split_hits = 0 + + next_scan_eval_count = 0 + extrap_hits = 0 + static_hits = 0 + + for trig_scan, root_tid, cur_c, pred_c, half_w in triggers: + sp_scan = split_scan_by_root.get(root_tid) + if sp_scan is not None and trig_scan < sp_scan: + pre_split_hits += 1 + if root_tid not in captured_roots or trig_scan < captured_roots[root_tid]: + captured_roots[root_tid] = trig_scan + + next_obs = obs_by_scan_and_root.get((trig_scan + 1, root_tid), []) + if next_obs: + next_scan_eval_count += 1 + hm, hc, hd = half_w + pm, pc, pd = pred_c + cm, cc, cd = cur_c + if any(abs(m - pm) <= hm and abs(c - pc) <= hc and abs(d - pd) <= hd for m, c, d in next_obs): + extrap_hits += 1 + if any(abs(m - cm) <= hm and abs(c - cc) <= hc and abs(d - cd) <= hd for m, c, d in next_obs): + static_hits += 1 + + lead_scans = [split_scan_by_root[r] - s for r, s in captured_roots.items()] + lead_mv: list[float] = [] + for r, s in captured_roots.items(): + sp = split_scan_by_root[r] + if s in voltage_by_scan and sp in voltage_by_scan: + lead_mv.append(abs(voltage_by_scan[sp] - voltage_by_scan[s]) * 1000.0) + + n_fired = len(triggers) + recall = (len(captured_roots) / n_frac_total) if n_frac_total > 0 else 0.0 + precision = (pre_split_hits / n_fired) if n_fired > 0 else 0.0 + mean_lead = float(np.mean(lead_scans)) if lead_scans else 0.0 + mean_mv = float(np.mean(lead_mv)) if lead_mv else None + extrap_rate = (extrap_hits / next_scan_eval_count) if next_scan_eval_count > 0 else 0.0 + static_rate = (static_hits / next_scan_eval_count) if next_scan_eval_count > 0 else 0.0 + + return PolicyReplayMetrics( + policy_name=policy_name, + n_zooms_fired=n_fired, + n_fracture_lineages_total=n_frac_total, + n_fracture_lineages_captured_pre_split=len(captured_roots), + fracture_capture_recall=recall, + fracture_capture_precision=precision, + mean_lead_scans_before_split=mean_lead, + mean_lead_voltage_mv=mean_mv, + setpoint_hit_rate_next_scan=extrap_rate, + static_centroid_hit_rate_next_scan=static_rate, + ) + + +def evaluate_causal_replay( + scans: Sequence[np.ndarray | str | Path], + *, + scan_names: Sequence[str] | None = None, + stimuli: Sequence[ScanStimulusPoint | None] | None = None, + calibration: AxisCalibration | None = None, + detector: DetectorGeometry | None = None, + backend: BackendName | None = "mock", + precursor_config: PrecursorConfig | None = None, + trigger_policy: ZoomTriggerPolicy | None = None, + zoom_budget: int | None = None, + seed: int = 0, +) -> ReplayBenchmarkResult: + """Run strictly causal scan-by-scan replay and benchmark against naive trigger baselines.""" + pol = trigger_policy or ZoomTriggerPolicy() + tracker = CausalStreamingTracker( + backend=backend, + calibration=calibration, + detector=detector, + precursor_config=precursor_config, + trigger_policy=pol, + ) + + steps: list[StreamingStepResult] = [] + # Capture per-step causal candidate pools so baseline policies face the exact same causal state & budget + causal_pools: list[ + list[ + tuple[ + int, # root_tid + float, # integrated_intensity + float, # abs_lineage_strain + tuple[float, float, float], # cur_c + tuple[float, float, float], # pred_c + tuple[float, float, float], # half_w + ] + ] + ] = [] + + for idx, item in enumerate(scans): + s_name = scan_names[idx] if scan_names is not None and idx < len(scan_names) else None + stim = stimuli[idx] if stimuli is not None and idx < len(stimuli) else None + res = tracker.step(item, scan_name=s_name, stimulus=stim) + steps.append(res) + + kin_by_tid = {k.track_id: k for k in tracker.kinematics} + pool_t: list[ + tuple[ + int, + float, + float, + tuple[float, float, float], + tuple[float, float, float], + tuple[float, float, float], + ] + ] = [] + for obs in tracker.track_table: + if int(obs["scan_idx"]) != idx: + continue + if pol.exclude_post_split_daughters and str(obs.get("lineage_role", "")) == "split_daughter": + continue + tid = int(obs["track_id"]) + kin = kin_by_tid.get(tid) + if kin is None or idx not in kin.scan_indices: + continue + pos = kin.scan_indices.index(idx) + if (pos + 1) < pol.min_track_age: + continue + root_tid = int(kin.root_track_id) if kin.root_track_id > 0 else tid + inten = float(obs.get("integrated_intensity", 0.0)) + if inten < pol.min_intensity: + continue + l_strain = abs(float(kin.lineage_strain[pos])) if len(kin.lineage_strain) > pos else 0.0 + cur_c, pred_c, half_w, _, _ = compute_target_geometry( + obs, + kin, + pos, + lead_scans=pol.lead_scans, + window_sigma=pol.window_sigma, + calibration=tracker.calibration, + detector=detector, + ) + pool_t.append((root_tid, inten, l_strain, cur_c, pred_c, half_w)) + causal_pools.append(pool_t) + + # Extract ground-truth lineage split scans and future positions from the completed sequence + final_kin_by_tid = {k.track_id: k for k in tracker.kinematics} + split_scan_by_root: dict[int, int] = {} + for ev in tracker.graph.graph.get("lineage_events", []): + if ev.event_type == "split": + for ptid in ev.parent_track_ids: + pk = final_kin_by_tid.get(int(ptid)) + rtid = int(pk.root_track_id) if pk is not None and pk.root_track_id > 0 else int(ptid) + if rtid not in split_scan_by_root or ev.scan_idx_to < split_scan_by_root[rtid]: + split_scan_by_root[rtid] = int(ev.scan_idx_to) + + obs_by_scan_and_root: dict[tuple[int, int], list[tuple[float, float, float]]] = {} + for obs in tracker.track_table: + s_i = int(obs["scan_idx"]) + tid = int(obs["track_id"]) + pk = final_kin_by_tid.get(tid) + rtid = int(pk.root_track_id) if pk is not None and pk.root_track_id > 0 else tid + obs_by_scan_and_root.setdefault((s_i, rtid), []).append( + (float(obs["centroid_mu"]), float(obs["centroid_chi"]), float(obs["centroid_d"])) + ) + + voltage_by_scan: dict[int, float] = {} + if stimuli is not None: + for idx, stim in enumerate(stimuli): + if stim is not None and stim.voltage_v is not None: + voltage_by_scan[idx] = float(stim.voltage_v) + + bt_targets = list(tracker.all_zoom_targets) + if zoom_budget is not None and zoom_budget >= 0: + bt_targets = bt_targets[:zoom_budget] + + effective_budget = len(bt_targets) if zoom_budget is None else max(0, int(zoom_budget)) + + bt_tuples = [ + (t.scan_idx, t.root_track_id, t.current_centroid, t.predicted_setpoint, t.scan_half_widths) for t in bt_targets + ] + + # Simulate naive causal baselines under the exact same zoom_budget and cooldown_scans + rng = np.random.default_rng(seed) + + def _run_baseline( + mode: str, + ) -> list[tuple[int, int, tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]]]: + fired: list[ + tuple[int, int, tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]] + ] = [] + cd: dict[int, int] = {} + # Distribute budget evenly or greedily once min_track_age is met + for t_idx, pool in enumerate(causal_pools): + if len(fired) >= effective_budget or not pool: + continue + eligible = [p for p in pool if (p[0] not in cd or (t_idx - cd[p[0]]) >= pol.cooldown_scans)] + if not eligible: + continue + if mode == "random": + choice = eligible[int(rng.integers(0, len(eligible)))] + elif mode == "brightest_intensity": + choice = max(eligible, key=lambda p: p[1]) + elif mode == "strain_only": + choice = max(eligible, key=lambda p: p[2]) + else: + raise ValueError(f"Unknown baseline mode: {mode}") + rtid, _, _, cur_c, pred_c, half_w = choice + cd[rtid] = t_idx + fired.append((t_idx, rtid, cur_c, pred_c, half_w)) + return fired + + comparison: dict[str, PolicyReplayMetrics] = { + "braggtrack_autonomous": _score_trigger_events( + "braggtrack_autonomous", + bt_tuples, + split_scan_by_root=split_scan_by_root, + obs_by_scan_and_root=obs_by_scan_and_root, + voltage_by_scan=voltage_by_scan, + ), + } + for base_name in ("brightest_intensity", "strain_only", "random"): + comparison[base_name] = _score_trigger_events( + base_name, + _run_baseline(base_name), + split_scan_by_root=split_scan_by_root, + obs_by_scan_and_root=obs_by_scan_and_root, + voltage_by_scan=voltage_by_scan, + ) + + latencies = [s.step_latency_sec for s in steps] if steps else [0.0] + return ReplayBenchmarkResult( + n_scans=len(steps), + mean_step_latency_sec=float(np.mean(latencies)), + max_step_latency_sec=float(np.max(latencies)), + steps=steps, + zoom_targets=bt_targets, + policy_comparison=comparison, + ) diff --git a/braggtrack/autonomous/streaming.py b/braggtrack/autonomous/streaming.py new file mode 100644 index 0000000..ef87f04 --- /dev/null +++ b/braggtrack/autonomous/streaming.py @@ -0,0 +1,327 @@ +"""Strictly causal online scan-by-scan tracker for live beamline streaming. + +Processes incoming 3D rocking-curve scans ``t = 0, 1, 2, ...`` without looking ahead: +- Causal trailing-window median Otsu thresholding (using only scans ``<= t``). +- 3D LoG + seeded watershed segmentation and Poisson-uncertainty feature extraction. +- Batched multi-view ``DINOv2`` embedding and cached ROI patch-dispersion scoring. +- Incremental Hungarian + gap-closing + ``1 -> 2+`` split/merge trajectory DAG update. +- Autonomous DFXM "Scout-and-Zoom" target selection at the end of every scan. +""" + +from __future__ import annotations + +import time +from dataclasses import dataclass +from pathlib import Path +from typing import TYPE_CHECKING, Any + +import networkx as nx +import numpy as np + +from braggtrack.io.models import AxisCalibration +from braggtrack.io.nexus import extract_axis_calibration, extract_scan_metadata, load_primary_volume +from braggtrack.segmentation import ( + extract_instance_table, + otsu_threshold, + relabel_sequential, + remove_small_objects, + segment_classical, +) +from braggtrack.semantic import DEFAULT_DINO_MODEL, make_multiview_encoder, make_patch_encoder +from braggtrack.semantic.mips import crop_spot_cube, orthogonal_mips +from braggtrack.tracking.cost import GeometrySemanticCost, PositionShapeCost +from braggtrack.tracking.events import LineageEvent, SplitMergeConfig, events_to_table +from braggtrack.tracking.gap_closing import GapClosingConfig +from braggtrack.tracking.kinematics import GrainKinematics, compute_grain_kinematics +from braggtrack.tracking.lifecycle import build_tracks, tracks_to_table +from braggtrack.tracking.precursors import ( + ObservationPrecursorScore, + PrecursorCandidate, + PrecursorConfig, + compute_fracture_precursors, +) + +from .trigger import ZoomTarget, ZoomTriggerPolicy, select_zoom_targets + +if TYPE_CHECKING: + from braggtrack.io.crystallography import DetectorGeometry + from braggtrack.io.operando_log import ScanStimulusPoint + from braggtrack.semantic.dino import BackendName + + +@dataclass(frozen=True) +class StreamingStepResult: + """Snapshot of online causal tracking and autonomous DFXM triggers after scan ``scan_idx``.""" + + scan_idx: int + scan_name: str + threshold_raw: float + threshold_causal: float + n_spots: int + n_active_tracks: int + n_lineage_events_total: int + new_lineage_events: list[LineageEvent] + precursor_candidates: list[PrecursorCandidate] + zoom_targets: list[ZoomTarget] + step_latency_sec: float + stimulus: ScanStimulusPoint | None = None + + def to_dict(self) -> dict[str, Any]: + return { + "scan_idx": int(self.scan_idx), + "scan_name": self.scan_name, + "threshold_raw": round(float(self.threshold_raw), 5), + "threshold_causal": round(float(self.threshold_causal), 5), + "n_spots": int(self.n_spots), + "n_active_tracks": int(self.n_active_tracks), + "n_lineage_events_total": int(self.n_lineage_events_total), + "new_lineage_events": events_to_table(self.new_lineage_events), + "n_precursor_candidates": len(self.precursor_candidates), + "zoom_targets": [t.to_bliss_command() for t in self.zoom_targets], + "step_latency_sec": round(float(self.step_latency_sec), 4), + "stimulus": self.stimulus.to_dict() if self.stimulus is not None else None, + } + + +class CausalStreamingTracker: + """Stateful strictly causal scan-by-scan 4D reflection tracker and zoom trigger engine.""" + + def __init__( + self, + *, + backend: BackendName | None = "auto", + model_name: str = DEFAULT_DINO_MODEL, + smooth_window: int = 5, + seed_peak_fraction: float = 0.08, + seed_response_percentile: float = 0.0, + min_spot_voxels: int = 4, + calibration: AxisCalibration | None = None, + detector: DetectorGeometry | None = None, + cost_alpha: float = 1.0, + cost_beta: float = 0.25, + max_cost: float = float("inf"), + max_gap: int = 0, + split_max_distance: float = 25.0, + precursor_config: PrecursorConfig | None = None, + trigger_policy: ZoomTriggerPolicy | None = None, + batch_size: int = 32, + use_patch_encoder: bool = True, + ) -> None: + self.smooth_window = max(1, int(smooth_window)) + self.seed_peak_fraction = float(seed_peak_fraction) + self.seed_response_percentile = float(seed_response_percentile) + self.min_spot_voxels = max(1, int(min_spot_voxels)) + self.calibration = calibration + self.detector = detector + self.cost_alpha = float(cost_alpha) + self.cost_beta = float(cost_beta) + self.max_cost = float(max_cost) + self.batch_size = max(1, int(batch_size)) + + self.gap_config = GapClosingConfig(max_gap=max(0, int(max_gap))) if max_gap > 0 else None + self.split_merge_config = SplitMergeConfig(max_distance=float(split_max_distance)) + self.precursor_config = precursor_config or PrecursorConfig() + self.trigger_policy = trigger_policy or ZoomTriggerPolicy() + + self._multiview_encoder = ( + make_multiview_encoder(backend, model_name=model_name) if self.cost_beta > 0.0 else None + ) + self._patch_encoder = make_patch_encoder(backend, model_name=model_name) if use_patch_encoder else None + self._cost_fn = GeometrySemanticCost( + PositionShapeCost(), + cost_alpha=self.cost_alpha, + cost_beta=self.cost_beta, + ) + + # Strictly causal state accumulated across scans 0 .. t + self._raw_thresholds: list[float] = [] + self._causal_thresholds: list[float] = [] + self._scan_names: list[str] = [] + self._scan_timestamps: dict[int, str | None] = {} + self._scan_tables: list[list[dict[str, Any]]] = [] + self._stimuli: dict[int, ScanStimulusPoint] = {} + self._roi_cache: dict[tuple[int, int], tuple[int, float]] = {} + self._cooldown_by_lineage: dict[int, int] = {} + + # Latest DAG & derived tables + self._graph: nx.DiGraph = nx.DiGraph() + self._track_table: list[dict[str, Any]] = [] + self._kinematics: list[GrainKinematics] = [] + self._obs_precursor_scores: list[ObservationPrecursorScore] = [] + self._precursor_candidates: list[PrecursorCandidate] = [] + self._all_zoom_targets: list[ZoomTarget] = [] + + @property + def n_scans_processed(self) -> int: + return len(self._scan_tables) + + @property + def graph(self) -> nx.DiGraph: + return self._graph + + @property + def track_table(self) -> list[dict[str, Any]]: + return list(self._track_table) + + @property + def kinematics(self) -> list[GrainKinematics]: + return list(self._kinematics) + + @property + def obs_precursor_scores(self) -> list[ObservationPrecursorScore]: + return list(self._obs_precursor_scores) + + @property + def all_zoom_targets(self) -> list[ZoomTarget]: + return list(self._all_zoom_targets) + + def _resolve_volume_and_meta( + self, + volume_or_path: np.ndarray | str | Path, + scan_name: str | None, + timestamp: str | None, + ) -> tuple[np.ndarray, str, str | None, AxisCalibration]: + if isinstance(volume_or_path, (str, Path)): + p = Path(volume_or_path) + if p.is_dir(): + h5s = sorted([*p.glob("*.h5"), *p.glob("*.hdf5"), *p.glob("*.nxs")]) + if not h5s: + raise FileNotFoundError(f"No HDF5/NeXus file found in scan directory {p}") + file_path = h5s[0] + default_name = p.name + else: + file_path = p + default_name = p.stem + vol = load_primary_volume(file_path) + meta = extract_scan_metadata(file_path) + ts = timestamp if timestamp is not None else meta.get("start_time") + cal = self.calibration if self.calibration is not None else extract_axis_calibration(file_path) + if self.calibration is None and cal.calibrated: + self.calibration = cal + return vol, (scan_name or default_name), ts, cal + + vol = np.asarray(volume_or_path, dtype=np.float64) + cal = self.calibration if self.calibration is not None else AxisCalibration() + name = scan_name or f"scan_{len(self._scan_tables) + 1:04d}" + return vol, name, timestamp, cal + + def step( + self, + volume_or_path: np.ndarray | str | Path, + *, + scan_name: str | None = None, + timestamp: str | None = None, + stimulus: ScanStimulusPoint | None = None, + ) -> StreamingStepResult: + """Ingest one new 3D scan ``t`` causally and emit tracking + autonomous zoom targets.""" + t0 = time.perf_counter() + scan_idx = len(self._scan_tables) + vol, resolved_name, resolved_ts, active_cal = self._resolve_volume_and_meta( + volume_or_path, scan_name, timestamp + ) + if stimulus is not None and resolved_ts is None and stimulus.timestamp is not None: + resolved_ts = stimulus.timestamp + + # 1. Strictly causal trailing-window Otsu threshold (scans max(0, t - W + 1) .. t only!) + raw_thr = float(otsu_threshold(vol)) + self._raw_thresholds.append(raw_thr) + win_lo = max(0, len(self._raw_thresholds) - self.smooth_window) + causal_thr = float(np.median(self._raw_thresholds[win_lo:])) + self._causal_thresholds.append(causal_thr) + + # 2. Classical 3D LoG + watershed segmentation & calibrated feature + uncertainty extraction + seg = segment_classical( + vol, + threshold=causal_thr, + seed_peak_fraction=self.seed_peak_fraction, + seed_response_percentile=self.seed_response_percentile, + ) + labels = relabel_sequential(remove_small_objects(seg.labeled_volume, min_size=self.min_spot_voxels)) + spots = extract_instance_table(labels, vol, calibration=active_cal) + + # 3. Batched DINOv2 multiview embeddings for all spots in scan t + if self._multiview_encoder is not None and spots: + triplets: list[tuple[np.ndarray, np.ndarray, np.ndarray]] = [] + for row in spots: + lbl = int(row["label"]) + masked_cube, _ = crop_spot_cube( + vol, + labels, + lbl, + row, + margin=self.precursor_config.roi_margin, + ) + triplets.append(orthogonal_mips(masked_cube)) + embs = self._multiview_encoder.embed_batch(triplets, batch_size=self.batch_size) + for row, vec in zip(spots, embs, strict=True): + row["embedding"] = vec + + self._scan_names.append(resolved_name) + self._scan_timestamps[scan_idx] = resolved_ts + self._scan_tables.append(spots) + if stimulus is not None: + self._stimuli[scan_idx] = stimulus + + # 4. Build causal trajectory DAG over scans 0 .. t + G = build_tracks( + self._scan_tables, + cost_fn=self._cost_fn, + max_cost=self.max_cost, + gap_closing_config=self.gap_config, + split_merge_config=self.split_merge_config, + scan_timestamps=self._scan_timestamps, + ) + t_table = tracks_to_table(G) + lineage_events: list[LineageEvent] = list(G.graph.get("lineage_events", [])) + new_events = [ev for ev in lineage_events if ev.scan_idx_to == scan_idx] + + # 5. Compute causal kinematics & incremental ROI-cached fracture precursors (only current vol in RAM!) + kin_list = compute_grain_kinematics(t_table) + prec_candidates, obs_scores = compute_fracture_precursors( + t_table, + self.precursor_config, + volumes={scan_idx: vol}, + label_volumes={scan_idx: labels}, + patch_encoder=self._patch_encoder, + lineage_events=lineage_events, + roi_cache=self._roi_cache, + batch_size=self.batch_size, + ) + + # 6. Select and extrapolate autonomous DFXM zoom targets at scan t + zoom_targets = select_zoom_targets( + current_scan_idx=scan_idx, + scan_name=resolved_name, + track_table=t_table, + kinematics=kin_list, + obs_precursor_scores=obs_scores, + policy=self.trigger_policy, + calibration=active_cal, + detector=self.detector, + stimulus=stimulus, + last_triggered_scan_by_lineage=self._cooldown_by_lineage, + ) + + self._graph = G + self._track_table = t_table + self._kinematics = kin_list + self._obs_precursor_scores = obs_scores + self._precursor_candidates = prec_candidates + self._all_zoom_targets.extend(zoom_targets) + + n_active = sum(1 for row in t_table if int(row["scan_idx"]) == scan_idx) + dt = time.perf_counter() - t0 + return StreamingStepResult( + scan_idx=scan_idx, + scan_name=resolved_name, + threshold_raw=raw_thr, + threshold_causal=causal_thr, + n_spots=len(spots), + n_active_tracks=n_active, + n_lineage_events_total=len(lineage_events), + new_lineage_events=new_events, + precursor_candidates=prec_candidates, + zoom_targets=zoom_targets, + step_latency_sec=dt, + stimulus=stimulus, + ) diff --git a/braggtrack/autonomous/trigger.py b/braggtrack/autonomous/trigger.py new file mode 100644 index 0000000..b4b16f6 --- /dev/null +++ b/braggtrack/autonomous/trigger.py @@ -0,0 +1,396 @@ +"""Autonomous DFXM "Scout-and-Zoom" trigger policy and BLISS/Ewoks setpoint extrusion. + +Evaluates active tracked reflections at scan ``t`` using strictly causal kinematics, +analytical centroid uncertainties, and multi-scan fracture precursor persistence to +select high-priority candidate grains for zoomed Dark-Field X-ray Microscopy (DFXM) +rocking/mosaicity acquisitions. Motor setpoints are velocity-extrapolated to +``t + lead_scans`` so fast-shifting reflections (e.g. Ni-rich layered oxide H2 -> H3 +lattice collapse) stay centered in the narrow DFXM objective acceptance cone. +""" + +from __future__ import annotations + +import math +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any + +if TYPE_CHECKING: + from braggtrack.io.crystallography import DetectorGeometry + from braggtrack.io.models import AxisCalibration + from braggtrack.io.operando_log import ScanStimulusPoint + from braggtrack.tracking.kinematics import GrainKinematics + from braggtrack.tracking.precursors import ObservationPrecursorScore + + +@dataclass(frozen=True) +class ZoomTriggerPolicy: + """Decision thresholds, cooldowns, and scan-window geometry for autonomous DFXM zoom.""" + + min_precursor_score: float = 0.40 + min_persistence: int = 2 + min_subpeaks: int = 1 + min_strain_rate: float = 0.0 + min_intensity: float = 20.0 + min_track_age: int = 2 + min_assignment_margin: float = 0.0 + cooldown_scans: int = 3 + max_triggers_per_scan: int = 2 + lead_scans: float = 1.0 + window_sigma: float = 3.5 + exclude_post_split_daughters: bool = True + + +@dataclass(frozen=True) +class ZoomTarget: + """Actionable DFXM zoom acquisition target emitted after causal scan ``scan_idx``.""" + + scan_idx: int + scan_name: str + track_id: int + root_track_id: int + priority_rank: int + priority_score: float + precursor_score: float + persistence_scans: int + roi_subpeak_count: int + anisotropy: float + lineage_strain: float + strain_err: float + strain_rate: float + assignment_margin: float + current_centroid: tuple[float, float, float] + predicted_setpoint: tuple[float, float, float] + scan_half_widths: tuple[float, float, float] + centroid_err: tuple[float, float, float] + lead_scans: float + trigger_reasons: tuple[str, ...] + scattering_angles: dict[str, float] | None = None + operando_state: dict[str, Any] | None = None + + def contains_point(self, mu: float, chi: float, d: float) -> bool: + """Return True if ``(mu, chi, d)`` lies inside ``predicted_setpoint ± scan_half_widths``.""" + pm, pc, pd = self.predicted_setpoint + hm, hc, hd = self.scan_half_widths + return abs(mu - pm) <= hm and abs(chi - pc) <= hc and abs(d - pd) <= hd + + def to_bliss_command(self) -> dict[str, Any]: + """Format as an ESRF BLISS / Ewoks machine-readable DFXM zoom command payload.""" + pm, pc, pd = self.predicted_setpoint + hm, hc, hd = self.scan_half_widths + em, ec, ed = self.centroid_err + cmd: dict[str, Any] = { + "schema_version": "bliss_dfxm_zoom.v1", + "action": "dfxm_high_res_zoom", + "source_scan_idx": int(self.scan_idx), + "source_scan_name": self.scan_name, + "track_id": int(self.track_id), + "root_track_id": int(self.root_track_id), + "priority_rank": int(self.priority_rank), + "priority_score": round(float(self.priority_score), 4), + "lead_scans": round(float(self.lead_scans), 3), + "target_motors": { + "mu": round(float(pm), 6), + "chi": round(float(pc), 6), + "obpitch_or_2theta": round(float(pd), 6), + }, + "scan_intervals": { + "mu": [round(float(pm - hm), 6), round(float(pm + hm), 6)], + "chi": [round(float(pc - hc), 6), round(float(pc + hc), 6)], + "obpitch_or_2theta": [round(float(pd - hd), 6), round(float(pd + hd), 6)], + }, + "scan_half_widths": { + "mu": round(float(hm), 6), + "chi": round(float(hc), 6), + "obpitch_or_2theta": round(float(hd), 6), + }, + "uncertainty_1sigma": { + "centroid_mu_err": round(float(em), 6), + "centroid_chi_err": round(float(ec), 6), + "centroid_d_err": round(float(ed), 6), + "strain_err": round(float(self.strain_err), 7), + }, + "diagnostics": { + "current_centroid": [round(float(x), 6) for x in self.current_centroid], + "precursor_score": round(float(self.precursor_score), 4), + "persistence_scans": int(self.persistence_scans), + "roi_subpeak_count": int(self.roi_subpeak_count), + "anisotropy": round(float(self.anisotropy), 4), + "lineage_strain": round(float(self.lineage_strain), 6), + "strain_rate": round(float(self.strain_rate), 6), + "assignment_margin": ( + round(float(self.assignment_margin), 4) if math.isfinite(self.assignment_margin) else "inf" + ), + }, + "trigger_reasons": list(self.trigger_reasons), + } + if self.scattering_angles is not None: + cmd["crystallographic_setpoint"] = dict(self.scattering_angles) + if self.operando_state is not None: + cmd["operando_state"] = dict(self.operando_state) + return cmd + + def to_dict(self) -> dict[str, Any]: + return self.to_bliss_command() + + +def _trailing_persistence( + track_obs_scores: list[ObservationPrecursorScore], + current_scan_idx: int, + threshold: float, +) -> int: + """Return contiguous causal run length ending at ``current_scan_idx`` with score >= threshold.""" + relevant = sorted( + (s for s in track_obs_scores if s.scan_idx <= current_scan_idx), + key=lambda s: s.scan_idx, + ) + if not relevant or relevant[-1].scan_idx != current_scan_idx: + return 0 + run = 0 + expected_scan = current_scan_idx + for sc in reversed(relevant): + if sc.scan_idx != expected_scan or sc.precursor_score < threshold: + break + run += 1 + expected_scan -= 1 + return run + + +def compute_target_geometry( + obs: dict[str, Any], + kin: GrainKinematics | None, + obs_pos_in_kin: int, + *, + lead_scans: float = 1.0, + window_sigma: float = 3.5, + calibration: AxisCalibration | None = None, + detector: DetectorGeometry | None = None, +) -> tuple[ + tuple[float, float, float], + tuple[float, float, float], + tuple[float, float, float], + tuple[float, float, float], + dict[str, float] | None, +]: + """Compute current centroid, velocity-extrapolated setpoint, half-widths, errors, and scattering angles.""" + cur_mu = float(obs["centroid_mu"]) + cur_chi = float(obs["centroid_chi"]) + cur_d = float(obs["centroid_d"]) + + if kin is not None and 0 <= obs_pos_in_kin < len(kin.scan_indices): + v_mu = float(kin.rate_mu[obs_pos_in_kin]) if len(kin.rate_mu) > obs_pos_in_kin else 0.0 + v_chi = float(kin.rate_chi[obs_pos_in_kin]) if len(kin.rate_chi) > obs_pos_in_kin else 0.0 + v_d = float(kin.rate_d[obs_pos_in_kin]) if len(kin.rate_d) > obs_pos_in_kin else 0.0 + err_mu = float(kin.centroid_mu_err[obs_pos_in_kin]) if len(kin.centroid_mu_err) > obs_pos_in_kin else 0.0 + err_chi = float(kin.centroid_chi_err[obs_pos_in_kin]) if len(kin.centroid_chi_err) > obs_pos_in_kin else 0.0 + err_d = float(kin.centroid_d_err[obs_pos_in_kin]) if len(kin.centroid_d_err) > obs_pos_in_kin else 0.0 + else: + v_mu = v_chi = v_d = 0.0 + err_mu = float(obs.get("centroid_mu_err", 0.0)) + err_chi = float(obs.get("centroid_chi_err", 0.0)) + err_d = float(obs.get("centroid_d_err", 0.0)) + + pred_mu = cur_mu + lead_scans * v_mu + pred_chi = cur_chi + lead_scans * v_chi + pred_d = cur_d + lead_scans * v_d + + step_mu = abs(float(calibration.mu_step)) if calibration is not None else 1.0 + step_chi = abs(float(calibration.chi_step)) if calibration is not None else 1.0 + step_d = abs(float(calibration.d_step)) if calibration is not None else 1.0 + + std_mu = math.sqrt(max(float(obs.get("cov_zz", obs.get("cov_mu_mu", 0.0))), 0.0)) + std_chi = math.sqrt(max(float(obs.get("cov_xx", obs.get("cov_chi_chi", 0.0))), 0.0)) + std_d = math.sqrt(max(float(obs.get("cov_yy", obs.get("cov_d_d", 0.0))), 0.0)) + + # Half-width covers intragranular spread (window_sigma * std) + centroid + drift uncertainty, floored at 1.5 steps. + drift_pad_mu = 0.35 * abs(lead_scans * v_mu) + drift_pad_chi = 0.35 * abs(lead_scans * v_chi) + drift_pad_d = 0.35 * abs(lead_scans * v_d) + + half_mu = max(window_sigma * (std_mu + err_mu) + drift_pad_mu, 1.5 * step_mu) + half_chi = max(window_sigma * (std_chi + err_chi) + drift_pad_chi, 1.5 * step_chi) + half_d = max(window_sigma * (std_d + err_d) + drift_pad_d, 1.5 * step_d) + + scattering: dict[str, float] | None = None + if detector is not None: + if calibration is not None and calibration.calibrated: + z_idx = (pred_mu - calibration.mu_origin) / (calibration.mu_step if calibration.mu_step != 0 else 1.0) + x_px = (pred_chi - calibration.chi_origin) / (calibration.chi_step if calibration.chi_step != 0 else 1.0) + y_px = (pred_d - calibration.d_origin) / (calibration.d_step if calibration.d_step != 0 else 1.0) + else: + z_idx, y_px, x_px = pred_mu, pred_d, pred_chi + scattering = detector.spot_to_scattering(z_idx, y_px, x_px) + + return ( + (cur_mu, cur_chi, cur_d), + (pred_mu, pred_chi, pred_d), + (half_mu, half_chi, half_d), + (err_mu, err_chi, err_d), + scattering, + ) + + +def select_zoom_targets( + *, + current_scan_idx: int, + scan_name: str, + track_table: list[dict[str, Any]], + kinematics: list[GrainKinematics], + obs_precursor_scores: list[ObservationPrecursorScore], + policy: ZoomTriggerPolicy | None = None, + calibration: AxisCalibration | None = None, + detector: DetectorGeometry | None = None, + stimulus: ScanStimulusPoint | None = None, + last_triggered_scan_by_lineage: dict[int, int] | None = None, +) -> list[ZoomTarget]: + """Select, rank, and extrapolate autonomous DFXM zoom targets at ``current_scan_idx``.""" + pol = policy or ZoomTriggerPolicy() + kin_by_tid = {k.track_id: k for k in kinematics} + scores_by_tid: dict[int, list[ObservationPrecursorScore]] = {} + score_at_current: dict[int, ObservationPrecursorScore] = {} + for sc in obs_precursor_scores: + scores_by_tid.setdefault(sc.track_id, []).append(sc) + if sc.scan_idx == current_scan_idx: + score_at_current[sc.track_id] = sc + + cooldown_map = last_triggered_scan_by_lineage if last_triggered_scan_by_lineage is not None else {} + operando_dict = stimulus.to_dict() if stimulus is not None else None + dq_dv_boost = 0.0 + if stimulus is not None and stimulus.dq_dv is not None and math.isfinite(stimulus.dq_dv): + dq_dv_boost = min(0.08, 0.08 * min(1.0, abs(float(stimulus.dq_dv)) / 250.0)) + + raw_candidates: list[ZoomTarget] = [] + for obs in track_table: + if int(obs["scan_idx"]) != current_scan_idx: + continue + tid = int(obs["track_id"]) + if pol.exclude_post_split_daughters and str(obs.get("lineage_role", "")) == "split_daughter": + continue + + intensity = float(obs.get("integrated_intensity", 0.0)) + if intensity < pol.min_intensity: + continue + + margin = float(obs.get("assignment_margin", float("inf"))) + if margin < pol.min_assignment_margin: + continue + + kin = kin_by_tid.get(tid) + if kin is None or current_scan_idx not in kin.scan_indices: + continue + pos = kin.scan_indices.index(current_scan_idx) + track_age = pos + 1 + if track_age < pol.min_track_age: + continue + + root_tid = int(kin.root_track_id) if kin.root_track_id > 0 else tid + prev_trig = cooldown_map.get(root_tid) + if prev_trig is not None and (current_scan_idx - prev_trig) < pol.cooldown_scans: + continue + + sc_now = score_at_current.get(tid) + if sc_now is None or sc_now.precursor_score < pol.min_precursor_score: + continue + if sc_now.roi_subpeak_count < pol.min_subpeaks: + continue + + pers = _trailing_persistence(scores_by_tid.get(tid, []), current_scan_idx, pol.min_precursor_score) + if pers < pol.min_persistence: + continue + + s_rate = float(kin.strain_rate[pos]) if len(kin.strain_rate) > pos else 0.0 + if abs(s_rate) < pol.min_strain_rate: + continue + + l_strain = float(kin.lineage_strain[pos]) if len(kin.lineage_strain) > pos else float(kin.strain[pos]) + s_err = float(kin.lineage_strain_err[pos]) if len(kin.lineage_strain_err) > pos else 0.0 + + priority = ( + 0.55 * float(sc_now.precursor_score) + + 0.20 * min(1.0, pers / 4.0) + + 0.15 * min(1.0, max(0, sc_now.roi_subpeak_count - 1) * 0.5) + + 0.10 * min(1.0, abs(s_rate) / 0.005) + + dq_dv_boost + ) + + reasons: list[str] = [ + f"precursor_score={sc_now.precursor_score:.3f}>={pol.min_precursor_score:.2f}", + f"persistence={pers}_scans", + ] + if sc_now.roi_subpeak_count >= 2: + reasons.append(f"bimodal_subpeaks={sc_now.roi_subpeak_count}") + if sc_now.anisotropy >= 2.0: + reasons.append(f"mosaicity_anisotropy={sc_now.anisotropy:.2f}") + if abs(s_rate) >= 0.001: + reasons.append(f"strain_rate={s_rate:+.5f}/scan") + if dq_dv_boost > 0.02 and stimulus is not None and stimulus.voltage_v is not None: + reasons.append(f"redox_active_E={stimulus.voltage_v:.3f}V") + + cur_c, pred_c, half_w, c_err, scat = compute_target_geometry( + obs, + kin, + pos, + lead_scans=pol.lead_scans, + window_sigma=pol.window_sigma, + calibration=calibration, + detector=detector, + ) + + raw_candidates.append( + ZoomTarget( + scan_idx=current_scan_idx, + scan_name=scan_name, + track_id=tid, + root_track_id=root_tid, + priority_rank=0, + priority_score=float(priority), + precursor_score=float(sc_now.precursor_score), + persistence_scans=pers, + roi_subpeak_count=int(sc_now.roi_subpeak_count), + anisotropy=float(sc_now.anisotropy), + lineage_strain=l_strain, + strain_err=s_err, + strain_rate=s_rate, + assignment_margin=margin, + current_centroid=cur_c, + predicted_setpoint=pred_c, + scan_half_widths=half_w, + centroid_err=c_err, + lead_scans=pol.lead_scans, + trigger_reasons=tuple(reasons), + scattering_angles=scat, + operando_state=operando_dict, + ) + ) + + raw_candidates.sort(key=lambda t: (-t.priority_score, -t.precursor_score, t.track_id)) + selected = raw_candidates[: max(0, int(pol.max_triggers_per_scan))] + ranked: list[ZoomTarget] = [] + for rank_idx, tgt in enumerate(selected, start=1): + cooldown_map[tgt.root_track_id] = current_scan_idx + ranked.append( + ZoomTarget( + scan_idx=tgt.scan_idx, + scan_name=tgt.scan_name, + track_id=tgt.track_id, + root_track_id=tgt.root_track_id, + priority_rank=rank_idx, + priority_score=tgt.priority_score, + precursor_score=tgt.precursor_score, + persistence_scans=tgt.persistence_scans, + roi_subpeak_count=tgt.roi_subpeak_count, + anisotropy=tgt.anisotropy, + lineage_strain=tgt.lineage_strain, + strain_err=tgt.strain_err, + strain_rate=tgt.strain_rate, + assignment_margin=tgt.assignment_margin, + current_centroid=tgt.current_centroid, + predicted_setpoint=tgt.predicted_setpoint, + scan_half_widths=tgt.scan_half_widths, + centroid_err=tgt.centroid_err, + lead_scans=tgt.lead_scans, + trigger_reasons=tgt.trigger_reasons, + scattering_angles=tgt.scattering_angles, + operando_state=tgt.operando_state, + ) + ) + return ranked diff --git a/braggtrack/cli/_utils.py b/braggtrack/cli/_utils.py index 6e60042..04710db 100644 --- a/braggtrack/cli/_utils.py +++ b/braggtrack/cli/_utils.py @@ -55,7 +55,7 @@ def write_csv(path: Path, rows: list[dict[str, Any]]) -> None: with path.open("w", newline="") as fh: fh.write("") return - fieldnames = list(rows[0].keys()) + fieldnames = list(dict.fromkeys(k for r in rows for k in r)) with path.open("w", newline="") as fh: writer = csv.DictWriter(fh, fieldnames=fieldnames) writer.writeheader() diff --git a/braggtrack/cli/embed_dataset.py b/braggtrack/cli/embed_dataset.py index f1baec7..b629819 100644 --- a/braggtrack/cli/embed_dataset.py +++ b/braggtrack/cli/embed_dataset.py @@ -40,6 +40,7 @@ def build_parser() -> argparse.ArgumentParser: help="Embedding backend (mock needs no PyTorch; torch uses DINOv2 default or custom --model)", ) p.add_argument("--model", default=DEFAULT_DINO_MODEL, help="HF model id when backend=torch") + p.add_argument("--batch-size", type=int, default=32, help="Batch size for ViT MIP forward passes") p.add_argument( "--allow-synthetic-fallback", action="store_true", @@ -107,23 +108,25 @@ def main(argv: list[str] | None = None) -> int: return 1 label_ids: list[int] = [] - vectors: list[np.ndarray] = [] + mips_batch: list[tuple[np.ndarray, np.ndarray, np.ndarray]] = [] for row in rows: lid = int(row["label"]) mip_mu, mip_chi, mip_d = orthogonal_mips( crop_spot_cube(lazy_vol, labels_full, lid, row, margin=max(0, args.margin))[0] ) - vec = enc.embed(mip_mu, mip_chi, mip_d) label_ids.append(lid) - vectors.append(vec) - - if not vectors: - dim = 384 + mips_batch.append((mip_mu, mip_chi, mip_d)) + + if mips_batch: + if hasattr(enc, "embed_batch"): + mat = enc.embed_batch(mips_batch, batch_size=max(1, args.batch_size)) + else: + mat = np.stack([enc.embed(m0, m1, m2) for m0, m1, m2 in mips_batch], axis=0) + dim = int(mat.shape[1]) else: - dim = int(vectors[0].shape[0]) - - mat = np.stack(vectors, axis=0) if vectors else np.zeros((0, dim), dtype=np.float32) + dim = 1152 if resolved_backend == "torch" else 384 + mat = np.zeros((0, dim), dtype=np.float32) scan_out = outdir / name scan_out.mkdir(parents=True, exist_ok=True) np.savez_compressed( diff --git a/braggtrack/cli/report_dataset.py b/braggtrack/cli/report_dataset.py index f6ac4fc..65d0d6f 100644 --- a/braggtrack/cli/report_dataset.py +++ b/braggtrack/cli/report_dataset.py @@ -12,6 +12,7 @@ generate_html_report, plot_kinematics_dashboard, plot_lineage_dag, + plot_operando_strain_and_events, plot_precursor_timeline, ) @@ -29,6 +30,11 @@ def build_parser() -> argparse.ArgumentParser: default=None, help="Optional raw HDF5 dataset root for embedding 3-axis MIP spot thumbnails", ) + parser.add_argument( + "--operando-log", + default=None, + help="Optional external operando CSV/TSV/Biologic .mpt log for synchronized stimulus plots", + ) parser.add_argument( "--outdir", default=None, @@ -76,6 +82,7 @@ def main(argv: list[str] | None = None) -> int: in_root, out_root / "report.html", dataset_root=args.dataset_root, + operando_log=args.operando_log, max_mip_tracks=max(0, args.max_mip_tracks), ) @@ -122,6 +129,32 @@ def main(argv: list[str] | None = None) -> int: ) plt.close(fig_prec) figures["precursor_timeline"] = str((fig_dir / "precursor_timeline.png").resolve()) + + # Synchronized operando stimulus + lineage strain figure if log or saved JSON exists + stim_rows: list[dict[str, Any]] = [] + if args.operando_log: + from braggtrack.io import load_operando_log, synchronize_to_scans + + n_scans_est = max((int(float(r["scan_idx"])) for r in track_rows), default=0) + 1 + stim_rows = [ + p.to_dict() for p in synchronize_to_scans(load_operando_log(args.operando_log), n_scans_est) + ] + elif (in_root / "operando_stimulus.json").exists(): + raw_stim = json.loads((in_root / "operando_stimulus.json").read_text()) + if isinstance(raw_stim, dict) and isinstance(raw_stim.get("scans"), list): + stim_rows = raw_stim["scans"] + + if stim_rows: + fig_op, _ = plot_operando_strain_and_events( + track_rows, + stim_rows, + events=event_rows, + precursor_observations=prec_obs_rows, + calibrated=calibrated, + save_path=fig_dir / "operando_strain_and_events.png", + ) + plt.close(fig_op) + figures["operando_strain_and_events"] = str((fig_dir / "operando_strain_and_events.png").resolve()) except ImportError: pass diff --git a/braggtrack/cli/run_pipeline.py b/braggtrack/cli/run_pipeline.py index 756f5b1..95adcaf 100644 --- a/braggtrack/cli/run_pipeline.py +++ b/braggtrack/cli/run_pipeline.py @@ -51,6 +51,11 @@ def build_parser() -> argparse.ArgumentParser: parser.add_argument( "--detector-json", default=None, help="Optional DetectorGeometry JSON path for (2theta, eta, Q)" ) + parser.add_argument( + "--operando-log", + default=None, + help="Optional external operando CSV/TSV/Biologic .mpt log to synchronize with diffraction scans", + ) parser.add_argument("--cost-alpha", type=float, default=1.0, help="Geometry weight in semantic cost") parser.add_argument("--cost-beta", type=float, default=0.25, help="Semantic embedding weight in tracking cost") parser.add_argument("--max-gap", type=int, default=0, help="Max missing intermediate scans to bridge (0 disables)") @@ -114,6 +119,7 @@ def _merge_config_overrides(args: argparse.Namespace) -> dict[str, Any]: "smooth_window": args.smooth_window, "calibration_json": args.calibration_json, "detector_json": args.detector_json, + "operando_log": args.operando_log, "cost_alpha": args.cost_alpha, "cost_beta": args.cost_beta, "max_gap": args.max_gap, @@ -170,6 +176,23 @@ def main(argv: list[str] | None = None) -> int: print(json.dumps({"error": "Dataset validation failed", "issues": val_payload["issues"]})) return 1 + # Optional external operando stimulus synchronization + stim_points = None + if cfg.get("operando_log"): + from braggtrack.io import load_operando_log, synchronize_to_scans + + op_log = load_operando_log(str(cfg["operando_log"])) + stim_points = synchronize_to_scans(op_log, sequence) + (outdir / "operando_stimulus.json").write_text( + json.dumps( + { + "source_path": str(Path(str(cfg["operando_log"])).resolve()), + "scans": [pt.to_dict() for pt in stim_points], + }, + indent=2, + ) + ) + # Compute input checksums discovered = discover_operando_scans(root) input_files = [ @@ -299,6 +322,15 @@ def main(argv: list[str] | None = None) -> int: if rc_evt != 0: return rc_evt + if stim_points is not None: + from braggtrack.cli._utils import load_feature_csv, write_csv + from braggtrack.io import annotate_tracks_with_stimulus + + for target_csv in (trk_dir / "tracks.csv", evt_dir / "tracks.csv", trk_dir / "kinematics.csv"): + if target_csv.exists() and target_csv.stat().st_size > 0: + enriched_rows = annotate_tracks_with_stimulus(load_feature_csv(target_csv), stim_points) + write_csv(target_csv, enriched_rows) + if cfg.get("export_nexus") and cfg.get("detect_events"): from braggtrack.io import DetectorGeometry, export_nexus_process @@ -323,6 +355,9 @@ def _build_manifest(cur_total_sec: float) -> dict[str, Any]: "total_duration_sec": cur_total_sec, "artifacts": { "validation_summary": str((outdir / "validation_summary.json").resolve()), + "operando_stimulus": str((outdir / "operando_stimulus.json").resolve()) + if stim_points is not None + else None, "segmentation_summary": str((seg_dir / "segmentation_summary.json").resolve()), "embedding_summary": str((emb_dir / "embedding_summary.json").resolve()) if need_embed else None, "tracking_summary": str((trk_dir / "tracking_summary.json").resolve()), @@ -343,7 +378,10 @@ def _build_manifest(cur_total_sec: float) -> dict[str, Any]: # 6. Optional interactive HTML & static figure report if cfg.get("report"): t0 = time.perf_counter() - rc_rep = report_dataset.main([str(outdir), "--dataset-root", str(root), "--outdir", str(rep_dir)]) + rep_argv = [str(outdir), "--dataset-root", str(root), "--outdir", str(rep_dir)] + if cfg.get("operando_log"): + rep_argv.extend(["--operando-log", str(cfg["operando_log"])]) + rc_rep = report_dataset.main(rep_argv) timings["report"] = round(time.perf_counter() - t0, 4) if rc_rep != 0: return rc_rep diff --git a/braggtrack/cli/watch_autonomous.py b/braggtrack/cli/watch_autonomous.py new file mode 100644 index 0000000..605a223 --- /dev/null +++ b/braggtrack/cli/watch_autonomous.py @@ -0,0 +1,220 @@ +"""Autonomous DFXM "Scout-and-Zoom" beamline watcher and causal replay CLI.""" + +from __future__ import annotations + +import argparse +import json +import time +from pathlib import Path + +from braggtrack.autonomous import ( + CausalStreamingTracker, + ZoomTriggerPolicy, + evaluate_causal_replay, +) +from braggtrack.io import ( + AxisCalibration, + BeamlineAdapter, + DetectorGeometry, + load_operando_log, + resolve_dataset_root, + synchronize_to_scans, +) +from braggtrack.semantic import DEFAULT_DINO_MODEL +from braggtrack.tracking.precursors import PrecursorConfig + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "root", + nargs="?", + default=None, + help="Dataset root containing scan subdirectories (default: data/sample_operando if present, else .)", + ) + parser.add_argument( + "--mode", + choices=("replay", "watch"), + default="replay", + help="'replay' benchmarks causal closed-loop triggers on an existing sequence; 'watch' polls for new scans", + ) + parser.add_argument("--outdir", default="artifacts/autonomous", help="Output directory for zoom triggers & logs") + parser.add_argument( + "--backend", + choices=("auto", "mock", "torch"), + default="auto", + help="Semantic/patch encoder backend (auto, mock, or torch)", + ) + parser.add_argument("--model", default=DEFAULT_DINO_MODEL, help="HuggingFace model ID when backend=torch") + parser.add_argument( + "--operando-log", + default=None, + help="Optional CSV/TSV/Biologic .mpt operando log to attach potential & dQ/dV to zoom triggers", + ) + parser.add_argument("--calibration-json", default=None, help="Optional AxisCalibration JSON file") + parser.add_argument("--detector-json", default=None, help="Optional DetectorGeometry JSON file") + parser.add_argument("--min-precursor-score", type=float, default=0.40, help="Precursor trigger threshold") + parser.add_argument("--min-persistence", type=int, default=2, help="Required contiguous precursor scans") + parser.add_argument("--cooldown-scans", type=int, default=3, help="Per-lineage cooldown scans after firing") + parser.add_argument("--max-triggers-per-scan", type=int, default=2, help="Maximum zoom targets emitted per scan") + parser.add_argument("--lead-scans", type=float, default=1.0, help="Velocity extrapolation lead (in scan steps)") + parser.add_argument("--window-sigma", type=float, default=3.5, help="Scan half-width sigma multiplier") + parser.add_argument( + "--zoom-budget", + type=int, + default=None, + help="Optional cap on total zoom acquisitions during --mode replay baseline comparison", + ) + parser.add_argument("--poll-interval", type=float, default=0.5, help="Directory poll interval (s) in --mode watch") + parser.add_argument( + "--max-scans", + type=int, + default=None, + help="Stop watching after ingesting N scans (useful for bounded live runs or tests)", + ) + parser.add_argument( + "--max-idle-polls", + type=int, + default=20, + help="Stop --mode watch after this many consecutive polls with no new scans (0 = run indefinitely)", + ) + return parser + + +def _load_optional_calibration(path_str: str | None) -> AxisCalibration | None: + if not path_str: + return None + raw = json.loads(Path(path_str).read_text(encoding="utf-8")) + return AxisCalibration.from_dict(raw) + + +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) + root = resolve_dataset_root(args.root) + outdir = Path(args.outdir) + outdir.mkdir(parents=True, exist_ok=True) + + calibration = _load_optional_calibration(args.calibration_json) + detector = DetectorGeometry.from_json(args.detector_json) if args.detector_json else None + prec_cfg = PrecursorConfig( + score_threshold=float(args.min_precursor_score), + min_persistence=int(args.min_persistence), + ) + policy = ZoomTriggerPolicy( + min_precursor_score=float(args.min_precursor_score), + min_persistence=int(args.min_persistence), + cooldown_scans=int(args.cooldown_scans), + max_triggers_per_scan=int(args.max_triggers_per_scan), + lead_scans=float(args.lead_scans), + window_sigma=float(args.window_sigma), + ) + + triggers_jsonl = outdir / "zoom_triggers.jsonl" + steps_json = outdir / "autonomous_steps.json" + + if args.mode == "replay": + seq = BeamlineAdapter(root).build_sequence() + if not seq.scans: + raise FileNotFoundError(f"No valid scan folders discovered under {root}") + scan_files = [sc.file_path for sc in seq.scans] + scan_names = [sc.scan_name for sc in seq.scans] + if args.max_scans is not None: + scan_files = scan_files[: int(args.max_scans)] + scan_names = scan_names[: int(args.max_scans)] + + stimuli = None + if args.operando_log: + op_log = load_operando_log(args.operando_log) + stimuli = synchronize_to_scans(op_log, seq)[: len(scan_files)] + + bench = evaluate_causal_replay( + scan_files, + scan_names=scan_names, + stimuli=stimuli, + calibration=calibration, + detector=detector, + backend=args.backend, + precursor_config=prec_cfg, + trigger_policy=policy, + zoom_budget=args.zoom_budget, + ) + + with triggers_jsonl.open("w", encoding="utf-8") as fh: + for tgt in bench.zoom_targets: + fh.write(json.dumps(tgt.to_bliss_command()) + "\n") + + steps_json.write_text(json.dumps([s.to_dict() for s in bench.steps], indent=2), encoding="utf-8") + summary_path = outdir / "replay_summary.json" + summary_path.write_text(json.dumps(bench.to_dict(), indent=2), encoding="utf-8") + + bt_m = bench.policy_comparison["braggtrack_autonomous"] + print( + f"[braggtrack-watch:replay] Processed {bench.n_scans} scans " + f"(mean {bench.mean_step_latency_sec:.3f}s/scan) -> {len(bench.zoom_targets)} zoom trigger(s)" + ) + print( + f" Fracture capture recall={bt_m.fracture_capture_recall:.2f}, " + f"precision={bt_m.fracture_capture_precision:.2f}, " + f"mean lead={bt_m.mean_lead_scans_before_split:.2f} scans, " + f"next-scan hit rate={bt_m.setpoint_hit_rate_next_scan:.2f}" + ) + return 0 + + # Live directory polling mode ("watch") + tracker = CausalStreamingTracker( + backend=args.backend, + model_name=args.model, + calibration=calibration, + detector=detector, + precursor_config=prec_cfg, + trigger_policy=policy, + ) + seen_files: set[Path] = set() + step_dicts: list[dict] = [] + idle_polls = 0 + + triggers_jsonl.write_text("", encoding="utf-8") + while True: + seq = BeamlineAdapter(root).build_sequence() + stim_by_name = {} + if args.operando_log and seq.scans: + op_log = load_operando_log(args.operando_log) + for sp in synchronize_to_scans(op_log, seq): + stim_by_name[sp.scan_name] = sp + + new_scans = [sc for sc in seq.scans if sc.file_path.resolve() not in seen_files] + if new_scans: + idle_polls = 0 + for sc in new_scans: + seen_files.add(sc.file_path.resolve()) + ts_iso = sc.start_time.isoformat() if sc.start_time is not None else None + res = tracker.step( + sc.file_path, + scan_name=sc.scan_name, + timestamp=ts_iso, + stimulus=stim_by_name.get(sc.scan_name), + ) + step_dicts.append(res.to_dict()) + if res.zoom_targets: + with triggers_jsonl.open("a", encoding="utf-8") as fh: + for tgt in res.zoom_targets: + fh.write(json.dumps(tgt.to_bliss_command()) + "\n") + fh.flush() + steps_json.write_text(json.dumps(step_dicts, indent=2), encoding="utf-8") + print( + f"[braggtrack-watch:live] scan={res.scan_name} spots={res.n_spots} " + f"zoom_triggers={len(res.zoom_targets)} ({res.step_latency_sec:.3f}s)" + ) + if args.max_scans is not None and tracker.n_scans_processed >= int(args.max_scans): + return 0 + else: + idle_polls += 1 + if args.max_idle_polls > 0 and idle_polls >= int(args.max_idle_polls): + break + time.sleep(max(0.01, float(args.poll_interval))) + + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/braggtrack/io/__init__.py b/braggtrack/io/__init__.py index 9a37a54..3b062f3 100644 --- a/braggtrack/io/__init__.py +++ b/braggtrack/io/__init__.py @@ -14,6 +14,13 @@ load_primary_volume, summarize_hdf5_tree, ) +from .operando_log import ( + OperandoStimulusLog, + ScanStimulusPoint, + annotate_tracks_with_stimulus, + load_operando_log, + synchronize_to_scans, +) from .paths import default_dataset_root, resolve_dataset_root, sample_operando_root from .validation import ValidationIssue, validate_sequence @@ -26,9 +33,12 @@ "IMAGED11_COLUMNS", "LazyVolume", "MissingH5DependencyError", + "OperandoStimulusLog", + "ScanStimulusPoint", "ScanVolumeMeta", "ValidationIssue", "annotate_crystallographic_columns", + "annotate_tracks_with_stimulus", "default_dataset_root", "discover_operando_scans", "discover_primary_volume_path", @@ -36,6 +46,7 @@ "export_nexus_process", "extract_axis_calibration", "extract_scan_metadata", + "load_operando_log", "load_primary_volume", "open_lazy_volume", "otsu_threshold_chunked", @@ -43,5 +54,6 @@ "resolve_dataset_root", "sample_operando_root", "summarize_hdf5_tree", + "synchronize_to_scans", "validate_sequence", ] diff --git a/braggtrack/io/nexus.py b/braggtrack/io/nexus.py index e85f604..a2d2e6b 100644 --- a/braggtrack/io/nexus.py +++ b/braggtrack/io/nexus.py @@ -15,6 +15,9 @@ "/entry1/data/data", "/entry_0000/ESRF-ID03/pco_nf/data", "/entry_0000/data/data", + "/entry/darfix/data", + "/entry_0000/darfix/data", + "/entry/process/darfix/results/data", "/entry/instrument/detector/data", "/entry1/instrument/detector/data", ) @@ -66,6 +69,22 @@ def _decode_value(value: Any) -> Any: return value +def _decode_str_list(value: Any) -> list[str]: + if value is None: + return [] + if isinstance(value, (bytes, str)): + s = _decode_value(value) + return [s] if isinstance(s, str) and s.strip() else [] + if hasattr(value, "__iter__"): + out: list[str] = [] + for item in value: + s = _decode_value(item) + if isinstance(s, str) and s.strip(): + out.append(s) + return out + return [] + + def _candidate_entries(handle: Any, h5py: Any) -> list[str]: seen: list[str] = [] @@ -133,12 +152,21 @@ def extract_scan_metadata(path: str | Path) -> dict[str, Any]: return metadata +_MOTOR_AXIS_SYNONYMS: dict[str, tuple[str, ...]] = { + "mu": ("mu", "omega", "obx", "rocking"), + "chi": ("chi", "phi", "oby"), + "d": ("d", "obpitch", "twotheta", "two_theta", "2theta", "tth"), +} + + def extract_axis_calibration(path: str | Path) -> AxisCalibration: """Extract linear ``(mu, chi, d)`` calibration from a NeXus/HDF5 file if present. - Checks ``/entry*/calibration`` attributes/datasets or 1D coordinate arrays - ``mu``, ``chi``, and ``d``. Returns an uncalibrated identity - :class:`AxisCalibration` when physical axis scales are absent. + Probes: + 1. Explicit ``/entry*/calibration`` groups. + 2. NeXus ``NXdata`` ``@axes`` attributes on the primary 3D dataset's parent group (e.g. ``darfix``). + 3. 1D coordinate arrays under ``NXentry``, ``data``, ``measurement``, or ESRF BLISS + ``instrument/positioners/{mu, chi, obpitch, twotheta, d}``. """ import numpy as np @@ -165,16 +193,50 @@ def extract_axis_calibration(path: str | Path) -> AxisCalibration: if raw: return AxisCalibration.from_dict(raw) - # Check 1D axis arrays under NXentry, NXdata, or the primary 3D dataset's parent group. + # Check NeXus NXdata @axes attribute on parent group (e.g. darfix NXdata cubes: (z=mu, y=d/2theta, x=chi)) + if vol_parent and vol_parent != "/" and vol_parent in handle: + pgrp = handle[vol_parent] + nx_axes = _decode_str_list(pgrp.attrs.get("axes")) + if len(nx_axes) == 3: + nx_found: dict[str, tuple[float, float]] = {} + # Voxel order (z, y, x) -> BraggTrack (mu, d, chi) + for dim_idx, target_axis in ((0, "mu"), (1, "d"), (2, "chi")): + ax_ds_name = nx_axes[dim_idx] + if ax_ds_name != "." and ax_ds_name in pgrp and isinstance(pgrp[ax_ds_name], h5py.Dataset): + arr = np.asarray(pgrp[ax_ds_name][()], dtype=np.float64).ravel() + if arr.size >= 2 and float(arr[-1] - arr[0]) != 0.0: + nx_found[target_axis] = (float(arr[0]), float((arr[-1] - arr[0]) / (arr.size - 1))) + if nx_found: + return AxisCalibration( + mu_origin=nx_found.get("mu", (0.0, 1.0))[0], + mu_step=nx_found.get("mu", (0.0, 1.0))[1], + chi_origin=nx_found.get("chi", (0.0, 1.0))[0], + chi_step=nx_found.get("chi", (0.0, 1.0))[1], + d_origin=nx_found.get("d", (0.0, 1.0))[0], + d_step=nx_found.get("d", (0.0, 1.0))[1], + calibrated=True, + ) + + for e in entries: + # Check 1D axis/motor arrays under NXentry, NXdata, measurement, or ESRF BLISS instrument/positioners axes_found: dict[str, tuple[float, float]] = {} - for axis_name in ("mu", "chi", "d"): - search_paths = [f"{e}/{axis_name}", f"{e}/data/{axis_name}", f"{e}/measurement/{axis_name}"] - if vol_parent and vol_parent != "/": - search_paths.append(f"{vol_parent.rstrip('/')}/{axis_name}") + for axis_name, synonyms in _MOTOR_AXIS_SYNONYMS.items(): + search_paths: list[str] = [] + for syn in synonyms: + search_paths.extend( + [ + f"{e}/{syn}", + f"{e}/data/{syn}", + f"{e}/measurement/{syn}", + f"{e}/instrument/positioners/{syn}", + ] + ) + if vol_parent and vol_parent != "/": + search_paths.append(f"{vol_parent.rstrip('/')}/{syn}") for sub in search_paths: if sub in handle and isinstance(handle[sub], h5py.Dataset): arr = np.asarray(handle[sub][()], dtype=np.float64).ravel() - if arr.size >= 2: + if arr.size >= 2 and float(arr[-1] - arr[0]) != 0.0: axes_found[axis_name] = (float(arr[0]), float((arr[-1] - arr[0]) / (arr.size - 1))) break if axes_found: @@ -209,6 +271,19 @@ def _resolve_volume_dataset( return "/" + key.lstrip("/") if candidates is None and auto_discover: + # Check NeXus @default -> NXdata @signal chain first (used by darfix / silx / Ewoks) + for e in _candidate_entries(handle, h5py): + eg = handle[e] + def_data = _decode_value(eg.attrs.get("default")) + if isinstance(def_data, str) and def_data.strip(): + dgrp_path = f"{e.rstrip('/')}/{def_data.strip('/')}" + if dgrp_path in handle and isinstance(handle[dgrp_path], h5py.Group): + sig = _decode_value(handle[dgrp_path].attrs.get("signal")) + if isinstance(sig, str) and sig in handle[dgrp_path]: + sig_ds = handle[dgrp_path][sig] + if isinstance(sig_ds, h5py.Dataset) and sig_ds.ndim == 3: + return f"{dgrp_path}/{sig}" + discovered: list[tuple[str, tuple[int, ...]]] = [] def _visit(name: str, obj: Any) -> None: diff --git a/braggtrack/io/operando_log.py b/braggtrack/io/operando_log.py new file mode 100644 index 0000000..4034070 --- /dev/null +++ b/braggtrack/io/operando_log.py @@ -0,0 +1,453 @@ +"""Operando external stimulus log ingestion and scan synchronization. + +Supports generic CSV/TSV potentiostat/load/thermal logs as well as Biologic +EC-Lab ``.mpt`` ASCII exports (``Nb header lines : N``, ``time/s``, ``Ewe/V``, +``/mA``, ``(Q-Qo)/mA.h``, ``cycle number``). +""" + +from __future__ import annotations + +import csv +import math +import re +from dataclasses import dataclass +from datetime import datetime, timezone +from pathlib import Path +from typing import TYPE_CHECKING, Any + +import numpy as np + +if TYPE_CHECKING: + from .models import ExperimentSequence + + +_COL_ALIASES: dict[str, tuple[str, ...]] = { + "scan_idx": ("scan_idx", "scan", "scan_index", "frame", "frame_idx"), + "timestamp": ("timestamp", "iso_time", "datetime", "date_time", "utc_time", "abs_time"), + "uts": ("uts", "epoch", "epoch_s", "unix_time"), + "time_s": ("time_s", "elapsed_s", "time/s", "time", "t_s", "seconds"), + "voltage_v": ("voltage_v", "voltage", "ewe/v", "/v", "ecell/v", "v_cell", "potential_v"), + "current_ma": ("current_ma", "current", "i/ma", "/ma", "current/ma"), + "capacity_mah_g": ( + "capacity_mah_g", + "specific_capacity", + "capacity", + "q_mah_g", + "(q-qo)/ma.h", + "q charge/ma.h", + "q discharge/ma.h", + "dq/ma.h", + ), + "dq_dv": ("dq_dv", "dq/dv", "dqdv"), + "cycle": ("cycle", "cycle_number", "cycle number", "half_cycle"), + "stress_mpa": ("stress_mpa", "stress", "load_mpa", "sigma_mpa"), + "temperature_c": ("temperature_c", "temperature", "temp_c", "t_degc", "temperature/°c", "temperature/c"), +} + + +@dataclass(frozen=True) +class OperandoStimulusLog: + """Time-series external operando stimulus channels (electrochemistry, load, temperature).""" + + time_s: np.ndarray + scan_idx: np.ndarray | None = None + epoch_s: np.ndarray | None = None + voltage_v: np.ndarray | None = None + current_ma: np.ndarray | None = None + capacity_mah_g: np.ndarray | None = None + dq_dv: np.ndarray | None = None + cycle: np.ndarray | None = None + stress_mpa: np.ndarray | None = None + temperature_c: np.ndarray | None = None + source_path: str | None = None + + @property + def n_points(self) -> int: + return int(len(self.time_s)) + + +@dataclass(frozen=True) +class ScanStimulusPoint: + """Synchronized external stimulus state evaluated at one diffraction scan.""" + + scan_idx: int + scan_name: str + elapsed_s: float + timestamp: str | None = None + voltage_v: float | None = None + current_ma: float | None = None + capacity_mah_g: float | None = None + dq_dv: float | None = None + cycle: int | None = None + stress_mpa: float | None = None + temperature_c: float | None = None + + def to_dict(self) -> dict[str, Any]: + return { + "scan_idx": self.scan_idx, + "scan_name": self.scan_name, + "elapsed_s": round(float(self.elapsed_s), 4), + "timestamp": self.timestamp, + "voltage_v": round(float(self.voltage_v), 5) if self.voltage_v is not None else None, + "current_ma": round(float(self.current_ma), 5) if self.current_ma is not None else None, + "capacity_mah_g": round(float(self.capacity_mah_g), 4) if self.capacity_mah_g is not None else None, + "dq_dv": round(float(self.dq_dv), 4) if self.dq_dv is not None else None, + "cycle": int(self.cycle) if self.cycle is not None else None, + "stress_mpa": round(float(self.stress_mpa), 4) if self.stress_mpa is not None else None, + "temperature_c": round(float(self.temperature_c), 3) if self.temperature_c is not None else None, + } + + +def _norm_col(name: str) -> str: + return re.sub(r"\s+", " ", name.strip().lower()) + + +def _match_columns(headers: list[str]) -> dict[str, str]: + norm_to_orig = {_norm_col(h): h for h in headers if h is not None} + matched: dict[str, str] = {} + for canonical, aliases in _COL_ALIASES.items(): + for alias in aliases: + if alias in norm_to_orig: + matched[canonical] = norm_to_orig[alias] + break + return matched + + +def _parse_iso_to_epoch(val: str) -> float | None: + s = val.strip() + if not s: + return None + if s.endswith("Z"): + s = s[:-1] + "+00:00" + try: + dt = datetime.fromisoformat(s) + except ValueError: + for fmt in ("%m/%d/%Y %H:%M:%S.%f", "%m/%d/%Y %H:%M:%S", "%Y/%m/%d %H:%M:%S"): + try: + dt = datetime.strptime(s, fmt) + break + except ValueError: + continue + else: + return None + if dt.tzinfo is None: + dt = dt.replace(tzinfo=timezone.utc) + return float(dt.timestamp()) + + +def _parse_float(val: str | None) -> float: + if val is None: + return math.nan + s = val.strip().replace(",", ".") if "," in val and "." not in val else val.strip() + if not s: + return math.nan + try: + return float(s) + except ValueError: + return math.nan + + +def _compute_regularized_dq_dv( + voltage_v: np.ndarray, + capacity: np.ndarray, + *, + min_dv: float = 1.5e-3, +) -> np.ndarray: + """Compute causal backward-difference ``dQ/dV`` with mild voltage-step regularization.""" + n = len(voltage_v) + out = np.zeros(n, dtype=np.float64) + if n < 2: + return out + + # Smooth voltage slightly with a 3-point causal moving average to suppress potentiostat bit noise + v_smooth = np.empty(n, dtype=np.float64) + q_smooth = np.empty(n, dtype=np.float64) + for i in range(n): + lo = max(0, i - 2) + v_smooth[i] = float(np.nanmean(voltage_v[lo : i + 1])) + q_smooth[i] = float(np.nanmean(capacity[lo : i + 1])) + + for i in range(1, n): + dv = v_smooth[i] - v_smooth[i - 1] + dq = abs(q_smooth[i] - q_smooth[i - 1]) + if abs(dv) >= min_dv and math.isfinite(dv) and math.isfinite(dq): + out[i] = math.copysign(dq / abs(dv), dv) + else: + out[i] = out[i - 1] + out[0] = out[1] + return out + + +def load_operando_log(path: str | Path) -> OperandoStimulusLog: + """Load an external operando CSV, TSV, or Biologic EC-Lab ``.mpt`` file.""" + file_path = Path(path) + text = file_path.read_text(encoding="utf-8", errors="replace") + lines = text.splitlines() + if not lines: + raise ValueError(f"Operando stimulus log '{file_path}' is empty.") + + # Detect Biologic EC-Lab ASCII header ("Nb header lines : N") + header_idx = 0 + for line in lines[:30]: + m = re.match(r"^\s*Nb\s+header\s+lines\s*:\s*(\d+)", line, flags=re.IGNORECASE) + if m: + header_idx = max(0, int(m.group(1)) - 1) + break + else: + # Skip leading comment lines starting with '#' + while header_idx < len(lines) and (not lines[header_idx].strip() or lines[header_idx].lstrip().startswith("#")): + header_idx += 1 + + if header_idx >= len(lines): + raise ValueError(f"Could not locate table header in operando log '{file_path}'.") + + body_lines = [ln for ln in lines[header_idx:] if ln.strip()] + header_line = body_lines[0] + delimiter = "\t" if "\t" in header_line else (";" if ";" in header_line and "," not in header_line else ",") + + reader = csv.DictReader(body_lines, delimiter=delimiter) + if not reader.fieldnames: + raise ValueError(f"No column headers found in operando log '{file_path}'.") + + col_map = _match_columns(list(reader.fieldnames)) + raw_rows = list(reader) + if not raw_rows: + raise ValueError(f"Operando stimulus log '{file_path}' contains zero data rows.") + + n = len(raw_rows) + + def _extract_num(canon: str) -> np.ndarray | None: + col = col_map.get(canon) + if col is None: + return None + arr = np.array([_parse_float(r.get(col)) for r in raw_rows], dtype=np.float64) + if np.all(np.isnan(arr)): + return None + return arr + + scan_arr = _extract_num("scan_idx") + time_arr = _extract_num("time_s") + uts_arr = _extract_num("uts") + + epoch_arr: np.ndarray | None = uts_arr + if epoch_arr is None and "timestamp" in col_map: + ts_col = col_map["timestamp"] + parsed_ep = [_parse_iso_to_epoch(str(r.get(ts_col, ""))) for r in raw_rows] + if any(x is not None for x in parsed_ep): + epoch_arr = np.array([x if x is not None else math.nan for x in parsed_ep], dtype=np.float64) + + if time_arr is None: + if epoch_arr is not None: + valid0 = float(epoch_arr[np.isfinite(epoch_arr)][0]) + time_arr = epoch_arr - valid0 + elif scan_arr is not None: + time_arr = scan_arr.astype(np.float64) + else: + time_arr = np.arange(n, dtype=np.float64) + + voltage_v = _extract_num("voltage_v") + current_ma = _extract_num("current_ma") + capacity = _extract_num("capacity_mah_g") + dq_dv = _extract_num("dq_dv") + cycle = _extract_num("cycle") + stress_mpa = _extract_num("stress_mpa") + temperature_c = _extract_num("temperature_c") + + # Derive Coulombic capacity (mAh) when current_mA & time_s exist without explicit capacity column + if capacity is None and current_ma is not None and len(time_arr) >= 2: + dt_h = np.diff(time_arr, prepend=time_arr[0]) / 3600.0 + dt_h = np.where(np.isfinite(dt_h) & (dt_h > 0.0), dt_h, 0.0) + i_clean = np.where(np.isfinite(current_ma), np.abs(current_ma), 0.0) + capacity = np.cumsum(i_clean * dt_h) + + if dq_dv is None and voltage_v is not None and capacity is not None: + dq_dv = _compute_regularized_dq_dv(voltage_v, capacity) + + return OperandoStimulusLog( + time_s=time_arr, + scan_idx=scan_arr, + epoch_s=epoch_arr, + voltage_v=voltage_v, + current_ma=current_ma, + capacity_mah_g=capacity, + dq_dv=dq_dv, + cycle=cycle, + stress_mpa=stress_mpa, + temperature_c=temperature_c, + source_path=str(file_path), + ) + + +def _interp_optional(x_target: np.ndarray, x_src: np.ndarray, y_src: np.ndarray | None) -> np.ndarray | None: + if y_src is None: + return None + mask = np.isfinite(x_src) & np.isfinite(y_src) + if int(np.sum(mask)) == 0: + return None + xs = x_src[mask] + ys = y_src[mask] + order = np.argsort(xs, kind="mergesort") + xs_sorted = xs[order] + ys_sorted = ys[order] + return np.interp(x_target, xs_sorted, ys_sorted) + + +def synchronize_to_scans( + log: OperandoStimulusLog, + sequence_or_count: ExperimentSequence | int, + *, + start_offset_s: float = 0.0, + scan_cadence_s: float | None = None, +) -> list[ScanStimulusPoint]: + """Interpolate external stimulus channels onto each diffraction scan's midpoint time or index.""" + if isinstance(sequence_or_count, int): + n_scans = max(0, sequence_or_count) + scan_names = [f"scan{i + 1:04d}" for i in range(n_scans)] + scan_epochs: list[float | None] = [None] * n_scans + scan_isos: list[str | None] = [None] * n_scans + else: + scans = sequence_or_count.scans + n_scans = len(scans) + scan_names = [s.scan_name for s in scans] + scan_epochs = [] + scan_isos = [] + for s in scans: + if s.start_time is not None and s.end_time is not None: + st = s.start_time if s.start_time.tzinfo else s.start_time.replace(tzinfo=timezone.utc) + et = s.end_time if s.end_time.tzinfo else s.end_time.replace(tzinfo=timezone.utc) + mid_ep = 0.5 * (st.timestamp() + et.timestamp()) + scan_epochs.append(float(mid_ep)) + scan_isos.append(st.isoformat()) + elif s.start_time is not None: + st = s.start_time if s.start_time.tzinfo else s.start_time.replace(tzinfo=timezone.utc) + scan_epochs.append(float(st.timestamp())) + scan_isos.append(st.isoformat()) + else: + scan_epochs.append(None) + scan_isos.append(None) + + if n_scans == 0: + return [] + + idx_vec = np.arange(n_scans, dtype=np.float64) + + # Choose synchronization coordinate: explicit scan_idx > absolute epoch > elapsed seconds + if log.scan_idx is not None and np.any(np.isfinite(log.scan_idx)): + x_src = log.scan_idx + x_query = idx_vec + elapsed_s = _interp_optional(x_query, x_src, log.time_s) + if elapsed_s is None: + elapsed_s = idx_vec * (scan_cadence_s or 60.0) + elif log.epoch_s is not None and all(ep is not None for ep in scan_epochs): + x_src = log.epoch_s + x_query = np.array([float(ep) for ep in scan_epochs if ep is not None], dtype=np.float64) + elapsed_s = x_query - x_query[0] + elif all(ep is not None for ep in scan_epochs): + ep_arr = np.array([float(ep) for ep in scan_epochs if ep is not None], dtype=np.float64) + elapsed_s = (ep_arr - ep_arr[0]) + start_offset_s + x_src = log.time_s + x_query = elapsed_s + else: + if scan_cadence_s is not None: + elapsed_s = start_offset_s + idx_vec * scan_cadence_s + else: + finite_t = log.time_s[np.isfinite(log.time_s)] + t_min = float(finite_t[0]) if len(finite_t) else 0.0 + t_max = float(finite_t[-1]) if len(finite_t) else float(max(0, n_scans - 1) * 60.0) + elapsed_s = np.linspace(t_min, t_max, n_scans) if n_scans > 1 else np.array([t_min]) + x_src = log.time_s + x_query = elapsed_s + + v_interp = _interp_optional(x_query, x_src, log.voltage_v) + i_interp = _interp_optional(x_query, x_src, log.current_ma) + q_interp = _interp_optional(x_query, x_src, log.capacity_mah_g) + dqdv_interp = _interp_optional(x_query, x_src, log.dq_dv) + cyc_interp = _interp_optional(x_query, x_src, log.cycle) + sig_interp = _interp_optional(x_query, x_src, log.stress_mpa) + tmp_interp = _interp_optional(x_query, x_src, log.temperature_c) + + points: list[ScanStimulusPoint] = [] + for k in range(n_scans): + points.append( + ScanStimulusPoint( + scan_idx=k, + scan_name=scan_names[k], + elapsed_s=float(elapsed_s[k]), + timestamp=scan_isos[k], + voltage_v=float(v_interp[k]) if v_interp is not None else None, + current_ma=float(i_interp[k]) if i_interp is not None else None, + capacity_mah_g=float(q_interp[k]) if q_interp is not None else None, + dq_dv=float(dqdv_interp[k]) if dqdv_interp is not None else None, + cycle=int(round(float(cyc_interp[k]))) if cyc_interp is not None else None, + stress_mpa=float(sig_interp[k]) if sig_interp is not None else None, + temperature_c=float(tmp_interp[k]) if tmp_interp is not None else None, + ) + ) + return points + + +def annotate_tracks_with_stimulus( + track_rows: list[dict[str, Any]], + scan_stimuli: list[ScanStimulusPoint], +) -> list[dict[str, Any]]: + """Return shallow-copied track rows enriched with synchronized stimulus and ``d_strain_d_v``.""" + if not track_rows: + return [] + + stim_by_scan = {pt.scan_idx: pt for pt in scan_stimuli} + enriched: list[dict[str, Any]] = [] + prev_by_tid: dict[int, tuple[float | None, float | None]] = {} + + computed_strain_by_key: dict[tuple[int, int], float] = {} + if "lineage_strain" not in track_rows[0] and "strain" not in track_rows[0] and "centroid_d" in track_rows[0]: + from braggtrack.tracking.kinematics import compute_grain_kinematics + + for gk in compute_grain_kinematics(track_rows): + lin = gk.lineage_strain if len(gk.lineage_strain) else gk.strain + for idx_s, s_i in enumerate(gk.scan_indices): + computed_strain_by_key[(gk.track_id, s_i)] = float(lin[idx_s]) + + # Process in chronological order per track so d_strain_d_v is strictly causal + indexed = sorted( + enumerate(track_rows), + key=lambda item: (int(float(item[1]["track_id"])), int(float(item[1]["scan_idx"]))), + ) + out_by_orig_idx: dict[int, dict[str, Any]] = {} + + for orig_idx, row in indexed: + r = dict(row) + tid = int(float(r["track_id"])) + s_idx = int(float(r["scan_idx"])) + pt = stim_by_scan.get(s_idx) + + v_val = pt.voltage_v if pt is not None else None + r["elapsed_s"] = round(pt.elapsed_s, 4) if pt is not None else "" + r["voltage_v"] = round(v_val, 5) if v_val is not None else "" + r["current_ma"] = round(pt.current_ma, 5) if (pt is not None and pt.current_ma is not None) else "" + r["capacity_mah_g"] = round(pt.capacity_mah_g, 4) if (pt is not None and pt.capacity_mah_g is not None) else "" + r["dq_dv"] = round(pt.dq_dv, 4) if (pt is not None and pt.dq_dv is not None) else "" + r["stress_mpa"] = round(pt.stress_mpa, 4) if (pt is not None and pt.stress_mpa is not None) else "" + r["temperature_c"] = round(pt.temperature_c, 3) if (pt is not None and pt.temperature_c is not None) else "" + + strain_val: float | None = computed_strain_by_key.get((tid, s_idx)) + if strain_val is None: + for key in ("lineage_strain", "strain"): + if key in r and r[key] != "": + try: + strain_val = float(r[key]) + break + except (TypeError, ValueError): + pass + + d_eps_dv: float | str = "" + if tid in prev_by_tid and v_val is not None and strain_val is not None: + prev_v, prev_eps = prev_by_tid[tid] + if prev_v is not None and prev_eps is not None and abs(v_val - prev_v) >= 2e-3: + d_eps_dv = round((strain_val - prev_eps) / (v_val - prev_v), 6) + r["d_strain_d_v"] = d_eps_dv + prev_by_tid[tid] = (v_val, strain_val) + out_by_orig_idx[orig_idx] = r + + for i in range(len(track_rows)): + enriched.append(out_by_orig_idx[i]) + return enriched diff --git a/braggtrack/segmentation/dino_segment.py b/braggtrack/segmentation/dino_segment.py index 1250b23..8cc4b01 100644 --- a/braggtrack/segmentation/dino_segment.py +++ b/braggtrack/segmentation/dino_segment.py @@ -41,11 +41,11 @@ def _extract_slice_features( pixel-level ``(H, W)`` of each slice. """ n_slices = volume.shape[axis] - feature_maps: list[np.ndarray] = [] - for i in range(n_slices): - slc = np.take(volume, i, axis=axis) - fmap = encoder.extract_patch_features(slc) - feature_maps.append(fmap) + slices = [np.take(volume, i, axis=axis) for i in range(n_slices)] + if hasattr(encoder, "extract_patch_features_batch"): + feature_maps = encoder.extract_patch_features_batch(slices) + else: + feature_maps = [encoder.extract_patch_features(slc) for slc in slices] if axis == 0: slice_hw = (volume.shape[1], volume.shape[2]) diff --git a/braggtrack/segmentation/features.py b/braggtrack/segmentation/features.py index 32dcc3d..47728bb 100644 --- a/braggtrack/segmentation/features.py +++ b/braggtrack/segmentation/features.py @@ -68,11 +68,17 @@ def extract_instance_table( dz = (z_coords - cz) * calibration.mu_step dy = (y_coords - cy) * calibration.d_step dx = (x_coords - cx) * calibration.chi_step + step_mu = abs(calibration.mu_step) + step_d = abs(calibration.d_step) + step_chi = abs(calibration.chi_step) else: c_mu, c_chi, c_d = cz, cx, cy dz = z_coords - cz dy = y_coords - cy dx = x_coords - cx + step_mu = 1.0 + step_d = 1.0 + step_chi = 1.0 # Weighted covariance (same weight logic) if sum_i > 0: @@ -87,6 +93,16 @@ def extract_instance_table( czx = float(np.dot(w, dz * dx)) cyx = float(np.dot(w, dy * dx)) + # Analytical 1-sigma centroid standard error: under Poisson photon statistics + # Var(c) = cov / sum_i; when intensities are normalized (< n_eff), fall back to + # Kish effective sample size n_eff = 1 / sum(w_k^2), floored by voxel quantization. + w_sq = float(np.dot(w, w)) + n_eff = (1.0 / w_sq) if w_sq > 0.0 else float(max(1, count)) + eff_denom = max(sum_i, n_eff, 1.0) + c_mu_err = float(np.sqrt(max(czz, (step_mu**2) / 12.0) / eff_denom)) + c_chi_err = float(np.sqrt(max(cxx, (step_chi**2) / 12.0) / eff_denom)) + c_d_err = float(np.sqrt(max(cyy, (step_d**2) / 12.0) / eff_denom)) + cov = np.array( [ [czz, czy, czx], @@ -105,6 +121,9 @@ def extract_instance_table( "centroid_mu": c_mu, "centroid_chi": c_chi, "centroid_d": c_d, + "centroid_mu_err": c_mu_err, + "centroid_chi_err": c_chi_err, + "centroid_d_err": c_d_err, "bbox_min_z": int(z_coords.min()), "bbox_max_z": int(z_coords.max()), "bbox_min_y": int(y_coords.min()), diff --git a/braggtrack/semantic/dino.py b/braggtrack/semantic/dino.py index c636052..afe7601 100644 --- a/braggtrack/semantic/dino.py +++ b/braggtrack/semantic/dino.py @@ -12,6 +12,7 @@ import hashlib import os +from collections.abc import Sequence from typing import Any, Literal, Protocol import numpy as np @@ -87,14 +88,31 @@ def _mips_to_rgb_uint8(mip: np.ndarray) -> np.ndarray: class MultiviewEncoder(Protocol): def embed(self, mip_mu: np.ndarray, mip_chi: np.ndarray, mip_d: np.ndarray) -> np.ndarray: ... + def embed_batch( + self, + mips_list: Sequence[tuple[np.ndarray, np.ndarray, np.ndarray]], + *, + batch_size: int = 32, + ) -> np.ndarray: ... + class MockMultiviewEncoder: def embed(self, mip_mu: np.ndarray, mip_chi: np.ndarray, mip_d: np.ndarray) -> np.ndarray: return _mock_embedding_from_mips(mip_mu, mip_chi, mip_d) + def embed_batch( + self, + mips_list: Sequence[tuple[np.ndarray, np.ndarray, np.ndarray]], + *, + batch_size: int = 32, + ) -> np.ndarray: + if not mips_list: + return np.zeros((0, 384), dtype=np.float32) + return np.stack([self.embed(m0, m1, m2) for m0, m1, m2 in mips_list], axis=0) + class TorchDinoMultiviewEncoder: - """Loads DINOv2/DINOv3 once; call :meth:`embed` per spot.""" + """Loads DINOv2/DINOv3 once; supports both single-spot :meth:`embed` and batched :meth:`embed_batch`.""" def __init__(self, model_name: str = DEFAULT_DINO_MODEL, device: str | None = None) -> None: import torch @@ -104,26 +122,45 @@ def __init__(self, model_name: str = DEFAULT_DINO_MODEL, device: str | None = No self._proc, self._model = _load_hf_dino(model_name) self._model.eval() self._model.to(self._device) + self._hidden = int(getattr(self._model.config, "hidden_size", 384)) def embed(self, mip_mu: np.ndarray, mip_chi: np.ndarray, mip_d: np.ndarray) -> np.ndarray: - vecs: list[np.ndarray] = [] + return self.embed_batch([(mip_mu, mip_chi, mip_d)], batch_size=3)[0] + + def embed_batch( + self, + mips_list: Sequence[tuple[np.ndarray, np.ndarray, np.ndarray]], + *, + batch_size: int = 32, + ) -> np.ndarray: + if not mips_list: + return np.zeros((0, 3 * self._hidden), dtype=np.float32) + + all_rgbs: list[np.ndarray] = [] + for mip_mu, mip_chi, mip_d in mips_list: + all_rgbs.append(_mips_to_rgb_uint8(mip_mu)) + all_rgbs.append(_mips_to_rgb_uint8(mip_chi)) + all_rgbs.append(_mips_to_rgb_uint8(mip_d)) + + step = max(1, int(batch_size)) + if str(self._device) == "cpu": + step = min(step, 16) + cls_chunks: list[np.ndarray] = [] with self._torch.no_grad(): - for mip in (mip_mu, mip_chi, mip_d): - rgb = _mips_to_rgb_uint8(mip) - inputs = self._proc(images=[rgb], return_tensors="pt") + for start in range(0, len(all_rgbs), step): + chunk = all_rgbs[start : start + step] + inputs = self._proc(images=chunk, return_tensors="pt") inputs = {k: v.to(self._device) for k, v in inputs.items()} - out = self._model(**inputs).last_hidden_state[:, 0, :].squeeze(0) - x = out.float().cpu().numpy() - n = float(np.linalg.norm(x)) - if n > 0: - x = x / n - vecs.append(x.astype(np.float32)) + cls_tok = self._model(**inputs).last_hidden_state[:, 0, :].float().cpu().numpy() + norms = np.linalg.norm(cls_tok, axis=-1, keepdims=True) + norms = np.where(norms > 0.0, norms, 1.0) + cls_chunks.append((cls_tok / norms).astype(np.float32)) - fused = np.concatenate(vecs, axis=0) - nf = float(np.linalg.norm(fused)) - if nf > 0: - fused = fused / nf - return fused.astype(np.float32) + view_vecs = np.concatenate(cls_chunks, axis=0) # (3 * N, D) + fused = view_vecs.reshape(len(mips_list), 3 * view_vecs.shape[-1]) + fnorms = np.linalg.norm(fused, axis=-1, keepdims=True) + fnorms = np.where(fnorms > 0.0, fnorms, 1.0) + return (fused / fnorms).astype(np.float32) def _requested_backend(explicit: BackendName | None) -> BackendName: @@ -161,6 +198,15 @@ def extract_patch_features(self, image_2d: np.ndarray) -> np.ndarray: """Return (H_patches, W_patches, D_features) feature map from a 2D grayscale image.""" ... + def extract_patch_features_batch( + self, + images_2d: Sequence[np.ndarray], + *, + batch_size: int = 32, + ) -> list[np.ndarray]: + """Return list of (H_patches, W_patches, D_features) maps for a batch of 2D images.""" + ... + @property def patch_size(self) -> int: ... @@ -194,9 +240,17 @@ def extract_patch_features(self, image_2d: np.ndarray) -> np.ndarray: norms = np.where(norms > 0, norms, 1.0) return (features / norms).astype(np.float32) + def extract_patch_features_batch( + self, + images_2d: Sequence[np.ndarray], + *, + batch_size: int = 32, + ) -> list[np.ndarray]: + return [self.extract_patch_features(img) for img in images_2d] + class TorchDinoPatchEncoder: - """Extracts DINOv2/DINOv3 patch tokens as a spatial feature map.""" + """Extracts DINOv2/DINOv3 patch tokens as spatial feature maps (single or batched).""" def __init__(self, model_name: str = DEFAULT_DINO_MODEL, device: str | None = None) -> None: import torch @@ -218,24 +272,43 @@ def feature_dim(self) -> int: return self._feature_dim def extract_patch_features(self, image_2d: np.ndarray) -> np.ndarray: - rgb = _mips_to_rgb_uint8(image_2d) + return self.extract_patch_features_batch([image_2d], batch_size=1)[0] + + def extract_patch_features_batch( + self, + images_2d: Sequence[np.ndarray], + *, + batch_size: int = 32, + ) -> list[np.ndarray]: + if not images_2d: + return [] + rgbs = [_mips_to_rgb_uint8(img) for img in images_2d] + step = max(1, int(batch_size)) + if str(self._device) == "cpu": + step = min(step, 16) + results: list[np.ndarray] = [] with self._torch.no_grad(): - inputs = self._proc(images=[rgb], return_tensors="pt") - inputs = {k: v.to(self._device) for k, v in inputs.items()} - out = self._model(**inputs) - h_img = int(inputs["pixel_values"].shape[2]) - w_img = int(inputs["pixel_values"].shape[3]) - h_p = h_img // self._patch_size - w_p = w_img // self._patch_size - expected_patches = h_p * w_p - seq_len = int(out.last_hidden_state.shape[1]) - skip = max(0, seq_len - expected_patches) - patch_tokens = out.last_hidden_state[:, skip : skip + expected_patches, :].squeeze(0) - features = patch_tokens.reshape(h_p, w_p, -1) - x = features.float().cpu().numpy() - norms = np.linalg.norm(x, axis=-1, keepdims=True) - norms = np.where(norms > 0, norms, 1.0) - return (x / norms).astype(np.float32) + for start in range(0, len(rgbs), step): + chunk = rgbs[start : start + step] + inputs = self._proc(images=chunk, return_tensors="pt") + inputs = {k: v.to(self._device) for k, v in inputs.items()} + out = self._model(**inputs) + bsz = int(inputs["pixel_values"].shape[0]) + h_img = int(inputs["pixel_values"].shape[2]) + w_img = int(inputs["pixel_values"].shape[3]) + h_p = h_img // self._patch_size + w_p = w_img // self._patch_size + expected_patches = h_p * w_p + seq_len = int(out.last_hidden_state.shape[1]) + skip = max(0, seq_len - expected_patches) + patch_tokens = out.last_hidden_state[:, skip : skip + expected_patches, :] + fmaps = patch_tokens.reshape(bsz, h_p, w_p, -1).float().cpu().numpy() + norms = np.linalg.norm(fmaps, axis=-1, keepdims=True) + norms = np.where(norms > 0.0, norms, 1.0) + normed = (fmaps / norms).astype(np.float32) + for i in range(bsz): + results.append(normed[i]) + return results def make_patch_encoder( diff --git a/braggtrack/tracking/__init__.py b/braggtrack/tracking/__init__.py index 68a1f62..cd4713b 100644 --- a/braggtrack/tracking/__init__.py +++ b/braggtrack/tracking/__init__.py @@ -1,6 +1,6 @@ """Multi-scan grain tracking with physics and semantic cost functions.""" -from .assignment import associate_frames +from .assignment import associate_frames, compute_assignment_margins from .cost import CostFunction, GeometrySemanticCost, PositionShapeCost from .events import LineageEvent, SplitMergeConfig, events_to_table, resolve_splits_and_merges from .gap_closing import GapCloseRecord, GapClosingConfig, resolve_track_gaps @@ -39,6 +39,7 @@ "TrackEvent", "associate_frames", "build_tracks", + "compute_assignment_margins", "compute_fracture_precursors", "compute_grain_kinematics", "compute_tracking_metrics", diff --git a/braggtrack/tracking/assignment.py b/braggtrack/tracking/assignment.py index a860cbb..b6af028 100644 --- a/braggtrack/tracking/assignment.py +++ b/braggtrack/tracking/assignment.py @@ -69,3 +69,34 @@ def associate_frames( unmatched_t1 = [j for j in range(n_t1) if j not in matched_t1] return matches, unmatched_t, unmatched_t1 + + +def compute_assignment_margins( + spots_t: list[dict], + spots_t1: list[dict], + matches: list[tuple[int, int]], + cost_fn: CostFunction, +) -> dict[tuple[int, int], tuple[float, float]]: + """Compute ``(assigned_cost, margin)`` for each accepted Hungarian match. + + The margin is ``min(second_best_row - c_ij, second_best_col - c_ij)``, + measuring how close a competing spot in frame *t* or *t+1* came to + claiming the link (``math.inf`` when no finite competitor exists). + """ + if not matches or not spots_t or not spots_t1: + return {} + + raw = np.asarray(cost_fn.pairwise_cost_matrix(spots_t, spots_t1), dtype=np.float64) + n_t, n_t1 = raw.shape + out: dict[tuple[int, int], tuple[float, float]] = {} + for r, c in matches: + c_ij = float(raw[r, c]) + if not math.isfinite(c_ij): + out[(r, c)] = (math.inf, 0.0) + continue + row_others = [float(raw[r, k]) for k in range(n_t1) if k != c and math.isfinite(raw[r, k])] + col_others = [float(raw[k, c]) for k in range(n_t) if k != r and math.isfinite(raw[k, c])] + alt_costs = row_others + col_others + margin = (min(alt_costs) - c_ij) if alt_costs else math.inf + out[(r, c)] = (c_ij, float(margin)) + return out diff --git a/braggtrack/tracking/kinematics.py b/braggtrack/tracking/kinematics.py index 8221e28..db53138 100644 --- a/braggtrack/tracking/kinematics.py +++ b/braggtrack/tracking/kinematics.py @@ -48,6 +48,23 @@ class GrainKinematics: # Raw shift in d-axis (always meaningful even when uncalibrated) delta_d: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + # Analytical 1-sigma uncertainties (propagated from centroid_*_err) + centroid_mu_err: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + centroid_chi_err: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + centroid_d_err: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + strain_err: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + + # Ancestor-referenced lineage strain across 1->2+ splits and 2+->1 merges + root_track_id: int = 0 + lineage_strain: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + lineage_strain_err: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + + # Strictly causal backward finite-difference rates (per scan step) + rate_mu: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + rate_chi: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + rate_d: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + strain_rate: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + @dataclass class KinematicsSummary: @@ -66,9 +83,54 @@ class KinematicsSummary: max_anisotropy: list[float] calibrated_axes: bool = False + max_lineage_strain: list[float] = field(default_factory=list) grain_kinematics: list[GrainKinematics] = field(default_factory=list, repr=False) +def _parse_parent_ids(raw: Any) -> list[int]: + if raw is None or raw == "": + return [] + if isinstance(raw, (list, tuple)): + out: list[int] = [] + for item in raw: + try: + out.append(int(item)) + except (TypeError, ValueError): + continue + return out + if isinstance(raw, (int, np.integer)): + return [int(raw)] + if isinstance(raw, str): + parts = [p.strip() for p in raw.split(";") if p.strip()] + parsed: list[int] = [] + for p in parts: + try: + parsed.append(int(p)) + except ValueError: + continue + return parsed + return [] + + +def _propagate_strain_err( + d: np.ndarray, + d_err: np.ndarray, + d_ref: float, + d_ref_err: float, + *, + zero_first: bool, +) -> np.ndarray: + """Propagate 1-sigma uncertainty on ``(d - d_ref) / d_ref``.""" + n = len(d) + if n == 0 or d_ref == 0.0: + return np.zeros(n, dtype=np.float64) + ratio = d / d_ref + err = np.sqrt(d_err**2 + (ratio * d_ref_err) ** 2) / abs(d_ref) + if zero_first and n > 0: + err[0] = 0.0 + return err + + def compute_grain_kinematics( track_table: list[dict[str, Any]], ) -> list[GrainKinematics]: @@ -80,46 +142,120 @@ def compute_grain_kinematics( Output of :func:`~braggtrack.tracking.lifecycle.tracks_to_table`: list of dicts with ``track_id``, ``scan_idx``, ``centroid_mu``, ``centroid_chi``, ``centroid_d``, ``eig_1``, ``eig_2``, ``eig_3``, - ``integrated_intensity``, ``voxel_count``. + ``integrated_intensity``, ``voxel_count``, plus optional + ``centroid_*_err`` and ``parent_track_ids``. Returns ------- list[GrainKinematics] One entry per track, sorted by track_id. """ - tracks: dict[int, list[dict]] = {} + tracks: dict[int, list[dict[str, Any]]] = {} + parent_map: dict[int, list[int]] = {} for row in track_table: - tracks.setdefault(int(row["track_id"]), []).append(row) + tid = int(row["track_id"]) + tracks.setdefault(tid, []).append(row) + pids = _parse_parent_ids(row.get("parent_track_ids")) + if pids and tid not in parent_map: + parent_map[tid] = pids + + sorted_tracks: dict[int, list[dict[str, Any]]] = { + tid: sorted(rows, key=lambda r: int(r["scan_idx"])) for tid, rows in tracks.items() + } + + def _resolve_root_tid(start_tid: int) -> int: + curr = start_tid + visited: set[int] = set() + while curr not in visited: + visited.add(curr) + parents = [p for p in parent_map.get(curr, []) if p in sorted_tracks and p != curr] + if not parents: + break + # Prefer earliest-onset parent (tie-break by highest initial intensity, then lowest ID) + parents.sort( + key=lambda p: ( + int(sorted_tracks[p][0]["scan_idx"]), + -float(sorted_tracks[p][0].get("integrated_intensity", 0.0)), + p, + ) + ) + curr = parents[0] + return curr results: list[GrainKinematics] = [] - for tid in sorted(tracks): - obs = sorted(tracks[tid], key=lambda r: r["scan_idx"]) + for tid in sorted(sorted_tracks): + obs = sorted_tracks[tid] n = len(obs) scan_indices = [int(r["scan_idx"]) for r in obs] - mu = np.array([float(r["centroid_mu"]) for r in obs]) - chi = np.array([float(r["centroid_chi"]) for r in obs]) - d = np.array([float(r["centroid_d"]) for r in obs]) + mu = np.array([float(r["centroid_mu"]) for r in obs], dtype=np.float64) + chi = np.array([float(r["centroid_chi"]) for r in obs], dtype=np.float64) + d = np.array([float(r["centroid_d"]) for r in obs], dtype=np.float64) - # Strain: (d - d₀) / d₀ and raw shift Δd = d - d₀ - d0 = d[0] + mu_err = np.array([float(r.get("centroid_mu_err", 0.0)) for r in obs], dtype=np.float64) + chi_err = np.array([float(r.get("centroid_chi_err", 0.0)) for r in obs], dtype=np.float64) + d_err = np.array([float(r.get("centroid_d_err", 0.0)) for r in obs], dtype=np.float64) + + # Segment-local strain: (d - d₀) / d₀ and raw shift Δd = d - d₀ + d0 = float(d[0]) + d0_err = float(d_err[0]) delta_d = d - d0 - strain = delta_d / d0 if d0 != 0 else np.zeros(n) + strain = delta_d / d0 if d0 != 0.0 else np.zeros(n, dtype=np.float64) + strain_err = _propagate_strain_err(d, d_err, d0, d0_err, zero_first=True) + + # Ancestor-referenced lineage strain across splits/merges + root_tid = _resolve_root_tid(tid) + root_obs0 = sorted_tracks[root_tid][0] + d_root0 = float(root_obs0["centroid_d"]) + d_root0_err = float(root_obs0.get("centroid_d_err", 0.0)) + lineage_strain = (d - d_root0) / d_root0 if d_root0 != 0.0 else np.zeros(n, dtype=np.float64) + lineage_strain_err = _propagate_strain_err( + d, + d_err, + d_root0, + d_root0_err, + zero_first=(root_tid == tid), + ) + + # Strictly causal backward finite-difference rates (per scan step) + rate_mu = np.zeros(n, dtype=np.float64) + rate_chi = np.zeros(n, dtype=np.float64) + rate_d = np.zeros(n, dtype=np.float64) + strain_rate = np.zeros(n, dtype=np.float64) + + # Seed initial rate at i=0 from immediate parent's last observation if split/merge child + imm_parents = [p for p in parent_map.get(tid, []) if p in sorted_tracks] + if imm_parents and n > 0: + p_last = sorted_tracks[imm_parents[0]][-1] + dt0 = max(1, scan_indices[0] - int(p_last["scan_idx"])) + rate_mu[0] = (mu[0] - float(p_last["centroid_mu"])) / dt0 + rate_chi[0] = (chi[0] - float(p_last["centroid_chi"])) / dt0 + rate_d[0] = (d[0] - float(p_last["centroid_d"])) / dt0 + if d_root0 != 0.0: + p_lin_strain = (float(p_last["centroid_d"]) - d_root0) / d_root0 + strain_rate[0] = (lineage_strain[0] - p_lin_strain) / dt0 + + for i in range(1, n): + dt = max(1, scan_indices[i] - scan_indices[i - 1]) + rate_mu[i] = (mu[i] - mu[i - 1]) / dt + rate_chi[i] = (chi[i] - chi[i - 1]) / dt + rate_d[i] = (d[i] - d[i - 1]) / dt + strain_rate[i] = (lineage_strain[i] - lineage_strain[i - 1]) / dt # Misorientation: drift from initial position dmu = mu - mu[0] dchi = chi - chi[0] misorientation_total = np.sqrt(dmu**2 + dchi**2) - intensity = np.array([float(r["integrated_intensity"]) for r in obs]) - voxels = np.array([float(r["voxel_count"]) for r in obs]) + intensity = np.array([float(r["integrated_intensity"]) for r in obs], dtype=np.float64) + voxels = np.array([float(r["voxel_count"]) for r in obs], dtype=np.float64) i0 = intensity[0] v0 = voxels[0] - rel_intensity = (intensity - i0) / i0 if i0 != 0 else np.zeros(n) - rel_volume = (voxels - v0) / v0 if v0 != 0 else np.zeros(n) + rel_intensity = (intensity - i0) / i0 if i0 != 0 else np.zeros(n, dtype=np.float64) + rel_volume = (voxels - v0) / v0 if v0 != 0 else np.zeros(n, dtype=np.float64) - eigs = np.array([[float(r["eig_1"]), float(r["eig_2"]), float(r["eig_3"])] for r in obs]) + eigs = np.array([[float(r["eig_1"]), float(r["eig_2"]), float(r["eig_3"])] for r in obs], dtype=np.float64) e3 = eigs[:, 2] anisotropy = np.where(e3 > 0, eigs[:, 0] / e3, 1.0) cov_trace = eigs.sum(axis=1) @@ -143,6 +279,17 @@ def compute_grain_kinematics( anisotropy=anisotropy, covariance_trace=cov_trace, delta_d=delta_d, + centroid_mu_err=mu_err, + centroid_chi_err=chi_err, + centroid_d_err=d_err, + strain_err=strain_err, + root_track_id=root_tid, + lineage_strain=lineage_strain, + lineage_strain_err=lineage_strain_err, + rate_mu=rate_mu, + rate_chi=rate_chi, + rate_d=rate_d, + strain_rate=strain_rate, ) ) return results @@ -154,19 +301,10 @@ def summarize_kinematics( *, calibrated_axes: bool = False, ) -> KinematicsSummary: - """Aggregate per-grain kinematics into a summary table. - - Parameters - ---------- - grain_kinematics - Output of :func:`compute_grain_kinematics`. - n_scans - Total number of scans in the sequence. - calibrated_axes - Whether centroids/eigenvalues were converted to physical ``(mu, chi, d)`` units. - """ + """Aggregate per-grain kinematics into a summary table.""" track_ids: list[int] = [] max_strain: list[float] = [] + max_lineage_strain: list[float] = [] total_misorientation: list[float] = [] intensity_change: list[float] = [] volume_change: list[float] = [] @@ -175,6 +313,8 @@ def summarize_kinematics( for gk in grain_kinematics: track_ids.append(gk.track_id) max_strain.append(float(np.max(np.abs(gk.strain))) if len(gk.strain) > 0 else 0.0) + lin_s = gk.lineage_strain if len(gk.lineage_strain) > 0 else gk.strain + max_lineage_strain.append(float(np.max(np.abs(lin_s))) if len(lin_s) > 0 else 0.0) total_misorientation.append(float(gk.misorientation_total[-1]) if len(gk.misorientation_total) > 0 else 0.0) intensity_change.append(float(gk.relative_intensity[-1]) if len(gk.relative_intensity) > 0 else 0.0) volume_change.append(float(gk.relative_volume[-1]) if len(gk.relative_volume) > 0 else 0.0) @@ -193,6 +333,7 @@ def summarize_kinematics( volume_change_frac=volume_change, max_anisotropy=max_anisotropy, calibrated_axes=calibrated_axes, + max_lineage_strain=max_lineage_strain, grain_kinematics=grain_kinematics, ) @@ -206,6 +347,7 @@ def summary_to_dict(summary: KinematicsSummary) -> dict[str, Any]: "calibrated_axes": summary.calibrated_axes, "track_ids": summary.track_ids, "max_strain": summary.max_strain, + "max_lineage_strain": summary.max_lineage_strain, "total_misorientation": summary.total_misorientation, "intensity_change_frac": summary.intensity_change_frac, "volume_change_frac": summary.volume_change_frac, @@ -218,22 +360,29 @@ def kinematics_to_table( *, include_delta_d: bool = False, ) -> list[dict[str, Any]]: - """Flatten per-grain kinematics into a row-per-observation table. - - Each row contains the track_id, scan_idx, and all computed kinematic - quantities for that observation. Suitable for CSV export or DataFrame - construction. - """ + """Flatten per-grain kinematics into a row-per-observation table.""" rows: list[dict[str, Any]] = [] for gk in grain_kinematics: + root_tid = gk.root_track_id if gk.root_track_id > 0 else gk.track_id for i, scan_idx in enumerate(gk.scan_indices): row: dict[str, Any] = { "track_id": gk.track_id, + "root_track_id": root_tid, "scan_idx": scan_idx, "centroid_mu": float(gk.centroid_mu[i]), "centroid_chi": float(gk.centroid_chi[i]), "centroid_d": float(gk.centroid_d[i]), + "centroid_mu_err": float(gk.centroid_mu_err[i]) if len(gk.centroid_mu_err) > i else 0.0, + "centroid_chi_err": float(gk.centroid_chi_err[i]) if len(gk.centroid_chi_err) > i else 0.0, + "centroid_d_err": float(gk.centroid_d_err[i]) if len(gk.centroid_d_err) > i else 0.0, "strain": float(gk.strain[i]), + "strain_err": float(gk.strain_err[i]) if len(gk.strain_err) > i else 0.0, + "lineage_strain": float(gk.lineage_strain[i]) if len(gk.lineage_strain) > i else float(gk.strain[i]), + "lineage_strain_err": (float(gk.lineage_strain_err[i]) if len(gk.lineage_strain_err) > i else 0.0), + "strain_rate": float(gk.strain_rate[i]) if len(gk.strain_rate) > i else 0.0, + "rate_mu": float(gk.rate_mu[i]) if len(gk.rate_mu) > i else 0.0, + "rate_chi": float(gk.rate_chi[i]) if len(gk.rate_chi) > i else 0.0, + "rate_d": float(gk.rate_d[i]) if len(gk.rate_d) > i else 0.0, "misorientation_mu": float(gk.misorientation_mu[i]), "misorientation_chi": float(gk.misorientation_chi[i]), "misorientation_total": float(gk.misorientation_total[i]), diff --git a/braggtrack/tracking/lifecycle.py b/braggtrack/tracking/lifecycle.py index 54b8c8c..9feb96c 100644 --- a/braggtrack/tracking/lifecycle.py +++ b/braggtrack/tracking/lifecycle.py @@ -7,7 +7,7 @@ import networkx as nx -from .assignment import associate_frames +from .assignment import associate_frames, compute_assignment_margins from .cost import CostFunction, PositionShapeCost if TYPE_CHECKING: @@ -56,7 +56,15 @@ def build_tracks( track_map: dict[int, int] = {} # spot_idx -> track_id for current frame for idx, spot in enumerate(scan_tables[0]): nid = _node_id(0, idx) - G.add_node(nid, scan_idx=0, spot_idx=idx, track_id=next_track_id, event=TrackEvent.BORN, **spot) + G.add_node( + nid, + scan_idx=0, + spot_idx=idx, + track_id=next_track_id, + event=TrackEvent.BORN, + assignment_margin=float("inf"), + **spot, + ) track_map[idx] = next_track_id next_track_id += 1 @@ -71,6 +79,7 @@ def build_tracks( cost_fn=active_cost, max_cost=max_cost, ) + margins = compute_assignment_margins(spots_t, spots_t1, matches, active_cost) new_track_map: dict[int, int] = {} @@ -79,10 +88,23 @@ def build_tracks( tid = track_map[i_t] nid_prev = _node_id(t, i_t) nid_next = _node_id(t + 1, i_t1) + c_ij, margin = margins.get((i_t, i_t1), (0.0, float("inf"))) G.add_node( - nid_next, scan_idx=t + 1, spot_idx=i_t1, track_id=tid, event=TrackEvent.CONTINUED, **spots_t1[i_t1] + nid_next, + scan_idx=t + 1, + spot_idx=i_t1, + track_id=tid, + event=TrackEvent.CONTINUED, + assignment_margin=margin, + **spots_t1[i_t1], + ) + G.add_edge( + nid_prev, + nid_next, + edge_type="continuation", + cost=c_ij, + assignment_margin=margin, ) - G.add_edge(nid_prev, nid_next, edge_type="continuation") new_track_map[i_t1] = tid # Unmatched in t → TERMINATED (mark on existing node) @@ -94,7 +116,13 @@ def build_tracks( for i_t1 in unmatched_t1: nid = _node_id(t + 1, i_t1) G.add_node( - nid, scan_idx=t + 1, spot_idx=i_t1, track_id=next_track_id, event=TrackEvent.BORN, **spots_t1[i_t1] + nid, + scan_idx=t + 1, + spot_idx=i_t1, + track_id=next_track_id, + event=TrackEvent.BORN, + assignment_margin=float("inf"), + **spots_t1[i_t1], ) new_track_map[i_t1] = next_track_id next_track_id += 1 diff --git a/braggtrack/tracking/precursors.py b/braggtrack/tracking/precursors.py index 053903a..980e885 100644 --- a/braggtrack/tracking/precursors.py +++ b/braggtrack/tracking/precursors.py @@ -103,17 +103,38 @@ def _count_internal_subpeaks(masked_cube: np.ndarray, mask: np.ndarray) -> tuple return n_peaks, subpeak_score -def _patch_dispersion_score( +def _dispersion_from_fmap(fmap: np.ndarray, mm_up: np.ndarray) -> float | None: + """Compute foreground patch-token cosine dispersion for one upsampled MIP feature map.""" + hp, wp, dim = fmap.shape + if hp * wp < 2: + return None + + bh = max(1, mm_up.shape[0] // hp) + bw = max(1, mm_up.shape[1] // wp) + cropped_fg = (mm_up[: hp * bh, : wp * bw] > 0).reshape(hp, bh, wp, bw).max(axis=(1, 3)) + fg_vecs = fmap[cropped_fg] if int(cropped_fg.sum()) >= 2 else fmap.reshape(-1, dim) + if fg_vecs.shape[0] < 2: + return None + + mean_vec = fg_vecs.mean(axis=0) + nrm = float(np.linalg.norm(mean_vec)) + if nrm <= 0.0: + return None + mean_vec = mean_vec / nrm + cos_sims = np.clip(fg_vecs @ mean_vec, -1.0, 1.0) + cos_disp = float(1.0 - np.mean(cos_sims)) + return float(np.clip(cos_disp / 0.6, 0.0, 1.0)) + + +def _prepare_upsampled_roi_mips( masked_cube: np.ndarray, mask: np.ndarray, - patch_encoder: PatchFeatureEncoder, upsample_size: int, -) -> float: - """Compute mean foreground patch-token cosine dispersion across orthogonal MIPs.""" +) -> list[tuple[np.ndarray, np.ndarray]]: + """Return upsampled ``(mip_up, mask_up)`` pairs for non-empty orthogonal views.""" mip_mu, mip_chi, mip_d = orthogonal_mips(masked_cube) mask_mu, mask_chi, mask_d = orthogonal_mips(mask.astype(np.float64)) - - dispersions: list[float] = [] + pairs: list[tuple[np.ndarray, np.ndarray]] = [] for mip, mm in ((mip_mu, mask_mu), (mip_chi, mask_chi), (mip_d, mask_d)): if mip.size == 0 or float(mm.max()) <= 0.0: continue @@ -122,29 +143,28 @@ def _patch_dispersion_score( zw = max(1.0, upsample_size / max(1, w)) mip_up = zoom(mip.astype(np.float64), (zh, zw), order=1) if (zh > 1.0 or zw > 1.0) else mip.astype(np.float64) mm_up = zoom(mm.astype(np.float64), (zh, zw), order=0) if (zh > 1.0 or zw > 1.0) else mm.astype(np.float64) + pairs.append((mip_up, mm_up)) + return pairs - fmap = patch_encoder.extract_patch_features(mip_up) - hp, wp, dim = fmap.shape - if hp * wp < 2: - continue - - # Map foreground mask onto (hp, wp) patch grid. - bh = max(1, mm_up.shape[0] // hp) - bw = max(1, mm_up.shape[1] // wp) - cropped_fg = (mm_up[: hp * bh, : wp * bw] > 0).reshape(hp, bh, wp, bw).max(axis=(1, 3)) - fg_vecs = fmap[cropped_fg] if int(cropped_fg.sum()) >= 2 else fmap.reshape(-1, dim) - if fg_vecs.shape[0] < 2: - continue - - mean_vec = fg_vecs.mean(axis=0) - nrm = float(np.linalg.norm(mean_vec)) - if nrm <= 0.0: - continue - mean_vec = mean_vec / nrm - cos_sims = np.clip(fg_vecs @ mean_vec, -1.0, 1.0) - cos_disp = float(1.0 - np.mean(cos_sims)) - dispersions.append(float(np.clip(cos_disp / 0.6, 0.0, 1.0))) +def _patch_dispersion_score( + masked_cube: np.ndarray, + mask: np.ndarray, + patch_encoder: PatchFeatureEncoder, + upsample_size: int, +) -> float: + """Compute mean foreground patch-token cosine dispersion across orthogonal MIPs.""" + pairs = _prepare_upsampled_roi_mips(masked_cube, mask, upsample_size) + if not pairs: + return 0.0 + mips = [p[0] for p in pairs] + batch_fn = getattr(patch_encoder, "extract_patch_features_batch", None) + fmaps = batch_fn(mips) if callable(batch_fn) else [patch_encoder.extract_patch_features(m) for m in mips] + dispersions: list[float] = [] + for fmap, (_, mm_up) in zip(fmaps, pairs, strict=True): + val = _dispersion_from_fmap(fmap, mm_up) + if val is not None: + dispersions.append(val) return float(np.mean(dispersions)) if dispersions else 0.0 @@ -156,6 +176,8 @@ def compute_fracture_precursors( label_volumes: dict[int, np.ndarray] | list[np.ndarray] | None = None, patch_encoder: PatchFeatureEncoder | None = None, lineage_events: list[LineageEvent] | None = None, + roi_cache: dict[tuple[int, int], tuple[int, float]] | None = None, + batch_size: int = 32, ) -> tuple[list[PrecursorCandidate], list[ObservationPrecursorScore]]: """Score per-grain fracture precursors and return persistent ranked candidates. @@ -173,6 +195,11 @@ def compute_fracture_precursors( lineage_events Optional list of :class:`LineageEvent` records used to annotate whether a precursor candidate subsequently fractured (``subsequent_split``). + roi_cache + Optional mutable ``(scan_idx, label) -> (n_subpeaks, roi_term)`` cache + for incremental online streaming so historical scans are not re-cropped. + batch_size + Mini-batch size when running ``patch_encoder.extract_patch_features_batch``. """ cfg = config or PrecursorConfig() if not track_table: @@ -191,6 +218,65 @@ def compute_fracture_precursors( lab_map = dict(enumerate(label_volumes)) has_roi = bool(vol_map and lab_map) + effective_cache: dict[tuple[int, int], tuple[int, float]] = roi_cache if roi_cache is not None else {} + + # Pre-compute uncached ROI sub-peaks and batch all DINO patch-feature extractions together. + if has_roi: + pending_keys: list[tuple[int, int]] = [] + pending_subpeaks: list[tuple[int, float]] = [] + pending_view_slices: list[tuple[int, int]] = [] + all_mips: list[np.ndarray] = [] + all_masks: list[np.ndarray] = [] + + for row in track_table: + s_idx = int(row["scan_idx"]) + lbl_i = int(row.get("label", 0)) + key = (s_idx, lbl_i) + if lbl_i <= 0 or "bbox_min_z" not in row or key in effective_cache: + continue + if s_idx not in vol_map or s_idx not in lab_map: + continue + # Mark placeholder immediately in case duplicate rows exist + effective_cache[key] = (1, 0.0) + masked_cube, mask = crop_spot_cube( + vol_map[s_idx], + lab_map[s_idx], + lbl_i, + row, + margin=cfg.roi_margin, + ) + n_sub, sub_term = _count_internal_subpeaks(masked_cube, mask) + if patch_encoder is None: + effective_cache[key] = (n_sub, sub_term) + else: + pairs = _prepare_upsampled_roi_mips(masked_cube, mask, cfg.roi_upsample_size) + v_start = len(all_mips) + for mip_up, mm_up in pairs: + all_mips.append(mip_up) + all_masks.append(mm_up) + v_end = len(all_mips) + pending_keys.append(key) + pending_subpeaks.append((n_sub, sub_term)) + pending_view_slices.append((v_start, v_end)) + + if patch_encoder is not None and pending_keys: + batch_fn = getattr(patch_encoder, "extract_patch_features_batch", None) + if callable(batch_fn): + all_fmaps = batch_fn(all_mips, batch_size=batch_size) if all_mips else [] + else: + all_fmaps = [patch_encoder.extract_patch_features(m) for m in all_mips] + + for key, (n_sub, sub_term), (v_start, v_end) in zip( + pending_keys, pending_subpeaks, pending_view_slices, strict=True + ): + dispersions: list[float] = [] + for v_idx in range(v_start, v_end): + val = _dispersion_from_fmap(all_fmaps[v_idx], all_masks[v_idx]) + if val is not None: + dispersions.append(val) + p_disp = float(np.mean(dispersions)) if dispersions else 0.0 + roi_val = float(np.clip(0.65 * sub_term + 0.35 * p_disp, 0.0, 1.0)) + effective_cache[key] = (n_sub, roi_val) split_parent_tids: set[int] = set() if lineage_events: @@ -207,11 +293,27 @@ def compute_fracture_precursors( for tid in sorted(by_track): obs_list = sorted(by_track[tid], key=lambda r: int(r["scan_idx"])) - e0 = ( - float(obs_list[0].get("eig_1", 0.0)) - + float(obs_list[0].get("eig_2", 0.0)) - + float(obs_list[0].get("eig_3", 0.0)) + eig1_0 = max(0.0, float(obs_list[0].get("eig_1", 0.0))) + eig2_0 = max(0.0, float(obs_list[0].get("eig_2", 0.0))) + eig3_0 = max(0.0, float(obs_list[0].get("eig_3", 0.0))) + e0 = eig1_0 + eig2_0 + eig3_0 + aniso_0 = eig1_0 / eig3_0 if eig3_0 > 1e-12 else 1.0 + c0_mu = max(1e-12, float(obs_list[0].get("cov_zz", 1.0))) + c0_chi = max(1e-12, float(obs_list[0].get("cov_xx", 1.0))) + c0_d = max(1e-12, float(obs_list[0].get("cov_yy", 1.0))) + has_cov = all(k in obs_list[0] for k in ("cov_zz", "cov_xx", "cov_yy")) + has_bbox = all( + k in obs_list[0] + for k in ("bbox_min_z", "bbox_max_z", "bbox_min_x", "bbox_max_x", "bbox_min_y", "bbox_max_y") ) + if has_cov and has_bbox: + dz0 = max(float(obs_list[0]["bbox_max_z"]) - float(obs_list[0]["bbox_min_z"]), 1.0) + dx0 = max(float(obs_list[0]["bbox_max_x"]) - float(obs_list[0]["bbox_min_x"]), 1.0) + dy0 = max(float(obs_list[0]["bbox_max_y"]) - float(obs_list[0]["bbox_min_y"]), 1.0) + scales2 = [c0_mu / (dz0 * dz0), c0_chi / (dx0 * dx0), c0_d / (dy0 * dy0)] + mixed_units = (max(scales2) / max(min(scales2), 1e-18)) > 25.0 + else: + mixed_units = has_cov and aniso_0 > 50.0 track_scores: list[ObservationPrecursorScore] = [] for obs in obs_list: @@ -221,32 +323,29 @@ def compute_fracture_precursors( eig2 = max(0.0, float(obs.get("eig_2", 0.0))) eig3 = max(0.0, float(obs.get("eig_3", 0.0))) - aniso = eig1 / eig3 if eig3 > 1e-9 else (1.0 if eig1 <= 1e-9 else 10.0) - aniso_term = float(np.clip((aniso - 1.0) / max(cfg.anisotropy_scale, 1e-6), 0.0, 1.0)) + if mixed_units: + r_mu = max(0.0, float(obs.get("cov_zz", 0.0))) / c0_mu + r_chi = max(0.0, float(obs.get("cov_xx", 0.0))) / c0_chi + r_d = max(0.0, float(obs.get("cov_yy", 0.0))) / c0_d + r_max = max(r_mu, r_chi, r_d) + r_min = max(min(r_mu, r_chi, r_d), 1e-9) + aniso = r_max / r_min + spread_growth = (r_mu + r_chi + r_d - 3.0) / 3.0 + else: + aniso = eig1 / eig3 if eig3 > 1e-9 else (1.0 if eig1 <= 1e-9 else 10.0) + trace = eig1 + eig2 + eig3 + spread_growth = (trace - e0) / e0 if e0 > 1e-9 else 0.0 - trace = eig1 + eig2 + eig3 - spread_growth = (trace - e0) / e0 if e0 > 1e-9 else 0.0 + aniso_term = float(np.clip((aniso - 1.0) / max(cfg.anisotropy_scale, 1e-6), 0.0, 1.0)) spread_term = float(np.clip(max(0.0, spread_growth) / max(cfg.spread_growth_scale, 1e-6), 0.0, 1.0)) n_subpeaks = 1 roi_term = 0.0 - use_roi_here = has_roi and scan_idx in vol_map and scan_idx in lab_map and lbl > 0 - if use_roi_here and "bbox_min_z" in obs: - masked_cube, mask = crop_spot_cube( - vol_map[scan_idx], - lab_map[scan_idx], - lbl, - obs, - margin=cfg.roi_margin, - ) - n_subpeaks, subpeak_term = _count_internal_subpeaks(masked_cube, mask) - if patch_encoder is not None: - p_disp = _patch_dispersion_score(masked_cube, mask, patch_encoder, cfg.roi_upsample_size) - roi_term = float(np.clip(0.65 * subpeak_term + 0.35 * p_disp, 0.0, 1.0)) - else: - roi_term = subpeak_term - + use_roi_here = lbl > 0 and ( + (scan_idx, lbl) in effective_cache or (has_roi and scan_idx in vol_map and scan_idx in lab_map) + ) if use_roi_here and "bbox_min_z" in obs: + n_subpeaks, roi_term = effective_cache.get((scan_idx, lbl), (1, 0.0)) w_sum = cfg.weight_anisotropy + cfg.weight_spread + cfg.weight_roi raw_score = ( cfg.weight_anisotropy * aniso_term + cfg.weight_spread * spread_term + cfg.weight_roi * roi_term diff --git a/braggtrack/viz/__init__.py b/braggtrack/viz/__init__.py index 52705e6..4c50333 100644 --- a/braggtrack/viz/__init__.py +++ b/braggtrack/viz/__init__.py @@ -4,6 +4,7 @@ from .kinematics import plot_kinematics_dashboard from .lineage import plot_lineage_dag from .mips import plot_scan_projection_overlay, plot_spot_mip_card +from .operando import plot_operando_strain_and_events from .precursors import plot_precursor_timeline __all__ = [ @@ -11,6 +12,7 @@ "generate_html_report", "plot_kinematics_dashboard", "plot_lineage_dag", + "plot_operando_strain_and_events", "plot_precursor_timeline", "plot_scan_projection_overlay", "plot_spot_mip_card", diff --git a/braggtrack/viz/html_report.py b/braggtrack/viz/html_report.py index 49518ef..deeaa2d 100644 --- a/braggtrack/viz/html_report.py +++ b/braggtrack/viz/html_report.py @@ -148,6 +148,7 @@ def build_explorer_payload( artifact_dir: str | Path, *, dataset_root: str | Path | None = None, + operando_log: str | Path | None = None, max_mip_tracks: int = 16, ) -> dict[str, Any]: """Assemble structured JSON payload for the interactive 4D explorer from pipeline/tracking outputs.""" @@ -256,6 +257,30 @@ def build_explorer_payload( if n_scans == 0 and track_rows: n_scans = max(int(r["scan_idx"]) for r in track_rows) + 1 + # Load synchronized operando stimulus from explicit log path or saved artifact JSON + stimuli_list: list[dict[str, Any]] = [] + saved_stim = _read_json(root / "operando_stimulus.json") + if operando_log is not None: + from braggtrack.io import BeamlineAdapter, load_operando_log, synchronize_to_scans + + op_log = load_operando_log(operando_log) + if ds_root is not None and ds_root.is_dir(): + try: + seq = BeamlineAdapter(ds_root).build_sequence() + pts = ( + synchronize_to_scans(op_log, seq) + if len(seq.scans) == n_scans + else synchronize_to_scans(op_log, n_scans) + ) + except Exception: + pts = synchronize_to_scans(op_log, n_scans) + else: + pts = synchronize_to_scans(op_log, n_scans) + stimuli_list = [p.to_dict() for p in pts] + elif isinstance(saved_stim, dict) and isinstance(saved_stim.get("scans"), list): + stimuli_list = list(saved_stim["scans"]) + stim_by_scan = {int(s["scan_idx"]): s for s in stimuli_list if "scan_idx" in s} + priority_tids = sorted( by_tid.keys(), key=lambda tid: ( @@ -279,6 +304,16 @@ def build_explorer_payload( for idx_o, o in enumerate(obs_sorted): s_i = int(o["scan_idx"]) strain_pct = float(gk.strain[idx_o] * 100.0) if gk is not None and idx_o < len(gk.strain) else 0.0 + lin_strain_pct = ( + float(gk.lineage_strain[idx_o] * 100.0) + if gk is not None and idx_o < len(gk.lineage_strain) + else strain_pct + ) + strain_err_pct = ( + float(gk.lineage_strain_err[idx_o] * 100.0) + if gk is not None and idx_o < len(gk.lineage_strain_err) + else 0.0 + ) miso = ( float(gk.misorientation_total[idx_o]) if gk is not None and idx_o < len(gk.misorientation_total) @@ -286,6 +321,7 @@ def build_explorer_payload( ) aniso = float(gk.anisotropy[idx_o]) if gk is not None and idx_o < len(gk.anisotropy) else 1.0 po = prec_obs_by_key.get((tid, s_i), {}) + stim = stim_by_scan.get(s_i, {}) obs_items.append( { "scan_idx": s_i, @@ -296,6 +332,12 @@ def build_explorer_payload( "intensity": round(float(o.get("integrated_intensity", 0.0)), 2), "voxels": int(o.get("voxel_count", 0)), "strain_pct": round(strain_pct, 4), + "lineage_strain_pct": round(lin_strain_pct, 4), + "strain_err_pct": round(strain_err_pct, 4), + "voltage_v": stim.get("voltage_v"), + "dq_dv": stim.get("dq_dv"), + "stress_mpa": stim.get("stress_mpa"), + "temperature_c": stim.get("temperature_c"), "misorientation": round(miso, 4), "anisotropy": round(aniso, 3), "precursor_score": round(float(po.get("score", 0.0)), 4), @@ -308,12 +350,13 @@ def build_explorer_payload( tracks_payload.append( { "track_id": tid, + "root_track_id": gk.root_track_id if gk is not None and gk.root_track_id > 0 else tid, "is_full": is_full, "has_gap": has_gap, "is_split": tid in split_tids, "is_merge": tid in merge_tids, "is_precursor": tid in prec_tids, - "max_abs_strain_pct": round(max((abs(x["strain_pct"]) for x in obs_items), default=0.0), 4), + "max_abs_strain_pct": round(max((abs(x["lineage_strain_pct"]) for x in obs_items), default=0.0), 4), "max_precursor": round(max((x["precursor_score"] for x in obs_items), default=0.0), 4), "observations": obs_items, } @@ -330,7 +373,7 @@ def build_explorer_payload( "calibrated_axes": bool(trk_summary.get("calibrated_axes", False)), "backend": evt_summary.get("backend") or manifest.get("config", {}).get("backend") or "n/a", "model": evt_summary.get("model") or manifest.get("config", {}).get("model") or "n/a", - "braggtrack_version": manifest.get("braggtrack_version", "0.3.0"), + "braggtrack_version": manifest.get("braggtrack_version", "0.4.0"), "total_duration_sec": manifest.get("total_duration_sec"), "kpis": { "total_tracks": len(tracks_payload), @@ -340,6 +383,7 @@ def build_explorer_payload( "merge_count": sum(1 for e in events_list if e["event_type"] == "merge"), "precursor_count": len(precursors_list), }, + "stimuli": stimuli_list, "tracks": tracks_payload, "events": events_list, "precursors": precursors_list, @@ -509,10 +553,13 @@ def build_explorer_payload( const lane = new Map(tracks.map((t, idx) => [t.track_id, padT + idx * rowH])); let svg = ``; + const stimMap = new Map((DATA.stimuli || []).map(st => [st.scan_idx, st])); for (let s = 0; s < nScans; s++) { const x = xOf(s); + const st = stimMap.get(s); + const vTag = (st && st.voltage_v != null) ? ` (${Number(st.voltage_v).toFixed(2)}V)` : ''; svg += ``; - svg += `${DATA.scan_names[s] || ('S' + s)}`; + svg += `${(DATA.scan_names[s] || ('S' + s)) + vTag}`; } // Event edges @@ -543,8 +590,11 @@ def build_explorer_payload( else if (t.is_merge) fill = 'var(--merge)'; else if (t.is_precursor) fill = 'var(--prec)'; const r = isSel ? 6 : 4.6; + const linS = o.lineage_strain_pct != null ? o.lineage_strain_pct : o.strain_pct; + const errS = o.strain_err_pct ? `±${o.strain_err_pct}` : ''; + const vInfo = o.voltage_v != null ? ` | V=${Number(o.voltage_v).toFixed(3)}V` : ''; svg += ` - T${t.track_id} @ scan ${o.scan_idx} | strain=${o.strain_pct}% | I=${o.intensity} | prec=${o.precursor_score} + T${t.track_id} @ scan ${o.scan_idx}${vInfo} | root_strain=${linS}${errS}% | I=${o.intensity} | prec=${o.precursor_score} `; }); }); @@ -592,18 +642,21 @@ def build_explorer_payload( mipsEl.innerHTML = ''; return; } - titleEl.textContent = `Track T${t.track_id} (${t.observations.length} observations)`; + const rootNote = (t.root_track_id && t.root_track_id !== t.track_id) ? ` [root T${t.root_track_id}]` : ''; + titleEl.textContent = `Track T${t.track_id}${rootNote} (${t.observations.length} observations)`; const badges = []; if (t.is_split) badges.push('Split Lineage'); if (t.is_merge) badges.push('Merge Lineage'); if (t.is_precursor) badges.push('Precursor'); badgeEl.innerHTML = badges.join(' '); - const strainPts = t.observations.map(o => [o.scan_idx, o.strain_pct]); + const vPts = (DATA.stimuli || []).filter(s => s.voltage_v != null).map(s => [s.scan_idx, Number(s.voltage_v)]); + const strainPts = t.observations.map(o => [o.scan_idx, o.lineage_strain_pct != null ? o.lineage_strain_pct : o.strain_pct]); const intPts = t.observations.map(o => [o.scan_idx, o.intensity]); const precPts = t.observations.map(o => [o.scan_idx, o.precursor_score]); chartsEl.innerHTML = - sparkSvg(strainPts, 'var(--primary)', 'Relative d-shift / Strain (%)') + + (vPts.length ? sparkSvg(vPts, 'var(--gap)', 'Operando Potential E (V)') : '') + + sparkSvg(strainPts, 'var(--primary)', 'Ancestor-Referenced Strain (%)') + sparkSvg(intPts, 'var(--merge)', 'Integrated Intensity') + sparkSvg(precPts, 'var(--prec)', 'Fracture Precursor Score [0, 1]'); @@ -680,6 +733,7 @@ def generate_html_report( out_html: str | Path | None = None, *, dataset_root: str | Path | None = None, + operando_log: str | Path | None = None, max_mip_tracks: int = 16, ) -> Path: """Render a self-contained interactive HTML 4D explorer from a BraggTrack output directory.""" @@ -687,7 +741,12 @@ def generate_html_report( dest = Path(out_html) if out_html is not None else (root / "report.html") dest.parent.mkdir(parents=True, exist_ok=True) - payload = build_explorer_payload(root, dataset_root=dataset_root, max_mip_tracks=max_mip_tracks) + payload = build_explorer_payload( + root, + dataset_root=dataset_root, + operando_log=operando_log, + max_mip_tracks=max_mip_tracks, + ) safe_json = json.dumps(payload).replace(" tuple[Any, Any]: + """Plot 3-panel synchronized operando stimulus, ancestor-referenced strain ± error, and fracture precursors. + + Panels (shared scan-index horizontal axis): + 1. External stimulus (Cell Voltage ``V`` + optional twin-axis ``|dQ/dV|``, or Stress ``MPa`` / Temp ``°C``). + 2. Root-ancestor-referenced per-grain lattice strain ``lineage_strain ± lineage_strain_err`` (%) with + dashed parent -> daughter cleavage connectors across ``1 -> 2+`` splits. + 3. Per-grain fracture precursor score ``[0, 1]`` with split lines and optional autonomous zoom trigger stars. + """ + _, plt = _require_matplotlib() + + if kinematics_or_tracks and isinstance(kinematics_or_tracks[0], GrainKinematics): + gks: list[GrainKinematics] = list(kinematics_or_tracks) # type: ignore[arg-type] + else: + gks = compute_grain_kinematics([dict(r) for r in kinematics_or_tracks]) # type: ignore[arg-type] + + stim_dicts: list[dict[str, Any]] = [ + s.to_dict() if hasattr(s, "to_dict") else dict(s) # type: ignore[union-attr, arg-type] + for s in scan_stimuli + ] + stim_dicts.sort(key=lambda d: int(d.get("scan_idx", 0))) + + fig, axes = plt.subplots(3, 1, figsize=(10.5, 8.2), sharex=True, gridspec_kw={"height_ratios": [1.0, 1.45, 1.05]}) + + # --- Panel 0: Operando Stimulus (Voltage + dQ/dV, or Stress / Temperature) --- + ax_stim = axes[0] + if stim_dicts: + s_x = np.array([int(d["scan_idx"]) for d in stim_dicts], dtype=np.float64) + volt = [d.get("voltage_v") for d in stim_dicts] + dqdv = [d.get("dq_dv") for d in stim_dicts] + stress = [d.get("stress_mpa") for d in stim_dicts] + temp = [d.get("temperature_c") for d in stim_dicts] + + if any(v is not None and v != "" for v in volt): + v_arr = np.array([float(v) if (v is not None and v != "") else np.nan for v in volt], dtype=np.float64) + ax_stim.plot(s_x, v_arr, "o-", color="#0F172A", linewidth=2.0, markersize=4.5, label="Cell Voltage (V)") + ax_stim.set_ylabel("Potential (V vs. Li/Li$^+$)", fontsize=9, fontweight="bold") + if any(q is not None and q != "" for q in dqdv): + q_arr = np.array( + [abs(float(q)) if (q is not None and q != "") else np.nan for q in dqdv], + dtype=np.float64, + ) + if np.any(np.isfinite(q_arr)) and float(np.nanmax(q_arr)) > 0.0: + ax_twin = ax_stim.twinx() + ax_twin.fill_between(s_x, 0.0, q_arr, color=OKABE_ITO[5], alpha=0.22, label="|dQ/dV|") + ax_twin.plot(s_x, q_arr, "--", color=OKABE_ITO[0], linewidth=1.2, alpha=0.85) + ax_twin.set_ylabel("|dQ/dV|", fontsize=8.5, color=OKABE_ITO[0]) + ax_twin.spines["top"].set_visible(False) + elif any(s is not None and s != "" for s in stress): + st_arr = np.array([float(s) if (s is not None and s != "") else np.nan for s in stress], dtype=np.float64) + ax_stim.plot(s_x, st_arr, "s-", color=OKABE_ITO[1], linewidth=2.0, markersize=4.5, label="Stress (MPa)") + ax_stim.set_ylabel("Applied Stress (MPa)", fontsize=9, fontweight="bold") + elif any(t is not None and t != "" for t in temp): + t_arr = np.array([float(t) if (t is not None and t != "") else np.nan for t in temp], dtype=np.float64) + ax_stim.plot(s_x, t_arr, "^-", color=OKABE_ITO[3], linewidth=2.0, markersize=4.5, label="Temperature (°C)") + ax_stim.set_ylabel("Temperature (°C)", fontsize=9, fontweight="bold") + + ax_stim.set_title("Synchronized Operando Stimulus", fontsize=10, fontweight="bold") + apply_axis_style(ax_stim) + + # --- Panel 1: Ancestor-Referenced Per-Grain Strain ± 1-sigma Uncertainty --- + ax_eps = axes[1] + gk_by_tid = {g.track_id: g for g in gks} + + split_involved: set[int] = set() + parsed_events: list[tuple[str, int, int, list[int], list[int]]] = [] + for ev in events or []: + if isinstance(ev, dict): + etype = str(ev.get("event_type", "")) + p_scan = int(float(ev.get("scan_idx_from", ev.get("parent_scan", 0)))) + c_scan = int(float(ev.get("scan_idx_to", ev.get("child_scan", p_scan + 1)))) + raw_p = ev.get("parent_track_ids", []) + raw_c = ev.get("child_track_ids", []) + ptids = ( + [int(x) for x in str(raw_p).split(";") if x.strip()] + if isinstance(raw_p, str) + else [int(x) for x in raw_p] + ) + ctids = ( + [int(x) for x in str(raw_c).split(";") if x.strip()] + if isinstance(raw_c, str) + else [int(x) for x in raw_c] + ) + else: + etype = str(getattr(ev, "event_type", "")) + p_scan = int(getattr(ev, "scan_idx_from", 0)) + c_scan = int(getattr(ev, "scan_idx_to", p_scan + 1)) + ptids = [int(x) for x in getattr(ev, "parent_track_ids", ())] + ctids = [int(x) for x in getattr(ev, "child_track_ids", ())] + parsed_events.append((etype, p_scan, c_scan, ptids, ctids)) + split_involved.update(ptids) + split_involved.update(ctids) + + ranked = sorted( + gks, + key=lambda g: ( + 0 if g.track_id in split_involved else 1, + -len(g.scan_indices), + -float(g.integrated_intensity[0]) if len(g.integrated_intensity) else 0.0, + g.track_id, + ), + )[:max_tracks] + + color_by_tid: dict[int, str] = {} + for idx, gk in enumerate(ranked): + col = OKABE_ITO[idx % len(OKABE_ITO)] + color_by_tid[gk.track_id] = col + xs = np.asarray(gk.scan_indices, dtype=np.float64) + ys = 100.0 * (gk.lineage_strain if len(gk.lineage_strain) else gk.strain) + yerr = 100.0 * (gk.lineage_strain_err if len(gk.lineage_strain_err) else gk.strain_err) + lbl = f"T{gk.track_id}" + (f" (root T{gk.root_track_id})" if gk.root_track_id not in (0, gk.track_id) else "") + ax_eps.plot(xs, ys, "o-", color=col, linewidth=1.8, markersize=4.5, label=lbl) + if len(yerr) == len(ys) and np.any(yerr > 0.0): + ax_eps.fill_between(xs, ys - yerr, ys + yerr, color=col, alpha=0.16) + + # Draw parent -> child split connectors in lineage strain space + for etype, _p_scan, c_scan, ptids, ctids in parsed_events: + ev_col = OKABE_ITO[1] if etype == "split" else OKABE_ITO[2] + for ax in axes: + ax.axvline(c_scan - 0.5, linestyle=":", linewidth=1.2, color=ev_col, alpha=0.75) + if etype == "split": + for ptid in ptids: + pgk = gk_by_tid.get(ptid) + if pgk is None or not pgk.scan_indices: + continue + py = 100.0 * float((pgk.lineage_strain if len(pgk.lineage_strain) else pgk.strain)[-1]) + px = float(pgk.scan_indices[-1]) + for ctid in ctids: + cgk = gk_by_tid.get(ctid) + if cgk is None or not cgk.scan_indices: + continue + cy = 100.0 * float((cgk.lineage_strain if len(cgk.lineage_strain) else cgk.strain)[0]) + cx = float(cgk.scan_indices[0]) + ax_eps.plot([px, cx], [py, cy], "--", color=OKABE_ITO[1], linewidth=1.3, alpha=0.85) + + ax_eps.axhline(0.0, color="#94A3B8", linewidth=0.8) + ax_eps.set_title("Ancestor-Referenced Per-Grain Strain (±1σ Uncertainty)", fontsize=10, fontweight="bold") + ax_eps.set_ylabel( + r"Lineage strain $\varepsilon_{\mathrm{root}} = (d - d_0^{\mathrm{root}}) / d_0^{\mathrm{root}}$ (%)" + if calibrated + else r"Lineage relative $d$-shift (%)", + fontsize=8.8, + ) + if len(ranked) <= 10 and ranked: + ax_eps.legend(fontsize=7.5, ncol=2, frameon=True, loc="best") + apply_axis_style(ax_eps) + + # --- Panel 2: Fracture Precursor Scores & Autonomous DFXM Zoom Triggers --- + ax_prec = axes[2] + prec_by_tid: dict[int, list[tuple[int, float]]] = {} + for po in precursor_observations or []: + if isinstance(po, dict): + tid = int(float(po["track_id"])) + s_i = int(float(po["scan_idx"])) + sc = float(po.get("precursor_score", 0.0)) + else: + tid = int(getattr(po, "track_id", 0)) + s_i = int(getattr(po, "scan_idx", 0)) + sc = float(getattr(po, "precursor_score", 0.0)) + prec_by_tid.setdefault(tid, []).append((s_i, sc)) + + shown_tids = {gk.track_id for gk in ranked} + for tid, pts in sorted(prec_by_tid.items()): + if shown_tids and tid not in shown_tids: + continue + pts_sorted = sorted(pts) + col = color_by_tid.get(tid, OKABE_ITO[tid % len(OKABE_ITO)]) + ax_prec.plot( + [p[0] for p in pts_sorted], + [p[1] for p in pts_sorted], + "o-", + color=col, + linewidth=1.5, + markersize=3.8, + alpha=0.9, + ) + + for zt in zoom_triggers or []: + z_scan = int(zt["scan_idx"] if isinstance(zt, dict) else getattr(zt, "scan_idx", 0)) + z_tid = int(zt["track_id"] if isinstance(zt, dict) else getattr(zt, "track_id", 0)) + z_score = float( + zt.get("precursor_score", zt.get("priority_score", 0.75)) + if isinstance(zt, dict) + else getattr(zt, "precursor_score", getattr(zt, "priority_score", 0.75)) + ) + ax_prec.scatter( + [z_scan], + [z_score], + marker="*", + s=155, + color="#F59E0B", + edgecolors="#0F172A", + linewidths=0.9, + zorder=6, + label=f"Zoom Trigger T{z_tid}@S{z_scan}", + ) + + ax_prec.axhline(0.40, linestyle="--", linewidth=0.9, color="#EC4899", alpha=0.7) + ax_prec.set_ylim(-0.03, 1.05) + ax_prec.set_title("Persistent Fracture Precursor Score & Autonomous Zoom Triggers", fontsize=10, fontweight="bold") + ax_prec.set_ylabel("Precursor Score [0, 1]", fontsize=8.8) + ax_prec.set_xlabel("Scan index", fontsize=9.2, fontweight="bold") + apply_axis_style(ax_prec) + + fig.suptitle( + title or "Synchronized Operando Stimulus, Lineage Strain & Chemomechanical Precursors", + fontsize=11.5, + fontweight="bold", + y=1.01, + ) + fig.tight_layout() + maybe_save(fig, save_path) + return fig, axes diff --git a/docs/architecture.md b/docs/architecture.md index c8efe27..4788f42 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -6,17 +6,18 @@ This document describes how the repository is structured, how data flows through ```text BraggTrack/ -├── braggtrack/ # Installable Python package (v0.3.0) -│ ├── io/ # Discovery, LazyVolume streaming, AxisCalibration, DetectorGeometry, ImageD11 & NeXus export -│ ├── segmentation/ # Classical 3D LoG+watershed, chunked Otsu + threshold smoothing, experimental DINO segmenter -│ ├── semantic/ # Orthogonal (mu, chi, d) MIPs + frozen ViT / patch encoders (DINOv2 default, DINOv3, mock) -│ ├── tracking/ # Costs, Hungarian assignment, multi-scan gap closing, kinematics, split/merge DAG, precursors -│ ├── viz/ # Publication plots (MIPs, Lineage DAG, Strain fans, Precursors) + interactive HTML 4D Explorer -│ └── cli/ # Thin argparse entry points (9 CLIs) + reproducible run_pipeline orchestrator +├── braggtrack/ # Installable Python package (v0.4.0) +│ ├── io/ # Discovery, darfix/BLISS auto-calibration, LazyVolume, OperandoLog, ImageD11 & NeXus export +│ ├── segmentation/ # Classical 3D LoG+watershed, Poisson centroid errors, experimental batched DINO segmenter +│ ├── semantic/ # Orthogonal (mu, chi, d) MIPs + batched ViT / patch encoders (DINOv2 default, DINOv3, mock) +│ ├── tracking/ # Costs, Hungarian margin, gap closing, lineage_strain & rates, split/merge DAG, precursors +│ ├── autonomous/ # CausalStreamingTracker, velocity-extrapolated ZoomTriggerPolicy, replay baseline evaluator +│ ├── viz/ # Publication plots (MIPs, Lineage, Operando dQ/dV, Precursors) + offline HTML 4D Explorer +│ └── cli/ # Thin argparse entry points (10 CLIs incl. braggtrack-watch & braggtrack-run) ├── data/ │ └── sample_operando/ # Bundled ESRF-ID03 Ni-rich cathode operando scans (scan0001..scan0003) ├── notebooks/ # End-to-end demo and DINO vs. classical segmentation notebooks -├── docs/ # Architecture, quantitative benchmarks, figures, and coding practices +├── docs/ # Architecture, ecosystem positioning, quantitative benchmarks, figures, coding practices ├── scripts/ # 9 acceptance gates, 5-scenario benchmark suite, semantic ablation, ci_report.py ├── tests/ # Unit and acceptance test suite └── artifacts/ # Generated outputs (gitignored) @@ -26,12 +27,13 @@ BraggTrack/ | Layer | Responsibility | Key Types / Functions | Depends on | |---|---|---|---| -| **io** | Discover scans, stream `LazyVolume` HDF5 slices & chunked Otsu histograms, calibrate `(mu, chi, d)` & `(2theta, eta, d, \|Q\|)`, export `ImageD11` `.flt` & NeXus `.nxs` | `LazyVolume`, `otsu_threshold_chunked`, `AxisCalibration`, `DetectorGeometry`, `export_imaged11_flt`, `export_nexus_process` | `numpy`, `h5py` | -| **segmentation** | Multi-scan threshold smoothing, 3D LoG + `h`-maxima + watershed (or experimental DINO + HDBSCAN), physical/voxel feature table | `segment_classical`, `smooth_thresholds`, `segment_dino`, `extract_instance_table` | `numpy`, `scipy`, `scikit-image`, `scikit-learn` | -| **semantic** | Lazy ROI spot cropping, orthogonal MIPs, multi-view global embeddings & dense patch-token grids | `crop_spot_cube`, `orthogonal_mips`, `make_multiview_encoder`, `make_patch_encoder` | `numpy`, optional `torch` + `transformers` | -| **tracking** | Vectorised geometry + semantic cost, Hungarian assignment, multi-scan gap closing (`max_gap`), per-grain kinematics, `1 -> 2+` split & `2+ -> 1` merge lineage, fracture precursors | `PositionShapeCost`, `GeometrySemanticCost`, `resolve_track_gaps`, `build_tracks`, `compute_grain_kinematics`, `resolve_splits_and_merges`, `compute_fracture_precursors` | `numpy`, `scipy`, `networkx` | -| **viz** | Publication figures and zero-CDN offline interactive HTML 4D Lineage & Strain Explorer | `plot_lineage_dag`, `plot_kinematics_dashboard`, `plot_precursor_timeline`, `plot_spot_mip_card`, `generate_html_report` | `numpy`, optional `matplotlib` (HTML explorer uses stdlib only) | -| **cli** | Parse args/JSON config, orchestrate stages, write CSV/JSON/NPZ/FLT/NXS/HTML artifacts and SHA-256 `run_manifest.json` | `segment_dataset`, `embed_dataset`, `track_dataset`, `detect_events`, `report_dataset`, `run_pipeline` | All of the above | +| **io** | Discover scans, auto-extract `darfix`/BLISS `AxisCalibration`, stream `LazyVolume`, synchronize `.mpt`/`.csv` operando logs ($\mathrm{d}Q/\mathrm{d}V$), export `ImageD11` `.flt` & NeXus `.nxs` | `LazyVolume`, `otsu_threshold_chunked`, `AxisCalibration`, `load_operando_log`, `synchronize_stimulus_to_scans`, `DetectorGeometry`, `export_imaged11_flt`, `export_nexus_process` | `numpy`, `scipy`, `h5py` | +| **segmentation** | Multi-scan threshold smoothing, 3D LoG + `h`-maxima + watershed (or batched experimental DINO + HDBSCAN), Poisson + quantization centroid uncertainty & feature table | `segment_classical`, `smooth_thresholds`, `segment_dino`, `extract_instance_table` | `numpy`, `scipy`, `scikit-image`, `scikit-learn` | +| **semantic** | Lazy ROI spot cropping, orthogonal MIPs, batched multi-view global embeddings (`embed_batch`) & batched dense patch-token grids (`extract_patch_features_batch`) | `crop_spot_cube`, `orthogonal_mips`, `make_multiview_encoder`, `make_patch_encoder` | `numpy`, optional `torch` + `transformers` | +| **tracking** | Vectorised geometry + semantic cost, Hungarian `assignment_margin`, multi-scan gap closing, local & ancestor `lineage_strain` + rates, `1 -> 2+` splits & `2+ -> 1` merges, $O(1)$-RAM cached precursors | `PositionShapeCost`, `GeometrySemanticCost`, `resolve_track_gaps`, `build_tracks`, `compute_grain_kinematics`, `resolve_splits_and_merges`, `compute_fracture_precursors` | `numpy`, `scipy`, `networkx` | +| **autonomous** | Strictly causal streaming segmentation/tracking, velocity-extrapolated BLISS DFXM `zoom_triggers.jsonl` target selection, offline causal replay benchmark | `CausalStreamingTracker`, `ZoomTriggerPolicy`, `select_zoom_targets`, `evaluate_causal_replay` | `io`, `segmentation`, `semantic`, `tracking` | +| **viz** | Publication figures, 3-panel operando electrochemistry + fracture dashboards, and zero-CDN offline interactive HTML 4D Lineage & Strain Explorer | `plot_lineage_dag`, `plot_kinematics_dashboard`, `plot_operando_strain_and_events`, `plot_precursor_timeline`, `plot_spot_mip_card`, `generate_html_report` | `numpy`, optional `matplotlib` (HTML explorer uses stdlib only) | +| **cli** | Parse args/JSON config, orchestrate batch or live-watch stages, write CSV/JSON/NPZ/FLT/NXS/JSONL/HTML artifacts and SHA-256 `run_manifest.json` | `segment_dataset`, `embed_dataset`, `track_dataset`, `detect_events`, `report_dataset`, `watch_autonomous`, `run_pipeline` | All of the above | **Rule of thumb:** keep **numeric kernels** and **typed data contracts** in subpackages; keep **CLI modules** as thin orchestration layers. diff --git a/docs/benchmarks.md b/docs/benchmarks.md index d0b5d58..bc1e4fd 100644 --- a/docs/benchmarks.md +++ b/docs/benchmarks.md @@ -1,6 +1,6 @@ -# BraggTrack v0.3.0 Benchmarks & ESRF-ID03 Case Study +# BraggTrack v0.4.0 Benchmarks, ESRF-ID03 Case Study & Autonomous DFXM Replay -This document reports reproducible multi-trial quantitative benchmarks for **BraggTrack v0.3.0**, comparing **Geometry-Only**, **Deterministic Mock-Hash** (`mock`), and **Pretrained Vision Transformer** (`torch` with ungated `facebook/dinov2-small`) tracking, gap-closing, and 4D chemomechanical fracture precursor scoring, followed by an end-to-end case study on bundled operando dark-field X-ray microscopy (DFXM) data from **ESRF ID03**. +This document reports reproducible multi-trial quantitative benchmarks for **BraggTrack v0.4.0**, comparing **Geometry-Only**, **Deterministic Mock-Hash** (`mock`), and **Pretrained Vision Transformer** (`torch` with ungated `facebook/dinov2-small`) tracking, gap-closing, and 4D chemomechanical fracture precursor scoring, followed by an end-to-end case study on bundled operando dark-field X-ray microscopy (DFXM) data from **ESRF ID03** and a closed-loop **Autonomous "Scout-and-Zoom" Causal Replay Benchmark**. All synthetic benchmarks can be reproduced via: @@ -71,14 +71,14 @@ To isolate when pretrained multi-view morphological features genuinely outperfor ### Key Scientific Takeaways 1. **Orientation-Sensitive Disambiguation (`crossing_morphology`):** When two grains have identical 3D eigenvalue magnitudes ($\lambda_1, \lambda_2, \lambda_3$) and rotate slightly past $90^\circ$ on a shared Debye-Scherrer / rocking locus, **Geometry-Only** suffers a deterministic `25.0%` ID-switch rate because 3D scalar eigenvalues discard 2D detector streak orientation (`+45 deg` vs `-45 deg`). **`facebook/dinov2-small`** preserves high multi-view morphological similarity (`0.9035`) along true trajectories and eliminates ID switches (`0.0%`). -2. **Real Pretrained Embeddings vs Mock Hash (`beam_dropout_gap2` & `intensity_jitter`):** While `MockDinoEncoder` produces pseudo-random zero-mean cosine similarities (`-0.003` to `0.016`) whenever shot noise Perturbs a single voxel—causing semantic gap-closing (`min_cosine_similarity=0.35`) to reject valid re-links (`0.0` gap closures, `50%` fragmentation)—pretrained **`facebook/dinov2-small`** maintains `0.988–0.991` cosine stability across `45%` flux spikes, progressive mosaic broadening, and multi-scan dropouts, recovering `100%` of dropped tracks (`0.0%` fragmentation, `2.0` gap closures). +2. **Real Pretrained Embeddings vs Mock Hash (`beam_dropout_gap2` & `intensity_jitter`):** While `MockDinoEncoder` produces pseudo-random zero-mean cosine similarities (`-0.003` to `0.016`) whenever shot noise perturbs a single voxel—causing semantic gap-closing (`min_cosine_similarity=0.35`) to reject valid re-links (`0.0` gap closures, `50%` fragmentation)—pretrained **`facebook/dinov2-small`** maintains `0.988–0.991` cosine stability across `45%` flux spikes, progressive mosaic broadening, and multi-scan dropouts, recovering `100%` of dropped tracks (`0.0%` fragmentation, `2.0` gap closures). 3. **Early Precursor Contrast (`chemomechanical_fracture`):** Across `1 -> 2` grain splitting (`scan 3 -> 4`) and `2 -> 1` sub-grain coalescence (`scan 5 -> 6`), BraggTrack's multi-component precursor score flags the fracturing parent grain `3` scans before topological separation (`1.00` top-1 precision, `+0.56` to `+0.64` score contrast above isotropic control grains). --- ## 3. ESRF-ID03 Operando DFXM Case Study (`data/sample_operando/`) -We executed the complete **BraggTrack v0.3.0** pipeline with real **`facebook/dinov2-small`** embeddings, multi-scan gap closing (`--max-gap 1`), interactive HTML reporting (`--report`), `ImageD11` `.flt` export, and NeXus `NXprocess` HDF5 archival on the bundled 3-scan **ESRF-ID03** near-field PCO dataset (`3` scans $\times$ `100 x 250 x 250` `uint16` cubes, ~`20 MB` compressed HDF5): +We executed the complete **BraggTrack v0.4.0** batched pipeline with real **`facebook/dinov2-small`** embeddings, multi-scan gap closing (`--max-gap 1`), interactive HTML reporting (`--report`), `ImageD11` `.flt` export, and NeXus `NXprocess` HDF5 archival on the bundled 3-scan **ESRF-ID03** near-field PCO dataset (`3` scans $\times$ `100 x 250 x 250` `uint16` cubes, ~`20 MB` compressed HDF5): ```bash braggtrack-run data/sample_operando \ @@ -91,25 +91,45 @@ braggtrack-run data/sample_operando \ --export-imaged11 artifacts/esrf_id03_dinov2/esrf_id03.flt ``` -### 3.1 CPU Stage-Timing Profile +### 3.1 CPU Stage-Timing Profile (`v0.3.0` Sequential vs. `v0.4.0` Batched) -| Pipeline Stage | Wall-Clock Time (CPU) | Share of Run | Primary Workload | -| :--- | :---: | :---: | :--- | -| **`validate`** | `0.043 s` | `0.1%` | NeXus `/entry_0000/ESRF-ID03/pco_nf/data` discovery & SHA-256 verification | -| **`segment`** | `13.48 s` | `24.4%` | Chunked lazy Otsu pass (`LazyVolume`) + 3D LoG + `h`-maxima seeded watershed (`[18, 17, 15]` spots) | -| **`embed`** | `18.35 s` | `33.3%` | Lazy ROI cropping + `facebook/dinov2-small` 3-view MIP inference (`50` spots $\times$ `1152`-d) | -| **`track`** | `0.024 s` | `0.04%` | Geometry+semantic Hungarian matching + Jaqaman gap closing + 4D grain kinematics | -| **`events`** | `20.23 s` | `36.7%` | `1 -> 2` / `2 -> 1` lineage resolution + 3D sub-peak & `dinov2-small` patch-token dispersion | -| **`report` + exports** | `3.04 s` | `5.5%` | Self-contained `report.html`, publication PNGs, `esrf_id03.flt`, and `esrf_id03.nxs` | -| **Total** | **`55.17 s`** | **`100.0%`** | Full 3-scan operando DFXM workflow on CPU (no GPU required) | +| Pipeline Stage | `v0.3.0` (CPU) | **`v0.4.0` Batched (CPU)** | Share of Run | Primary Workload | +| :--- | :---: | :---: | :---: | :--- | +| **`validate`** | `0.043 s` | **`0.044 s`** | `0.1%` | NeXus `/entry_0000/ESRF-ID03/pco_nf/data` discovery & SHA-256 verification | +| **`segment`** | `13.48 s` | **`12.23 s`** | `25.3%` | Chunked lazy Otsu (`LazyVolume`) + 3D LoG + watershed + Poisson $\sigma$ (`[18, 17, 15]` spots) | +| **`embed`** | `18.35 s` | **`15.70 s` (`-14.4%`)** | `32.4%` | Lazy ROI cropping + batched `embed_batch` (`facebook/dinov2-small`, `50` spots $\times$ `1152`-d) | +| **`track`** | `0.024 s` | **`0.029 s`** | `0.06%` | Hungarian matching (`assignment_margin`) + Jaqaman gap closing + `lineage_strain` & rates | +| **`events`** | `20.23 s` | **`17.80 s` (`-12.0%`)** | `36.8%` | `1 -> 2` / `2 -> 1` lineage + batched `extract_patch_features_batch` & $O(1)$-RAM `roi_cache` | +| **`report` + exports** | `3.04 s` | **`2.57 s`** | `5.3%` | Self-contained `report.html`, publication PNGs, `esrf_id03.flt`, and `esrf_id03.nxs` | +| **Total** | `55.17 s` | **`48.44 s` (`-12.2%`)** | **`100.0%`** | Full 3-scan operando DFXM workflow on CPU (no GPU required) | ### 3.2 Detected Lineage Events & Persistent Precursor Candidates - **Split Candidates (`events.csv`):** - - **Event 1 (`scan 0 -> 1`):** Parent **Track `6`** (`s0_i5`) $\to$ Daughters **Track `32`** (`s1_i11`) & **Track `34`** (`s1_i9`), intensity partition ratio `1.434`, mean daughter separation `18.64 px`, **DINOv2 multi-view cosine similarity `0.7561`**. - - **Event 2 (`scan 1 -> 2`):** Parent **Track `21`** (`s1_i1`) $\to$ Daughters **Track `36`** (`s2_i1`) & **Track `44`** (`s2_i13`), intensity partition ratio `1.258`, mean daughter separation `20.11 px`, **DINOv2 multi-view cosine similarity `0.6837`**. + - **Event 1 (`scan 0 -> 1`):** Parent **Track `6`** (`s0_i5`) $\to$ Daughters **Track `32`** (`s1_i11`) & **Track `34`** (`s1_i9`), intensity partition ratio `1.434`, mean daughter separation `18.64 px`, **DINOv2 multi-view cosine similarity `0.7561`**. + - **Event 2 (`scan 1 -> 2`):** Parent **Track `21`** (`s1_i1`) $\to$ Daughters **Track `36`** (`s2_i1`) & **Track `44`** (`s2_i13`), intensity partition ratio `1.258`, mean daughter separation `20.11 px`, **DINOv2 multi-view cosine similarity `0.6837`**. - **Top Persistent Precursor Tracks (`precursors.csv`, `min_persistence = 2` scans):** - 1. **Track `14`** (`rank 1`): Active across all `3` scans (`onset_scan=0`, `peak_scan=1`), `peak_score = 0.8789`, `mean_active_score = 0.7775`, `max_anisotropy = 5.45`, `max_spread_growth = +106%`, `confidence = 0.8555`. - 2. **Track `34`** (`rank 2`, split daughter of Track `6`): Active across `scans 1-2`, `peak_score = 0.9023`, extreme streak elongation (`max_anisotropy = 26.78`), `max_spread_growth = +129%`, `confidence = 0.8119`. - 3. **Track `27`** (`rank 3`): Active across `scans 1-2`, `peak_score = 0.6710`, `max_anisotropy = 16.00`, `confidence = 0.6534`. - 4. **Track `29`** (`rank 4`): Active across `scans 1-2`, `peak_score = 0.6668`, `max_anisotropy = 6.67`, `confidence = 0.6490`. + 1. **Track `14`** (`rank 1`): Active across all `3` scans (`onset_scan=0`, `peak_scan=1`), `peak_score = 0.8789`, `mean_active_score = 0.7775`, `max_anisotropy = 5.45`, `max_spread_growth = +106%`, `confidence = 0.8555`. + 2. **Track `34`** (`rank 2`, split daughter of Track `6`): Active across `scans 1-2`, `peak_score = 0.9023`, extreme streak elongation (`max_anisotropy = 26.78`), `max_spread_growth = +129%`, `confidence = 0.8119`. + 3. **Track `27`** (`rank 3`): Active across `scans 1-2`, `peak_score = 0.6710`, `max_anisotropy = 16.00`, `confidence = 0.6534`. + 4. **Track `29`** (`rank 4`): Active across `scans 1-2`, `peak_score = 0.6668`, `max_anisotropy = 6.67`, `confidence = 0.6490`. + +--- + +## 4. Autonomous "Scout-and-Zoom" DFXM Causal Replay Benchmark (`v0.4.0`) + +To validate online closed-loop target selection before synchrotron beamtime, `evaluate_causal_replay()` (`braggtrack.autonomous.replay` / `braggtrack-watch --mode replay`) streams a 6-scan operando charging sequence (`3.95 V -> 4.27 V`, `3 min/scan` cadence, mimicking Ni-rich `H2 -> H3` $c$-axis contraction) strictly scan-by-scan through `CausalStreamingTracker` using real **`facebook/dinov2-small`** (`backend="torch"`). + +The scene contains three competing reflections under a strict `zoom_budget = 1` acquisition budget: +- **Target Grain (Track `3`):** Develops persistent bimodal mosaicity across `scans 1–3` while drifting rapidly along $d$, then fractures (`1 -> 2` split) between `scan 3` (`4.21 V`) and `scan 4` (`4.24 V`). +- **Bright Distractor:** Higher integrated intensity than the target grain, remains isotropic and never fractures. +- **High-Strain Distractor:** Undergoes larger rigid-body lattice shift $|\varepsilon|$ without internal mosaicity broadening or fracture. + +| Autonomous Policy (`zoom_budget = 1`) | Zooms Fired | Pre-Split Capture Recall | Pre-Split Precision | Lead Scans Before Split | Electrochemical Lead ($\Delta E$) | Velocity-Extrapolated Setpoint Hit Rate | Mean Causal Step Latency (`dinov2-small`, CPU) | +| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | +| **`braggtrack_autonomous`** | `1` | **`1.00`** | **`1.00`** | **`2.0` scans** | **`80.0 mV`** (`4.16 V` vs `4.24 V`) | **`1.00`** | **`1.39 s / scan`** (`max 1.71 s`) | +| `brightest_intensity` | `1` | `0.00` | `0.00` | `0.0` | — | `1.00` | — | +| `strain_only` | `1` | `0.00` | `0.00` | `0.0` | — | `1.00` | — | + +At `1.39 s / scan` on CPU (`< 1%` of a typical `180 s` wide-field scouting scan), `CausalStreamingTracker` leaves ample margin for diffractometer slewing and objective-lens insertion while predicting velocity-compensated `bliss_dfxm_zoom.v1` motor setpoints before grain microcracking occurs. + diff --git a/docs/figures/operando_autonomous_zoom.png b/docs/figures/operando_autonomous_zoom.png new file mode 100644 index 0000000000000000000000000000000000000000..a992df2792aac20e3760415256eb5eff78122a3c GIT binary patch literal 268687 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 z zb6WYo#g%o_qaUUnPlDS^+-r#Z^`o~Vo-;K1JLUroA?Us5^Ge1zu=(q*=WZ>s`aYttJkLT39hbwcN{A z{|7F0nLtf$t#FDl*zq@e$k@)h>o^CK&C;To{W+)P#OqT($Z(vDCE_)W#U3`Plk-z$ z6k-yBo9b=`i&W_1*`L6NH(JC+U%++U__DXAW?8QHRU>{l#u{f(jWdt%!}Ynu?80E@ zr^@46x8G!V>uqo`S^blRj%P%!DEA_TlfgW_yj-W-*8HdX%u~=(f)qm zjOZ~)!ohEaO@QQ3AQrU->$H!V;Og2he!8%*Q0m8k&hKOpF!`V1%mo z4{B>AF!6*S7C38E{h+U}Pl&}-Nt2TjTwQ{ol{ew!U6#v%NpL$}g=-G^@!ihFUyh{T z{Z`?{9ba^*pZ>gx_IEnfzbRz99HSk-*n||NBMbt?8$`a{^B@b?F+#tp4Y!vH>iBu{DYCTm%a$cr+Y|Y6<6mpdG_ZpkZP{f_s zE6(3BLZ1};T5^E0`$ah72KU|3@uuXv?;f76S(>OT2&Qqr?;`mLooQH57xXCk&d6Qy zFMaQtmxga7CP-P2TSFPC^Frd!VOIjC5`evSAf+pZ>^QbW2}qR`TS+2+@ova51GEqC~dNXiA(3Rf(8dR9k?acH`vxo&^5ZSTFHU_kwIp5m03q$2uW(X_o!1Qd=< zj@^8&Ax&5^2^T4*-*7j3^!Z}4ol={xjx-s4^63Lgaw6?BqXY(CPA^zv}rR7DrL52mAc6Y3G?%eHx`9Z`g@ zK|W=6W9M(MUqtK;XW-Mg;Nk>Sha5k*>w@K4SkYz5 zMT3UPmA7tBOn%r${Z($EL5ZLnjQ?%69G-ljsUDb`lK_&u7 zA8e%JkWaqv(bDonT`F|)W5FFG9QHegX>r}*B1iV4%psqX!_<>oW@cu-yNIpON4K&L z@P<%wb{0gIFxr}9m_(`+;lq5y1pJ^r83FbSEfS zKa2L_T-H+f{6&((*{L!qhMYo8Lqpb6`-!B1deog^$>dKqz;C9!dtiKZJ}+r zJXRfdgYky-(mJnx1z6NT^XWX|j|Hz&TY+@T(AP3s<3dX147H9rNLqg@kq2pa0!{&xj=PmPZE=~=YpLc z(GTxP60?z#z?&g_4b?ZXOI-=IG$c6s+Pm6TiOFK#TvGeKQ(C~d_JWfn$9KuL*88M9 zxJ9L=*AF!{V{LFG5lYd;keAs(SzcO}oFS}HXznXW9&(9T5vx~^$j58GQW4K%U98Jg zMa@(ztsRNc>SJJ~@hYiUyRPsfiI?v%$hzJ#g1DPVhvsj8-i?CEZY&)d6&29DShyUo|*#atH)y3pU=-#U8khY%#NYR!n| zKz;Yf2Lnox=*>f?O#)Q?tkaeM0ZgJEGV4|`+u#KbYSB&S8V2W<(!D@KOjm5*az2va z1wt&G?f8<}UhvTCSy%qt`kox5&2|LLS>&oZ)Z39j)qT#)%*d(=%tAHz8FDwg)e#d{ z@wxVFYG%WOotyhZ&F}Sl*de}YX-&JmD!w6mPzr1TY);8Pn%@c1Td1Gk+JFi{#|Vqc z5cvGcCTEfU;jTU!|C*BO=XXb^qZR@h32}qOray^t7ky!+;)$*>Te6RPoSgHAizT_BJuU?H3z!mj`-r@GP+o6xN@_hV(D;Wuu<0)HzUFVvU zuk-aKe_Oa^9-M>C&tp@Lw{iVT(sfWA#Ls-q=sBl|wA*pfuP&s2U%kjj5TQv$Ae)C7s;VOCODwo{+wXmSno&-e{ zJ13_UDHl68bk^dFqKqZRBdyFlnW(6!YEA;PJx~5XM^ zw<3*b32DLI4wa~J>Dp*^t<<9ol;I*r73E--i$Zxwgd1x{x8>{eJ4!^ZE_{l1M>hW& zc_^WW67wJW6w6UmzH5P_+MXn>&8WH$aZ7v8&eXt@bm@tVefq3BNxP-#n>{;sYl7S$X4+m8K1)UZ#mQFH#eL)wNzsz ze@)D4SzpWT86##PGMpKAknUb)KDbbt%fDV4{-&obbC*7)eSXG$Ev~<;IWtT=rTkjB zPj2S#tz2ryW$Pcu!I9Y{uXiO5R_7mvQSRylQESc=I9?JF8Fsi5HN7DMJM_fI#>SBL zxA!5Mfg#pWPt>Zp&uR|#u=U4@Bpz*OWBG{3pW^UPdR*pUX%S=y`XqeQ4z>~K9!fp z#l}7tw}gHqSWsdJ3DZ~in;IEi=7|dp4-Yqa0)`ppQE%Sd7NSloEOe~5B?|Hf|3Hkl zZ{LPMy=apBaVGCRET;NJjzkB-;>r|c_)Z2`AK5@#Py{n+Y%*-6EC2>dBdgR$2 zWxC9xM<3DyZoW71sVzRET`@-g`eq(y_n<08`Zq}HZNK9NTJX5mv6#=;2g~&3s9HxpVDT6E$ z!_wB;-~C5$QW7n#GTYdg{_onQWzYh-cvDgN*9N7dSfJDfsO!sl=&0azf-+`h^S9A$B@BIg_Ew zN{w}~PVDz5P$_m#s&J2O;RR|oE;N}FnwEk6_!_8XN4FwY9|p*w_D4Sao7h zR{tp(RHw2ZT2|L-38|>0UWRURa9n*?@%eQKS$l$*D`}-D=9BS1#W4_G4kt)n_DAxHal5S)8=iP5*cfMNMSVK#Sw%Fjo z2=zJmIf!J_HaR5243QqbUQeEc5AkMFM>+^xyE(&$Qr0N0`{=z>Jz)kG><74;Jc__9O_vvFE!szElfjK&*m13-0EqPYPV751SUKUvr&YwvOQI*Z%m?b9?i9$=3$?8ja*H-klZ9m0uyde$0Cx zX;=_$sKou_nrp}9c8Dg=w>T zlFY;zD3)QDXU(Z&SS%W>S1Zu>^*qUNJ2gkBhksHomxlMx&*bItP}9)hF8@EW2$TZD z!#be(z*&w{|C>w7Aq@LI{F9ZHb-W&)^z;G94WMOO^grbWm;l6U07dG@qN4Ybj=I3PrC-3z<&!b+_OY8{f%fx z`0Lj9yhFn5Nl2(}oN}AW>danDj9AyB+^)O}m|)0Z#)S&Ik|KE=YPBw=1I!|%yOOT4p1?7W=m0EIVuN!#0BX0r3X z|6DMcv#)5T?FgYuUSZ4ltwqmL?DvNQ;~jm8S$pVkohKj3(XwVmuKo#Hpr;Zui1&4jXy~)D^4qe?vaXw**#0uuL}w{mxGx2wV6BG|05ncceAu1= zf_LxEr?6&V<#dA}c} z>JJB0bq9jYnp7m3@mf2&-UHg->@{w0zqhZ!!~VX2QPW~2^_i`nWr{#4g?79x zFa6Ql5SYErQHU3G%#RjK+tUc()884)sKL<=fK3+WE+_A)D*$5Orflk1PM8+1T( zw6DoUs}yJi8}9}fSlOjV&%DoxKOCj~=Jutv!kGH61O;R~bR?la3%Ys+9+H$dG|#D2 z(|9_nkj=-KJMI*n=ShwY%DfbO%1$TyukENsTRa8F6ul%O?~QYo8S7AtFEfJcR%;Sy_fhvd&wt62eZVD z7`;xMtEUK6dpm39eoOp*2W#PKVAsAO4UG?-@dIUQcizPMKhF3YBA2LCMOp80{8i+PZ{1n8?Vj#9Y_q$ID`mZ)2@{Ch1+PezC-<(7JU4lr}`k=Qz+wKsVc4 z(qFiGH%CuZLCsm=!JO$^A_VgAa=%}8sCXyw{rqKdPKE4C!L9tpwxuOfJJ;;6^0uCM zq)ihY7vx9hIppM<4uTAMPJwrMW+ZWi>M3RPGqQ6sw-O0?$WYZd>V8^3BN9p3?29ejU zJh7;ksa-)~Uz3BKQ{gOuckS;_o$^tT4IhL|-9w3QB)wlVp-j5YAGF0fSMV_pD`G@m zcaZgBNc4h0u(t4luGii#v~@!48al;{%wwYS46V-I4Q2m-!*R(qRslbok>(;Un-S%0 zb6mA~EZhMA1GY?~2veqJ|u$GJLv_xIy+wu6O*kK~6t!mpCvz6IA=Z;Dl07)-kwG`MJ{pNe1QqTwTmRq961VW)L+bgCPe%V#;*#{>Ls zFtjy(<5%k-!>5I`h#$Q3oySsMn;iyo4aCNK(-(|U6 zQzQ|w?12WQ02&^kG*DhDgzhv-f(E%nh;Bg6pj{u=#Wj8OCM^a> zLd1pf;hnqgD$up=s#le9CH&hi{nW|9jEV!9h7buW2r^(#UE|8ngbF4n@?g0TSK4## zqJmrXj*Ca{zVNVJ@8X>eY$tu>nGuAES45Si*v8Up1L+Aav-R5401%C!#bdnHT zGarM^HAS+xOhHsjb$7RNmR~7tR@SQS|Iv&*dB)c;^-RX`J|@x1tLTd##5gRlP<&eI z^oI96pM6nEM#eBWy{JQmgp1D$a&&ah7-IR#q$ed=Pb%n9pxpdU+#v;cAoXSVh zMIl2ddLa=m`iQ>1J|!KUs_t<*G^oRY*#K<)8?cE&f!KG__aFd`5v|lyz84zG!O3~A zRkO2?VeevZO4audP1whKG{| zCzJ;AFV5XN(74LZiPQ*R{Uj9Cq%{S~GL`RLbu^!gteft@;)#g4Sr-TD6zq<&g_pxF zvRqYFXb(D^>LnddTLb+3HT$Xe1H|i*&i5*x$^)S-=D%h0@!t+f%sJXo#}+z0hX!m5 ziEdaO6=?KVcH&evI5yb!F`IbvYd8**BTdIDKJ}m>reJ81$H}2UtV(C|QolfxMfF{l zn@UPY_p>kc|1Q4?4-@jV1U+$D+U=M)`bU}2^(iT#Om#~M34TQsgm3ZALp`-uhya8x zR6PDrJ9;(Fg%HY23&-E^5@|-kUxs#lm=mwo+R~G2s8b8JK1lqSdIQH5W~M}k)c&5| z;?`!vU}$X201(#_K7#z9ob$M#Kq4rSBBroF2*2E9MpNkZMdJ~n(h}CMXXW69xRjGt z`<`T^ELtGf@37|MFayi+n>Xaqsd1r3R|%MzoXQ{+y2Qy;;Y(E%Bv}Y!4{6YR(_^>~gKKc+BI@n{6oXY1lY?^HlOXbOoe2|42m^4(ylb^SyKn_KE0qg$*Gs ziblZY@K^I;Wn|KAptbE)cpKhU$>P7rg23>j6#734|7rV#mq>|ZUAhT$41InqiX6IE z`XX22@H1wL(#n$AuB&g%JvU#jy+mwd^JuuQ(O}%l+(({uhbyt(tZ&Ql*H$=^l#(#9 ziDd7*wt5TnuVS(-3zGml$c^O#Q{rzcxv5iz$)J-$CPI!{LlRH?~v&*fuDsyA=90*X)gv#6e zUP=&^$hB>Vw7SqdF6ImWKfZzKi12sIi*X%kgu;KrR_k4mmqGxc_Bosb87)e&{m;fx zA_Zxw%`mgDBtK0MroorT!c=x-f|smc+meMgIfx~Tp}(j|&}Y=vKF>0=^e8UH={49NSU3Jm1` zUle9qQMz--^Dy_ZPi^hXxm9+@k>)ZZcM~?=RV#CIM~sYfqK~3oEFPyeQG_;G+S*=$ z+I(KyP1xJZOYY<7Pd9LU<$>S{HTG-ks829rxIIdDA}^U<9EeV?;xe zR=VfJIGn0_$CRZC3SI$#Cq3U1Jp8TSWJ-wp&@MVKoG;ba2Ul2FvxjRE-NE`-{2bf& z?tguU(<->rdYNFW&-I}Mw6(hL)<|0#V#N|RXwA>87)#KpD>&G;O;kS#}-xPk7 z;T9ZG0>Ru>N&n#~v>EM060UueO*L3AdP#ItqV82dnsx=PiEo<$O7Z=G;fRoM`R`nf*LdVe zyZro5n5BMUJMvKqrV`oNTbBS$G1$SKQuMJSvK+FAbmUEgDFu=HNpG4@Dm|_;NV=b? z8`48T=M(RbEdQ&4o*nMB$1bQ?3n8T&ItI*Ir4+OMr^fTFNYhs6SsqJYmQEu%&VA~8{tG3_cb>u zuRd94ao|bkm5{;DqEXPa4tD5Vm!%qP8f$Zq;^rAxy??z@6_SUv$(m0d+OH%WAF?qWJy*3b6PQz}*su6A>GO zWOY*=2D?I_U6Rh^7Z zi!VEKvC)M8=E{oc-Vs#EO;_5?{+AM@$C(li%m|cQjMeI!b;${oeza+$~h1^2eeU}2VGNKC5 zrKF&NidOD@C5uyJn`kNYHpZuniOJ+SoE6$!HtP8WrE7;CE0-S+qqKyz%EAa`KMJeZ z<;=|mTr%}k^ya~GPC84-NFu!3enbo}RA7w(bPNq@PjtOkvQyWH>7cW*xJUz1@F$*`FhiNlSIxG+9rB%rT4%}>>LL+xf-4*z>w6-!<> z|68FnyG%0DM*usFt7oCD5oP|@hbx1*pKNxc-0#r)>Fd~((_GVl!$kvmEiapEc5x`c z)QgT1&2EViB7EN9q$fz3QW!!08$Boc82Ix&@AGOS-wr=9E{yhCcIap$LgJ>Urvc3i zKv@9+*dnxIpCK#@j6-Q{laE!`k}hbxRX4H}to>T6zkV(`ou{_KiH-QsmBF2h2aTGK z$r?k}{nK+yeL7hOhcm7D8@0jDII1uOT+j!#Vqs3fuHa^IF4_bnWiq zJKKwaq+xfot9|-f6@TeN_W&sDn7G*A`43bzV(}<{}Xs2+kE184<%f@C={Hr(m4MNJvNL9RhAs!n8mIg}OC5VL6lrl*_ z)%#S;$ztaHhq!vTFNKwh^Sdx8APgTo!nxkfi z&bZXCX!>Ia}nK4MG znxBC0dAP%?6VI&+(z*;Y!$a8K(>3Q5J9_T^y`C9@R}1wGUv|bj4uIFh9Oz0Gzb;=) zA{yJb08Md<3}?lYECBzMKjb5e)jEr;R!S?JlsQhSvq?sf1eDYSldGcTOwR^HeTW@` zyihh1r9oY~ZUv5g8d=tlDdTS5>uLz63wN!QVUR+nQpnBOlIPD;^Zef-g5PJ8# zlPIm8WOXpmXhr)sI8|(OjIEXMP#9PRX!5$T2Xda_5p^9KQ*N*FW3@AH{7dGT?3e#~ zYn>;*eNi?LfG&tSfC>n{+x{T=qNunHL13^BIsQGYl0fcZ6uDzZx=>3?{~2kR$b}I*3O>cN0nT5&^CfZYDP@D3iHu+1FZD9{{#)0t(Bq;aC&$#IDPV!D56wcOB z!r`|vJ}Ui>s}^%$j9LUy4Ycb3>L)v1W)i@Io4e6bX8UMj;wy7DanZIa4VhD~=dW1j z0-Im2bX;U@3#Mwb=O7d{T7{?jPl9~IW~eNbTi30~bBSnt$Q`4j=*~=Kx=M26izrXJ}Ues&svp$w@ z-E@XT)LPpybTyAh!mb>OGLyTWjL9cnZ9*W76MWo9Rru>=v%E7kwA7HcN4(j_nC6c2 z(uW6j`g(VitG>o$-1{H5SioVuTYPOD5qBf&34!4#v!OEBYu5xGN`AW^L7cMP_doz& zth)qUSkT}^?-+v+MuE+G6|IoVZLLLtHV2w`lU+tn6B9Mx3d4?{$v{s=2}CUA)hZf+ zu}9=ZlC{TaPml5scn>HhUZCQV8>!Ny`uNtX2?g|UB>5pvH$~HAEre;u;|RISd943A zLbTo2yEv!w(k>~s%B%cy`1Bu$IUuVsVKpLQJ(S38uyqy0s#8GLr@@aCAK1=04VlH{ zX#WrFV`Q_gI)$hf$tjje8Nxr;(WOB!-)Hg%o6v?-2CHtM>A*bB;g%V{r_{h8)ceAv zu75(FHN?`v8y;P?A814~zO=z-vajy8JgUS(ExFLL=Pi|2vHZa(F$kh&5|#L{!dgSv zQJmnsK{S~8a;Fe?<~595 zS}&U!7A`o+7$QmxXk74_G!tOJqKxO5M*b*pTtaLRJ$I*q}Ch>rZW_FpX zGdoFsc2rw2QGg_eg%Hnv5Oz&?} zXn;KPh-};7pl7WQXw}gTuq;8ok#>#caY5I8(6$RGLN@k)4@v$EK^(=}ivTR1js-9v zX__5E+%}+>pkjx&xj23Yq&(*a2XmypwI||^RMc7m#BGcD4dV6GtkEQ!xh|!gM|}BCLbr=-6uRX%> zYj}4CH%b6}rRXEzuP$j|{u>1Q%ZqFMfz|rD=DOL2pF#Rk3jllf=i74qlUSi_52kmD zN+3-pJdyFY6l%{K^MV%|SGR1{bYxrq_wT?U+e4u8W$WKLk#Eg+fBIB`*ZnTV%+z%K zm?m%TXutr5t8wY{^-cG^caIV*gz|!0D@;ckx$%RnvhKWm<$T+RH?`98ygOI!q`U58 zPd9~Y0SQ(!=ILbTTNc7bDim9{#Y6^2WgOGv{1joxEm{3PG5u2!%qRwjGu(A1T=L+c z5wWzhTRjJCPq=PaG z8Z%K<<5`cQov4ZfpqUTr<^LNjbR#j0y%hfI4Hn{$DKXP1eYCTdg2K>3? zjNDGc6*|Ipq^2xC0BIcQKcsP_;TpkVq%PiD*uN@OV96vE2Xju1R;(wC9xy>R;=a5} zOu0N<9HGS}Y=c&LtExOZn$Vdj9@<_h*w*%aI}n1>-6GEpXaT9u}cd3KVnKfi6JE$06aQdjc}F8g-+uMFz#-DNpBIVT5*8Vbyg zwi?M)ej8keZN$JuBlr~=RFo0b)E+K>WXcBIiSVekghl9B*OE0_ z3E!k$1QAITr4URo8FrNE+YA*&cj>yXch_QR#a`nwNlb5xX(J0iOJLqppE}DBTX>3N zO`#q6D8v8msJWQ}1-apf;Td6JAeg3S-QQ|!EzYk(%_PPxotbKZ{A%S-D@&SJyv}E^ zKs<%TWGg2=Jt>mNLTD_zx?dkc_v`Yrv$5(yWUH<&Bu0kF3rMKYO#Gn}wz+6un4Le4 zrO$E4ChXNy=1F|m2o);FpKAVShdWxUrDW>VtD^kL4ds+HAyzFGM%LzAW`}LW!YXWSCwzr;BDU|xE4W*~8C-ycUfi#%kVM<3+egIV; zT*{#;D;(pY5Hwdb8z0q%G}yLG)wiDR8D#4X_fFJnNaK~(XS;ec`S5e13*J*jRHLrr zvOcAmffQu}y_doxckfyk=T|2B9!}_cAN+Xgz5P|*`&UvC86g#KO*GVuz^!itu5P zTUHCEJ;CbWX9N73l6JO< z!&UpT^@bfp!uDhG`cF{>glm61kSG7f*@Dl0)y7;g_0@=EpzzNm<;^WubHwZdnpCZ- zo8I(Nj>jx^`VYFd00XYfJ$@^OqP+9r$IV+7FAObS{RDc3UXUZ(GmPb*dSBqrQJ?e? zSyxvV28_YNd`0Hx&-F!ct_N?Jm@rH4e~;Mxk?+%l&s$T!IolB-u3>M_3qw&?@@x06 zVt{}hndAj87{o#c_R%BLtuWQ<^A(nzOHHGb?ruEworBtJw6-D%>Yz!d_zcOPmV7qV z_FerKFA?B?Gm+0NeSJFkgOL5{Sg{|qzC5`GL!xIV!M-g69FMit=&r+d=z)n|V^}@G zrCr3*CP<1v7{U7!B zNQg~nq-v|ajdlcaU2DGZL+5vu_^B;z5z<93YJ^~X1kPS9XVD8>_q{|uHMI*qvw6q>XUfz)JaAm8HnaF1E6JB0FN zXYY7zOK{ZN!-%7tm&XE>{#Ievdml(SFn&~d?mtBqcE`%vn)w3WZwlJKx;Rr)#IB%j zLZZ>Wy#E39T{LcalE3XO&CYa589X0&6y51^N7PN17_KO${Pu1W;&7G?-4$Yx#im&@H-)RnqZkfLGYw2Yh7V7dsn?%X5zeQiuP^0Z#XX=?MrP1)I5tiT< zbj?=xv25szT=BuGrxeM_`Y2%^Ww&RZZ$cbo5d6;0+rX#hC0{9M1g)97>eoQ9iI^$2LP=9OUlX!yyEr|+?S1CrP zE)|(AvwW?NBJ0(*VjqR2J+lKHI$0yR3x;$C8Z1)By004yb?7T_R+#zlFRaFlrSZVx zrk|o!0XNw%Qva5!J2_gz#5;Q?$@h4#g>I>8DG$Ank=hJuP#DIC8DU8#bka)>PpMVk z2?B&`M>^5S&De4yd_PVJz3}HJV?#G$2ikDSV;l~qonlqmMOWs<$T&_Gpn?rq^Vz9B zmG-wqT|vfay?@FRXBW0jO76iti5pK-%QyHwgX9@WTx>KWixbfTL z?@yvUaV*RO{w0*mmXzI=p9F#FhhqNOdkQZTG~s-yidwJ+1ni-N!Mqb#zYP&YfHV0~ zp`&e6Z1?D=&Z%{#jZN0@lgg8xYR~o3qtUX87+s1t(Mx?4l@3lk6LpR}J$AY1d3)@=zPvj(zwje$ z1Ymw+aA6sth;v-}Aiz5FiMYc#^;HZpFs)Dp=jfJ)_dH#79(CzcLI97R_ePURSw!sV z1t;uwh%0&T{CK+jc};@V65>7>OkBRs%Wh&^wo?-OYy}~x!pDv<{q?=JNkW?fZI7c_ zW7I_5S>HI5aZ=9Am=cc+A_18x%Ye;Ir?3nB6ZM`*<0eHLZ3d_CvnG?c?ME?pNBrFeag5*h6uM`no9qtg-Mj3rVy91F6B0HoISOP%$28}9L{4XCJKiEutBwq&i@j|e}2QTbpu=` z=_7(1M7$Nf0;i}gDlVBn**yr&Sl^*gF|xK5C(f5@_01J~W`+WJ0R8uQDILH~2-=c5 z+3VRthJ)EsJp90b&gxrn=Jx7XM_k>ZSuITIJ0bQCV7iwIM*b{D%}gzD6L-C#)cHrj znItw+wh%mAvaOROo%Z_V37TpKvJatJ~>7M|6;3ST4i3mp| z=!n?*GL(#uN3|h~wIvM+uJ5^Q4`lKw;f|M-{P$08y?d&2;+*`VwlxH^+0ZNcNoUgl zI;Xs3wXe^&DHH7AFg_nh5Np8t2Shp9jKGR&hW&3r7%;6Su{~%~p_gZ}IsjVXlP?2H zl2aAH;(|#aD01XXlOhdAg!5OdPoqw8CF^%%*O)Y$Neo6o!RQgY>M-O3JO$$1nBp;g zP9y)(Q^oU8lW*0X9Ked;!duU=OjcNT)?k~_b#V#(CN-$l(ewAzPVYlh_D=Uva zg{W z&OX({G9isAS*=y%<} z9aN329+;?egj$u~R{{n@H8iMm)G1C1}yaEhZ+`>Sn%l<85#&Bch!X@y0CTt+K8+qe@Mm zFj50`D_q8+{{tsATbI?hC4t>$gYEldi&MJ!%jk~^?Yom-9~_RG^iW!#vW0p*th@0S>VT;en9lm5g`$l%w`F`WIQ35GBC8VtEWvISwNg>YWPA}dY& zYc!4Z?%w`Y0Aa$DWzL*uMr%JM5%aKL7Jurp^F0hqNWQ~(CzxkCh$Jm%A`v^7AlsjN z49Hx@x)B{Y5jzuYVc`p?Ig6#N3bXIB5=8!oCGOlqk4Hd#XTJ3_*=Fc19;MK=a)OZ> z?}Y{R?t}!e+vzqRjtLP-GI4Ug3BbT~kSb58hO9?^TgdccB`vEqjGWWB$k`4vljpBl zgN@PkbWB$|qhmC$*Iok+?%ubrq=+ACqygtMAT^Wnz$<7RS~o=&J@gp0e{$_N5_-JN zTU%n{7(_dyDG7)?C*HoL=IRieb3}=DF9bJoA;wXV$iZ?I+zS@#a=AJ>azi^Ro;r#O zo)_retyCU}AG)QbtJ{GXu#l-pG{BY>gycbr38T`Fz;S6X%m9@DcF$bmBtiu?1!lb1DTKvQ-?veQa-+ruq*`ZyA|Q^m~Vb^N|wBeWUWn} zbfec(!t0d;PJOg7*u9yLSDN|i&kmzb6KiS?evz^AWkj{52fix172w5TWyJxJ#Ac%QY3l*~(*syJe8)6Nt#HneQ`*3w3EpGN z1*zWV%VR5(&6T&2QcEEN9AI1Q^Tl+4hre(>VE0eHZx`~F4URYCj)htcp^jLC#27E> zwawnGir~1J&Yb+m=&6Ue2zrU_;+OHiLgrKnDqZLEPiaTppIP|s;3Sr>7%r9RySNd3 zc`=d+=HdvWxi#1Q!D*F?H73q5zHLdA6Z!fAu>fzeqn*JEkH~)6ehNb9|JB_jWs9}o zlf*M4mJ`P3Kp9=l&d;C!vi6i$+|J zJgI}Ek$G|eGYemsg}dA0kJosMGZtEXq*2fC*=7;sW|v@aGyQrg(MHBkoAAvy`Q8Ec zK3j=wHi-y%F9nq?VsDBNGxv(gL`A^`ZNsBvit*GQ+NtcI+hAwYAe)GE4WIf3lcgag zP6yk35laiJ%Osu8pH}D5I+N>?l3!5UqXF1^A(sfQ{s+a9>heYjAZ{OSnRj0PHDvho z0oCA-&pKc9uR#gFc;WQ(u&$0Zp{@3D^1P(T9%B0}+ConxUV zz3xw=zx$}Ig+AF#8ls!SS_o-OO-&s-xXT^DiNmP@o8r}Gr>t^H$1IaH;@L)jpH4lIP#LYQd_(7cUt7_2$uPnpjYu zJmc%+Wh+2mTrm8=vB6##o_-wK-6`Qv5hZe29viVP;Z8xl|7n*pPC1h{7E;?0;@W7# zI%oFa2gxaEO+Egj=^qxet$(1uzcDTD(eT6vFzTV7bWS}O<%nJb|eASDj$%WV@?eE0kM2L`YlCZ6tu{SskALqiIp-Yb08*;gT|ihw$BioN%oR%^DD zrPiMlzm9w_r5UxqTq}6#Isg3&U<;eL_$i6|YoUniiV;9v5aC-clv>)Yeb}y->Sdzq zcex{Pe{MQ+tm%EYxyYhB+C?dc-Qv-#;?;S$4Xth8F%$Ubf2CsmxJwdg0y^09A+AE- zcSi^IdFS(Y1-frIl3K82eqs_&?x}MZW6&3VK2f9Ju~z=maHzn;Sju)v1jKmd%*x>{ zGMXZO16EPVKr+quZt(-oqIeG$B7OFwfl^xTHb-~g;=8yqcGL_oJv&ugW$ zMbDlR2N{;D{Qnqx>#(TTC~6c%!5~DGkWy3-X{1vH1f&F{yG3&7MnOtSLOK*_6{J&A z7+?q`B!;e$?ykE>&-dLg?jP6ZnG?_P;QZp#GvWpJpN&+5uCoHFH zwG@<2g)d_M+Z|Em7y!T)&~2XH4=(M$Z+DaNtI$kWV_Vt6X&~izt`2U0zz;$k8!yX4zx?o~LRaS@|9&YUtEsZt@bL-sCpM_SI zsrYPWerwyBqRXt2BW4tMpi1*W!t3=4IZe6Y27U8KZYQF#^Apc!O_NWk6(rm9?d;|= zNM$@8~?KzEGp8uWkwI_6>auV7mx}4Jw z!xk0Em(0y*p%D?DC~9q!c1X++xJ6yASy~c1np+xUd$y$q<^L*9Gar zoL)r4t99pMHfr8+1LAwcE+hpe&MwzT7-#&=*UwGSy!b?F>n#iAuEyJfdP5aS$Me@E zQ0B(`J)Cm*0Yl{69P%~4*p9;R?Rb~68GAe$*T2&e7n{rfJF{Izb6ZSWV~TLU@4Oe# zdHM0CIXK+!)%z-w#hR?owA|N2qb2^?_^aY;X*zrhqudu=5wJZw&~d+hp5vd&h4M_; zu0H3V?bDqeAx})d7bu~o>DUt5r#4t%)4|JO4^92+Q(~tZM1fi!&=WCiM#QD=KfTN- z``<;7ezQ&*_1GzVDGw;y%TDdSzTc#~7}A8Y(7}$+Fy@u(J@d*iks?6Gy@JMPQ?w&X zT;tb;--wpo%xo3F2cYnHCg1{#lNB02mKkBwF1>lm{CUcw&G*GQmaDV#^8H5$Dc0{w zmwR!(4gLDrhDk;L#ZG|4KCyFm_MZ(nL2(U1H|Kyzb!qr&O;rSh%QcKg?4*;xfi3gp zjKUK7qzE=vOi`fvW{Udm`j~~Aj!?DT^SRI8<3VFEYp?YDIWV00*HfVXd<^|(9t+9{ zAfB2+cahI(1?K&U>eq>!e*1WV{~u-cdPFaO_?>#NMP&ja1voP3yp|J1z7 z%Q4<>_UOM55K}nkQLv0Zku=ardxe)@D-qRDo}bjYv0B&QSFoZ23_oEG0^IB_g=-`N zY>>LHgUdiUpRM8-gKuUcpT|cY-s|%oITRYv6CQHoU$VKe#9ubw2vPy}#8#_8zft8t z>*m74m9%IY1HD-mI0cgb!G1p*NCZfleufhRZ61rwYl1NX;;`qEsH*~#&!AE_z{x74 z3k@6-3j&$kj?FLTd0Oq008I}6p?m?`0SKJwm!Y)eRSU$?&{&|`@V+ctj5GMt<@DEw z@jHJNDxe@YF*Thhj{DbhXf{q>pyIWjw~hSfJjwtD$N1k1tSNpxH8aRGkJKwYZ|h9k z#Z8yh6wLhKp-n}CMqhBj3C))>JQj5Nx0_;xzK{NXdl?G^NzG#D?MPB^Z*g>ToT_w&sQkfCMMESS4;V;owZb{6Srhc_EMzK$c96!0Z-GVpb!~KU(+T6R?CpaeFO=j*MP2!?0yfhLh%$0)GEwMVBt}ZnP|Hf6*#VB}^*28rGt)P*~O^={V&{A5AXq&JZwP4_1H#jih8z{kpPB z-n0)G$vAE2Okj*GqoA;Jp^hFK1xX@bj}ZBdaN}#L(YvkHYEN+hc+OtT z+nZ{qIo_pX{iok+jUN~uZdoX$ay3?^H(1+=rO}9WdTKnl!c8CDbxY9VmTM1(96kkJ zfZ>#Vb(@R}Vm8X5a@jZG+T0%Lt#kjrJQ2P#&kyLE9KTp{9gor zwkP^oAEDBAIkGwYn9Z-*?QaQZ&Fz<10|}E0@2E~TYi+4akXNnT0i$B;aGK@}6gS1l zaammtb}GwZfxcnfdI-0or>RVzc+0V(A%JATylACjng}a%UYf_IA?Zt&FRY%HNNE(O z@jo40{5tQ9F`EwCMFLP}o3?7Z=;qwL%CRqv%Di1W2>yIL3cT8!mV=y^nWcQj97Tr(!DqNYH==W8Gdg(F+wHd|Qq<^OH*2&WzoloU-4?wj8^aJo| z6q{_or!#>m4^{((wIjSGrhjZ}x`f5Rj=iZD?!tZ)kkJTeLXuYd>K393i#0@6m%za4 zHt8H`f(z4_Bb{gg9|@OT#$uoHjWy%pVPpTG{J*Btq`+t|?2qg3IQQ@zkceT3bA3m%idpwb4M&l#75JACx)|KEGpft5r&i zGenn(EOZM7Sr&Yc{Yx+Inzctj5#@lSalww0C+sVuxT}j%FiM1eh6x9_8m0iW%cMqP zUtD=B^jv+z{V|PWGTSeD$UGif#M(2v!4^eDS>ySr^U39&Oegb~_gVs=QYj+!Qec)X z#&)o>?YI>*T3XNlmRBu-bNLqleKYGnF&oRbnGM*V9Vz($Qo{@(dFrg!)@aYQY|HvG zASckOceG;C+XTP?d~QS%9wW*BR!homgtkOzj5G=a`1&v%Gr?Awjiusl>?bNMts5Xy z!&04hoXtfnVCqC0f!|9lBB~`VPf<8I{AbF|GXbp)%HlBV7sXNdjI%h0OWa zFWL6njf6!92O!DuJtym>4E{w^$U$(y-+H(ap_A1x7Qj2~o{n>5V@cC(^BK9wjkT#) z?`p+F<+{yeR7dakNJs?u@5nyAk2+mQt9WU42B^~Z{T*kEdXx_{j^Jd;#d8?8qG4;6 z+gbyDzx|_@7&<}uZJaYWI5HBCo`X3nIH#RIf4*Y$;3gaWhD~0yIU@@8mKpQGqw3D< zU(_s}V@*ud4zNB-PR2pSv6}4{NhX(DamuIac$e_DGLI_Rr0^y!&<1IffyYEwd?zbL zZpIh`PItSL+}F9^^^rs%Er|WWc&a5gh3=oOoJ63Ow7(Tr%7oT-+JVjx>w|1HCOr70 zA8RJ^cfgG&c|hJ@6iCtBpYafY1i`B&hw8;GRyNydI)9-F#$^0JbHt54Z*4=h>0 z9BvC=_U~k`n+VDW;0domc&{n^9|Z)APRYq;5GQW38nsp=n6&aYfE^keuQi6dV@GGB zVY)w-e<+mr)EJSyHx&Soi~tu-8l??x;KvWIGg85w2KFTwF&36NL4N=f*4!We_n3NU z#nIAaq-anX-C*gFq~Y};;b3R%_M~5J0Zx{o0R>0hV0UjhYvaeYvY=4TVRpAU`0_I) z+Y(TIi(u75#6naTwp$KtKeKd!Q7^q(2a}168_weH6LFNl`OYdB08@ z1gS$d`?9pKjt0~(7aJBX-@wt}1#bgFm5`#gjrctsJhMxlH?bxbk%irtTzU%k{ZCM1 z!5B~v8Amm7Yd%YC_U&O2b(%EUfl1B67{hPs7iK;x3_Q+dK|vp(>>Q@H$VDyDp(Ftf~$wUoy5xLM@dp@@!< zP~k>{Y3~LQXk`*?pPnZQF9Q%EmR-Ngk65%7ONua#5NUxm&KCol{Kii0Q2r>k>QIPo z&N1d#B+PziVP(Z|Gys|&K@tv)I>QHG!Q^8mM5Dr>D1DBgOS@ykGz7es1m;9jCMmG8 z3C6{|7k@$_J6cfz_0^%~*f8`dM z{(B-s$6wmwVH*-rwu)Fe1c1K>fg^>#_${6enM_t>PGsh5ZqbsQP-52mpDLLfEe{hD zRH;8?4xFu@=8$%1M5}%Uta@shP8JKqWf_Y<3uhb^^h2Z%h07_Ng$ z_XIzpIlw1z^I`Ukk+Syp!&(P}n^E@ZM%~F`-Nt%^&rxVgC~_LcIDUYr6vFyiAh$@V zs$MU%e&8@Crw4n8Rt2?c0A+`X zogM!}Ufx@Om2 z0!y-3;4F#^8$|hC<{uXwWv6}%)5LOen@Kmh=l2?7J=X zDo)zo4_M>);zLHp8?fy(q#7tR{&I} z5t~dWNr^FeCoUckf?@Ne+E>kP?3ux&90L^qIc@f<(TzpSmV`XH{0+D{M^0|0Z1AHO z1P66`yE->zUl3}SNU^|Li-PlD2{Dz@qF|%$x+TTuu&3AOMw>az9T-X4uAlQWP^CH{92_P3v-L&fEoh26|xu;!H<3$hK?r4AU6)zgBbZbLr_JZ790QINA&ZHMZ1b*(^S{z+;vBcF)w+k+6zX7JG|$ zZAM%h52=8ML9W+I<1*5~T0Zg^w2eXCg)s5MLfSZ3gRG`hcXyXT?9$m8xxuo|6_G=Y z(mCn+4_Rg2gDtz}X5Xyl1wanr7NW^vyF=-dTF8>5zQeoOy5I+@T1Zn&9rK05K}ytVOQM2D9(0+o#^wtCEKQ`${R5?R~|l&O7n^ehhjo=Z9Kl%$K$`G#Ss|^pFR-G34tjhz- zUM4wG`Xw`A#`;I_(0ZXn335Wl*u8ALy}o(2<+gGQH0jj02$R4)WMp|d5c*zv?!n?!Z4 zi4%Pv1mCIS&=yIOdHWI1SgqILJJ6G`l49@4*kZIYe^;8s9@W`)EM2y|1M6b8v{TQtiGM3S@~a?(wp6`~ZSHvU>Aem+cp8^!gqQ+)>_|wP1r1unX-~-AEHn7HX?R3WiLndc)-^c}Hg_V)Py?WJvZI zyV@njPQn2q6e9`0RQ6SiDQ2HR8KA{hSR11aqBVZq1ftPG^9n z%iD3x+A>QDlI{T%FNk_v<7*^QQ$2=jZ^{(bgJyp_c}9h8Czl({hO0guPvZV>jq z*EfVZA=|vO)#am#6Gw;9+uH;3rL1Y`@&+7{DA56%3?`c$%OUqVp9;-+Q_?b$%XQ8A zwpDtrq%(~iZEk-N>1&};v@z<>?#A4%8?2|o*OKzAW!ks6oxn%&p=waQ+uVRh0DX zr|=0$QDrg?Lb=Nqh%el@X5y}?q}i@od}-Z-T1Io|>7Bb2cnZsVS4adz0V}-~fC_PG zY=k8qQ7@_cq|2KcHe@OxA;>}>q6K}(VWP(Ox`e8ov6D3zc0vT*DMzjeUVZIPP%dM8 z=ZUUV{QSPCwffsuPVB820w&k59vV|4g&RIK9+U}Vq;x&(-3rr+F6_o*xIVMbEQyP2 z*U8<}$rO4gCX+B>e>_zf?A}F2{-WcOR)hCrzssez>2pEtQ!_J$2+@NVMcEE5?I@Ju zK`qRxr0?|j3~|fDRyP5NC$2_2tCJ zR~Ss06v=V59Wf-d$(6~_7MrKSzlFLL-NOreBFBBnm;Szx@7whBvz@g&wa=YgR8t(h zeYkadw$2icK6l#PJ$BzOQs}Q-t?JV4Cs)PjIE}OJ*gowl)F8lYJ#Ur&>*HypsTMN( z0H(#$>m@@4$ms?S0$_5Mje4eBje}ld7M5**F7xv-FO97F7J96Zmz(>Us;cCZCr^yL z7V~d3Ic%dHzkJ>A)7@a*Hb^JoUIjqx4abGI=P(x+^c=WpQAATZW-2gdR zB2~D0d@S}hDAtBfhLfzu4sK|deedcjAG<|nDY`;#ywz$bSGNKC+<3wgdb8i9#r0Yd zeERhwZuSEDOkH<~DLSU_N$%TW6FlKi_KvCT+wTcFWH6sd@$8o0U9m`Q>3#Bh9^(Qw z`dPu&+JkDF10x&+IyQX#3L&mZMvWZbST19hc0*7`{8+DSSiO3^iSDs}|j<>N4Pmk4)E(IYDm!dyTWQD|Q=v1)iI%I9_S zu$|sYP@^sOIFmXz=v^A+go!-v8NR(yJiYQj)m2(d-N0(*JydrMNo5C3By!fD(pAJJ zrC4}cLuKAGsY|m=SS_V^smdWX)>H{RPr*;1cr&Uh|JRWQdQrWqt9>*~jOg_DNF+wp z>gOHiiAik-skH>gv2-@G=vlzkL{#GW?$>>Od|o+cV&az+-SXD`&Ixwx$ihV?&R*2x=d=<3Sf>G6EJ3NkjX2M>aue2M`BdXJ7} z=iYK#{SWJ<0*7?tS)5L<_*7^aW>f-~R6T$LQ&W_H`yH_q;AqvdR zx2bJ$16O>|hNFtKM1E%tWR-Ff_&)}>S0%8@mXzF_w@4ft|9L>vTUoH$I7-+RKN`DHHAdl4JR%--Cb5G7?T zg_QG?6%D20;vM(eCju_|tyjx~{4FQP`eYc?2~(Sg7SOAdW$jz8th={%5lzBrT|eL2 ziE8H7>HFPR(kfyxKM$uU{nv|-fst8fSb>21P}1~n^84FhL2p+%DnW0!u$YKRHQ#_oyP~Gue~}rdC_%)}kXLgH1JABl)*(q%j-aC z!qHkTw;*Vmr zgA<~2xEa~z@DDb;0jjF3CxjjCU5$&@#stUSTo2H$KDhhYr{BTa(gIh?s_E?)^}fQYcv57rQAemO5Muc^&)`#1LI?n!aaFAGe`eP4HwP&K{F!@~nqmuXS2 zTVEMxgU+S}D(VXaVL#sk!>8W{FctX4_wI?e_$JH!US_&$GjuJ^f8WQ{(7Ss1O63_o zhX9QI^xhe{CDIR7Mf+~yV~(PaF)U&k4zXeGXaQLy0(J-eJuhxDx&tp9MFk#Lbsc8k z7#G`Q|M1M9A;{U7+v=X(>Jst$EmC6;Mb5Io3kg zrgE0-1A^gAf#)o93au1S*aX}*?ieG(XF(xU`{$&qG^4RAMF=ZcI5Sv*xD7C)yl~dj z`q<+#moIR>l7-!(j*gCgoaE|&k-hPt_Wd)etRq4W61KTyHns$;sHvH@Xb5!NpWiOG z2~6z;t5}Wh2x{wDCpQ@EdU$9r`Fw;$8>H-Yp_J+hW-VLH@jS-&hcpvpP$afAUuVh- zXbqQBm07Y80e-d}bWK0fsqZfu4HBIj!K0+bEkONwUnlr9LEmORE|{(b4DIy7k<-uB zRHNdO0@2F~3A^Rq34)2nq9pa*MxB~6)oLR3CC?F^5zCg7l#2&>Ir zn7!~56BNFqt*;)}8YxfS<1QZl%_>k3^^pND&Bqhp=@&nq0fm9VPe=E0Zi1fgZ27c_ zogi36jbx}_WgH?0NDhc+~vx{4ONG+T@~!|B8n^z`)p-&C^u=hvrT&3a#bHO?ugPfTEOsdxbghTbgs z#h4QSWn2N?PvEw=3L>xB^ShfMLQ2GL+&Opl4A|?k1`yMY8Ktdg*x9k6%WV~F$Uq+Q zve*}QJ|4usxhmOLRg*w0uVdR9EftYs(EC@R?x$rneClV`ZSu3NJ_;Q$Wi ziS^2bmDDdGru5$>ZTZ=U`opOO(tZ8dqE452Vgf!nh(&I~B>dCmrYhOop z#=7bcA@o*kcVnMxR6DbtZYiGr7^!psuZ7yiqy0_x7t0aRjEY471_Np4xQ<%LIn*3X z+|#E7y^r{TvA-S};hE9z)s^f$10;7|td8zgi;+KYyO+~b^`VomB1aAVMgj!nauMdU! z{m%8=g!zY;(A{suc^{Y`@>^bBXle zDO}vZstUh>#aTP~WXFg{RmdOHT;HtmRmSy!N_3SfHSUQ8e|w0>)5_0&&35c7Ofp-D z+zg3^N71F014V#F!d{ok;~jK@n2#vDA*M#7QN^0E&1l=YP5?4NN`BH9!d^RQ)E?1w zCF}{D^%;TP&$+oWUo0JV5}))4C1lCCy9;Iw70xS2NVtcrq%zVVC;dd4v6X02nU(qG z?*V@2qmeYqE_Jgfg1yK{T=bsM%GJ&H8#-# zpAPI7XOAf*k@tH{xmYi+0+Doja zPmvTT5-315cia-_ppNo0Mb~)M1Q0f7T8TXCTF(>g@w7R>WT@!bk_1!6Q1FVzHRwCj znvJGjB@1mgUkMU^ay_G5!&y_JDtpCSPuabUs^!|ZZG-dU`qhDVUK<> zlzQM)cso8)4;YktdJPl|ojwWbYHBT5`XVkdx3@HCnKSh3ys@>~g>yMMIoRdA$A`P5 z!4h57i@UEWG{5c$y z#nIh1U(}__*^QGenO%d0H=)vju+*)m_dyiRU*nn7nCDZ2h$&UZMC*_{(e@^2ovgMu zCz^79z-h1GM$1?a2Y&l)jqpbnDX{Qy-1LeamGJ4Ki>oPLCR3t$js^~n2?+KR__)&c zZ*L|Hid~K~6T32BR)uzxnb#E+^134CWkI)^k~jN_*alNr%@|Gd;xrJ9`|r{D?D2@+ zyBIz1vN=TQ$EH-mq-?jg)V=$)LPU0L_A7?s1SSU-AX8{427;-a@XX}rwd_c zzQgzj4qvOJomEoBb>y=BVw?s1@Mo#lNGy`Cv%`!u z<|~FJml?8|vNCo(yIuj`&?K;Xlb@ra2?>?PTsN(;Hw~l_gF6dUeF5lH`P@%SZHeLk6q#Iv`>tp41DY!IbEZ)l)Yr?7aaETE>^y{a$rgH$Numw|w=Kk~!o0%>(lT*?eZotPyKi40QHy^#^_{C7z$*RO`R z47q>s4QtM(z+3Q1(h)~W7;P)$FF zy*Y=~LT5!LoXDL1FRdTiY9if6e2!ma5fbPwaHxEq_#neUF|&HIvbtAYcPIpSEv74l zTF@~FiaI!}ZJnK&A3nTVpGH0~sDEV=h|UFO1fycA)pjA2=P$EkL@Ay$rJAn@<#YGg)qJ-52b* zsPUU_PVh?aQV5@p$utro=E6F%?_HDL`3PT&&tdk%6?RV>yh9XyO;JJUX!gr{mysL< ztry)XRNgi4G}%)|QORkAGHKe`F~p&op)gGlcC#-Mx9Hy<(C>!pJ_D8`RxabPofa2W zG@N3z2l8BQ7zYWgV!FG!L|47wySgX6efzYm=0Grsmya!SZ7zRwuxymc3uXj+h)<-& z%jZBr@XG zt8_XjlAA&s1hD>9j4y|t>AXdoDr>D8+#ov>_o&|ZN-*WoYOFYQe$bkqlLuu=T9+@x zA({l_A74jSseAPF7;9-8j$Fy}%QE}Ee$O$R`&ujxKVzXVcUU1Mz`Ka2ve`*bV@`pW zWwGG*DM*?M7LlgjXEH_o9vH01EUcdx9rduI&Q>{auGEoBL_GXFfIj}4>uyq|61i8K*%@`&gM3zdnfZe-X^c|CYiaTgz&92Lj(;zbkyKuzMt%f8%oiP5@Ym$zB_f}CG54i& zNeblTR>MVpA|AUgTAr}`xJ_NB3tO7-cwJJ-mb)p!`nC5!@wzST=cyC&owd2bmtT7Q z@qTK&Fi6B3AYeCW`*A|hE!%q#O&=GJT4rEh9g#%Q(|>>e-_=AnVYr}BE%IdGM13q7 zHncJ%TTRVrDWUk|pj=zrb`}eBC8+$6kduwS!)vFJuP9~f1Hgi2hTTAXAw_NoPCUhPP1&My4d85Bs*oX%d4yhpVgSDafB z!xy1;H4IIWZ7yO5bn;TAldTp`TC`hoowxgq>4OZzh3bkR>4NvCDHx$lI*gd@QjB+( z8(}5 zEsH4JDcn6T(H+&6i|zzHA`BL^e!9p! zruH5EBK^F#TXES+A?)Of; zN7rP@3N8^r(8@rms;RBdcY7@-H{;1uBP;(H`9VR}d5Pdj#Ek%poqV1vs79sOW&V!a z1vHsex58)nzqlUW>BYk+(>Mib5z+P4Q zJSTr3r61T3CMDugAvtnFg!)>j<#5B*-w5cbM4YK{uZW_N%G+zG`X1V@D0_`AludfT z#hoOQHlvi%I@SB|90>0^qylEv8qKq(cRlxvtIiCafjqdLYa!X;WpEk$pOZ=4SZcp? z-wjrWR~OF5EUnv7u3DVZA359uaxTl3=Wx2PZ62kdi9x|}kryqlafI+a5L!_e!N)jzlX1;HAR zq8lhY1@`KR2?PGMl{PKsw7l6kDk6@X=x)f@9dw%Y*Kv#N625PGLQYfMK@lFF*_#iG z<6-9ISE-+#GUwB4={Ozx!Ty{4^8|L}?2d;->@^i3g}#p)isN%S99%O~uw~(((C91Z zP5V?mq#_`N~qj6R)Sx$pg~!kQHV2X05Q&In}fL49lTYDyM3Gm6TH95u+#TM*C0wRy^=Y8 zfF8AlR}Du`?E7iv2VdMswi)N@Hds)({5vf%XiI@^iD~ZjIGeftdPB&HWk=3r@RTpm z>{JHJKakQdQH}|!{m*Pk^Nog4$z%eD6z`1&S7A^aZqZuR7Bhb2O5?13@N?EQV21VmOO>$id%Nk1S#tHT5qh328L6 zOmR6=voKPJJt*@Ddg~r?P$47V*MQ^6wznsars!o%!S-lE^acIf4U+DpkXBaAq!nK6 z$~Fq`v~bos_P^uZ^;in~ghS9tsF(Nix!uj4_be!SaPNGQU1H`aLi(R;*!~ zIrU>+URCeG_t}>7;OF3?hNTSw3KCx zUs+P2Ds4Dk+^Mh8`qjAgx83L08DHMuSL&^2K5XCLS=fcHGvxfI4d_85UVoHzQF?ku z_0K_=BVSs4U)rhb3GRv0Y<0$=&d7tz3j>rGZ&vi=$K}BNgZ9zjWA^tk_xQo*5#JTW zqC%MkV79UuN+VRJa&Wa$1Ex8;x?$t117aHVJ-1=gGDFvCApd2HA#|%IP(qN$<)_!iEF7Km~q~ags5tl1cJUq3cV-xqsqaRJN z9+GG@gepVfYDiGYV>hfyAuA@TZZvJMt8PB2qWE$&MdX%qd*t_sf!V3{M`6X{g5lzR z=baEqRTWLcBAGvEpu5CJzg`Yxc3YOdE~Zl+r?hXuLh-(Pgk&EI=Z8t_SVg^QaatCGy0!q5wRLDGm=SukXG3hL|?#tg~$+Q8)5I$Tg z{-RS^q;jBDVfXQG#I71ls&?L7+hBB^VrK?id$|a+ztt15d%#}l#2LakF4(nNPBY~y zk4ro*@P3J#P6?GIxB%U7yht89UnpyaVikUITtpnUWr3(<3zeid4Aw=8cJHqE?{ewQo9eV7^~zC?^W3#kD|;@iu+bQ(rwkc5fTJ)3vyA zH!F-1ky;;O&GGdk(xz963Jcu@HZ+R$4)d2R0Qv+b~swh*G`dUlUs$%0+9g6;KPFkEN<#1dunR@SZlE#jM;>lWA=7Q zS2hwdGOHc0Vt*v|mlh8{W9#=`Jp0v>*VG01=Hd|VLQt+4iR-b;1{8E%-gY@f;nsnl z1ys!;U|gsmJg#^oaYyovuO999#Y-pMjY?leyrM=KEpsh`q9+|5WGM=Uv}_q_=ndbE zko}iV7yvRg#-N2ujxMGiE#7a8ta9KJY%={MW!J4MySHZ@;^u`xdmgR$+@uwA`33rh zxrXth(50oZ^5n-B*0{vhVvT8I{7;?4g_T}R;FRIo(iWHn&%RsayI4VZ{U6aZ0|yS> zKA%_dP#K7`?{{o%76u>h5B@lL{=0ebxlT*Vv1yH4hHpScm|;C2=j{tDc{gD9D!{dD z)ZRx^_#L#VNFH&Awzb8LC@=&hK*>(i72HT%;<&0jrT>QH_7e`k2NmX-!Twz3fMlKk z_OTP-af0C}v|EnSrm8%O!uu>JTFnOZYR&k^GN?i%Bg5v#s%^~M zzJ|26cf4?@Yj3|#d%W3uWH>avH0p8_ak^&chdpVVZ4sj*pUrsrb(E0od@JU&)!1|# z^4JfXjGc@~itz&1s<+Qe|9d?ps-Sq{)*y0PZ#lKXKlx_CPPLoT$nn7dl&Zjq@YRc_ z1GS-y8-Tmk@O((*us!>Q3aV}dp9aT0#`@YG94Y3-dK^-_7c5T(y(^*y!k@1-o%|i4r|7OVe7+eR0w^gh`uhFbTBR4A=$5Eh z0^hn{P8;vOE_thrh6Nv+vE4>QbH%V3+ju9RlO%EuxE|N9Uw`xX)<|mCG5tOI9@2Y? zZ-YwY1(XFt3@P?T?N&=3jR;v^0mR|UxO)5C-zezc`+%08pMq#fR2AiMx3tEsCP05w zF!dGsj}yi-!{g^Rm5k{}+x(TDla$k%LY2cs-t+k3)6bx9a&qD+vo5a$xcT@39*=1R zgj&m|vM6u~OPiaNN;BymgCR&#LSz>*ZlqPjh1KwA@R#m2!)_Bak>zg8+ER7)UPC(P zb19ma#ze8p&uB_3SBkvPdD6zp-8XVoz=``0aj3e^s3z6)Yc$we|CEy=_2JdqS4rk? zh}-)Sw9&NoSl|li>2?Q9ag{BxPcKiaYLxjQ+;{wBBn7B*OYJD%t?)qoq=5(-h*0Bn zumiI0`z3K~{iu0j<8YDg58iov+qz@k-Eki=%imu<78PwIABt^uJYdnQsaV7%1ssjR z3T@VurSA48LUC=$!7{jcisq%yY+o?T_eEz>_vy2~k5V`mgDOlnJE|G?eYA;-3b=h| z>!G<3Rx1`P-K`cs zk1-}a#0JIOFCm4w6`^5=s6nSMQLp!hl0!Aljf52otMO3OY&9@>Z%iF#xasOVU3;uvvetshUSIZ9-5+gnblD}Ji z(6*MS)%4eg1Ok*hbsEaQ`#jKz=nNo8O~!Y=-nf9EBETi6um32zvbIsn^&8d-E%U5C z$n_!Hl$ztTH4*i*FY$ydO!R&xjD7t+RA=U8vY1+CRwP^f`RJS=;56LJ=xWm+jmu=1E{yYVwc2n zIAbyUoxqoAxfQb+MW1`q^fEYqjwM$t zZ@cef9Y#Mzh_;tmqyNr+qyW#yzWxw7I#NZFU`42p`P7eKnYS9i5AJyjmW1DIa8a=Z z6Z@r$h1S*L%LSD$1$W1sg!ovJ{kk#B>GwQpX#$z|`;3MDmz)UuF`#ENBksQahclWc z?_VVbq{sNIwu(lAmg{C~`_^eoE#sLmakT?ik`p_A`+A4BZ?Tu`jr3`{(*Uy2{7Yp z;Klb`P)Rdd8L4c$pq`-$%vRtrJ^py*AIu|7jQF$0d9wE>T6kknU%>guBygB)24jz* zDYxrRDd#jc5Af#W!fO$x`W1V8b;QS4*8Y}`Ek ze4y`LLgZ^yN|FAkghbSn|MEx=4M7_r*BzIeve|?)67nKcJMRnKd?;<{3K~ss5Oj2A zq&H-Vt~?tunBbb&A4TprmHBnh{Hj=L>}a@kM5_*IzUm`(6nN)-#u8%~@cw@+Tl8j~ z;ZE|dm{(7RnE(bmq3YxtpV1yaAaenml1#$q88qS3FegP&GeXTH%?Ep{G>#jYSq`U3 zYxXv>h-R-haa61fYqESlbSCSnX2=wM=u$51R*@c_{_IuG?6Y46Dx(I*LUzZ4k7>QP zZ$`hhuK-XkpW>bWK;}~ql1hH~=@HFU^5NG=D*OIx3YkXb#|gyB6_>h~Ne@*t$)~@o zl)8$r-CwZ2k5hoUIT1iEdM}fkdUibpxwn~wl-aDRFw-D{Q|8e5O^53^*I`UnS=&X3 zohhnaxoqMl1p$MNxw$zmclASMHMQ7^6krF{H~8VZ!Hk2F=Vf2!MP&eVLTLD1;{)j| zk~=46a(jqMm(>RYg;p#4tHs=?a6=B9l-`J>P4im~>v!3f(V8G9@5hdd_=motLpkS! z4fXw?HX~SWdUNJh%T8PUSEl3tiWmtt4d?nM2vImJNQev2PVno|Oqbq%&#y4ubD4pN zhY+Dw>+x2#T6V39AdC1Cr;mxKgVbDP+KTK7prcz?nY8Vm!M^JXT}{o457pGvrfRYN z_ljN%DlzZhuOBQHFs_KXZ{=V+oDA)dC!fA}+R$LjQPg5N^a&P;9cdmsva4E+H3I6B zze|G2JIZME_CCBBw-RZE5#KlJZ#02oRze*jy@6N5g(ezcn*F<9AE2!F~@=8lQY z;(($$md1lAWvF1VaggKY=wjAAKEIwI$x4f9&Rd>|y^DD|b1uqV^=D~shoLNv0x`oBT+6UGvnf(YN0rTbTe%|tNZz1pvj^kI3ECaR# z2ZbEum?&T8y7D;F2;slDN_zUj2w@k8>obzw5jU!|qdlp4G-F)|eGRwrEk(5fq{hjx z673iwzDSw?g|NG!E?e(>ld%&yg*es_E@Qt{M}bUQ$vkbZs&08>Zz8 zDM&;0RL9zFOXV+d%3jEPoGJ{}WcL7h`91D?9Rzm0v$z@@f@uT=ve-*(8!D3&7snM% zBkt`p2bFs4I zgpth2dl9R`EotMz3W)>F(9On+-A}U&n2nm>y|eo;LpJlj>%2^aBYHfqSYBZZkGBSv z-Gj%okHPNBC~#%-s}}BKC2z1@?P~fpizHJ`;NMPdyKfW6O0$qXMhM& z_B^FO4SkQuP^`SQJS%Ov6l1WYgx1G@=%sYz6Sm%)qn7Vh&Z7`Pl9PbBS&3;VSc_A` zE+P&@jzv(h{VtQ*cXeMRcf2V758udr9kHxeORwG%yWh~QBbgUw(zW{;3u%1wt8K0k zR2jIWUv`BYIm!PD8gmj1!DoRS1ag_S1;h*ULbzX* z2Y-7rEO`_gMp5Aegij^E46J&_fd3BTs{0%;-|hG+?=rvlzJYDK8T05XjJoe%z48M; zt+2(x(jxG11A;Kty^m&Oh_AKyH%(F0^xN#z2jHWNP{#~-TUN#!$`?xp_Uku2DDiGVETdtQzDD6fCVi?O&R7_1dEZ6K8fRed8vhtczKA^Rk1mp|Wp(o;ZZVcfRnSzNmvH6;i$3ek)$xWvmp8SW^L>tpOV-aX=@bzMh^yL*O>k-dYLNK!9C`UdpbvPj*2F88H7Iy!i+Fgf*yaCvOm*#&pu@?y47#$worfu$1+4~UpD+f|H|@vZ}-Fz`xr(g5QMaJb*aIr&>eh=^?V*p;HK;O0+DvJb?1S?%F7$@({Y1V#5PKC94 zLY@`GCl~?Vb-$~rWgJg_L`lLi22=suoFPs|;h22m!Ff*Y8bD`s<$yN>=u9GSEYg3L zXj4Q+rhbPCKrJPbbvx$Unv0Kjv{5hd4^wjLdn6Bcq&TT=w_HPSzh)Trf2+gEINW+( z?93DoS!C?ra=Cj}Crh@XZ!CcCB;c71-~G>7adR8(r8`*6VPIc68<-d%%Hfjspx5J~ ztFk|(v`EUUh0BGcvYjuHo8~3D`i#o{>w)Cvx7)|oo<4h}K9(BHUnapJ;*hrrHcY*&K6mXh~95P zHa}Xn?2jcEZh9Jwec@?POTkR5|0R*m^S{ZBFrW5k?%qrq!5ll%Z)M9I%xY|}x=M2D zR>bTr*QNpOy8z-r;5dB8J)6yX9rn01aJ%t5nAgWQ07*R8(tJ?X7Hqzh^{{_gxxX-O zOB+kLYZ-jih}J^p(b|bv=weHUKKg$AXh5mZ@6jvVsI*;PKpXfDFDV2ssf;)jy@??m zBvFq)KQ{djE^<;U>tFY5Ki=me^*+6zV07vjy$I7bG9{ddwub|sPQ(6=xUgl{Tm8`d z9E)oV>K@))ACjp@6xgM*y6rE&<*&w*xE$F_oR=0MygDTSB~IL?QeT9Le8ne-9KiYX z=H_cCxUC#(!ART@dLG<-?}J^6r#LCSYHBfOOec6M7Yf%az-TTbC;1Zllv;#LN8vRM z^{ONFzyT9u1Tk+yi~ghL{IkWRx)~GV@yl)}X#C$Sp3ZgQC0eN@3cvdV zKycDedvF|EV6bItnB@PY@kd?5W(MeSddv$s4gC>7A%G>=N zOuo!ijEygDZiclA!`rg{D+&chJR5=~*6VA#T#_4TRuCdzgbgWhpetTFA=8C>e7b4< zpA&+*CYn1hGh&ZQrx;*uFq(+{2yZwVbPw7yA<1N!JMHpmS(qwj%J`wGY+(a%-+q6T zsFK&miQe!HLNj+dSmOPl_VppW2CN=zw4JEV-7fz;I+Ok_rib`LIwFh_2*57Hj9-g> z(fInbSSg&9X^v^wxOh5#iir~L8)g&EM~4T4!=?H8r+Wke2GOeQT*%J8-tXs+xLShu z5Y9@wKv%x&>V)w20iqlH3$LI*n)h%kJp=enidM!xr#!4HV_fTzoODx>C|4{pGZno6p+PnKo&&Dk5#S8Hr4-8>da2 z$yUraC+R*DT6Fn|NI_5tMVF<-#(rO_2`~iGFe1Ymcw{0Yb@wv`%Bc~|N179bEU|Vb zC~M;<&E%ygS6$D%P-cwMi8U^89=;kYRp=+gQ{`u@1+ZxEd-EZW?M2QSZ*J+d($H56 zUY+gHu%E(!8{y*T1YRmorKG-Wl#U%x*PiainIPypE+##csG%zFE(#(j8$Ir<-(!=T zzv-?SiWY4|u4Ute(nEGy^m9fO+N2u!K>1k={QUN91ZxPXGRlH_Vu3veBj3m}OgKv? zH`65kICpddd~-PM2N$KcjqM}QJ+E|4w|Z`G2KnI*mPFI~Ddr%Cy4`oKF}6DGwD83q z&E_FUkf_6keBi+J%oHF&^ixY}BhC5g{uONXBXGv^Du1uiuSe){DQAU%CO*U+-OqHY z%z6SVAOPonEnGio!zaNFEf^xGz=?O|{oI+)`tA$`DFSNfYlxL!Qp^W46sPS z^-wY*-neM}-Z=ypTD*K7s!}REWvbJ!UX3uGDH1aVv>p$ea=&eK#H9J<>GiAA0?Z<= zORUi+bZcjIkUmq=?@I$ixMXyHNdbO)+0oLN#}*I zlFg#P=v~ONuV^7cEq^OBjP{Z;==J;i+6`uPOC1mPEmz%zl4Laj^jjG6@#8tz^s+*m zX_$>|mzCK#>DyFS!3pnKMg;Rb#pMTD6vaY98Kw_^GQ+FL0i*R7qRz>#y}>|=Y0W^f zcT2hHu-p#4qRe&5a8Rz_>r#7wSEe#`eA`=bnjT+YfQE#BI2VS*ZNFH(Zhv0J&5gdn z(f@d+9Qo_neA3q)IePQx+)=08`uZz)L{!fgc<+N*lj;yR5099H*5hT~`My=?PvrY}uEM)Vf{0F%DzEPb^!lG3<1Q|FOk-YO4VydOW7$RT z6{A78)BL8LRs{(qu=4G;vyBcx|0zMtFklFgu6HqJ%2o zUH&mEHe-<2Yxbdzw_K4mu!=e-ADwsA#nY0Gj$hR&_c;&g-O9wm3>@i3pjT`(b;LPbr@PREgwoJ-?q7hE} z?75qo8sNEmUdr96umM=bHw^SwW$C;ho{W$_6ug*eOlvV%tFOOwIBAVMPO2~ZPc0}h zcT{lcJzVk8?`Wt)PnmIY`Zj-_D{7NLjSb%}es}`6(dtb^|D9{Z0aKZ)m1@ct8nX3u zfA6&0MtJ;+X=QBvhVZWQjPnswgfBG!)%;CvXn{Sjcediznj=q9KloF>QUn)Fe84Q^ zy)pg#64gBvU?TZkZ>pKbb`qGoi1|KvjR!;UP)WsTkD3gzZ`;&^udia$=EZZ;Qs1D- zQDr*Zh#Jm`I-lt#qERdsT(7$%h>c@r!ymUI;6z!D(9?KOe^Cn&0wUmn>{Azds zG*yKkniQ)0KAwgw`YBS$Z+bY|kQ5ZD9R-EDDxb zTxrT3V%&(nbcUbxi(kPO_0Ol9ECHKTMCW@T4fnj9SNlY-+&L>Ys8Z{oN;L|e@aMn_ z5G5<&_4OSDAYh{T7}TpE`?b-!auN8W6^-4QHxO$HMR-9E_m*eCp2m`|a*4*as;;O@ zn(&i~$gsSutZdw7&)H1nx;jvqv2$^$Sk*%4DIgg*Ve{JHlTd1Al*n@a{CUKn8f>Sf zloJJK&nR#>c!K~BmVHG&yF=v2kpVsOJ{zg+hpnxBCMl-9_bm+>z93+5eN8onetW%l zfS&-E-3xh;dzfs}#vmFlCpv9c){KL`uyncIIjEoH+Bt19IChb?$C$;O91x4RS$?G(nt+3whyH=|6x>;B(M`P# zYh~{D=m6*JFuIF;WrL6T1GfLMe=n>G;~OU$`3J(R$<^4vJ}Ha*n7I#G1-Qu}ZUaBmpS$uu#&T z@lb&|?K*lM?TyZWr;VajUteF5^`J1;?$%-(l*);VM?Z`rzLwgKQXD|=yG`|`2GaIp zfm{cS#)&{mQ3WArSb&)w?$5}qLmt@24p(HAu^5|(ifV&Co9jb?-{(cueqMzE@POXj z+}t@h)bpyloxwEHe}IjQy;je4fk(n{dWl>h(Zku48#|3?+bjl|yii7E6>BbkbsdWI z3hB-U7gdvcdg3<+FIb2*TD1`Ep1pD5V=2*<+V@xog}CI#_^a{HmxNd2@odfxW!3rG zdvS}}pi4kv?pm!!GzD0q2{gs>1AiETiezHZ=7~F4X>AI^VQrb;n`qz7V}4|J;ZqBC z>dlFg(8mPy7qPb=S^YU5XiTN!@5h8y2DT?dZ#;}h`N76R^S;*tWD_Ne+P~`ef?NBr z1W(y*?rrvQegk3}ge2qud*p0HN0LYc{m~Bk8NE!+@SktURP_1eS0elrR_ZW^xo_;J zPMunDuWlu|#%zo*)7CaDklhwxrpZ}X>ye6ZC8DLEV1K98d?~`}a$E%dF>?{QtvPV|1ud?G?^9)JOQA1@reV#x4qWI$g#*!?&xTs^cy5R>rQ~ z`T2ueLerIfcDJLcl3W0_FjAcaV$0O+LztqWm$%a#Yvlq-?Du!T2^CuKuu&>n|KQ>VkZS5qThX^~0TSPwCxg;Ct1bU=;Vcgx8d9fJh(`euAl zKJ_++<3k4d$Hw)Ov(h$6Um^xsHeOdqH-mcB>Jm3*lW9t@5u7ttJzx1Z{H*CG*KGQy zg1Eby#oWgKjq%yA!G|aB3^AwJw#V~kk7~izT@yzsU z>SuoZ7;}&F`_iEd1S`giIZj^;0qLapyNaw>;H`xK1e*`H3lQw`_Ucy}%6w=hmD8LR zN^3>EbB#}<43yJ|4!4aGf{jlnZnSRP*7<%f!yf(sF8~Jw39K?>*E#*av?$an-(5Zq zR7Gxz;Nh+mK)|GZ5wmh$LleCKd2n)LKtcNCwLRX9>CKzAH3@=8C+T%}9G}6KW;C3GS z-5l4cA{-*oYN9J&FW$$K{oM{HI{ugE%{ZJex;Qas2oh>eq;@YARJKVBJf?}(8UFx8 z6Oh8py2Aea+GG{{OFNzG^mcBBcz>FFImaG=@ff?CV8%HHH5=k9EGQ_*EI}Sg2pIu% z5!r)Br?e-p+|{_d-Wc7r_64YqGsC3f--M|M?B=iKna=9oh<9k3Vn1>L^b&>$O~#Rp z$|qfv=ehvnzL`^?$Y3E>rFkFyZu@$t<@po%X8EWs&8w|z9xKR}vriZ8lO%B}uWezg zje!ch6c?AiqZt^x@BU|fHLjdkA+2GA`i7b9T8N_QTA6b5Mk^L|m;Y7kH=+G^gziC+ zt2%@o-E2$=j7ib^9i2wK`x{da0;W%#ZNkUwniwR$jf^`crXf@MLgThORt&?bXiU0V znsh6P++>sk3Y<7bkvc|lvz>ZwZcgIc;o7QE*>>)rmcu+Fzd&~-+h@YQk3{t~-Mmdx zWLqz;vT>6Z<#Ar=n1#131kXVLM`vbD*fQz-ilLZlsPSojT)I;NxEoz0yki^u1pZfK zfo8f|@k}6A_NNxu#E6NB!4H;azQ}$J&{?&=)pz$@1PaE1y|rYt375XsZ*%YSkE+@j zQq|ruEWB*O)2KkHOvA0%r@ux!@Mn|8F*$uCQ?D_E(VpaptRewUQX3*$|tgRumH4!?!8ozDnAARX1v*xl0u>6O%23q-0m%T#TD#ya< zLp_Xwieyn zenUc;K~V#E!sKxXQ>ZjT^GqoU)IEr1(d?1bi<_ck;Xnlibw~>7xmj%Fnw8gQx@P)K z)0!}=$a_bE_?yJUJO|4bh!k_djkIY7lngYOzz$j|eZlkP%jre+z1HaFB4p^XIsG&v zTX(m(s#6EgP+x0j?v|5j}Twvzv_gE?wgI$Ji9}y>^|Eu>;<=|9Li1M89DFtFEFi)fd>(!7OKFqwM@dA>(Mnp?Dv!R^2{QZ?zPEj-1ak?a!#AGOL|sfAUpC!t z^x4Xbs{wLBL@zCA?=jn*c}e)WO`Cn^;c$`Sw&wl&ooR>rf=JCc;)M^(OF+OsVzeaQ zW9dF3X0BxURCKSTAw5Jqq>VaGnvL7i1J)8g$hsfTQGxAkKZ*U|h3U)Q0cqQ+y;#;f z{=A~(8ET~Zc+iNh&2m1TelK$LnJGeD-W+V0N8fYrTO6u#m98^* zdE)_*NFyH+fxFE9Oou({aChsUL$9f&<67=zXNl|fohRyvquNnPGpJ3F%=^Gjro`T82MjEn#JmybkOFv=(CJMZP^ z3AP6(;vIU8DB7U3)Wvu(ivnUlmhx1t$opgc1h}j zjCr@i|LpRx*Jp_E6Z=CqGbZho+m~PNHGw5e&xTQVgUOtEa`1P%v9Q;@3z8ZgYWmzJ zW~$HOa4Pq@asgMa4mq5XksIogIg*5#%y=tn+T_kE<{6Dhc#=&;uu?S3*K9R<U+TaBAY-y^4)8paEt`Bbiv=xef^9HFipl4@nstoD8YnNX=0D?pF zQgm^c!pUqxA`6=P-2Pt#_j(6e>vbS_6Kbd;)V>~1?D{xA!9gL;Mq4*O!QcK3w9eqC z_sd*QTELMYEkW#w+&QxE%N$1Qhqt6f@A~6XC39c4Lv2A7sZC)5q^7m*1316}Ow!IN zi8m;HJ$W4lXYF7^EHSi{V47;UI?<$i`sQ+h7cvk`!utfCXrI5my&a9ZxjiLHvg(Q| z9sJ<4k)bUL%Eq>%4N9O^Az&K7xYN^5%GSdp9J*3&P)S>@xRnx$G_rF?*uBeo43-kO zVLlRkmG;hlm2_??pkM1MC%V$J*tQqAlRe+eOy`mmCP0p2`(S*zCC~WutuTy%76k+t zZzKi<31-8B>Xx2TQo5+|%vHtwK~G8~KDXK#+$cRYv0L&L<=wxxM%X(l!|xt%jr^WA zbd}rJJ#8qt5lZ{E(-bZg69uZ5$O_6hc3dP+pa%g{=uRG6_q zgwH7T*pSLqa@T?VEf)kQ?uX86m3W@ysVc)BEP+F8Aji~h8St})`hM5y5shtoRAAHq z8&dnylgEkZ(CALKWz=aGARdWVt2<>=3d#)LMgu5B5^yu5TY2Lz2b+izqfoKx98p4!y`dJH;#Ft&6 z-}Ct0#tYp~fjbQC62y6peaH7y;tM39$3#R(x30+?JjJl8K6+!F<|m0zc>q!QKy+R* zzt?LkHsIIdcmM3TD`r0DPxzKCu5`BY{z|}p5G%L8L4-exEh9S`*v3Hq)Q{X4s^8T5 zLQcj=-a3Q(m^^OC$&vkYPsegc^2k)?o@K+jpVFLE!}x>tAiw9U+^#V2v#ys13hn0 zc-$@?JhXrSi*uQi0#iPtKRrIh;kr7d;`Hz?Z3Az-#2(X-W8WERhfU7#Z;h@wob~$p z{pfG6tfcvw1LKLIp)(Of<%9vAa~4WRKRJxJ&T`!M@vU7r_<*A*E#`)`txEI8__RA4 zy5wzM4(k}HuPT^=3%>sIhLS~=K>eYpW=xGI8zK7zX6IiF#8B+E3_QbKZxh{*X{dE2 zC}G++25oiMYxe5tnzuW^7s>NjEZ*~aUW74)83>#Z;5qv+5Q;XV1sS^_WNSob3E9^_ zcjkoQiq;4^;6)e=B$t!x3a1v9g{Dzl+nEt5Wj=Khg)c2GebrFa_?ial4AR~&r;Vo^d5&2Hg@%^s0oC{j zpAB-qg#I#IZ$0!_u~aWttSp$=_(8GtdG0;D`QK-~SV-G1Hq4lO(rRM>uXgVLoI+Ah z&gQ%x|GCsyl6OQ!q{a|T77Wc2ca}MS1w+c$le3;C)2B)9ek({Xi|N>Fb3J+}L=q-I zAAec(%MISK8O6I&kKd@|inP{+IyoMb$qcs^hPw)2Horpmq@j(6 z*EqVXABFmXp5Jw;e8zRPiBimcgAME^mpx}B0KItuz%`Q1{rECg-1pZ}h)|Le3i4JwBw)789B%3-2)Sd$;$GYgbEJI6)-sXG5omV)#H>TsEF+ih#YRxw+(e+cw7<}t z{QbD`?dRj$c9JO8pM(z*FSUc%4rwR>oOJBHtBJUmOiKg1#`@Km!NKn4CDG?G4+e$7 zS~CLu+UMh>-#1}6wL$^vG11q0GEqoCpZsomn8|o2qE>Bj+LU)#uibzoLCdRdF}-uj zM#JjMJ@b|E_julE5#H&70hH7H4CDr8qX_s|ro#5Q<>CFCCQ%W3?zjK|Y1{w`92CHJ3D*&-yuJ9Q?=u(0FiJFU|T}b9uHRzb}nYgj#$*xuf7E^$un;L z2oDoky1-M)lQrl+>nuV+=PK!15LAgv1^-?zkX1u1oH8ryd}IA=oIn;^gfIH(;1_;^ zC{M(9@}?5l(|tG#b>jai;u#l$H?PY$>%j$MwSuO0p$S@ysr>!T z*OCS6KW1@o@zL05`ylx_f@^a@%@2Yz&k*&5MMvInAO9qORAOz2elSVvLCADJP(%;? zepWNz?66oz+IeGEi}df9`}lY9YtSfEt<)0+4+6K<2(EDmh}4J{v8e{KM*uj(K};%d zXxORWyjh2dkV*ZKDr89k!{OzRhnQ7S@R>*QLqTZ;Eq#KtmpJtCJ*jf?;`%CH$p=&P zowvSh9QmJn)M$;5@4D03O8&GPCKL z8s8TR;Bg!-jvj{j>}LCbZdrH3F}S5E$2w>|jc56FnIzJbXIs1m+()$!Yb=?Y*=+6m z>U|t<8R&>ii-zBRqH=J{|l-;B&HO!EzYJaT_o|0dl*P>BzNvn zu-2)y?kdiNFFdece+y9jHvUy4oUCY3{;_OymI~V3+e1x@mg$tWjwnjfHHdg#q{wYu z7-yVURWihAuw&P}W-~oq4!^*x4mGVK5xTMQu~X71@5iBV+4zQysINKIWcD6g`zc-q3B{XipI$C7;5z!1eQ?)vGw14(Dh`pV%{MzB@(d6-%cfp{t`>@WzGUASaRk>|GE3McaO!aqD;^Zd+tz0xQe!Rugbg zz>@|NQ)JlzLc>Br$ZZQEjJ5V*eCzl?_(YH3c`=8FapG211DGfFei_gus-wea7mqYklD> zpQdr4)UY#4jv9Oa4jAt(a|GdI&fJClv3fu4p2(6!O;8adP<}rR56O5YZ3G{9t^#5Qh#lEpOh0p53Tett65J zTPE|B7de3w{Mu>eFDu?93h~$&Y_9WwM&>IC?T!1qEyBa(Pn^SsA`%4u0k3qMt5bZnPKp&Gv4C?TfCdGa=YDA<1 z`l5xQ^0U4WeI)GR33tpj;5kmH|Fb)ugjT!}u@J*Lj(bp7|MK=A@BZfaN6S8aAFrgn zVY>$6j)6C043EUZ{f)ImJNs*+<2u!E)0_IZO+Ksl`yMB2mR$VF5L0JSCGGRz{FC^p z=PA=@XQX%L;ZQtUxQyW^NEZaO`Uwu*kO@Y5X5xpigiCcBBuarMQ=;Hrl^oi+KR$9O z-$1y}^P%{m?-9<`YZ+iSgg;pL0(=ne|My;V+dbE84>e%?tfUUFxfmsWo5r72j6x&rUFFL_#V?0pd<7?LVmlkzGAbaQ45i?jfJohijhP?CmXug9=>*8Cs^b8U zm|7kjX}~i%SeQ}j1xECnU}NisNFMJqZDD~U52j7~Jpc^_r4IF!;`t6Ru%NN7m}A?d z2|j;S0>J0Xkk8jseGH{?zQ4!(Sd9h&W@KvfBgfnaU;V_0=ybk~&rtj&NFl$M$K0wI zGgzB!MO65n;O3V7>eZ``gXzwcwvcliyedU)4}SILc{hOzqaxU#*Z%6Tt(X)`G_j`= zwHp)LrWG_h4Ohx#;w?%Ky|elDYBZ~abL5>2fkw_GIQhuaiUH0oBxrEx**Rd%MJ7MR zv=hRx{ebohZvcQZUXD+`3k(hG0*PGyV|;Zl#!Z|?#zI4e3#|1#j3^=W(`dbaIyb^NR)fmnn{;;QowdVQGnI-I^#A z6lRXvX3Yc#tOEY&5wx!yhVd~cg=Il)-~34iiqPWtfaXPK7*xj^8)|73p#fR`xAnTU zh)4UB!?;5^kWO5yemxz@@=glRiZr0bhqW<0+ySw| z7n!!MmqSD_w%+JkdA{f(qK#KK#m}pJcCaL$D{1F^gIPQacU+Er>r>aZSJX=B^vbb$)2Ecj@vGEkZ&`(8?LAtUiO1;VF@w5HR{ifka{{Y z`k9O?;;z^gv59u?O|gmYsUTNL)%}fao2j66(eLEm$X{^jn$r>LD`%EoJX2?TR_vXe1c1cXqN!NmcjqZMavH zlaph89I)-7($LfdCsE(#(7^0^`_B_LEX3Rl4U6!jLl!T$2bgZ(S<%;4HK@=L6}@MV z;0Ywj+^_iH&Hr51RDx^#Fa=Vkm)E0SM0Q5C?Kw8&EAJY+!V#o{7tifqRkhzp6_AtU z!_dd;#7vP`2HR?cJqH_2#+T_wD1( z%eaJu;I8HD^z_FAi327PZdG)JMbHZLSk#ugmB$B!4kRX0l(TY4rGSsQAay39O)@eK zH&ig5nze`{otm74bWm;DhGUm=_Z%a$3S|e!b>HT`=>^j6{&XwJthfqA-HGL_V3{#i zrq^M7f<$ZUkYdo=d(YHs47|rds8(Oxff(3Fy+{dL{CIfS2~U!j$il)hNFk|Kc=r74 z37iiR>4TUHo8vJ2vtPr~G@_=Zb z@teY2qSSZ6fK}Hj1?7&B(GOwc3eyBHd->X1T0YSeoVE^PIYpEtSY4YQ1_tJL!!L`y zQnGC$gTL|EGrh~*XFCctE=pokTDdw&_?hf8Sy&7cHTyNexy3Xl6tr$&iAQ}jyUvXK z(M#0VjMAAPfz9SFGNIz)U{wExm-exVInz`S>1H!3y^BmNK8rA-bakMaeZFA}o&@;J z!@&xqA?uO6K^55YA2(a7n(EV=RS4e!2mD1X^njB!xVsgXeSd(s^KatbuN96-O1c4z z4-`qM==aMEm*I?!H7<51&Yn%YZP^z9>R`BjSc|1p*;(_>Uv`Vrv+Pe}^ClPNeaZ>~ znQinF2Uf2#gPecqLP-DfsHNtdiLF!mAEo#oyt)$|As91zfbDw+LNJJ=e z^s5VTd3KQP!icIGO{HR1z{>dvF^%xY%A-epx@d?d^=-Du&a!yFZl8Pcob%F9YnaFg z!KdahngsDj7886Oc3%odJ9CBSRRvIRs2Ua9Z^d2P8M{N=WK0&)#zY?1dy~?VlW}Ky z|EmrVi7L#JcV;hmZ_5kmdrhY_6XRP^XY-qdT;do@=M`x2Re$cSC5>ltvh2OB_^h6Y z4epRl-^IKv$-B2c6V3}4PCwOTW9PD5O_LORci8`@54f#m_W*>t~kWAN0-N zXmg%!hTM|Rn~olYxjTu7|SbMG!6cy`*b-D@_kc57&5{%!{|jJs>IE4Az`?EB-P^BihRBl z3`11+*|gl#Vp7J(K<080h>j=5U`AnHIyRP-WMfgX46$eu7Xx%Fok1SHN{_WahA(4w z)9OnCQ3HsJ&w$789qN*-xBQ=%w_V=+z!III-v^b*+0tq~TgKKDT3gF)5p&y1FS1U2 zPlPm-k%Gjmew)GExow@EW-#}UOidk`h>sQuSlslGHrkmF+j9d~$i3@KsCVy~yxoE0 z;RnD(VuuD`;rCgH+nJ{08@YnS#)wbY^R}pMe?6{2v2f*%$z`Wbwvf0&+4F^^LDBQM zd05VHU++`%637fVxQ~DfwRP`iz84&9ifHc}4SAd4Mdwj<5fe`H8V#IVY)%O3oAN8s z)9h)qE~$39UWu_IJJ4I8(p&Qu3eX*})qIw2tqtp#-~_I9^N^nMVzuyF(ExWJkw@?O zls_)o7`X;JHvZZejCO477rV8*%)O*(^ds{i3(n$g)Yo)xkDrh+A=#gBP(p1>O51Q} zR^%KyA0t-(>TrxE_(MB~jfK!sjHmU+Va<*=gq;xgyp+B*I=8(TgKD5lW9rNsg+IKt za`1t#YR9{Bn95l;9AVww!_B>XKc`QDdwM|Kqc8c^>cE$#4GtW39lPhJ5QY|rzFI$j zu3vOshnDH%4@BOsJTy|}Cg5F5Zo2~6 zaxjOqZ-@tZeEDU^!<0*4V+^4xut>IEJpJbym$Zl@ZwcmfF@uE!P;Or=zgQW0n`k0% zhI#j;y)!H8SJnlNyw@K`ngu^uQ@bjIsUW6x&*bziuf5qK9*l&wT z6I%RMJ~=g=Z!jVRF@i}oUTc*smm}#KORS(^kWR~6R zh5M}}3K@g*WGC@W^TfKf61_Wg?%r*Z*>8|Zc06KDb@hW^IKDE6s}Z!^qEs^8lFK!F z+;DKCWW1B>>+3bPIk>o{js+GpBDr#17tRz}fh!e2d;m^n*q?vWQ_6IcYm7gecFy3k^Yh2)SpJTFSbVQD!=Yjb^QY@qrZGM{t+Q5G0B!2d(&>Me%v<%1dbTWss(O~6$%wNJA zt{EGH*&wuc0tLefwK1vSOoV8W28U+=Bzvz_gy#!w5d?X;VqFbK^^ebheq!Ere-(|5 z7~=!{=907bLAO%)CJ~>@(h!ME#D*$x{#R0Zm(%+A39!cFn^L<8(qE><6Z4_#>|e66 z`nTcVBWfX0ce(%rnRupa5$i*Vk0fiIrC!|arM1w0p4PUxZdzn;SUfp1<$UwWpAl)) zoR0a0D}DRA2zeOkgC=ifjg5_XEE_Kl6bCOtv1Sq>#C6w>Wv~PgRq!NYU4pck`H%5P z@*w=ma^6OmbZ1WDBLZuE*y6c&ej(`;$F3BB(jNkT5eN5{(~A?Lf3(|&1tV$TCw?dN zmYzL?ce8QU_;hD-!PwS6PuppFkwL;Yhc`ju3+%+meR@ZP0z(%#O0(E2Wef(1uF5-& z=MKs}9FAhN@zR-IePyE&sr~$}muGc4*9AoCg1YTxYo{o~(2EfrcX6JI=Ec2+?*Z_0Ap*3ukHiiWb;@dhS z_wMB9akkfV6FlO}(faD^FDI+<{N@3*kG<_Ndtw*_8aeq450Gq#%+|LB4-vjso3JuOF^2GD~@{Uz^IM zU9z%h>yrdg1P(wlH=@F`{QiDCGfoeOI?iJ!;%F!02355V0q9cLoDM0onZAn3+OEq$ zqDk3$q=+lVtXB-shD(w^z_Rk;k7M3j(}(B~HpOiLHu8rCB6{$ksOMDZHg(w5*k)X zI`pD5Yb=AP~G)Nyy`LTq^ugmCG{P~wY z&dfaCPW0!pp+8T9DMvxpPFt_dO0IU;$_NH-bZK@4CKAQEJ zMxiQtMlJMCfu={WwWVdOu#Fpo3_2ETHUb46ww#vU>+iy``!y9;TDc4~EENTXCb67M zSg@`;5!BSUjh-tdQ8)AuyVrl&-Yug8C}k#$ zuIuvg(&xP=N&vwQ>VHnVA;KN_x@>_CXSo;io`-97z_>hxeq< z?wW2V!mU_41w&oEvz5CdC%|yi+14fUnC0Gf7YYNeqM=A8_qkr%*2_+r- zejq;(`Lvu=?9YimTH`s2S~xAwooJp2cpYbh!qEc50pKBsE!(H(fOhes$E!)V3f9Ug z-P{f+=4hzJzj?NdJ?6YG8VK5m>*RtkCO-b?aQ4KhHcyEN4j#i_v&6@YH~@Y2;f*oc zoa-g0q=eQMvW|^E$FL&-i0x@IGW{1qKF%I-Qpw)GN&(8J`*`Cxz25`eRx`ui>r{sy z;FCOh^I>$xXiG?-+;ALqH3F5@Pb7aU@{s%3FZK8Kq(o-I;J*TvV2up3 z0DZd^u<%(gi12y_Lnf1LdQk2oWh=nKg=SwF>AW^>@(Tz=lV>WtF#mgw zo8iS>nlv&DM}RM4-?v5VYu`UbOrQ zg~X#f8knu@$O#{t)+y1da!V1|Qd$B!^3H@dNqqAJr`@6a74h8ix$8KOFH@dmXVk3= zL4!#F3kTS*XakFL5>XT*qf(ghCLJ%P_hkwS*75CC%AcY^+FVf_bC6MBkGTrXRR01} zF7lbQQ^5`)3THrG^%gY*K?S3I0CImjcKKEaSXOJGL{tmql$5~UylQ2_T_e{!_%%8l zcxT{^3xYVDz#FJ;xL710s(QzYL)a{*|wE%y2 zg3oZTPOX8kKOV`?R|Nmja3Ftq1{16pIG9=NJpjG8UYc2TrIK*AdNl^&-S2Yb&PJ|3 z9HfxY^9a3bsrR4_AY1Dkxkc7zwa*m#x(tEY2Fxh#5b$pLpAWY@j9(!T@1hMQB_-_U z$If0oJw272ERo?3<+=|uvd@a>w319kU1Dc9-dxYi-+dY}Ge|+MT(r6y*7iY?-Jt*(*Z>JU`+l&04hQgUX~?JVTf8(ziBN%aWU z)E^AC9t0gZ1W+Nv0)cF`=EYT~n=y=07DPRbGrwJ!WBwK?N*4oIeZk5I7!QA#PXXp* zj(fbs2-U*L1Kt`gm|5X+ccL-3yfb_*o!-^N^#vvggQRfO3 z2_bXzZBB#p=Fk+DYBHxGjB5&z)}4!ES$!~BU6^o2zpegP->n~|YLp6WjBndZxaQ_* zR`$H&v)+M~OXuIK`cpc6%v;@6iLtWf{d+CEwj+`-hiC-jt;fy47)|vEhhMoJ!Uz(| zeb<$7rU@Z)5!8H)Ik;WPpdr~gZJh^M+Twa1UXK)64Oq_KZl3 z`%XP&&1HtuiVhi!Qf=c6*R+avFQ)33rq0bJf{WSh=UtnGxyE%>maT0av;SRyx8(l6 ze$B|Wv}8uE!Po=rtpI}B!NmfNk31t87=(c7ZEIxk$1XvYDmqfCVNCVFmoJ~1RR*=n zrxl#55A+Zbp^b^2+ez^7Yk))szKv~m#+f=^l`6eF2gqpR_`7@%yK*1_Ir38HjsCp< zx}|BJ0&0P^y#tU*Jq*0ypa&2(;BoR3uzi~MJ;n{xDmS6E?6ZDZB0Q8{a&T(T4kpI! zX)Z$P3k$jbK(quW*kQ#w1O_SQ{GT7ORj$KQ*RHI?&2^FsR%YRt0c=#9(4WAO2x%{~ zJ=vr{(BVRcy8wQ-lBi8qAtS)S=YE@bn~yfD3hg;^zE?F?R?7TT*N#AUTr*Lg+I{L6 zFM7y-_j+i{Q%95)x>-<}_u0d1VC#JU?@woMOo_a9s4{8=MiqCCcXLM+c*xs3dC5&a z$h=ec7$fS5?4`h(5DV|wKeY%RTMZH38%&3g84bht4Q2(lZaz>|gTbJud4ey*NMPmX z?O<`Fc|<~?#exb3P4QP>@1cA@5YU&E5C;)Ecy}))?{;zq!@w-g${K`rE;^Jb@ z?aEQ98E>$F9P&9j*oTy`niDsJ!3w2e&m%;ud{;rw+gRYyCNZsr^h0&BKAz-;q5dKu zp8b5q@b5#S@;cP9rfFWW0|Nu=1KR~?I*exR?zsSObFS_yqNwqvIN?Hv4)KssQfH)c z!X)OHLgj*Leny=OmDB%zGE|^F$OjpFqjdxC4w74jP$dAgt#n?Tu+-n9hLJxOl5Ph7 z2_KliJbcO#bsrVzGP37;H%EWs1+lid+0P$Vcntw0CSRe*EqA6cH$Se8e*csVQ-=qS z1X05&KejgM{m1`d=3_*bapVmq<5MKzv=XspUNAyj@u%NsDDYY=?ps?Z>f%StW;h98 zONJ9PLlPQ8RklF)w%MpdOK{pT9KM>WeQ*Y!gmy`N@bagw1xu4cxVNh$^zY!_nAstr z88l0Y#o)?!?oZtSHYraz-rhUfYjlQpurcL>AFdMJakU14X%1J!%7$})Z-$_fO=x3p zPZG&%!oW)hr^7#110UZu9WuWC3^bG;tjeoOQ9CuK>7pV8og=e#Zg3p95O2BR@>-a5A{0(UXVQktLE=aY{tAN-(;@P8;6b(|tq zkk5$xyOdtQLSnC)>HB-)PU^rO#-`@X1LG}(Gi1Q~Ce#0x;&loXvdetXE-fhozm-v$ z8EL3pMG!rG_l|tUeK&=ZU3t1)j+S~8{~4zb&F4-8ob2Os{o?z7j+%`55BCcE^!Fzq z-RC3wP3EYSln$6V*Spm2=^|%0%5XV0>Lh-I%;C<-WoUez&Y={q+o1yA%~69LPmA5q z^I3oAOCPKTCyGU!3oJIpORPL_+veasj*F;#24(0p=qo{nNl8=l=P)|{O|cs|Xh?>i zHz;Ls4PfN4x1C*55({z12yH0Ub4>}+#pc%R&M{vb^vHY&1)z(DmR1uJxB>f<9wpqi z=c!SbUb_4oRoXN`GhJw~)C-=1tXn)>9HvlQ6an-p=JqZ_uIt5%gx39XO~(emej=(b zc}4J*|Ide+-Fv5jo+X4BLCL&?QWm z?0iq6PMmR9WJqVekRf-9Jww*)pC?r$*jN5(^5tj_d%!E)jAzw4TsZk^WIopIhAW+#A?vh%)tu6EO7m5RVzRem*wMWzsb!gq|QG<|D} zq}&L@NP7y$6?R%?rPbBdLW~D=0bQmW&eSYfv90_~LaeXNQx0#_(`8{wU$}OX0L%5lHJrUlP&0c61}?o_r~g1dtf!-cT61LZEL%Gnep^K)#d&Ff#)&q%|JDCv?=8ck zT)(&BQMZjC2GXd6A|)tYDgqLMA|Wl^-7#Q-N=XYy3eq6mpdu|DLnBfHNDnnI@T?nk z@BRD#{_pXAdERgD92-2g!pwbN_qtY`>s;s6n=e~sF>PWJDPr-uMR1GAKtE9`Xoe<; zI&1OJG1UF~32V9*7Yj>Ojd5WVA0_`O)Khx-i)ml=>$#>b#dxmvxn(IXI&Gb zzt4PBHWu~hkuCoT#^MZVsgL!#jOX@$YX8r-XHSkl6n?jXbMlUN2ZuX=dz3=X*1dQ^ z*M6I#vXw^u z{>ahJbuKFZJxuiRJAr zXn5SjuyJsNH%%<}5m$H%M&BUUAWX=F1a%aorG|v)YdTDn)4o1}!h8Aq6NBSPegB@m zBOZ05>$j=iK5ZoS;))jG#Z+tGJ<{nnS3d>P?>o=8tZ(1c&~V?-@B@PhWXU%%!li`7 zV7Zz0;_q|^58oh%n%Z<{%=4IwC3$*x+GfD6l!-~IFg3-m3v`Vvs}N_aF%$BfUu*H+ zIS9u42vW8}1`}{WaB2{7@h}KJ3GK#k8Au1z9n?NUjnd)L!}Gh2PD={XOrK|DROJvN zq!`MICWl`<@b^vQ{aLb#Zw2X-d%>iNN!4uekR@SjWH*e#z|hbXh~5=sbUWTp51jXf zUzCh>FP5z$bdzu!;*Mk&a=w?u7FFTnMK-M|Y7YH+N5V^fo|{JxJ`nbt?0tU6`!5u# zEm;#p4Jf%yLl~wpRXYVB{_5Vd2^Di36oYqyJRnzlE_90ji_d%F=c;OIX_gh6ltasY z+3Dp83cv*Gd`Vgz5^NFPp#R$5`PXM0xn?F^n9D(c6E)y3u)Mmuy11{W<&8l%JS{b~ z9lStN?C$oIz?ko~uHN1hqZk(nh!}|sCcu{~1y#X|)JvblKksW3121TsJJtH2Hy-`+?MI)JFbe)Q z1#4<*?k%OIWqIL%JdQ0ta|$tfa#HxWHo?n$j{^z|d0MNA%==D#zJsp>tMBgVxgspA z$;rtXNPHNTK>V-kx*hD_e;^INak_OZW0dMlu*dnQq&jhXu4lYqOhrp;esjHjos4tw zo;8XN$^zJNpn)0ih~d|T+@Ql1$y}t_2lk!K%+B8PmQ(K{&7q55si%Km=-wYUMyih- zUbJao40qlU2BEi_ni_HTw;~zkLxD!_IA{j#Tk zvi_e}T+?N~fBp}J(v!kyA&RS0aNu=-#dr@{SJ6C ziT|4)03PF?*JJkg-~ahP6zc!md;9-C8ue$vKiL2#>WZIEc7SHtEW`%|OUo=k^~N`& zL_Iwc#cq?};q>c@mUW;{*hBwQQh@b#3DO%C$wpeD5(2E$@3W(mftBu3QwqE%aKbnW z^c;bf7(kd<%+4@$9|MVxqEK3dVOdrZ&06W8mcMGOHz7Q(G(A3 zpyoziGxEpes^%F^PbbIv-@7fWx3j&8UkdP~{y3!1#eCtyO(0-FS)cJiHX@;kqe?@} zi)gy$auQ(9XUWKBp!`2xEN5qD$06~2xCfF9Aj4-H0C+JppPh%PWKhjiPD)I?%*(5i z9PJp%UbSs|H}ZPwKx>~0kh;tof*4&PU0#Lp?3B_{HRu53_L)mdNkPs*@6aK2$z-N0 zRbc9!9khYYO}{yimY%-iGGuRWfBSOechFEyJg4P+lZwauo~mjDB^8xHUSCLLWEv3n z{V1+UT#9wiZ4p|Ljkf-B)ME>q9;=C-7OGfoWO0R66%LT}C6D)EFHOOWfuq0!jDUmE zVg@<@UHH{mw7-s{W1-0Ac(7JLCd>B3kEc)fXKGdSFW?~^pcM5eZ(Zg#>$xl{T6O8x zPp6B~moBb)1dMxVdlFXhtJ$7&eXXE`stw3krbGbk&{*pU*x=gW4^gO-5>RCpw}#tG zB4V+npo8SbpRm&~YW;k5(lFoD(voV<AATI$Z#KgfP89dD)V>OC?1Or z7!OZ_Ne6i#PT>17l^;d`E0ex^cdo{GDoeg^Nr;N8RudA?>rLkf*_BLpBNOFC3Hg{<-a%NRjEs!Ovt=6WRV4#(H^PNG zrg4+6?#!>lD3(JrHwFvOIK;mA(+|MxN?@L57uUD~4iI-(HWgVGrddoj2J#)Uj|AWa zgcDU`YhGSGSx{6o3ngl|mFL!gmRk$B{&u52F%scKXs674|NKnAc`?qic+^YF=kNgx z$eTF~yG%{P-v<&iW`wb+e*g~IY`Y}g2{m);3@@)k!fU;H;PvM|WAWJ#H@Q!`5I5GF$;jbg89W)g3>#p1IXi|!c z`EIqtmE(l>oZE9LBfGAJp)%g@C-ZLVqViXb+5^ezx=?VvjikX=i-Ad(YB4u zF?E)3u!G3Pqw)RwA)C_Mi&;mWt*toVqs66W_$SY1}softuMvtCojvGxVgKL zyX9bFV(QRwq24NCmoj>1;}zq%HlE ziZC=l!G8Cy2Q?dZf{|r_z=M>$(9-js4As*)4g4=FM&gZ~2ied?` ze!|1U#~(aS2Ir+CX(J8}XmCaE+kxIFVlzs>8vj&Txe~pA1@6hR+FBz^wlO>pXnM7S zm&oW&S3&j}Aaaph2Cprv2#$VmU}Ps>Q&ZFG_DZW65SIFL^t@qY0o>Acd+a^{BxQ(JrJr(SD}uq$G7(9#VJ2}!A})H-_fXk&A8H%z6ZBa;x2RV%jfQBqRkKx)qf z26Fl<(Pbdf1KIpf$1=FU>!w|oqaFKAB6%z#y-rX~_RWL#dfRc1^7F}^)16bGyO{)i zRu{G?xWtk8kD$nw1)N!}g{s|3X&D(MZSCx@UvI-!?p{|<#%3(&Q~n6ATc#xn~CR;aBP6k@=HYM zy9y0LXP7AsQ1luw3VAk$W_vLvgwrP?Oc1Wn#7J(!;&#JcE%4m+fbr64-)k*xAf56d zSWY0dbFO-{7qbI9*kQThl3D$m3#CACsOWJJh*qoesDSapxuR@i=eZYqUSwo+^Z4=O ztKhq@(9>6&xoBy{)CSOHLuj0a5n{|tcls*8Gh9EnK7v4d1^7O-GRI7itNZ{sTzW}~ zDw&UXLqh{4r|xq({)sc1plB!n9{<3+_DAwtnhVY&MxQ~hx_Z{e)HF>wQ!Qy@!?`sV zrn;itmm5kaBhB{K2P%DnGIm-_e+q^gDiJG#})Eu%| z#XxL)ar~U==JEs{4r@_TQc9|=m4M-lH-( z*{TrSw1LBu@G$K&QLqi0sUoXvUZ83V2j$5$0Pc~PTo7=)k4ylShiQ6jPL#rZ3I{|* zM&kO-vZvG1vz7-qz|#G7;oJA(=7?)`Z^k#TMab5I_wfb($|tiDhB4SSMEw{5a^~`y z)0EPERkU1c?#RilnFQ;9t*fKTuG(?^BoY-B5p%XjBKb;u7oh1kmPOO7A zdbRs8nr>lp8+z!NB)j(BUh={zksr=2V)Auu+QZq9>o1hA_y>lDPB?7=wu0Q@bqEeL zv4vnB2Y=>W({!1mkP40s== zbN?u_K!8g63;fJ7l}g;6feahP-;tJHp0NWnxnSY+b4etomA&PGv7FG-?QD;!mS{H( z!U-CIu1*Z-iJ}LWps2$Cbc3qp&OnxGUM;zZyK{KURE{TfG&G8S%uBQL5LE+26*n@q z3l@UznOlg3q-B9tJ_g&gus;9O$-p3q^xV0r0(Tf;+^2nRCq@rQ^d1-(_j-eIMc9t} z*N#KNx2q!!@WJD;eAr=t(+!&S0ritx_v;Z&hi;`@wTi=`GcEbYSd=r`LRGY;*Tb_q zMn_kw)(WyyOH2EcGXb1K+RDhP^HclF#Wsy__<|ebHfTHp*zxW%g~-Ur8ZrXw0EO`u zPDxcY6^W5n@18tAWp^2P2lhRxM$_QKRw#~siUm%+F%;%VQY$vITY%B(L{RrwZ7Q#2 zjk@%tByq^7M4DDsRtQ;iSu1@s!i2&2ciu7n@m1y8j3%=^nMi^PZ@O(c0z1eGKwvnJ zRwp@UEd+>y8=5hZku$4&lv-|@Il48+AYa&G-33X5>DA*~_ue+g6ELD7XsoH+&VuJ| zdbaxni)KI5nYtB`}Mij*)&8)1} zDR_3URZzjZ_8!fHCi0NK;2F5K2Rb_O0C>3KToS}R@!PoMW>;k)As><< z5wUO%^}=sPmlvQ{-aRYf2Lbf}iBMdt$kw-O=hi?x4hMs=ceM#KD%?Q%%bo)QXBCo$ zsg>HN%KO3yDel{X$M^y^-VnJ1i-E#sv#8VZLier8m%Lz^kU*#DzEq<%*WBD(Ivyl* zE3#@8PK&^ml_wu3hBy)jp}S$KX&$1`?DNxdi)DBDTBeZL0LyQ>FkB%*2q5SDGNr-5 z#N;(s^6cn@5YB!ttVr<=*$1nssg;NM(TQq-5Q7q=U5L+yzVHJ$cfoVmUEHBz7=^WyFqbBTR116!lCH5X}OE-$&Xp4nP#xhXL4j#&Iy(rbMF@DA?{= z>cBfsAY<1cU+kZF3H!2TB@$UWSJoEm8Tr`Qoxj}vb`bOHh^Bwu4qSs%tO2ObDuZ*z z2Chq>dd*82} zNv|Hg$|U>tyB#YOY{IjMlGu_d9j~Rv_XBQ#w5rN`R-F79VD^@x7HC?==0m03y`>K6OMn8B!;^lHyhZ-9D&99!IXy5q zSPu>f+aOv;k6XbBG!iy8IU^#~E+QwYud1o5qw!RrM4c_<G2TwgYdC$rAqM+YZIT)fgEh{m@zH?Nk>gZ5U1 ze{+r}@<>{FhK3F&clMe5+!0y#fP%*Rj97}8lhZo7=Pa>zHT0|;KVkaXJ)vt-3kjqt zaO{~Ld1?}V9?M?<6F`zBc~5X5$4mXHTC?W2hv2Bq3pKsb%x4itk#|=mOVhG)bMlSu z@ef7Gidc@=*e7coA?ub-%eOt9tDKCgjJ~}cwWEb>u)L=Ps@jU4SAKr0{3?=L0PoJ9 zu7m97SuKJlRWH(xK+cQOTn0yC0$p;gCL}%2)?RUk1G^N})FLq)Td@ERBSp&vk}`KF zkGHnDOn^@&GD{d&Os!K0`Sjc{?=ZYcU1@ z%&QfeM<6C59i*V3P+r&v8S4kR=rjNrm_xkJVWC|bXU`Xg@EIkj8GK8u{0gg-Wte;M)C_*h0hcr|V&y69;DY&0! zS!4DBN?@Wz&4zhM%F~hUvC0C0=i7q7s8FnCH&yFUp9|KH9N)C%0Md3MX!K^2_F7+2 zVj=@Fx{f4QXRo$cA6e@cRf7fttt<9Iwn6)1|EwwTBJXXdIQQP+VOm`8bAdr8qpkBa zEx|N2G{~vwNd29VaFIs9{tkGw7@Z2jiG?|<>mg(9Km}EKn5oRBmVXCssA>nM%MV6N z#}^bR!6^Z0TIf}!A@`ML#FzBwJz%kpDOXZd++c0`_Km3Yu7<`tO#acj$m=FS$pobI zGYHq5bgIzvte}zGv9$)n81~qjqxH#5#)Y@G-niwm;8=IVwTf;I$^D^SDioluriO!n zr(QJV7?oH}A4(%Q(Frz~=IiVG7>#eDfn!sT$&`al5Pl(=bvl6gh&1`jCR^V&H_t$n zD`uDK=+d*HO)eh-0>!YU$>!+Pv#W&Y2*ygdejqUcO;h zgjb)p+R{UE6OSrI?g-hS#19`n$XSKa3MN~r80hO8Z*MHY)GWYEe62<*tF?AcjJomGNqb>X;006&4%~-(=Nx0#0FDCEhAL}V9Kl`%d3dyy zJ76I*%kP$-OycIV<||uE8%+yl;24`!M0LdsN?)}c-4`O;i((dix#AWU79K?|Aa-)y z@Y`Ft@Sv-Bi-%U zsbi$3OLsjtw}}{#txJ@+zSYiNioJ;7Q-V(OI94}^D8dI1LxNq}ntzXX*jcYlq_d;L zJ?vl<7lJi=?}5f`cVS~8Z3uLjHY}5fHZ^`L!4#g^g>%U4L6?#0<*M!M)YK(a$DbSl z0%Hq4?w(EiQ`6D_dq-ltQ{@Vc@Nzx!8J$bJ~ zy#uNwXM3imEr3WO()0yA*FoV~x7JHlENNzGxmLE_OPaNR8u6mIuLVDDxK+_LL!4h5 zu)=`TnO7}@u^Oa8M8HNIl<#htqL42)zvZMij@|LsW5~9Fhk<_`Loq@EjbxPbbW-@X z2eZ=s`+In&sHZk1$HR~3$2qtNXw`F#+40-x&$A0mx>t89&F5c3HI!Wkry+g>&mITb z&X?KQ*|CLlb8~nYZMPY$Vx4I`H@Q>EDlaSh6L)-T7{96qPz*7xP)bnHDI|ek2*&{7 zayQu%+@41f$vOaX!_M<9e_~o4F+H2Z9Qw4Sq}GbGbR>;2S(ijEa>68_a7MgCK3}h7%zY? z7*YBaSUwKSA+RkBlT`G$jQR1}FI240oU7V+F;y!iE9*PeOWm3+B{<*+6`n{Ft>?B) ztV>7Pa{71UHK3xX+f9CJ2fT(F$D{;h!Z*XbLCYe{@>n#}rIRheML-bVVik;OcTNz$ zdGkpatLl$}3>FOg=H_M{&9kZt%QVE^TAl<4O`DptA{HDKxS-bD({g+_0ez~Yk-6Hw zhCHV2e$TjykpKXu5~(bUZ;}WtJ~rwDh%XV8!CcSQzHK(tbQ*GqUYp`@x~(gH7V6DP zFH)r8RjLD-x>}xLv(5Sn0%C1EJNhHRhkaRf4S*WQ>B;Xo+7G2W0BKGDRP+Sp^_0%4 zM=O`>YHMeZtQ+Z%((NpIy8>9Z3Q%#M5d^+e^3$is^5i~V@PO^L4NtgkVS51C5mR{? z=_{zM;J0skr*mdnI7lscq7YgY;A^gIqEJdBfp;@wBzP+CTA=&9@#_n3jNPi_Vnv3M zvynV^3O(jnwhBi?J*U=VxLxhCAV-X_@~3z?kV&l$I3x;(karq(NhV`cON5;#U#3HjV3Vs*iuNVRQt z1!p?0V>zA~wZ>##YvHRlQ&m@w`XC>h1-WEKsl!Qp9c7Deuxwn!0(hcJ=>pOao*K9~op zA0Z)Fz@Jw80-zeouB)S!luO{zD}74;Jogp=zoul?kV0;PMY|nfO$HkFL#04K zM;cJnyZf*=+uetsMO@W+x&tSDY*@H~%9R7SdZZN&NFg+i72Ms+!4>xEE&0+2_89dE zuMduu9Mx7<{s0E80O|Z}4*5kLIFt+zk^z1*eLT zKVWLck&0fz_bP)6p<;6~D%x@@(+b^WR0fIWme#BWAaWwJ8EOTM$=T2p>N2WGeUOaL zD6*T9(`$>nDKaa~1yKY>Ds>*RlC|bS6x_h&KsG_o!qQ|#2Y5wt0KF%yl@cNcW@d`a`q2std>47KQc~tddy!O3 z+r5g?O9zfI?7A8uyKjUSF6xawa?Xv&EJE?^v?INvqO}$O+6$xQ1WmW96)N=iurVbdXhyutIUjn#71s*z= z58GA;`um0Iww!m6X;J)~CrFhIxy~V@ZdwEw*Y1QkAu<~Qs{s)ALV-`8IS*tJ)*5vy z4?(P3yl8C->2LKKdG2lt#k9W48h^Ee^H?zT5bB56bb!`7BZKvQMMXvDm=@GWd2{pu zLLJkN@HpYfN`za0O;Ac#HUWpd*9amIi+W@rk<6$MfRnLRmR)P8pYwaNG}EE0j7e?= z>K^3goh~2b`9}ZR%a zMLJY2E+v?&dD<{=k#E>c8ExMoBARV}txO0&?venJV1NWZJ z1V#uwym?4!^|`=b-a~-ahd=n%2kk06o}lvqf0yb2F@uZ+^n#m?OXVH-^_5$Z;RIta zM5Mk$fZVD%#BKY7+h&-CZbB|*45;l$TZFi{QinWd3@zljlco8^1ezkQQ_)WD!&|je zRk@;T{fsOuGDuzz490UkdXP{3-hZq5dwiVB{V`>$$19F7cFSA`s2NHw!Zt|%IsKOjI^9u^uNZU&;@ zIzFwjf%K9HqUSoBS!567O;bRqwRlfHc<{gh5}a8e|A!()ZWVfbYHAiBmbL_OAA6W| zGV4mYuca-do~hh7=LiF?H+cuGpCQQyjL55Np})lls{^>!4PNg(ly~qzTc-@=BqY3` zHi}0wbCBNbK6>fhcV6gURjMI(56a|Z%O~QGo@O$J0OShZ%K=C|8$=_KZ{MbXiRB+4f$r8_pKVzZ$zx>x43&;v{~@-=ekMhIgJMz)66?cpAod3buv zqQTimd+uzO!m(UR3JM8;`EvfWv1jTR5iLtkcS)!!9|_GYkucl}z+6Qrc10I3aP=*D2u3ktf^ zg~9Dih4Vx10Y9zP1ToD080CIYTm#nHn`XlY@E3Om{+g*a=V4)FOj1YRQLwYigE5nk zH*eZ9ImiRPwnHuQp2G?T2+@@%MZ>B`?}>>$`!O~qCgL3*^M0(mqay)2^VtSGQOye{ zvLEGutE;jbqfIZHS^-M{`h_yIS#xgryig_=XO_&E4J-lRWWu>C0_x{xB(`6x|)j1@U@8A_+1jRt zY@65w0E!h35XEEZp$WtKlyo1KIf~b+2PjJ+5fQ17*8}iXpH2Y4@q|fZU>&WSEMVI) zb@09gEdsL{AM2n^)fUT{1XqQ;@GpQ(1XJHGw3iqefuF*RyyH;_k8O}T&KJ!A4A2Q# zhIWMP2f3}(%uFSyET?Q-T}xqqRFhpop+4Psg$pUq;v9%Sc?z5o9 zA(E(jVA}c#f`|H((Em+@!xJTU0!(s6DyYv~8B(-whK3}tHD3Pp=XUqr6R3M@K&blr z^`nG?89-59`}m9&oXTy;zmS1-a}$2mQurvXEw z@Vek#eIcruDY)Uxv^DDd%$t9BySJ~~@F=F)e&!Gk@E*Lb&FOfI_$2?|^x3iJDB=21 z>lEPF5PR>Dz!fk4@0a-ZA|TiEm|YKP!S22Ih&k6tDVN5S0*MjAC)UCDzj&Z=-Vx2^ z&8YL_%RnWTK&A!$&E_4|;UcPjX@Bx1qCSea3Wm_Iuq(X0ykAKF#THFCk@Sb^i+pTc zQ$`>$>Is~-YJ_AmaGcyFn3VwNLeqKlMdVeTTZv*~FTs1lVe}z^fv`4Y|I5N~V^VF# z_P36WONG}5y(PX_a|DhAZ;BfnVN7u6zIdHQm_ z+=LIgQvD`!3s>u3Rld`el9F-{$SuIavIh=>2_$wNm?%y?FCd;UM>T(dqWA=@5MPE3 zK%mSV3yUX~pu`0(pjW}}&d+BrRwj_u6ArvT>ZQY#PULUy0F~iu< zJ=xacS(S;OJM6~Hg?cIUKX~+~u&QUMZwG?zh3k$m;Cqi}k+dhKMBjh-P~ZcXkBTJ| zBcToB$4t<{4N376PHD@JOh_c*Lq7NQ#|yV+hYnsK&KT#(pV}<2Ep)`0KSG^6_@ARJ z<5F=`s^B1YrT~f#-Yb>`1qHvmLf;XFT0TNU`g`A@zygatI_}coz!UxkIr+u|QJz7B z{;IWmiZ`4$zLk%ym$HU9+`pY!=oHy&p3csGu)DfgtlFU_Yx;kbYMn_nKUcz&{B#?LLp&e4NJ{2-2l zi9WH63VQ-NT$;dnY@4a@K~QBl>L!q-_=v-QeK)2)mVU+Bp9+!OMxl$D2GYOKde~7}YU~T;KjG59^Kf=0&Gbq9b1P2^IpmEaV9AMRvDihTB#XR00ZmazYgZPs z{QvD1KP~A#e|8zjE|>E9Sm7L_wY4=ljFpAO>bBs83-L0oN@{A9`2;NU*~w-;B^b3^ z&5vj{RAp19;2O8yXmL5M=M%`l|Bg7eq#p9eZ%lcx0?__fiE7XfYBoLIo84>}EXBmH zDOWONna$%wcp_Soig>D{bS~We$z3 zLvp23W5~#2cJBi?y~o_HGa?VQXV1lbKc5D$l`>FmRlu5(XK7W9pfD7sArsKad6+Lc zY3tWhtvT$db2r}7LVl)$Cr3H&gMXu<&J)cS2m7wn%N<*OayTxTM*ZwemB(eo?8|~J z53mz4e?9s1*y!edhXWXvcZzDS$sS%+rLW~?>zmVA21*eLkGAA%@<)G^x+Z)3~r2EEO zH=p#M+kHSLBU3*>?xjyDqIEih89)9=tbU+CaLCopEopdAD|MlwQmMLQOzEv>@y4Ut zUe=_qeWiKFQ9v$9=v?47UT2rx>YT_Re9O7wnGBn8WVC31&euMDQM-%`$rI{_Pz2K7 z4*1t3O;(u;mt99at?x0cb}0{;sB0ILXV}ek0PhcE6&bf*Y^~xb#U{}D9gWW+Y3bZ~ zci4bD>`f78M54@KRhL&(ZozJhYUJ+3EBx};3(^4#YM(z<_A3i7eHKAaYg2`6t{6n( zv2OUG*EIOz3@uAuvGsi~iF-E4{k9v=G*IhOyy!~=&-^8v4t40S|MHS9Oz%6FBHPuW z=(-L)D+B~UFg>VXp$7Y2AZKQlj<6y@u%W@S$P8i8%u;9P=5j$xPbvt?q0p!(s-B&# zJcr}E@!&=sO%e~tblfq}%9jh{D`RMw;K{Gdmy_{f$xkf4HM`#ZLI7VH@NWEJb3>7t z<;_AvzdV*}fh2cOfl5_`xHX|F9%J#Gzaz;rH_rdnv-89AjsQegVFc8j8KeLT?}P?l z=J>e26jDEC0ec9kbAl492y<2tW-8CFkzeNH6A3*mQ!v*oYGSHyh)*nz*$Q5?}R;)FJ& zi7gB@P*5ULjRVvG1BkBBzyX1CS zG*U4Kzn4?;X$?x(@ovT2&{w79uf(iIlk8l!EQ)VFOes`z*lfM0v9H zqMSy3M_T)s)Z~~n;PYSrN$&*kN5}%kI@%FAC|Zg>)TlwuLw!0fSubw6wV&pytYi&A zslE|DiUn9%iaBnr*`hfYxx37Iq3(?w2i8n@qU@zD)8rcNb_W>wDxuTGSe%qyK4@Rg zG&{}@X6~)kYkz~oT;RNvfXkiN$5!%`9zMc^kW#$Pi7YD`L!G<`^K@pnGFX{ya+$u` z-X}px{u#5Rs-AfBKJDu)=Sk*23HdpC>f4;vSD`V(G&fKr9|VJ3$`6YnI6T{Nh_+$pwZ^1^vM2|9x7?0D5BJv~bPg2a-lt zh7I|%dVe`?{Am@tXi8r8MIpHu`&X>5Oh|o@wm+8b4E3kO2M>>qS@VG$bTS~`0Q|S z@2Q@v!RD*#l ztC~{PonuN5-(;2?>=W>m4GS8(!-BenQH4>xCwqh5{~n$E;w|{>#$SN^Bt;8rci&~S zRjgd-o;2;v>Q@S9*6ZPlVCB?74?j#7@2t}|!M|lCjQ%)XP*tha^qM5V18H?59PMKZ;q|6G)9(T)V&$tIVV-|x_VxI++Q@g@1E|zU4RdRm(Y0o2TFzb? zciqbS1&A}13H?!_t}WZN6*i*RxwUxTampfJa^dQ9^XZ)(7T%Jg8!7o(@jdJOLte@Y zX+1NV-T3x|izlT0S7j@%vW#T;K3^o0`{$EhQXeCJeEHFgku$XWok58ZL<+PG{$hdC-8*EXleffQ^*jS z3GTROqZCJli_f7hzLM7cEl2R5R!U0z{TV6om*n^F#h|a**wUgbD=S++K;flckj}2M zRjGpR&oH^fyz+Ei-(Tv4QHl;`aJ~!7L=C@*JzSQiUOI$1$}e^08}f`@-gBKb8mp$m za+F40+V|-E?}6mor=8sL)SR-{h5YFpO26g2BK19TfaZ_SfuYzNXSgE1NsBH}C~-tw zkz75L&0{n~)}2+UKymF{qkf_ITWSD;M0Iz zqBxwGu*@X9xMo>1@GX)@K<33k$FpSmX6DKXkSxm20saNA8_Dq5(n30FdqdbLR~mq7 zLby~_F4vja3#`+RpMt?lpHor?3oHWkYLAm#d$hS7C;%kR*bIN>q zWbjQRai+$o$=Y=!#Hw$nm^F1%T41`2^mW#jZYEhXxe>ZGt2f|fWqVl|@;m3@xt>lFU zQ&SB;+V`Ac5V?`lzi#CA_34zs^aJu*3ob(AA2wg-1iaL^LB9CA%Kme6i_=)_J#q0D zpn!JvwB5GSoYz2Vf9Oh=R$*^)b0p{e2)mKMzA*d2)=rhKLVF~Hu`y@0b^JI+V{E+O zs2yzkKxtzWcif0rKD=3%ST7N^|ELqVpq;;6&}F_G`M-09^X>@jbptDFnBMV0BzvZ2 zs$O;Ll}c2eVem|kyVCR&$D0Q8SNEP*un1p}2#*!IjeL3O7&paBK&IIBM>Vg|IDYuz8O?EMXQOqjUsqn`6L-2xm-)dl8HpgUHIQ44iR^i^Wom3U z6Dm(K4PSI4r|p6iA$ES*Hjfs(B4$(g1)IHR)ba;!q@$9lbIxqL0rnO4i-sVF2%k%W7aKxX%d@o+Kxd=Fg>yWav&d{EBUS} zp=vbqZ?^i?h7&UR!rGnPG_MMou3}!S5`C)sU{jj}q1}T^m zgSj|A>)YsX0QE{V0OAu~W7+u7x|3LYLUd8pGMAAB@wzf}BlN8Uu^~N$rhSFg;(uAq zr6}l?<*5_CKKv%&r0A858cn>}0O^2z0`D>d3a9iRzzg5<9+-_JUT7a3@-)xgDAS=G zl2{&@A6E^uisizd-z0sRVP#u9h>uHDmU#^&QOd0-;_LQh+3~41F+ZL~jQy1MDSE-F z@b|r(&;7mq>Za|}Dl4^sc%G}~W|@M9^I4jgk9XNDvc>YK_e?jkYOn=!$JfPFiLzLk zW1`@U%Eiew>F#{K((Zs7^Nxt>jy;2TYJQh8@=9Jrnp9j7as%SOZeUNuM|pN0dMr!t z<-+-SIRDXPkUH=F`x^c;ZUu;hmsQAh`y|(^YL9o4@osY^-F3Uq6kH;yhh5OH6r*aI z0jH_~j}E6}5GNYnrU1e$2^3~Y^oThy9T?e z-_wl`I7}|utFoQ({%7e+5w#Bbp7B6w(OqsOj%fCh3M&s@PsgeZC|$13*B%ka>?U6N zihUjIjeON#C4wyWK4PlH#kb7XyXxCtjFO04NykVUtm2#11w$x}y1&^tp7jvff6G$M zon-zG!Vhr^83HEA%C4zO3$8PFXKuchR|lDuAV!x&-NUhTPwMf!!3~K^&mLU&uzo!+ z;^`aNAFWo9Cyi`G*cXfinGl#qCcBzqsgbV`2DHw-TqE2wI|+l!J*LyCL%;57=%gN9 zJgKPG*+2aipvy*Gd-J{us<{7(UnLrVq$um^Ca{JLS4a&OZ;EiEx9wslKD@ndpt)F? zVREp7vh{``xtF6dx0%iT7i8y@u+hTZrVhnr-72?y#is%qmVG_03b1f~Yu{hN5(Iuf z;ZGv+FM*MRhZk>tzPbB|+-qi}LN2pxXRgywiZ6O!|q z4(;$fLG0=?g&+3KCN8Cu`9dXwUa$!|A$>+-l~;#Ai5T_!+6f-qd<-Sx+eOuL@2(}1 zH#dlCxL*|r6pI=+REHayC&_O(zCyk`?Nr&{^hCpS+ZX4E7uT*@Xtpp%ySn`3kaHpd2WTS*Z&Fs)e&~}^fpUs#JB2Ox+^UHWon3`O>&_*yqpJ@xiNlA7 zl?YHIh4$a?MjV9U9|v)Z=-O(WSpvWO{u_zE+rfXgNN;Rd8(o%;cIZ(pg)x%@h3c$C zCc`SlLql7PF7kO_jiBznsKg;4Ep zzj|i^qxf0GLn)P|bq$UlE6Ju&YVKc}rxo6wr>#+I7O+yR9o_#NvavV8x7&~1I+cm+ z?tTBYyCHG7Z`%7&2MzJ&LpqQI$SJ2w(q2XjxkSuZX$fPb6 z{yYD~@c_)QkKM7JH7REE?aavT2YK}&LG5tJ3OU!VT|7x~@j|U>PglEYq=0}7;NiDv z%#Axcen8O7=)IrRuPj-Q4(%zJrlb4WDJs%?DZMX|nZ85#;E_utQh|SJi^n^k`|ia@ zo(*uJHTqVp)D!Y^ujzrp5d%@;@`YVPek#Wlm!{ZqDh;T`m&B25sb`#&^wo(#Zazln z9MOK5y+jh+WMK^Zhs=Tv1CWsgYkD}TuBcp5e326dJ2%9QZ}_1*!BA%^SE-5YE7)GD zQaQq^bLT6!ED^?AV4wNkHYG0}^f&BgjfN6mQp6%hZ1OUIND<$N zeD`YuOe{~#V|@R9N!S@B&cQ1}sbHgw_HxG{~C}|*Uw62~WCMjgN6bFMlPU+Yl*hj9%|7#zCrr&)-kkF&#wR|^H z2<>fzSO5g0Fb0Ho+X+I?@7YBqRV>LC`U{%Uzkf34X)-Nv^@`*NJjRy+#B{K|;bGmT zp?&6IO%p*N^Y^O3Fz?{c_4+qFKxDHl8c1)}&8dg~<{Y7yiJwym5)g3rb|aCj`n(3x zMM}^bff?SIRks;($DV~i^eSc{XKN;daC@~WS*C?4*5ect;r`OWqV;}G9LDN8U3KL$ zUL-fW&d&0duoqO5>IQiT@)0FyikqLOEGR1JurV7yk$+Dsds6i9J2dfx2% z)XVvD;`bLM|LVugQ;PwS0mju};>{V)U#M++d$)yDa!ep$1?@M9ak@@hT^U1<@ZHkV zuETTdGcQbWK?l>juZL3K^ye$p&Z2kakmRE#2C8|ZWf2P}XO22SVvLhPa$}x_|0(qa z8=CfR572NB=3lPof+OAVjFNBY1!j3E11?}lE4L`I`_p4_Ijx)kglWb@@ikp`hzP^hJgok=aa8U~&L4CxpbQsG-q% zf>%pZb56=O2-;9_zP?02=|qMcGdvUd;$eX9(kml zp95to*UC?PkuXmRv!RSq2+Q$RFRTa*k|I-@n8v{8Q9wS$;q0sG+Vr_hU~D)j5k?ha z89c_x3-j|qh-EmPjh$T%7Q(h{$Rl7B4tCM!ia>yPkj=@4AGr>}j>duLu#~p*?a8~m z^$ZInHIsf$>FuExKx2lc8W@cQ`T5S7Q9(foAt7f#*)t_AtuejXw7?VyT|vaLQF@~8 z0o2udv^SS?BGmj|Ff(kV4fp0nL~&}79Aq;rWxkeZZ^E*tozFvM6@w^(1Y2WQfaY4&04=e!pPQO46k#qqLVs;^Y-N%XwO_*HKvXHE*OixR5-;=b0 z)ONeFG8jZ~!@?%lSJ61mjI6A+k`yFF!`$hJ9{FWS{X3;sMDIJb)~m>PKgdSs%UI2) zv_}RVnoC`&_akmLgL|alvyiv{oNgHa9r$z2f<(n75#V# z|BYBkJPeHJXqmdStD+}ff@Bh61j@>;ns0;XcZ|-Dzoakr=kukuA;*wfBlmq>*Y`8d&-ppe znRIeQjX_YnZncfv=0mii;ApW`6Qb(_%=s94M93DD3qHT!(MwSA!N@BR6n=*r|YO~(6-quQFaJ|H3+3Qcab_F&?L0? z!)Lp@T~$n7_ck+cXSSsua1#iXO42&EYK*(mvajh`&s z$eaF74$9&TUd5gq{@ zHQ=?is8)^=4|&-pX+ORE^{#c;Wpq)9;By8$)6-~Cub~;owF!YC?dnS1?pNyO7B!nM zsWQk?sY;PraB<-c>fe^K|ICp)&n?lIZGk|Gd|f9-!XvbvxL z3v0mNz0aLQM=4vCE$=B@(xzuV)%3=qrf%EYTtm00r^cq+Qtqje-5kI#16duggCdqS~n(vEKdaoUZC>$&>!CUX9?;$GbJTne{Rcy*EY zpRrL3AbhY9)xJ+oxOzbVY8|e+f=Uz3O3(UgEx#yZuBGp@es||Scgbh@a;fZzLG6$# z`kQwZ%ox~BBc=Z2KiUUu+`aU-A;fNn0%q^Cuq1u^U@HbFc907M^%x$$Vz_49CaQje zPi$jYOy6of+a}Mh74JF6PgbZlPX+vI*wiq6TAiyBX(lcasU!GGf%#5K$h8Qu&~;aH zv4qqyCB|r(#N;^V-%WIC9Aikr0G_LyS7$Wp9l?LIsHojRTho87q{_s&k$DS^{rNRE(r~Z{pqIsm779LkeyX!A6gR?#rvL%-C-{3$s}t8gRNMJ1 z*?r5ByDuXjqIDbfr?8lTv5E3LZ0sq4)FQIR21-t)+)&H>{Jw-_tLH`}Fu&h}?T!|T z`DJzXySY~m>L04tt#YiyH-9D{o?rw*#M^~Sl8ij(O-%rvn$KB%{z+}(CcnXUF>XU; zgUY#(uIF>z?@FB*>K6KQgxRVyz5+k!V>TSPIp9!m;o)m0(r zwv^CE_jHjYJkI6aYc5xLhYLuJE7V{tpZv=*v_pEixdEvhk6*#o2sKB?x(1QTLUt)& zkO-@^pNFW3iF4&xYQz!w94@04e=Lc!(odKs7#R7UlX{2e`jH*Je^HCwe(~;K z3u?^(t^U#V9erMxhE7|4q>tmnE%{I#B&QcMaw?TH} zlXl6iD)oXqbpE(UsC2ldQ8NtNzPI1M!W$+M@b?l5AHAnLg9%MiILJ|Yf*eKxq=E`} z*kVF-CtwQ^o;?8H)b;d=3kt3xLVx40tOg@(qoSj?!F@v*c7Nkwi=&m2);E0`r8i^w zsd!c5Vb_Gl%3v(dp_DA|whMkRHdgqHT8$f5uZ~2av5UvlivzhIR_&GFm4_anZRre_ z^Bt1pmfzE>cj1m|8$&)!F!-dhA9R2FQA(VJ8a`}#oPWc#A;P{zG%I1-0Lpe#Q1(Lv z*f<>)<>BU}j}H$GA*5JDRdpM3d>+6Kt${d$LPtLpdy{!@CL7UW0UFT`JZ=yfg}UIt zRXR27X=Q=FYva82u9=*`ewr+ao7ide$(HUF`!&BP?S`)aM!@;VtGk@;r+SZzNk}K) zr*m&t)ipXA#-j2ahEoiHNVxokdd{A~4CemJQBnNZ?xNq|T8W4T!7_&`vVDnxM@8}N z6)349+vuekehJDgZBH_zTn~X0d8Y{czUzM)p(? z=0Fdl*|##szRz*p zY|a_|85DvC^8*VdS>5=|P?l3S;6iHty^v4p8txX?0h^#boKJ7@;~OkVf1j|wnfa_+ z^NBq{xRVdlJq$?$Gxl6c)z?aLJ;tufWIlHq;7gc$0dU8=x>apTZ4KQFxGb&~ZZWvr zdkVKM7N`d1HwJH5DIW}y)>m=&@er5m< z`!kfHIkT3rY?5RA7zklQ>CYAZ7kDOKGz~UurxJy{8WFVInCXvQp4WhQKRh{>iQ+^;PP<&v};b$#uFa9d!aGCsZ>vg6d$> z_Ftp|+5mySF(+M0B5T?Z3=Q{SxxN5;pEOwd$^o%cHG~G}%75KG4ES=OeD%-ZqH(u- zZf?la6j(^f3^kO3R%T0rnLh?JrQoN#0>?nRp+ein^2W%w^_VezWU?S>LZ4Umx&%l^ ziN|Bb0p5`J!u=qPe*SNnK=SVy`2#^yaooRE!rFq97)=ZhnJON%H>n*>Za3mA zlEAZ)AD>*|Cd8Z`{!w!r9iY=)2}8p|7tO-_iJ@Xo%S+LHlnE=O2h->LqB2dkPC-fY zcLU@vdUWJ*#QuLw*VD?5J`JopW2UU#2Tdcs8GnK;sAV3hp9l293?y@EK@`gAEs>^a zv+tQbkfY{VK%B&02saL*OyNtwqBr!lvS_Z9|KU@bg!QVpo+SS8&z)Xt(YO5q z3&48NDA$5&+4K1L@yo= zxoq_Eiq1{J6jMNS;Dm=?@4exd>~|Bn8ReqXCg0@*9K-VY>imUjgRA^bGSrx4W7}Sr zV^@y^ug8qir|{lBustE_`I{R-L7Dj*KZH-_y?p5rv#<5jCr<`IVFDA;g?3$t(R3dJ zEx1yUZEHfxo2m6%pp65n47$jYatkGyHx@haZTOcAUOY&d83a;V4v^A1ZJoraInp<~ zWS$I$K0H4nH|MYC?$lC$tRVe+8l)aU77kYJ$86qRayD3bL@7mnRJY`~z|0moru$%S6h{%V%(LXb>ru z|0cKmbsczGG+c(q{C=rgyIZ|sS-vK5XYb|P@CK25)zoK+j~9Fzi*jo8Afxd) z?|sG`GetZnr}}Ts&|1&T%8R=#I)%~@VgA@3{G-4R<6hUSY2he91GYm9eu?4n&d$yPDw~CSr1%25h(~p)0DUUzVg+fqb zKQ9Kzp+;eh!N%omkE5i5$7?4$ZGXPZzO!FCE2T^2ljrS|kw1|SBTgh0!=SFE zwbTCIaP?+RU8@e}MVnYXo-|bJ z*05yvD{t^Y7>;f*&K9TrZ)=X0T+MU1VOpRd3|{XV$k9L){19vegnTNiT7^+CbjG`^ z)l6y~XRfK2v-5t$9hiIuN{eSUJ1L?s`gEW`t$X!SL-}?@ERp8wI*iH9cT+GJ2-%P0 zcRoJpS?HVdlQ;TU1&U0fFHQ0!piiMrk&Q$hJM;X1up)W{hU`Fb3)!ikrGEJYb_9nerrI=2~@Yi(BjxT9Te{-RcBDaqKp+1W=jIsEEeh0fDHJsK_L)UBpIpw(82KjPDP>&pfZG8HQ z(IQwOR!8~-t`Xf##Fqs?09SAyn74P@Bz}(CqpG-}OnP%Ng4ZZdQD^@!+g!_~j+X7h zId5Z_dG}I095Gl-$x`%UyR*NUkloIjmM+(hr=soNFCVG~w+bY}Q?`jdqF;o2LY^L$)=sd=-P z6~MX%Tk#*-3AH7X`9OhF6R~3$F4oBf)HBVwmCbP`fOr*@#YR9jX<=y5k#8H^a@3oC zyk&I+^`}*kK|TM_6bm03iRZ802Oxx2j!*3`#szBC;Cgct>5e4)7XN8M^?D z^&%CC!LN5hzBGK7T#+NdSbK)dzg;c4ng3p(cM?WN!;J+6vWS*CNPx)z#(~J2!P@4+ zph>0nHX;xUB5R4f4knO?T~lB+A6R-6;Cn8%LNNP{MWt&6?}r(?TGe8qy_(mjHTDzB zwMAK4dTy?%sYiSHd|M%-+O`K~?L$)rlas{`RF4(!?p_}xQnY#}G_tOGSI;6Iea3tF zZRLO3<6Oi_D4z(qXW??fJf)0 z{emo1R4X9=etuW=)G{V$o~kekF>B6QS8f{24lP=bmL?JrUvt5_jo zz~hE~rO6#sIdvn5ta3pq^YEo>+(pYvDME~@$SxIdxR;CGlnMUX-$J3j5bgM$f)fP2 z;Bj(-1C<4#f27a@#+R<3A`=te5sE?`CiG}z-|^5NlIx4C*ii-YZ*O~n+rBwM2$Wjv0Yto1>%af<%zxh~Z@C|uXyn_mB z6hg^~A5k$W){4izc^Ui`SySGMrTV!eaPy`rYyB5rSURo*31JvFT!jvSfJxy43=iFA zubkMrxfoCQphxRB?eW^Kxdp3-Ug+hC;^%`$6dB7X$04WOrIk1vYfX=&oAXvt#>IOB zKaByUFmI^HmF%U=P)sT-td$6_uhK-`$I&!q<%%#5JCh7!bUuIGF<9nVqrIxOyP=xe ze)i1Zv46p9Z$pmwl|7gjJ02!dam`Q z7)$(2IzI&RWwe(kb8g*tIXswp2i#H^PWH8wQK@Uq9;z#NnU|+>%~{Rd;<0MgT*sZz z!A}G))Z^2N0V#V=f>h)Bw|E1bL_qp4XPN(hNpZRfH@mYvfhq#8rHKv z9hQ}qI!IYvza$5jXfRRmz>iF5FQeZ+`i4XTaXpjH9x*L)xbm!4-a*&}GPPUf-~Q2*ee}vgjQflR&kzYPVhKvG05Uf>bak^V^DR`o$oRkG=`%Sy4(V z2ms~hDJjMA@$YO>n_*H|V6cxFv78KWcbJMb=+%67J%r)JW69Nh!yaUU2bXK*5oe5f@Rz{a&%lD9M9$`RaU2|Ac;F!CTe&0@fV> zDeMA(dd(XB#DMyghlI^iXKgGl!mS2)wD{xQ?BhL;HRyI>bw??pxI!xD+Hlu93sg&p z1$aQhhTXqrM^JfyU@PNKL^U4q+<;wh=f-AbkPx{(0n$bY&4#v+>$4wQI>GM(PM~$P zOin$d@A-iK0)j)f0}fe*q;MB;4n?xSjDB1$DyjoRo$N{0eD%7)iQ>kK#@CVcBPt6RM2JqwBT0S5z1N}gPFWECY^Ot}+E5CvLeqV2@>(0>?qtDyOr_+>BO|@LH zUF`)XBXkc$PzTrLWCMEJEBoO%?AVNa7)X!}&hWk{JR+eA10qxL)MMd_Jd?M^sqLgU ztz)zX}1tp)S$e;{#95Gb+@~dhA0J3Z^1CU?-xanj^pBvwQ^mJX=J?b!n;->TogIIZ_$61gYVDn1cLmmr7&7njgU7gQX%pG9Poi=DB3xq4BJq}! z^>@KW`CB5@JqWQN;kBvK+>A&}f;rO6QSvXS3P+Ij*3zA${idTq@Y!RQ*;~BTl#eL2 z8jblK!3A*t@p_dquuyNP+oVhRYl&jgjeUv-eUIfBg$3=FQDMr!WzA2|(h2;j04J zv0FC@7qZfEMFloe*THJ(^O+OBk9|Y?ghqA&j30)oyK`@Nei(V~y3s^>>1?p*0lT6G z=c~(92kF(Ku$Ed_P?M>15HJ7Uti~)+2No<&)&b8nE?@x9`$V?TBCM!0{R@B-{t5(b&) z#Ya2KYmL6KHQ4r=T|IhhSzI?qap1nFmBN1g&M*t%d6Gb6vARjSQBRf1Q*p;FcIBF) zSC*HDR)HUml>iv@{(1Sg!P4#*p+e2lonLNXM|ol-NzkMAx8$ovseUnx7%G-Bz}Z>jw~?% znup8zGU$`0RiPN{>82BNQ%2CkWM-E1z_2U${9CR3KU;WE6|&^0EsN--sL+6x`*@X2 z+=R8JgoMO9Coq6R{Cq%BQ5$rv&ufBQj0#Qi`PK-S#*JE<@EqxXcwyYQI#t(P)l8Au z!+VV=+QE4f^UUi~pJXPSR^U;Sy)4Vq1&-YZOoqx;Tc^zz*RQmpkH?Y`#k@a9$r2JS zESjDWZxQYTw_EK0xJzs;B80HP6`d7f{bdQjPZ$KITGf8P?Lz@PqHd2CAs_*Vyahrg zMl!&k-J@jye;)SzFZdJnh_vJJd&K=ABcJcFX@Mu7LvrGHimQW8_9f!u)!OxZv$Hj& zIk<89<0>U1ub#_AwT%)8T|S`JIbQ4KW(#M3H-a+{p(2AC&fb5q3<5!v=)B|KDG|bP zYXP)Bd*MrHz<t@!3qjQSnCdoSQURg16NEa}o!u(oyudHey5LQjY+b&*vfI(PC5~|2 zVCo38DsX|@cDLRB!2Y>tif(_kbjnmP@Nf@jfrL@9RxxaEef8t+3(cef{cPxSu6XqE za}-_CTfOz%_@k!&l+@1lqrN*X`a$!-eY;NS3s|jeYO1Q4P-B#y`<2>f2vNc|4G^?o6G-{{9^)U9o1J4*WOZ0@&WMZ6Vldrf z4lXWr@L!l%MM!SEEiMN8qG7f#xw@6rX;;3mGV+flKA<4F#oOX$u-|n|!pS=TB^6iu z`N$)iXu8^A))DxzeS4v8#vM-nn~fNJfpD2&L;wzjU-$H*C}tW;GwK_QHLP#pIW~O5 zX1;M_2vRGevJ^^wi^X!yc?bbQ0s{l*R*hk1xd)nTlsUnNxpVPH-j0jQC&7hnhlPm3 z5#&HBnL1@uL`8i;$Z_70??7SS_P%2v3<=ZdQzIiY{QXZ?zIp|ArhSDsfW`*I)n>lWo8kK-Yl@)HtEmGjr!by{E-eSxY^BI-1(euiR6spek)yY>GZN(bKoAeaJqh#s{(bT{a=C;TNNIboeZCb*;Bu5M72 z2$($kp+VG7ugw%-cYuCq*Mj}ei4nS`wkdXbMMX{6g8_jI&}Ud1a-QG5@lz-e%%G!& z%+&#S1EY`z`1f0Z+y|2$w@S)`y%NyQ=M5Yk9ffJZ*Zn;OSy>g>1f3e$jWlMa>^sq} zuZBqL0#gGjEJ5BF3OlVlUUYuG3@8lhTb;TgMe+CsLICtQ+;$9$_;tAzD(tuI?fV`c zyUt3w4clQU^SedA<0NwP6uxIw_tM1^7A4baY~uLIT#X?EU{C&mD0kE93%Y z6G*)|!1|S@1!f&?he23@BP_RqH}2>`Q+{6uevlodotDi)Fg$Lhn+%=DzbE0H z^};Yerm8_%0un4h(>!K{;;zYtb@cRXnYF*Z#}U@6CNK@q)d!^4nE=g6*DuYOt*@*# z;p+T!|KT)*m?;Cs!;$5Li9?nJ>{dkb711W))0;A{gnP6CTE_3kDlPm<_^rk`i@_F4 zRRDNlVoznTtz-i_qnYHQV2-}P_4ZVZcjE!Z_z18YLE@y_y2@=heDUfl)7ydVI%k*7 zd9(Iz^+(n{PV09q&n(rPoo_-)%@3?YEkVjRK2>^VE+EW1$lFlyXo6y?=2wcLmc|3B zhSGg=9a#91?RHUH0}{Hqsmq=vF*d@2Zymgyd0Cz$`FeDxc-WVU()nPY$CUUh6f>a7 z0Mci0V7j5K?_Eoxn5iqB$FhGja3Hzw^rrk^XMw_QKE$zZVuSQ-6i^qJWt(Pt@JnL( zD!podd}-2SVUVxaiuLDA14^H+6h&RB!1f*(5%0`*&~#fDXjTC=~kay?#AZVSU zgeN}(Xe%%V=w1VQqyH{K2^7VzJcEg7j#E9F_9<&Czu$Q=Z8fC?v9p8vl;nM_-VL4( zfU&HsiWNYu*J`4cYq=J|Zh(G(7&fZnJJ$mx@b(}Ja6w&(DAFyEGpMXQlRqYYpU1o^ z&-E)IDee@$LX={Ify~@yn6Mg({@Z;X9zAPh?I+|_ti{i;s~-00A`=bOW#D0d$1H#-5%HIOn9+_=2y|yAXVIA<&am zR8>JIg_g3*o0#7*Or`IUIL_ryvx6GDJ0tfK>Lh_iCPmF*Xh^3RIFUVxRWf*AI*#TEA}s=d4=up4cvkas$UmitoHTOZl`8unm;H$2L8>RjsYQKm4|< zc3JFhRGnO(07&663e3?A1H9C zQ;x#@HosM0x|T98|CMwAfdMwd|Gmi*500-JoJ}VLeoXuA0m*;7*lKQeb_-P0wSj7+ z8K1f80RbCP-bH5f2!fwdf*8UnXG$XV9w3y1;AP<+r3d+<@k;<}9z0KQWQM_t61>|d z4M<`UZ9G=RC@?$%hu}|TJ3X$j;kO=9ZA9MnakD0;J*o#fh!d&C=MeNXJn|W=g`aLSyirG42KbX{i2^oy%)0HajJyTDIyx( z&z>mY_6jk~Wd<}h3Nlz>smHp7cKxGrdNZ(qL0rOGsBZlq6TxW*Ybj)&!2}pFYDlGRLI5^LH>E zF_G?Z-)m=szrJ{H^74;;Q@2jBRyya|^Whgnsr}Bsh)WT{Qqtz0$9(xb7K53Xr7GLc z&c;oLWyL=hKmCmCx#tl)ZcO)?{QY^T>@3^EjOAY3(22cakur6ekybSJ9>4ahsnVsH z$M1epd2I7CeH)MZHL%OZbS3d)sCu58N5GPEn_pqZy9ZJw)MQ)nk>cV$>`YI5ndrTg zyL)>jfYG_+?BH+{$}2y+xwaW_bisQoCiw|WoCV^|8z}_<+ zny3ETAOVgic=XGm9#p12)<3=pQ-`NA(TpM&PE!cFg9{iD>I*RO0<%WFP1zzk<{~+4 zZpceS&sYm>a+wG<;TH#Khzk4+zi^sHl;|RUfI+=%m`+LO>l-8YQ7GB-mx}m@yzgX7 zx@!#i;|A5WJH(I`F>|Ti8`_Y~yMM8V>gUiZCd|cFXX8u7|9PDfe@BjsxZ@)F_thY< z{}pCycqm)Y6u$@4HW0$c-f5Kx1=o>#Ky{l4gMvP-TsV{%vB3xePmWmxD}_g>%wmM4 zUrRyZI5dD^ia_&~WYdVKHXMzZ+xFRx z5vJ)*-b_OWp7H~Ex?y7SvdT~XD#kkDOXa*1AGOTiw5iaQEfT&^y?49tat~>?gzwX9 zT^I2GzP2?*j{K_%3b4UzS`_SS9*zSq^DC%k8-s5xI322&UFNuY{qBn_%{Z!fPBWF) zU!id&fc(V-XV-4y6E8{_1b9cf@WmY;%qOlzaISf9+8E#lPfmTZ68OcFb(Su@OPefV zHaHj^EX&e5JCLt+n~w;kG-UdA?A|Hv7_zc`OM>eueN_GGLmzxJchu)%Jcc6V&dB#G zd@b^1;}-BKyo`KW5t5|ZoS>NpT?>xG+&T5?Zq$KE4S@=S?PG{%-H1sUF zbfvuBlM2VWN17J>IzF244t*ETo6uCs6^`KB|MSEz<6!3J>rJ`u!xYg^fJ?cFF0NZZ zh=8!+p41Um-!R9^xL>0db;~c&X5%WRaa6vX+;pNt_&An5orj8yF^1M*xDF1rjm=IO zLxJd73`=JAdk+K7-dPv05p6JBd9&KerR7nLaq&d_ZO)&C7^f*2?=y;Aogo({)BXDq zf`1uHUc^7smQ0ULB|<2{9!~%@Jm^KA!wotW&3LD!+HOusSN9ocQX7G+U_7^#cKBk# zEgLH9y7gCvv62E1yFy^43?&Rii&7RMkq-t>teFz4CW8CElY6w?zcQC`_a*to$GWGl z($TIqeX_>KEJ#vztUaOA^^8Yj{G{e(gU9Cg7PR6=hTO~8G=n%RuU5ak`1kq4S1vu% zFoQyY+;sp<_fKkaY=d22x%p7RG?9crTcF=``S>~;S?IeJMy9rS#&rg&4>5Rp z4fdX0sfeX{+}D1A{ymnOB&RJq6J{J^A?2DPd0ECA@AZfBc~y=(k4x49^XfE&ItGo+ zojK-JWG-A|c#8YymWhiWveP{YK549Q@r>d-RI`F?NUjptp zcI!_(@@aw%QVu=fEk&4(AE1Zj>dGumkIfaeR4O)C+i5#aR^P^FAsDc*JgB6&XXRf& zM^+sl?I$Ihe9}d+=gkDcO`4~)jXYCND|5-qYCZ(}EhWw@zx{@pmS*#IX-Vg+(0HG4 z@pB{nl1l*w#olb3yxjg$B82*XpRF6>xs+jxeEn9B?J-W19z7C?eEW=^7W)}5Ecnrw z@u0lHqstIJ9I961_QyIGR`6WzRX-QZT+lfiMDutu*Yp$5Ior|twxV2pU$qp!>iSKI zJU&{qkJyFNx=9Ja7B>mLe)iRUIZE+S&HT;YMR@cRZ2LY9%++Y~r~KIMbp5q|UjQ{- z@ZnMaD&|eeEMbPFRZip}5^BSz`q0qW;=n)GJfyVzf==@|xG2Z_7tKtoWJ-m%!Q?yu zB3>+sPPwd>q}cS9z@|<9u}5AD~bQ zx3tQ3)C9QW63R*o&QjvKgfCsSHWjlIBR{kmx%;MrA^xVy_>gx*X)Ci8#c2_&A*26^ zYB*Po%y^iYnT16}M0lv41~W6?d(m`e#NVLVeoLqUQ=B-_WfG%z)+2%`{E57sxVYcz z`_^!M)dTSx|=JvPE$C`3 zmH#IZa8jS8WmOWLQu?3Mf&-)mI$h->hNra23QYGoNSp4A;ypnJ$9mwQGk@JlW0(2F z1}EO1laUL)J`P2X%xXxNwHJJ;Y}U#MEHTY_-Pbw969pi^Quqi zbj$PHwORSDOKN@`^ujK6mjCjO5B~dNj!3^n0sb-AKuG678U9WhF(a>1Yabb43vpAN z4j)|ce|t|vRP^M14wlhR1~vRiMpqNDH7)Y{NhcoQVfoU-_uuyFk->g-uJ~2S z5T5M$k9Iluy_8{sy>$5ASHz-~d9=e@ZVNzg6Qwn(;twFc85PXTwn&d3>Gk(0Hxq27 zr9;bX*crued>npQuH}d9GOYH0vc6TMaSe!Tw0hWjC!TPSUiltkcs22SdBuQ5kH!J3 zmSDe+>#q<x-;tN~R1FqM5hD6fR&#(Jj@FA5EcjWDnp`|_g8-#tCmakDL9kmnT z`nFqFwHmSsmyU>KOuy(kNNF%)CA-yo>XUO?`5ST#I_{;zFT@fb`q`PTB$JKvl{dce z4rRcwtJ!rytkLNL>5_UE(8#jfD6BH%1f43hw&jzJDT9>r#*HmgCP;C@Bja z+n2A-uv*`cLdypJtl=YETv3Y1mC~@6#|rmFo&a=Y-Qd%(iXee1V@Y{m@lG3gB(M*> zZVx;~i`EY&wPQ*yUNGf9JhyqG>QpbkwU2Y>iH?g7bSmWd_}j_USR`pN{$KCP{P@{& zTgwvH@;bYr#}oYVuFyR8ao5|LA-zw+6?9)qF|nXfZCPzD#hwwR?a%P9D0O9J@SUfH z*VBuA8g$Rne!c$_eLmU>BM0)-WpdnLQR%BOv@|p)RIVJoV~cnbzE29Dr7Xo`#G=mB zMsjeN;T;Q{Mp^QV)!;qiMS6*l(=ilPdi(6ilrahm8iKYipP_yP z2ZaI`bKahp{-R7)cLue?xI9~N(s|ACyJ_r0!EOZs7ks*c_wW|!x1}E5(I~oR z{kl!%)Q%c=#&N77gjgkMsuZ6qWz>jk{Qlw(H@|weKN%MPXZzojbsNGnI3#sIC*b77 zMTmW-al6Uqc=xhDT>hK(|Kmg5ZFK^l!Bi8!gZ*7&;9}1_(xOF2L^CYVL6u=TR)66_ioUT` z+R^zJ{>t!hOF@#SMJq+iF~p}8w*JzkM5UL!4Rm_D{ZZ@Qo3N*n@%+CGL_a6>RgHaV z%W!x!_l{SZ;bac3oFrVEfXA-7x9IUNp4AkhMxJEkgX|rEBR?1UR7xUFoX(rZ0!Bhe9dZe0 z+t;+GH)h7}u~Y>&#N7F)GwPpa%^bj@;Nx4Gh<9mmB|Stla7XxW2oDZ+rM`}XDf?gq z6Ah~_Gmm&^(PbgMcTYUDAT46@S`e7t5FdP%l&HZ*>6V!S`z(6nOr5liM!Skq;JaCqa1pcv1~h#NIh1^jfCr%F7X@O*@f z{`VJ#ul(hlTx&DH?Wd;KVsL{o&WT*0j*+Fo(mnZ@O`7D0R=4<}Vd3FBi@J|yqJzV4 z-?0dyo^V{@c#AJ_Wsx3-aSTFO(({0Q#s?6>C!G3 zihQf)b2{CTc~M3pCAjb@2v=kW=a|V@{pDzO2-~QKVSB1nMVv^nJ z3v6}lcqkt!hrS3k`S#53qKEN*o1RiGbeEA%9Cor59CBd~vBhs@q_ z-{`KPkLwd0OmWS&A$>g6f&10POYUv=?5TujUygj_k`Wj8gxX^kz(Tebh@8ud5r~IEl4JtS#EyU&EzcqeO3ibLf=s6;>1@hC&c4M;ukswBN(5F_mt_-s!=L$87f@V(=QSY ze4v?YJUXP;TT7I~U33ke?EDjMeca9FE_x<`r732X?U#iLTj1@h!r0t{f5kx0QzU#K z|EsPKQ`ethr@|STd%ig$X!5BesW{cYN|Zo9m`0NV!B+FOqOy-X@jpMiw^)wYXhmdxtNE2;nluC8(`xeSu+X3^qB7JhA?kbtl zD_*zTnxUhCBe=<}7MOh^5C^QZ>@`n`HsX$$(2LT}tYRKNrpSNhLy4^zXtB%vpELyw zs`&IJR_c#WymIBV(mUBZ+fS{WN2f*!&lr7z4Ev);+T2vBu}Bzu7;}f2Z^HY=14#;@ zsi&zd7nkirKB|uT3&h;{(HVGgd5(y=W6fMpE27YkMW6Kj-2a5nLy-%a^Rx7qLe8Kf zA|fu#$ie{RKXWVkuzTIPb;eehB~FYsQoNSpDRosQPAIv_>rux~59QgjE?oIOEE-XU z`3&RoBE9ktk{c<^d{#(?dli>t_;PHYGn^VlaFakF&Y;@U^x}P$!(V|X|F2RM&gdyj z-06-;x_CaPtAIXFk9q=Ff&e=oD<0yZreQ_28IYFIM;An(7{|tmtGtxs6g{(%_nkDP z_lV|V?k}2?>QG7<(m$mQ8-8hMWhe0Jd4g?q+xgr&8=G@cY8=-)1~b?c!+qT;1L@mN z*JvLnkR?m5bhGg^fhyHSfs+Z^mz$p+NBI^yOB_t3*9U_++pT5gXP1R0D?Gq&f(P7+ zMj8u(s_%n%Xgswhz%>;nf4- zl5mVWj1(?P1jXX=bH|b(b*j|@W3mkr(#p-w{yE0h9ST08Z8m4Oi2htA34*`1N#7$| zF2dT+9Yo@ORDb@b@)!Sw!6ukDQSjQIhTd_-krSXeg%%MW7{Gjv&c= z?NUPSTeVq@%hli4-pTZEripmTct;xNd4nYhG&;>T&Kiar*Y+d7eU|*RwMbL{q7?ff zc`;3a=k&clAj-dMycYZBFCYbm5{5;cksaV>p-`!h7fHdb;Sw;D-|lZVg@fabA#m$S z*zbw+bkWgbUmJS&KstWw;`N}kFH{#M*f#fYIYWf}Za>hy{}hg%h$1xPDJ5+~E9SRv zvSO|~GjYd}l^;5etYSV)a@Sn>+HUSLGpLI5V@vH6idvIAsAa$v%5pY~ER6D}W%ZOa z@EBn8KH<1j{NNAsyUMR}FE&l7p3Ro`y-UXlPeBHoLAble?bFRJXON?cJ`~Ow z7W4YfN~?!~d^+Wi0ogOtvzS3JsZ6zkK#hq0X~kJFSW41&s|&X ztA?fHpSc#Tg~D@+!l0hO^7R&Q z+ey#PJ_9fPeSKXVnwvLoQe>Zr>0S`Evtvg}X@DIwb8;}y%=aL){uoR<{E*2DgS``+ zoSeGOLII*a&=&uYmCLyhElnRB65=QRzRu$E;54=Led*K#Mb46@6AIt2l(Ih@Tw>d7 zBmk$wKpz)OeE#x3=L-wX{4~Qe0%qn}IXUR!VjSR$ zvR-17qbfad8%Kg{Zc2k?( zhMe_ycH=L=vDz_B{ruSyICKWiLfI;3VJm-)4_Ng7MBYTt(O)7T(s;%T2C6q)tF187 z%B$HGMFm!F;pahgTJEa;M7yH_V8cfw=DRD8JZ)_JDjlkcrZxzImjBYcc}A!vMx_Qk zJHKD6NoAZAsMp=BP0s)^Y_S*z0MmB91Ha?G-nko~jv|~p*bGtrJ_ijqH#gj_x4=UU z0sEtikagpE>}Y{K>z@V=(`-q-9_BpoEiiz=e5Gk$Ci{H^*Znf+gT$3V!p2{oagOWB z73#XL)KJY~=r)FmKT$pM{aC*l*u;!xgIWQH3PX+wdC-n4U(S~MmAhtCQ0_ipM4owx z%j z6#5)!bD!yrIshIb5i&9e_LZi^XEQV9V8pr8<`D3ct!n%?93p9X?H0PE5)J{E3(uG4 zuYB&d^|&ZD7QN6GcLD70PVuoRCj*|1+=JMFen+5(%OgLeUxgI5!5DsJ+!Pl8BC|72 z3#_O-Px(;8&5D?^*mUv*Nn$o8O{h$$k`vS}8IgpAuT$o3+AaN%htWkev3B{Z>Jv$F zp*%`fffEZGUv&+1P2Um|Ykys%e0ZTW;+}rk4#4jMFI2&t!~CBTXn^G&4kiL3!%7i5 zxJX0TWmS0~4nsrP+uwU`<`otBcQ5!V$u~g1PExDgo9Z;** zmTPFE$nj&_Y`6^RH;CHyi76RLe6%>Bbh1idQhUzaV)+Wnn*(4KXi`<7qP~_iuwlFX zs6-``D7#Jem$f2;8pm0a&<~DW)X<>ihKG0Ee%h7@Ak$fgD0BcP%UPM58{tq+>;F^p z`^BjRbNEslLSGioWpN2u&w-HPpcDWG;f2k{eU|H&&Uu0p_$ozzKhXW*=i4_X-gZU-a)5D83< z0B#8U8EZNEi%&~@qMyJm3%_@WnD$CkXteSn3YP7d2xNcJaCml-+D5neQctBz#X?P=~iOD zky6@JL56hl0e+9prIXg14pYvv64cf_7r#-V-tBuO!Cy8=o$3iLWv8nTcT#$IT6EW@ z_1PBz4HI!k6Mq%PxAl>o@%*%Bg{k_uTnxqX@pZb$%L~zGi&G|d&t=utobnnq2yOaY z8YoX|I95gv;3=9~F$4<73#WZZzlIvGv-WSA-VW-)nlfHk!!kMj`q}b&{eV4g0=|K< zq^_sFiT`Ff2VFdVTwnJyLrM4VS_$|)!E#HX!_Stx<1)<*N!9wj>o#i7-MDc>lT!-t z6e^Fc0c!R6!a5Vb5YUDyb6(e;UtB~(dS`9ex`?EJH*fqmv^RhYmKt%&`{PF~pm)Ar zacnVU`|;VU{1Ald(k=kYMa0tbI#6y5xsw{&p35>g@=*dj;5-Qro^-ZKe6PtzOYYM0 zH*du0>FHmaRAl7mcUs7^#L;na5upq@$vj%XDUry&h61`2jlv;|>wr)`dGf@ThXRIN z`o?f?R#x=7_Y&n9)2N4G=5;j&(iDVEDR=kVS?^0MPJ<^o4KHuaxC1kmZ*FD@{PRq2 zSW^)aT-wqL*=%2p!hrGhjU5V;`}c(}oQBWi=J3C> z{>nr8ZPNE0;$vem666D8V=qCneiWKNG(xiyc*|(gp{oC24A=eg(>KaWIlaD}_rLK5 z9fN-8@g*1d`XD`4>)~nOic3yT?xC+{R;it*R$$#va}zD6coQjQE`_|cuq=BZE-!z6 zb!~0NxlVxhEE^pQ5f5Fh{i})!g3!>(!VKNLUnY`lbl!&v_zfPE87FPOV*!ZvQ(O9h zy(QmcTnU)Y)zuQcl_ak}I&r=uVXn!PoKtITREwg{q}{9M z>chxLCJ5iHImnoZ6C=Ogj9?f`esK~X`B_|25~$0vyQdpPI*@&fG-JTjz0J%P|BVf! zdi>v63z$eg0TcLu1@=nq;(peqN!Mu~%rCIRv}-yAN{8@5#(_UzEx&Zxj&=K^arg|d z{U}j}u>Am&vE`uyH+z`?@Ytn7DFJ(I=ybD!@YLf|lonD_n7}_wA6&V;FXce2!i3$`bm>6A@vDtrxN))81$czVOteIHBHtGD6XDD}TKu_K--G3u zIc@)4a*p@D2?@6RHZbd!8hiUi%0ve5B)xYXzdV)hPXRSH%y?Og~+idbr zlz0Gl71bC9Q3B3YbR=;VJDuw-)|TuscBx8^D*Li%TfGy$GDUI-J-^5$KtHIM@qpY! zjG6|=W&*0m^O5PjIF4NOy7iw$VMP8~otT-eZUWb@d3t4xe)XC%Aw1f*EFVsNCyi!& z=I`7oBCYnBHtR5mS4KQ?8pXXj7&cu|zL3WbfFK$Y|=WkR*v;!c_KAXk_rW-DJ3zVVAO zyOL~zC?5XzO?!(dq|ZZM%ACkhvgvS}m5_+Y2mtnYHlve>Yh3>eXF`fN{fj;$5;SDD zPbXk^IvjUOl~%s!-P^nc4HG zyr!C@rk3aSZ6}hAwC4fyTAtsJCtFBOgcbuzK$-c_)!TAjtGZnTYk zqMV_&5D|Lf^UX_M6W^stb_bDRpA^grpE_G{V?vKwe)tl9ypKeA=)=HL&A08Zsf&II zbX>uaP+r}NC9&O~3PZnL+`4%xA}?yj&y5kP@~I_0sOPX7W3x^#7+?%%(E$;>LFvbR#%d(VrstW*+Ng{)++ z5ZQzxO146>viGJ!cE}1D8CluuIlmX(zwY1v|2&T)$8jI`ap1bX*Y|sV&hdJ`Pa4X} z*<90nh7+gHzo>AgQdyrEiTlKM zP7g}AR4fA+?G}TBnEWm6kE?~F-;sdU+0~`4rsfF;ZZ;pBGdJ%z zg@toS$~|qL2W6cO_o;6K17x(cMCqC?n-a%Y-`wr{UK~ZR6o}}fqNB_ z)H}`-C$cS#^QckQ&@trHE$ud+1Mic@U}}N#!c5(=lh94_);y=^;vx46s=J?c0Gg?H~AS1z_zJWAk6k?aRjh#enAxl=LQC}aTYzG=RI<#^^*A(ywqPq~le zO6a$uNeqT6Yp#IqhQ-A_&AeTNG!lUJyfY4)PdC8E!UyEW zgkoZ1HRt2}w=$m`-6u(%AQsP%S^mcD@TxuE{%C&CxD+A%B8Gep9i@X64LI;BD4a367kh4~~6CZR_h*6NTHGwGrWPFJl z>0vKk_=2XxJz5!k2S?892lYZi?mYO&`c*XQaIu>XZ*rw@_MzlhLe+ebSN;6Txtc*b z`pL;@6lygSCJ@MsmDS-jA6V5qYzS31&adq=_LG)#Zm@-it|O8x)awmg+ILFs&3Q}9mie>X{`&gRx?-P)x?naVahF3-w@%F}O&Dpxe?-2&pWr}p- zCUA1O!0Rhc>N&RTUO*qDl$yk==jSCUrP1#Oqj*ZP{~H~oT)V_1uG?GW0?0G=uQSg- z<+yFyycV;?106Hzh5Kk`_Hg9{jdZ5)ClePS$-HktqcNH7&7`_WJthJpps-$lB zZzZYy0U8M7axy8Ft3Xp4E$Pe;k19gKVLBISX^X)Ubfo2rwL}Le-@A+~!kh5H!R|{) zJa9$nob+4HcPWB)U;~SYZ1u7m*ToKW*x7{kd#-yFcLSB9 z(B5?a>1-NO$=rfvm`#t?hy0Go?6l`W@FRiRO4RWe9TaRR6qrjYK;IVj)71TM-~|ka z{vvZ|uM#qL%*(H=O-#Snof0^GnSlryT7{oM!|eS5oYzU*F_(z7wi=m5hoU@OPd_Kn zTCZM>7SiyB1`K7a6$Z};{wgiA=O3X3ryrysb+6U6>(7^@u#qXs{8!kl{bp_50r2xu zEfEjm?k7ExLJg-e3}qfck?LE)Ts$?8=p*WYb)+-CxiDNf8zVZuE3NEl8co&F%IdGNJAG+F#Us`s14; z#>A?d@37=TVF=AcP;vX}V}A}hxFi1VR0b&5)hMp6u8O++=772ij#WN~Ijt+vyv!OC z?KcrX1J0N5$q!#^^R4&?>FuSBayMnrV-YgQq&FK5Q~z?IqJgEgaBY~Td^T_J($S@> zl;NUXzuJPfnVVSY9JMi8?^k-yBMj^U*_m0cM_FeTGJgv)wzPGuO)mxb*FMf>5BLji zit`tyQ?oOKLDk}^lZx0E#`&VZwxM+9rHy7jRb3dIzQC$>LLHDEGWB(|I=Z4i@N+31 zahtNDw#MLzOn&P`U^Jl0%dPjMH=*em>?ktVyo96wIp;3t);lbNoiMaAo6fGMKZ|!Z z``K5;5}DJYu6?!=#`SE<5fA^3*csGeZ6fnB=*6g0G7}t$N_^x0A@;WShSCor za<;Zz%6ISC$03AI1oHCu#T=wK}7Yk>G274qcx=5K`$Q~JjhRzYpiocAOJgB%oCri4zPbwfhOo}z-1HUMMig!Fgs zvjV2AZd3?kN4|6zJ1&&&)E+=$a_=Mj@sdqH!n11n4=pSCLHQJ%OrxyIKVSsI^VbN5 zFWPa$=SK;n!tvrAJ~%?Lj-C^%6tW^fzTrN)hyY=j&gFlAFgzj^A+5#EtUUk7%X}sg zZ)cZ@HeG@{Ka7SWi3EJ5$ru7j(ZR&3&c@s7Je_^&A zCyt|$qXff%Po(GpR=dw|Jl(@boEZeSN*`xd|b&vs-qWyF`<*BWv`> zQs(KY`y77}fNC(`I|`^t(zk>2`xVPf0KG zEh9JS?k$fm@L~RSI{6FHL8k+m(LsLLKD!#u@puQ=m5%S74r3nrVrzQR1GptLuh_Sl zRZGudYLpIH4U=Eh-@5QD&hhD+D6+nipnLS{0$>dGTKq6M;ArU@FJ%r0Q!d^D0!A^e z+01vM59S+3$D-Ns*l-RHX#*T{;by{S) z5(jD7IjKYkUi5#UMdoBG{% z^z24FyKHg+1%jw>@ab<;QxIFOF|^&w|F*QAJcWES6I4H84!|%opA?=mJzth$?~oN% zg9ySw^-pL2j75B%*H&zMmqp<%4PI z@*N#+Im*YZ1zb)B=3;O6mjp~b3Xc|5Ji>WEC+WAsMb9jG1R|(x*k|Tm(v_Vv$`j$- zmZFQKz#OltYIT>Wg?dQK_duZO&}Skz0%)^=yfL}^oiIOy5sRczv-^h3a=Huq z4p7)*syfwv7!>v`yVDJsVgo1s2>yd%4j!}f=i|iA)0xUq7)XrL0h0f|Di0ZyKFBqp zcG0SS1eKPNLFB9pWX{#M3_cOg@d*#RB&+8aY4YNnu=wps4KEBKI4n$qa@3nX zJ{%}eu!e7@K$gH+F0I=KqyB6wrPREs^SrU|i@x8jz^&@P^;p!061)nl%w*dQo}A_e z*#ZPK9a8(6#Ph6EhwJ+ifYtM*F>SBnon%i`paKAj>ADoSk>m3WSXKJ z`?#KV7~LG_>ei^eCPi@HO*rDd0DOuh=tGct7$#oPc0!FQ8B6giHtnO<29Pey24My; zfsM#bR#27$Lpt*yS`ovSEOmfp)>|3SN7uV`}S;z(3xupnRil504wwczRKd_IuAA;iez^7f{tmbxGzhdw zj^~AP1ZqL3gEc?AcGGGgi;VRKn_I9zqP`8S1lt~CQ09OSyjK)z;=kc|D=C%Zb?VTnD&l@ zHEA}zD1JJ+I^W<^Tr-bOOgKTn6A*?e62fROAg{;st)<7>pvud2g1ct!=FeFCsQ*yd zwVl@Ra3Rr{^G-R{{;J--4{$~D+zVSblmR_Pnl10|RM7YxW5h!tZ_(#Uqq#9Tnc^#^ zYapAU5zH!M$SORS&F5!utYw=)zVmlcaSJazvx)`G|Dx9R-knD3binYCoG#aI1)&-= zg$>{~aQ~2qlfHBbFb+t8n!I$l@|Qk`G2p}R;BhpO_;%UB+3L*IDjAyw42t5T-naKo z4?0?~lY?Spdw6{j_T4xadVrVU#*gQ!C=|3It2SF7SPxhh`DAdiu#^&~U-J90IoqKn zcp@pe0iw$iDQ0lF-gS^$bW1>V{>dsBEiLb@hs9f9p9J>;B9ht-K6*N%0%qv>_G7WE z1x{1STsTwdntV3rm`; z#bbd5ZJO)PTY?#b0l1Bhazd1Jk&P3i0iH#^>xI1R?>k<_^D8FI*QS_^Hyi=AgbS!X za(_Is_<_br0C;hWZr69L7$f@2R>1z!??3Ju%3D2#CKJ^(YD}aNh#S!G{Xr#m@&_c5 z*+>#e9q{fr<59SR&(PFCeLJ`Q4EM3+C>!Fk7%qCFq4xyqgHR}dK*9DP*jjP-R5lhG z`>JdIEOh+B{?+kYH9w3n;k}&(O^xKNU*m=KK?3xpsBcTMSLo+ay-fFnCX)WMY9Aph z=!k@7+21`s;P)7j<6WI{)J~lF`6s6kR~laJP)U;6sQuYIT{W{rT^E86PeuWE**cHO zcUnG9vjnoJ^xQ_mRm`Q3KD{2|vgV=GlCcvSEv+36$N-#Ar|v-w`6}*zg)N|^!KDd3dq+nt=(MLYOd6-nIC{us(i@ z<^>%>fyDp?*6>y(DF{W7MS;rWfl$B!XJmv77GP)TWD-H1fDpb zW7@&uK&FTV3a4Wp1|70frs9tgLQ=~?7aXA> zZ}8^cnWBSQ`%|5v?ICjaj3a#7v%qY%;;GVfBP!DWFH>Wk4v8G%_|-J8EIx8ZbS70)CQ5 zVKWWZR7O@-NQLV<{Ji~)W;sj?KYsaA`Rv0k(y#!s7C0}MTgsh_R4S!Q3NsVi zV9k%;^KNsvc!eha@-aD@s1uLhaePDCCdhpwZB^vYTJU#h%m{tZ|J>+@7L?O4(!$*o zPsz9r6*b2)a_{Ke5a4W*UK&)Ps-o*GPVw(isQ*WEquyb?xH%O+j@-~-qCR_TB0)xo z4h9UA;01OZ2MaXnjUWpOfBqah@{-Tkm|^+aH*-k9@lh?W#VBqUS^4O2FF0^N|McX3 z*W1MMaylSy;8D=ZHzkA242%>PVTnuiyaPh1A=EBBrR|}9AV}ywl{DZpY1!QF>|O!I zyfY^PyrSa}ArX9Sov|&Wr@c&q=m0V&lypqz=T>yaJA06zTbDma$#FOFwovHdF@zTi z6(3cIQaPMNPP3Us$l$}N5Jtg+a1S|wXLZ=~=M({*E|#0iNEYV=9^8CjA|3w_MneNu zWh7t^f{iK%r*0=0F_gy6f(cGN?SpbGloJT{t)ZNA3fV`Wn@E zAqt-J=L7S;aKFkY68yZ!>!0K^U?4ZX_0w87ev$eb>8&TwIF}Fm$f8EAco^iBOCz8i zvMhi8>q$iM>$%%w+^73Xx-~KZWWG;N`fQ4W5G6d8oE9_}wf`Oc3PvIS(+8(V94z#-y%->*pFt|)JyTPXkz4493x?@X_3azDEK`$Vz@gB>)Vex3; z795@VJ4W;D9-g3Y-pF7$;P}wk3Lxm1071uQ&mn$x(8P(qE}T3xIRfIh8ZL@E4V}w>)XGMJ6ouTAh3OIJ;8f1 zpSd4Yl#`A^j4kwttwU7PpWHp$XX5#hbj?5*Kp7%WXr-H&=DF*l48reTOSzr|lP8oX z%&0ZMgirxYpH#!e)o#OUcv2<4;#!o|TB1)4#)+mYS z*u+2Y%@pX`X?GwKLL|z@FeJ`!&>Wu58aa2_o5sR_)-8SfJ!)M#xbgnO(OKYnK}vUK zM!PDPA<{#o$UpW(NZ+jv|9wux0Rj%kRp=EN$i07cq}LH;aKn5|n_dtns>jPk7|ZC zG~{RC7TX)GdCmv^LDcH{xqCG>Xyu6R)LF`vwKXjTdr}^eg$AQ}t6@`VzoAyz)~TE- z$toTObJ4hwq=Cm@=|yV#b6QiC?l0Rb>*SDlaXzJ9iZpe1zkuL8zxRWSDfKSs>}e%$ zZqkQLg;Cc87w5k<75D3iAOj*=IO0`K$>5WDXs&nva;=IBBdAV!kLGOYFf_bP@EJi7 zk?ki=;NAk$qK=LZti1j?p|_gn61#pf1sWEuyahVxTx6|boIEDoH zpF2j7C4%Eevp-FUQamsGA2>Jt8Vn!zn61)WR#uiZG-QD&9jug$d_pkB?=AXp_4ISq z<8X>`L|y{nO^so$QwUi6|HJv2_yi$qmyTCCkq!(DJc?@us6adOq*YPbfNgYmIF{UT zpbFwLMJBEjU3BA3M0a?32(SQN}%koAr zBmfQ)Ww$%vwi31Q1~|Xg?N@oH+7iL4GW{Y;I1>=&vg=c7$sJ6mPve2P4&o(egbeOY z1>p`JVwi34i23!!z{Z9jwDtOV{ZN(62{|lnlGu5Wf_Wg*^H1%aonFud2J&wz2Ls>% z;us}e1#h=atb2A9=-VObs`2sh@Q8@+`IYTX+rGZO>6N5QpdWmrVed-1YmDAoV7gyM z?Nu;n?s0Qvig&&kdrZhfF;J;F7$q>qf*p-lmn{N#Ig8L87F`L zct+T(=OKm4vbKJsYXNs42m#=icPW#%>RNO-k>cMz^Ii7WNr!^#N%y+!{9}iCI#IHb z`#9v;`>hGh1P(-wt^Muoo^bPL`$_;)TaGP-q3Ay4Dy^(Y(6kwNv=O9s1;G07wwMi5 zXLkWsw@~{8V>IM!G0n7a4*AocxLU0L^Y_cVR6xOiTf?w?{DMbq(%Hr!teDilX`;E> zwqR|HXevJ4^|~?8Q$84lAbD$1!P7s>-RMW90MpB6t#p2$=;B^fROHIPJhp9Vj9!3; z9r#U=2ZC`5l}`aJ_Lu@2n54=|2DriqH~C~e*Tx5XCgA^SK{2BLt-{r@sHT%v!I!uO zI$1nrBd|M&4=yy2vGBCHL0g4`lattqF+|B5p0OVj6NxD)Y~L%9&KH=Lgdq#Ct~e(2QhgG!T*E5suA*VC!2o#Yb<>7gtNTE*oFe&Q< zbR`kn7i`4#<>xZ~NEl>+U?BuLaL59AIoX9j_H^pk{5yN{8n&^4Eh8)v60|5@B#p(` zchtZF#g>G&{#bw$3_uSufukO)H>Pm-i?Y>>U!sX@LoQ6NZ!7E)6QQm`xm+82R{ZYBYbcvAX zjwY*r<;ECMOS}vt#B1bgf&-T8AY9Gn7hH9aD-ohLU`O+=FddSE-dSg6nRzgly~!hb zyIDWOsR`_xOchsND7FteQE5bSW19M8>JKJKk ze7M1@q9frin~2S$@6yt$L854l@Q1%>xgcZpflWrPuSk$we7zKuQQ%kMz7jKnLP7TD z35IdWS-)n#OmA(u48kfvQI9=I)OXm~W8WS_!ch!m4>0>4x5(@j!p?>9PZ=pwC~XFd z1>@@vyE4|cQ(Pben=A~^hTYH(?3n(R_4`Nq{IBA8s-G^XHiVjlR15u_xzjps9e_C0 zsAfupn7fw|y==3r!Dggus;W#=uq~59_goVMH0kdqp?cBD#DO9E*rvVT*zS7d0{D!mBC$Xjf2ZL6cqh5+88Y-3A>VojFG&pUviUePl3Z&tAdcz ziW&*q5#D>qbQH;WjpU74*vPZodD{0spFDX&aI@2vo}NB#KRY91 zMLRO#%=+eAsP#y}#k8KsWAiedgah$~P=?iDUDx@7js7-wUugbpehz$_1J#|Wxw(Rc zg+pGR-}04$NA~R(xw$k~5RUuM90phtymYe@4AK0=$F5N0 zK_fZQwiRi#A^P!5OYrLKU4uXkMl{0_!VXfG#*T+_$E)#98jU93WK)ZefZ{q>=< z6@JEq2`sFjmCO?G&-g&T(^~E3O+RRjxLDo1al@r>VWlq7 zeP-wsm}zBxy)y(v9oP4b5BHjLEc*Eo6S1i;vDhe>k2AA+Ke*v<`d$5PD;hi*IzFsR z$LE3>lsrv5$-Qqa08${e&nOFqXY)GSf7a>YlBwV=3Bcw(S5v{m4DmB_;(p%qbX{5| zbX|I3OQUXsIp9!Zd$#TwbJSY=^%DVU9>?zzB5*i2BJ}d-n8V@2IrZ^Q0bC}Joh9iJ z8A$A4yM=#f=rP0V-PfQM_wn=RBPgi*m_XoKdtz1Z-;OKC6)V0Pwbi_-?TvcN{lcG!t#O>ia%cBli4`$i~_pC zcgM;LgVu}%EpOq>cY23$TsxR2kSPW-5fnQpvt-df^N;8LsCXL`ahH&;l4s_<)2{`# zt1L!E3LM0jmOi<-xqV#E;qWPAn<>!%ZY1tq z6A+xz85Ulx;J6`)IBo=Y+F|^RI4sxoUL{Qbci*Jb8exTzJP=l4LrL>6jqzy~IBfWH zbm|DR()8*cyLmej9JGE&AzVCg8HlG76wa#%IuaFw43D9i7D1i)D9$|P^jFZLxu)PP zU2;Eu5j|wFlgi?_V z$}I4ISG;_gNGI!8)h%mi>>2^rYmfzU_oM)RBWd!~J!-D)%2|Q0AEu-~j`_+ZPAy=D zq%+hdnqDPh+Ay#=f||K~7(emmM7#VaNiT#>iH{i8(fWNE4N;h4iX@2U7yM+q>9eFj z&K$mYTLW{+(SnOU1*6}SL#1nh%?$|*3~c^Y27Aj8fhw7yEu&Z78{)6ms#Y1S9g~~~ z_)T9hcyTgIuoNJD7xn!Yf3dhFz~c4>7o>uZjHp8;?k|R{qd#qeHr~IZj)$n%AM&QX z;VkeXeuz4D*{;3eyn-ten(`r`uJDKWezKqZNSN@i<+cD745%i5Rc>3MkTSK~Ob8)* zpuz+)6*7mK2^(g1c3i~N&!3DH+^b*$R|4)HzFjtWu~X7Z-+uiPOu9eIf|*5!Q(+{$ z{-&~FmvFAMs?>DPQSPii>oEP`VE8Bi89?S%3_kHK1nWZxT#|QUJGfNnQHmFi#SoW}#r0Sy*h+f*%4rIy^N*sck@FG}Gr%+wY+}V>HkAuk zacBC13?V`ip9x>|W=lHHP5?Nb+bRB5oOr&Qmyf=393<=*TA6row)C(IM6RfE={32d z>c?7F$IvDpJ=NBEAZIZ$;l7ahppJSQhLgV{ed7!&f*VQF~-umHut?9t&@*Juf8g*e&QTQb~ zPeB-*)-$6Pr8Jb5nW+ew87cw%1)vo~mId5aP{!_&E3>C-hTMluI8U!Lv#IP7;XLmB z%#P&4?PjxfhDb_z(77t$DwJ-sx7U^j>j-D@D~#bs-dv%nzjTO-$)D$p(!@0PVSrB$ z{REVx$8j6zOYMT7;vqQxjKk!w23pBW^A9{E=qBKflVJ|Idg1fVs;Q0#HrgbnSL;H* zd04tFc=|lYxI;jY4sv=!Tolq=Z8^>l)W{`bOD)%T3^3qC?!;IXaB$rEFzm%M%e688 zg|Pnf8yLSS8pI(Pd2n~5&msrrHUyJMq}2*dEEIU;xfY&{yo8dy9kb3DY-4MSg@P(! zlp};A1zISuU?A+-vm>BL2AT>F$N94mxCvr`Gbw@pFyjyHr;@n$YdPwPZ!^3cOY8kJ z;M>BNJI*UEgq3`aVzGOW&Q4UP47#^yc!;+J5EM%MtS@h%Z+1X0tb$Sh=ob)Oc=8Q3I*btJT6ds zqL31-AiKv5_xpgqY&RoN+F})ghvU1_JSDf09&~`5API z@C^OI{8Bk-@2nDcLnq&TE%DPND7AjD&b@}j+j@w%Ip1`nUXGfZT$$fUPABx(c~3}~ zjw5g(#ZK3qSuZq0V;p~Xq8>9Dnm3MKubeNTkCBNX!KYOJhq|PIfp2-aBx<-77nWSo zqrQKy@h-L=Jp%Uu%sg|ATWL^wB4;5Y*`L{acVX0wOTqOMV+Fnrz3I17oNu(DvNTcD z2T!_xCBF`ZA7d-sWBA7MYYrJY5dx+ah=(NN#5V3c$1PI$A_g%iKGS=W_58)29=EX6 zCJcJAkqIaR@%1VeiyQe~Fl1>i+x4QMowFZ5K=OdJA|rD~+}fft>dL{b z?YsPCur|WX2kA|&@D99|ipyxUKx~ah3$QUk`$gPr~6m0_X`%q!U{YfflbacRFHzQ{0 zXSxf5OFHQi4L;hbS7OYTt-0BXPh?{cA>RA8MZ}*UI53KpG%y!koPuRc$oNuSTRRZe zy|`@;j384#)?1wkO~BqhEE}4hn|q>>{sheu00ijOmc zI(lXd@R|z{kn@zxj%N^TH7TR9eg6$tJ;FJE@RWvz3DWH>M^%-NIYW;83H&};W`yL9 zhl#GXS>O6nd#7s1yk*Fp;p)H(*)r2(IJYb?Mm_L&$5NG0iafno7h+WU%A)Pnd!$w) zVaJ=xwD9Wr1>?ATO6NZZM{exKUE;V$-a?Zoci6I-9cLzx2kVNok%x|j$rX2_rW`td zZ?oPc#$-cOU?R=L!*gt8^NVAaQyfUn@DpiRSZIQA0_cE3^18nZ1{Ige8()VswU^JT z0GChY#T0;%TS3LeCr|4K?rQoIEo3W$d0a)Ov=1}J@X!RPqSON^Yy7mH#2mM$M9xHXbhb4-0*=Duh z5UWIiv5n0ezgMx7yPaU7h0xD{dz}2{bWhD3$tfVKn65db^2snZdK&2wy@hOn2~R&C z(}zalf+v&0vKNWky_RDh>NuWo>rxWHLCEr{`)fcF@J80)?FXUt);uuQ$2~8;yoem7 z9i~zs`!0)%pcg^4K~%#qqWM+IR!~RfiTcrC>4R z$8`PYVa2Nc`m=_ zT47?ajuf?@iRhJvUa}mFxg6&D9)leOoo>_puslFkYD*q zn|OBcsNC102U^HOM@DkeERt@d#DSpFcK$eUI@eZDV(3kB*0q}=b-!%DgNA2Ddr49E zynDqsF~YVrcOb$As6t>JLB-mTmSOe0heY7Xm@bnz{^S#?ZrZ_mR@`;?>sMsuD)$0I zpC2TI+&rAUTrdVf_>S)mWlMF8d&f_lIN=0Kiyo~#|8zH6%2gP-ZRYyOkSxITI9bZ2 zl$Kqb&L`p0Mx}Vd=2YG zXz;jGTYuHQ0)Mr=3upLt8Z1BV_c%zdeTo80*Xmb1vk%8<{You`i#5TU_{{^l+PCC& zk#r~3v&CM08Q(EqcipoUj19E|uTA(eAbW9w6tS*@?h(>eMQlb=G}1?AXJ7)4g;I%^ z4gnhDERtJyFtMoL5Bs2x4avPizKCl`|GT}TLE@)omf9|WO*`@&?s45Eoo;dhrAiF9uIfQPEIl7*6z3$z`H6{Vq^>cj7_{0eg3v?7V>9vAh zOU&=7Vd6Yb_geZ94T={wH*rut9+`fV>R7>SX=X+UXn5l3sAfKZ06tDEgM1Gi1qptb z};jBR@lITu8^(Mwqk} zT&1GWZr|U0P)t)JQfbTD7(zKuRUykxvg#GCtB|TR9mq(?(6Ft0#1Bg8@0365w-P|zpm z$va~`*T;v_)6;&OCSwcMEHSOH$ipy-PMtE4-kuR5uj8CLT&pcF93bI1FI_b62GX+q z2{)z*%~t{&>bgEGE#_Mwy5nrCMkJnd3ylSp-tdnq@%S(hOe^7d1m)hn=Samy@Iz$1ZCV(PEW^%#I7v#~D^oWM=Ab~-Yz929z1|$$B&kwifi;_!9 z00`_#RW!8*1G!n^A3Yw@k zcCJH3)UzgPVhB;hc-X&Pq$mlwN0ljCb?EV;zh3nkaQR}wY5b!?`Ssq(?Aa4X{ybV} z-4V&={Z&%v;Z=HDiJX>D)xS7pb;bI%eCYtr=rbZd0@M$Uh2BNDUSAewn1ZIx8KVVr zmi}{8-LAs|OlcN@W`U<%aM(fI9uZ5*ot+))NJ>i3$nxHCofm>PU9}Bnhu|7=3fUG5 zh`{czD6lU8!oOMiEtCSS#9p&Ln+G{Z2Rx;|K^d}8!)7r6bV>K95WmW3| zkn+$8pnGCM_XOlhW6i%(9g4;pzr;ox$vkm0VJF9>WgD5Meqrv*JS8$Ay4=3jxrd`d6j+ZrR13=3*hQYn7^{E5W+$uF@3JXKPqfWSe6 z6i7-#urtTpL^d{{8Aq0xRP9Xg!1+dr(x2&0?<=uQ9a${xv*vv;EV%*IpxtnG^UZNEgoqd>!(Y!mrY}`NK{|fR-|Ez}w?iSp_#?mjtF}aNbK-`v zkE^n+zdpuj*}Y3{f!DGtJ?v++sQoqWcR zsO+{?2`;pRHbVC|j>9#i3ijQ)ydU^=cVvY=j3Zp5nBvlI1UQf&=arzpB}n3a()xY3)7vxRe2K0u#m~AR zS2>*5YH9AhS?%giFGlk2ea53-*R~X-bmooY=R5n@(tLIOo-B#TNv&FaG~CVBzUWO0 zU26C;&3X1@Tn?1$YBz4+C3jFgg%=KcgYc1CtjrReQlZ-gRxsId*GUj>L%%%9Kwy|~ zGkOT4n%84G(UcWq%auWW8F7pBnEq#owf4K(J6*Df%o$^||GU7;O$u=kA;12?bDRC$ zUFlXl6q9-b>%BEc_yf~v;$JQEfa3ht3fKSfmLsFWW~c_lhzrS9t93aq9-Un5e1%4b zH~#B-L!?5Xf*RIe^y@Z@funj}P`eEdmq@I00)n zJ2=L=kUP^Mb`fmCbtWzD1`^t9ut2e6JWs&J%1J5(6%oj#0|(+61xKv;8iT z4kfD+4K9}vVO_!B_i`D_3}e5C(vy11bdAYd|Lk^1&62`5se88ofSxSl?+~MHJ!Jx^>9sWo(L!7*FEeC`-B0t~h)woT& z5%LR892coGWF4~XA+5518ndZA=I@htgka0YUyWIR`HL*i<)lVWr=1zZLFI__B;8vW zur3gi?`$P}!R0z~1XVmwKb#ew(j^MXSmxDr*uB&0IzL zFbG9?A_gwVbMLCF`k-|0{JC?817ZnM-GO~!AfR!6ZF_`1M^N9bMcpb_&;Ri>bju20 zB{=fKrewrv#to4o%P;?)dzy8{)M9Bo!2#03$s9mz-u`hzNd# z7-}gtDx0-7iVRLI7zZm~xq^nFcKjsCn%H}1gLC5Ms#`7NtI_!qx!R9e_hbpG`bAaMV=nZdVDag0mn zkrnLeHvomHe#DXmKSW5MzT1f#@KU+0RrS3_I6#WAvuDrxhlC)Du-mGf{iB0Ab1wj_gRBG@8=_27gJCJ6^PQZ@SR+qd%EQFVs7)n==E zlQytH2wEtx#T7htDjK1Xni4bPf9d9>mD(kju9*aQA+kw3tGHN{?aUcRS5jQLYD^a% zK09e<_a(YJZgti$OTf*%K~yv_G%wcj@uMdb0i^cRbH6M1?rLa|kByI)N%_IO2d;yt z(%AJeF$+seMY!<2(b}25@DJ#Ja3!RH$5k0zYuZ;IthDM?o@z6=eVZ1}x$;KtIAq!J zwdZISIVGju<@KRh1;EOpqp3jikq;ZHLmEI1pWIPBVPo(5{?xu@sf6FBPoKaSdPVT1 z&dk^f?ereq+c$6IPCrk4^QK|S<}Cbf$l&3Vt!U(aPvx#aPV1(Gz)CArP z=>t>ifNlcDI;9v1-jA2w%&gIoP6vmn;@EhQ-tTX#TAF6zj32^Yc@oOR=Ag@;no13{ z2wqUbn2<1)01F>qIN-ae_BH_)oNTz|+~~3Fq^fu-YfKP3J>z;sa4dAA?|1_~lU>%w zmx8GrX;a8g46ZgDpT7~miITPZW{@FclA8p0-aggOQu`9Bo6(ZhAE8uA-ML{25)@RZy|vH5{FNqcB&Ho zZp9~p5T$Ve74OShH$?qU{!eBSAQ@jTuOo<}rm@iw@;Mm)ZJm&kM(s3t?BKgYYx@Wa zrm8tkOJjG2s?J1d7VmA%Vp;om>)Yk(N`4JGe;Ex9hxy=e*nRY))#!Aae_`GEj$3>0 z+A6)yoe1#RW(sKy{%lK?NzELtEV**0<X)+Lq{#u1<$-(nxuj4Tpo>-34>{# zr&}$v`2*j5QwChNZQgh6>@W~ekMdrx*;rdg*-444uJ50)u`Fx@U&YF&8Dt!@MG9A;r z2(HhjN6D$5P3;hcC|(;Cj9;d)eWjY@JXM733B?K6Z=S*=BOTvag08dP`?Vg%Uo=a* zNZ-@cvD`0_bMk>gC&~K8+=4?{$1PiOD_4p44FmdI!@j=j4Bk31A$>dj%C8+n#%vxC ztRJqT+oaMY!3S`E(Ewgl0+@YvS>))~cqK?Tme@{7?!!dTTU>;UOg9c4=ZWzLaFiM> z!~@^0O%hY7-&DvFh{I04dVUbK1DBz%?yO_^?r+lK`Qcu=Q6Q4(@b?-&VmX|DWT4|ky(rUZ^)Iwy`NsfK_B>=8gXKz zod08S;%1f@2eT=#*8{s=ul8NPBk1n^g4i8Bm;lWq6Cj1WyNo|R8L_He|4R?m2V41E zuW@OwRfZJud`({2iLxG$kTfE{M`yF&O%PDOy{$NJax8f*bVPpcW4fAZ3HH+X3t5)& z>o)@MN^1~jj0(Vm2^m1IRf9O*kJTSV$(os+QwpK6@85RY81;igY2};nA2rEwM#j+Y zZcS4`8eqyJA|nCbz(T(t$lnZXA}f5sk#fLk zF1HEPM`7pBiZQ{D!P>w-LzD3$e1AN_j(ORx$s>KUjvK+B1jiF~^YOhng^xrkiu~zZ zABDd>o`duNl9_{)3kwBp0-#J$$sGiMae&P( z__Zf=UmhKYn9$Mj7}!UoY07*W@fKR)Lsk!)ajnqU3Nt9IWJ!cet{V|}E#P||*d_h( zqIfVQM2pfrPeVX{7G0DPqfVw0MD}8QR$r`=^wbTHQ-R&;%F#~ee>Z!a{N{yEWs*VG zsOtXn(Ers!G~wgn3ai6A17K@!>C{VaYN5R2bK6)Na_K=Sw}k*yhz%&RbKB0reHTAEIGDI?KPocP06IU#qrS8`jtj$>fefV} z;jSRt@ZxFhwZRF2uP)!olqq}_BKc&H-J{4C7GM83+4G?S!_)yQh1r^8?JmEK`o1vu z=4C=Wy0J0XG@qZm+U|E;*FkW>g`WKS5lw|`#o7W9mWNvvVGXHIwt15R<)cF8OdQaq znDvB7IYhVXY5;BxXku_BMj`qRm`%_1jqb9z0nd!+HP;qKj(OLhD(*05E&IzuEh7(J z+=w=ql7%p@FWj;A-q{NSOL|Vn{8gfXSek$49mYO!A*Imt(0&9XwB#3MBRuiUc+f9} zdL0Wj7c!O5PQ2RRX7iiEpSx_TaKKp3wVxqBYX0%4-u}^Bmrfe4yj75zP^s4yIz}GA zX3->zuKbVl4rlfbR8M;=GW!&$MJPIr0D;#kw0PO(4tif`H2|Y4-AaJoCG#*KBe7Z< zcgO1?7`aZ0zHpwVh_cpFKr!Ln^uJ!5U@08Jo@)ZzSOh~)1CnT;Hk#$nxtMu7JiadeNH^|+< zm%^{}#&@L(@dB>>@|0vJ^7_8bmn_IljWpQ`i{hn->n^m_TD>Q}(2w>e|0h0ugogU5 zGH)n_O=7AVy#eG$$?E9nOcOzioDe(Ul6M3yEwbJe_9N2dUEig!oY7$m_K-f%YyKa; z-U6zs?2Q|~bjPK;ML?uQx)D)QLPSzfk(TZf1nE#gL2^_;Kv3y!5D-x577zppN$Kx7 zO#Elw_g&vz&RWjE+eq4CP7Fg{XMv9u8E{`vKJE-M|O)o282ddzh(GMz%y67RX4`9`##*mV3Vq88`Y{o^c_B9dEbV+1-GX_i0iKMGjY+sLjz76+%%KPEywmW2Th=SuX$*= zN%q~i9{s86mYBny>ChSahuSJlzf%*$<~=U!|H}I72;6Vj{btJ!ETRZJRzGrBun3<7 z(vjM>3CD|r1vef5`5X;yqdQ|xYG5A->OO?Le{wm^ltLqLGb++f!YfKnen?N3<#->s zNZb^xXXsP-_x5@hnArN7?cl6$g3N*?&zB9h%ZGuiA8$K6-0nJ`8@PZ@JDAv5ryjuz z(I>6+NLi3qQ5kCU9|lGu|n_tCE|OUEQfySABcEWiaEpc$%L#)lcYPlT^?Ktb{9bZ+5g4 zo!*(4bTuN<{JDh%AaXHRxc#8$z9X8QlOqhOO3Rv#8v-;;6|wy`DvpiG`%aK(Ij>2v!^S=U$N+}SF&%$t}>xV=Ff5+5mNDE6qngMa;VVQq>^t?j5kDs^pa zcwT8d`xaBqy&<7XRm+Tt-s7n>rwonVXZEfq3$o?|Rc&*l$ZMvI*dD%}SNpw5H=z>S zP63-&+cuez;!Y|)?Coks#iLb^VKW!!u;!KQEMjWfo$PN-W^;!-e2>{n)}3U@tB&=u zR-QMEkmdGU#By=u({FMm*sU*t;Y&xnpBvI_k#lJ|~Jmsrxg;?ptLo z?+Qom%H0_aLFcqOp;l#6$_vnyJpLI_bJtpC`Vj#?J7O zX(wS1M{(xu`!Pp>Phs8Wc+avO_4rbw-Y3-0>n$($CB!LaMHPH8I(?(PIsbW4a$0Dnu=UWp==61dnB=N%2vDsYlg{6zwES32to{LoIy9CR`2NXcL+DDJ zQxIQ1Gp1CGQeXVDz7`MX{UcRn$&bBU#^!ir>G$>8m65m9H^)!pQeO>7!XctTbm82W z-dxLD|9n+&1{4iE?(6Hn01p!|3&27FEts5^c40nZNl-lz6w)&F`Pe}aoE6=FlB7aJ zSf&-s?jK{CYBEGRLz%>;hvUsIvTKYsEG zwo#Ia5xIA|lT?ak6G9O3{4Llgr)ekX3uEKqSwRkE)1Qq4j4o(E76Ve%q}B&nCSKp4 z-9ng~S;oxwg zwi?7q%NRl{Y}a#BTNCDT+-#~p!p9~{C#`>4>o8jR2PTp#UNB_gl|Tg{z|WJz1$kkB zQXo`Pd{WY~dvAfU1|?(!(9~w@4py7NM~yv_1BRASptFb{5D)-@3-cRBwND@>- zZ!a0E-#P{eDLw!W6HR*@Yq$n?Ggt)nmpR|=9)9o1pv>FXod@fd{6S*{3$8;hIGaN zv4jF02g{~V0+fZR8BFqXv-BRitMwJ%cHYXVnro2PNvLX?6-FKiJQBC(!&){X+fz2% zy~;M_#i$apz^I1Rq~k#EQ2D#hDdz|m_b07}rcAu3@3Ignf2@DVxx0JPV3M}dxOiGj z$nvNz>+R{l>*7q_$=_xbcJV#E4MW zJS1|nTK9gy#dm?;1Rvv#ewWh|o7U&`c`)NW>*nkYI{iZ4p%6{-pXv;Qm=MYC5e#=x zD0cQhEpStg^%-t5Dlcgskgx=`7t2d%5)u@7x5aGt(PLUkU8 zG26z@MRM;0#(`Bm7q`L{T=fuMd1h7hE}h38h(%uF<_~M(FN%;hD&JM29{k#)i;zvx zmC0%!?}d{v;=-I3#h3m5g_-j}x8V2Vn3g31aC zsB=S)azDX=z@9|QJMBcA|&WL3siluwyAaf+vfZyz>OzjN0Q{Kl1 z8w}{#z<6V(oi(uK>G_)|6oMaw6^@Gn^&2Jd1%eqrcr#2dEG#^7W-R@`;$1|buUkxE*QQ}_u7ht;Pu*8I;25Q&N`&O14WTZWG_CNT6SZ(mL{ zaxgdWa{X}Z`R=vSX(Hpo8^@oALP3*@<;s;S>)S)-FibfDZgze15h6$dI#D;w7v|=s z;V-H%(loMH*pB6i6ndrsmJJ1ooY|=ydOygee3)H^wjSp8mfRCHyAk)zUzIr3VaML8d~YwJ|VK^iy5>M0b{mlH!fIxcU4`~V=%Kcih(CY zaFqe8zs~qQimNx+uaFiN*OC5|#Bp&bZual$J)32->&YWsOZ_S>3Sx&boW-}wr$*X2 zEqMj8QTQ%6`sl*xDNF2-@a`b<&2&czLfgxKFtu!b9+T)`zWJl+#8#V|-;-!H0&$5t#VD9d=6jX!_4Y<6i^ zduBY%CM~dtS)?w2?qT=)RpMkMf^?7)A@GT%tRR8j=C_~=xRO{&g_GLed@W$$?>9}j z8XD_IwL(L~_I<{QeAu6Zs_HT-q}l&WKc9vXt8$z6V{O8juBSX@0@8 z*(8NP)9?BRKZp8>x)J%>pmFy#43ssWe6E$W;@E8_WM%Oc8r+ z#Q&k+1{;+-U<;f?=%rpx#D36dF~LGk9uyRW(hdWluf9{~S9W~nQc}1WC6T$Y5A>f6 zvwt_Z;xBEo3aTRN-r!jzLFX#KZq=``yqt0)Dl5`vwQM(um#T03IkD;6PKZ;AxZSNI zq`T*3OZxXc`;CGlA7kZSmJAv zw?M-Rq*tN2k|OT#+`SDedtW1w3v@ZWoaZSxZ2$PGiOXrzH$*xXxqD2qAKk+e+adX% zP|}ZB)qMz9<9M!dM0Pkv8mvKSv{IKig6}^nJXhpP_9J6_zLBSs`Cr%ajB|OeGYJ(0 zvS^%KTrICOsZ^Jz038>{tM_UeMj=h$_$6%FgsmOAKmlbr00D=~92lYQy}!L=0F@di z8yo8U&9WAlEF+3TO;b}-dB31+LrQrh+uWG%isvHGOciepC7=|#_n8YcMlP~KC>XeS zT==T-T3Yny9H(LN%Xg?8tFbI86Ele&*Ipp!IJ_8y!UQnUdS<2GE9a;%vhW#2@hq*r zqfj3cPZWNoujzW+k=BspjaP{>Wj%@IWR5kc*ksI|t!{YhtzF)BiuB$Nhl~Ma-B75K zl9E9OK7;uWy&(22e&Dh6l|cSzixMo0uQ?Ht0=29EAnGwYqz;IX(?ZB~>~29P=PYDSS=Nc3vank*vVnfBc~MF)a!e zf~Q@+488(I0rGg+B`^uGuz9|#ViDKbN0NdYR{tpndXw;~Yv#nkgAO|?2*$n3WyQrp zs3#Yf-`+0KH~c#2wmCTjY~jbr$yVUrOebW4GA^@!1oKSTuAs?|vpn>+U0ePr6rqp- zI0w9%p)*X{UgfjRcPWk~24*B6LM^j1Y=r<m#g@iW?2zxS;G&E_a*|vS>j4oUCO;IWK+Xb%RIR*w_d&A0+2OS*%Yt0wza( z9aJQ~0p2gXTG^EV8q0tlYG_y*Qh+ti3ZoXn2aQ4SWx(H2vSz&w$i7Gxf`JM+-n%<~ zznxip1(|=r4#7YL0t5?kJ^70D%X}|izvcupcogDe1o(>NdNnJkXrM6*>C{P%stU`Q zCD(-NS7iJzlYfqi^{gtbug{ZXH*N--hI>N^=hF?%)C*SWTpI=FqV8nd?CxG1*M3D1 z#9haTS*5MAp7}#(QKBpT;{Q$rC<)lqDV~cvfU%OjwY9a;-HVHTSy%`h49$57j1E~E z0RL6u_3IW2k%8|AA9!P;pYYY&;6Y<&x{QRvkHxS4D+S1Tzlx;{Hy%B%Jm*J zOs)>fCyp$x#G7ah{6WpJ_WP`HT^Z|&+`u$)5r~nHMg2q zEYo(Y!~%YbLVQ!j97ex7X1oA=doF(;cqiJFT9MF;VE<`)TJ5poa-(o0QB@!9gED@qHpDL|nhL`tQ-lDa!^ljrgwW@IMM z?{Wr|>4`6Sp96(8VcbzwRpZ~eX~MGC5usyWrXrn~O?-K?^Bd5*o_?8Z*3_AF7L@sZ zK~#`1xp;7Tf&h%1jfW?9^w$UD^PmxTe{bV7xiJpG5e*EHhoWlbf zrN+TAa&dNokC}t9(x}f zJ>!x4eJ+yhm{2h*M5+pIP_$~_G`)^mDX2{%NCjO}uiEL%EJ=@_bSweCEkTpXMg`30 zPIa%baETibbzr~~O8!g*27jgtZYblUsHkSh5fYv~yRl67<%?Z#bIiXM`uc0NY5;}++K0-m z&~4pok3TpF%)}=Se|1~_w6RlP&90X_&MbxOi-F)FLQ=Ra&@m02p0{% z(zR=e6FZBGHqor|EYOqp9PYhUl9`?Dk}n(>c*0nxJs<~}4gBGIvPnA*oF%Qbn->D8 zpK0KRDPf$prhe|cjReqg?j?22 zgSbDGZg<{~%v2b(e~Z2EOx@;znTozzLpaiBzsVJNvbE9bud9@AiQujfF?MpL#tz`qmPv9r3%p@f=3^&(Ox#-==74a}2vdCG(sUB_U(@9sl6|GtLxF z)YP%x!8gf*HOVGxksIa*pBGXkn~sf;9~Cht524e$(BRg*AL#f!f|2!&U|^m9FQ!3p zwacT5I5sEvEhQf(L`nG0+5I{u{ARC_PG*u^lR8+rS zonW_Hxg$SV^fWp7u4q|(y}XjLvZZ)x;mO0H$fzhR6aZv~&;07^)A@aHkdvL=v^u3& zXb43&W+Im)(?uyM28bSEVPU}d6L(NlRKzDH4mEoV)*yA7sn_yUlDIWbhZG*2AJmh$ z;mIRSwHr5{Y2Jj+T1ZF;^e{mf*y;U^R&2WkWXQHV|3F?B> zGFa8v*w_*>;e1a%8dJ^LjOV)=0Sy7L%c+qhfn4jg07ksR8KuhoHrrDlRWC9~u@0+K>`5gZY7s zY70VKT-cxj31CGW92{{6gAAvJUy{+0k#O25=;|hvuIFAEkQAdM?&#`zf3JFH^F?Z^ zohK4iK|_yF{&Hgjeb&-%=sJ(MfmQW#Ye#p z_wL5#>ObRDLIuTmY9 zH9$W$1mJEX_Vs1cY!@%m>gwv^laZ-iy7X|H)~<+xg~f5V`E41C-?}2d@rT^OBZSHa zhae{i6U@xaNcisX!y0zj(LJ^3UYx40FSW^%0*|?7AgzGs1bEM5D>_Tj+LbIS^oe#yyb?k^DA#8f%K=A?$pQuxq~^n=7f7BC3_` zJaiE`P+k>m#<$4t-rM_h!-nJLFw+|wagO;P5fxSkR45n+Y24wZg%JG~k@!TeBEYp`3l+E7uIh^$3|JH3Y0N z<@_W7R#f7<>qtx|)bLW6Nye*hCOKQ2gOjr#RIsGB0b;EEtGxb*1O<#uR%G-bz5;s> zHlZqbnL;u#!qC3-`6ZE7nnW;cr0V>f)F$=g;@Nnhvs6OXRY9SE#9rk4~um z@ntB>qKix6T}G9N*W$_akW0SWH;aD{A09D?_vfnps$&ly0P;5o*B8J)Gf)VU z?mCQ>oriCFA3%o5v`kw|16?m?2L=IgQy3`kwVr9}3%N~vYHCzhvY;|mE5ltcX!PTt zJ~&NHZU-lJ>1)R5UC^XLC%o-zi3u+Pk0LFf@uEWKA>t0q=ZeffMl+gY|66pEq-wlW zT%SHb%ltmJ-Q}G;NtzIc*73&N3m)ysM?W*t!#TuQj#qG%hfd6Fq+{Lo3aaWN|JTb) zc=INI9>cM6o<_`Wu%ONV%^*c*M@R1c`u)o}{YEFNHn$!j`okz-q``_cT#-1do&KRH zLvJ7)^4+oz%*VJVq}rnwBXFtgE2+OHUS)~<6A+dwM?rEMnspQVYGRKkDkvw!46M)b zgk+;60z?cFRZ=#t>3%ry{li}fqcbjyW4@=6yl3Z&9g_FxPI&z>jR@ZU#zbXtguXMRxI$K~=(qzdB9huS3+k2>`3T$YHvD5CQ zwke9y__8Agckr|QR+F>`Y1D6To}@&%)-Yeo>6=UU?Dsgn4ZQ(O4(@u)dYW2xy*-2K zdK><5;bkUkLb=W>NS($9LmW^PMFowIk29{Of|d*la(!nzjr2Q0bjaxWrn&YrkyghH zC^|CTmj_Wn2pXQW_c~zOU6m#iJ9<+cq-TjXT$;pVQPb$0qEpBvt%2X0<-q z5Q)A)D}xqC?%RWD7=Q_w@;Tl5IZ;i^okS2cOHT@9LfDcdsKtq~Utt-7J}ad|h`v9k ztn5S)^feGkX(Sp=*7`yVt)x% z(!2NXfu%sszz_+F&QfvLA$u~-2WdZ2$lZzvOO5#@oSA`90^J;_Bc1n%IPx!E(XNS0 z#0o5Tia+4AH{sAn7v0>6_)qc2as5q&8-7@Io#NgP2cbI|;nu=K6@f|BCo#qMwY|A3 zjBou@yL!3xg#7sO+6uY`h%jz3_<);0GXTsIpo@f@Sm{1Xyl%^bJxOrMkT2QW|J0K40GG;#k7=V-XlYV)6N zB)alBj3(CYCMi*D4BI?f#iy8v*<1DRTYa}b$kX1 zlE@&PxR!vwC%Y7tv499cWvWKefZ0ji>#3&@j?%dBG2M<%h+I2W=|nG%eRxEDUANd< z1}-94gMRuY{+~fPV*Ki>&um^DZrEhcNKr!8>8dlIpjlCZZtH#z#lAE@H_zmO{Ns#~ z*bULKgxbR!|0gOX$$MW1>2!>LoW;RIg5v@9GfZ~Q0L9hO<6^28W%opB(-j(bs>!8X z0RBCG6+tn;YmfB*80QRqV;|B}D_2gcp1K78JhTySdYroCT%V|1f8#_zog=z3*`m8P zv`PM{(yKuw<{=!62?}x%FI=id-E_hXxPT4^BS7}3sE~H*ONGXoh1U%DvoW~Xk49e~ z%<-CH!rne<`Mb#oAMVXg=;?3ezcLjdK}5rj;NP!+7OXYZ?{`-mGkuX6?-2`PvTe|VCyCrDLQ*5~2(Zgo}^>B9VjSeT14K01*3 zsAaG4Yw|Xn);O+>)Rz-&>T|dn^__8E`O9Y={?tmQVFJ~R@h0NAC$|+1Z7%71=?Tm$ zsJJnkU4@mzbiq~Zg=D6sHT+5kKu7tm*v(S5Bu0JxY40vK(cnOrSVB~szLkm8}B7YTvkQx|%`99WMq4OrjYd|>j){nMk|fOC@jG*`&#t;kJx!1#i3;n z?Ck?0!_^aN&$FzdH#}w;?-2HfWQ=a#>Bm4{@Tqyq<-#1tKMvWY97+L-@LvESd_N2v zja(LR?QF!NRiu|}DbnPx4+-fZi0`I0i#V0}hMynn+B`r@Z3tK2!b0)vTiq)?;=jGe zBV9u9Y)U3lG%j3m?}+Je_RzzP?_%-)g(OX&eGVN;WKNlT zOfkn78f!w}ZDCg}?s{xV#ia#D;Qu~t20ufHOjuM-O<_Se9xv3OIs>W@E%S(Kk+_*^ z&MqOjtS0o~kRdxLLH=mj98T(||FU^DuG7X^w=y_8PK1kI64FPzQ#s}z1dd9}Fm zDBokI-{G{`a5>1!R>GPg5S#49qgUE*6|3V!`ZqGd(c<5EVYH_lf3EQ0M$r!|wDmB> zWLw^^`j3^Ex^q}q@Sbj)KNoCWkcKjwgajR;CI?WL55|ROC!cmK1AYMre{A@Zq+t;q zFCQxwqFuTO=bV^GA}*zty-QkCF0#XNs2;h<^xqD*`7MD@myVxm7rs?ilfw-Y_#B1S zRnB>|g5C2qFo%He?geD{F(RGJChC2*DH??0#59GXT^0i7GqOn=MCH4iCnnl6ox&~S zrAOib?K1tZ9d+jFQ;YB2&k&qFk_aj1^m~1C$U|m1|IS#F5uk#(K|la+q=#m?6ZvC& z`cj(b!~N-Ge^O{VnxiF?<4bH_ZM%0DwCbpe?V2fkS$gjvZ{^qVkn(ue^>GX^XP>c9kiLWH}$0;$IymxqZ3a z_TV&p{*570`8teq?_9D}_ZCsp>+`sS-f1Q;Sp#s_T`v)ao@32^Q-Yo2W|`6#K>pB; znJ7%jyBYLlmKaZ?CJew56BE}5Zw5|AK>5`QrJUVQXycy7&AZSB0$mH3c7ex&Q@FCq z91Vu-F@ftZ$wk2<8)TBjjtslcu7-~bHd&hgC(igi(pVuo*=e>nqpZAXZNp?tcO@a4 z)OjQ&k!?EHI6McJa#FsESrPA|1rI+R?H621Urm)Sx#9x8f*c%9-;n1BwNEBEoWZcu zxNv`Kbz)4jAClmNa|9tl)9hChuKUox8m|?1xOIb%uuMZ`_%}28oUNehpCH;fGeT1? z4kzE9F-sjz&ZN$D1uuRx0bZ9eUn<_OMkE&QJJg2`6ALy@JdL?1W(woo=JT=?nRo7! zKpvlS_HrVZw>197c?h|K^8)`u_vQ3=5K3~`imCVuKzrw*(No)@SNA+YRANqz$|-Q{J+pr^nvS1A_?0@5#*!S1L#lh> z7YP-W$p#Sg82Z&gjQ4fjKwm$zqJj=iHE04&lD6N4K=!Ed zGwIR&p%E;hF2}H(3y3*;sEF0P!xx32=z&6U4muSWq$y*`D144gCN5{H~&2}u8 zI$S)okv+7xDRi6v(C0(b(&7P4bw#JF2A2K&F zVp02?hkx9G_FCcnR}U24V_cQqDyLzTaQS9JVaRgKd~>tNBJNrgVdXomU%BV+Y`xdF z(C}j7cBhZ|RCurv%+ImGdm8v@nBrfIQZWHiZyFZ3_!t$TR+^$p479!*OXan26cvEa z&FC)2FMV((a#zNFicOEhZR=8QPPlR+SH!-F5wU9gn+I%PLf=b7MJ%5Dg&PKmMl3v#U`%>mgXaN-A}$e2bVT#dn=EkBM}L_$(0_cZ`PjTU=FZOZaU4>VqzbyWMvshV-D)aD=;&H}NG&DszFc6T` ztHX00$MdSo%N^2_AtGXf5T32(R++qyH-rmhiWzRc6PzKd#BIIM{Yr;2%tldAkN#5l zCCh8C(Tfw7ba&<1IO33y>|0SYjdaOVq&)>t7BH0r^@iXc@w*1wXL{dgHZ}s%2DtDj z6f}%(mo&OV3>>k4sFY>l&ZNr;?DhKqUquC7%25O_w;HAdPxZuzkizoj__B9~N7%Q? zl^zO)OL-Ke0_JQ(bAM}_M1x3G`DE)T`rkgYSgXx|Keew1* zUx92j-dI=EeI;h>yx97aXdwfOP?Ls=-?5h$FA!)peRGnMzzasp4VC4%59?N%{ z1dmVQHKqktcrfGOD5(|Bw929{Fd!E_ECN}_#mQ%I>lxVL*1PjdusLmnF+KCxmN8s8 zAxRbaWcfN%rS9`vt=SGP^hESaI%=v|f)zX~o#cKUp2q?)Pa+st%{!7*NS<{Ok>(y- zH3lyiPY31xvNZc}m$yDLZ9taYzKZ?gejJTXY12OutUh&y1U2e?M+T@aVb1 zmg#@&H(WD}NK`&o@D|HgE7*kbXQ@~2uk}`@dnG9)n~OdLl20O5&frL74>odqUGdCO zyd(Qiv87_TEaj^!#kXwZN(o~Q+eJSZvR)7)bi#9%jcUbA>coaw6R^~q;Iz#)PCQU+ zd^<1pIK%I);SrY}`bsSLVn6*dPDKxswcLtz)53sX7%<${oo$j)-wq3GcO0z0xy4(& zSW8EIfuZg>C!TmzYr~ygOcY_HOT3q#=#KU4=}hdofjc``IL<5$XK#eBcUCFeSn{g{ z2A;>gxDp}IGCpZey-pdV$0V36!ZW+BzyE(Y-y+Kr+Vcej!Z@+J3M~iE5a& za#{ee7Y=Cn3v%62J6!5YpPW`Kd9`)`*89)vBG*u*6({Vwz?gT3ya zL)ZvblQrI@OPei}+SB0Gh>e0FDJC>X)j)3n`ZOT;@%*AwEHGkb6VzA~6%>M`o4E6- zVYJ74vFVnOVv(WJ>YDUaBk=m!&Yv$dL>%kFpddpvlvuTc)Z!)k@d`8oU*=Lb0)K=3 zot5QSXGZFN{coU1_|MB$Rg7Bs6~U$lor+u>4xYXs)nmpI>p%v%v82ekG?C?Wm;rpv}87Dri;{0eGr!AlKfC*zgwI5KV5m zqJQ%{A?F6^E4I5+-gGV}HQoiJWGX6CgZRq>n1u3c0eG%1F1AO^pf-AK37Jt8V3p*Z5IfX0e3&K+Oo7@*2N!edfr25h0;m|30+skKwx28^* zzH4nctYn3=mfZ3s9*Y+W(A}?l#DT>NO;zCfB1CI=Kk*fV_cZXYTWeFS@Ed1+c78qr zbW;up0wIFrU}_Tyu20A^sXyL-(;ge1dqvlU``Xi$hpJBR>_q3DvK{R^ zfq{WAY#g(Hdf75ho6}n zNa`NY)DkQtuPQ7bg!>dOPVa}Xpzw(c{N9=6^y?oSVFl5e`=Q^~?dNZoUh6a`tW0FX zUw7KYzp^85x?G20Y916gcEd3uGNQxt@!7yf015kA#R}Ak3pCwH`m8A%pEI@n+xDfb zhYxffw)zTl*zz;nj4jwN1mTgEr<|$90`qhf=ZGa{Xichvu~8H#S#n*IShNe;%F38M zYZ+f9RR2U8u$+NQ&(D^wuoPZby`eJM5`wjH184q{#?j6+Nfb$biYmdbpD#JDVC>fZ z24U%$Bm?u9o9>jQwlBOnw1uzJCA_oWh2JYsA>i%u$k}|KR8v=@ikmnihM@VJx%nrVaD#)u=2zXD!)JIB-fp@26fixJ55QixGNiF)3{<#i z#d`@))k5i@k#6`l6&0aeijscDzy%HoD+Tqha7 z`YJ+ZZMekh_t?}iE(#G2tzja$AnuK)$0U%WLm4$0TBFSC7#Xo7`b-L&y*U{xB&n4- z1QY%?v}_(gj+XqplcUedjL_$0_U4kz9z9xm`#_L?^W(v*x3bY&rQuGt(Pk&lm$Gd-l5?%vIo!T7P}$eN zZi~F7NFN$M)0Gv=yxh1L5mEE^_nTX`wmtuW`Jt~gvF#rzoDQAygwc>DaQYY=$6k~c zWPXzv(Ac*1Wtg3y5D^#2%6J2mjv7i7ne95xJ9k?XjwGc;~_a z_VJTI=u3%_QSPDAu(FAqbvxM?)GaDsdH%^x5gge-6me8@L8xR3jsle`lSC=Wxj2vl z%Qj)s$7$k9l9nChEhT*&P2=ZvixxB1zLmT)R9N@CaGn~bajU1xlp=Y*Ccw~KSYdnz z{GlB1VYn!(HBhy!5~B{}01;79c6AE4%6M>5gpi2`%8!V&(K=8chQ`<_&=X>?T1K_B z8|!D8E>OsXYckdf1)!xF!j8}v{%cBSieXR6*AFb~axeZy8>oOyhyl}{U?sTUF z(~I7z@G;8vQKx!g&PtqHGY#-wOq7b68UoHt5wgTY(l| zVXT4>vG(@%@bU3aM`R!2fy;+chw5jLPe!bN4lY9!$r*I zaZhrUIWZ{ohb$U{iJ%n;AaqimbLU)#>wuEv2iA;80~R6fBaX!bvF?Dp1cj=}b=d)1 z_ZPF2qYaq`BQY z>Q3{cp0&umzJfru&swKC)yD~r9(ZN%x9GV?wo(f4{ z!FAoif+BXv$axwQTpN5blAXXqKTYf225M)>1zyKt#tX9}0sC$tz zZs;O+&SfW$D((17!9Qwe$LXH<%KU1fM2>rIjT8h^3N<`zY&a^v0c059Gy>q-_7HFa zKGOQODosA63f~7Qix)Mub`$I#<1ddi#pwQ>^q{@X#=cMdii3a1P`JuC;;bf*rjm9! zO0tR1UQpDEvwGTDaGm?;H= z3poeKzyrySbZo6^SwQCa_bi=+GaJmf(}9?aSV*{3){F{2c<`VfoFOl&n#hO#ep7r{ zXO{ANKrW?~QQIyjp1>%;Trl+aQ2mc3QdYTWZMi*c6tKw20rL-dA3I;b6xBf&jzL~j zrRdeVURLYZV2OG+yy+HCauE#3mO`7}9{b}#$c}{DXl%YPKaYXp)=npW`Oc-V4k>^E zAG&+R@9$K4PWr2@yat^FH6^a$C!yy)^ZbS^Cc&D|Xp67vWa;GH_bIS{BL5V_=&1+k zM%T$DPvksQyQLJKMc21S(=lHY1MJSa82LOCg_l*odP<>&vjAcwV)|TURvQ^bE0_%x z97{w|0OOb(1>``h7%8zE^NtYM*2}BOw+8YJE~~4T z&@ci?1e20mqXArZ$bcGJEqslmJ!JG!&i0WqBnX}{qRbr^u6#(5B3E?Ck)?aF3}Fvc zaz-3_dwa`|YjblulGraWTzN?W!`Wb^#;X)ic>W#F{T_*M;R1?ttcH7o`}^fyTbeOa z?KZjavluBo+*~Ys%y!yqEjyo;m<*QL2tV~0*`uu`atCKD!dTXrMkC_?FrX7i5)vdhQsocyuG@xjyyChD4=9+DbY`y-_Wz`e&^du0(t zi`UB7s6Sr6zUk!n8ks>9?Vlk;Tr)wME=*}=5Hm8wg%eVV*sy9rcFEV>RkaSGG;yT% zv9SF8JnlRIJD%KQ+hSyfsmT6a@89 z5R5dPy(qhtNqzW4 zUEb=;llQ~yo$-YmZ#RuzkhIcK(}fVM;NCJSzpul$cVGpYO>#6$UJ)>V1%uf8`&;(_ zhD()~mq)t$hED?7r&XS7v5@gYNdPM^6I4-c)Vh zbo4~4mt&d)=AfXZC6IjJmZtJ4k&ECdAt%2N z3B#6+!FWuPF4)NE8bLR}bR3y{!y0t1a589AbO(4ffE1!YvWi1UsPFu*eV0Z>f6mD4 z?L!ICY7F#1V0Tohl^8?9pMBofPkCTIpz${Y1R>FO>}O^2;MpYxG(GG(8*f9CP(+%$ zY2-kBhVBPzMCf3xaQ*_*vC(Hd$Bt)Yn1-W=IcVoPXce6HTN^?4WigsJPFUa6w?H#PG>Npw3?`LNBB92$S?pt>j#Amd(5VZLE$K;-^Twu zG-P#n0E-W1TfhY#;G)mwG0yl#tJ?3#4>}e2n9$qGd2|6VuB8qaw%zZHSGCMV-p4RH zxW2Mb==ElFdEaR^Hf3q7;-W7p)KvW%quwTT`QFrEMgt97ax0JRaxWmQ9(`ERN7Iq zeaXheTrNDetx#%^G3Mrkq+5HvCg67AzwRLrTsIFBbIEXMvN-NA4em0*gty?W|Bua{ zKk;qd=%LuIW&GZGeCX-G#!u>OVVY?v+22?g1MNiz*H9at2WM(GJVRiQE`6_M)3aM? zyB$02-m-lP2R4Xx`wpPqpY7Xi?kYp#NBw!XS-Y`xjLo8B@C+@ime5=bF%`M}BQZB# z5LQy$gk0o&cl+ie`OJ|vK_R8Wwu(CwLiz33*tW`k8-HF>O{}wdETTYsYqzd0jni*i zD&*=lot%B_XgXm`h%py0w1F&NED+CMj_yFHp9Y<$f8lST;WBG}vQLW?=!XDcqLc9| zZa$8UB*_POs>R;Myv>(aB#_}2JI^Q~`FY=uwEDi>Lhye|&9go{IzlrrfHY?`urBPf zpLWfII_9ANd77&+om0Bs@~eJ$`eWi9Ya9b)`sFMi6(N2ITRCbTCVO;Dg{7tDqasOHc{i{g7kq@0$T+zi5Lwt707V}uwe+o zAG^97M%|>Cfr|hraS#%=7to+4#L3Ri{u5BVa5Cy@WNd8v#n7D;Y|BkGfMzQ!ER15x zXa*M2@4daOf&yXy5QsZK&Vf%v^q}?DeXjz86YUVo^0ooPT7W zD=zS1R+x_==~-D*q}f+jZX2SRl8_~!p#Z>x&K*-$U{a#!?8JY3baB~M)VATNURk!fq1#}=e zFGVXrimIffAW-%n?*8cP|56{E zQlO9p!3pD1+X0(&GY^mPe8w~b?O#5klXh15Jr%3bd37T9Sx@Tok;~j zF%H5D9AyBJFE$>2L{AEs_pE-KpDt(KggLa&Q{wn#qt;h?%LUV$_tQDy6JS}QnV5*5 zX?zE;K9CBmZo{pu@Bmo9mw?)zdVY#;2AX<%p?kjnP0~8HSblIno>QYTIexRp9`!_& zQuWhsOrVu{%!;V3OMTn7avxf_`F04|S)il3f8y{xVl-yCYX}Ybb{Ug#7zr&Io3456 zm*;HNyRL?hOPDyRT%sQ>N0i8Nv+-AK+~IR=iD@tFm2A5HDeIyu!dQW&R9|1;vv!72 zDYoL+Xu_Ylk)AYHmzoKo!OTz=l%j!N_~r~j(Khsb!IR?Si5E^zySrKv&i+<0Y1b3`Lj1;P)2=9c`es1nB;s0y; z0oAw5kB{^Pl zj8RI8$G7EmFpV3!Y8pHvVqs$9tMSwQTsG(P%3XyB8Nj)9xHA|u2A7-O1{9(+9=gAUd ztm51oXi1rbu$uohzeWn91ZLzw_+yp%p5K3tysW5CTv1Uc0A)rx)eJrfA{*LgBo26|p#n zg-I;%aL;HB!6M58xfHv%wRime#~jKB?xhLVA5utru43!luy5FI{0rTNJo?2;)*|${ z?u=226K$BN4WjqOQa|q6SNLH{^HUV%Vx_UXG0JLV$SvVMOR4R6NU;JLT^@;w(sEtJ z%XVzY=vJjbly5^ADHCbUyfEMlXatgO-@DsaQ%lVtzY%wuj7Ivl;bg$tlv!`ULO@^> z5{PXN0R0o7Z2`@V(P-ECkJNquWCw(v+@DG+{#yyD0D$`6iy^yjnma{q$0;TD;|N)7 z+DMo|ySRm&BFzpjmPNdDAkmKkDe}8L4X^L+G_K9Df&q*W_d9xSch>M7h?n6YRNKsc zItz=1t9Je*TTh6!rpxn|N z8ZmUK3KteeF@b?ykwReNdv`U3Uuf1WoLei_nb;+7WLpzu@Ry9v3=!OCIRqlxID6YIY}mZKmpE5ml`f=Uf(xzp6W1KLqI*^T^En zVa&mGi-|q|;Ud9ydQF`d?UCY7XJ}qh%szKlRC;?8%`n~)mH<4xvl8_vGRgD&`~_O7 zxc?t}Zyr|T+W!r&R3wy$(nuMSkfC{`k_-u{G)h#O=Xn$rO@yK%Wk{t-^Bid~G-+5g zQqeqXTn*3X%HI3lzxRHQ_xWNT9PQ@o#9}xOg|0UKNfzNUxL*~d{*ke_h(|LK=S^(UD0kU zltOFa1xJ2zZqtFQMn(q6yM+%&Z8L*#3BE*c29q#G_54l_i4-k)`sK>mhxWk~v zz~Ylp%y&Sg!;LTtAMJgP31{$&yActZiPK1YCv@tI6VXeAh5)*f)Rs70GL1aD-N-=J zPnQxC+k)WX_Yl92A(^YG-<_Qvy!QCSNfnQ&LmIc2<{3WPoB!w-W}3-tcz)DrDYPE}i}NWe#lrHnW-GnJcXLBN&#yHyX( z2JB)ck-=uFJo0X8{4$67sv`+q)F*$uq+c7phLwd(wbAADQB_gywP@0bs|XDWr`{e> zKB+9OzBO@21@c!rm>siaVFH*sHSdWCKEaS`_^5%h@>j?ErMBQ-_B8}$M3+(-GvFIgir5Sm-bI$ zpiu~fY}k9=w-EP2atHq5p93R;6AOfwz1*tUEKfZ*0@4I2!Z)e4i>2mXlnXYg`%k zfJ-an)0&-Bn{9(Aw|*+*NP6-_RO@tQ#`<_H%*E&xdt_PP;%RrE)1nzJ&(7@8M$1)NG@L7#4cj-o~-8?gah=g(5iEc zz4hd0gc~biR)X)*?K{QJJP?75Y1SRlkzpYY*#5@E11`Uf5uXy7^_PHg2IwadGif)} z+_*RGFFQ0)3;6@5Bf9F8YQCQ(Z4TIyA7c3~Vq;5c(spjY3*LgCq9P~NHqZbIv}(BY zj-r^&+xvaxT5sB}SS^FgHMfj6*EbceI*OQ~%WtV>1@K^hVNovBPkS59`T6+LZ>|jI z{bd86_Ou3i;;|F;T$Ci1rcuok@sJ5D%%kgRPQm7rY(COn__e@!nZE}7-`Nm<9;2gn zjgOC8A;c-xdE!@-I|{QKFe>vR_y~)^oie2W?X9VsrO_N{fljENGo|k?B7#LW=G7^s z#l=M@BmoY%4GLKwenvykH3pv_9zYwybo=&Tba%9*^Fh=!Vf%ENjp-TW<*4X4#qKTcp-F}YC;dCrzJI=61$W!f`r2`aY-_8a zCPAo|wzH4L?6|}&d8SHLvFzu&NrX(0`qF9Tm0TU8w9Vj~&LzqnjVxmQX0W2c#8ZTm z7BTdYMs%lRM~t`LLaX?GoQHXMZl%6KG-M^2+Z$}m6aGp86Cu14aK9y1)2_lnDC#`E zy%`BAch*zbi{XHK_i2CeT8zCQU~@osNtsE==Q3_D5JMZz`ff1aj#y{VI~R5Ynz|JyMCMVZeEO^o(hzE4k7SZ)u0 ze+~x8v&>_)a*Txc#S#Xc(}g22H&MZ~mG2ltse;2AL+EmThH2GinyO<^3jw&31X0!r zXl1QM;4+p=@7FY5Xf{(FhBU#hT>jl#N1W^P^NZTHiNfv#%R*GG(H?WVF@BVgsmtw4 ziIP5s_yzZ4pF8z0ye{YNgW7d*Ak61@rRYZ*;Zj zJ=_HId!se={DR%q((62D;f*a177OiXhvPu^v2ToeoW2vMthJJ~N5}M@COz>$&Yg$O zHFztBT-c|se^2}7Y1&*Thk2RB2#(0G%QPilMzmQ| z7BP4bN@Zd^+~&QSH+DU7idA;Uh4+T7X(JRLaz~C(>AFu|Fg_d+DL&k+k?*jV;M)gG zv8XXKZ@nkxiX;r3pSU$Ax zg^&&dEEJK2A~cL7uiDyLw&}>j*Ftp=ZT9+N`byF$cJs!UFr(pt^1@85M#JK~sj-)Y zYzOW7`$IL7J}7rK0tdo#ydB#QU7_ws>Y2vb&(+maS6+3~Iy*bF;t1UbMHDhum;tDa zIvig|d~_wH)dHIXAR*%!7yG+gSUwSj4nNkMe!Ir8@OD**$E||mqM!~<`?6BO*rXzd zlkeEN=?7J4J70A2*ipKS4lj&b=6H^A%%@K7VP@{h+3hl}u)F}aF!;NbAX9}Net4n{ z<8to+$td3Xgm7;*DsR)v>@ER?WswjfvSa)9t=qP}oy&Xrl!Wwx(meZtQKb74`m6EF zcHO7(TpxsX6iC=j22+1)9lai0|=JFu$F55w?`UhUyBzvj7G_La-pI+f_V@{i*u&fHA-8S zBWa-jmU>#Nz%!mjF5p}VprnDn=+Ki}BY{Swho@GWN#)R+)(pQzy%(i|dheHG6Zz1m z?&IeM?x?B-i%c&C`?nQe%7J<`C-`Bl>xPIMW%{QGyK`fIV9|Mkm4peHFhdEd|POzajM$UE0x}*-87lLl(nPVNaq$LKiZZ z82aZv`(@Ri7ny8tx57k|Kz0!ZEJ;*9+*UPG(@xMo{r#0d`{GgeYta4L zjq`HugsI?%c^^bU<*`3Yc-;SFs#wjBfpZjnfw&nlR7cqCs~5P$<%HTV&u^U{kua`> zuF?x7V-tTnKim;c&=!nUiFABV@m$!0C1GKHQc3A8fRL3W$T{Afo}?lI=1339n2=!f z`g}n(kynN6N{)Ry?jl1YC=CQ21BF}EiX{7U)_m=}R*h`mUGla^QA-T;AGgkAPCXuZ znodl0Mj!?{g6~8fmz3S!KXiv}9fA>()IPy~<MLGk@8!%=ZTO7K1BD8Ulv% z)@Hm-QLVw|J7z^+Lmn$S&3TuGO0hwl<*Vo^6-N)zg@EQ^dt+M;O&!=84qYvZ|+km`}qqyF8fMgIUBLFp_ z$}GpmW|6>1A_{fIV2-!YFWiE#v=m{te+sc?nTwvh;rn#nc~Mal$1N(*O~{lHWD5e> z{T91}%GtBtfWRe}<|iE7Po6kI3V6?Q^-Ch9Qwu+0NR+fj%nq0}sW2?fE1bH&n!E9spMR@!~Zp&a;d6FFKycp^9F_Q2`2`AYbemKQ=`^+>`v>cH7zF2dP0zY zE8S}IIeq!*F_pxHHaq4&%y%gie%GjU%47Rlg;4Z9VKWlHGrMZraN19VyEggMwLKIG zU!6l_et`hj|M~I3L+Qe)Gf|$%rG6-6x;bpWUhsoG>X-42rYzJ21Y6YfZMDVA8mL`^ z@SRR{R)kNIv=vDjdzbUr2x$dkLWf3uZIE!CYFx*YVbRu{Y!3YZC~>fh(Vx1;ul9dU zLpzCAj3(+Q%MxGu5;EUJ|D$>_CSJ$B5>$H*yI)=|70*nP)Zmn)Bk1Kwc^jnQ6P8hUjCr6G*OsUW$r@p;(y2mgvxd zw&~(V1ytf{vt}-4>3&oID&-DJ?F<(p`rC#y>aKI5-%#DU}&_r5LSJh z(+IVZ$7X1m^IX=P(v4tP$Z{01qoaERj|76EXa4O9V$5e#vd%z5?g=F&f?tNZ0i-6x zt2c?h5b3v#Q%c8=m!K{pGO18qH}Gfq%EAlLIgeD3{Pkg-GQ~cyOBlCE(HA$>yW1F2 z8%eVOZ7;P7+V8iz0W57B@U&_OR0n!YSF$J6qOm{)?Kv;^X_Sp^R7dIiK zpeOXvUB?32tHxaqx7~F^eO*_zoBu;;^K-q_#V=I|Q-LCO*e484x+^;wvZT9~92S%WpYeGbts9Yf590d|W zG-Sr)vh2p4YKl?S?5wsV{e6NtCYV*KkgG%4s_d`rhA+4f5aJ@+ZiCD~SC zGjR)cwMWx6FStrS66!L_20~q?_UbX$01BHIq%d7^+Oo2)UUQkocwW_leH4!Yd<@ zCDo=QoE(#b9O1|MTRo-z~>l#&Xf_*BTedHFgug@z4ANgA!7!pkDk$~wR{tt%KJe&NWlfDDrY77!p>}m6lg{7L+CQPk zUL&k47W6pQE0N#)F*FN&<*&RhZO`EJVrr|9d+{Yl@Qd#)f&^l2XYhIzV{n=g2Qsu3 zAFfvHakUGA}ijTzC3x?{%e#YE#10P7|P|eO-s7o^UETDOsQ9#E& zwcu;d!pKv1sl+*`y3hKz&5o=O55B5tcsWaiZS$DmX^m~#8sjVyIAFiW&RZX+0gp*4 z&8>iYwFLS2FDI>bCgq8QBg673w8FeOV@%b55(p*^94G*;Z*`L3;29_3_A@CkA%Tl6 z$hWaUUY`7)?Xgb9_jUj!DP=)(%KKE(Bzz2Cp?nkK`Vg;}HeSMSR-GHzX0z_Zrhd>5 z>-YAW@>lex;@NUr(qt1jQHoVa>X_8ep%SzF`@lg9j2b*ip8$1K)fFi9h1xm zmZ^VTu0Pc$9Vy~icKN;RMd~vvQZ+t*wVrW&Emla~a&nEee3B2JsAG*R^A*wOO+Qp_ zQjKu62i|cv6+E?5-^@(wRKM8jw9}e-)3U8zf359q9>Cp1_-zZK|D^i{dksC&lO#ko z3$12gNVY!}x?LZ%10Nq>3GiT(whr}8EG$TE(wtmPPj92~`>d`m1I7iJtU0<}>0OC8 zH4Z>4@S>Z|iQJk$UuO$>!}kcrPA9R}QPfDXY8Gs2BNSTpFEy9qwr@T8!rtZeiWe*Q zkY49R_$qoXG52_U z%pg+q<@L1#rdN-zrMU@v6uuf?D>+FT?vT8B@s*p?!M^u~ucgyAwcNI`mfb{`{(07w zepiEdl%Qtn_Zejx+^V;N24<>zPW9jQ3bW>HBShC5u`x^@^^V~HeWLhRe0k!~L;Rx1ic}EX? z4O7a9d|JRTmPvCi=fFu>{djj%bCW9ZBev#(tQch!qssqd#B%B4tB6OJkk$-NHN!$Z zu@TA}Lbi@EY$5B|g}(!P%oOVYn$Ae*;g&5DxHc; zvg89KuXnN9ua)Okv+v_pjJ+tI*F5IFM)3r*$!j0B0h^T0_|tmNf?{ZR7pU*n=7}7e zjG~bVnmDw3{n-T!1Q~Z8sIR$X(&@-|uz#pIG{AQBchLo>h00?B+#cNJ{~ z>D{(`+gflyV6ZYwzX;=D+O+9H7b{T33UBIF+8b)n&fEdR))Vbn^tNrQ4AG5b{WbW7 zhiEk<;Ev;9Vui%80=;u z?Hce}{?8nLHeNK7sM&v>_^)QN*N|q_&90&YA)V5y(ydN|t-7zp-!N#6A4)qDe^WQv z&gHdjzid=GDf+P#srbCBU`cGn!%D-44dw#kS%W`|d~)E}1HdQGfWwnfvU^{9A>fuTesGRX^E z^w-Hm@es^Jc+qm1*Cddco|YKMq>{Q4hVFm3%0Hw}?rj)9rX8rqK1wagcRmZaV>`k= zlcumsa%*4R3BCM|pX!wlz9!JWpSU^Odw)jeFlCVGv-UW%$0_aWp>I}*aC#g31#`lz zRl%cT=Ly3bzP_=j{2hjf z;4Fxm2zejyQEmcQetq&N`irVObQTmMvmCP7_0ZMvKcL5ew)e1$Xb-tcv>1WNqFcTC z2n0@~t^EA-K$?i(0uBXxAyR65cm)Yv(oi$#O*{#7nB7_SQpLyL;*TF*e-*3erp8@Wx#{;wFVvhj?_HW%$B17l6F8Wpq*9=V$_reMz-;MxBY9GO7l^Z16 zArD87i=19NLRU;{OM0hXwY)UilRh?gCZ+59qsL8to7!&v+1I}t;tnaGTS@XXiRfR@ z#63r$G5TWFQcW(>3QOsia?6qNgVl2U!ONE~gT-TnEDI*AF0AwHb~?u<{4FZFy1}?uO*tKaa4La_V=_d;@ z-)SwEBrAcX1LcJl48lQ>!an)Kd299;&BV4jW%fNov(LnyhT@d zkJ4U{w;kX<5;N{_yrB{m#of3J)4GjIITKgS+`3P8pI%~A%N`0+q&+0wA7COBthBR& zJ3+QUP4jxYs~XR*PoIRWVn|dZl9K!p)e7qo@|o`~ReD=fz9)R@GF;}yH+CMw3Gq_vil`w?1bzH2nXfj4|YZ|1ewC>8QfyM_Er-a<3#E|#D;Z%yXFzYNyvX`j>uxB5i#Mm74ij= z7t+SsRJko7k(Eo5^vmA!o7K&Vnx{CzM`H8BI=$p2)<xnle|b|troDiLC+>I!OVq(0;Mh9qGBcaXBQ zBmteghQ4@rtVI&G1D;b+qD&^4%@z~{2vU(yIHcI$x@lS!C07532g&a6V8`hI%|S_H zqWTzOOSei%ablX#k;|83OQpTNy-EB=`ypZb=c|X0`9xs9ExUBik`#xB9aHkD2%j1r z18cu{W~TCS&7cP}YnLJ8y;o;D-FPkTV4{~FmkS+fbdfS5AyxVo zlg7rNr(8iAE|^e8lye#%j7yMjirdlnUIz6)! z<>I=Q+qTv!M7g;5_L$=KBPG_E3>86!pJj@uz5PV=={~cvH?rMx+4)q#Y!#`*Qlhx@ z_aP;|v#+Q!he{)M_mc{=&)x7`nimdp=ndKJ6PG(@b&KsVW+uJ`J9HcF96}F=x49K$ z;1AVeMC^Z?n}&^2HNS&U)o*1UuPQ!KZ%JEFfIy^a`!ch`6SFk7@>d22@oH#RFQcqE9EYj=H8dHsn z0hf~8IY?W$U8!+6fB6J;K|14BgtNtuL77BF0%dyN)>}7jSrkoJ4Upu5JhZfHOBg*t zHSg?GlXT-u@35 z{H*(CHjZ1A3Q1qeSux7ny6!d&dkn{A)-IF2N?L2vV`;fFk@~K7z_jqE?wqCHy4r(> zSNzx(JhEy1-Mx>psf~|=9T~+Np?;;!T?Da4X1^zd5+qqWyA1mzCq=j$l0=>)&K;IN zq&a=;PJ)BTQy*2fQ z=#zU1l~^VG+>qwCgy|6DjaM>o_!E*>Ajgn`5!7X>d5bV1KPC1-sLbLpA!U!!2BJd& zH-SkNx$qtx1&e=b=e_?8$;u?ej8a9anXx?ae8>A>MV4(w{iYi21-yp0T{0T-dvuT9 zIvP}y?eQ}#?G_sk4yU6~GZ6tiE7!4I*(>=f2%nnND5K+^1WzY2Ge0!P2?H57mjnsXPu0c{yI_C`^bZeT+W;YsAOu2@4rnh3avj-=h4IoPs|rrXODH}c z;@Af8y@~{Dg`9KUOTFrsWsH6JHY%F){RO>B`%9xk~Uai4;|2McTudQWn-~ zH>frfqn&K?f#UYSmUcp(>EM>=ww-xQ*kCHbrQJdq0$k%eN|xkFy9-Dz1PTPhLkoL+ zGc>bc++>rIo!cInmQ_?p6sFV}-+*4XDD1-(C`rK=z{mk~d%tFx>4ubNas7!e$3o%K zxS4!vXSyjnXWPoeW7Y5VHWVw~Rnjw$I>Ns$Y#n9KF~#gO*O9#P?o$OKY%C-&V?=;H zMV!qMObv1A)8Jgt&at9`C#HWuK3a?!=2X%@2t{^in^@F6anL5cGZb-aQ|zxZi#CtIkM{5hk)rTevu_6>e|m?3a2Sc9Rza`2uZk#tCl+!SJ6?jQBn)PR)`xhUU`a$d z=YRY5Q53xgpmZTp!+*GX;Nc^Ap^?oWoESQ#r|!nU{x0W&`@ko$f~ia>eofVJ;XYhJ z{0RPW7}Jh4N{Krc-+C|^9q?8OJKV!UwjnKosjbI!WTFuhGInZMnd zxjwV2$?kP<`Q%UAUgYx|6xQW5K9+NwZ&BqO2r8d^K)5gDj4CD{*!CuhbsE;_yVoqw zXlM?X?)c0!Rq>Gn;p;;=1;L}*!T10WOyj?wnUp#H8sC7i3rifUs{iP`aQA@c6D)yCHc%k9)|i<7o|3tzuw zuIC&XFV_`OWyr@|(AN4@DB(;A#!W#EV0GSr=tv3X*gOmIB&!KoF6nzFSyv7re5O*v znYTI~#l@v8j7L=c(%i(+a7hC2R9jFVq)-yE32!s7E>_>1Hb;`>tgW_-k{!i zx_H2oF4*h~J*Vg5T^%hnzFl`677nDF>-935_{qp7va`IB47t9Q zz?vS;b51V1?p#4ML7#5gX@59bEwKzM=79U0ou7`$6$^UYo23&yTubOB}mXvR1Sz_vN zRAE~q*5MPU&ef4!@%*AzQysrz{J7r9F-l!YkA7C8KRw)rNkBCwo`QOwZWk&F-DYj< z2EQWTG0^LqnZvgpcCX2Kaq*@EYfg6tsj*oHJBGw^d%M>nhm!YH$0RP9_uDWioXz+q zA|gT_c86T-saoP$P0iczU_}ZisRi7*v)=Scp>%t~)#E4(hW7o&8Sn!#Pz-qh$oVbf z+F>>*^yQcp@~yo;KC(rb4gPxVN}tnOR#t+5s{lgXjgGdge|au`Jt9L%3>D_^dZA`O zeGa(MqW)!lAJXqG2}k0|Gnhy}9iu{Y;v`~nh2vt16fr6SV;*{HuN?eVw*B6R*N0Y% ziTmm6>mx8#4#O_m#`pdI?m-hgcyI%d0w`4wijaP74e}hUtWxdit4(!W879WZ2a6D`}OQe)kxsLzno#xn|mu`5vi*zx-u%B6;7vdpFn|Z_Tt_F$5!} z@i`r2=1m6B3%rk22zZ^cL+PDA6E88_UANF>+wR>Tk}nah3el*NNKi9ZoIfM=)5`3{ zxz%t~E-p~WqCX`_YuSa@qM1uoJF)uu#36ps^ykDjNJV1Vr=7Z(N;|mc1p-GdrDz^jv zY&&aho~A*JO@_a6K$INv$wXiJtQBVAjByB;@1l3ZgqmglEHUB$BYQB}E_&AOkm6VF zJ(%$EKC^3F{9XDX4gz$>lxt0^66}{}BQc?Z%^^5P&7dHdSV6xk6U;v|WwM78<13C4 z*0pZ?8$)TjRfU1QjojaY23}{3g+Q9WOS%K2C*X*B3v`}C`mH8AcCaRXUJ`*#3Ys4K~gYVX26p4$VMU#1nVgG~4I-J&_| zxwbv8KRm~u-52z18_r@J!~r}7Kak8-hDOR7Vxq`z{FP#0exzKdHqr0~%(~e!R`BLQW z8XocpLba!F@_NyL+vn6|p06nY9NV;IL%VYiC)(1wokdYm9NG{wZVq_Syyl2f=$(iN zlOegHlj~_x^lDQyGe0Jd=ymL7rbo`#=NA3-LK+b1QBh?Uf8WJpvi3h(%>PQg^C!N? zAHC?gRdVzGaOO6ro&iZ#rcaltd3FgUT&H$SK(h-}*D|LAEiWoGjDSVi@r&|IN)bB6GviqdK&zpR$ zlR=Z2o|GRTa#NN=+J9G8t{NMO?l^Yq=#X7Bf-uu9ookT@A|z1oB}a*n90qgC=ypY; zB&^L_0?1+1CJoVBWEwm)mlr4)>8m#63jcBn1Le*Lg6B2|l>NvX17(?OrsUzVczVAx zW^S(kJ8I%DN6CYCa+iseXFmCW^OQaEYly~i^v*-}kyG*{(bBi412Cu^!{&l0P}8-~ zO{1nKOoBf=(B}dt=d?nmf`E3;dLmc?{$R7I57pJ>o=X%xk}NuFjI;EQlw9!-9+0=? zy7ua;PKP4N1nbHEa_tk}XcCf?Es>c)6R}RCIYtKm->=;77@LbKTn^nJPCwF-^>?D9 zLx}hl;v!Gsp(RpVFe>HdRysIX8MlUiDr7yd3{DaM*)4|w47D2ov>Lz8mcxt3nj*t` z9dV9}*dH<0=gYiis?S#znYUHDz?LguoqxaAA&!}cgv=9N@^S{iA1VGOXq?v5P$3}} z!Ok0{XTDQoLva$*{O9u!zvy7$+Tg=7;-#qC(+tK^xX zu_Md58#7&u_<7lQ)y|I(_8dQR#t)MxppPQL572y9wCIQ4qd79_Kqudg=?~5lH(V6f z(;$=g*9jh;Revwxzb2mdW60;>)d7kvhHbUm1)d;+P(~U1aQVMFdkF4)BBBTEB$2tV`&XXq zAF8L)J?HuLRXC$!AqcYXPdpb-#Qm`-c8kM6t7%1GPcV+8^?LcUaVmup$}hO)2eMEx z?}uXlKVRJ*p!gzV>-%tH8A;$9j-gFqruTTAyyG@cT-P>}?@-HDouj|L6%OyOu2hY@ z|M+x%R|-hOhqn43=jp?M^t;7B&kqdL-VHet6F{Wn5v(#(<1(Y~Wc1MDc62m1Fo-*M z@9MW13P%>Q-nCqQJZNolqXu3u32i_a3;Z<#MSpIriM+g=7)Fa}>aAjY@}uz5@<*5S zca-aWiLe2T;CcqO7QPwO-0ch>5ZG(HSMD5V8PJqwhA~|cSyt!$(SzTS7+(xUd(3D)sbBWf>j+W;6Jz2Wl z+n*bKbY7~AysLlW;D_ypwsq9l|NJ7>BUY1JbI52|>~re`$5YNnr*@(=u>zdP6d<{p zw0M`7YOCP*cG8SuFpXD9i$sM-(HyiTCK=oIN_A9zSYk)g!ZZ_RloEd=gPm{ z1&QQE7akp*f{{8_e%^uy{3QPQ2Jv2I1xu+48X6m~L1q~G9OK1b%3gbcl5qMI6Vh_4F(R_y762e(Wunn18b;p__ar7He8Ed*LJaaCEG!{8Ss4fai8E)^ zVPg}5MtyRCd`4|gF>fy)CUGDy>j{{aBy_ktcJ10DA)y8Er!lR9D-lzD7;X{pZzIsT z!Z5}y2jx9yO1Z_i`?`-U`W&xsb#*(b4IWCo|JAdj%xB3z5>@gul_kgIAA2s&9x*?E z;lhje@8v_T!c9pA`6jnvBd%z{*asRC$;viY+XYORPxDS;VKo*VySv0BsH<15WSqaE zQ$y5Sd%@)xe8WwtN5V_hDTa7|d?-W#_wCnME7HN+e@%_|@r(zQ_ zx&Opt?%Fyo$sA5zId!$OXJbIB=@G-cF6iiRrkb0Xy$%-p#VR#k$xGZD3BGs9aWOGR zz%LdPI*`W3##ytCoSaEuiv~axTau^y!P)gAzv6D`k5SF=J9nO9E))N@Z82?ABa9<5 z{)gWdRZwhj_s(0@(xcxqo}A3x|8_I+KtJtzw7j%>TTM(&Cr3P&wB&r({!r&7O_}Zs zKN;;l^@vz#?&#xwFs!1)VD=-Y>tLD-Ts;wch3~L+_!J}CX8|@Z&hyuO_a zP~7}rpmv?bY$c>!34~mQM=uXj=*D!TGe3KJOu^Zrtvv7d{tyxqy$0e=J&N6voD(Z| znQF=r3X>lUR7vYOIfo`kvKks11QoCg*9xf+n`4AMn7;lJYR3E9FQ}^z0BNlwZaF@f zYX+GA$3&NOI!g2ahkjNfw*EGN z$U?0s+1%LF)c?rn$=IAMyKxdwox+J~3EfYwll?DXcRDZS^7~HNtb(vYa4LDYI&C4*2okJ%ct9?@%|R=_d>mM)%ckdG?6>&-@F+m?ws~vL zS$FgbWDT$5j$|FjYoKv?#gmgND={ z=;<6F;0tPMm~o0|F*{D+t!&b6IY@Yzx5)pmO)T_z5W5KcHy1zF)To=AClLdLu{-6q zh;zWzI+VTqmuYCcYHrpf9{oLgPJ&|=@4h3~fbeMaUV2I2$S~IZ21|Q96uB6`8hh|y zq+pLrxeB40u6c`XR6sz$B+wFL2;bj)GZRPqg7^s56jwFBai{A)2cjk`e%kcCjI_Y# zhhtd^O0>}Dh%Ix+V}r$W4+6FY>-!p@NO%rzim;X^ynd~!sTqOoG6n+tYZ&azH54hW`dG%ZNF6Cz zIHV+d7%wv7n40>Ew-PB!8q?VAqtEdF~FRbrPGgvq1hpa()BW_H>s@;EM)P zp;;h68KB4@8cfW}QUj05CV0t9S-fvMum)H2jr_pTr^Od#mS$_%gv}lbTeSA3xnb}n zR|xOejE_|Kc7<-|G?-cTUVI~uWsT?c0d5qco?bwUVv09P{B;7GPo{UB)zV6Ys^=`o zkn>7PxBC10?}vuQB0s?tWD`~K^L33A12q@|@zW+(GHe~Uw6>nx*iATN3!9;xFaZTT z2bo55?4p+KzQH{k%2S?A__SF}Yi?#|9~k>;COm+}-4q}9q<^w#^9k_VW10@2UV4#U z;2RBMWidTvN-`Vo;WvC%CX@Y*Z(4@Lzk5;J!R4IoU~tx15bTlog(+T9CNL5q5JL%@5HiFWN$Xx z+uQ5Xu0qc$-6F!-(oVY#@;5RbgtI~CBqE?sue(w?r)~ToH;mT7MM$msZ z;b`d|8`0GpqhZ_VY4Gj6;M%=fV!vHLo@e#OAG3Qp+<+X&a!RnCrbqbv6pn=U5S8BTqw5yD2l3O3!vq_&MwsA zo&LN9bDmg7?pf~Ny;l`9mzR|(431?_X&(%%6yHw-+8KN=@veGO52n<^_6>?{+&pXS zd+fV+@1~+`!Cp6p`CPMu&ys2^ZHeShm&v8@;`tZfh7uAI0)h9<>U4zJ>W{eJa0Lw@ zbJ!Vbk-{n4uljylCMPGiwJ4r!z@{4HiBm8TrCo|?FpQ;a%5n9UdNFQ6BGb*S(LE5!T)p-eFCzVD{j_0}lgNFuXy4jza8_a0rGol)`3?2c?`? z{IZAreaS|;vNxan0OYhd+N6#w^@K-LDYWI&$rD&gvblX z^Z-Z7`9;s(K9d;P&5IioOA+*83VWL8~=Z&#^`Uo&K4lB8?dDC+Ai zxLzV{cK676&=<@O?Kwx!&`fD{!FgGD`|R|B>(n2?fRH51W)cf%n_reS1N%*O%q3wnB%QC9C(OWP_!4bU-kR46%SaF2G6hUv}N@5Jnc z-&+P&al5UzlF<8A{dge#q030|r+xXa%V<}`3|nHr&oPL=LfmE{>rQ#146Q0ZfcaSu!ow-rMu#`6yPUoi@#s-JZu%>TiV{*% z)KN&%uUV4`_a7|Incv*!>YLm-@vep`kENl`(#_ts9Kdg(Rg1`Fr6HMWXmN6ZKnNi# z^|9-4E-wBTRIP&trceNfNRIovM$Be$oY9hk4>RI`fp5p8w}sy}A>}MA;#Y(GR>MX?a;u)=N%ub&46bKCi;&6_qM3+*^GJonU+G=HY2H~qv-kg z@nh>J8pvRADMq*F}VJXa<4-#otIePTE zuE*@v6nj)06O~)AxmGFHv`4vH#$7u2$PR7DiO_w;^EQQe)4D_O*?#L>)S|Fi4pGiv zW5jO0+y>w@(Xsik<90|08M-9PB)#JHXKlFL$?TQ|FnpdJzRGFezJ#}0k6@)lr1=!i z^(WehatsTn6ffpUQw9$WeM?t-rWn$MLOuh9(&=dFwr44jZ}s8?nSRJqT!@FAa)fW( zg-_eIN=UcI6v8~*`o3w+!}q(IztyB!H5a+(cWCj_P>QrPH4{$m%azAA&-Dqa$)uC} z3svF4o`WKC5{EubfzA=vNp)0O^~w^b@n}tGw8x#{Mun^lwSs1jRZKPRW82x2!Ps*Cb!%{I?K`h1pz)w$s(Sqjsx(~22`Z{rXF(b*uro$bARdR z!lwbGrWU)~zZccBdP~c-fRgk5K)4UqopjtIhAAh_j~!wytsU((I!~o98yEzkPkXog z62xou*2jfZB=HiN0@3O6hvSozr{*pse=`%t@{(*O)`0Z%&yC@x`I!E5z=Y;mB_W6p1k{hco4M!c_CURy zai99W!^v=Z7)FN>*WI+my-jHHl zO1HQW$6K9*=kRNnR2~j-s4J#SvPY8Sk8X)f(c5(L;ITl~AJ#1a*c>{H@-c6x*&rIN z(1ghZvNtl@IvFQ(H{330S0k2^dK5}5xUkhqhK`CQKVIN44almts{PHv!eXTDKG{gr z0p_iC^{0;^qbLZtM8}9jk)fzlZ;W3-^EwD4=-?nlU!5FoRR0K>F#P-MbH<%rHQ*N@?PPSWlFJ zfJSP`z{w6-&2v`k6Wq5Pv(l?|d@rgcusM2~u4CHAK&hOFQM8kMOVj`mo26(;9zJ}S z6?B8HH8V3a>qx;wFeVF}VZ~0IJys#JShw&ZGljy86xCV-N-2ZH=fu+|huex$R4}2; zV-B@{*3W>Szskq&$T5sHmy?Ht@LUoRSRoDwgm}wvFEVA~%?nS2eL${%?LDU_U-gUQ zV*4=;sjqGkKXbsaD&i{M{y z{HUuzs6jz9&;=q&gKNmmovP5X?j&E=UyElm+)2qbEoK?rYbI5KO^swKnt7OMSD{xg zM@=Wy+|<~ZTk|YzGsmFTs~sN*MPWhnCT8ZDf=!i0ddYryGJ4tPpjb>-_hj%Z9VqO3 z>cc?)0r6jkE*Ua-(?QT>HB>^>@%j0E)=><(wo;(fdDqfg5Dd!px&R;Wm#hz|Ey+>5`lb3T9l3BF}#Lw zl~6WYS5#j@P^1$rcTbdUFz^S-IRFj~Xe|fRK3_R_4JnJ#U0cL#o|7{c;8A&8EjjU7 zm{T#;V~NsXIzKZOA#5H&SP~XcteO}bkG3olI~q2P7-;nPckVoP&UpO9@)lJ}fKrgM zI|)bt%KZ(eo(ZHL;$4A<}g815B<@-L(UOrJQOC&@74 zFrKTAUhFSq4DbZwl(ZwZ?{H8EPOPog-@G%bSqHj4E zsFnyhLdezA?e%-76yWOn(6wv`gCwgkvc~%NAHOrIy$O zUkQ1+ro?$SKP+eBA;5?QQWYsuQ)uxabjPp(3M;!}!w|q>k8P{Pq-(hU0S}wI0US0! z50^-sU0sXWp^`;TmTv$ZMNdmiT?GyYN{ve9E5~7Dl@iz65vO)8^quki0?c^O)*UTA zQ7$2wrymzs&BP>uh|J3y3E&6}ZY8&iUyj0v;6B^gqMF?2Pe-Dgxhx7N)i|BLdwY14u>@=r8hWdkaFu&LEppFVxMcEr=0 zogjBH@DVc$OPobp-nGg*+oU}w+n*;Dhk>0)NJ_fk=2p-lOj+b94F|uYghY53L=RRTt;Lc5F;q3cx=R(rC}?cm@k4Tldq!ZZ3< zqLQEVo=It;xpzf8&a;sGb3AWGCPHw&vgw+XpGhft-5fTR+mNJj zE`TyRX&O~1_aoj4yU)_kZdlH|V&^kU#(r3k1u9+A>61UMi zR}pBdUf=4Ri3rlYni-V_7qzvc0F?ilJlPD}8O>lK`j0mn0$h44o0^(TkReNDbd8Qy zub8!Un(TRc>d6W*R@_}RwXn~I=@qN`krwNM15>LY1Pa1zeqlZ0Mxu#2aAm>1d(5w2 z`}U2A*blqoqGAz*WQ_hj0^l}b05kuZdITFO8Sk{P$o~S3t!9q1Wv9 znl6+I?3O6b`X#CfJFE&pETz|vC@LxrAR%ayUzCssETLZdtJW#B46lXDK^`sPa0Nm4 zWtfupNx`Y$ksTBi)QGN>`}blbw!HxmDCUz>p})aEDMAmFQxUGuImX8L9QE?Tfvhk( z`}ra3eVrr&nh7@&85Id%)$q_VMGl&5_8K1`Q;MhK3d*cPUDHBDD9SG^~nLx{V}BNqb1z z3sIEz(w0g~B^s3K|GvUGopYY&`Tc&c|NU}s(zx&MeSNR%^Lek&dIP-+BKJ#<4Rk*V zWU?*Wqx)(;N}Dn4bF)XtQLOJHasbJ@L+X>@$$Ei;F4-D?te~!zSIXhjyVhh=V9fPd zXKjuoK2;{nqr{jY;cxm+;hQj$dcnDAR3=1h@<@=JpQY|6(y{ASzQ8!ceP9&`>(W>> zQW62)mQV||bnF;!UbRY1yEXA`t0k#jbjQU}KsT_QTa0gL)c)E}6x50xI`^KeuO(m4 z?hXWUhrDGY-J;RS(5-)N`+F8Jwqtc&yo#t+nyXW}3dql_Lc$_Xiflz3F|PF)`9Gj8orno7a^q zd1d(}I6)<0ET!1ak|->WDYe}M$h$^BsYMh36Ji!JB8I(%bT`*#frR)1kA5XI5nBi zu9Pow{g_V#|7SbN8kDg{6Jx{u1*j}DdZJ^Lm6R$>U4fn-lu)42z55Zq*d)2}S zhrVd@y|VhxT4vB6lZy_3iWk0jBeXRHjuC`((t92M0kj3Wm**jM#a3vSH1V{+ zMC{#Y@Im2JQGHV$hQe?AoZ~OCC8SoN&y6O?uE|;Gnun1s+yj8cbYuX0o4-@$?|0r` z*D}SuZj{qhz!Mz~bpVoFWFp%3LF9etY z=sFYfE;>EK;pU;68*1n+!*UifzWoHLLd?f4Kfe%=r?2w!qp=|(Iyt#E;qw7+##J@W zOPEEK5%cv`eHYeKkX8OVEXW%i%*de3fDn~)f4=a7<(~$nGr&m_!k#5JBQ7SU5_>{C ze~IwE(@7eDXUkB?SA#%xW2KX=!0-V99Pz|-n*A30Ag)tYQmI6YzOT3{3W}{;wv<5{ zk!;tinvHA2h)F&&lF*?J_l%Pk(q;0y!EjeO`NpX79RbdB2r3jyShpXkE&YJ^s9Pj6qIJ($0K3>t!_B0!Cg5FFNxYOi|M0;UbcKFsQkmwt3-XLLcA#RjpGVq`@ORCC9g6L%`S19I9<5TUX1Btt+3k$A)v|*=$af zWkUpe=*+;7P{HxuFPl)?JFFSJG<`Ounjg$o~E@kY!*Vvb5E3M+gGs8t!k>0^Bn(nTqI!(cVr_LsdAzm;ZS1iKOq} zHYZ_z<(H)W98u!O4Xip6DkG#3ZH z5PW>?Ndr=@q)C^N#K%7y+u$DGl{pm~8~b3y33>L6_LG(wy^($EZXGr@JOz>he^X=R}&bBS`{B$ z5J=(dL)E(9a$7y!`czqIE(iP0o#mLzky9#xJyiO|x6AC3Y1-S{$PQF(^JG*HWmO{T z`3Iw}sH>fZ1 zfBD$Kd~4{v_VkUq&7t3c1#q`-4VWF*pUjQ}QDlMs9|pu94LWvKgXXr?WUC@Xacx4X zRxh^T8d4v^%Inrgq!47s1L({eRkw(D+HlEoTsDmgf?CkKb<~TJU0#B^$OrYxP>yrb2zM%dq zShJ#0@qWuPIIF9BpRh8(tdrAnYh(`|EQ<(si6-(ZqEM-glNqrC<=aD~2q@bc#8Z5h z6;5Nmi#lInmn8H&7g+9Nnb>3|T9>+(!FYY^#*MaQ2@w$u?8%kTSsY%1@CFM>R7Dvd zu5uH~Afaxy=nDiwBopxq3L??&up28^tXT2b8NK~92m@YL6azw?Qx^R`4MA~C-_IZN^oW?PwcI~c=)dFow&>F5@b zAs>UnRSAPNSyR$4(yP~ziYTA8(1ug_thn}1aJNAZNfXip6FT6-)SbMYhetjkd*p6^ z?vx7zJdSaP<>k#rCjp-cf_TdwuF(<&U=}ETAE6}1A6{Nz+<8Je$xQ15O>TQRl181I z70fMAlV`NLlX;z?6Fn_X*d96#xtCuEJTQymw*C1IIwD`vEh_M3P5AWb)Ac?BpoyA^ zCoW@~L%kk>iihBI*vpP$c}^&-(uVYhpv?Lj@QG@QnLUKC28lvXZ8{am849Nz7NYfl z19UPjsY~oz%<5{J!LX6G8XAE}+}Lf+XC0X?L zT9u6Tuw!!rmZag8ss~^LYD1og$|wvsV@6VDKkwq)u^#S(adlr*FAJC~rJlKf2YU#7 zj2zGC<#7fdMck7B;x0}v*5n|nV$E#FWI_d)w=qDmhx~(4-9DY|{=l1}LCNe_h&T#y zRymr&&0eqAsAKqqPAiM!QG*hlPOe5}HHnQ{=rYJ>L*a*FR~8AeJvDKGNMNrbvxz0Y znO?!$Ed$HP7j=91F^TTdOvTmD5e=(9TSpdwQ?dE0C@Fb1dM&mWITOfu0Cp_2NAOaOHwR39+>3}E;Zh@>3MkaWQ5Lk_59 zLp^Mvjzs)$ThHp%DjvuC=!1rF9cuLhK#UUVQ|0yYtF_;9E;vsaRWNkc0A`9oe2LSx z^&-|MlWI@Jc^8|f_5x=!*_DD~0b;m3eGS~?B@*MNzNhf4tH9BV--g~&eRGhlQs&Ft z)FZ*%A#Z!fAvhh``ozflqi$-*TBz<SD#=$;&^}i4^*4v;kLa40BAMJcV%7OewzuDMO`*2Hv!Fs>>Goqv1{A3 z)^hrD%O0J>@h6HF_f)c`ASPmy>J3^*0?WZ9lWqQ-jfxg2izr=!Q z{%Z2G-k`k$u`IE8_Q)>q^@K4fUcCT#7yj{J0ne&mpGeV>CD=5oRCG0CX8K@lv03*b zrl1DL%T4eY$0wi-uwC7#gg>SqWt{8WLjaZ-Vq1XhPDx(g8^(NSh981&IRtIz@jhrr zH&pyXj-CJ4&&0R+f7Q$XKZ)&&8T%>A&N9(^*!MSbQGePH6o_c}*TZe|X_y>v%Wmc6 zJq+Hb|HVvY|49Df+Vl49wxYiTS{mDK|J(O)B`HJuR*{6Yq=MKFCXEkAU#wm#_1n4u z*Fu>OcqMcc>=Bjg`j1dHu=#DC^-R*5gEIHP470*Q=F`7T1Mp+KjM&ogjr*rLqOA3= zwLqRUF&{i&*4VZhJAlm;E9LXW877Pwt`SSQc|SjG(bYI(F9gnl;7U0U_T|e(qfUr!LAR#yc!Fc@y(9`rguciNg8h=&jg1~x))Oa1F(S415xkVrlQbR+XEz*QYpuQ*MPWt`0yYKm)#Y}cpiliK{ zMY3=YqCJ#x!`uoAii551`hW>^nqV{np{*uQ8H!suD75`J2zWsHRs?0o0}xjs_-=`C z+qLTjzrOc_j#%otLgCImzT_iPYEt+~WXLM>6IN()wanA^yC2_zT?xgPqP=~J)5L>4 z7X_R~Ovye;gcC3h3m^*viB6N@jc0Pg#J@)BKTcW$b$4@5J zyBF*vTFO$+=UZfCQr@2Jm-8kjipWZoUCS=|y91LgkpN}%dEyA7~(APlC3dj)0 z;BbREkaE1MpWn^*i-Le2f?6!BeQEns^e=s{Jb_*SRzFFQaS-ow4$z!*(z&c{0%4>S8Ka?DvLo zRlX+$*F*r8rc3kZEnql_T7?#dqF=BfB}yJgJ6#@PB#Z}Lp!?KpOo5j1VMdYZt|H^) z!X0#Vef9|>ii+M-*CA}xy;6@4;-9*03%ik4`11{M8Bd;mS0GjanZ(iy^B#Ud0*Jk- z)Fsg8k@%QdzdAF$N5RhI+O@lCEh-bodW2{NWoo&8V(vj5Kg>mIQtr1r_t_{C`d#0< z{cEOp{t;T~o!1P_6EybM3`!@1Tl|FGgT!Ut_1TZM9Td%d!_ZtH>$5@TQxk731G7In z>a6jW#&*w-zJj#UfrCtW$80WTpY*yKF|kLfZQTCjs;TQd*{N!|?F-}CN5pGJ#BxU` zv}sHX+PT^?*V*s(3N0_V-n(!>e^|(!hAlCBM9$~4Sk3KwEvnplLJoHKW-)~3xQPz0d{dYoFFi4#X zWL|P|GWOw7^))D4;PHYoKB)z2eQb7+k;TNvm+0$QTR%bHfIB$?<%_Q!pg_pRX<@(| z6HeZ}b&C@?L}8&U{@p274#XBd9j_Y)w|EV{3$R}~8fw?9JOI(jQey0ft+jQgONSaqY$R8>L2hoeRR9pnhWlpMu` z;7$i{ejt9%-EVR7J&tOzcE1XkTp}eVOH5JDMjARC@Fy%K!<0zV>T|_JvoN$}cgMN5<&M2s6<;WQLdSCm-b!6L}H&t#8;U zwPCt?;x5U)##HXv>v@3Lj~#lTED3)O8G#R?p$sA)gmiYwSTdIj=U^r12Fuad8Ry+# z*Zi{2_*2WF`Cl(TmBkB0CSusH!pf|_wA(ggMLl552P8E8*fZJSAWCM z?wLK_AsVW0APmQ@D*5K`-SCwQ!&{DgTzFd8Py;v98CDagpcVka{Y-UFul>gx%sx{G zWjVx&qu+1~ww{fBYw33T!TSfd_Uc$}5LDfWFYdX5vi@@)Oz4wV~%vWn}n^O)zqKk&Qk zA&ylSe%QjO-l+obMkj@xVxpp~T2_Y`t(V?}bp*Y=lYHhJis66R+{pm}&ceS+*t_V$ zyv09Kh_1A0(PQ%EI1+n$j1!!ODHO&T`}tqKPf|;;y*}F+)Hyi?)D9;Qu$X_HKwVPM z>s69E25e7oFACTgFx67DAt=X;2pM7qt!o5?g9mAtY>+@$G`(lP&ak^3(Fv-*t7Lbg%8DUq4&3C^16)6{~o=%RPRh ztD$@!^8PgI8lH#XxYyV9$HP)P5b9+}{}H=QFko1*_Qs6d3Ji=vhDFbX#oNmuTOERY zq!)PVs9`1a;iM^m9Mm9Yh9N_o4k+bub!A=*NU)&|w|4%20G`3QtUT&OWg#Ob;y-YOg z0_s~!VP$RYZ60|H|N9mFy2j*>|5H~&8Vg9%-<+hqI^p-`alwz#q;2dBAQmjLC%n2=k_zjsvSXj#rt?^oHaeCiaZg*xT^f*IS{pDoh)verM_ z^|JXNyM$jY5iW1riC15?YT9u)eI3k>$rmbrOm`*kBG!xtoaWOX|M}ar6}#`X=`L=7 z`=|MN1u35|&)9)yG;4Q&sJ~#I%O(eu0R<)p_51hlg~i27Y^4ACc5Vmv)zMGCZ%yWF z?8GVWXKuqYo_EN5ilGc{4X{(FM*qXx>r`iN<~s4mXmGZvQ`)}0YyJ!xP@guKPX9#P z)9#hqo!+SaYDu2a{oP{z*J?03c12FH(8}LQ48B83#_T`PPM+oqc)>iIA}uiEuJ&Ac z``gM#Os@OW@+e~0*{3rOmN9Mu6JWWZyxoJ<<%o`s&cSgpAeNxQS5!!hI{fRV{|!6f z2eHXZ7h7W9)m%vM1jC%oo3k{sokr=6g8#Z+6k9t6j1A)u7uP`~j=VEOIgkxp-op04 z4kaOW>YKN3Z^GH#Z%Ntk;rf4U%7Z+&39Ey42sGd%gBM>L$WbnwTI-H4XX`5Aq%2dM zao^5JVNj5scI=X;B4tp1By0cf$+M5ftxCeUt`>GN=eXhHZuH9)=Pe*J1ObSyT)%$3 zBEp>hdK|_xM+o0j&ri^r{P{R@HS)roW3Kwin$W*(in-;_NclE1@xbrp-J2oTY*>cQ z&|O;b`!@OSd+3ZG$mT85IO`G(8v@CfSnC!zeRn*%r(p2Eda#k03m2g|dVM;{2=EzJ z+V!e$?kGN=uU}31w&y?hZTOm*2us;c(#ZXKi1O!^Zy4`q?k`BGVhV^=#O;oM=~|16 z@fdVwUEheR#ek*o-nC19eStt}j+2M|kFT<$ZTF~0SKcb$eQp+cRm>crf6x=#I9VNy z$0-~2vBRK*O$x~Lr?~OX*d+ggV)kyv*SJl1R~w@acEl=m^W6WRUjke7dvfyCXV}F6 zwGVxMalwM@36S5&qj+KONoUBMw*!C*HnmgaKA@*aGtImYIPls!4&D7QxOU-YG@Jwl zn*Py5pmVC|wh;{VqL9#DY?j!%HJUkewq~h$Dx^a?Xe-)(%%!l-SaNK%JF$vnNzH8N zH;0-ZvIcM`M}q@!*~f#wE*1GhY6Gq$tV5d*hQ6QiVYh>86jPNEj$MIKX$00sOM}jQ zLGlDNsoPL*LA+ys^$5B-%@orBoaDG`iK&&@>LmkT;6A-fMO5S%^aV$nGz}e6JZ7#U zw2Qla94?06j}7Eq+(1>+w%Q+)YF4^;PTr0oWODWR$*?E_h%LxKN7Rejs~QG}4L9CY zeRPI=T`gm3a(oyF4#YxDzU!sSN#Qv3s^X9Y|pJ_CqGlv z{ml+K_QpN7^ASE=kvloeOH~4SqafTm7a#!<9KwA=3nOYfI91ImT_y*8UAvGws!~~5 zfoh1LPaw#Fh?Il9;K0aIDiLbLL$$rDuhbvD6V!B68sK^qRqMYv+pcmy{(1*pz@hN# zD<4vxO}fw6<&ldrxVrCK=dJz%ksIM#wmx+DHhZuCpL_15NeRk$NUg3@v5x5uKqW-M z2yb@poJk@xf{XbM#C;B?xE%v!plQn*aL#P99;h}%D7%&V^!qupwYH+ zaso1%HZcLd*=K#tkQJ}sbW(s2_kV>8k64xwqa~4L(ZYy13jI|0hc?$hdLG0nKyOwF zoeu}q5&VG4(W8~o&d?tmh5mvT2FYeG?A$}f{3z}wFth45hoFD}srt;SbINx9Y`>u! z%=_P<5&!AZ`yk8gskF&&1(I8L?W&0(<~$M`KvhE947q)Ev@>y@O-zA`3~RBMVYa(D zK2=m$sF}=bivv_yPmi}>dp0HKZ#Be~!mhaH8@bj~R=ek2TK{`j1WLs}vYiDm9RH7$ z_57!=jZbOq?gcG1r*Vq4OLY;5y07WKw;8h3m@i+rc=`vpS6Udxc7sqUwaA1gP73WI zjV%5YV?C%1?FQPQ5U?$ceVmG3ndCyy!iY)&npETJoarU|^EboA=odU~QKnz#7zXQ6 zmjc#H32BTq33@Hj&N#b`V6tbFbjg|)Y=CQkiOaV1#AEX&QKAeWigDEUL(l+h5fv5f znt%mjuC^Xz!O`Dl?CUy^r4}Rh)|Z2elk-ts3ix$e7~qCDD{FPC8PE%Wz2k{>rne!jJHD1cU40Kj zLpiASnN7VpLeO>Ko&iq=|B-$W3ghC_UmFsNPs2h(%WJ(})bT~#AW{8fqB=H56y)bd z8f>@qm0LW}zeOTW0Bnp-Hki-__NI2LI}fjaqu&+Na*!pj#M(uO*+lDpV9m8Zk+1Ch z9f(b2KiuEID{_IUTss%QS38iY4pFvmOs%$}x2|8`fbK={A5D3i^`**g+o{0JMffU) zL%Hpq6T4+T#c}J(fb35w<$S~Nd{_>EnLw=thtI}Zz-K)cbUdrQmM>pEjZvIoF_9}7 zsBzJ|GO@rwiUI(k|56z(U@oAUrYXInM<0SJe=wR3aih+;!B<4T#X-fa4Dvn!D}#b{dLXShVK}ZHUTjbH$s7%jH~q8PU&kz*&8oJib)m=+r3X&-KR^7HW#;t<;b!O@18Sy>YR zHU;Y&@&!}@E~k=ps}LgD_(=cV+)4q zcCJ0Je?J#L|4|y=cL8@u;uS#_6~O-liz_F=eDMcMFJwLAKX|rpA94J@!Ntfc(K%AZ zfei|b-Hpobp|i2_rQQiU56R0Dr8O?fQ|M`dgLS61JJCTvwH?qKVlPMv2GF)V9CXA< z5Zf^R0~p;PV;+1(xb?n^<*r!19C-;JzW!)-qLY)8%ibOh_c;-a+t9sX@YY0FZ*;V> zhDLW{JoiUW;Az%#MfNTi30))-%23PT4P>ziVP*@hFG>3t?)5QzX(#;a^`rXluHo1O$uQp|>-C$?5VlIzlw|iJZ1AgQ89O5kG)Kr z@GUmUK)qUQBA&7OMxsUdg+LUxYV(-kWYK(lY|pb1MAw!<`^FWOIGgL;Rg5@Z&V07r zj}$DRqXqQy>4G5qVlm4BNlv=)t$?aP!-9qXpm3L`nx?fCaifQ5Pp#Sxj0VO@b3RCL znZq2@WUhv{jJz~{7HR8MS{y#d)nev`X{MQUc*ZO7Fd5Rp@CwdZ?6iAbsva&#Xu1o# z6)snEL7|=WXOR~j*5rMLf3n|fV){lq=;!Pr1Ke$dDRDIMK*jeazv)lP$sz7q0uiYE zzO(!2L|*7V+5f6?as!o*ZeM`fk9{da&ALFo(|q2IsyFohh=-vVevyJsTD#}_u@2GS z`vQU6Vsdv1(Cq`nidy^2-vPCCcsd}LYl!LuRP_SWaT4f3BE@j_sJ+sYBhGk2N^ww; zrjb}8+Pf{d55DRcmEpkH`Mi^L1WB4W1(;~Fx>0{IqKz%?^$<{ z6Su(}YM*{Kw{WvxC(9*|Hz#iJWc!boo=m*Fn*$$xuu^s=qga#xS8R$jUume*RP-V zBJXz1K5-XGQe)%6Y@Qp?`hZC4$XH7vI#AQGyM-lDU)6%Lt#N7!c8qUkqxd~-z?sjw z{k3Wz5veKZ5AL-An94x~WgJ%znbMyRv&5E_Oj(E_!oofeQv`dH%XlBrB@_QGhI;Cl z^*A)9S@k=mWbd}-Ji~&BBeT0_0}+5l0`lP363EW4jS>{2Z84V z?MEm~oG&~W-gzE1T>gL=Jq#|enAn2=5n-ZF7)EIbL3brIS{tackW1`eqZ5WE2C8@> zRv@VaO{v-#(jF@@`At8dI3y_Y!pxpc%4UnOVF*YC!WBB=bvnnhB48z)`zk8+v0C2OT;^L}_$^^n?Zb?Z!+~NR) z2t9oIbT|=0!ja0&&i=4TzZ+5Zs9w4Dgac)aENF4L!_})NJtGbBe)rffCpVvibV^Kh({!) zhQ#@h$nz%XaF1WZhywDEQq%YGIojy9LY##>d7VAdtC+};FC9}$BBVoqLxfjRaP9^7 zp@AEQp{)l-`^q2RzuI9s`gADV_@|`Z!q(H@4&ULHAlK1=&PkD98$b!jZ-)L2cN=lx z96tsaOcUjhb}L~XkXH&n-9F;`({&zJf!ga3BHi_O%VfB6Z`p#;S@$`(@D5@I!Ev9+ zuh`@1Jpdi5Y`Veqzrfv(mJ1%IVy~2?u|S!
QSG)R$9ymDa+fL|L1q@3)%b1$6W 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 FKLAb(aTEXm literal 0 HcmV?d00001 diff --git a/docs/positioning.md b/docs/positioning.md new file mode 100644 index 0000000..1330579 --- /dev/null +++ b/docs/positioning.md @@ -0,0 +1,118 @@ +# Ecosystem Positioning & Autonomous Operando DFXM Guide + +`BraggTrack` occupies a distinct layer in the synchrotron X-ray diffraction software ecosystem: **object-centric 4D reciprocal-space tracking, chemomechanical fracture lineage (`1 -> 2+` splits & `2+ -> 1` merges), operando electrochemistry synchronization, and online causal "Scout-and-Zoom" target selection for autonomous Dark-Field X-ray Microscopy (DFXM)**. + +Rather than replacing upstream beamline acquisition engines (`BLISS`/`LIMA`, `Ewoks`) or downstream crystallographic unit-cell indexers (`ImageD11`, `HEXRD`, `GrainSpotter`) and DFXM pixel-moment mappers (`darfix`), `BraggTrack` bridges 3D reciprocal-space reflection series and grain-resolved chemomechanical failure dynamics. + +--- + +## 1. Software Ecosystem Comparison Matrix + +| Capability / Design Axis | **`BraggTrack` (`v0.4.0`)** | **`darfix`** *(Garriga Ferrer et al., 2023)* | **`ImageD11` / `GrainSpotter`** *(Wright, 2023; Schmidt, 2014)* | **`HEXRD`** *(Bernier et al., 2011)* | **`BraggNN`** *(Liu et al., 2022)* | **`TrackMate 7` / `LapTrack`** *(Ershov et al., 2022; Fukai & Kawaguchi, 2023)* | +| :--- | :--- | :--- | :--- | :--- | :--- | :--- | +| **Primary Scientific Domain** | Operando 4D reciprocal-space & near-field DFXM grain dynamics | Single-reflection real-space DFXM rocking/mosaicity mapping | Polycrystalline 3DXRD peak harvesting & grain orientation indexing | FF-HEDM / nf-HEDM orientation & elastic strain tensor fitting | Fast neural 2D Bragg peak sub-pixel localization | Live-cell bioimage particle & mitosis lineage tracking | +| **Input Representation** | Time-series of 3D $(\mu, \chi, d)$ or $(\omega, y, x)$ NeXus/HDF5 cubes (`LazyVolume`) | 3D/4D real-space DFXM detector stacks (`NXdata` `@signal`/`@axes`) | Thresholded 2D/3D diffraction peak tables (`.flt`) | Raw 2D detector frames + instrument geometry YAML | Small 2D detector patches around candidate peaks | 2D/3D fluorescence microscopy time-lapse stacks | +| **3D Reflection Segmentation** | Stabilised multi-scan chunked Otsu + 3D LoG + `h`-maxima watershed | Background subtraction, ROI cropping & pixel-wise Gaussian moments | Connected-component / threshold peak search | Omega-wedge peak extraction around virtual grain reflections | Patch-level CNN regression (requires upstream patch cropper) | LoG / DoG / StarDist / Cellpose cell detectors | +| **Foundation Vision Descriptors** | Batched 3-view orthogonal MIP `DINOv2` / `DINOv3` global & patch tokens | PCA / NMF blind source separation on rocking curves | None (scalar centroids & integrated intensities) | None | Supervised CNN latent features (2D patch only) | Hand-crafted cell morphology / CNN embeddings (2D) | +| **Multi-Scan Gap Closing & Lineage** | Jaqaman LAP gap closing + intensity-conserved `1 -> 2+` fracture splits & `2+ -> 1` merges | Per-scan static analysis (no cross-scan grain identity) | Per-scan grain indexing (post-hoc orientation matching required) | Per-scan grain fitting | Frame-by-frame localization only | Mitosis `1 -> 2` division (no Bragg intensity conservation or $d$-strain physics) | +| **Uncertainty & Ancestor Strain** | Analytical Poisson + quantization $\sigma_d, \sigma_\varepsilon$, `assignment_margin`, ancestor `lineage_strain` | Rocking-curve fit residuals | Peak centroid covariance | Least-squares strain tensor covariance | Sub-pixel regression spread | None (spatial pixel coordinates) | +| **Pre-Fracture Precursor Scoring** | Persistent 3D eigenvalue anisotropy, spread growth, 3D sub-peak bimodality & ViT patch dispersion | Per-pixel mosaicity & KAM maps (after high-res zoom) | None | Intragranular peak broadening (post-fit) | None | None | +| **Operando Stimulus Sync** | Native `CSV`/`TSV` & Biologic `.mpt` sync ($E(t), I(t), Q(t)$, regularized $\mathrm{d}Q/\mathrm{d}V$, $\partial\varepsilon/\partial V$) | External user scripting | External user scripting | External user scripting | None | None | +| **Autonomous Beamline Feedback** | Causal streaming (`braggtrack-watch`) + velocity-extrapolated BLISS `zoom_triggers.jsonl` | Offline / Ewoks batch post-processing of acquired DFXM zoom scans | Offline / batch indexing | Offline / HPC batch fitting | Edge-AI peak streaming (no grain lineage or zoom trigger) | Offline microscopy analysis | + +--- + +## 2. Upstream & Downstream Beamline Interoperability + +`BraggTrack` slots cleanly into ESRF ID03 / ID11 and general synchrotron HDF5 workflows without custom file conversion: + +```mermaid +flowchart LR + subgraph upstream["Upstream Beamline & DFXM Acquisition"] + BLISS["BLISS / LIMA HDF5 (/entry_0000/... + instrument/positioners)"] + DARFIX["darfix Processed NXdata (@default -> @signal + @axes)"] + EC["Potentiostat / Load Frame (.mpt, .csv, .tsv)"] + end + + subgraph bt["BraggTrack v0.4.0 Core & Streaming Engine"] + IO["braggtrack.io (Auto-Calibrated LazyVolume + Operando Stimulus Sync)"] + TRK["braggtrack.tracking (Stabilised 3D Watershed + Batched DINOv2 + Lineage & Precursors)"] + AUTO["braggtrack.autonomous (CausalStreamingTracker + Velocity-Extrapolated ZoomTriggerPolicy)"] + end + + subgraph downstream["Downstream Indexing, Visualization & Closed-Loop Control"] + FLT["ImageD11 Columnfile (.flt) -> GrainSpotter / ImageD11 Indexing"] + NXS["NeXus NXprocess (.nxs) -> Archival & Ewoks Pipelines"] + HTML["Offline Interactive 4D HTML Explorer + Operando dQ/dV Figures"] + ZOOM["zoom_triggers.jsonl (bliss_dfxm_zoom.v1) -> Autonomous High-Res DFXM Zoom"] + end + + BLISS --> IO + DARFIX --> IO + EC --> IO + IO --> TRK + IO --> AUTO + TRK --> FLT + TRK --> NXS + TRK --> HTML + AUTO --> ZOOM + ZOOM -. "Closed-Loop Motor Setpoint (mu, chi, 2theta)" .-> BLISS +``` + +### Interoperability Recipes + +1. **Zero-Config `darfix` & ESRF BLISS Motor Auto-Calibration (`braggtrack.io.nexus`):** + - `discover_primary_volume_path()` inspects NeXus `@default` entry and `NXdata` `@signal` attributes before falling back to explicit ESRF-ID03 LIMA paths or largest-3D numeric dataset discovery. + - `extract_axis_calibration()` automatically extracts physical $(\mu, \chi, d / 2\theta)$ coordinate origins and steps from `NXdata` `@axes` arrays (`darfix` exports) or ESRF BLISS `instrument/positioners/{mu, chi, obpitch, two_theta}` datasets. +2. **Downstream `ImageD11` Polycrystalline Indexing (`--export-imaged11`):** + - Supplying `--detector-json` maps 3D reflection centroids to transmission crystallographic coordinates $(2\theta, \eta, d, \mathbf{Q})$ and writes standard `ImageD11` `.flt` columnfiles annotated with `track_id` so orientation indexing preserves multi-scan fracture lineage. +3. **Operando Electrochemistry & Potentiostat Coupling (`--operando-log`):** + - Pass Biologic EC-Lab `.mpt` exports or `.csv`/`.tsv` cycling logs directly to `braggtrack-run` or `braggtrack-report` (`--operando-log cycling.mpt --operando-tz-offset 0.0`). `BraggTrack` interpolates $E(t)$, $I(t)$, $Q(t)$, regularized differential capacity $\mathrm{d}Q/\mathrm{d}V$, and electro-strain susceptibility $\partial\varepsilon/\partial V$ onto every grain observation. + +--- + +## 3. Autonomous "Scout-and-Zoom" Operando DFXM Workflow + +High-resolution 4D Dark-Field X-ray Microscopy (`darfix` $(\phi, \chi)$ rocking/mosaicity mapping with an X-ray objective lens) resolves intragranular dislocation walls and strain gradients at ~`50–100 nm` spatial resolution, but has a narrow field of view (single grain, ~`20–80 µm`) and requires minutes per 3D/4D scan. Conversely, wide-field reciprocal-space / near-field scouting monitors `50–200+` grains simultaneously across an electrode, but cannot resolve internal sub-grain microstructure until after catastrophic particle fracture (`1 -> 2+` split) has already occurred. + +`BraggTrack v0.4.0` closes this loop via **Scout-and-Zoom**: + +1. **Wide-Field Scouting (`CausalStreamingTracker`):** + - As each wide-field scouting scan finishes writing to disk, `CausalStreamingTracker.step()` computes a strictly causal trailing-window Otsu threshold (`window = 5` scans, zero lookahead), segments 3D reflections, runs batched `DINOv2` multi-view inference (`embed_batch`), updates incremental Hungarian associations and causal gap closures, and evaluates persistent pre-fracture precursors (`anisotropy`, `spread_growth`, `3D sub-peak bimodality`, and `DINOv2 patch dispersion`) using an $O(1)$-volume-RAM ROI cache. +2. **Velocity-Extrapolated Setpoint Prediction (`ZoomTriggerPolicy`):** + - During rapid electrochemical phase transitions—such as the `H2 -> H3` $c$-axis collapse in **Ni-rich layered oxide cathodes (`LiNi0.92Mn0.04Co0.04O2`, Ni92)** above `4.15 V vs. Li/Li+`—reflections shift rapidly along $d$ ($2\theta$) and rotate in $(\mu, \chi)$ while the diffractometer reconfigures from scouting optics to the DFXM objective lens. + - Instead of commanding stale centroids from scan $t$, `compute_target_geometry()` extrapolates causal velocities (`rate_mu`, `rate_chi`, `rate_d`) across the reconfiguration lead (`--lead-scans`) and sizes the zoom rocking window from $k_\sigma \sqrt{\mathrm{Var}_{\text{spot}} + (\sigma_{\text{pos}})^2}$: + $$\hat{\mathbf{x}}(t + \Delta s_{\text{lead}}) = \mathbf{x}(t) + \dot{\mathbf{x}}(t)\,\Delta s_{\text{lead}}$$ +3. **BLISS / Ewoks JSONL Trigger Stream (`zoom_triggers.jsonl`):** + - Triggered targets are appended atomically to `zoom_triggers.jsonl` using schema `bliss_dfxm_zoom.v1`, ready for consumption by an ESRF BLISS macro or Ewoks listener task. + +![Operando Electrochemistry + Autonomous DFXM Scout-and-Zoom](figures/operando_autonomous_zoom.png) + +### CLI Usage: Offline Ni92 Replay vs. Live Beamline Directory Watch + +**1. Offline Causal Replay & Baseline Policy Evaluation (Before Beamtime):** +Validate trigger precision, **Lead-Time Before Fracture** ($\Delta s_{\text{lead}} = s_{\text{split}} - s_{\text{trigger}}$), and setpoint hit rate on archival operando Ni92 datasets against naive policies (`brightest_intensity`, `strain_only`, `random`): + +```bash +braggtrack-watch path/to/ni92_scans \ + --mode replay \ + --outdir artifacts/ni92_replay \ + --operando-log path/to/ni92_echem.mpt \ + --zoom-budget 5 \ + --cooldown-scans 2 \ + --lead-scans 1.0 \ + --backend torch +``` + +**2. Live Beamline Directory Watcher (During Operando Beamtime):** +Watch an active experiment directory as BLISS writes `scan0001/`, `scan0002/`, ..., waiting for HDF5 write completion before causally stepping the tracker and emitting `zoom_triggers.jsonl`: + +```bash +braggtrack-watch /data/visitor/maXXXX/id03/sample_ni92 \ + --mode watch \ + --outdir artifacts/live_autonomous \ + --max-triggers-per-scan 1 \ + --cooldown-scans 3 \ + --lead-scans 1.0 \ + --max-scans 200 +``` diff --git a/paper.bib b/paper.bib index 6b37b89..5a8fda9 100644 --- a/paper.bib +++ b/paper.bib @@ -195,3 +195,86 @@ @article{Jaqaman2008 year = {2008}, doi = {10.1038/nmeth.1237} } + +@article{GarrigaFerrer2023, + author = {Garriga Ferrer, Julia and Rodr{\'i}guez-Lamas, Raquel and + Payno, Henri and De Nolf, Wout and Cook, Philip and + Sol{\'e} Jover, Vicente Armando and Yildirim, Can and + Detlefs, Carsten}, + title = {\textit{darfix} -- data analysis for dark-field {X}-ray + microscopy}, + journal = {Journal of Synchrotron Radiation}, + volume = {30}, + number = {3}, + pages = {527--537}, + year = {2023}, + doi = {10.1107/S1600577523001674} +} + +@article{Isern2025, + author = {Isern, Hector and Dufrane, T. and Brochard, Thierry and + Yildirim, Can and Detlefs, Carsten}, + title = {The {ESRF} dark-field x-ray microscope at {ID03}}, + journal = {Journal of Physics: Conference Series}, + volume = {3010}, + pages = {012163}, + year = {2025}, + doi = {10.1088/1742-6596/3010/1/012163} +} + +@article{Bernier2011, + author = {Bernier, Joel V. and Barton, Nathan R. and Lienert, Ulrich + and Miller, Matthew P.}, + title = {Far-field high-energy diffraction microscopy: a tool for + intergranular orientation and strain analysis}, + journal = {The Journal of Strain Analysis for Engineering Design}, + volume = {46}, + number = {7}, + pages = {527--547}, + year = {2011}, + doi = {10.1177/0309324711405761} +} + +@article{Liu2022, + author = {Liu, Zhengchun and Sharma, Hemant and Park, Jun-Sang and + Kenesei, Peter and Miceli, Antonino and Almer, Jonathan + and Kettimuthu, Rajkumar and Foster, Ian}, + title = {{BraggNN}: fast {X}-ray {Bragg} peak analysis using deep + learning}, + journal = {IUCrJ}, + volume = {9}, + number = {1}, + pages = {104--113}, + year = {2022}, + doi = {10.1107/S2052252521011258} +} + +@article{Fukai2023, + author = {Fukai, Yohsuke T. and Kawaguchi, Kyogo}, + title = {{LapTrack}: linear assignment particle tracking with + tunable metrics}, + journal = {Bioinformatics}, + volume = {39}, + number = {1}, + pages = {btac799}, + year = {2023}, + doi = {10.1093/bioinformatics/btac799} +} + +@article{Ershov2022, + author = {Ershov, Dmitry and Phan, Minh-Son and Pylv{\"a}n{\"a}inen, + Joanna W. and Rigaud, Stephane U. and Le Blanc, Laure and + Charles-Orszag, Arthur and Conway, James R. W. and + Laine, Romain F. and Roy, Nathan H. and Bonazzi, Daria and + Dum{\'e}nil, Guillaume and Jacquemet, Guillaume and + Tinevez, Jean-Yves}, + title = {{TrackMate} 7: integrating state-of-the-art segmentation + algorithms into tracking pipelines}, + journal = {Nature Methods}, + volume = {19}, + number = {7}, + pages = {829--832}, + year = {2022}, + doi = {10.1038/s41592-022-01507-1} +} + diff --git a/paper.md b/paper.md index 1c56e8d..e56699e 100644 --- a/paper.md +++ b/paper.md @@ -35,12 +35,17 @@ transient beam dropouts. In addition, BraggTrack ranks persistent pre-fracture precursor candidates across scans by combining 3D reflection anisotropy, covariance broadening, internal sub-peak bimodality, and frozen vision-transformer patch-token dispersion. Designed for synchrotron NeXus/HDF5 -data, BraggTrack supports lazy HDF5 ROI streaming, crystallographic -$(2\theta, \eta, d, |\mathbf{Q}|)$ conversion with direct `ImageD11` (`.flt`) -and NeXus `NXprocess` HDF5 export, publication plotting and offline interactive -HTML 4D lineage reports (`braggtrack-report`), bundled operando scans from ESRF -beamline ID03, nine CLI entry points culminating in `braggtrack-run`, and -interactive Jupyter notebooks runnable on Google Colab. +data, BraggTrack supports zero-configuration +`darfix` and ESRF BLISS motor auto-calibration, lazy HDF5 ROI streaming, +batched vision-transformer inference, analytical Poisson centroid/strain +uncertainties, operando electrochemistry synchronization (`--operando-log`), +crystallographic $(2\theta, \eta, d, |\mathbf{Q}|)$ conversion with direct +`ImageD11` (`.flt`) and NeXus `NXprocess` HDF5 export, publication plotting and +offline interactive HTML 4D lineage reports (`braggtrack-report`), causal +online streaming with velocity-extrapolated Dark-Field X-ray Microscopy (DFXM) +zoom triggering (`braggtrack-watch`), bundled operando scans from ESRF beamline +ID03, ten CLI entry points, and interactive Jupyter notebooks runnable on +Google Colab. # Statement of Need @@ -48,51 +53,67 @@ Operando diffraction experiments at modern synchrotron sources generate hundreds to thousands of three-dimensional diffraction volumes at sub-minute or sub-second cadence, each containing tens to hundreds of Bragg reflections whose positions, intensities, and 3D morphologies evolve during electrochemical -cycling, mechanical loading, or thermal treatment [@Simons2015; @Hayashi2019]. +cycling, mechanical loading, or thermal treatment [@Simons2015; @Hayashi2019; @Isern2025]. In battery electrodes such as Ni-rich layered oxides, chemomechanical degradation manifests first as anisotropic intragranular strain broadening and sub-domain formation before culminating in particle microcracking — observable in reciprocal space as reflection broadening followed by `1 -> 2+` peak splitting [@Finegan2017]. Quantifying per-grain lattice strain ($\varepsilon = \Delta d / d_0$), lattice rotation ($\Delta\mu$, $\Delta\chi$), -and fracture lineage across long scan sequences is essential for linking local -crystallography to macroscopic failure, as well as for solidification and -additive manufacturing studies [@Leung2018]. - -Existing workflows rely on frame-by-frame peak fitting, bespoke experiment -scripts, or crystallographic indexing packages such as GrainSpotter -[@Schmidt2014], 3DXRD orientation mappers [@Poulsen2004], and ImageD11 -[@Wright2023] that focus on unit-cell orientation indexing rather than tracking -evolving, splitting, and broadening 3D intensity distributions through time. -Previously, researchers lacked an open-source, `pip`-installable toolkit -combining stabilised 3D spot segmentation, foundation-model visual descriptors, -calibrated per-grain kinematics, explicit split/merge fracture lineage, and -beamline-ready crystallographic exports in a reproducible software architecture. +and fracture lineage across long scan sequences — and selecting pre-fracture +grains online for high-resolution DFXM zoom before catastrophic splitting — is +essential for linking local crystallography to macroscopic failure, as well as +for solidification and additive manufacturing studies [@Leung2018]. + +Existing diffraction and tracking packages address complementary parts of this +workflow: crystallographic indexing suites such as GrainSpotter [@Schmidt2014], +3DXRD orientation mappers [@Poulsen2004], HEXRD [@Bernier2011], and ImageD11 +[@Wright2023] determine unit-cell orientations and static grain tensors; deep +neural localizers such as BraggNN [@Liu2022] accelerate 2D sub-pixel peak +finding; DFXM analysis suites such as *darfix* [@GarrigaFerrer2023] map +pixel-wise rocking-curve moments once a single-grain zoom scan has been +acquired; and bioimage linear-assignment trackers such as TrackMate 7 +[@Ershov2022] and LapTrack [@Fukai2023] link cell trajectories without +reciprocal-space Bragg strain physics, integrated-intensity split conservation, +or synchrotron beamline metadata. Previously, researchers lacked an +open-source, `pip`-installable toolkit combining stabilised 3D spot +segmentation, foundation-model visual descriptors, calibrated per-grain +kinematics with analytical uncertainties, explicit split/merge fracture +lineage, operando potentiostat synchronization, and causal autonomous DFXM +target selection. BraggTrack addresses this need by separating beamline HDF5 ingestion and axis -calibration, 3D instance segmentation, multi-view vision-transformer encoding, -Hungarian and topological lineage tracking, fracture precursor scoring, and -interactive visualization (`braggtrack.viz`) into cleanly tested, modular -layers. +calibration, operando stimulus synchronization, 3D instance segmentation, +batched multi-view vision-transformer encoding, Hungarian and topological +lineage tracking, fracture precursor scoring, online causal streaming +(`braggtrack.autonomous`), and interactive visualization (`braggtrack.viz`) +into cleanly tested, modular layers. # Implementation -## Beamline ingestion, lazy HDF5 streaming, and crystallographic mapping +## Beamline ingestion, lazy HDF5 streaming, operando sync, and crystallographic mapping BraggTrack discovers sequential `scan*` directories, inspects NeXus/HDF5 trees -(including ESRF-ID03 LIMA detector hierarchies under `/entry_0000/...` and -generic HDF5 layouts via automatic largest-3D numeric dataset discovery), and -validates timestamp monotonicity. To handle gigabyte-scale detector stacks -without exhausting host memory, `LazyVolume` streams `z`-slabs for exact -two-pass global Otsu histogramming (`otsu_threshold_chunked`) and reads only -tight 3D spot bounding-box slices (`read_roi`) during semantic embedding and -precursor analysis. - -An `AxisCalibration` transform converts raw detector indices into physical -reciprocal-space coordinates $(\mu, \chi, d)$ while preserving integer voxel -bounding boxes for lossless 3D ROI cropping. Complementarily, -`DetectorGeometry` maps transmission-diffraction spot centroids into -crystallographic scattering angle $2\theta$, azimuth $\eta$, $d$-spacing +(including `NXdata` `@default`/`@signal` hierarchies exported by *darfix* +[@GarrigaFerrer2023], ESRF-ID03 LIMA detector hierarchies under `/entry_0000/...` +[@Isern2025], and generic HDF5 layouts via automatic largest-3D numeric dataset +discovery), and validates timestamp monotonicity. To handle gigabyte-scale +detector stacks without exhausting host memory, `LazyVolume` streams `z`-slabs +for exact two-pass global Otsu histogramming (`otsu_threshold_chunked`) and +reads only tight 3D spot bounding-box slices (`read_roi`) during semantic +embedding and precursor analysis. + +An `AxisCalibration` transform — supplied via JSON or auto-extracted from +NeXus `@axes` arrays and ESRF BLISS `instrument/positioners` metadata — converts +raw detector indices into physical reciprocal-space coordinates $(\mu, \chi, d)$ +while preserving integer voxel bounding boxes for lossless 3D ROI cropping. When +operando electrochemistry logs (`.csv`, `.tsv`, or Biologic EC-Lab `.mpt`) are +provided via `--operando-log`, `braggtrack.io.operando_log` synchronizes cell +potential $E(t)$, current $I(t)$, specific capacity $Q(t)$, regularized +differential capacity $\mathrm{d}Q/\mathrm{d}V$, and per-grain electro-strain +susceptibility $\partial\varepsilon/\partial V$ onto scan timestamps. +Complementarily, `DetectorGeometry` maps transmission-diffraction spot centroids +into crystallographic scattering angle $2\theta$, azimuth $\eta$, $d$-spacing ($\lambda = 2 d \sin\theta$), and reciprocal-lattice vectors $\mathbf{Q}$ ($\text{\AA}^{-1}$), exporting directly to `ImageD11` columnfiles (`.flt`) [@Wright2023] and self-describing NeXus `NXprocess` HDF5 archives (`.nxs`). @@ -117,34 +138,39 @@ BraggTrack's primary segmentation pipeline processes 3D volumes in four stages: 4. **Seeded watershed and basin refinement.** Watershed region growing [@Vincent1991] over the inverted LoG response is followed by small-object removal, 3D hole filling, and optional nearby-centroid merging to prevent - over-segmentation of mosaic reflections. An experimental dense patch-feature - + HDBSCAN slice-stitching segmenter (`segment_dino`) is also provided for - cross-method comparison. + over-segmentation of mosaic reflections, alongside analytical Poisson counting + plus voxel-quantization centroid standard errors. An experimental batched + dense patch-feature + HDBSCAN slice-stitching segmenter (`segment_dino`) is + also provided for cross-method comparison. -## Multi-view semantic descriptors +## Batched multi-view semantic descriptors Each segmented 3D reflection is cropped via `LazyVolume`, masked to its instance support, and projected into three orthogonal maximum-intensity projections -(MIPs) along $\mu$, $\chi$, and $d$. By default, BraggTrack encodes these views -using the public, ungated DINOv2 vision transformer (`facebook/dinov2-small`) -[@Oquab2024] into a concatenated $L_2$-normalised 1152-d descriptor, while also -supporting newer DINOv3 backbones (`facebook/dinov3-vitb16-pretrain-lvd1689m`) -via dynamic prefix/register token handling and a deterministic hash-based `mock` -encoder for zero-GPU continuous integration. +(MIPs) along $\mu$, $\chi$, and $d$. By default, BraggTrack batches all +$3 N_{\text{spots}}$ views per scan through the public, ungated DINOv2 vision +transformer (`facebook/dinov2-small`) [@Oquab2024] into a concatenated +$L_2$-normalised 1152-d descriptor (`embed_batch`), while also supporting newer +DINOv3 backbones (`facebook/dinov3-vitb16-pretrain-lvd1689m`) via dynamic +prefix/register token handling and a deterministic hash-based `mock` encoder for +zero-GPU continuous integration. ## Tracking, gap closing, kinematics, and chemomechanical fracture events Frame-to-frame 1-to-1 association solves the gated Hungarian assignment problem [@Kuhn1955] over $\alpha \cdot C_{\text{geo}}(i, j) + \beta \cdot (1 - -\cos(\mathbf{f}_i, \mathbf{f}_j))$, constructing a NetworkX [@Hagberg2008] -`DiGraph`. Prior to topological event detection, `resolve_track_gaps` solves an -augmented multi-scan linear assignment problem [@Jaqaman2008] with diffusive -displacement scaling ($\Delta r^2 / \Delta t$) and semantic cosine gating to -reconnect reflections across transient beam dropouts (`--max-gap`) while -severing spurious cross-detector jumps. From each trajectory, -`compute_grain_kinematics` extracts time-series strain $\Delta d / d_0$, -rocking/azimuthal misorientation, integrated intensity and volume evolution, and -3D eigenvalue anisotropy. +\cos(\mathbf{f}_i, \mathbf{f}_j))$, recording per-link assignment cost margins +(`assignment_margin` to the runner-up candidate) and constructing a NetworkX +[@Hagberg2008] `DiGraph`. Prior to topological event detection, +`resolve_track_gaps` solves an augmented multi-scan linear assignment problem +[@Jaqaman2008] with diffusive displacement scaling ($\Delta r^2 / \Delta t$) and +semantic cosine gating to reconnect reflections across transient beam dropouts +(`--max-gap`) while severing spurious cross-detector jumps. From each +trajectory, `compute_grain_kinematics` extracts local time-series strain +$\Delta d / d_0$, ancestor-referenced `lineage_strain` across fracture splits, +propagated strain uncertainty $\sigma_\varepsilon$, causal angular/lattice +velocities (`rate_mu`, `rate_chi`, `rate_d`, `strain_rate`), integrated +intensity and volume evolution, and 3D eigenvalue anisotropy. To capture grain fracture and coalescence, `resolve_splits_and_merges` augments remaining unmatched birth and termination nodes with explicit `1 -> 2+` split @@ -154,11 +180,28 @@ intensity share, assigning clean daughter track IDs so diverging post-fracture strains are tracked independently (\autoref{fig:lineage}). Complementarily, `compute_fracture_precursors` scores pre-split intragranular degradation across contiguous scans (`min_persistence`) using 3D eigenvalue anisotropy, covariance -trace growth, internal 3D sub-peak bimodality, and foreground DINO patch-token -cosine dispersion. +trace growth, internal 3D sub-peak bimodality, and batched foreground DINO +patch-token cosine dispersion. ![Four-dimensional chemomechanical fracture lineage, pre-split bimodal MIP evolution, persistent precursor decomposition (`facebook/dinov2-small`), and calibrated ESRF-ID03 Ni-rich cathode per-grain strain trajectories.\label{fig:lineage}](docs/figures/fracture_lineage_and_precursors.png) +## Causal streaming and autonomous "Scout-and-Zoom" DFXM targeting + +To support closed-loop synchrotron experiments [@Isern2025], +`braggtrack.autonomous` provides `CausalStreamingTracker` and the +`braggtrack-watch` CLI. Operating strictly without future-scan lookahead +(trailing-window Otsu threshold stabilisation and $O(1)$-volume-RAM cached ROI +precursors), `CausalStreamingTracker` evaluates active reflections as each +wide-field scouting scan completes and applies `ZoomTriggerPolicy` with +configurable zoom budgets and per-track cooldowns. Because reflections drift +rapidly during phase transitions while beamline optics reconfigure, target +motor setpoints $(\mu, \chi, 2\theta / d)$ are extrapolated forward by causal +angular and lattice velocities over the reconfiguration lead time +$\Delta t_{\text{lead}}$ and emitted as schema-validated `bliss_dfxm_zoom.v1` +JSONL commands (`zoom_triggers.jsonl`), accompanied by an offline causal replay +benchmark (`evaluate_causal_replay`) comparing precursor-guided selection +against intensity, strain-only, and random baselines. + ## Quantitative evaluation, visualization, and reproducibility Across controlled 4D benchmarks (`scripts/benchmark_suite.py`; @@ -171,9 +214,11 @@ $\approx 0$), eliminate crossing ID switches between reflections with identical ![Quantitative 4D diffraction benchmark suite comparing Geometry-Only, Mock-Hash, and Real `facebook/dinov2-small` across crossing tilted reflections, flux/mosaic noise invariance, and staggered beam-dropout recovery.\label{fig:benchmarks}](docs/figures/benchmark_comparison.png) -BraggTrack (`pip install braggtrack`) provides nine CLI commands, including -`braggtrack-report` (generating publication figures and a zero-CDN offline -interactive HTML 4D Lineage & Strain Explorer) and `braggtrack-run`, which +BraggTrack (`pip install braggtrack`) provides ten CLI commands, including +`braggtrack-report` (generating publication figures, 3-panel operando +electrochemistry $\mathrm{d}Q/\mathrm{d}V$ dashboards, and a zero-CDN offline +interactive HTML 4D Lineage & Strain Explorer), `braggtrack-watch` (live causal +streaming and offline autonomous DFXM replay), and `braggtrack-run`, which executes validation, segmentation, embedding, tracking, kinematics, event detection, reporting, and `ImageD11`/NeXus export while writing a `run_manifest.json` with SHA-256 input checksums and per-stage runtimes. diff --git a/pyproject.toml b/pyproject.toml index 128b6ae..507429d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "braggtrack" -version = "0.3.0" +version = "0.4.0" description = "Semantic 4D kinematics and fracture tracking for operando diffraction." readme = "README.md" requires-python = ">=3.10" @@ -61,6 +61,7 @@ braggtrack-embed-dataset = "braggtrack.cli.embed_dataset:main" braggtrack-events = "braggtrack.cli.detect_events:main" braggtrack-report = "braggtrack.cli.report_dataset:main" braggtrack-run = "braggtrack.cli.run_pipeline:main" +braggtrack-watch = "braggtrack.cli.watch_autonomous:main" [tool.setuptools.packages.find] include = ["braggtrack*"] diff --git a/tests/test_autonomous_zoom.py b/tests/test_autonomous_zoom.py new file mode 100644 index 0000000..c84b3a1 --- /dev/null +++ b/tests/test_autonomous_zoom.py @@ -0,0 +1,264 @@ +"""Unit tests for online causal streaming and autonomous DFXM Scout-and-Zoom.""" + +from __future__ import annotations + +import json +from pathlib import Path + +import h5py +import numpy as np +import pytest + +from braggtrack.autonomous import ( + CausalStreamingTracker, + ZoomTriggerPolicy, + evaluate_causal_replay, +) +from braggtrack.cli import watch_autonomous +from braggtrack.io import AxisCalibration, DetectorGeometry, ScanStimulusPoint + + +def _add_gaussian_spot( + vol: np.ndarray, + center_zyx: tuple[float, float, float], + sigma_zyx: tuple[float, float, float], + amplitude: float, +) -> None: + zz, yy, xx = np.meshgrid( + np.arange(vol.shape[0], dtype=np.float64), + np.arange(vol.shape[1], dtype=np.float64), + np.arange(vol.shape[2], dtype=np.float64), + indexing="ij", + ) + cz, cy, cx = center_zyx + sz, sy, sx = sigma_zyx + g = amplitude * np.exp(-0.5 * (((zz - cz) / sz) ** 2 + ((yy - cy) / sy) ** 2 + ((xx - cx) / sx) ** 2)) + vol += g + + +def _build_scout_and_zoom_sequence() -> tuple[list[np.ndarray], list[ScanStimulusPoint]]: + """Construct a 6-scan operando sequence with: + - Grain A (target): builds bimodal mosaicity across scans 1..3 while drifting fast + along d (-2.5 px/scan, mimicking Ni92 H2->H3 contraction) and fractures 1->2 at scan 4. + - Grain B (bright distractor): higher integrated intensity, spherical, never fractures. + - Grain C (high-strain distractor): shifts early so |strain| is larger at scan 1..2, + spherical, never fractures. + """ + shape = (24, 36, 36) + vols: list[np.ndarray] = [] + stimuli: list[ScanStimulusPoint] = [] + voltages = [3.95, 4.08, 4.16, 4.21, 4.24, 4.27] + dq_dvs = [40.0, 95.0, 260.0, 340.0, 180.0, 70.0] + + for t in range(6): + v = np.full(shape, 0.2, dtype=np.float64) + d_target = 25.0 - 2.0 * t + + # Target Grain A: spherical at t=0, strong anisotropic mosaicity broadening at t=1,2,3 + # (single LoG peak so watershed keeps it unified), then cleaves into 2 intensity-conserving + # daughter reflections at t=4,5! + if t == 0: + _add_gaussian_spot(v, (8.0, d_target, 12.0), (1.1, 1.1, 1.1), 220.0) + elif t in (1, 2, 3): + sx = 2.0 + 0.55 * t # progressive mosaicity elongation along chi + amp = 220.0 / (sx / 1.1) ** 0.35 # grows moderately while staying below Distractor B + _add_gaussian_spot(v, (8.0, d_target, 12.0), (1.1, 1.25, sx), amp) + else: + sep = 4.2 + 0.5 * (t - 4) + _add_gaussian_spot(v, (8.0, d_target, 12.0 - sep), (1.1, 1.2, 1.45), 185.0) + _add_gaussian_spot(v, (8.0, d_target, 12.0 + sep), (1.1, 1.2, 1.45), 175.0) + + # Distractor Grain B: brightest integrated intensity, completely spherical & stable + _add_gaussian_spot(v, (16.0, 10.0, 27.0), (1.35, 1.35, 1.35), 340.0) + + # Distractor Grain C: large static d-shift right after t=0, spherical & non-fracturing + d_c = 12.0 if t == 0 else 8.0 + _add_gaussian_spot(v, (16.0, d_c, 10.0), (1.2, 1.2, 1.2), 260.0) + + vols.append(v) + stimuli.append( + ScanStimulusPoint( + scan_idx=t, + scan_name=f"scan_{t + 1:04d}", + elapsed_s=float(t * 180.0), + timestamp=f"2026-05-01T10:{t * 3:02d}:00Z", + voltage_v=voltages[t], + current_ma=0.85, + capacity_mah_g=float(140.0 + 14.0 * t), + dq_dv=dq_dvs[t], + ) + ) + return vols, stimuli + + +def test_strict_causality_invariance() -> None: + """Processing scans 0..2 must produce bit-for-bit identical outputs whether future scans 3..5 exist or not.""" + vols, stimuli = _build_scout_and_zoom_sequence() + # Inject a massive future intensity spike in scan 3..5 that would corrupt any non-causal smoothing window + vols_spiked = [v.copy() for v in vols] + vols_spiked[3] = vols_spiked[3] * 12.0 + 50.0 + vols_spiked[4] = vols_spiked[4] * 15.0 + 80.0 + + policy = ZoomTriggerPolicy(min_precursor_score=0.30, min_persistence=2) + tracker_short = CausalStreamingTracker(backend="mock", smooth_window=5, trigger_policy=policy) + tracker_long = CausalStreamingTracker(backend="mock", smooth_window=5, trigger_policy=policy) + + steps_short = [tracker_short.step(vols[t], stimulus=stimuli[t]) for t in range(3)] + steps_long_prefix = [tracker_long.step(vols_spiked[t], stimulus=stimuli[t]) for t in range(3)] + + for s_a, s_b in zip(steps_short, steps_long_prefix, strict=True): + assert s_a.threshold_causal == pytest.approx(s_b.threshold_causal, abs=1e-12) + assert s_a.n_spots == s_b.n_spots + assert [t.to_bliss_command() for t in s_a.zoom_targets] == [t.to_bliss_command() for t in s_b.zoom_targets] + + +def test_velocity_extrapolated_setpoint_hits_fast_drifting_grain() -> None: + """On a fast-shifting H2->H3 reflection, velocity-extrapolated setpoint centers the t+1 spot whereas static lags.""" + shape = (20, 44, 28) + vols: list[np.ndarray] = [] + # Drift -6.0 voxels/scan along d (y-axis) so static centroid misses a tight 2.0-sigma window! + true_centers = [(10.0, 36.0 - 6.0 * t, 14.0) for t in range(4)] + for t, (cz, cy, cx) in enumerate(true_centers): + v = np.full(shape, 0.2, dtype=np.float64) + if t == 0: + _add_gaussian_spot(v, (cz, cy, cx), (1.0, 1.0, 1.0), 200.0) + else: + _add_gaussian_spot(v, (cz, cy, cx), (1.0, 1.1, 2.4 + 0.5 * t), 200.0) + vols.append(v) + + cal = AxisCalibration( + mu_origin=10.0, mu_step=0.02, chi_origin=-1.0, chi_step=0.05, d_origin=4.5, d_step=0.002, calibrated=True + ) + det = DetectorGeometry(distance_mm=150.0, wavelength_angstrom=0.2898) + # Use a tight window_sigma=2.0 so lagging by 5.5*0.002 = 0.011 A falls outside the static window! + policy = ZoomTriggerPolicy(min_precursor_score=0.28, min_persistence=2, lead_scans=1.0, window_sigma=2.0) + tracker = CausalStreamingTracker(backend="mock", calibration=cal, detector=det, trigger_policy=policy) + + step2 = None + for t in range(3): + step2 = tracker.step(vols[t], scan_name=f"scan_{t:02d}") + assert step2 is not None + assert len(step2.zoom_targets) == 1 + tgt = step2.zoom_targets[0] + + # Step 3 gives actual next-scan centroid in calibrated coordinates + tracker.step(vols[3], scan_name="scan_03") + next_obs = [r for r in tracker.track_table if int(r["scan_idx"]) == 3][0] + next_mu, next_chi, next_d = ( + float(next_obs["centroid_mu"]), + float(next_obs["centroid_chi"]), + float(next_obs["centroid_d"]), + ) + + # Extrapolated setpoint captures next scan; un-extrapolated current_centroid misses along d! + assert tgt.contains_point(next_mu, next_chi, next_d) is True + cur_d = tgt.current_centroid[2] + half_d = tgt.scan_half_widths[2] + assert abs(next_d - cur_d) > half_d + + bliss = tgt.to_bliss_command() + assert bliss["schema_version"] == "bliss_dfxm_zoom.v1" + assert "crystallographic_setpoint" in bliss + assert bliss["crystallographic_setpoint"]["two_theta_deg"] > 0.0 + + +def test_causal_replay_beats_naive_baselines_with_lead_time() -> None: + """Closed-loop replay captures fracturing lineage ahead of split while naive baselines pick distractors.""" + vols, stimuli = _build_scout_and_zoom_sequence() + cal = AxisCalibration( + mu_origin=0.0, mu_step=0.05, chi_origin=0.0, chi_step=0.05, d_origin=2.0, d_step=0.002, calibrated=True + ) + policy = ZoomTriggerPolicy(min_precursor_score=0.30, min_persistence=2, cooldown_scans=4, max_triggers_per_scan=1) + + res = evaluate_causal_replay( + vols, + stimuli=stimuli, + calibration=cal, + backend="mock", + trigger_policy=policy, + zoom_budget=1, + seed=123, + ) + + bt = res.policy_comparison["braggtrack_autonomous"] + bright = res.policy_comparison["brightest_intensity"] + strain_only = res.policy_comparison["strain_only"] + + assert bt.n_fracture_lineages_total >= 1 + assert bt.fracture_capture_recall == pytest.approx(1.0) + assert bt.fracture_capture_precision == pytest.approx(1.0) + assert bt.mean_lead_scans_before_split >= 1.0 + assert bt.mean_lead_voltage_mv is not None and bt.mean_lead_voltage_mv > 10.0 + assert bt.setpoint_hit_rate_next_scan == pytest.approx(1.0) + + # Under budget=1, brightest_intensity picks Grain B and strain_only picks Grain C (both non-fracturing!) + assert bright.fracture_capture_recall == pytest.approx(0.0) + assert strain_only.fracture_capture_recall == pytest.approx(0.0) + + +def test_watch_autonomous_cli_replay_and_watch_modes(tmp_path: Path) -> None: + """Verify braggtrack-watch CLI in both --mode replay and --mode watch.""" + vols, stimuli = _build_scout_and_zoom_sequence() + ds_root = tmp_path / "ni92_dataset" + for t, vol in enumerate(vols): + sdir = ds_root / f"scan_{t + 1:04d}" + sdir.mkdir(parents=True) + with h5py.File(sdir / "data.h5", "w") as fh: + eg = fh.create_group("entry") + eg.create_dataset("start_time", data=stimuli[t].timestamp) + dg = eg.create_group("data") + dg.create_dataset("data", data=vol.astype(np.float32)) + + echem_csv = tmp_path / "echem.csv" + lines = ["scan_idx,voltage_v,current_ma,capacity_mah_g,dq_dv"] + for sp in stimuli: + lines.append(f"{sp.scan_idx},{sp.voltage_v},{sp.current_ma},{sp.capacity_mah_g},{sp.dq_dv}") + echem_csv.write_text("\n".join(lines) + "\n", encoding="utf-8") + + out_replay = tmp_path / "out_replay" + rc = watch_autonomous.main( + [ + str(ds_root), + "--mode", + "replay", + "--backend", + "mock", + "--operando-log", + str(echem_csv), + "--min-precursor-score", + "0.30", + "--outdir", + str(out_replay), + ] + ) + assert rc == 0 + summary = json.loads((out_replay / "replay_summary.json").read_text(encoding="utf-8")) + assert summary["n_scans"] == 6 + assert summary["n_zoom_targets"] >= 1 + jsonl_lines = [ + json.loads(line) + for line in (out_replay / "zoom_triggers.jsonl").read_text(encoding="utf-8").splitlines() + if line.strip() + ] + assert len(jsonl_lines) == summary["n_zoom_targets"] + assert jsonl_lines[0]["operando_state"]["voltage_v"] == pytest.approx(4.16, abs=0.1) + + out_watch = tmp_path / "out_watch" + rc_w = watch_autonomous.main( + [ + str(ds_root), + "--mode", + "watch", + "--backend", + "mock", + "--max-scans", + "4", + "--min-precursor-score", + "0.30", + "--outdir", + str(out_watch), + ] + ) + assert rc_w == 0 + watch_steps = json.loads((out_watch / "autonomous_steps.json").read_text(encoding="utf-8")) + assert len(watch_steps) == 4 diff --git a/tests/test_ci_report.py b/tests/test_ci_report.py index e887d8a..1b1b30f 100644 --- a/tests/test_ci_report.py +++ b/tests/test_ci_report.py @@ -9,6 +9,7 @@ def test_ci_report_runs_and_reports_summary(self) -> None: env = os.environ.copy() env["PYTHONPATH"] = f".{os.pathsep}{env.get('PYTHONPATH', '')}" env["BRAGGTRACK_SKIP_TEST_MODULE"] = "test_ci_report" + env.setdefault("BRAGGTRACK_DINO_BACKEND", "mock") proc = subprocess.run( [sys.executable, "scripts/ci_report.py"], check=False, diff --git a/tests/test_dino_batching.py b/tests/test_dino_batching.py new file mode 100644 index 0000000..9ed8ce5 --- /dev/null +++ b/tests/test_dino_batching.py @@ -0,0 +1,67 @@ +"""Unit tests for batched DINOv2 multiview and patch-feature inference.""" + +from __future__ import annotations + +import numpy as np +import pytest + +from braggtrack.semantic.dino import make_multiview_encoder, make_patch_encoder + + +def _random_triplets(n: int = 7, seed: int = 42) -> list[tuple[np.ndarray, np.ndarray, np.ndarray]]: + rng = np.random.default_rng(seed) + triplets: list[tuple[np.ndarray, np.ndarray, np.ndarray]] = [] + for i in range(n): + h = 16 + 2 * (i % 3) + w = 18 + 2 * (i % 4) + triplets.append( + ( + rng.uniform(0.0, 100.0, size=(h, w)).astype(np.float32), + rng.uniform(0.0, 100.0, size=(h, w + 2)).astype(np.float32), + rng.uniform(0.0, 100.0, size=(h + 2, w)).astype(np.float32), + ) + ) + return triplets + + +def test_mock_multiview_and_patch_batch_parity() -> None: + triplets = _random_triplets(6) + enc = make_multiview_encoder("mock") + single = np.stack([enc.embed(a, b, c) for a, b, c in triplets], axis=0) + batched = enc.embed_batch(triplets, batch_size=2) + assert batched.shape == single.shape + np.testing.assert_allclose(batched, single, atol=1e-6) + assert enc.embed_batch([]).shape == (0, single.shape[1]) + + penc = make_patch_encoder("mock") + imgs = [t[0] for t in triplets] + p_single = [penc.extract_patch_features(img) for img in imgs] + p_batch = penc.extract_patch_features_batch(imgs, batch_size=3) + assert len(p_batch) == len(p_single) + for f_b, f_s in zip(p_batch, p_single, strict=True): + np.testing.assert_allclose(f_b, f_s, atol=1e-6) + + +def test_torch_dino_multiview_and_patch_batch_parity() -> None: + pytest.importorskip("torch") + pytest.importorskip("transformers") + + triplets = _random_triplets(5, seed=7) + try: + enc = make_multiview_encoder("torch", torch_device="cpu") + penc = make_patch_encoder("torch", torch_device="cpu") + except Exception as exc: # pragma: no cover - offline fallback if model cache missing + pytest.skip(f"DINO model unavailable in environment: {exc}") + + single = np.stack([enc.embed(a, b, c) for a, b, c in triplets], axis=0) + batched = enc.embed_batch(triplets, batch_size=2) + assert batched.shape == single.shape + np.testing.assert_allclose(batched, single, atol=1e-5) + + imgs = [np.pad(t[0], ((24, 24), (24, 24))) for t in triplets] + p_single = [penc.extract_patch_features(img) for img in imgs] + p_batch = penc.extract_patch_features_batch(imgs, batch_size=2) + assert len(p_batch) == len(p_single) + for f_b, f_s in zip(p_batch, p_single, strict=True): + assert f_b.shape == f_s.shape + np.testing.assert_allclose(f_b, f_s, atol=1e-5) diff --git a/tests/test_kinematics.py b/tests/test_kinematics.py index 6d215eb..7a92923 100644 --- a/tests/test_kinematics.py +++ b/tests/test_kinematics.py @@ -193,11 +193,22 @@ def test_required_columns(self) -> None: rows = kinematics_to_table(gk) expected = { "track_id", + "root_track_id", "scan_idx", "centroid_mu", "centroid_chi", "centroid_d", + "centroid_mu_err", + "centroid_chi_err", + "centroid_d_err", "strain", + "strain_err", + "lineage_strain", + "lineage_strain_err", + "strain_rate", + "rate_mu", + "rate_chi", + "rate_d", "misorientation_mu", "misorientation_chi", "misorientation_total", diff --git a/tests/test_kinematics_uncertainty.py b/tests/test_kinematics_uncertainty.py new file mode 100644 index 0000000..9e415f5 --- /dev/null +++ b/tests/test_kinematics_uncertainty.py @@ -0,0 +1,153 @@ +"""Tests for analytical centroid/strain uncertainty, lineage strain, and assignment margins.""" + +from __future__ import annotations + +import math + +import numpy as np + +from braggtrack.io.models import AxisCalibration +from braggtrack.segmentation.features import extract_instance_table +from braggtrack.tracking import ( + PositionShapeCost, + SplitMergeConfig, + build_tracks, + compute_grain_kinematics, + kinematics_to_table, + tracks_to_table, +) + + +def test_poisson_centroid_and_strain_error_match_monte_carlo() -> None: + """Analytical centroid_d_err and strain_err match 1,000-trial Poisson Monte Carlo within <10%.""" + rng = np.random.default_rng(42) + zz, yy, xx = np.mgrid[0:15, 0:15, 0:15] + sigma = 1.8 + cal = AxisCalibration( + mu_origin=10.0, + mu_step=0.05, + chi_origin=-2.0, + chi_step=0.04, + d_origin=1.35, + d_step=0.002, + calibrated=True, + ) + + # Expected photon distributions for scan 0 (d_center=7.0) and scan 1 (d_center=8.2) + lam0 = 2500.0 * np.exp(-((zz - 7.0) ** 2 + (yy - 7.0) ** 2 + (xx - 7.0) ** 2) / (2.0 * sigma**2)) + lam1 = 2500.0 * np.exp(-((zz - 7.0) ** 2 + (yy - 8.2) ** 2 + (xx - 7.0) ** 2) / (2.0 * sigma**2)) + mask0 = (lam0 > 1.0).astype(np.int32) + mask1 = (lam1 > 1.0).astype(np.int32) + + mc_d0: list[float] = [] + mc_strain1: list[float] = [] + pred_d0_errs: list[float] = [] + pred_strain1_errs: list[float] = [] + + for trial in range(1000): + v0 = rng.poisson(lam0).astype(np.float64) + v1 = rng.poisson(lam1).astype(np.float64) + r0 = extract_instance_table(mask0, v0, calibration=cal)[0] + r1 = extract_instance_table(mask1, v1, calibration=cal)[0] + mc_d0.append(float(r0["centroid_d"])) + mc_strain1.append((float(r1["centroid_d"]) - float(r0["centroid_d"])) / float(r0["centroid_d"])) + if trial < 50: + G = build_tracks([[r0], [r1]]) + gk = compute_grain_kinematics(tracks_to_table(G))[0] + pred_d0_errs.append(float(gk.centroid_d_err[0])) + pred_strain1_errs.append(float(gk.strain_err[1])) + assert gk.strain_err[0] == 0.0 + + emp_d0_std = float(np.std(mc_d0, ddof=1)) + emp_strain_std = float(np.std(mc_strain1, ddof=1)) + mean_pred_d0 = float(np.mean(pred_d0_errs)) + mean_pred_strain = float(np.mean(pred_strain1_errs)) + + assert abs(mean_pred_d0 - emp_d0_std) / emp_d0_std < 0.08 + assert abs(mean_pred_strain - emp_strain_std) / emp_strain_std < 0.08 + + +def test_ancestor_referenced_lineage_strain_and_causal_rates_across_split() -> None: + """Post-split daughter tracks retain root ancestor d0 in lineage_strain and causal rates.""" + + # Scan 0 -> Scan 1: parent grain contracts slightly (1.420 -> 1.414 A) + # Scan 1 -> Scan 2: grain splits 1 -> 2 into H3-collapsed (1.390 A) and H2-pinned (1.413 A) + def _spot(label: int, mu: float, chi: float, d: float, intensity: float, d_err: float = 1e-4) -> dict: + return { + "label": label, + "voxel_count": 30, + "integrated_intensity": intensity, + "centroid_mu": mu, + "centroid_chi": chi, + "centroid_d": d, + "centroid_mu_err": 1e-3, + "centroid_chi_err": 1e-3, + "centroid_d_err": d_err, + "eig_1": 1.2, + "eig_2": 1.0, + "eig_3": 0.8, + } + + scan0 = [_spot(1, 10.0, 5.0, 1.420, 1000.0)] + scan1 = [_spot(1, 10.1, 5.0, 1.414, 1000.0)] + scan2 = [ + _spot(1, 10.2, 4.7, 1.390, 550.0), + _spot(2, 10.2, 5.3, 1.413, 450.0), + ] + scan3 = [ + _spot(1, 10.3, 4.6, 1.385, 540.0), + _spot(2, 10.3, 5.4, 1.412, 460.0), + ] + + G = build_tracks( + [scan0, scan1, scan2, scan3], + cost_fn=PositionShapeCost(), + split_merge_config=SplitMergeConfig(max_distance=5.0), + ) + events = G.graph["lineage_events"] + assert len(events) == 1 + assert events[0].event_type == "split" + + gks = {gk.track_id: gk for gk in compute_grain_kinematics(tracks_to_table(G))} + parent_tid = events[0].parent_track_ids[0] + c1_tid, c2_tid = events[0].child_track_ids + + for dtid in (c1_tid, c2_tid): + dgk = gks[dtid] + assert dgk.root_track_id == parent_tid + # Segment-local strain resets at cleavage (scan 2), whereas lineage_strain preserves root d0=1.420 + assert dgk.strain[0] == 0.0 + expected_root_strain = (dgk.centroid_d[0] - 1.420) / 1.420 + assert abs(dgk.lineage_strain[0] - expected_root_strain) < 1e-9 + assert dgk.lineage_strain_err[0] > 0.0 + # Causal rate at split scan (i=0) uses immediate parent's scan-1 d=1.414 + expected_rate_d0 = dgk.centroid_d[0] - 1.414 + assert abs(dgk.rate_d[0] - expected_rate_d0) < 1e-9 + + flat = kinematics_to_table(list(gks.values())) + assert all("lineage_strain" in r and "strain_err" in r and "root_track_id" in r for r in flat) + + +def test_assignment_margin_distinguishes_crowded_from_isolated() -> None: + """Ambiguous nearby neighbours yield small assignment_margin vs inf when isolated.""" + s0_iso = [ + {"label": 1, "centroid_mu": 0.0, "centroid_chi": 0.0, "centroid_d": 0.0, "eig_1": 1, "eig_2": 1, "eig_3": 1} + ] + s1_iso = [ + {"label": 1, "centroid_mu": 0.2, "centroid_chi": 0.0, "centroid_d": 0.0, "eig_1": 1, "eig_2": 1, "eig_3": 1} + ] + G_iso = build_tracks([s0_iso, s1_iso]) + assert math.isinf(G_iso.nodes["s1_i0"]["assignment_margin"]) + + s0_crowd = [ + {"label": 1, "centroid_mu": 0.0, "centroid_chi": 0.0, "centroid_d": 0.0, "eig_1": 1, "eig_2": 1, "eig_3": 1}, + {"label": 2, "centroid_mu": 1.0, "centroid_chi": 0.0, "centroid_d": 0.0, "eig_1": 1, "eig_2": 1, "eig_3": 1}, + ] + s1_crowd = [ + {"label": 1, "centroid_mu": 0.4, "centroid_chi": 0.0, "centroid_d": 0.0, "eig_1": 1, "eig_2": 1, "eig_3": 1}, + {"label": 2, "centroid_mu": 1.0, "centroid_chi": 0.0, "centroid_d": 0.0, "eig_1": 1, "eig_2": 1, "eig_3": 1}, + ] + G_crowd = build_tracks([s0_crowd, s1_crowd]) + margin_crowd = G_crowd.nodes["s1_i0"]["assignment_margin"] + assert math.isfinite(margin_crowd) + assert 0.0 < margin_crowd < 1.0 diff --git a/tests/test_nexus_darfix.py b/tests/test_nexus_darfix.py new file mode 100644 index 0000000..9ed34be --- /dev/null +++ b/tests/test_nexus_darfix.py @@ -0,0 +1,88 @@ +"""Unit tests for darfix NXdata and ESRF BLISS NeXus/HDF5 auto-discovery.""" + +from __future__ import annotations + +from pathlib import Path + +import h5py +import numpy as np +import pytest + +from braggtrack.io.nexus import ( + discover_primary_volume_path, + extract_axis_calibration, + extract_scan_metadata, + load_primary_volume, +) + + +def test_darfix_nxdata_default_signal_and_axes_calibration(tmp_path: Path) -> None: + h5_path = tmp_path / "darfix_processed.h5" + vol = np.arange(5 * 6 * 7, dtype=np.float32).reshape(5, 6, 7) + mu_axis = np.linspace(12.0, 12.4, 5) + tth_axis = np.linspace(21.5, 21.75, 6) + chi_axis = np.linspace(-1.5, 1.5, 7) + + with h5py.File(h5_path, "w") as f: + f.attrs["default"] = "scan_01" + entry = f.create_group("scan_01") + entry.attrs["NX_class"] = "NXentry" + entry.attrs["default"] = "rocking_curves" + entry.create_dataset("title", data="ID03 darfix rocking curve") + + nxdata = entry.create_group("rocking_curves") + nxdata.attrs["NX_class"] = "NXdata" + nxdata.attrs["signal"] = "intensity_cube" + nxdata.attrs["axes"] = ["obx", "obpitch", "oby"] + nxdata.create_dataset("intensity_cube", data=vol) + nxdata.create_dataset("obx", data=mu_axis) + nxdata.create_dataset("obpitch", data=tth_axis) + nxdata.create_dataset("oby", data=chi_axis) + + ds_path = discover_primary_volume_path(h5_path) + loaded = load_primary_volume(h5_path) + assert ds_path == "/scan_01/rocking_curves/intensity_cube" + np.testing.assert_allclose(loaded, vol) + + cal = extract_axis_calibration(h5_path) + assert cal.calibrated is True + assert cal.mu_origin == pytest.approx(12.0) + assert cal.mu_step == pytest.approx(0.1) + assert cal.d_origin == pytest.approx(21.5) + assert cal.d_step == pytest.approx(0.05) + assert cal.chi_origin == pytest.approx(-1.5) + assert cal.chi_step == pytest.approx(0.5) + + meta = extract_scan_metadata(h5_path) + assert meta["entry"] == "/scan_01" + assert meta["title"] == "ID03 darfix rocking curve" + + +def test_esrf_bliss_instrument_positioners_calibration(tmp_path: Path) -> None: + h5_path = tmp_path / "bliss_id03_scan.h5" + vol = np.ones((4, 5, 6), dtype=np.float32) + + with h5py.File(h5_path, "w") as f: + entry = f.create_group("entry_0000") + entry.attrs["NX_class"] = "NXentry" + det = entry.create_group("ESRF-ID03/pco_nf") + det.create_dataset("data", data=vol) + + pos = entry.create_group("instrument/positioners") + pos.create_dataset("mu", data=np.array([10.0, 10.02, 10.04, 10.06])) + pos.create_dataset("chi", data=np.linspace(-0.5, 0.5, 6)) + pos.create_dataset("twotheta", data=np.linspace(18.0, 18.2, 5)) + + ds_path = discover_primary_volume_path(h5_path) + loaded = load_primary_volume(h5_path) + assert ds_path == "/entry_0000/ESRF-ID03/pco_nf/data" + assert loaded.shape == (4, 5, 6) + + cal = extract_axis_calibration(h5_path) + assert cal.calibrated is True + assert cal.mu_origin == pytest.approx(10.0) + assert cal.mu_step == pytest.approx(0.02) + assert cal.chi_origin == pytest.approx(-0.5) + assert cal.chi_step == pytest.approx(0.2) + assert cal.d_origin == pytest.approx(18.0) + assert cal.d_step == pytest.approx(0.05) diff --git a/tests/test_operando_log.py b/tests/test_operando_log.py new file mode 100644 index 0000000..b19ce16 --- /dev/null +++ b/tests/test_operando_log.py @@ -0,0 +1,127 @@ +"""Tests for operando electrochemistry / stimulus synchronization and visualization.""" + +from __future__ import annotations + +from datetime import datetime, timedelta, timezone +from pathlib import Path + +import matplotlib + +matplotlib.use("Agg") +import matplotlib.pyplot as plt + +from braggtrack.cli._utils import write_csv +from braggtrack.io import ( + ExperimentSequence, + ScanVolumeMeta, + annotate_tracks_with_stimulus, + load_operando_log, + synchronize_to_scans, +) +from braggtrack.tracking import PositionShapeCost, SplitMergeConfig, build_tracks, tracks_to_table +from braggtrack.viz import generate_html_report, plot_operando_strain_and_events + + +def test_biologic_mpt_parsing_and_dq_dv_sync(tmp_path: Path) -> None: + """Biologic EC-Lab .mpt ASCII format parses Nb header lines, Ewe/V, /mA, and derives dQ/dV.""" + mpt_path = tmp_path / "ni92_cycle1.mpt" + mpt_lines = [ + "EC-Lab ASCII file", + "Nb header lines : 5", + "Acquisition started on : 11/17/2026 10:00:00", + "Electrode material : LiNi0.92Mn0.04Co0.04O2", + "time/s\tEwe/V\t/mA\t(Q-Qo)/mA.h\tcycle number", + "0.0\t3.600\t0.50\t0.00\t1", + "600.0\t3.950\t0.50\t60.00\t1", + "1200.0\t4.180\t0.50\t165.00\t1", + "1800.0\t4.210\t0.50\t205.00\t1", + "2400.0\t4.300\t0.50\t222.00\t1", + ] + mpt_path.write_text("\n".join(mpt_lines), encoding="utf-8") + + log = load_operando_log(mpt_path) + assert log.n_points == 5 + assert log.voltage_v is not None + assert log.dq_dv is not None + # H2 -> H3 plateau (4.18 -> 4.21 V, delta_Q = 40 mAh over 30 mV) produces largest dQ/dV peak + assert float(log.dq_dv[3]) > float(log.dq_dv[1]) + + t0 = datetime(2026, 11, 17, 10, 0, 0, tzinfo=timezone.utc) + seq = ExperimentSequence( + scans=tuple( + ScanVolumeMeta( + scan_name=f"scan{i + 1:04d}", + file_path=tmp_path / f"s{i}.h5", + sequence_index=i, + start_time=t0 + timedelta(seconds=600 * i), + end_time=t0 + timedelta(seconds=600 * i + 20), + ) + for i in range(5) + ) + ) + pts = synchronize_to_scans(log, seq) + assert len(pts) == 5 + assert 4.17 < (pts[2].voltage_v or 0.0) < 4.20 + assert pts[3].cycle == 1 + + +def test_csv_operando_annotation_plot_and_html_report(tmp_path: Path) -> None: + """CSV operando log enriches tracks with d_strain_d_v and renders synchronized plot + HTML explorer.""" + csv_log = tmp_path / "echem.csv" + csv_log.write_text( + "scan_idx,voltage_V,current_mA,capacity_mAh_g,temperature_C\n" + "0,3.80,0.4,40.0,25.0\n" + "1,4.16,0.4,155.0,25.2\n" + "2,4.22,0.4,198.0,25.6\n" + "3,4.30,0.4,215.0,25.8\n", + encoding="utf-8", + ) + + def _spot(lbl: int, mu: float, chi: float, d: float, inten: float) -> dict: + return { + "label": lbl, + "voxel_count": 25, + "integrated_intensity": inten, + "centroid_mu": mu, + "centroid_chi": chi, + "centroid_d": d, + "centroid_mu_err": 1e-3, + "centroid_chi_err": 1e-3, + "centroid_d_err": 2e-4, + "eig_1": 1.4, + "eig_2": 1.0, + "eig_3": 0.7, + } + + scans = [ + [_spot(1, 5.0, 5.0, 1.422, 1000.0)], + [_spot(1, 5.1, 5.0, 1.415, 1000.0)], + [_spot(1, 5.2, 4.7, 1.388, 560.0), _spot(2, 5.2, 5.3, 1.412, 440.0)], + [_spot(1, 5.3, 4.6, 1.384, 550.0), _spot(2, 5.3, 5.4, 1.411, 450.0)], + ] + G = build_tracks(scans, PositionShapeCost(), split_merge_config=SplitMergeConfig(max_distance=5.0)) + rows = tracks_to_table(G) + + log = load_operando_log(csv_log) + pts = synchronize_to_scans(log, 4) + enriched = annotate_tracks_with_stimulus(rows, pts) + assert any(r["d_strain_d_v"] != "" for r in enriched) + + fig_path = tmp_path / "operando_fig.png" + fig, _ = plot_operando_strain_and_events( + enriched, + pts, + events=G.graph["lineage_events"], + zoom_triggers=[{"scan_idx": 1, "track_id": 1, "precursor_score": 0.72}], + calibrated=True, + save_path=fig_path, + ) + plt.close(fig) + assert fig_path.exists() and fig_path.stat().st_size > 1000 + + art_dir = tmp_path / "art" + write_csv(art_dir / "tracking" / "tracks.csv", enriched) + html_out = generate_html_report(art_dir, art_dir / "report.html", operando_log=csv_log) + html_txt = html_out.read_text(encoding="utf-8") + assert "Operando Potential E (V)" in html_txt + assert "4.22" in html_txt From bb85cc42ae7abdebf96ba870d42be10251b1694e Mon Sep 17 00:00:00 2001 From: James Le Houx <37665786+jameslehoux@users.noreply.github.com> Date: Wed, 18 Nov 2026 09:48:55 +0000 Subject: [PATCH 2/3] feat(autonomous,tracking): FAL Level 3 ODD/Sim-to-Real audit and red-team physics hardening --- CHANGELOG.md | 16 +- braggtrack/autonomous/__init__.py | 35 +- braggtrack/autonomous/odd.py | 282 ++++++++++++++++ braggtrack/autonomous/replay.py | 65 +++- braggtrack/autonomous/streaming.py | 454 +++++++++++++++++++++++--- braggtrack/autonomous/trigger.py | 312 +++++++++++++++--- braggtrack/cli/run_pipeline.py | 7 + braggtrack/cli/watch_autonomous.py | 196 +++++++++-- braggtrack/io/beamline.py | 2 +- braggtrack/io/lazy.py | 5 +- braggtrack/io/nexus.py | 25 +- braggtrack/segmentation/classical.py | 73 ++++- braggtrack/segmentation/features.py | 161 +++++++-- braggtrack/semantic/dino.py | 15 +- braggtrack/tracking/cost.py | 87 ++++- braggtrack/tracking/events.py | 70 +++- braggtrack/tracking/gap_closing.py | 18 +- braggtrack/tracking/kinematics.py | 56 +++- braggtrack/types.py | 17 + braggtrack/viz/html_report.py | 56 ++-- docs/architecture.md | 14 +- docs/positioning.md | 55 +++- paper.bib | 80 +++++ paper.md | 195 ++++++----- tests/test_redteam_hardening.py | 467 +++++++++++++++++++++++++++ 25 files changed, 2415 insertions(+), 348 deletions(-) create mode 100644 braggtrack/autonomous/odd.py create mode 100644 tests/test_redteam_hardening.py diff --git a/CHANGELOG.md b/CHANGELOG.md index dbeeb31..1b361bf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,12 +17,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Batched `DINOv2` ViT inference & zero-config `darfix` / ESRF BLISS NeXus auto-calibration (`braggtrack.semantic.dino`, `braggtrack.io.nexus`)**: - Added `embed_batch` and `extract_patch_features_batch` across `MultiviewEncoder` and `PatchFeatureEncoder` (with CPU L3-friendly micro-batching), accelerating `braggtrack-embed-dataset`, `compute_fracture_precursors`, and `segment_dino` while guaranteeing bit-identical cosine parity. - Added `NXdata` `@default` / `@signal` / `@axes` (`darfix` processed HDF5) and ESRF BLISS `instrument/positioners` auto-calibration in `discover_primary_volume_path` and `extract_axis_calibration`. -- **Online causal streaming & autonomous DFXM "Scout-and-Zoom" engine (`braggtrack.autonomous`, `braggtrack-watch`)**: - - Added `CausalStreamingTracker` (`streaming.py`) with strictly causal trailing-window Otsu stabilisation and $O(1)$-volume-RAM cached ROI precursors. - - Added `ZoomTriggerPolicy`, `ZoomTarget`, and `select_zoom_targets` (`trigger.py`) with velocity-extrapolated diffractometer setpoint prediction, uncertainty-aware rocking-window sizing, and `bliss_dfxm_zoom.v1` JSONL serialization (`zoom_triggers.jsonl`). - - Added `evaluate_causal_replay` (`replay.py`) benchmarking autonomous pre-fracture recall, electrochemical lead ($\Delta E$), and setpoint hit rate against `brightest_intensity`, `strain_only`, and `random` policies, exposed via the 10th CLI entry point `braggtrack-watch` (`--mode watch` and `--mode replay`). -- **Ecosystem positioning, verified bibliography & release workflow (`docs/positioning.md`, `.github/workflows/release.yml`)**: - - Added `docs/positioning.md` comparing `BraggTrack` against `darfix`, `ImageD11`, `HEXRD`, `BraggNN`, `TrackMate 7`, and `LapTrack`, updated `paper.md` and `paper.bib` with verified DOIs (`@GarrigaFerrer2023`, `@Isern2025`, `@Bernier2011`, `@Liu2022`, `@Fukai2023`, `@Ershov2022`), bumped metadata to `0.4.0`, and added tag-triggered sdist/wheel + Twine + GitHub Release / PyPI Trusted Publisher workflow. +- **Facility Autonomy Level 3 (FAL L3) online causal streaming & autonomous DFXM "Scout-and-Zoom" engine (`braggtrack.autonomous`, `braggtrack-watch`)**: + - Added `OperationalDesignDomain`, `BulkReferencePrior`, `SimToRealAuditRecord`, and closed-form differential-entropy-normalized Sim-to-Real Gap `compute_sim_to_real_gap` (`odd.py`), implementing FAL L3 hypothesis-conditioned policies (`--hypothesis {mechanical_fracture, phase_nucleation, intragranular_disorder}`), motor soft-limit clamping, electrochemical voltage/temperature ODD bounds, per-lineage X-ray dose caps, latency budget checks ($\tau_{\text{loop}} \le t_{\text{decision}}/\kappa$), and upstream beam-flux health weighting $D(x) = H(x)\mathcal{W}(\mathbf{s}_t)$. + - Added $O(1)$ bounded sliding-window incremental tracking (`sliding_window_scans=24`) in `CausalStreamingTracker` (`streaming.py`), maintaining constant per-scan latency across `1,000+` scan operando runs while preserving global track IDs and root strain anchors. + - Added staged certification modes (`--mode {replay, shadow, watch, active}`) and live HDF5 file-quiescence + `SWMR` polling in `braggtrack-watch`, emitting `bliss_dfxm_zoom.v1` commands (`zoom_triggers.jsonl`) and immutable Sim-to-Real audit logs (`audit_trajectory.jsonl`). +- **Crystallographic physics & Red-Team hardening (`segmentation`, `semantic`, `tracking`, `viz`, `cli`)**: + - Added local 1-voxel exterior background pedestal subtraction (`background_level`, `net_intensity`), gain-aware Poisson counting variance (`detector_gain`), standardized Pearson rocking-curve excess kurtosis (`kurtosis_mu`, `kurtosis_chi`, `kurtosis_d`), dimensionless voxel eigenvalues (`vox_eig_1..3`), and boundary truncation flags (`touches_border`, `touches_rocking_border`) in `extract_instance_table`, plus `float32` classical segmentation memory reduction (`segment_classical`). + - Added step-normalized physical-unit invariance across `PositionShapeCost`, `resolve_track_gaps`, and `resolve_splits_and_merges` so calibrated `AxisCalibration` runs (`deg`, `Å`) produce identical trajectories to uncalibrated voxel space, plus `mechanical_split` vs. `phase_split` (`H2 -> H3`) split classification and wall-clock `strain_rate_per_s`. + - Added aspect-ratio-preserving square letterbox padding for global `DINOv2` MIP embeddings, strict `--config` key validation in `braggtrack-run`, and Content-Security-Policy (CSP) + HTML entity escaping against DOM XSS in `generate_html_report`. +- **Ecosystem positioning, verified FAL bibliography & release workflow (`docs/positioning.md`, `.github/workflows/release.yml`)**: + - Added `docs/positioning.md` comparing `BraggTrack` against `darfix`, `ImageD11`, `HEXRD`, `BraggNN`, `TrackMate 7`, and `LapTrack` and formalizing its FAL Level 3 classification, updated `paper.md` and `paper.bib` with verified DOIs (`@GarrigaFerrer2023`, `@Isern2025`, `@Bernier2011`, `@Liu2022`, `@Fukai2023`, `@Ershov2022`, `@Drnec2025`, `@LeHoux2026`, `@Lu2025`, `@LeHouxFAL2026`, `@Szymanski2023`, `@McDannald2022`), bumped metadata to `0.4.0`, and added tag-triggered sdist/wheel + Twine + GitHub Release / PyPI Trusted Publisher workflow. ## [0.3.0] - 2026-11-17 diff --git a/braggtrack/autonomous/__init__.py b/braggtrack/autonomous/__init__.py index d44cf62..8cf6729 100644 --- a/braggtrack/autonomous/__init__.py +++ b/braggtrack/autonomous/__init__.py @@ -1,17 +1,48 @@ -"""Online causal streaming and autonomous DFXM "Scout-and-Zoom" engine.""" +"""Online causal streaming and FAL Level 3 autonomous DFXM "Scout-and-Zoom" engine.""" +from .odd import ( + CHI2_DF3_P95, + CHI2_DF3_P99, + DEFAULT_VALIDITY_EPSILON, + BulkReferencePrior, + ExecutionMode, + FALActiveLevel, + HypothesisMode, + OperationalDesignDomain, + SimToRealAuditRecord, + compute_sim_to_real_gap, + spot_kurtosis_non_gaussianity, +) from .replay import PolicyReplayMetrics, ReplayBenchmarkResult, evaluate_causal_replay from .streaming import CausalStreamingTracker, StreamingStepResult -from .trigger import ZoomTarget, ZoomTriggerPolicy, compute_target_geometry, select_zoom_targets +from .trigger import ( + ZoomTarget, + ZoomTriggerPolicy, + compute_predictive_std, + compute_target_geometry, + select_zoom_targets, +) __all__ = [ + "CHI2_DF3_P95", + "CHI2_DF3_P99", + "DEFAULT_VALIDITY_EPSILON", + "BulkReferencePrior", "CausalStreamingTracker", + "ExecutionMode", + "FALActiveLevel", + "HypothesisMode", + "OperationalDesignDomain", "PolicyReplayMetrics", "ReplayBenchmarkResult", + "SimToRealAuditRecord", "StreamingStepResult", "ZoomTarget", "ZoomTriggerPolicy", + "compute_predictive_std", + "compute_sim_to_real_gap", "compute_target_geometry", "evaluate_causal_replay", "select_zoom_targets", + "spot_kurtosis_non_gaussianity", ] diff --git a/braggtrack/autonomous/odd.py b/braggtrack/autonomous/odd.py new file mode 100644 index 0000000..c4f0b02 --- /dev/null +++ b/braggtrack/autonomous/odd.py @@ -0,0 +1,282 @@ +"""Operational Design Domain (ODD), Bulk Reference Priors, and Sim-to-Real Audit for FAL Level 3. + +Implements the formal autonomy safety, prior-calibration, and audit constructs from +Le Houx, *"Facility Autonomy Levels: A Hierarchical Taxonomy for Self-Driving Beamlines"*: + +- **FAL Level 3 Crossing (Inference Barrier)**: + 1. Acts on inferred physical sample state (strain, mosaicity covariance, rocking-curve kurtosis $g_2$). + 2. Evaluates measurements against an external/calibrated reference prior (:class:`BulkReferencePrior` + ``DINOv2``). + 3. Adapts acquisition policy to the declared experimental hypothesis (:data:`HypothesisMode`). +- **Latency Criterion (FAL Eq. 1)**: $\\tau_{\\text{loop}} \\le t_{\\text{decision}} / \\kappa$. +- **Sim-to-Real Gap (FAL Eq. 4)**: Closed-form differential-entropy-normalized Gaussian surprise + $\\Delta_{\\text{gap}} = \\frac{1}{2}\\sum_k (s'_{\\text{obs},k} - \\hat{\\mu}_k)^2 / \\sigma_{\\text{pred},k}^2 - \\frac{3}{2}$, + which is affine/unit-invariant with $\\mathbb{E}[\\Delta_{\\text{gap}}] = 0$ under nominal calibration. +- **Discovery Potential Weighting (FAL Eq. 6)**: $D(x) = H(x) \\cdot \\mathcal{W}(\\mathbf{s}_t)$, suppressing + spurious triggers during upstream beam dumps or shutter closures. +""" + +from __future__ import annotations + +import math +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Literal + +import numpy as np + +if TYPE_CHECKING: + from braggtrack.io.operando_log import ScanStimulusPoint + +HypothesisMode = Literal["mechanical_fracture", "phase_nucleation", "intragranular_disorder"] +ExecutionMode = Literal["replay", "shadow", "watch", "active"] +FALActiveLevel = Literal["L3", "L2_fallback", "L1_halt"] + +# Exact chi-square critical values for df=3 (3D (mu, chi, d) predictive setpoint Gaussian) +CHI2_DF3_P95: float = 7.814727903251179 +CHI2_DF3_P99: float = 11.344866730144373 +DEFAULT_VALIDITY_EPSILON: float = 0.5 * (CHI2_DF3_P99 - 3.0) # 4.172433365... + + +@dataclass(frozen=True) +class OperationalDesignDomain: + """Explicit Operational Design Domain ($\\mathcal{O}_{\\text{ODD}}$) bounding Level 3 agency.""" + + mu_bounds: tuple[float, float] | None = None + chi_bounds: tuple[float, float] | None = None + d_bounds: tuple[float, float] | None = None + max_extrapolation_steps: float = 12.0 + voltage_bounds_v: tuple[float, float] | None = None + temperature_bounds_c: tuple[float, float] | None = None + max_zooms_per_lineage: int | None = None + scan_cadence_sec: float | None = None + latency_safety_factor_kappa: float = 2.0 + min_instrument_health: float = 0.25 + validity_epsilon: float = DEFAULT_VALIDITY_EPSILON + + def clamp_setpoint( + self, + pred: tuple[float, float, float], + half_widths: tuple[float, float, float], + ) -> tuple[tuple[float, float, float], tuple[float, float, float], bool]: + """Clamp ``(mu, chi, d)`` setpoints and scan intervals to physical motor soft-limits.""" + pm, pc, pd = pred + hm, hc, hd = half_widths + clamped = False + + def _clamp_axis(val: float, hw: float, bounds: tuple[float, float] | None) -> tuple[float, float]: + nonlocal clamped + if bounds is None: + return val, hw + lo, hi = (min(bounds[0], bounds[1]), max(bounds[0], bounds[1])) + new_val = min(max(val, lo), hi) + if abs(new_val - val) > 1e-12: + clamped = True + # Ensure [new_val - new_hw, new_val + new_hw] stays inside [lo, hi] when span permits + max_span_half = 0.5 * (hi - lo) + new_hw = min(hw, max_span_half) + if new_val - new_hw < lo - 1e-12: + new_val = lo + new_hw + clamped = True + if new_val + new_hw > hi + 1e-12: + new_val = hi - new_hw + clamped = True + new_val = min(max(new_val, lo), hi) + return new_val, max(0.0, new_hw) + + pm, hm = _clamp_axis(pm, hm, self.mu_bounds) + pc, hc = _clamp_axis(pc, hc, self.chi_bounds) + pd, hd = _clamp_axis(pd, hd, self.d_bounds) + return (pm, pc, pd), (hm, hc, hd), clamped + + def check_sample_environment(self, stimulus: ScanStimulusPoint | None) -> tuple[bool, list[str]]: + """Check whether electrochemical potential and sample temperature remain inside $\\mathcal{O}_{\\text{ODD}}$.""" + if stimulus is None: + return True, [] + violations: list[str] = [] + if self.voltage_bounds_v is not None and stimulus.voltage_v is not None and math.isfinite(stimulus.voltage_v): + v_lo, v_hi = min(self.voltage_bounds_v), max(self.voltage_bounds_v) + if not (v_lo <= float(stimulus.voltage_v) <= v_hi): + violations.append(f"voltage_out_of_odd={stimulus.voltage_v:.3f}V_not_in_[{v_lo:.3f},{v_hi:.3f}]") + if ( + self.temperature_bounds_c is not None + and stimulus.temperature_c is not None + and math.isfinite(stimulus.temperature_c) + ): + t_lo, t_hi = min(self.temperature_bounds_c), max(self.temperature_bounds_c) + if not (t_lo <= float(stimulus.temperature_c) <= t_hi): + violations.append( + f"temperature_out_of_odd={stimulus.temperature_c:.2f}C_not_in_[{t_lo:.2f},{t_hi:.2f}]" + ) + return len(violations) == 0, violations + + def evaluate_latency_budget(self, step_latency_sec: float) -> tuple[bool, float | None]: + """Evaluate FAL Eq. (1): $\\tau_{\\text{loop}} \\le t_{\\text{decision}} / \\kappa$.""" + if self.scan_cadence_sec is None or self.scan_cadence_sec <= 0.0: + return True, None + kappa = max(1.0, float(self.latency_safety_factor_kappa)) + budget_sec = float(self.scan_cadence_sec) / kappa + return float(step_latency_sec) <= budget_sec, budget_sec + + def to_dict(self) -> dict[str, Any]: + return { + "mu_bounds": list(self.mu_bounds) if self.mu_bounds is not None else None, + "chi_bounds": list(self.chi_bounds) if self.chi_bounds is not None else None, + "d_bounds": list(self.d_bounds) if self.d_bounds is not None else None, + "max_extrapolation_steps": float(self.max_extrapolation_steps), + "voltage_bounds_v": list(self.voltage_bounds_v) if self.voltage_bounds_v is not None else None, + "temperature_bounds_c": list(self.temperature_bounds_c) if self.temperature_bounds_c is not None else None, + "max_zooms_per_lineage": self.max_zooms_per_lineage, + "scan_cadence_sec": self.scan_cadence_sec, + "latency_safety_factor_kappa": float(self.latency_safety_factor_kappa), + "min_instrument_health": float(self.min_instrument_health), + "validity_epsilon": round(float(self.validity_epsilon), 6), + } + + +@dataclass(frozen=True) +class BulkReferencePrior: + """Reference prior $(\\mu_{\\text{bulk}}, \\sigma_{\\text{bulk}})$ for rocking-curve kurtosis $g_2$ (FAL Eq. 2).""" + + kurtosis_mean: float = 0.0 + kurtosis_std: float = 0.25 + sigma_multiplier: float = 3.0 + n_reference_spots: int = 0 + source: str = "analytic_gaussian_prior" + + @property + def kurtosis_threshold(self) -> float: + """Dynamic anomaly threshold $K_{\\text{thresh}} = \\mu_{\\text{bulk}} + k\\,\\sigma_{\\text{bulk}}$.""" + return float(self.kurtosis_mean + self.sigma_multiplier * self.kurtosis_std) + + @classmethod + def from_spots( + cls, + spots: list[dict[str, Any]], + *, + sigma_multiplier: float = 3.0, + min_std: float = 0.15, + ) -> BulkReferencePrior: + """Estimate bulk undeformed kurtosis statistics robustly via median and MAD on initial scan spots.""" + vals: list[float] = [] + for s in spots: + if bool(s.get("touches_rocking_border", False)): + continue + g2_max = max( + abs(float(s.get("kurtosis_mu", 0.0))), + abs(float(s.get("kurtosis_chi", 0.0))), + abs(float(s.get("kurtosis_d", 0.0))), + ) + if math.isfinite(g2_max): + vals.append(g2_max) + if not vals: + return cls(sigma_multiplier=sigma_multiplier) + arr = np.asarray(vals, dtype=np.float64) + med = float(np.median(arr)) + mad_std = float(1.4826 * np.median(np.abs(arr - med))) + return cls( + kurtosis_mean=med, + kurtosis_std=max(float(min_std), mad_std), + sigma_multiplier=float(sigma_multiplier), + n_reference_spots=len(vals), + source="initial_scan_bulk_ensemble", + ) + + def to_dict(self) -> dict[str, Any]: + return { + "kurtosis_mean": round(float(self.kurtosis_mean), 5), + "kurtosis_std": round(float(self.kurtosis_std), 5), + "sigma_multiplier": round(float(self.sigma_multiplier), 3), + "kurtosis_threshold": round(self.kurtosis_threshold, 5), + "n_reference_spots": int(self.n_reference_spots), + "source": self.source, + } + + @classmethod + def from_dict(cls, data: dict[str, Any]) -> BulkReferencePrior: + return cls( + kurtosis_mean=float(data.get("kurtosis_mean", 0.0)), + kurtosis_std=float(data.get("kurtosis_std", 0.25)), + sigma_multiplier=float(data.get("sigma_multiplier", 3.0)), + n_reference_spots=int(data.get("n_reference_spots", 0)), + source=str(data.get("source", "external_json_prior")), + ) + + +def spot_kurtosis_non_gaussianity(obs: dict[str, Any]) -> float: + """Return $\\max_{k \\in \\{\\mu, \\chi, d\\}} |g_{2,k}|$ quantifying departure from Gaussian rocking peak.""" + return max( + abs(float(obs.get("kurtosis_mu", 0.0))), + abs(float(obs.get("kurtosis_chi", 0.0))), + abs(float(obs.get("kurtosis_d", 0.0))), + ) + + +def compute_sim_to_real_gap( + predicted_mean: tuple[float, float, float], + predicted_std: tuple[float, float, float], + observed_centroid: tuple[float, float, float], + *, + validity_epsilon: float = DEFAULT_VALIDITY_EPSILON, +) -> tuple[float, float, bool, bool]: + """Compute FAL Eq. (4) differential-entropy-normalized Sim-to-Real Gap $\\Delta_{\\text{gap}}$. + + For a 3D diagonal Gaussian forward model $P_{\\text{sim}}(\\mathbf{s}' \\mid \\mathbf{s}_t, \\mathbf{a}_t) = + \\mathcal{N}(\\hat{\\boldsymbol{\\mu}}, \\mathrm{diag}(\\sigma_\\mu^2, \\sigma_\\chi^2, \\sigma_d^2))$, + $-\\ln P_{\\text{sim}}(\\mathbf{s}'_{\\text{obs}}) - H[P_{\\text{sim}}]$ cancels $\\frac{3}{2}\\ln(2\\pi)$ and + $\\frac{1}{2}\\ln|\\boldsymbol{\\Sigma}|$ identically, yielding: + + $$\\Delta_{\\text{gap}} = \\frac{1}{2}\\sum_{k=1}^{3} \\frac{(s'_{\\text{obs},k} - \\hat{\\mu}_k)^2}{\\sigma_k^2} - \\frac{3}{2}$$ + + Returns ``(delta_gap, mahalanobis_sq, within_95pct_ci, within_validity_domain)``. + """ + m2 = 0.0 + for mu_k, sig_k, obs_k in zip(predicted_mean, predicted_std, observed_centroid, strict=True): + denom = max(float(sig_k), 1e-12) + z = (float(obs_k) - float(mu_k)) / denom + m2 += z * z + delta_gap = 0.5 * m2 - 1.5 + within_95 = m2 <= CHI2_DF3_P95 + within_valid = delta_gap <= float(validity_epsilon) + return float(delta_gap), float(m2), bool(within_95), bool(within_valid) + + +@dataclass(frozen=True) +class SimToRealAuditRecord: + """Immutable trajectory audit entry $(\\mathbf{s}_t, \\mathbf{a}_t, P_{\\text{sim}}, \\mathbf{s}'_{\\text{obs}}, \\Delta_{\\text{gap}})$.""" + + source_scan_idx: int + eval_scan_idx: int + track_id: int + root_track_id: int + execution_mode: ExecutionMode + actuated: bool + hypothesis: HypothesisMode + predicted_setpoint: tuple[float, float, float] + predictive_std: tuple[float, float, float] + observed_centroid: tuple[float, float, float] + scan_half_widths: tuple[float, float, float] + setpoint_hit: bool + delta_gap: float + mahalanobis_sq: float + within_95pct_ci: bool + within_validity_domain: bool + + def to_dict(self) -> dict[str, Any]: + return { + "schema_version": "fal_audit.v1", + "source_scan_idx": int(self.source_scan_idx), + "eval_scan_idx": int(self.eval_scan_idx), + "track_id": int(self.track_id), + "root_track_id": int(self.root_track_id), + "execution_mode": self.execution_mode, + "actuated": bool(self.actuated), + "hypothesis": self.hypothesis, + "predicted_setpoint": [round(float(x), 6) for x in self.predicted_setpoint], + "predictive_std": [round(float(x), 6) for x in self.predictive_std], + "observed_centroid": [round(float(x), 6) for x in self.observed_centroid], + "scan_half_widths": [round(float(x), 6) for x in self.scan_half_widths], + "setpoint_hit": bool(self.setpoint_hit), + "delta_gap": round(float(self.delta_gap), 5), + "mahalanobis_sq": round(float(self.mahalanobis_sq), 5), + "within_95pct_ci": bool(self.within_95pct_ci), + "within_validity_domain": bool(self.within_validity_domain), + } diff --git a/braggtrack/autonomous/replay.py b/braggtrack/autonomous/replay.py index ef0f3b3..111019c 100644 --- a/braggtrack/autonomous/replay.py +++ b/braggtrack/autonomous/replay.py @@ -3,22 +3,25 @@ Replays a recorded 4D operando diffraction dataset strictly scan-by-scan through :class:`CausalStreamingTracker` and evaluates whether autonomous zoom triggers fire *before* actual ``1 -> 2+`` grain fracture events, whether velocity-extrapolated -motor setpoints accurately capture the grain at ``t + 1``, and how ``BraggTrack`` -compares against naive beamline trigger baselines (``random``, ``brightest_intensity``, -and ``strain_only``) under an identical zoom acquisition budget. +motor setpoints accurately capture the grain at ``t + 1``, the closed-form FAL Eq. (4) +Sim-to-Real Gap ($\\Delta_{\\text{gap}}$) distribution, and how ``BraggTrack`` compares +against naive beamline trigger baselines (``random``, ``brightest_intensity``, and +``strain_only``) under an identical zoom acquisition budget. """ from __future__ import annotations from collections.abc import Sequence -from dataclasses import dataclass +from dataclasses import dataclass, field from pathlib import Path from typing import TYPE_CHECKING, Any import numpy as np +from braggtrack.tracking.kinematics import compute_grain_kinematics from braggtrack.tracking.precursors import PrecursorConfig +from .odd import SimToRealAuditRecord from .streaming import CausalStreamingTracker, StreamingStepResult from .trigger import ZoomTarget, ZoomTriggerPolicy, compute_target_geometry @@ -63,7 +66,7 @@ def to_dict(self) -> dict[str, Any]: @dataclass(frozen=True) class ReplayBenchmarkResult: - """Complete causal replay trajectory, zoom triggers, and baseline comparison table.""" + """Complete causal replay trajectory, FAL Sim-to-Real audit, and baseline comparison table.""" n_scans: int mean_step_latency_sec: float @@ -71,6 +74,11 @@ class ReplayBenchmarkResult: steps: list[StreamingStepResult] zoom_targets: list[ZoomTarget] policy_comparison: dict[str, PolicyReplayMetrics] + audit_records: list[SimToRealAuditRecord] = field(default_factory=list) + mean_sim_to_real_gap: float | None = None + p99_sim_to_real_gap: float | None = None + nominal_95pct_coverage: float | None = None + esme_gain_vs_scripted: float | None = None def to_dict(self) -> dict[str, Any]: return { @@ -78,7 +86,20 @@ def to_dict(self) -> dict[str, Any]: "mean_step_latency_sec": round(float(self.mean_step_latency_sec), 4), "max_step_latency_sec": round(float(self.max_step_latency_sec), 4), "n_zoom_targets": len(self.zoom_targets), + "mean_sim_to_real_gap": ( + round(float(self.mean_sim_to_real_gap), 5) if self.mean_sim_to_real_gap is not None else None + ), + "p99_sim_to_real_gap": ( + round(float(self.p99_sim_to_real_gap), 5) if self.p99_sim_to_real_gap is not None else None + ), + "nominal_95pct_coverage": ( + round(float(self.nominal_95pct_coverage), 4) if self.nominal_95pct_coverage is not None else None + ), + "esme_gain_vs_scripted": ( + round(float(self.esme_gain_vs_scripted), 3) if self.esme_gain_vs_scripted is not None else None + ), "zoom_targets": [t.to_bliss_command() for t in self.zoom_targets], + "audit_records": [a.to_dict() for a in self.audit_records], "policy_comparison": {k: v.to_dict() for k, v in self.policy_comparison.items()}, "steps": [s.to_dict() for s in self.steps], } @@ -163,6 +184,7 @@ def evaluate_causal_replay( ) -> ReplayBenchmarkResult: """Run strictly causal scan-by-scan replay and benchmark against naive trigger baselines.""" pol = trigger_policy or ZoomTriggerPolicy() + odd = pol.resolved_odd() tracker = CausalStreamingTracker( backend=backend, calibration=calibration, @@ -172,7 +194,6 @@ def evaluate_causal_replay( ) steps: list[StreamingStepResult] = [] - # Capture per-step causal candidate pools so baseline policies face the exact same causal state & budget causal_pools: list[ list[ tuple[ @@ -203,10 +224,11 @@ def evaluate_causal_replay( tuple[float, float, float], ] ] = [] - for obs in tracker.track_table: + for obs in tracker._window_rows: if int(obs["scan_idx"]) != idx: continue - if pol.exclude_post_split_daughters and str(obs.get("lineage_role", "")) == "split_daughter": + role = str(obs.get("lineage_role", "")) + if pol.exclude_post_split_daughters and role in ("split_child", "split_daughter"): continue tid = int(obs["track_id"]) kin = kin_by_tid.get(tid) @@ -228,12 +250,16 @@ def evaluate_causal_replay( window_sigma=pol.window_sigma, calibration=tracker.calibration, detector=detector, + max_extrapolation_steps=odd.max_extrapolation_steps, ) + pred_c, half_w, _ = odd.clamp_setpoint(pred_c, half_w) pool_t.append((root_tid, inten, l_strain, cur_c, pred_c, half_w)) causal_pools.append(pool_t) - # Extract ground-truth lineage split scans and future positions from the completed sequence - final_kin_by_tid = {k.track_id: k for k in tracker.kinematics} + # Extract ground-truth lineage split scans and future positions across the full sequence + full_table = tracker.track_table + final_kin = compute_grain_kinematics(full_table) if full_table else [] + final_kin_by_tid = {k.track_id: k for k in final_kin} split_scan_by_root: dict[int, int] = {} for ev in tracker.graph.graph.get("lineage_events", []): if ev.event_type == "split": @@ -244,7 +270,7 @@ def evaluate_causal_replay( split_scan_by_root[rtid] = int(ev.scan_idx_to) obs_by_scan_and_root: dict[tuple[int, int], list[tuple[float, float, float]]] = {} - for obs in tracker.track_table: + for obs in full_table: s_i = int(obs["scan_idx"]) tid = int(obs["track_id"]) pk = final_kin_by_tid.get(tid) @@ -279,7 +305,6 @@ def _run_baseline( tuple[int, int, tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]] ] = [] cd: dict[int, int] = {} - # Distribute budget evenly or greedily once min_track_age is met for t_idx, pool in enumerate(causal_pools): if len(fired) >= effective_budget or not pool: continue @@ -317,6 +342,17 @@ def _run_baseline( voltage_by_scan=voltage_by_scan, ) + audits = list(tracker.audit_records) + mean_gap = float(np.mean([a.delta_gap for a in audits])) if audits else None + p99_gap = float(np.percentile([a.delta_gap for a in audits], 99.0)) if audits else None + cov_95 = float(np.mean([1.0 if a.within_95pct_ci else 0.0 for a in audits])) if audits else None + + # Entropy-Scaled Measurement Efficiency (E_SME) gain vs unguided scripted sampling + all_roots = {rtid for (_, rtid) in obs_by_scan_and_root} + scripted_hit_prob = (len(split_scan_by_root) / max(1, len(all_roots))) if split_scan_by_root else 0.0 + bt_prec = comparison["braggtrack_autonomous"].fracture_capture_precision + esme_gain = (bt_prec / scripted_hit_prob) if scripted_hit_prob > 0.0 and bt_targets else None + latencies = [s.step_latency_sec for s in steps] if steps else [0.0] return ReplayBenchmarkResult( n_scans=len(steps), @@ -325,4 +361,9 @@ def _run_baseline( steps=steps, zoom_targets=bt_targets, policy_comparison=comparison, + audit_records=audits, + mean_sim_to_real_gap=mean_gap, + p99_sim_to_real_gap=p99_gap, + nominal_95pct_coverage=cov_95, + esme_gain_vs_scripted=esme_gain, ) diff --git a/braggtrack/autonomous/streaming.py b/braggtrack/autonomous/streaming.py index ef87f04..689e274 100644 --- a/braggtrack/autonomous/streaming.py +++ b/braggtrack/autonomous/streaming.py @@ -1,25 +1,30 @@ """Strictly causal online scan-by-scan tracker for live beamline streaming. Processes incoming 3D rocking-curve scans ``t = 0, 1, 2, ...`` without looking ahead: -- Causal trailing-window median Otsu thresholding (using only scans ``<= t``). -- 3D LoG + seeded watershed segmentation and Poisson-uncertainty feature extraction. -- Batched multi-view ``DINOv2`` embedding and cached ROI patch-dispersion scoring. -- Incremental Hungarian + gap-closing + ``1 -> 2+`` split/merge trajectory DAG update. -- Autonomous DFXM "Scout-and-Zoom" target selection at the end of every scan. +- Causal trailing-window median Otsu thresholding (using only scans ``<= t``), with chunked z-slab + streaming on HDF5 inputs and ``float32`` working volumes. +- Upstream instrument-health weighting $\\mathcal{W}(\\mathbf{s}_t)$ (suppressing beam-dump false positives) + and Operational Design Domain ($\\mathcal{O}_{\\text{ODD}}$) verification. +- 3D LoG + seeded watershed segmentation, background-pedestal subtraction, Poisson centroid error, + and standardized rocking-curve kurtosis $g_2$ extraction. +- $O(1)$ bounded sliding-window incremental trajectory DAG updates for ``1,000+`` scan operando runs. +- Automatic next-scan Sim-to-Real Gap ($\\Delta_{\\text{gap}}$, FAL Eq. 4) trajectory auditing. """ from __future__ import annotations +import math import time -from dataclasses import dataclass +from dataclasses import dataclass, field from pathlib import Path from typing import TYPE_CHECKING, Any import networkx as nx import numpy as np +from braggtrack.io.lazy import open_lazy_volume, otsu_threshold_chunked from braggtrack.io.models import AxisCalibration -from braggtrack.io.nexus import extract_axis_calibration, extract_scan_metadata, load_primary_volume +from braggtrack.io.nexus import extract_axis_calibration, extract_scan_metadata from braggtrack.segmentation import ( extract_instance_table, otsu_threshold, @@ -41,6 +46,12 @@ compute_fracture_precursors, ) +from .odd import ( + BulkReferencePrior, + FALActiveLevel, + SimToRealAuditRecord, + compute_sim_to_real_gap, +) from .trigger import ZoomTarget, ZoomTriggerPolicy, select_zoom_targets if TYPE_CHECKING: @@ -51,7 +62,7 @@ @dataclass(frozen=True) class StreamingStepResult: - """Snapshot of online causal tracking and autonomous DFXM triggers after scan ``scan_idx``.""" + """Snapshot of online causal tracking, FAL telemetry, and autonomous DFXM triggers after scan ``scan_idx``.""" scan_idx: int scan_name: str @@ -65,6 +76,11 @@ class StreamingStepResult: zoom_targets: list[ZoomTarget] step_latency_sec: float stimulus: ScanStimulusPoint | None = None + instrument_health: float = 1.0 + fal_level_active: FALActiveLevel = "L3" + within_latency_budget: bool = True + odd_violations: tuple[str, ...] = () + audit_records: list[SimToRealAuditRecord] = field(default_factory=list) def to_dict(self) -> dict[str, Any]: return { @@ -79,12 +95,17 @@ def to_dict(self) -> dict[str, Any]: "n_precursor_candidates": len(self.precursor_candidates), "zoom_targets": [t.to_bliss_command() for t in self.zoom_targets], "step_latency_sec": round(float(self.step_latency_sec), 4), + "within_latency_budget": bool(self.within_latency_budget), + "instrument_health": round(float(self.instrument_health), 4), + "fal_level_active": self.fal_level_active, + "odd_violations": list(self.odd_violations), + "audit_records": [a.to_dict() for a in self.audit_records], "stimulus": self.stimulus.to_dict() if self.stimulus is not None else None, } class CausalStreamingTracker: - """Stateful strictly causal scan-by-scan 4D reflection tracker and zoom trigger engine.""" + """Stateful strictly causal scan-by-scan 4D reflection tracker and FAL Level 3 zoom engine.""" def __init__( self, @@ -104,6 +125,9 @@ def __init__( split_max_distance: float = 25.0, precursor_config: PrecursorConfig | None = None, trigger_policy: ZoomTriggerPolicy | None = None, + reference_prior: BulkReferencePrior | None = None, + sliding_window_scans: int | None = 24, + swmr: bool = False, batch_size: int = 32, use_patch_encoder: bool = True, ) -> None: @@ -117,11 +141,14 @@ def __init__( self.cost_beta = float(cost_beta) self.max_cost = float(max_cost) self.batch_size = max(1, int(batch_size)) + self.swmr = bool(swmr) + self.sliding_window_scans = max(6, int(sliding_window_scans)) if sliding_window_scans is not None else None self.gap_config = GapClosingConfig(max_gap=max(0, int(max_gap))) if max_gap > 0 else None self.split_merge_config = SplitMergeConfig(max_distance=float(split_max_distance)) self.precursor_config = precursor_config or PrecursorConfig() self.trigger_policy = trigger_policy or ZoomTriggerPolicy() + self._reference_prior = reference_prior self._multiview_encoder = ( make_multiview_encoder(backend, model_name=model_name) if self.cost_beta > 0.0 else None @@ -136,16 +163,30 @@ def __init__( # Strictly causal state accumulated across scans 0 .. t self._raw_thresholds: list[float] = [] self._causal_thresholds: list[float] = [] + self._nominal_flux_history: list[float] = [] self._scan_names: list[str] = [] self._scan_timestamps: dict[int, str | None] = {} + self._scan_elapsed_s: dict[int, float] = {} self._scan_tables: list[list[dict[str, Any]]] = [] self._stimuli: dict[int, ScanStimulusPoint] = {} self._roi_cache: dict[tuple[int, int], tuple[int, float]] = {} self._cooldown_by_lineage: dict[int, int] = {} + self._zoom_counts_by_lineage: dict[int, int] = {} + self._pending_zoom_targets: dict[int, list[ZoomTarget]] = {} + self._audit_records: list[SimToRealAuditRecord] = [] + self._last_step_latency_sec: float = 0.0 + + # Sliding-window state preserving global track_ids and root strain anchors in O(1)/step + self._next_global_tid: int = 1 + self._spot_to_global_tid: dict[tuple[int, int], int] = {} + self._birth_anchor_by_tid: dict[int, dict[str, Any]] = {} + self._committed_rows: list[dict[str, Any]] = [] + self._committed_events: list[LineageEvent] = [] + self._committed_up_to_scan: int = -1 # Latest DAG & derived tables self._graph: nx.DiGraph = nx.DiGraph() - self._track_table: list[dict[str, Any]] = [] + self._window_rows: list[dict[str, Any]] = [] self._kinematics: list[GrainKinematics] = [] self._obs_precursor_scores: list[ObservationPrecursorScore] = [] self._precursor_candidates: list[PrecursorCandidate] = [] @@ -161,7 +202,7 @@ def graph(self) -> nx.DiGraph: @property def track_table(self) -> list[dict[str, Any]]: - return list(self._track_table) + return [*self._committed_rows, *self._window_rows] @property def kinematics(self) -> list[GrainKinematics]: @@ -175,12 +216,20 @@ def obs_precursor_scores(self) -> list[ObservationPrecursorScore]: def all_zoom_targets(self) -> list[ZoomTarget]: return list(self._all_zoom_targets) + @property + def audit_records(self) -> list[SimToRealAuditRecord]: + return list(self._audit_records) + + @property + def reference_prior(self) -> BulkReferencePrior | None: + return self._reference_prior + def _resolve_volume_and_meta( self, volume_or_path: np.ndarray | str | Path, scan_name: str | None, timestamp: str | None, - ) -> tuple[np.ndarray, str, str | None, AxisCalibration]: + ) -> tuple[np.ndarray, float, str, str | None, AxisCalibration]: if isinstance(volume_or_path, (str, Path)): p = Path(volume_or_path) if p.is_dir(): @@ -192,18 +241,266 @@ def _resolve_volume_and_meta( else: file_path = p default_name = p.stem - vol = load_primary_volume(file_path) - meta = extract_scan_metadata(file_path) + with open_lazy_volume(file_path, swmr=self.swmr) as lazy_vol: + raw_thr = float(otsu_threshold_chunked(lazy_vol)) + vol = np.asarray(lazy_vol._dataset[()], dtype=np.float32) + meta = extract_scan_metadata(file_path, swmr=self.swmr) ts = timestamp if timestamp is not None else meta.get("start_time") - cal = self.calibration if self.calibration is not None else extract_axis_calibration(file_path) + cal = ( + self.calibration + if self.calibration is not None + else extract_axis_calibration(file_path, swmr=self.swmr) + ) if self.calibration is None and cal.calibrated: self.calibration = cal - return vol, (scan_name or default_name), ts, cal + return vol, raw_thr, (scan_name or default_name), ts, cal - vol = np.asarray(volume_or_path, dtype=np.float64) + arr = np.asarray(volume_or_path) + vol = np.asarray(arr, dtype=np.float32 if arr.dtype.itemsize <= 4 else np.float64) + raw_thr = float(otsu_threshold(vol)) cal = self.calibration if self.calibration is not None else AxisCalibration() name = scan_name or f"scan_{len(self._scan_tables) + 1:04d}" - return vol, name, timestamp, cal + return vol, raw_thr, name, timestamp, cal + + def _compute_instrument_health(self, vol: np.ndarray, min_health: float) -> float: + """Compute upstream synchrotron flux/shutter health $\\mathcal{W}(\\mathbf{s}_t) \\in [0, 1]$.""" + flux = max(0.0, float(np.sum(vol, dtype=np.float64))) + if not self._nominal_flux_history: + if flux > 0.0: + self._nominal_flux_history.append(flux) + return 1.0 if flux > 0.0 else 0.0 + win = self._nominal_flux_history[-self.smooth_window :] + baseline = float(np.median(win)) + if baseline <= 0.0: + return 1.0 + ratio = flux / baseline + health = 1.0 if ratio >= 0.50 else float(np.clip(ratio / 0.50, 0.0, 1.0)) + if health >= min_health and flux > 0.0: + self._nominal_flux_history.append(flux) + return health + + def _build_window_dag(self, scan_idx: int) -> tuple[nx.DiGraph, list[dict[str, Any]], list[LineageEvent]]: + """Build causal DAG over active window ``[win_start, scan_idx]`` with immutable global track IDs.""" + n_total = scan_idx + 1 + win_start = ( + 0 + if self.sliding_window_scans is None or n_total <= self.sliding_window_scans + else n_total - self.sliding_window_scans + ) + + # Commit outgoing scans strictly before win_start from the previous step's window rows/events + if win_start > 0 and self._committed_up_to_scan < win_start - 1: + for row in self._window_rows: + s_i = int(row["scan_idx"]) + if self._committed_up_to_scan < s_i < win_start: + self._committed_rows.append(row) + prev_events: list[LineageEvent] = list(self._graph.graph.get("window_lineage_events", [])) + for ev in prev_events: + if self._committed_up_to_scan < ev.scan_idx_to < win_start: + self._committed_events.append(ev) + self._committed_up_to_scan = win_start - 1 + # Prune ROI cache older than win_start - 1 so RAM stays O(W) + stale_keys = [k for k in self._roi_cache if k[0] < win_start - 1] + for k in stale_keys: + del self._roi_cache[k] + + if win_start == 0: + G = build_tracks( + self._scan_tables, + cost_fn=self._cost_fn, + max_cost=self.max_cost, + gap_closing_config=self.gap_config, + split_merge_config=self.split_merge_config, + scan_timestamps=self._scan_timestamps, + ) + w_rows = tracks_to_table(G) + for row in w_rows: + s_i = int(row["scan_idx"]) + sp_i = int(row["spot_idx"]) + tid = int(row["track_id"]) + self._spot_to_global_tid[(s_i, sp_i)] = tid + if tid >= self._next_global_tid: + self._next_global_tid = tid + 1 + if tid not in self._birth_anchor_by_tid or s_i < int(self._birth_anchor_by_tid[tid]["scan_idx"]): + self._birth_anchor_by_tid[tid] = dict(row) + w_events = list(G.graph.get("lineage_events", [])) + G.graph["window_lineage_events"] = w_events + return G, w_rows, w_events + + # Sliding-window solve on scans [win_start .. scan_idx] + sub_tables = self._scan_tables[win_start : scan_idx + 1] + sub_ts = {k - win_start: v for k, v in self._scan_timestamps.items() if k >= win_start} + G_local = build_tracks( + sub_tables, + cost_fn=self._cost_fn, + max_cost=self.max_cost, + gap_closing_config=self.gap_config, + split_merge_config=self.split_merge_config, + scan_timestamps=sub_ts, + ) + + # Group local nodes by local_tid and map to persistent global_tid + nodes_by_local_tid: dict[int, list[tuple[int, int, str]]] = {} + for nid, data in G_local.nodes(data=True): + ltid = int(data["track_id"]) + nodes_by_local_tid.setdefault(ltid, []).append((int(data["scan_idx"]), int(data["spot_idx"]), nid)) + + local_to_global: dict[int, int] = {} + used_globals: set[int] = set() + for ltid in sorted(nodes_by_local_tid): + obs_list = sorted(nodes_by_local_tid[ltid]) + s0_loc, sp0, _ = obs_list[0] + s0_glob = s0_loc + win_start + cand = self._spot_to_global_tid.get((s0_glob, sp0)) + if cand is not None and cand not in used_globals: + gtid = cand + else: + gtid = self._next_global_tid + self._next_global_tid += 1 + used_globals.add(gtid) + local_to_global[ltid] = gtid + + # Rebuild relabeled window graph with global scan_idx and global track_id + G_global = nx.DiGraph() + nid_map: dict[str, str] = {} + for nid, data in G_local.nodes(data=True): + d = dict(data) + s_glob = int(d["scan_idx"]) + win_start + sp_i = int(d["spot_idx"]) + ltid = int(d["track_id"]) + gtid = local_to_global[ltid] + gnid = f"s{s_glob}_i{sp_i}" + nid_map[nid] = gnid + d["scan_idx"] = s_glob + d["track_id"] = gtid + if "parent_track_ids" in d and isinstance(d["parent_track_ids"], list): + d["parent_track_ids"] = [local_to_global.get(int(p), int(p)) for p in d["parent_track_ids"]] + elif gtid in self._birth_anchor_by_tid: + anchor = self._birth_anchor_by_tid[gtid] + if anchor.get("parent_track_ids"): + raw_p = anchor["parent_track_ids"] + if isinstance(raw_p, str): + d["parent_track_ids"] = [int(x) for x in raw_p.split(";") if x.strip()] + elif isinstance(raw_p, list): + d["parent_track_ids"] = list(raw_p) + if anchor.get("lineage_role") and not d.get("lineage_role"): + d["lineage_role"] = anchor["lineage_role"] + G_global.add_node(gnid, **d) + self._spot_to_global_tid[(s_glob, sp_i)] = gtid + + for u, v, edata in G_local.edges(data=True): + ed = dict(edata) + if "parent_track_id" in ed: + ed["parent_track_id"] = local_to_global.get(int(ed["parent_track_id"]), int(ed["parent_track_id"])) + if "child_track_id" in ed: + ed["child_track_id"] = local_to_global.get(int(ed["child_track_id"]), int(ed["child_track_id"])) + G_global.add_edge(nid_map[u], nid_map[v], **ed) + + remapped_win_events: list[LineageEvent] = [] + for ev in G_local.graph.get("lineage_events", []): + remapped_win_events.append( + LineageEvent( + event_type=ev.event_type, + scan_idx_from=ev.scan_idx_from + win_start, + scan_idx_to=ev.scan_idx_to + win_start, + parent_track_ids=[local_to_global.get(int(p), int(p)) for p in ev.parent_track_ids], + child_track_ids=[local_to_global.get(int(c), int(c)) for c in ev.child_track_ids], + intensity_ratio=ev.intensity_ratio, + mean_distance=ev.mean_distance, + confidence=ev.confidence, + timestamp_from=ev.timestamp_from, + timestamp_to=ev.timestamp_to, + split_subtype=ev.split_subtype, + delta_orientation_norm=ev.delta_orientation_norm, + delta_d_norm=ev.delta_d_norm, + ) + ) + all_events = [*self._committed_events, *remapped_win_events] + G_global.graph["window_lineage_events"] = remapped_win_events + G_global.graph["lineage_events"] = all_events + G_global.graph["gap_closed_count"] = G_local.graph.get("gap_closed_count", 0) + + w_rows = tracks_to_table(G_global) + for row in w_rows: + gtid = int(row["track_id"]) + s_i = int(row["scan_idx"]) + if gtid not in self._birth_anchor_by_tid or s_i < int(self._birth_anchor_by_tid[gtid]["scan_idx"]): + self._birth_anchor_by_tid[gtid] = dict(row) + return G_global, w_rows, all_events + + def _evaluate_pending_audits( + self, + scan_idx: int, + window_rows: list[dict[str, Any]], + kin_by_tid: dict[int, GrainKinematics], + validity_epsilon: float, + ) -> list[SimToRealAuditRecord]: + """Evaluate FAL Eq. (4) $\\Delta_{\\text{gap}}$ for zoom predictions targeting ``scan_idx``.""" + pending = self._pending_zoom_targets.pop(scan_idx, []) + if not pending: + return [] + + obs_at_scan = [r for r in window_rows if int(r["scan_idx"]) == scan_idx] + if not obs_at_scan: + return [] + + by_tid: dict[int, dict[str, Any]] = {int(r["track_id"]): r for r in obs_at_scan} + by_root: dict[int, list[dict[str, Any]]] = {} + for r in obs_at_scan: + tid = int(r["track_id"]) + gk = kin_by_tid.get(tid) + rtid = int(gk.root_track_id) if gk is not None and gk.root_track_id > 0 else tid + by_root.setdefault(rtid, []).append(r) + + records: list[SimToRealAuditRecord] = [] + for tgt in pending: + matched_obs = by_tid.get(tgt.track_id) + if matched_obs is None: + cands = by_root.get(tgt.root_track_id, []) + if cands: + pm, pc, pd = tgt.predicted_setpoint + matched_obs = min( + cands, + key=lambda r: ( + (float(r["centroid_mu"]) - pm) ** 2 + + (float(r["centroid_chi"]) - pc) ** 2 + + (float(r["centroid_d"]) - pd) ** 2 + ), + ) + if matched_obs is None: + continue + obs_c = ( + float(matched_obs["centroid_mu"]), + float(matched_obs["centroid_chi"]), + float(matched_obs["centroid_d"]), + ) + d_gap, m2, in_95, in_valid = compute_sim_to_real_gap( + tgt.predicted_setpoint, + tgt.predictive_std, + obs_c, + validity_epsilon=validity_epsilon, + ) + rec = SimToRealAuditRecord( + source_scan_idx=tgt.scan_idx, + eval_scan_idx=scan_idx, + track_id=tgt.track_id, + root_track_id=tgt.root_track_id, + execution_mode=tgt.execution_mode, + actuated=tgt.actuate, + hypothesis=tgt.hypothesis, + predicted_setpoint=tgt.predicted_setpoint, + predictive_std=tgt.predictive_std, + observed_centroid=obs_c, + scan_half_widths=tgt.scan_half_widths, + setpoint_hit=tgt.contains_point(*obs_c), + delta_gap=d_gap, + mahalanobis_sq=m2, + within_95pct_ci=in_95, + within_validity_domain=in_valid, + ) + records.append(rec) + self._audit_records.append(rec) + return records def step( self, @@ -213,23 +510,40 @@ def step( timestamp: str | None = None, stimulus: ScanStimulusPoint | None = None, ) -> StreamingStepResult: - """Ingest one new 3D scan ``t`` causally and emit tracking + autonomous zoom targets.""" + """Ingest one new 3D scan ``t`` causally and emit tracking + FAL Level 3 zoom targets.""" t0 = time.perf_counter() scan_idx = len(self._scan_tables) - vol, resolved_name, resolved_ts, active_cal = self._resolve_volume_and_meta( + odd = self.trigger_policy.resolved_odd() + + vol, raw_thr, resolved_name, resolved_ts, active_cal = self._resolve_volume_and_meta( volume_or_path, scan_name, timestamp ) if stimulus is not None and resolved_ts is None and stimulus.timestamp is not None: resolved_ts = stimulus.timestamp + # Upstream instrument health W(s_t) & ODD environment verification + health = self._compute_instrument_health(vol, min_health=odd.min_instrument_health) + env_ok, violations = odd.check_sample_environment(stimulus) + if health < odd.min_instrument_health: + violations.append(f"instrument_health_low={health:.3f}<{odd.min_instrument_health:.3f}") + + prev_lat_ok, _ = odd.evaluate_latency_budget(self._last_step_latency_sec) + if not env_ok or health < odd.min_instrument_health: + fal_active: FALActiveLevel = "L1_halt" + elif not prev_lat_ok: + fal_active = "L2_fallback" + violations.append(f"prev_step_latency_exceeded={self._last_step_latency_sec:.3f}s") + else: + fal_active = "L3" + # 1. Strictly causal trailing-window Otsu threshold (scans max(0, t - W + 1) .. t only!) - raw_thr = float(otsu_threshold(vol)) - self._raw_thresholds.append(raw_thr) + if health >= odd.min_instrument_health or not self._raw_thresholds: + self._raw_thresholds.append(raw_thr) win_lo = max(0, len(self._raw_thresholds) - self.smooth_window) causal_thr = float(np.median(self._raw_thresholds[win_lo:])) self._causal_thresholds.append(causal_thr) - # 2. Classical 3D LoG + watershed segmentation & calibrated feature + uncertainty extraction + # 2. Classical 3D LoG + watershed segmentation & calibrated feature + kurtosis extraction seg = segment_classical( vol, threshold=causal_thr, @@ -237,7 +551,13 @@ def step( seed_response_percentile=self.seed_response_percentile, ) labels = relabel_sequential(remove_small_objects(seg.labeled_volume, min_size=self.min_spot_voxels)) - spots = extract_instance_table(labels, vol, calibration=active_cal) + spots = ( + extract_instance_table(labels, vol, calibration=active_cal) if health >= odd.min_instrument_health else [] + ) + + # Calibrate BulkReferencePrior on first nominal scan if not explicitly supplied + if self._reference_prior is None and spots and health >= odd.min_instrument_health: + self._reference_prior = BulkReferencePrior.from_spots(spots) # 3. Batched DINOv2 multiview embeddings for all spots in scan t if self._multiview_encoder is not None and spots: @@ -261,24 +581,60 @@ def step( self._scan_tables.append(spots) if stimulus is not None: self._stimuli[scan_idx] = stimulus + if stimulus.elapsed_s is not None and math.isfinite(stimulus.elapsed_s): + self._scan_elapsed_s[scan_idx] = float(stimulus.elapsed_s) - # 4. Build causal trajectory DAG over scans 0 .. t - G = build_tracks( - self._scan_tables, - cost_fn=self._cost_fn, - max_cost=self.max_cost, - gap_closing_config=self.gap_config, - split_merge_config=self.split_merge_config, - scan_timestamps=self._scan_timestamps, - ) - t_table = tracks_to_table(G) - lineage_events: list[LineageEvent] = list(G.graph.get("lineage_events", [])) + # 4. Build bounded O(1) sliding-window causal trajectory DAG + G, w_rows, lineage_events = self._build_window_dag(scan_idx) new_events = [ev for ev in lineage_events if ev.scan_idx_to == scan_idx] - # 5. Compute causal kinematics & incremental ROI-cached fracture precursors (only current vol in RAM!) - kin_list = compute_grain_kinematics(t_table) + # Prepend lightweight historical birth/ancestor anchors for exact root-referenced strain in O(W) + win_min_scan = min((int(r["scan_idx"]) for r in w_rows), default=scan_idx) + anchor_rows: list[dict[str, Any]] = [] + if win_min_scan > 0: + needed_tids = {int(r["track_id"]) for r in w_rows} + # Walk parent links in _birth_anchor_by_tid to include root ancestors + queue = list(needed_tids) + visited_anc: set[int] = set() + while queue: + cur_t = queue.pop() + if cur_t in visited_anc: + continue + visited_anc.add(cur_t) + anc = self._birth_anchor_by_tid.get(cur_t) + if anc is not None: + if int(anc["scan_idx"]) < win_min_scan: + anchor_rows.append(anc) + raw_p = anc.get("parent_track_ids", "") + ptids = ( + [int(x) for x in raw_p.split(";") if x.strip()] + if isinstance(raw_p, str) + else [int(x) for x in raw_p] + if isinstance(raw_p, list) + else [] + ) + for pt in ptids: + if pt not in visited_anc: + queue.append(pt) + + kin_input = [*anchor_rows, *w_rows] + kin_list = compute_grain_kinematics( + kin_input, + scan_elapsed_s=self._scan_elapsed_s if self._scan_elapsed_s else None, + ) + kin_by_tid = {k.track_id: k for k in kin_list} + + # Evaluate FAL Eq. (4) Sim-to-Real Gap for previous zoom targets scheduled for scan_idx + step_audits = self._evaluate_pending_audits( + scan_idx, + w_rows, + kin_by_tid, + validity_epsilon=odd.validity_epsilon, + ) + + # 5. Compute incremental ROI-cached fracture precursors over active window (O(W)) prec_candidates, obs_scores = compute_fracture_precursors( - t_table, + w_rows, self.precursor_config, volumes={scan_idx: vol}, label_volumes={scan_idx: labels}, @@ -292,7 +648,7 @@ def step( zoom_targets = select_zoom_targets( current_scan_idx=scan_idx, scan_name=resolved_name, - track_table=t_table, + track_table=w_rows, kinematics=kin_list, obs_precursor_scores=obs_scores, policy=self.trigger_policy, @@ -300,17 +656,28 @@ def step( detector=self.detector, stimulus=stimulus, last_triggered_scan_by_lineage=self._cooldown_by_lineage, + zoom_counts_by_lineage=self._zoom_counts_by_lineage, + reference_prior=self._reference_prior, + instrument_health=health, + fal_level=fal_active, ) + if zoom_targets: + eval_offset = max(1, round(float(self.trigger_policy.lead_scans))) + self._pending_zoom_targets.setdefault(scan_idx + eval_offset, []).extend(zoom_targets) + self._graph = G - self._track_table = t_table + self._window_rows = w_rows self._kinematics = kin_list self._obs_precursor_scores = obs_scores self._precursor_candidates = prec_candidates self._all_zoom_targets.extend(zoom_targets) - n_active = sum(1 for row in t_table if int(row["scan_idx"]) == scan_idx) + n_active = sum(1 for row in w_rows if int(row["scan_idx"]) == scan_idx) dt = time.perf_counter() - t0 + self._last_step_latency_sec = dt + within_lat, _ = odd.evaluate_latency_budget(dt) + return StreamingStepResult( scan_idx=scan_idx, scan_name=resolved_name, @@ -324,4 +691,9 @@ def step( zoom_targets=zoom_targets, step_latency_sec=dt, stimulus=stimulus, + instrument_health=health, + fal_level_active=fal_active, + within_latency_budget=within_lat, + odd_violations=tuple(violations), + audit_records=step_audits, ) diff --git a/braggtrack/autonomous/trigger.py b/braggtrack/autonomous/trigger.py index b4b16f6..94fcf3f 100644 --- a/braggtrack/autonomous/trigger.py +++ b/braggtrack/autonomous/trigger.py @@ -1,11 +1,11 @@ """Autonomous DFXM "Scout-and-Zoom" trigger policy and BLISS/Ewoks setpoint extrusion. Evaluates active tracked reflections at scan ``t`` using strictly causal kinematics, -analytical centroid uncertainties, and multi-scan fracture precursor persistence to +analytical centroid uncertainties, standardized rocking-curve excess kurtosis $g_2$, +calibrated bulk reference priors, and multi-scan fracture precursor persistence to select high-priority candidate grains for zoomed Dark-Field X-ray Microscopy (DFXM) -rocking/mosaicity acquisitions. Motor setpoints are velocity-extrapolated to -``t + lead_scans`` so fast-shifting reflections (e.g. Ni-rich layered oxide H2 -> H3 -lattice collapse) stay centered in the narrow DFXM objective acceptance cone. +acquisitions at Facility Autonomy Level 3 (FAL L3). Motor setpoints are velocity-extrapolated +to ``t + lead_scans`` and clamped to an explicit :class:`OperationalDesignDomain`. """ from __future__ import annotations @@ -14,6 +14,15 @@ from dataclasses import dataclass from typing import TYPE_CHECKING, Any +from .odd import ( + BulkReferencePrior, + ExecutionMode, + FALActiveLevel, + HypothesisMode, + OperationalDesignDomain, + spot_kurtosis_non_gaussianity, +) + if TYPE_CHECKING: from braggtrack.io.crystallography import DetectorGeometry from braggtrack.io.models import AxisCalibration @@ -24,7 +33,7 @@ @dataclass(frozen=True) class ZoomTriggerPolicy: - """Decision thresholds, cooldowns, and scan-window geometry for autonomous DFXM zoom.""" + """Decision thresholds, hypothesis mode, ODD bounds, and window geometry for FAL Level 3 zoom.""" min_precursor_score: float = 0.40 min_persistence: int = 2 @@ -38,6 +47,38 @@ class ZoomTriggerPolicy: lead_scans: float = 1.0 window_sigma: float = 3.5 exclude_post_split_daughters: bool = True + hypothesis: HypothesisMode = "mechanical_fracture" + execution_mode: ExecutionMode = "replay" + odd: OperationalDesignDomain | None = None + mu_bounds: tuple[float, float] | None = None + chi_bounds: tuple[float, float] | None = None + d_bounds: tuple[float, float] | None = None + max_extrapolation_steps: float = 12.0 + exclude_border_truncated: bool = False + border_truncation_penalty: float = 0.65 + + def resolved_odd(self) -> OperationalDesignDomain: + """Return effective :class:`OperationalDesignDomain` merging policy-level motor overrides.""" + if self.odd is not None: + return OperationalDesignDomain( + mu_bounds=self.mu_bounds if self.mu_bounds is not None else self.odd.mu_bounds, + chi_bounds=self.chi_bounds if self.chi_bounds is not None else self.odd.chi_bounds, + d_bounds=self.d_bounds if self.d_bounds is not None else self.odd.d_bounds, + max_extrapolation_steps=self.odd.max_extrapolation_steps, + voltage_bounds_v=self.odd.voltage_bounds_v, + temperature_bounds_c=self.odd.temperature_bounds_c, + max_zooms_per_lineage=self.odd.max_zooms_per_lineage, + scan_cadence_sec=self.odd.scan_cadence_sec, + latency_safety_factor_kappa=self.odd.latency_safety_factor_kappa, + min_instrument_health=self.odd.min_instrument_health, + validity_epsilon=self.odd.validity_epsilon, + ) + return OperationalDesignDomain( + mu_bounds=self.mu_bounds, + chi_bounds=self.chi_bounds, + d_bounds=self.d_bounds, + max_extrapolation_steps=self.max_extrapolation_steps, + ) @dataclass(frozen=True) @@ -66,6 +107,14 @@ class ZoomTarget: trigger_reasons: tuple[str, ...] scattering_angles: dict[str, float] | None = None operando_state: dict[str, Any] | None = None + predictive_std: tuple[float, float, float] = (0.0, 0.0, 0.0) + kurtosis_non_gaussianity: float = 0.0 + discovery_potential: float = 0.0 + instrument_health: float = 1.0 + hypothesis: HypothesisMode = "mechanical_fracture" + execution_mode: ExecutionMode = "replay" + actuate: bool = False + fal_level: FALActiveLevel = "L3" def contains_point(self, mu: float, chi: float, d: float) -> bool: """Return True if ``(mu, chi, d)`` lies inside ``predicted_setpoint ± scan_half_widths``.""" @@ -78,15 +127,22 @@ def to_bliss_command(self) -> dict[str, Any]: pm, pc, pd = self.predicted_setpoint hm, hc, hd = self.scan_half_widths em, ec, ed = self.centroid_err + sm, sc, sd = self.predictive_std + disc = self.discovery_potential if self.discovery_potential > 0.0 else self.priority_score cmd: dict[str, Any] = { "schema_version": "bliss_dfxm_zoom.v1", "action": "dfxm_high_res_zoom", + "actuate": bool(self.actuate), + "execution_mode": self.execution_mode, + "fal_level": self.fal_level, + "hypothesis": self.hypothesis, "source_scan_idx": int(self.scan_idx), "source_scan_name": self.scan_name, "track_id": int(self.track_id), "root_track_id": int(self.root_track_id), "priority_rank": int(self.priority_rank), "priority_score": round(float(self.priority_score), 4), + "discovery_potential": round(float(disc), 4), "lead_scans": round(float(self.lead_scans), 3), "target_motors": { "mu": round(float(pm), 6), @@ -107,6 +163,9 @@ def to_bliss_command(self) -> dict[str, Any]: "centroid_mu_err": round(float(em), 6), "centroid_chi_err": round(float(ec), 6), "centroid_d_err": round(float(ed), 6), + "predictive_mu_std": round(float(sm), 6), + "predictive_chi_std": round(float(sc), 6), + "predictive_d_std": round(float(sd), 6), "strain_err": round(float(self.strain_err), 7), }, "diagnostics": { @@ -115,6 +174,8 @@ def to_bliss_command(self) -> dict[str, Any]: "persistence_scans": int(self.persistence_scans), "roi_subpeak_count": int(self.roi_subpeak_count), "anisotropy": round(float(self.anisotropy), 4), + "kurtosis_non_gaussianity": round(float(self.kurtosis_non_gaussianity), 4), + "instrument_health": round(float(self.instrument_health), 4), "lineage_strain": round(float(self.lineage_strain), 6), "strain_rate": round(float(self.strain_rate), 6), "assignment_margin": ( @@ -155,6 +216,53 @@ def _trailing_persistence( return run +def compute_predictive_std( + obs: dict[str, Any], + kin: GrainKinematics | None, + obs_pos_in_kin: int, + *, + lead_scans: float = 1.0, + calibration: AxisCalibration | None = None, +) -> tuple[float, float, float]: + """Compute 1-sigma predictive transition uncertainty $(\\sigma_{\\text{pred},\\mu}, \\sigma_{\\text{pred},\\chi}, \\sigma_{\\text{pred},d})$.""" + if kin is not None and 0 <= obs_pos_in_kin < len(kin.scan_indices): + v_mu = float(kin.rate_mu[obs_pos_in_kin]) if len(kin.rate_mu) > obs_pos_in_kin else 0.0 + v_chi = float(kin.rate_chi[obs_pos_in_kin]) if len(kin.rate_chi) > obs_pos_in_kin else 0.0 + v_d = float(kin.rate_d[obs_pos_in_kin]) if len(kin.rate_d) > obs_pos_in_kin else 0.0 + err_mu = float(kin.centroid_mu_err[obs_pos_in_kin]) if len(kin.centroid_mu_err) > obs_pos_in_kin else 0.0 + err_chi = float(kin.centroid_chi_err[obs_pos_in_kin]) if len(kin.centroid_chi_err) > obs_pos_in_kin else 0.0 + err_d = float(kin.centroid_d_err[obs_pos_in_kin]) if len(kin.centroid_d_err) > obs_pos_in_kin else 0.0 + else: + v_mu = v_chi = v_d = 0.0 + err_mu = float(obs.get("centroid_mu_err", 0.0)) + err_chi = float(obs.get("centroid_chi_err", 0.0)) + err_d = float(obs.get("centroid_d_err", 0.0)) + + step_mu = abs(float(calibration.mu_step)) if calibration is not None else float(obs.get("step_mu", 1.0)) + step_chi = abs(float(calibration.chi_step)) if calibration is not None else float(obs.get("step_chi", 1.0)) + step_d = abs(float(calibration.d_step)) if calibration is not None else float(obs.get("step_d", 1.0)) + + std_mu = math.sqrt(max(float(obs.get("cov_zz", obs.get("cov_mu_mu", 0.0))), 0.0)) + std_chi = math.sqrt(max(float(obs.get("cov_xx", obs.get("cov_chi_chi", 0.0))), 0.0)) + std_d = math.sqrt(max(float(obs.get("cov_yy", obs.get("cov_d_d", 0.0))), 0.0)) + + # Propagated 1-step linear extrapolation variance + intragranular sub-domain spread + discretization floor + vel_factor_sq = 1.0 + 2.0 * (float(lead_scans) ** 2) + sig_mu = max( + math.sqrt(std_mu * std_mu + vel_factor_sq * err_mu * err_mu + (0.25 * lead_scans * v_mu) ** 2), + 0.35 * max(step_mu, 1e-12), + ) + sig_chi = max( + math.sqrt(std_chi * std_chi + vel_factor_sq * err_chi * err_chi + (0.25 * lead_scans * v_chi) ** 2), + 0.35 * max(step_chi, 1e-12), + ) + sig_d = max( + math.sqrt(std_d * std_d + vel_factor_sq * err_d * err_d + (0.25 * lead_scans * v_d) ** 2), + 0.35 * max(step_d, 1e-12), + ) + return (sig_mu, sig_chi, sig_d) + + def compute_target_geometry( obs: dict[str, Any], kin: GrainKinematics | None, @@ -164,6 +272,7 @@ def compute_target_geometry( window_sigma: float = 3.5, calibration: AxisCalibration | None = None, detector: DetectorGeometry | None = None, + max_extrapolation_steps: float | None = None, ) -> tuple[ tuple[float, float, float], tuple[float, float, float], @@ -189,22 +298,33 @@ def compute_target_geometry( err_chi = float(obs.get("centroid_chi_err", 0.0)) err_d = float(obs.get("centroid_d_err", 0.0)) - pred_mu = cur_mu + lead_scans * v_mu - pred_chi = cur_chi + lead_scans * v_chi - pred_d = cur_d + lead_scans * v_d - - step_mu = abs(float(calibration.mu_step)) if calibration is not None else 1.0 - step_chi = abs(float(calibration.chi_step)) if calibration is not None else 1.0 - step_d = abs(float(calibration.d_step)) if calibration is not None else 1.0 + step_mu = abs(float(calibration.mu_step)) if calibration is not None else float(obs.get("step_mu", 1.0)) + step_chi = abs(float(calibration.chi_step)) if calibration is not None else float(obs.get("step_chi", 1.0)) + step_d = abs(float(calibration.d_step)) if calibration is not None else float(obs.get("step_d", 1.0)) + + dm = lead_scans * v_mu + dc = lead_scans * v_chi + dd = lead_scans * v_d + if max_extrapolation_steps is not None and max_extrapolation_steps > 0.0: + cap_m = float(max_extrapolation_steps) * max(step_mu, 1e-12) + cap_c = float(max_extrapolation_steps) * max(step_chi, 1e-12) + cap_d = float(max_extrapolation_steps) * max(step_d, 1e-12) + dm = min(max(dm, -cap_m), cap_m) + dc = min(max(dc, -cap_c), cap_c) + dd = min(max(dd, -cap_d), cap_d) + + pred_mu = cur_mu + dm + pred_chi = cur_chi + dc + pred_d = cur_d + dd std_mu = math.sqrt(max(float(obs.get("cov_zz", obs.get("cov_mu_mu", 0.0))), 0.0)) std_chi = math.sqrt(max(float(obs.get("cov_xx", obs.get("cov_chi_chi", 0.0))), 0.0)) std_d = math.sqrt(max(float(obs.get("cov_yy", obs.get("cov_d_d", 0.0))), 0.0)) # Half-width covers intragranular spread (window_sigma * std) + centroid + drift uncertainty, floored at 1.5 steps. - drift_pad_mu = 0.35 * abs(lead_scans * v_mu) - drift_pad_chi = 0.35 * abs(lead_scans * v_chi) - drift_pad_d = 0.35 * abs(lead_scans * v_d) + drift_pad_mu = 0.35 * abs(dm) + drift_pad_chi = 0.35 * abs(dc) + drift_pad_d = 0.35 * abs(dd) half_mu = max(window_sigma * (std_mu + err_mu) + drift_pad_mu, 1.5 * step_mu) half_chi = max(window_sigma * (std_chi + err_chi) + drift_pad_chi, 1.5 * step_chi) @@ -241,9 +361,21 @@ def select_zoom_targets( detector: DetectorGeometry | None = None, stimulus: ScanStimulusPoint | None = None, last_triggered_scan_by_lineage: dict[int, int] | None = None, + zoom_counts_by_lineage: dict[int, int] | None = None, + reference_prior: BulkReferencePrior | None = None, + instrument_health: float = 1.0, + fal_level: FALActiveLevel = "L3", ) -> list[ZoomTarget]: """Select, rank, and extrapolate autonomous DFXM zoom targets at ``current_scan_idx``.""" pol = policy or ZoomTriggerPolicy() + odd = pol.resolved_odd() + + # FAL Eq. (6) & ODD safety: halt autonomous target emission on beam dumps or ODD sample excursions + health = min(max(float(instrument_health), 0.0), 1.0) + env_ok, _ = odd.check_sample_environment(stimulus) + if not env_ok or fal_level == "L1_halt" or health < odd.min_instrument_health: + return [] + kin_by_tid = {k.track_id: k for k in kinematics} scores_by_tid: dict[int, list[ObservationPrecursorScore]] = {} score_at_current: dict[int, ObservationPrecursorScore] = {} @@ -253,17 +385,26 @@ def select_zoom_targets( score_at_current[sc.track_id] = sc cooldown_map = last_triggered_scan_by_lineage if last_triggered_scan_by_lineage is not None else {} + dose_map = zoom_counts_by_lineage if zoom_counts_by_lineage is not None else {} operando_dict = stimulus.to_dict() if stimulus is not None else None dq_dv_boost = 0.0 if stimulus is not None and stimulus.dq_dv is not None and math.isfinite(stimulus.dq_dv): dq_dv_boost = min(0.08, 0.08 * min(1.0, abs(float(stimulus.dq_dv)) / 250.0)) + k_thresh = reference_prior.kurtosis_threshold if reference_prior is not None else 0.75 + should_actuate = bool(pol.execution_mode == "active" and fal_level == "L3") + raw_candidates: list[ZoomTarget] = [] for obs in track_table: if int(obs["scan_idx"]) != current_scan_idx: continue tid = int(obs["track_id"]) - if pol.exclude_post_split_daughters and str(obs.get("lineage_role", "")) == "split_daughter": + role = str(obs.get("lineage_role", "")) + if pol.exclude_post_split_daughters and role in ("split_child", "split_daughter"): + continue + + touches_rocking = bool(obs.get("touches_rocking_border", False)) + if pol.exclude_border_truncated and touches_rocking: continue intensity = float(obs.get("integrated_intensity", 0.0)) @@ -286,41 +427,81 @@ def select_zoom_targets( prev_trig = cooldown_map.get(root_tid) if prev_trig is not None and (current_scan_idx - prev_trig) < pol.cooldown_scans: continue - - sc_now = score_at_current.get(tid) - if sc_now is None or sc_now.precursor_score < pol.min_precursor_score: - continue - if sc_now.roi_subpeak_count < pol.min_subpeaks: + if odd.max_zooms_per_lineage is not None and dose_map.get(root_tid, 0) >= int(odd.max_zooms_per_lineage): continue + sc_now = score_at_current.get(tid) + prec_score = float(sc_now.precursor_score) if sc_now is not None else 0.0 + subpeaks = int(sc_now.roi_subpeak_count) if sc_now is not None else 1 + aniso = float(sc_now.anisotropy) if sc_now is not None else 1.0 pers = _trailing_persistence(scores_by_tid.get(tid, []), current_scan_idx, pol.min_precursor_score) - if pers < pol.min_persistence: - continue - s_rate = float(kin.strain_rate[pos]) if len(kin.strain_rate) > pos else 0.0 if abs(s_rate) < pol.min_strain_rate: continue + if subpeaks < pol.min_subpeaks: + continue + + g2_val = spot_kurtosis_non_gaussianity(obs) + reasons: list[str] = [f"hypothesis={pol.hypothesis}"] + + # FAL Level 3 Condition (iii): hypothesis-conditioned candidate admission & heuristic H(x) + if pol.hypothesis == "mechanical_fracture": + if sc_now is None or prec_score < pol.min_precursor_score or pers < pol.min_persistence: + continue + priority = ( + 0.55 * prec_score + + 0.20 * min(1.0, pers / 4.0) + + 0.15 * min(1.0, max(0, subpeaks - 1) * 0.5) + + 0.10 * min(1.0, abs(s_rate) / 0.005) + + dq_dv_boost + ) + reasons.extend( + [ + f"precursor_score={prec_score:.3f}>={pol.min_precursor_score:.2f}", + f"persistence={pers}_scans", + ] + ) + elif pol.hypothesis == "phase_nucleation": + min_phase_rate = max(pol.min_strain_rate, 0.0015) + if abs(s_rate) < min_phase_rate: + continue + g2_d = abs(float(obs.get("kurtosis_d", 0.0))) + priority = ( + 0.65 * min(1.0, abs(s_rate) / 0.005) + + 0.15 * min(1.0, g2_d / max(k_thresh, 0.25)) + + 0.10 * prec_score + + 0.10 * min(1.0, pers / 4.0) + + 2.0 * dq_dv_boost + ) + reasons.append(f"phase_strain_rate={s_rate:+.5f}/scan") + elif pol.hypothesis == "intragranular_disorder": + if g2_val < k_thresh: + continue + priority = ( + 0.70 * min(1.0, g2_val / max(2.0 * k_thresh, 0.50)) + + 0.15 * prec_score + + 0.15 * min(1.0, max(0.0, aniso - 1.0) / 2.0) + + dq_dv_boost + ) + reasons.append(f"kurtosis_g2={g2_val:.3f}>={k_thresh:.3f}") + else: + raise ValueError(f"Unsupported hypothesis mode: {pol.hypothesis!r}") + + if touches_rocking: + priority *= float(pol.border_truncation_penalty) + reasons.append("rocking_border_truncated") + + # FAL Eq. (6): D(x) = H(x) * W(s_t) + disc_potential = priority * health l_strain = float(kin.lineage_strain[pos]) if len(kin.lineage_strain) > pos else float(kin.strain[pos]) s_err = float(kin.lineage_strain_err[pos]) if len(kin.lineage_strain_err) > pos else 0.0 - priority = ( - 0.55 * float(sc_now.precursor_score) - + 0.20 * min(1.0, pers / 4.0) - + 0.15 * min(1.0, max(0, sc_now.roi_subpeak_count - 1) * 0.5) - + 0.10 * min(1.0, abs(s_rate) / 0.005) - + dq_dv_boost - ) - - reasons: list[str] = [ - f"precursor_score={sc_now.precursor_score:.3f}>={pol.min_precursor_score:.2f}", - f"persistence={pers}_scans", - ] - if sc_now.roi_subpeak_count >= 2: - reasons.append(f"bimodal_subpeaks={sc_now.roi_subpeak_count}") - if sc_now.anisotropy >= 2.0: - reasons.append(f"mosaicity_anisotropy={sc_now.anisotropy:.2f}") - if abs(s_rate) >= 0.001: + if subpeaks >= 2: + reasons.append(f"bimodal_subpeaks={subpeaks}") + if aniso >= 2.0: + reasons.append(f"mosaicity_anisotropy={aniso:.2f}") + if abs(s_rate) >= 0.001 and pol.hypothesis != "phase_nucleation": reasons.append(f"strain_rate={s_rate:+.5f}/scan") if dq_dv_boost > 0.02 and stimulus is not None and stimulus.voltage_v is not None: reasons.append(f"redox_active_E={stimulus.voltage_v:.3f}V") @@ -333,6 +514,30 @@ def select_zoom_targets( window_sigma=pol.window_sigma, calibration=calibration, detector=detector, + max_extrapolation_steps=odd.max_extrapolation_steps, + ) + pred_c, half_w, was_clamped = odd.clamp_setpoint(pred_c, half_w) + if was_clamped: + reasons.append("clamped_to_motor_bounds") + if detector is not None: + if calibration is not None and calibration.calibrated: + z_idx = (pred_c[0] - calibration.mu_origin) / ( + calibration.mu_step if calibration.mu_step != 0 else 1.0 + ) + x_px = (pred_c[1] - calibration.chi_origin) / ( + calibration.chi_step if calibration.chi_step != 0 else 1.0 + ) + y_px = (pred_c[2] - calibration.d_origin) / (calibration.d_step if calibration.d_step != 0 else 1.0) + else: + z_idx, y_px, x_px = pred_c[0], pred_c[2], pred_c[1] + scat = detector.spot_to_scattering(z_idx, y_px, x_px) + + pred_std = compute_predictive_std( + obs, + kin, + pos, + lead_scans=pol.lead_scans, + calibration=calibration, ) raw_candidates.append( @@ -342,11 +547,11 @@ def select_zoom_targets( track_id=tid, root_track_id=root_tid, priority_rank=0, - priority_score=float(priority), - precursor_score=float(sc_now.precursor_score), + priority_score=float(disc_potential), + precursor_score=prec_score, persistence_scans=pers, - roi_subpeak_count=int(sc_now.roi_subpeak_count), - anisotropy=float(sc_now.anisotropy), + roi_subpeak_count=subpeaks, + anisotropy=aniso, lineage_strain=l_strain, strain_err=s_err, strain_rate=s_rate, @@ -359,6 +564,14 @@ def select_zoom_targets( trigger_reasons=tuple(reasons), scattering_angles=scat, operando_state=operando_dict, + predictive_std=pred_std, + kurtosis_non_gaussianity=g2_val, + discovery_potential=float(disc_potential), + instrument_health=health, + hypothesis=pol.hypothesis, + execution_mode=pol.execution_mode, + actuate=should_actuate, + fal_level=fal_level, ) ) @@ -367,6 +580,7 @@ def select_zoom_targets( ranked: list[ZoomTarget] = [] for rank_idx, tgt in enumerate(selected, start=1): cooldown_map[tgt.root_track_id] = current_scan_idx + dose_map[tgt.root_track_id] = dose_map.get(tgt.root_track_id, 0) + 1 ranked.append( ZoomTarget( scan_idx=tgt.scan_idx, @@ -391,6 +605,14 @@ def select_zoom_targets( trigger_reasons=tgt.trigger_reasons, scattering_angles=tgt.scattering_angles, operando_state=tgt.operando_state, + predictive_std=tgt.predictive_std, + kurtosis_non_gaussianity=tgt.kurtosis_non_gaussianity, + discovery_potential=tgt.discovery_potential, + instrument_health=tgt.instrument_health, + hypothesis=tgt.hypothesis, + execution_mode=tgt.execution_mode, + actuate=tgt.actuate, + fal_level=tgt.fal_level, ) ) return ranked diff --git a/braggtrack/cli/run_pipeline.py b/braggtrack/cli/run_pipeline.py index 95adcaf..bf192f5 100644 --- a/braggtrack/cli/run_pipeline.py +++ b/braggtrack/cli/run_pipeline.py @@ -138,6 +138,13 @@ def _merge_config_overrides(args: argparse.Namespace) -> dict[str, Any]: cfg_data = json.loads(Path(args.config).read_text()) if not isinstance(cfg_data, dict): raise ValueError("--config must point to a JSON object") + allowed_keys = set(effective.keys()) | {"root"} + unknown_keys = sorted(set(cfg_data.keys()) - allowed_keys) + if unknown_keys: + raise ValueError( + f"Unknown --config override key(s): {', '.join(unknown_keys)}. " + f"Allowed keys: {', '.join(sorted(allowed_keys))}" + ) effective.update(cfg_data) return effective diff --git a/braggtrack/cli/watch_autonomous.py b/braggtrack/cli/watch_autonomous.py index 605a223..c34ec5b 100644 --- a/braggtrack/cli/watch_autonomous.py +++ b/braggtrack/cli/watch_autonomous.py @@ -1,4 +1,4 @@ -"""Autonomous DFXM "Scout-and-Zoom" beamline watcher and causal replay CLI.""" +"""Autonomous DFXM "Scout-and-Zoom" beamline watcher, FAL Staged Certification, and causal replay CLI.""" from __future__ import annotations @@ -9,6 +9,7 @@ from braggtrack.autonomous import ( CausalStreamingTracker, + OperationalDesignDomain, ZoomTriggerPolicy, evaluate_causal_replay, ) @@ -20,6 +21,7 @@ resolve_dataset_root, synchronize_to_scans, ) +from braggtrack.io.nexus import _open_h5_readonly, _require_h5py, _resolve_volume_dataset from braggtrack.semantic import DEFAULT_DINO_MODEL from braggtrack.tracking.precursors import PrecursorConfig @@ -34,9 +36,15 @@ def build_parser() -> argparse.ArgumentParser: ) parser.add_argument( "--mode", - choices=("replay", "watch"), + choices=("replay", "shadow", "watch", "active"), default="replay", - help="'replay' benchmarks causal closed-loop triggers on an existing sequence; 'watch' polls for new scans", + help="FAL certification stage: 'replay' (offline), 'shadow'/'watch' (live non-actuating), or 'active' (closed-loop)", + ) + parser.add_argument( + "--hypothesis", + choices=("mechanical_fracture", "phase_nucleation", "intragranular_disorder"), + default="mechanical_fracture", + help="FAL Level 3 experimental hypothesis governing heuristic target prioritization", ) parser.add_argument("--outdir", default="artifacts/autonomous", help="Output directory for zoom triggers & logs") parser.add_argument( @@ -59,13 +67,69 @@ def build_parser() -> argparse.ArgumentParser: parser.add_argument("--max-triggers-per-scan", type=int, default=2, help="Maximum zoom targets emitted per scan") parser.add_argument("--lead-scans", type=float, default=1.0, help="Velocity extrapolation lead (in scan steps)") parser.add_argument("--window-sigma", type=float, default=3.5, help="Scan half-width sigma multiplier") + parser.add_argument( + "--mu-bounds", + nargs=2, + type=float, + default=None, + metavar=("MIN", "MAX"), + help="Optional ODD motor soft-limits for rocking angle mu", + ) + parser.add_argument( + "--chi-bounds", + nargs=2, + type=float, + default=None, + metavar=("MIN", "MAX"), + help="Optional ODD motor soft-limits for roll angle chi", + ) + parser.add_argument( + "--d-bounds", + nargs=2, + type=float, + default=None, + metavar=("MIN", "MAX"), + help="Optional ODD motor soft-limits for d / 2theta / obpitch", + ) + parser.add_argument( + "--voltage-bounds", + nargs=2, + type=float, + default=None, + metavar=("V_MIN", "V_MAX"), + help="Optional ODD electrochemical voltage window (V); halts actuation on excursion", + ) + parser.add_argument( + "--max-zooms-per-lineage", + type=int, + default=None, + help="Optional ODD per-grain maximum high-res zoom count to cap X-ray dose", + ) + parser.add_argument( + "--scan-cadence-sec", + type=float, + default=None, + help="Expected beamline scan cadence t_decision (s) for FAL latency budget verification", + ) + parser.add_argument( + "--sliding-window", + type=int, + default=24, + help="Bounded causal tracking window size in scans (default: 24 for O(1) latency)", + ) parser.add_argument( "--zoom-budget", type=int, default=None, help="Optional cap on total zoom acquisitions during --mode replay baseline comparison", ) - parser.add_argument("--poll-interval", type=float, default=0.5, help="Directory poll interval (s) in --mode watch") + parser.add_argument("--poll-interval", type=float, default=0.5, help="Directory poll interval (s) in live modes") + parser.add_argument( + "--settle-sec", + type=float, + default=0.03, + help="File size/mtime quiescence window (s) before reading newly created HDF5 scans", + ) parser.add_argument( "--max-scans", type=int, @@ -76,7 +140,7 @@ def build_parser() -> argparse.ArgumentParser: "--max-idle-polls", type=int, default=20, - help="Stop --mode watch after this many consecutive polls with no new scans (0 = run indefinitely)", + help="Stop live watcher after this many consecutive polls with no ready scans (0 = run indefinitely)", ) return parser @@ -88,6 +152,30 @@ def _load_optional_calibration(path_str: str | None) -> AxisCalibration | None: return AxisCalibration.from_dict(raw) +def _is_hdf5_quiescent_and_readable(path: Path, *, settle_sec: float = 0.03) -> bool: + """Verify file size/mtime stability and SWMR HDF5 dataset readability before ingestion.""" + try: + st0 = path.stat() + if st0.st_size <= 0: + return False + if settle_sec > 0.0: + time.sleep(settle_sec) + st1 = path.stat() + if st1.st_size != st0.st_size or st1.st_mtime_ns != st0.st_mtime_ns: + return False + h5py = _require_h5py() + with _open_h5_readonly(h5py, path, swmr=True) as handle: + ds_path = _resolve_volume_dataset(handle, h5py, auto_discover=True) + ds = handle[ds_path] + if ds.ndim != 3 or any(int(dim) <= 0 for dim in ds.shape): + return False + # Probe trailing frame voxel to catch incomplete LIMA chunk flushes + _ = ds[-1, 0:1, 0:1] + return True + except (OSError, KeyError, ValueError, RuntimeError): + return False + + def main(argv: list[str] | None = None) -> int: args = build_parser().parse_args(argv) root = resolve_dataset_root(args.root) @@ -100,6 +188,16 @@ def main(argv: list[str] | None = None) -> int: score_threshold=float(args.min_precursor_score), min_persistence=int(args.min_persistence), ) + odd = OperationalDesignDomain( + mu_bounds=(float(args.mu_bounds[0]), float(args.mu_bounds[1])) if args.mu_bounds else None, + chi_bounds=(float(args.chi_bounds[0]), float(args.chi_bounds[1])) if args.chi_bounds else None, + d_bounds=(float(args.d_bounds[0]), float(args.d_bounds[1])) if args.d_bounds else None, + voltage_bounds_v=(float(args.voltage_bounds[0]), float(args.voltage_bounds[1])) + if args.voltage_bounds + else None, + max_zooms_per_lineage=args.max_zooms_per_lineage, + scan_cadence_sec=args.scan_cadence_sec, + ) policy = ZoomTriggerPolicy( min_precursor_score=float(args.min_precursor_score), min_persistence=int(args.min_persistence), @@ -107,9 +205,13 @@ def main(argv: list[str] | None = None) -> int: max_triggers_per_scan=int(args.max_triggers_per_scan), lead_scans=float(args.lead_scans), window_sigma=float(args.window_sigma), + hypothesis=args.hypothesis, + execution_mode=args.mode, + odd=odd, ) triggers_jsonl = outdir / "zoom_triggers.jsonl" + audit_jsonl = outdir / "audit_trajectory.jsonl" steps_json = outdir / "autonomous_steps.json" if args.mode == "replay": @@ -143,14 +245,21 @@ def main(argv: list[str] | None = None) -> int: for tgt in bench.zoom_targets: fh.write(json.dumps(tgt.to_bliss_command()) + "\n") + with audit_jsonl.open("w", encoding="utf-8") as fh: + for rec in bench.audit_records: + fh.write(json.dumps(rec.to_dict()) + "\n") + steps_json.write_text(json.dumps([s.to_dict() for s in bench.steps], indent=2), encoding="utf-8") summary_path = outdir / "replay_summary.json" summary_path.write_text(json.dumps(bench.to_dict(), indent=2), encoding="utf-8") bt_m = bench.policy_comparison["braggtrack_autonomous"] + gap_msg = ( + f", mean Delta_gap={bench.mean_sim_to_real_gap:+.3f}" if bench.mean_sim_to_real_gap is not None else "" + ) print( f"[braggtrack-watch:replay] Processed {bench.n_scans} scans " - f"(mean {bench.mean_step_latency_sec:.3f}s/scan) -> {len(bench.zoom_targets)} zoom trigger(s)" + f"(mean {bench.mean_step_latency_sec:.3f}s/scan) -> {len(bench.zoom_targets)} zoom trigger(s){gap_msg}" ) print( f" Fracture capture recall={bt_m.fracture_capture_recall:.2f}, " @@ -160,7 +269,7 @@ def main(argv: list[str] | None = None) -> int: ) return 0 - # Live directory polling mode ("watch") + # Live directory polling modes: "shadow", "watch" (non-actuating), or "active" (FAL Level 3 actuation) tracker = CausalStreamingTracker( backend=args.backend, model_name=args.model, @@ -168,45 +277,70 @@ def main(argv: list[str] | None = None) -> int: detector=detector, precursor_config=prec_cfg, trigger_policy=policy, + sliding_window_scans=int(args.sliding_window) if args.sliding_window and args.sliding_window > 0 else None, + swmr=True, ) seen_files: set[Path] = set() step_dicts: list[dict] = [] idle_polls = 0 triggers_jsonl.write_text("", encoding="utf-8") + audit_jsonl.write_text("", encoding="utf-8") while True: - seq = BeamlineAdapter(root).build_sequence() + try: + seq = BeamlineAdapter(root).build_sequence() + except OSError: + seq = None + stim_by_name = {} - if args.operando_log and seq.scans: - op_log = load_operando_log(args.operando_log) - for sp in synchronize_to_scans(op_log, seq): - stim_by_name[sp.scan_name] = sp + if seq is not None and args.operando_log and seq.scans: + try: + op_log = load_operando_log(args.operando_log) + for sp in synchronize_to_scans(op_log, seq): + stim_by_name[sp.scan_name] = sp + except (OSError, ValueError): + pass - new_scans = [sc for sc in seq.scans if sc.file_path.resolve() not in seen_files] - if new_scans: - idle_polls = 0 - for sc in new_scans: - seen_files.add(sc.file_path.resolve()) - ts_iso = sc.start_time.isoformat() if sc.start_time is not None else None + candidates = [sc for sc in (seq.scans if seq is not None else []) if sc.file_path.resolve() not in seen_files] + ingested_any = False + for sc in candidates: + if not _is_hdf5_quiescent_and_readable(sc.file_path, settle_sec=max(0.0, float(args.settle_sec))): + continue + ts_iso = sc.start_time.isoformat() if sc.start_time is not None else None + try: res = tracker.step( sc.file_path, scan_name=sc.scan_name, timestamp=ts_iso, stimulus=stim_by_name.get(sc.scan_name), ) - step_dicts.append(res.to_dict()) - if res.zoom_targets: - with triggers_jsonl.open("a", encoding="utf-8") as fh: - for tgt in res.zoom_targets: - fh.write(json.dumps(tgt.to_bliss_command()) + "\n") - fh.flush() - steps_json.write_text(json.dumps(step_dicts, indent=2), encoding="utf-8") - print( - f"[braggtrack-watch:live] scan={res.scan_name} spots={res.n_spots} " - f"zoom_triggers={len(res.zoom_targets)} ({res.step_latency_sec:.3f}s)" - ) - if args.max_scans is not None and tracker.n_scans_processed >= int(args.max_scans): - return 0 + except (OSError, KeyError, ValueError): + # Transient partial HDF5 write or lock — retry cleanly on next poll without losing the scan + continue + + seen_files.add(sc.file_path.resolve()) + ingested_any = True + step_dicts.append(res.to_dict()) + if res.zoom_targets: + with triggers_jsonl.open("a", encoding="utf-8") as fh: + for tgt in res.zoom_targets: + fh.write(json.dumps(tgt.to_bliss_command()) + "\n") + fh.flush() + if res.audit_records: + with audit_jsonl.open("a", encoding="utf-8") as fh: + for rec in res.audit_records: + fh.write(json.dumps(rec.to_dict()) + "\n") + fh.flush() + steps_json.write_text(json.dumps(step_dicts, indent=2), encoding="utf-8") + print( + f"[braggtrack-watch:{args.mode}] scan={res.scan_name} spots={res.n_spots} " + f"fal={res.fal_level_active} zoom_triggers={len(res.zoom_targets)} ({res.step_latency_sec:.3f}s)" + ) + if args.max_scans is not None and tracker.n_scans_processed >= int(args.max_scans): + return 0 + + if ingested_any: + idle_polls = 0 else: idle_polls += 1 if args.max_idle_polls > 0 and idle_polls >= int(args.max_idle_polls): diff --git a/braggtrack/io/beamline.py b/braggtrack/io/beamline.py index 4762131..2b4bbcc 100644 --- a/braggtrack/io/beamline.py +++ b/braggtrack/io/beamline.py @@ -58,7 +58,7 @@ def _scan_to_meta(self, scan_file: ScanFile) -> ScanVolumeMeta: volume_path = discover_primary_volume_path(scan_file.path) except (KeyError, ValueError): volume_path = None - except MissingH5DependencyError as exc: + except (MissingH5DependencyError, OSError) as exc: metadata_error = str(exc) extras: dict[str, Any] = {} diff --git a/braggtrack/io/lazy.py b/braggtrack/io/lazy.py index 968a26e..ea5dc86 100644 --- a/braggtrack/io/lazy.py +++ b/braggtrack/io/lazy.py @@ -96,10 +96,13 @@ def open_lazy_volume( candidates: list[str] | None = None, *, auto_discover: bool = True, + swmr: bool = False, ) -> LazyVolume: """Open an HDF5 file and return a :class:`LazyVolume` bound to its primary 3D dataset.""" + from .nexus import _open_h5_readonly + h5py = _require_h5py() - handle = h5py.File(path, "r") + handle = _open_h5_readonly(h5py, path, swmr=swmr) try: ds_path = _resolve_volume_dataset(handle, h5py, candidates=candidates, auto_discover=auto_discover) ds = handle[ds_path] diff --git a/braggtrack/io/nexus.py b/braggtrack/io/nexus.py index a2d2e6b..ad9c6a2 100644 --- a/braggtrack/io/nexus.py +++ b/braggtrack/io/nexus.py @@ -36,6 +36,17 @@ def _require_h5py() -> Any: raise MissingH5DependencyError("h5py is required for HDF5/NeXus parsing. Install dependencies first.") from exc +def _open_h5_readonly(h5py: Any, path: str | Path, *, swmr: bool = False) -> Any: + """Open an HDF5 file read-only, enabling SWMR when supported by the file superblock.""" + if not swmr: + return h5py.File(path, "r") + try: + return h5py.File(path, "r", swmr=True) + except ValueError: + # Older HDF5 v0/v2 superblocks reject swmr=True with ValueError; fall back cleanly while keeping OSError intact. + return h5py.File(path, "r") + + def summarize_hdf5_tree(path: str | Path) -> list[tuple[str, str, tuple[int, ...] | None, str | None]]: """Return a flat summary of groups/datasets in an HDF5 file. @@ -120,7 +131,7 @@ def _read_first(handle: Any, candidates: list[str], h5py: Any | None = None) -> return None -def extract_scan_metadata(path: str | Path) -> dict[str, Any]: +def extract_scan_metadata(path: str | Path, *, swmr: bool = False) -> dict[str, Any]: """Extract common beamline metadata from a NeXus/HDF5 scan file. Probes standard NeXus ``/entry*`` groups (including ``/entry_0000`` used by @@ -130,7 +141,7 @@ def extract_scan_metadata(path: str | Path) -> dict[str, Any]: h5py = _require_h5py() path = Path(path) - with h5py.File(path, "r") as handle: + with _open_h5_readonly(h5py, path, swmr=swmr) as handle: entries = _candidate_entries(handle, h5py) or ["/entry", "/entry1", "/entry_0000"] start_candidates = [f"{e}/start_time" for e in entries] end_candidates = [f"{e}/end_time" for e in entries] @@ -159,7 +170,7 @@ def extract_scan_metadata(path: str | Path) -> dict[str, Any]: } -def extract_axis_calibration(path: str | Path) -> AxisCalibration: +def extract_axis_calibration(path: str | Path, *, swmr: bool = False) -> AxisCalibration: """Extract linear ``(mu, chi, d)`` calibration from a NeXus/HDF5 file if present. Probes: @@ -173,7 +184,7 @@ def extract_axis_calibration(path: str | Path) -> AxisCalibration: h5py = _require_h5py() path = Path(path) - with h5py.File(path, "r") as handle: + with _open_h5_readonly(h5py, path, swmr=swmr) as handle: vol_parent: str | None = None try: ds_path = _resolve_volume_dataset(handle, h5py, auto_discover=True) @@ -302,10 +313,11 @@ def discover_primary_volume_path( candidates: list[str] | None = None, *, auto_discover: bool = True, + swmr: bool = False, ) -> str: """Return the HDF5 dataset path of the primary 3D detector volume.""" h5py = _require_h5py() - with h5py.File(path, "r") as handle: + with _open_h5_readonly(h5py, path, swmr=swmr) as handle: return _resolve_volume_dataset(handle, h5py, candidates=candidates, auto_discover=auto_discover) @@ -314,11 +326,12 @@ def load_primary_volume( candidates: list[str] | None = None, *, auto_discover: bool = True, + swmr: bool = False, ) -> np.ndarray: """Load a primary 3D detector volume from NeXus paths or largest-3D auto-discovery.""" import numpy as np h5py = _require_h5py() - with h5py.File(path, "r") as handle: + with _open_h5_readonly(h5py, path, swmr=swmr) as handle: ds_path = _resolve_volume_dataset(handle, h5py, candidates=candidates, auto_discover=auto_discover) return np.asarray(handle[ds_path][()], dtype=np.float64) diff --git a/braggtrack/segmentation/classical.py b/braggtrack/segmentation/classical.py index 878921b..79a31cd 100644 --- a/braggtrack/segmentation/classical.py +++ b/braggtrack/segmentation/classical.py @@ -2,6 +2,7 @@ from __future__ import annotations +import math from dataclasses import dataclass import numpy as np @@ -19,9 +20,18 @@ class ClassicalSegmentationResult: response: np.ndarray +def _float_work_dtype(arr: np.ndarray) -> np.dtype: + """Use float32 for <=32-bit detector arrays (50% RAM cut) and float64 when explicitly float64.""" + dt = np.asarray(arr).dtype + if dt == np.float64: + return np.dtype(np.float64) + return np.dtype(np.float32) + + def gaussian_blur_3d(volume: np.ndarray, passes: int = 1, sigma: float = 1.0) -> np.ndarray: """Apply Gaussian blur along each axis.""" - result = np.asarray(volume, dtype=np.float64) + work_dt = _float_work_dtype(volume) + result = np.asarray(volume, dtype=work_dt) for _ in range(max(1, passes)): result = gaussian_filter(result, sigma=sigma) return result @@ -29,7 +39,8 @@ def gaussian_blur_3d(volume: np.ndarray, passes: int = 1, sigma: float = 1.0) -> def laplacian_3d(volume: np.ndarray) -> np.ndarray: """6-neighbor discrete Laplacian.""" - return laplace(np.asarray(volume, dtype=np.float64)).astype(np.float64) + work_dt = _float_work_dtype(volume) + return laplace(np.asarray(volume, dtype=work_dt)).astype(work_dt, copy=False) def log_enhance_3d( @@ -54,11 +65,13 @@ def h_maxima_seeds( Each seed must be a local maximum whose value exceeds the highest neighbour by at least *h*, and must be >= *min_value*. """ - vol = np.asarray(volume, dtype=np.float64) + vol = np.asarray(volume) + if not np.issubdtype(vol.dtype, np.floating): + vol = vol.astype(np.float32) coords = peak_local_max( vol, min_distance=max(1, min_separation), - threshold_abs=min_value, + threshold_abs=float(min_value), ) if len(coords) == 0: return [] @@ -66,15 +79,30 @@ def h_maxima_seeds( seeds: list[tuple[int, int, int]] = [] for coord in coords: z, y, x = int(coord[0]), int(coord[1]), int(coord[2]) - center_val = vol[z, y, x] + center_val = float(vol[z, y, x]) z_lo, z_hi = max(0, z - 1), min(vol.shape[0], z + 2) y_lo, y_hi = max(0, y - 1), min(vol.shape[1], y + 2) x_lo, x_hi = max(0, x - 1), min(vol.shape[2], x + 2) - neighborhood = vol[z_lo:z_hi, y_lo:y_hi, x_lo:x_hi].copy() + neighborhood = vol[z_lo:z_hi, y_lo:y_hi, x_lo:x_hi].astype(np.float64, copy=True) neighborhood[z - z_lo, y - y_lo, x - x_lo] = -np.inf - max_neighbor = neighborhood.max() + max_neighbor = float(neighborhood.max()) if center_val - max_neighbor >= h: seeds.append((z, y, x)) + continue + # Handle symmetric sub-voxel peaks (e.g. center at y=15.5) where 2..8 apex voxels tie: + # verify prominence >= h against the 5x5x5 shell outside tied immediate apex neighbors. + tie_tol = 1e-4 * max(1.0, abs(center_val)) + if h > 0.0 and abs(center_val - max_neighbor) <= tie_tol: + z2_lo, z2_hi = max(0, z - 2), min(vol.shape[0], z + 3) + y2_lo, y2_hi = max(0, y - 2), min(vol.shape[1], y + 3) + x2_lo, x2_hi = max(0, x - 2), min(vol.shape[2], x + 3) + box5 = vol[z2_lo:z2_hi, y2_lo:y2_hi, x2_lo:x2_hi].astype(np.float64, copy=True) + cz, cy, cx = z - z2_lo, y - y2_lo, x - x2_lo + core = box5[max(0, cz - 1) : cz + 2, max(0, cy - 1) : cy + 2, max(0, cx - 1) : cx + 2] + core[np.abs(core - center_val) <= tie_tol] = -np.inf + rem_max = float(box5.max()) + if math.isfinite(rem_max) and (center_val - rem_max) >= h: + seeds.append((z, y, x)) return seeds @@ -85,11 +113,13 @@ def local_maxima_seeds( min_separation: int = 1, ) -> list[tuple[int, int, int]]: """Find local maxima seeds above a minimum value.""" - vol = np.asarray(volume, dtype=np.float64) + vol = np.asarray(volume) + if not np.issubdtype(vol.dtype, np.floating): + vol = vol.astype(np.float32) coords = peak_local_max( vol, min_distance=max(1, min_separation), - threshold_abs=min_value, + threshold_abs=float(min_value), ) return [(int(c[0]), int(c[1]), int(c[2])) for c in coords] @@ -105,12 +135,13 @@ def watershed_from_seeds( Passing a mask derived from the response itself under-shoots catastrophically because the response and volume distributions are on different scales. """ - response = np.asarray(response, dtype=np.float64) - markers = np.zeros(response.shape, dtype=np.int32) + work_dt = _float_work_dtype(response) + response_arr = np.asarray(response, dtype=work_dt) + markers = np.zeros(response_arr.shape, dtype=np.int32) for label_id, (z, y, x) in enumerate(seeds, start=1): markers[z, y, x] = label_id - labeled = watershed(-response, markers=markers, mask=np.asarray(mask, dtype=bool)) + labeled = watershed(-response_arr, markers=markers, mask=np.asarray(mask, dtype=bool)) return labeled.astype(np.int32) @@ -162,6 +193,9 @@ def segment_classical( min_seed_separation: int = 2, seed_peak_fraction: float = 0.2, seed_response_percentile: float = 99.95, + *, + working_dtype: type | np.dtype = np.float32, + log_scale: bool = False, ) -> ClassicalSegmentationResult: """Run classical LoG + h-maxima + seeded watershed pipeline. @@ -177,10 +211,17 @@ def segment_classical( foreground mask*. The fraction term uses a robust peak reference (99.99th percentile) rather than the absolute max, so isolated bright voxels don't inflate the floor. + working_dtype + Floating-point dtype used for 3D blur, Laplacian, and watershed buffers + (default ``np.float32``, reducing peak 3D buffer RAM by 50% vs ``float64``). + log_scale + When ``True``, compute LoG enhancement and seed peaks on ``log1p(max(volume, 0))`` + so weak satellite reflections are not suppressed by intense primary Bragg peaks. """ - volume = np.asarray(volume, dtype=np.float64) - response = log_enhance_3d(volume, blur_passes=blur_passes, sigma=sigma) - foreground = volume >= threshold + vol_arr = np.asarray(volume, dtype=working_dtype) + foreground = vol_arr >= np.asarray(threshold, dtype=working_dtype) + enh_input = np.log1p(np.maximum(vol_arr, 0.0)) if log_scale else vol_arr + response = log_enhance_3d(enh_input, blur_passes=blur_passes, sigma=sigma) seed_floor = _seed_floor_from_response( response[foreground], seed_peak_fraction=seed_peak_fraction, @@ -194,7 +235,7 @@ def segment_classical( ) labels = watershed_from_seeds(response, seeds=seeds, mask=foreground) return ClassicalSegmentationResult( - threshold=threshold, + threshold=float(threshold), seed_count=len(seeds), component_count=_count_labels(labels), labeled_volume=labels, diff --git a/braggtrack/segmentation/features.py b/braggtrack/segmentation/features.py index 47728bb..bcf8dcf 100644 --- a/braggtrack/segmentation/features.py +++ b/braggtrack/segmentation/features.py @@ -11,26 +11,45 @@ from braggtrack.io.models import AxisCalibration +def _excess_kurtosis(delta: np.ndarray, weights: np.ndarray) -> float: + """Standardised fourth central moment (Pearson excess kurtosis ``g_2 = mu_4 / mu_2^2 - 3``). + + Zero for an ideal Gaussian rocking profile; positive (leptokurtic) for heavy-tailed + dislocation pile-ups/notches and negative (platykurtic) for incipient bimodal splitting. + """ + m2 = float(np.dot(weights, delta * delta)) + if m2 <= 1e-12: + return 0.0 + m4 = float(np.dot(weights, (delta * delta) ** 2)) + return float(m4 / (m2 * m2) - 3.0) + + def extract_instance_table( labels: np.ndarray, intensity: np.ndarray, *, calibration: AxisCalibration | None = None, + subtract_background: bool = True, + detector_gain: float = 1.0, ) -> list[dict[str, float | int]]: - """Compute centroid, bbox, integrated intensity, covariance and eigenvalues. + """Compute centroid, bbox, integrated intensity, covariance, kurtosis, and eigenvalues. Voxel array axes are ``(z, y, x)`` mapping to reciprocal-space coordinates as **μ → z**, **d → y**, **χ → x** (STFC / operando convention). When *calibration* is provided, centroids, covariance components, and eigenvalues are transformed into physical units while ``bbox_*`` bounds - remain integer voxel indices for 3D array slicing. + remain integer voxel indices for 3D array slicing and ``vox_eig_*`` / ``step_*`` + preserve dimensionless step-normalised geometry for unit-invariant tracking. """ labels = np.asarray(labels) intensity = np.asarray(intensity, dtype=np.float64) if labels.size == 0 or int(labels.max()) <= 0: return [] + nz, ny, nx = labels.shape + gain = max(float(detector_gain), 1e-6) + is_calibrated = int(calibration is not None and calibration.calibrated) slices = find_objects(np.where(labels > 0, labels, 0)) rows: list[dict[str, float | int]] = [] for idx, slc in enumerate(slices): @@ -47,45 +66,67 @@ def extract_instance_table( count = len(vals) sum_i = float(vals.sum()) + # Estimate local detector pedestal from outer perimeter of 4-voxel padded window (labels == 0), + # well outside the immediate Bragg flank so sub-Otsu rocking-curve wings are not subtracted. + pz0, pz1 = max(0, sz.start - 4), min(nz, sz.stop + 4) + py0, py1 = max(0, sy.start - 4), min(ny, sy.stop + 4) + px0, px1 = max(0, sx.start - 4), min(nx, sx.stop + 4) + lbl_pad = labels[pz0:pz1, py0:py1, px0:px1] + vol_pad = intensity[pz0:pz1, py0:py1, px0:px1] + outer_ring = np.ones(lbl_pad.shape, dtype=bool) + if lbl_pad.shape[0] > 2 and lbl_pad.shape[1] > 2 and lbl_pad.shape[2] > 2: + outer_ring[1:-1, 1:-1, 1:-1] = False + bg_candidates = (lbl_pad == 0) & outer_ring + if not np.any(bg_candidates): + bg_candidates = lbl_pad == 0 + if np.any(bg_candidates): + bg_level = max(0.0, float(np.median(vol_pad[bg_candidates]))) + else: + bg_level = 0.0 + + vals_net = np.maximum(vals - bg_level, 0.0) + sum_net = float(vals_net.sum()) + w_vals = vals_net if (subtract_background and sum_net > 0.0) else vals + w_sum = sum_net if (subtract_background and sum_net > 0.0) else sum_i + z_coords = local_coords[:, 0].astype(np.float64) + float(sz.start) y_coords = local_coords[:, 1].astype(np.float64) + float(sy.start) x_coords = local_coords[:, 2].astype(np.float64) + float(sx.start) # Intensity-weighted centroid; fall back to geometric centroid # if total intensity is non-positive (avoids sign-flip). - if sum_i > 0: - weights = vals / sum_i - cz = float(np.dot(weights, z_coords)) - cy = float(np.dot(weights, y_coords)) - cx = float(np.dot(weights, x_coords)) + if w_sum > 0.0: + w = w_vals / w_sum + cz = float(np.dot(w, z_coords)) + cy = float(np.dot(w, y_coords)) + cx = float(np.dot(w, x_coords)) else: + w = np.ones(count, dtype=np.float64) / count cz = float(z_coords.mean()) cy = float(y_coords.mean()) cx = float(x_coords.mean()) + dz_vox = z_coords - cz + dy_vox = y_coords - cy + dx_vox = x_coords - cx + if calibration is not None: c_mu, c_chi, c_d = calibration.voxel_to_physical(cz, cy, cx) - dz = (z_coords - cz) * calibration.mu_step - dy = (y_coords - cy) * calibration.d_step - dx = (x_coords - cx) * calibration.chi_step + dz = dz_vox * calibration.mu_step + dy = dy_vox * calibration.d_step + dx = dx_vox * calibration.chi_step step_mu = abs(calibration.mu_step) step_d = abs(calibration.d_step) step_chi = abs(calibration.chi_step) else: c_mu, c_chi, c_d = cz, cx, cy - dz = z_coords - cz - dy = y_coords - cy - dx = x_coords - cx + dz = dz_vox + dy = dy_vox + dx = dx_vox step_mu = 1.0 step_d = 1.0 step_chi = 1.0 - # Weighted covariance (same weight logic) - if sum_i > 0: - w = vals / sum_i - else: - w = np.ones(count, dtype=np.float64) / count - czz = float(np.dot(w, dz * dz)) cyy = float(np.dot(w, dy * dy)) cxx = float(np.dot(w, dx * dx)) @@ -94,11 +135,12 @@ def extract_instance_table( cyx = float(np.dot(w, dy * dx)) # Analytical 1-sigma centroid standard error: under Poisson photon statistics - # Var(c) = cov / sum_i; when intensities are normalized (< n_eff), fall back to - # Kish effective sample size n_eff = 1 / sum(w_k^2), floored by voxel quantization. + # Var(c) = cov / N_photons (N_photons = w_sum / detector_gain); when intensities are + # normalized (< n_eff), fall back to Kish effective sample size n_eff = 1 / sum(w_k^2), + # floored by uniform voxel quantization variance step^2 / 12. w_sq = float(np.dot(w, w)) n_eff = (1.0 / w_sq) if w_sq > 0.0 else float(max(1, count)) - eff_denom = max(sum_i, n_eff, 1.0) + eff_denom = max(w_sum / gain, n_eff, 1.0) c_mu_err = float(np.sqrt(max(czz, (step_mu**2) / 12.0) / eff_denom)) c_chi_err = float(np.sqrt(max(cxx, (step_chi**2) / 12.0) / eff_denom)) c_d_err = float(np.sqrt(max(cyy, (step_d**2) / 12.0) / eff_denom)) @@ -113,23 +155,74 @@ def extract_instance_table( eigvals = np.linalg.eigvalsh(cov) eigvals = np.maximum(0.0, np.sort(eigvals)[::-1]) # non-negative descending + if is_calibrated: + v_czz = float(np.dot(w, dz_vox * dz_vox)) + v_cyy = float(np.dot(w, dy_vox * dy_vox)) + v_cxx = float(np.dot(w, dx_vox * dx_vox)) + v_czy = float(np.dot(w, dz_vox * dy_vox)) + v_czx = float(np.dot(w, dz_vox * dx_vox)) + v_cyx = float(np.dot(w, dy_vox * dx_vox)) + vox_cov = np.array( + [ + [v_czz, v_czy, v_czx], + [v_czy, v_cyy, v_cyx], + [v_czx, v_cyx, v_cxx], + ] + ) + vox_eigs = np.maximum(0.0, np.sort(np.linalg.eigvalsh(vox_cov))[::-1]) + else: + vox_eigs = eigvals + + min_z, max_z = int(z_coords.min()), int(z_coords.max()) + min_y, max_y = int(y_coords.min()), int(y_coords.max()) + min_x, max_x = int(x_coords.min()), int(x_coords.max()) + touches_rocking = bool(min_z == 0 or max_z >= nz - 1) + touches_any = bool(touches_rocking or min_y == 0 or max_y >= ny - 1 or min_x == 0 or max_x >= nx - 1) + + # Evaluate rocking-curve Pearson excess kurtosis g_2 = mu_4 / sigma^4 - 3 over a 4-voxel + # padded local ROI (excluding foreign spot labels) so sub-Otsu diffuse scattering wings + # (LeHoux2026) are integrated rather than hard-clipped at the watershed boundary. + kz0, kz1 = max(0, min_z - 4), min(nz, max_z + 5) + ky0, ky1 = max(0, min_y - 4), min(ny, max_y + 5) + kx0, kx1 = max(0, min_x - 4), min(nx, max_x + 5) + lbl_win = labels[kz0:kz1, ky0:ky1, kx0:kx1] + vol_win = intensity[kz0:kz1, ky0:ky1, kx0:kx1] + own_or_bg = (lbl_win == 0) | (lbl_win == lbl) + net_win = np.where(own_or_bg, np.maximum(0.0, vol_win - bg_level), 0.0) + net_win_sum = float(net_win.sum()) + if net_win_sum > 0.0: + rz, ry, rx = np.nonzero(net_win > 0.0) + w_kurt = net_win[rz, ry, rx] / net_win_sum + cz_k = float(np.dot(w_kurt, rz + kz0)) + cy_k = float(np.dot(w_kurt, ry + ky0)) + cx_k = float(np.dot(w_kurt, rx + kx0)) + k_mu = _excess_kurtosis((rz + kz0) - cz_k, w_kurt) + k_chi = _excess_kurtosis((rx + kx0) - cx_k, w_kurt) + k_d = _excess_kurtosis((ry + ky0) - cy_k, w_kurt) + else: + k_mu = _excess_kurtosis(dz_vox, w) + k_chi = _excess_kurtosis(dx_vox, w) + k_d = _excess_kurtosis(dy_vox, w) + rows.append( { "label": int(lbl), "voxel_count": count, "integrated_intensity": sum_i, + "net_intensity": sum_net, + "background_level": bg_level, "centroid_mu": c_mu, "centroid_chi": c_chi, "centroid_d": c_d, "centroid_mu_err": c_mu_err, "centroid_chi_err": c_chi_err, "centroid_d_err": c_d_err, - "bbox_min_z": int(z_coords.min()), - "bbox_max_z": int(z_coords.max()), - "bbox_min_y": int(y_coords.min()), - "bbox_max_y": int(y_coords.max()), - "bbox_min_x": int(x_coords.min()), - "bbox_max_x": int(x_coords.max()), + "bbox_min_z": min_z, + "bbox_max_z": max_z, + "bbox_min_y": min_y, + "bbox_max_y": max_y, + "bbox_min_x": min_x, + "bbox_max_x": max_x, "cov_zz": czz, "cov_yy": cyy, "cov_xx": cxx, @@ -139,6 +232,18 @@ def extract_instance_table( "eig_1": float(eigvals[0]), "eig_2": float(eigvals[1]), "eig_3": float(eigvals[2]), + "vox_eig_1": float(vox_eigs[0]), + "vox_eig_2": float(vox_eigs[1]), + "vox_eig_3": float(vox_eigs[2]), + "kurtosis_mu": k_mu, + "kurtosis_chi": k_chi, + "kurtosis_d": k_d, + "step_mu": float(step_mu), + "step_chi": float(step_chi), + "step_d": float(step_d), + "calibrated": is_calibrated, + "touches_border": touches_any, + "touches_rocking_border": touches_rocking, } ) diff --git a/braggtrack/semantic/dino.py b/braggtrack/semantic/dino.py index afe7601..0d6770f 100644 --- a/braggtrack/semantic/dino.py +++ b/braggtrack/semantic/dino.py @@ -75,13 +75,24 @@ def _mock_embedding_from_mips( return v -def _mips_to_rgb_uint8(mip: np.ndarray) -> np.ndarray: +def _mips_to_rgb_uint8(mip: np.ndarray, *, preserve_aspect: bool = True) -> np.ndarray: m = np.asarray(mip, dtype=np.float64) + if m.size == 0: + return np.zeros((1, 1, 3), dtype=np.uint8) lo, hi = float(np.percentile(m, 1.0)), float(np.percentile(m, 99.0)) if hi <= lo: hi = lo + 1.0 u = np.clip((m - lo) / (hi - lo), 0.0, 1.0) g = (u * 255.0).astype(np.uint8) + if preserve_aspect and g.ndim == 2 and g.shape[0] != g.shape[1]: + h, w = g.shape + # Pad onto a centered square canvas (with 8% margin for DINOv2's 256->224 center-crop) + side = max(h, w, int(np.ceil(max(h, w) / 0.875))) + canvas = np.zeros((side, side), dtype=np.uint8) + y0 = (side - h) // 2 + x0 = (side - w) // 2 + canvas[y0 : y0 + h, x0 : x0 + w] = g + g = canvas return np.stack([g, g, g], axis=-1) @@ -282,7 +293,7 @@ def extract_patch_features_batch( ) -> list[np.ndarray]: if not images_2d: return [] - rgbs = [_mips_to_rgb_uint8(img) for img in images_2d] + rgbs = [_mips_to_rgb_uint8(img, preserve_aspect=False) for img in images_2d] step = max(1, int(batch_size)) if str(self._device) == "cpu": step = min(step, 16) diff --git a/braggtrack/tracking/cost.py b/braggtrack/tracking/cost.py index 45906b5..0b426e5 100644 --- a/braggtrack/tracking/cost.py +++ b/braggtrack/tracking/cost.py @@ -27,8 +27,39 @@ def __call__(self, spot_i: dict, spot_j: dict) -> float: ... +def _spot_scales(spot: dict) -> tuple[float, float, float]: + """Return positive per-axis voxel step scales ``(step_mu, step_chi, step_d)``.""" + sm = abs(float(spot.get("step_mu", 1.0))) + sc = abs(float(spot.get("step_chi", 1.0))) + sd = abs(float(spot.get("step_d", 1.0))) + return ( + sm if sm > 1e-12 else 1.0, + sc if sc > 1e-12 else 1.0, + sd if sd > 1e-12 else 1.0, + ) + + +def _spot_eigs(spot: dict, *, normalize_by_step: bool) -> tuple[float, float, float]: + """Return shape eigenvalues (dimensionless voxel-space when calibrated & normalized).""" + if normalize_by_step and "vox_eig_1" in spot: + return ( + float(spot.get("vox_eig_1", 0.0)), + float(spot.get("vox_eig_2", 0.0)), + float(spot.get("vox_eig_3", 0.0)), + ) + e1 = float(spot.get("eig_1", 0.0)) + e2 = float(spot.get("eig_2", 0.0)) + e3 = float(spot.get("eig_3", 0.0)) + if normalize_by_step and bool(spot.get("calibrated", 0)): + sm, sc, sd = _spot_scales(spot) + s2 = max(sm, sc, sd) ** 2 + if s2 > 0.0: + return (e1 / s2, e2 / s2, e3 / s2) + return (e1, e2, e3) + + class PositionShapeCost: - """Weighted position + shape cost with per-axis gating. + """Weighted position + shape cost with per-axis gating and step-scale invariance. Parameters ---------- @@ -37,10 +68,14 @@ class PositionShapeCost: shape_weight : float Multiplier for the shape (eigenvalue) distance term. gate_mu, gate_chi, gate_d : float - Maximum allowed displacement along each reciprocal-space axis. - Pairs exceeding *any* gate are assigned ``inf`` cost. Defaults - are deliberately loose; tighten ``gate_d`` less aggressively - than mu/chi for operando data where d-spacing shifts are large. + Maximum allowed displacement along each reciprocal-space axis (evaluated + in the spot's native coordinate units). Pairs exceeding *any* gate are + assigned ``inf`` cost. + normalize_by_step : bool + When ``True`` (default), calibrated physical displacements ``(deg, deg, Å)`` + are divided by ``(step_mu, step_chi, step_d)`` and ``vox_eig_*`` are used + so Euclidean association costs are dimensionless and invariant to choice + of physical units. Uncalibrated spots (``step_* = 1``) are unchanged. """ def __init__( @@ -50,12 +85,15 @@ def __init__( gate_mu: float = math.inf, gate_chi: float = math.inf, gate_d: float = math.inf, + *, + normalize_by_step: bool = True, ) -> None: self.position_weight = position_weight self.shape_weight = shape_weight self.gate_mu = gate_mu self.gate_chi = gate_chi self.gate_d = gate_d + self.normalize_by_step = bool(normalize_by_step) def pairwise_cost_matrix(self, spots_t: list[dict], spots_t1: list[dict]) -> np.ndarray: n, m = len(spots_t), len(spots_t1) @@ -71,40 +109,55 @@ def pairwise_cost_matrix(self, spots_t: list[dict], spots_t1: list[dict]) -> np. dtype=np.float64, ) e = np.array( - [[s.get("eig_1", 0.0), s.get("eig_2", 0.0), s.get("eig_3", 0.0)] for s in spots_t], + [_spot_eigs(s, normalize_by_step=self.normalize_by_step) for s in spots_t], dtype=np.float64, ) f = np.array( - [[s.get("eig_1", 0.0), s.get("eig_2", 0.0), s.get("eig_3", 0.0)] for s in spots_t1], + [_spot_eigs(s, normalize_by_step=self.normalize_by_step) for s in spots_t1], dtype=np.float64, ) - pos_d2 = cdist(x, y, metric="sqeuclidean") - shape_d2 = cdist(e, f, metric="sqeuclidean") - dmu = np.abs(x[:, 0][:, np.newaxis] - y[:, 0][np.newaxis, :]) dchi = np.abs(x[:, 1][:, np.newaxis] - y[:, 1][np.newaxis, :]) dd = np.abs(x[:, 2][:, np.newaxis] - y[:, 2][np.newaxis, :]) bad = (dmu > self.gate_mu) | (dchi > self.gate_chi) | (dd > self.gate_d) + if self.normalize_by_step: + sx = np.array([_spot_scales(s) for s in spots_t], dtype=np.float64) + sy = np.array([_spot_scales(s) for s in spots_t1], dtype=np.float64) + smu = 0.5 * (sx[:, 0][:, np.newaxis] + sy[:, 0][np.newaxis, :]) + schi = 0.5 * (sx[:, 1][:, np.newaxis] + sy[:, 1][np.newaxis, :]) + sd = 0.5 * (sx[:, 2][:, np.newaxis] + sy[:, 2][np.newaxis, :]) + pos_d2 = (dmu / smu) ** 2 + (dchi / schi) ** 2 + (dd / sd) ** 2 + else: + pos_d2 = cdist(x, y, metric="sqeuclidean") + + shape_d2 = cdist(e, f, metric="sqeuclidean") + cost = self.position_weight * pos_d2 + self.shape_weight * shape_d2 cost[bad] = np.inf return cost def __call__(self, spot_i: dict, spot_j: dict) -> float: - dmu = abs(spot_i["centroid_mu"] - spot_j["centroid_mu"]) - dchi = abs(spot_i["centroid_chi"] - spot_j["centroid_chi"]) - dd = abs(spot_i["centroid_d"] - spot_j["centroid_d"]) + dmu = abs(float(spot_i["centroid_mu"]) - float(spot_j["centroid_mu"])) + dchi = abs(float(spot_i["centroid_chi"]) - float(spot_j["centroid_chi"])) + dd = abs(float(spot_i["centroid_d"]) - float(spot_j["centroid_d"])) if dmu > self.gate_mu or dchi > self.gate_chi or dd > self.gate_d: return math.inf + if self.normalize_by_step: + smi, sci, sdi = _spot_scales(spot_i) + smj, scj, sdj = _spot_scales(spot_j) + dmu /= 0.5 * (smi + smj) + dchi /= 0.5 * (sci + scj) + dd /= 0.5 * (sdi + sdj) + pos_dist2 = dmu**2 + dchi**2 + dd**2 - deig1 = spot_i.get("eig_1", 0.0) - spot_j.get("eig_1", 0.0) - deig2 = spot_i.get("eig_2", 0.0) - spot_j.get("eig_2", 0.0) - deig3 = spot_i.get("eig_3", 0.0) - spot_j.get("eig_3", 0.0) - shape_dist2 = deig1**2 + deig2**2 + deig3**2 + ei = _spot_eigs(spot_i, normalize_by_step=self.normalize_by_step) + ej = _spot_eigs(spot_j, normalize_by_step=self.normalize_by_step) + shape_dist2 = (ei[0] - ej[0]) ** 2 + (ei[1] - ej[1]) ** 2 + (ei[2] - ej[2]) ** 2 return self.position_weight * pos_dist2 + self.shape_weight * shape_dist2 diff --git a/braggtrack/tracking/events.py b/braggtrack/tracking/events.py index 595eea5..3ec8a7d 100644 --- a/braggtrack/tracking/events.py +++ b/braggtrack/tracking/events.py @@ -9,6 +9,10 @@ import networkx as nx import numpy as np +from .cost import _spot_scales + +SplitSubtype = Literal["mechanical_split", "phase_split", "mixed_split"] + @dataclass(frozen=True) class SplitMergeConfig: @@ -22,6 +26,8 @@ class SplitMergeConfig: max_intensity_ratio: float = 1.6 min_fragment_share: float = 0.1 min_semantic_similarity: float | None = None + normalize_by_step: bool = True + phase_split_ratio: float = 2.0 @dataclass(frozen=True) @@ -44,6 +50,9 @@ class LineageEvent: semantic_similarity: float | None = None confidence: float = 1.0 timestamp: str | None = None + split_subtype: SplitSubtype | None = None + delta_orientation_norm: float = 0.0 + delta_d_norm: float = 0.0 def _spot_coords(node_data: dict[str, Any]) -> tuple[float, float, float]: @@ -54,6 +63,40 @@ def _spot_coords(node_data: dict[str, Any]) -> tuple[float, float, float]: ) +def _classify_split_subtype( + child_datas: list[dict[str, Any]], + *, + phase_split_ratio: float = 2.0, +) -> tuple[SplitSubtype, float, float]: + """Disambiguate orientation cleavage (``mechanical_split``) vs two-phase ``d``-jump (``phase_split``).""" + max_orient = 0.0 + max_d = 0.0 + n_c = len(child_datas) + for i in range(n_c): + mu_i, chi_i, d_i = _spot_coords(child_datas[i]) + smi, sci, sdi = _spot_scales(child_datas[i]) + for j in range(i + 1, n_c): + mu_j, chi_j, d_j = _spot_coords(child_datas[j]) + smj, scj, sdj = _spot_scales(child_datas[j]) + dmu_n = abs(mu_i - mu_j) / (0.5 * (smi + smj)) + dchi_n = abs(chi_i - chi_j) / (0.5 * (sci + scj)) + dd_n = abs(d_i - d_j) / (0.5 * (sdi + sdj)) + orient_sep = math.hypot(dmu_n, dchi_n) + if orient_sep > max_orient: + max_orient = orient_sep + if dd_n > max_d: + max_d = dd_n + + ratio = max(1.05, float(phase_split_ratio)) + if max_d >= ratio * max(max_orient, 1e-6): + subtype: SplitSubtype = "phase_split" + elif max_orient >= ratio * max(max_d, 1e-6): + subtype = "mechanical_split" + else: + subtype = "mixed_split" + return subtype, max_orient, max_d + + def _pair_distance_and_sim( a: dict[str, Any], b: dict[str, Any], @@ -66,6 +109,12 @@ def _pair_distance_and_sim( dd = abs(d_a - d_b) if dmu > config.gate_mu or dchi > config.gate_chi or dd > config.gate_d: return None + if config.normalize_by_step: + sma, sca, sda = _spot_scales(a) + smb, scb, sdb = _spot_scales(b) + dmu /= 0.5 * (sma + smb) + dchi /= 0.5 * (sca + scb) + dd /= 0.5 * (sda + sdb) dist = math.sqrt(dmu * dmu + dchi * dchi + dd * dd) if dist > config.max_distance: return None @@ -255,14 +304,22 @@ def resolve_splits_and_merges( if not valid_all: continue + sorted_children = sorted(all_children) + subtype, d_orient_n, d_d_n = _classify_split_subtype( + [G.nodes[c] for c in sorted_children], + phase_split_ratio=cfg.phase_split_ratio, + ) + parent_tid = int(G.nodes[p_nid]["track_id"]) G.nodes[p_nid]["lineage_role"] = "split_parent" + G.nodes[p_nid]["split_subtype"] = subtype child_tids: list[int] = [] - for c_nid in sorted(all_children): + for c_nid in sorted_children: if not G.has_edge(p_nid, c_nid): - G.add_edge(p_nid, c_nid, edge_type="split") + G.add_edge(p_nid, c_nid, edge_type="split", split_subtype=subtype) else: G.edges[p_nid, c_nid]["edge_type"] = "split" + G.edges[p_nid, c_nid]["split_subtype"] = subtype old_c_tid = int(G.nodes[c_nid]["track_id"]) if old_c_tid == parent_tid: @@ -273,6 +330,7 @@ def resolve_splits_and_merges( new_c_tid = old_c_tid G.nodes[c_nid]["lineage_role"] = "split_child" + G.nodes[c_nid]["split_subtype"] = subtype G.nodes[c_nid]["parent_track_ids"] = [parent_tid] child_tids.append(new_c_tid) @@ -288,7 +346,7 @@ def resolve_splits_and_merges( parent_track_ids=(parent_tid,), child_track_ids=tuple(child_tids), parent_nodes=(p_nid,), - child_nodes=tuple(sorted(all_children)), + child_nodes=tuple(sorted_children), centroid_mu=p_mu, centroid_chi=p_chi, centroid_d=p_d, @@ -297,6 +355,9 @@ def resolve_splits_and_merges( semantic_similarity=round(mean_sim, 4) if mean_sim is not None else None, confidence=_event_confidence(mean_dist, cfg.max_distance, ratio, mean_sim), timestamp=ts, + split_subtype=subtype, + delta_orientation_norm=round(d_orient_n, 4), + delta_d_norm=round(d_d_n, 4), ) ) next_event_id += 1 @@ -404,6 +465,7 @@ def events_to_table(events: list[LineageEvent]) -> list[dict[str, Any]]: { "event_id": ev.event_id, "event_type": ev.event_type, + "split_subtype": ev.split_subtype or "", "scan_idx_from": ev.scan_idx_from, "scan_idx_to": ev.scan_idx_to, "timestamp": ev.timestamp or "", @@ -416,6 +478,8 @@ def events_to_table(events: list[LineageEvent]) -> list[dict[str, Any]]: "centroid_d": ev.centroid_d, "intensity_ratio": ev.intensity_ratio, "mean_distance": ev.mean_distance, + "delta_orientation_norm": ev.delta_orientation_norm, + "delta_d_norm": ev.delta_d_norm, "semantic_similarity": ev.semantic_similarity if ev.semantic_similarity is not None else "", "confidence": ev.confidence, } diff --git a/braggtrack/tracking/gap_closing.py b/braggtrack/tracking/gap_closing.py index c40ce8f..c436522 100644 --- a/braggtrack/tracking/gap_closing.py +++ b/braggtrack/tracking/gap_closing.py @@ -10,7 +10,7 @@ import numpy as np from scipy.optimize import linear_sum_assignment -from .cost import CostFunction, GeometrySemanticCost, PositionShapeCost +from .cost import CostFunction, GeometrySemanticCost, PositionShapeCost, _spot_eigs, _spot_scales from .lifecycle import TrackEvent @@ -94,12 +94,18 @@ def _eval_gap_cost( if (dmu / step_scale) > geo.gate_mu or (dchi / step_scale) > geo.gate_chi or (dd / step_scale) > geo.gate_d: return math.inf + if geo.normalize_by_step: + smu, schi, sd = _spot_scales(u_data) + smv, schiv, sdv = _spot_scales(v_data) + dmu /= 0.5 * (smu + smv) + dchi /= 0.5 * (schi + schiv) + dd /= 0.5 * (sd + sdv) + # Diffusive scaling (dx^2 / delta_t) keeps gap costs comparable to 1-step costs. pos_dist2 = (dmu**2 + dchi**2 + dd**2) / step_scale - deig1 = float(u_data.get("eig_1", 0.0)) - float(v_data.get("eig_1", 0.0)) - deig2 = float(u_data.get("eig_2", 0.0)) - float(v_data.get("eig_2", 0.0)) - deig3 = float(u_data.get("eig_3", 0.0)) - float(v_data.get("eig_3", 0.0)) - shape_dist2 = deig1**2 + deig2**2 + deig3**2 + eu = _spot_eigs(u_data, normalize_by_step=geo.normalize_by_step) + ev = _spot_eigs(v_data, normalize_by_step=geo.normalize_by_step) + shape_dist2 = (eu[0] - ev[0]) ** 2 + (eu[1] - ev[1]) ** 2 + (eu[2] - ev[2]) ** 2 g_cost = geo.position_weight * pos_dist2 + geo.shape_weight * shape_dist2 if beta == 0.0: return alpha * g_cost @@ -206,6 +212,7 @@ def _edge_is_jump(a: str, b: str) -> bool: n_born = len(born_nodes) if n_term == 0 or n_born == 0: G.graph["gap_closures"] = [] + G.graph["gap_closed_count"] = 0 return [] inadmissible = 1e12 @@ -272,4 +279,5 @@ def _edge_is_jump(a: str, b: str) -> bool: ) G.graph["gap_closures"] = records + G.graph["gap_closed_count"] = len(records) return records diff --git a/braggtrack/tracking/kinematics.py b/braggtrack/tracking/kinematics.py index db53138..c38825b 100644 --- a/braggtrack/tracking/kinematics.py +++ b/braggtrack/tracking/kinematics.py @@ -59,11 +59,12 @@ class GrainKinematics: lineage_strain: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) lineage_strain_err: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) - # Strictly causal backward finite-difference rates (per scan step) + # Strictly causal backward finite-difference rates (per scan step, plus per-second when elapsed_s known) rate_mu: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) rate_chi: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) rate_d: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) strain_rate: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) + strain_rate_per_s: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=np.float64)) @dataclass @@ -131,8 +132,27 @@ def _propagate_strain_err( return err +def _obs_elapsed_s(row: dict[str, Any], scan_elapsed_s: dict[int, float] | None) -> float | None: + s_idx = int(row["scan_idx"]) + if scan_elapsed_s is not None and s_idx in scan_elapsed_s: + val = scan_elapsed_s[s_idx] + if val is not None and np.isfinite(val): + return float(val) + raw = row.get("elapsed_s") + if raw is not None and raw != "": + try: + f = float(raw) + if np.isfinite(f): + return f + except (TypeError, ValueError): + return None + return None + + def compute_grain_kinematics( track_table: list[dict[str, Any]], + *, + scan_elapsed_s: dict[int, float] | None = None, ) -> list[GrainKinematics]: """Compute kinematic time-series for each tracked grain. @@ -144,6 +164,8 @@ def compute_grain_kinematics( ``centroid_chi``, ``centroid_d``, ``eig_1``, ``eig_2``, ``eig_3``, ``integrated_intensity``, ``voxel_count``, plus optional ``centroid_*_err`` and ``parent_track_ids``. + scan_elapsed_s + Optional mapping ``scan_idx -> elapsed_seconds`` for non-uniform scan cadences. Returns ------- @@ -217,11 +239,12 @@ def _resolve_root_tid(start_tid: int) -> int: zero_first=(root_tid == tid), ) - # Strictly causal backward finite-difference rates (per scan step) + # Strictly causal backward finite-difference rates (per scan step & wall-clock /s) rate_mu = np.zeros(n, dtype=np.float64) rate_chi = np.zeros(n, dtype=np.float64) rate_d = np.zeros(n, dtype=np.float64) strain_rate = np.zeros(n, dtype=np.float64) + strain_rate_per_s = np.zeros(n, dtype=np.float64) # Seed initial rate at i=0 from immediate parent's last observation if split/merge child imm_parents = [p for p in parent_map.get(tid, []) if p in sorted_tracks] @@ -234,6 +257,10 @@ def _resolve_root_tid(start_tid: int) -> int: if d_root0 != 0.0: p_lin_strain = (float(p_last["centroid_d"]) - d_root0) / d_root0 strain_rate[0] = (lineage_strain[0] - p_lin_strain) / dt0 + t_now0 = _obs_elapsed_s(obs[0], scan_elapsed_s) + t_prev0 = _obs_elapsed_s(p_last, scan_elapsed_s) + if t_now0 is not None and t_prev0 is not None and (t_now0 - t_prev0) > 1e-6: + strain_rate_per_s[0] = (lineage_strain[0] - p_lin_strain) / (t_now0 - t_prev0) for i in range(1, n): dt = max(1, scan_indices[i] - scan_indices[i - 1]) @@ -241,6 +268,10 @@ def _resolve_root_tid(start_tid: int) -> int: rate_chi[i] = (chi[i] - chi[i - 1]) / dt rate_d[i] = (d[i] - d[i - 1]) / dt strain_rate[i] = (lineage_strain[i] - lineage_strain[i - 1]) / dt + t_now = _obs_elapsed_s(obs[i], scan_elapsed_s) + t_prev = _obs_elapsed_s(obs[i - 1], scan_elapsed_s) + if t_now is not None and t_prev is not None and (t_now - t_prev) > 1e-6: + strain_rate_per_s[i] = (lineage_strain[i] - lineage_strain[i - 1]) / (t_now - t_prev) # Misorientation: drift from initial position dmu = mu - mu[0] @@ -255,9 +286,23 @@ def _resolve_root_tid(start_tid: int) -> int: rel_intensity = (intensity - i0) / i0 if i0 != 0 else np.zeros(n, dtype=np.float64) rel_volume = (voxels - v0) / v0 if v0 != 0 else np.zeros(n, dtype=np.float64) - eigs = np.array([[float(r["eig_1"]), float(r["eig_2"]), float(r["eig_3"])] for r in obs], dtype=np.float64) - e3 = eigs[:, 2] - anisotropy = np.where(e3 > 0, eigs[:, 0] / e3, 1.0) + eigs = np.array( + [[float(r.get("eig_1", 1.0)), float(r.get("eig_2", 1.0)), float(r.get("eig_3", 1.0))] for r in obs], + dtype=np.float64, + ) + shape_eigs = np.array( + [ + [ + float(r.get("vox_eig_1", r.get("eig_1", 1.0))), + float(r.get("vox_eig_2", r.get("eig_2", 1.0))), + float(r.get("vox_eig_3", r.get("eig_3", 1.0))), + ] + for r in obs + ], + dtype=np.float64, + ) + e3 = shape_eigs[:, 2] + anisotropy = np.where(e3 > 0, shape_eigs[:, 0] / e3, 1.0) cov_trace = eigs.sum(axis=1) results.append( @@ -290,6 +335,7 @@ def _resolve_root_tid(start_tid: int) -> int: rate_chi=rate_chi, rate_d=rate_d, strain_rate=strain_rate, + strain_rate_per_s=strain_rate_per_s, ) ) return results diff --git a/braggtrack/types.py b/braggtrack/types.py index 67e631e..f498f8c 100644 --- a/braggtrack/types.py +++ b/braggtrack/types.py @@ -18,9 +18,14 @@ class SpotRecord(TypedDict, total=False): label: int voxel_count: int integrated_intensity: float + net_intensity: float + background_level: float centroid_mu: float centroid_chi: float centroid_d: float + centroid_mu_err: float + centroid_chi_err: float + centroid_d_err: float bbox_min_z: int bbox_max_z: int bbox_min_y: int @@ -36,6 +41,18 @@ class SpotRecord(TypedDict, total=False): eig_1: float eig_2: float eig_3: float + vox_eig_1: float + vox_eig_2: float + vox_eig_3: float + kurtosis_mu: float + kurtosis_chi: float + kurtosis_d: float + step_mu: float + step_chi: float + step_d: float + calibrated: int + touches_border: bool + touches_rocking_border: bool # Optional — semantic stage embedding: np.ndarray diff --git a/braggtrack/viz/html_report.py b/braggtrack/viz/html_report.py index deeaa2d..d938cde 100644 --- a/braggtrack/viz/html_report.py +++ b/braggtrack/viz/html_report.py @@ -219,6 +219,7 @@ def build_explorer_payload( events_list.append( { "event_type": etype, + "split_subtype": str(r.get("split_subtype", "")), "parent_scan": int(float(r.get("scan_idx_from", r.get("parent_scan", 0)))), "child_scan": int(float(r.get("scan_idx_to", r.get("child_scan", 1)))), "parent_track_ids": ptids, @@ -395,6 +396,7 @@ def build_explorer_payload( + __TITLE__