| """Known-answer tests for ISO 11146 beam widths, using the simulator."""
|
|
|
| from dataclasses import replace
|
|
|
| import numpy as np
|
| import pytest
|
|
|
| from beampilot.simulator import (
|
| BeamParams,
|
| CameraConfig,
|
| beam_diameter,
|
| dark_frame,
|
| render_frame,
|
| )
|
| from beampilot.widths import (
|
| Roi,
|
| mean_dark,
|
| measure_widths,
|
| second_moments,
|
| subtract_background,
|
| width_statistics,
|
| )
|
|
|
|
|
| BEAM = BeamParams(
|
| wavelength_m=1064e-9,
|
| d0x_m=0.5e-3,
|
| d0y_m=0.4e-3,
|
| z0x_m=0.10,
|
| z0y_m=0.12,
|
| m2x=1.2,
|
| m2y=1.5,
|
| )
|
| CAMERA = CameraConfig(
|
| pixel_size_m=5.5e-6,
|
| nx=512,
|
| ny=512,
|
| bit_depth=12,
|
| offset_counts=100.0,
|
| read_noise_counts=5.0,
|
| signal_counts_per_ms=1e6,
|
| )
|
|
|
|
|
| NOISELESS = replace(CAMERA, offset_counts=0.0, read_noise_counts=0.0, shot_noise=False)
|
| PIXEL_M = CAMERA.pixel_size_m
|
| Z_M = 0.25
|
| EXPOSURE_MS = 20.0
|
|
|
|
|
| CORNER_MEAN_TOL = 4 * 5.2 / np.sqrt(4 * 18 * 18)
|
|
|
|
|
| def _darks(camera: CameraConfig, n: int, seed: int) -> list[np.ndarray]:
|
| rng = np.random.default_rng(seed)
|
| return [dark_frame(camera, rng) for _ in range(n)]
|
|
|
|
|
| def _true_diameters(beam: BeamParams, z_m: float) -> tuple[float, float]:
|
| d_x = beam_diameter(z_m, beam.d0x_m, beam.z0x_m, beam.m2x, beam.wavelength_m)
|
| d_y = beam_diameter(z_m, beam.d0y_m, beam.z0y_m, beam.m2y, beam.wavelength_m)
|
| return float(d_x), float(d_y)
|
|
|
|
|
| def _rotated_ellipse(
|
| sigma_major_px: float, sigma_minor_px: float, angle_rad: float, n: int = 512
|
| ) -> np.ndarray:
|
| """Noiseless elliptical Gaussian, major axis at `angle_rad` from x."""
|
| y, x = np.indices((n, n)) - (n - 1) / 2.0
|
| u = x * np.cos(angle_rad) + y * np.sin(angle_rad)
|
| v = -x * np.sin(angle_rad) + y * np.cos(angle_rad)
|
| return 1000.0 * np.exp(
|
| -0.5 * (u / sigma_major_px) ** 2 - 0.5 * (v / sigma_minor_px) ** 2
|
| )
|
|
|
|
|
| @pytest.mark.parametrize(
|
| "roi", [Roi(0, 512, 0, 512), Roi(18, 453, 89, 408)], ids=["full", "8sigma"]
|
| )
|
| def test_second_moments_of_analytic_gaussian(roi: Roi) -> None:
|
| """Rotated, off-centre Gaussian sampled at pixel centres.
|
|
|
| Expected: centroid (x0, y0); sigma_x² = a² cos² + b² sin²,
|
| sigma_y² = a² sin² + b² cos², sigma_xy = (a² - b²) sin cos; sum = 2 pi a b A.
|
| Projected sigmas are 27.0 px (x) and 19.8 px (y); both ROIs reach at least
|
| 8 sigma from the centroid, and sampling at >= 15 px sigma is exact for a
|
| Gaussian, so both effects stay far below 1e-9 relative.
|
| """
|
| n, peak = 512, 1000.0
|
| a_px, b_px, angle = 30.0, 15.0, np.radians(30.0)
|
| x0_px, y0_px = -20.3, -7.6
|
| y, x = np.indices((n, n)) - (n - 1) / 2.0
|
| u = (x - x0_px) * np.cos(angle) + (y - y0_px) * np.sin(angle)
|
| v = -(x - x0_px) * np.sin(angle) + (y - y0_px) * np.cos(angle)
|
| image = peak * np.exp(-0.5 * (u / a_px) ** 2 - 0.5 * (v / b_px) ** 2)
|
|
|
| moments = second_moments(image, PIXEL_M, roi)
|
|
|
| c, s = np.cos(angle), np.sin(angle)
|
| p2 = PIXEL_M**2
|
| assert moments.x_c_m == pytest.approx(x0_px * PIXEL_M, rel=1e-9)
|
| assert moments.y_c_m == pytest.approx(y0_px * PIXEL_M, rel=1e-9)
|
| assert moments.var_x_m2 == pytest.approx((a_px**2 * c**2 + b_px**2 * s**2) * p2)
|
| assert moments.var_y_m2 == pytest.approx((a_px**2 * s**2 + b_px**2 * c**2) * p2)
|
| assert moments.cov_xy_m2 == pytest.approx((a_px**2 - b_px**2) * s * c * p2)
|
| assert moments.total_counts == pytest.approx(2 * np.pi * a_px * b_px * peak)
|
|
|
|
|
| def test_noiseless_centred_beam() -> None:
|
| frame = render_frame(BEAM, NOISELESS, Z_M, EXPOSURE_MS, np.random.default_rng(0))
|
| result = measure_widths(frame, PIXEL_M)
|
| true_x, true_y = _true_diameters(BEAM, Z_M)
|
| assert result.converged
|
| assert result.d_x_m == pytest.approx(true_x, rel=0.005)
|
| assert result.d_y_m == pytest.approx(true_y, rel=0.005)
|
|
|
|
|
| def test_centred_beam_roi_not_clipped_and_holds_the_signal() -> None:
|
| frame = render_frame(BEAM, NOISELESS, Z_M, EXPOSURE_MS, np.random.default_rng(0))
|
| result = measure_widths(frame, PIXEL_M)
|
| assert not result.roi_clipped
|
| roi = result.roi
|
| assert 0 < roi.x_start < roi.x_stop < NOISELESS.nx
|
| assert 0 < roi.y_start < roi.y_stop < NOISELESS.ny
|
|
|
| total_counts = NOISELESS.signal_counts_per_ms * EXPOSURE_MS
|
| assert result.roi_sum_counts == pytest.approx(total_counts, rel=0.005)
|
| assert result.roi_sum_counts == pytest.approx(
|
| frame[roi.y_start : roi.y_stop, roi.x_start : roi.x_stop].sum()
|
| )
|
|
|
|
|
| def test_beam_cut_by_sensor_edge_flags_roi_clipped() -> None:
|
| """A beam 1.35 mm off-centre on a 2.8 mm sensor converges ~34 % too small.
|
|
|
| Nothing else in the result reveals this, so roi_clipped must.
|
| """
|
| rng = np.random.default_rng(0)
|
| frame = render_frame(BEAM, NOISELESS, Z_M, EXPOSURE_MS, rng, x0_m=1.35e-3)
|
| result = measure_widths(frame, PIXEL_M)
|
| true_x, _ = _true_diameters(BEAM, Z_M)
|
| assert result.converged
|
| assert result.d_x_m < 0.8 * true_x
|
| assert result.roi_clipped
|
| assert result.roi.x_stop == NOISELESS.nx
|
|
|
|
|
| def test_off_centre_beam_gives_same_width_and_correct_centroid() -> None:
|
| x0_m, y0_m = 300e-6, -200e-6
|
| rng = np.random.default_rng(0)
|
| frame = render_frame(BEAM, NOISELESS, Z_M, EXPOSURE_MS, rng, x0_m=x0_m, y0_m=y0_m)
|
| result = measure_widths(frame, PIXEL_M)
|
| true_x, true_y = _true_diameters(BEAM, Z_M)
|
| assert result.d_x_m == pytest.approx(true_x, rel=0.005)
|
| assert result.d_y_m == pytest.approx(true_y, rel=0.005)
|
| assert result.x_c_m == pytest.approx(x0_m, abs=0.05 * PIXEL_M)
|
| assert result.y_c_m == pytest.approx(y0_m, abs=0.05 * PIXEL_M)
|
|
|
|
|
| def test_astigmatic_beam_recovers_both_widths() -> None:
|
| beam = replace(
|
| BEAM, d0x_m=0.3e-3, d0y_m=0.6e-3, z0x_m=0.0, z0y_m=0.0, m2x=1.0, m2y=1.0
|
| )
|
| frame = render_frame(beam, NOISELESS, 0.0, 4.0, np.random.default_rng(0))
|
| result = measure_widths(frame, PIXEL_M)
|
| assert result.d_x_m == pytest.approx(0.3e-3, rel=0.005)
|
| assert result.d_y_m == pytest.approx(0.6e-3, rel=0.005)
|
| assert result.ellipticity == pytest.approx(0.5, rel=0.01)
|
| assert abs(result.azimuth_rad) == pytest.approx(np.pi / 2, abs=np.radians(0.5))
|
|
|
|
|
| @pytest.mark.parametrize("angle_deg", [25.0, -60.0])
|
| def test_rotated_ellipse_azimuth_recovered(angle_deg: float) -> None:
|
| angle = np.radians(angle_deg)
|
| sigma_major, sigma_minor = 40.0, 20.0
|
| image = _rotated_ellipse(sigma_major, sigma_minor, angle)
|
| result = measure_widths(image, PIXEL_M)
|
|
|
| assert result.azimuth_rad == pytest.approx(angle, abs=np.radians(0.5))
|
| assert result.ellipticity == pytest.approx(sigma_minor / sigma_major, rel=0.01)
|
|
|
| var_x_px = (sigma_major * np.cos(angle)) ** 2 + (sigma_minor * np.sin(angle)) ** 2
|
| assert result.d_x_m == pytest.approx(4 * np.sqrt(var_x_px) * PIXEL_M, rel=0.005)
|
|
|
|
|
| def test_iteration_converges_before_max_iter() -> None:
|
| dark = mean_dark(_darks(CAMERA, 10, seed=0))
|
| frame = render_frame(BEAM, CAMERA, Z_M, EXPOSURE_MS, np.random.default_rng(1))
|
| image, _ = subtract_background(frame, dark)
|
| result = measure_widths(image, PIXEL_M, max_iter=25)
|
| assert result.converged
|
| assert result.iterations < 25
|
|
|
|
|
| def test_dim_noisy_frames_all_converge() -> None:
|
| """At peak ~430 counts the 3 x d rectangle can flip by one pixel each pass.
|
|
|
| Each frame gets its own dark set, as in a real run. Before the
|
| repeated-rectangle stopping rule, 20 of the first 100 seeds hit max_iter.
|
| """
|
| dim_exposure_ms = 3.0
|
|
|
|
|
| for seed in range(50):
|
| dark = mean_dark(_darks(CAMERA, 10, seed=seed + 10_000))
|
| rng = np.random.default_rng(seed)
|
| frame = render_frame(BEAM, CAMERA, Z_M, dim_exposure_ms, rng)
|
| image, _ = subtract_background(frame, dark)
|
| result = measure_widths(image, PIXEL_M, max_iter=25)
|
| assert result.converged, f"seed {seed}"
|
| assert result.iterations < 25, f"seed {seed}"
|
| assert np.isfinite(result.d_x_m) and np.isfinite(result.d_y_m)
|
|
|
|
|
| def test_small_beam_with_residual_offset_is_measured() -> None:
|
| """A 200 um beam holds only ~3e6 counts at 70 % of full scale.
|
|
|
| A residual offset of ~0.2 counts (the corner estimate's standard error is
|
| ~0.15) summed with r² weights over the full sensor outweighs the beam's
|
| sigma², so a full-image first pass gave negative second moments on
|
| several of these frames. The 1/e² start area avoids that.
|
| """
|
| small = replace(BEAM, d0x_m=0.2e-3, d0y_m=0.2e-3, z0x_m=0.0, z0y_m=0.0)
|
| small = replace(small, m2x=1.0, m2y=1.0)
|
| exposure_ms = 1.5
|
| dark = mean_dark(_darks(CAMERA, 10, seed=0))
|
| rng = np.random.default_rng(7)
|
| results = []
|
| for _ in range(20):
|
| frame = render_frame(small, CAMERA, 0.0, exposure_ms, rng)
|
| image, _ = subtract_background(frame, dark)
|
| result = measure_widths(image, PIXEL_M)
|
| assert result.converged and not result.roi_clipped
|
| results.append(result)
|
| stats = width_statistics(results)
|
| assert stats.d_x_mean_m == pytest.approx(0.2e-3, rel=0.01)
|
| assert stats.d_y_mean_m == pytest.approx(0.2e-3, rel=0.01)
|
|
|
|
|
| def test_realistic_frames_mean_of_five_repeats() -> None:
|
| dark = mean_dark(_darks(CAMERA, 10, seed=0))
|
| rng = np.random.default_rng(1)
|
| results = []
|
| for _ in range(5):
|
| frame = render_frame(BEAM, CAMERA, Z_M, EXPOSURE_MS, rng)
|
| image, _ = subtract_background(frame, dark)
|
| results.append(measure_widths(image, PIXEL_M))
|
|
|
| stats = width_statistics(results)
|
| true_x, true_y = _true_diameters(BEAM, Z_M)
|
| assert stats.n == 5
|
| assert stats.d_x_mean_m == pytest.approx(true_x, rel=0.02)
|
| assert stats.d_y_mean_m == pytest.approx(true_y, rel=0.02)
|
| assert 0 < stats.d_x_std_m < 0.02 * true_x
|
| assert 0 < stats.d_y_std_m < 0.02 * true_y
|
|
|
|
|
| def test_skipping_fine_offset_makes_beam_look_larger() -> None:
|
| """Negative control: why the corner offset correction matters."""
|
| dark = mean_dark(_darks(CAMERA, 10, seed=0))
|
|
|
| brighter = replace(CAMERA, offset_counts=CAMERA.offset_counts + 3.0)
|
| frame = render_frame(BEAM, brighter, Z_M, EXPOSURE_MS, np.random.default_rng(1))
|
| true_x, true_y = _true_diameters(BEAM, Z_M)
|
|
|
| dark_only = measure_widths(frame - dark, PIXEL_M)
|
| corrected_image, _ = subtract_background(frame, dark)
|
| corrected = measure_widths(corrected_image, PIXEL_M)
|
|
|
| assert dark_only.d_x_m > 1.15 * true_x
|
| assert dark_only.d_y_m > 1.15 * true_y
|
| assert corrected.d_x_m == pytest.approx(true_x, rel=0.02)
|
| assert corrected.d_y_m == pytest.approx(true_y, rel=0.02)
|
|
|
|
|
| def test_width_statistics_single_and_empty() -> None:
|
| image = _rotated_ellipse(40.0, 20.0, 0.0)
|
| single = width_statistics([measure_widths(image, PIXEL_M)])
|
| assert single.n == 1
|
| assert np.isnan(single.d_x_std_m)
|
| with pytest.raises(ValueError):
|
| width_statistics([])
|
|
|
|
|
| @pytest.mark.parametrize("level", [0.0, -1.0])
|
| def test_no_beam_gives_nan_not_crash(level: float) -> None:
|
| image = np.full((64, 64), level)
|
| result = measure_widths(image, PIXEL_M)
|
| assert np.isnan(result.d_x_m) and np.isnan(result.d_y_m)
|
| assert not result.converged
|
|
|
|
|
| @pytest.mark.parametrize(
|
| "roi",
|
| [
|
| Roi(-1, 10, 0, 10),
|
| Roi(0, 65, 0, 10),
|
| Roi(0, 10, 0, 65),
|
| Roi(10, 10, 0, 10),
|
| Roi(20, 10, 0, 10),
|
| ],
|
| )
|
| def test_second_moments_rejects_bad_roi(roi: Roi) -> None:
|
| with pytest.raises(ValueError, match="roi"):
|
| second_moments(np.ones((64, 64)), PIXEL_M, roi)
|
|
|
|
|
| @pytest.mark.parametrize("pixel_size_m", [0.0, -5.5e-6, np.nan])
|
| def test_non_positive_pixel_size_raises(pixel_size_m: float) -> None:
|
| image = _rotated_ellipse(10.0, 10.0, 0.0, n=64)
|
| with pytest.raises(ValueError, match="pixel_size_m"):
|
| second_moments(image, pixel_size_m, Roi(0, 64, 0, 64))
|
| with pytest.raises(ValueError, match="pixel_size_m"):
|
| measure_widths(image, pixel_size_m)
|
|
|
|
|
| def test_fewer_than_ten_dark_frames_raises() -> None:
|
| with pytest.raises(ValueError, match="at least 10"):
|
| mean_dark(_darks(CAMERA, 9, seed=0))
|
|
|
|
|
| def test_mean_dark_averages_frames() -> None:
|
| dark = mean_dark(_darks(CAMERA, 10, seed=0))
|
| assert dark.shape == (CAMERA.ny, CAMERA.nx)
|
| assert dark.mean() == pytest.approx(CAMERA.offset_counts, abs=0.1)
|
|
|
| assert dark.std() == pytest.approx(CAMERA.read_noise_counts / np.sqrt(10), rel=0.05)
|
|
|
|
|
| def test_negative_values_survive_background_subtraction() -> None:
|
| dark = mean_dark(_darks(CAMERA, 10, seed=0))
|
| frame = dark_frame(CAMERA, np.random.default_rng(1))
|
| image, _ = subtract_background(frame, dark)
|
| assert image.dtype == np.float64
|
| assert (image < 0).sum() > 0.4 * image.size
|
| assert image.mean() == pytest.approx(0.0, abs=CORNER_MEAN_TOL)
|
|
|
|
|
| def test_fine_offset_removes_residual_background() -> None:
|
| dark = mean_dark(_darks(CAMERA, 10, seed=0))
|
| extra_counts = 3.0
|
| frame = dark_frame(CAMERA, np.random.default_rng(1)) + extra_counts
|
| image, info = subtract_background(frame, dark)
|
| assert info.offset_counts == pytest.approx(extra_counts, abs=CORNER_MEAN_TOL)
|
| assert info.std_counts == pytest.approx(
|
| CAMERA.read_noise_counts * np.sqrt(1 + 1 / 10), rel=0.1
|
| )
|
|
|
| n_corner = 4 * 18 * 18
|
| assert info.offset_std_err_counts == pytest.approx(
|
| info.std_counts / np.sqrt(n_corner)
|
| )
|
| assert len(info.corner_means_counts) == 4
|
| assert image.mean() == pytest.approx(0.0, abs=CORNER_MEAN_TOL)
|
|
|
