backscattermeter_analyzer 2.2.2__tar.gz → 3.0.1__tar.gz

backscattermeter_analyzer-3.0.1/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: backscattermeter_analyzer
+Version: 3.0.1
+Summary: Tool to work on the backscattermeter at LAPP
+Project-URL: Documentation, https://git.linarphy.net/linarphy/backscattermeter_analyzer/wiki
+Project-URL: Homepage, https://git.linarphy.net/linarphy/backscattermeter_analyzer
+Project-URL: Source, https://git.linarphy.net/linarphy/backscattermeter_analyzer
+Project-URL: Issues, https://git.linarphy.net/linarphy/backscattermeter_analyzer/issues
+Author-email: linarphy <linarphy@linarphy.net>
+License-File: LICENSE
+Keywords: backscattered light,virgo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.14.7
+Requires-Dist: gwpy>=3.0.12
+Requires-Dist: lalsuite>=7.26.15
+Requires-Dist: pyqt6>=6.9.1
+Requires-Dist: pyusb>=1.3.1
+Requires-Dist: rich>=13.9.4
+Description-Content-Type: text/markdown
+
+# Backscattermeter analyzer
+
+Help working with [the backscattermeter at LAPP](https://doi.org/10.48550/arXiv.2202.07370).
+
+This tools can characterize the experiment itself, or make
+${ f } _ { sc }$ or *BRDF* measurement with a focus on uncertainty
+propagation.
+
+## Getting started
+
+### Requirements
+
+- Python >= 3.14
+- GWpy >= 3.0.12 (data type, computation)
+- pyusb >= 1.3.1 (interaction with actuator/sensor - not used yet)
+- pyqt6 >= 6.9.1 (visualization - not used yet)
+- rich >= 13.9.4 (console output)
+- lalsuite >= 7.26.15 (data format - not used yet)
+
+### Installation
+
+To install this package in the current python environment, use
+
+```sh
+python -m pip install backscattermeter_analyzer
+```
+
+### Usage
+
+```py
+from backscattermeter_analyzer import (
+    Acquisition,
+    AnalysisBuilder,
+    Backscattermeter,
+    Camera,
+    ProtocolBuilder,
+)
+from gwpy.timeseries import TimeSeriesDict
+
+# build a protocol with a camera that save the position of the beam and
+# with a snail movement of the motor.
+protocol = (
+    ProtocolBuilder(Backscattermeter())
+    .with_camera_on_suspended_bench(
+        camera=Camera(
+            id_="an nice identifier of the camera for human",
+            serial_number="1359",
+        ),
+        position=3e-2, # in m
+        error=5e-3, # in m
+    )
+    .with_camera_channels( # X and Y are reversed on this camera !
+        pos_x="V1:Camera_scatter_FitPosY",
+        pos_y="V1:Camera_scatter_FitPosX",
+    )
+    .with_snail_motor_path(
+        number=3,
+        duration=10,
+        speed=50,
+        step_numbers=(100, 100, 100, 100),
+    )
+    .build()
+)
+# convert it to an acquisition with real data
+acquisition = Acquisition(
+    protocol=protocol,
+    data=TimeSeriesDict.read("data.gwf"),
+)
+
+# build an analysis where we will get the time interval in which the
+# motor is moving. We don't want these data as they are noisy, so this
+# can be used later for another analysis that needs stable segment.
+analysis = (
+    AnalysisBuilder()
+    .with_step_split([acquisition])
+    .build()
+)
+
+# run the analysis, return a result object
+result = analysis.run()
+
+print(result.representation.structure.with_step_split[0].start_times[0])
+# this will print the start of the segment that contains transition data
+# in camera position measurement.
+```
+
+## Documentation
+
+A complete documentation will be available soon, in a wiki.
+
+## Development
+
+### Development Requirements
+
+This project use [mise](https://mise.jdx.dev) to manage development
+tools.
+
+> [!TIP]
+> If [mise](https://mise.jdx.dev) is installed, and
+> [mise.toml](mise.toml) is trusted with `mise trust`, all tools can be
+> installed automatically with `mise install`
+
+This project use the following tools:
+
+- [just](https://just.systems): command runner
+- [hatch](https://hatch.pypa.io): project manager and package builder
+- [uv](https://docs.astral.sh/uv): package installer
+- [ruff](https://docs.astral.sh/ruff): python linter and formatter
+- [ty](https://docs.astra.sh/ty): python type checker
+- [jujutsu](https://jj-vcs.dev): version control
+
+> [!NOTE]
+> Tools used in the project consume and produce interoperable format to
+> avoid vendor lock-in. This is the toolchain of the current maintener.
+
+### Development Usage
+
+[just](https://just.system) can be used to speed up development for an
+identical toolchain.
+
+Before making a commit, `just fix` will run all tests, format the code,
+lint and type check. If you don’t want to modify the code, `just check`
+will run all tests, lint and type check without any attempt to fix any
+issue.
+
+Before a version change, `just release` will push all local commits to
+repository and publish the new package version.
+
+All available commands can be listed with `just -l`.
+
+## License
+
+This project is licensed under the GNU GPL v3+.
+See [license file](LICENSE) for more information.
+
+## Acknowledgement
+
+Thanks to all the people that worked on the tools used, like python,
+neovim and mise.

backscattermeter_analyzer-3.0.1/README.md

@@ -0,0 +1,139 @@
+# Backscattermeter analyzer
+
+Help working with [the backscattermeter at LAPP](https://doi.org/10.48550/arXiv.2202.07370).
+
+This tools can characterize the experiment itself, or make
+${ f } _ { sc }$ or *BRDF* measurement with a focus on uncertainty
+propagation.
+
+## Getting started
+
+### Requirements
+
+- Python >= 3.14
+- GWpy >= 3.0.12 (data type, computation)
+- pyusb >= 1.3.1 (interaction with actuator/sensor - not used yet)
+- pyqt6 >= 6.9.1 (visualization - not used yet)
+- rich >= 13.9.4 (console output)
+- lalsuite >= 7.26.15 (data format - not used yet)
+
+### Installation
+
+To install this package in the current python environment, use
+
+```sh
+python -m pip install backscattermeter_analyzer
+```
+
+### Usage
+
+```py
+from backscattermeter_analyzer import (
+    Acquisition,
+    AnalysisBuilder,
+    Backscattermeter,
+    Camera,
+    ProtocolBuilder,
+)
+from gwpy.timeseries import TimeSeriesDict
+
+# build a protocol with a camera that save the position of the beam and
+# with a snail movement of the motor.
+protocol = (
+    ProtocolBuilder(Backscattermeter())
+    .with_camera_on_suspended_bench(
+        camera=Camera(
+            id_="an nice identifier of the camera for human",
+            serial_number="1359",
+        ),
+        position=3e-2, # in m
+        error=5e-3, # in m
+    )
+    .with_camera_channels( # X and Y are reversed on this camera !
+        pos_x="V1:Camera_scatter_FitPosY",
+        pos_y="V1:Camera_scatter_FitPosX",
+    )
+    .with_snail_motor_path(
+        number=3,
+        duration=10,
+        speed=50,
+        step_numbers=(100, 100, 100, 100),
+    )
+    .build()
+)
+# convert it to an acquisition with real data
+acquisition = Acquisition(
+    protocol=protocol,
+    data=TimeSeriesDict.read("data.gwf"),
+)
+
+# build an analysis where we will get the time interval in which the
+# motor is moving. We don't want these data as they are noisy, so this
+# can be used later for another analysis that needs stable segment.
+analysis = (
+    AnalysisBuilder()
+    .with_step_split([acquisition])
+    .build()
+)
+
+# run the analysis, return a result object
+result = analysis.run()
+
+print(result.representation.structure.with_step_split[0].start_times[0])
+# this will print the start of the segment that contains transition data
+# in camera position measurement.
+```
+
+## Documentation
+
+A complete documentation will be available soon, in a wiki.
+
+## Development
+
+### Development Requirements
+
+This project use [mise](https://mise.jdx.dev) to manage development
+tools.
+
+> [!TIP]
+> If [mise](https://mise.jdx.dev) is installed, and
+> [mise.toml](mise.toml) is trusted with `mise trust`, all tools can be
+> installed automatically with `mise install`
+
+This project use the following tools:
+
+- [just](https://just.systems): command runner
+- [hatch](https://hatch.pypa.io): project manager and package builder
+- [uv](https://docs.astral.sh/uv): package installer
+- [ruff](https://docs.astral.sh/ruff): python linter and formatter
+- [ty](https://docs.astra.sh/ty): python type checker
+- [jujutsu](https://jj-vcs.dev): version control
+
+> [!NOTE]
+> Tools used in the project consume and produce interoperable format to
+> avoid vendor lock-in. This is the toolchain of the current maintener.
+
+### Development Usage
+
+[just](https://just.system) can be used to speed up development for an
+identical toolchain.
+
+Before making a commit, `just fix` will run all tests, format the code,
+lint and type check. If you don’t want to modify the code, `just check`
+will run all tests, lint and type check without any attempt to fix any
+issue.
+
+Before a version change, `just release` will push all local commits to
+repository and publish the new package version.
+
+All available commands can be listed with `just -l`.
+
+## License
+
+This project is licensed under the GNU GPL v3+.
+See [license file](LICENSE) for more information.
+
+## Acknowledgement
+
+Thanks to all the people that worked on the tools used, like python,
+neovim and mise.

{backscattermeter_analyzer-2.2.2 → backscattermeter_analyzer-3.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "backscattermeter_analyzer"
-version = "2.2.2"
+version = "3.0.1"
 description = "Tool to work on the backscattermeter at LAPP"
 authors = [{ name = "linarphy", email = "linarphy@linarphy.net" }]
 readme = "README.md"
@@ -129,10 +129,21 @@ indent-style = "space"
 docstring-code-format = true
 
 [tool.ty.src]
-exclude = ["tests/**/*.py", "display.py", "utils.py"]
+exclude = [
+  "tests/**/*.py",
+  "display.py",
+  "utils.py",
+  "src/backscattermeter_analyzer/beam/**/*.py",
+  "src/backscattermeter_analyzer/characterize/**/*.py",
+  "src/backscattermeter_analyzer/utils/distance/**/*.py",
+  "src/backscattermeter_analyzer/utils/measurement/**/*.py",
+  "src/backscattermeter_analyzer/utils/ratio/**/*.py",
+  "src/backscattermeter_analyzer/utils/result/**/*.py",
+  "src/backscattermeter_analyzer/io/hdf5/**/*.py",
+]
 
 
 [dependency-groups]
-dev = ["ty>=0.0.28", "ruff>=0.11.2"]
+dev = ["ty>=0.0.83", "ruff>=0.16.8"]
 stubs = ["mypy<=1.20.0"]
 test = ["coverage>=7.14", "rich"]

backscattermeter_analyzer-3.0.1/src/backscattermeter_analyzer/__init__.py

@@ -0,0 +1,30 @@
+"""Entry-point package."""
+
+from .axis import Axis  # noqa: I001
+from .direction import Direction
+
+from .experiment import (
+    Acquisition,
+    Analysis,
+    AnalysisBuilder,
+    Protocol,
+    ProtocolBuilder,
+    Result,
+)
+from .hardware import Backscattermeter, Camera, Motor, Optic, Photodiode
+
+__all__ = [
+    "Acquisition",
+    "Analysis",
+    "AnalysisBuilder",
+    "Axis",
+    "Backscattermeter",
+    "Camera",
+    "Direction",
+    "Motor",
+    "Optic",
+    "Photodiode",
+    "Protocol",
+    "ProtocolBuilder",
+    "Result",
+]

backscattermeter_analyzer-3.0.1/src/backscattermeter_analyzer/beam/__init__.py

@@ -0,0 +1,9 @@
+"""Sub-package managing object focused on beam."""
+
+from .beam import Beam
+from .waist import Waist
+
+__all__ = [
+    "Beam",
+    "Waist",
+]

backscattermeter_analyzer-3.0.1/src/backscattermeter_analyzer/beam/beam.py

@@ -0,0 +1,266 @@
+"""Beam class."""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, NamedTuple
+
+from astropy.modeling.fitting import TRFLSQFitter
+from astropy.uncertainty import Distribution
+from astropy.units import Quantity
+from numpy import argmin, pi
+from numpy.random import default_rng
+
+from .gaussian_model import GaussianBeam
+from .waist import Waist
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from gwpy.timeseries import TimeSeries
+    from numpy.random import Generator
+
+    from backscattermeter_analyzer import Measurement
+
+
+class GaussianBeamModels(NamedTuple):
+    """Utils to share x and y models."""
+
+    x: GaussianBeam
+    y: GaussianBeam
+
+
+class MeasurementData(NamedTuple):
+    """Utils to share measurements result."""
+
+    position: Distribution
+    radius_x: TimeSeries
+    radius_y: TimeSeries
+
+
+class FitSamples(NamedTuple):
+    """Utils to share samples that will be used in fit."""
+
+    positions: Quantity
+    radii_x: Quantity
+    radii_y: Quantity
+
+
+def _extract_measurement_data(
+    measurement: Measurement,
+) -> MeasurementData:
+    """Convert a Measurement into a simpler object for analysis."""
+
+    position = measurement.state.backscattermeter.state.camera.position
+    beam_radius = measurement.state.camera.beam_radius
+
+    if not position.is_on_suspended_bench():
+        message = (
+            "Camera position can only be known if the camera is on "
+            "the suspended bench."
+        )
+        raise ValueError(message)
+    if not measurement.state.camera.has_beam_radius():
+        message = (
+            "Cannot compute the waist of the beam from a "
+            "Measurement that do not contain any data on the beam "
+            "radius."
+        )
+        raise ValueError(message)
+
+    return MeasurementData(
+        position=position.distance_from_entrance,
+        radius_x=beam_radius.w_x,
+        radius_y=beam_radius.w_y,
+    )
+
+
+def _fit_initial_model(
+    positions: Sequence[Quantity],
+    radii: Sequence[Quantity],
+    wavelength: Quantity,
+) -> GaussianBeam:
+    """Find approximative values for future guesses on one axis."""
+
+    waist_index = int(argmin(radii))
+
+    radius_waist = radii[waist_index]
+    position_waist = positions[waist_index]
+    rayleigh_range = pi * radius_waist**2 / wavelength
+
+    return GaussianBeam(  # type: ignore[ty:invalid-argument-type,ty:missing-argument]
+        position_waist=position_waist,
+        radius_waist=radius_waist,
+        rayleigh_range=rayleigh_range,
+    )
+
+
+@staticmethod
+def _fit_initial_models(
+    data: Sequence[MeasurementData], wavelength: Quantity
+) -> GaussianBeamModels:
+    """Find approximative values for future guesses."""
+
+    positions = [item.position.pdf_mean() for item in data]
+    radii_x = [item.radius_x.mean() for item in data]
+    radii_y = [item.radius_y.mean() for item in data]
+
+    return GaussianBeamModels(
+        x=_fit_initial_model(positions, radii_x, wavelength),
+        y=_fit_initial_model(positions, radii_y, wavelength),
+    )
+
+
+@staticmethod
+def _samples_data(
+    data: Sequence[MeasurementData],
+    n_samples: int,
+    random_generator: Generator,
+) -> FitSamples:
+    """
+    Define samples of measurements value.
+
+    n_samples fits will be done, with one position per measurement
+    and one radius per measurement. This means that a fit will use
+    len(measurements) positions and radius.
+
+    It keeps a link between w_x and w_y as they are identicaly
+    sampled. Meaning that we can keep the covariance data between
+    w_x and w_y.
+    """
+
+    positions_samples_list: list[Quantity] = []
+    radii_x_samples_list: list[Quantity] = []
+    radii_y_samples_list: list[Quantity] = []
+
+    for measurement in data:
+        positions_indexes = random_generator.integers(
+            0, measurement.position.n_samples, size=n_samples
+        )
+        radii_indexes = random_generator.integers(
+            0, len(measurement.radius_x.value), size=n_samples
+        )
+
+        positions_samples_list.append(
+            measurement.position.distribution[positions_indexes]
+        )
+        radii_x_samples_list.append(
+            measurement.radius_x.value[radii_indexes]
+        )
+        radii_y_samples_list.append(
+            measurement.radius_y.value[radii_indexes]
+        )
+
+    return FitSamples(
+        positions=Quantity(positions_samples_list),
+        radii_x=Quantity(radii_x_samples_list),
+        radii_y=Quantity(radii_y_samples_list),
+    )
+
+
+def _fit_samples(
+    models: GaussianBeamModels,
+    samples: FitSamples,
+    fitter: TRFLSQFitter,
+    n_samples: int,
+    wavelength: Quantity,
+) -> Beam:
+    """Fit the samples to get distribution of n_samples."""
+
+    fitted_positions_x_list: list[Quantity] = []
+    fitted_positions_y_list: list[Quantity] = []
+    fitted_radii_x_list: list[Quantity] = []
+    fitted_radii_y_list: list[Quantity] = []
+
+    for i in range(n_samples):
+        positions = samples.positions[:, i]
+        fitted_x = fitter(
+            models.x.copy(),
+            positions,
+            samples.radii_x[:, i],
+        )
+        fitted_y = fitter(
+            models.y.copy(), positions, samples.radii_y[:, i]
+        )
+
+        fitted_positions_x_list.append(fitted_x.position_waist)
+        fitted_positions_y_list.append(fitted_y.position_waist)
+        fitted_radii_x_list.append(fitted_x.radius_waist)
+        fitted_radii_y_list.append(fitted_y.radius_waist)
+
+    return Beam(
+        waist_x=Waist(
+            position=Distribution(fitted_positions_x_list),
+            radius=Distribution(fitted_radii_x_list),
+        ),
+        waist_y=Waist(
+            position=Distribution(fitted_positions_y_list),
+            radius=Distribution(fitted_radii_y_list),
+        ),
+        wavelength=wavelength,
+    )
+
+
+@dataclass
+class Beam:
+    """Parameters of a 2D beam."""
+
+    waist_x: Waist
+    waist_y: Waist
+    wavelength: Quantity
+
+    @staticmethod
+    def compute(
+        measurements: Sequence[Measurement],
+        wavelength: Quantity,
+        n_samples: int = 1000,
+        random_generator: Generator | None = None,
+    ) -> Beam:
+        """
+        Compute a beam from multiple measurements.
+
+        Conserve the covariance between measurement of the beam radius
+        on the X axis and the beam radius on the Y one.
+        """
+
+        if len(measurements) < 3:  # noqa: PLR2004
+            message = "At least three measurements are required."
+            raise ValueError(message)
+
+        if n_samples < 1:
+            message = "`n_samples` must be positive."
+            raise ValueError(message)
+
+        if random_generator is None:
+            random_generator = default_rng()
+
+        data = [
+            _extract_measurement_data(measurement)
+            for measurement in measurements
+        ]
+        initial_models = _fit_initial_models(data, wavelength)
+
+        fitter = TRFLSQFitter()
+
+        positions = [datum.position.pdf_mean() for datum in data]
+
+        models = GaussianBeamModels(
+            x=fitter(
+                initial_models.x,
+                positions,
+                [datum.radius_x.mean() for datum in data],
+            ),
+            y=fitter(
+                initial_models.y,
+                positions,
+                [datum.radius_y.mean() for datum in data],
+            ),
+        )
+
+        samples = _samples_data(data, n_samples, random_generator)
+
+        return _fit_samples(
+            models,
+            samples,
+            fitter,
+            n_samples,
+            wavelength,
+        )

backscattermeter_analyzer-3.0.1/src/backscattermeter_analyzer/beam/gaussian_model.py

@@ -0,0 +1,66 @@
+"""GaussianBeam class."""
+
+from astropy.modeling import Fittable1DModel, Parameter
+from astropy.units import Quantity, Unit, m
+from numpy import sqrt
+
+
+class GaussianBeam(Fittable1DModel):
+    """1D Gaussian Beam model to fit with units."""
+
+    position_waist = Parameter(
+        description="Position of the beam waist", unit=m
+    )
+    radius_waist = Parameter(
+        description="Radius of the beam waist", unit=m, bounds=(0, None)
+    )
+    rayleigh_range = Parameter(
+        description="Rayleigh range", unit=m, bounds=(0, None)
+    )
+
+    @staticmethod
+    def evaluate(
+        position: Quantity,
+        position_waist: Quantity,
+        radius_waist: Quantity,
+        rayleigh_range: Quantity,
+    ) -> Quantity:  # type: ignore[ty:invalid-method-override]
+        """Fit function."""
+        return radius_waist * sqrt(
+            1 + ((position - position_waist) / rayleigh_range) ** 2
+        )
+
+    @property
+    def input_units(self) -> dict[str, Unit]:
+        """
+        Check input units.
+
+        See https://docs.astropy.org/en/stable/modeling/add-units.html.
+        """
+
+        return {
+            self.inputs[0]: self.position_waist.unit,
+        }
+
+    @property
+    def return_units(self) -> dict[str, Unit]:
+        """
+        Check output units.
+
+        See https://docs.astropy.org/en/stable/modeling/add-units.html.
+        """
+
+        return {
+            self.outputs[0]: self.radius_waist.unit,
+        }
+
+    def _parameter_units_for_data_units(
+        self,
+        inputs_unit: dict[str, Unit],
+        outputs_unit: dict[str, Unit],
+    ) -> dict[str, Unit]:
+        return {
+            "position_waist": inputs_unit[self.inputs[0]],
+            "radius_waist": outputs_unit[self.outputs[0]],
+            "rayleigh_range": inputs_unit[self.inputs[0]],
+        }