multipac-testbench 1.6.3__py3-none-any.whl

multipac_testbench/__init__.py

@@ -0,0 +1,5 @@
+"""This package stores all the function to study MULTIPAC testbench."""
+
+import importlib.metadata
+
+__version__ = importlib.metadata.version("multipac_testbench")

multipac_testbench/instruments/__init__.py

@@ -0,0 +1,44 @@
+"""This subpackage holds instrument (current, voltage, etc)."""
+
+from multipac_testbench.instruments.current_probe import CurrentProbe
+from multipac_testbench.instruments.electric_field.field_probe import (
+    FieldProbe,
+)
+from multipac_testbench.instruments.electric_field.i_electric_field import (
+    IElectricField,
+)
+from multipac_testbench.instruments.electric_field.reconstructed import (
+    Reconstructed,
+)
+from multipac_testbench.instruments.frequency import Frequency
+from multipac_testbench.instruments.instrument import Instrument
+from multipac_testbench.instruments.optical_fibre import OpticalFibre
+from multipac_testbench.instruments.penning import Penning
+from multipac_testbench.instruments.power import (
+    ForwardPower,
+    Power,
+    ReflectedPower,
+)
+from multipac_testbench.instruments.reflection_coefficient import (
+    ReflectionCoefficient,
+)
+from multipac_testbench.instruments.swr import SWR
+from multipac_testbench.instruments.virtual_instrument import VirtualInstrument
+
+__all__ = [
+    "CurrentProbe",
+    "IElectricField",
+    "FieldProbe",
+    "ForwardPower",
+    "Frequency",
+    "Instrument",
+    "OpticalFibre",
+    "OpticalFibre",
+    "Penning",
+    "Power",
+    "Reconstructed",
+    "ReflectedPower",
+    "ReflectionCoefficient",
+    "SWR",
+    "VirtualInstrument",
+]

multipac_testbench/instruments/current_probe.py

@@ -0,0 +1,16 @@
+"""Define current probe to measure multipactor cloud current."""
+
+from multipac_testbench.instruments.instrument import Instrument
+
+
+class CurrentProbe(Instrument):
+    """A probe to measure multipacting current."""
+
+    def __init__(self, *args, **kwargs) -> None:
+        """Just instantiate."""
+        return super().__init__(*args, **kwargs)
+
+    @classmethod
+    def ylabel(cls) -> str:
+        """Label used for plots."""
+        return r"Multipactor current [$\mu$A]"

multipac_testbench/instruments/electric_field/__init__.py

@@ -0,0 +1,8 @@
+r"""Define all :class:`.Instrument`\s measuring voltages, e fields.
+
+:class:`.FieldProbe` represents an electric field probe.
+:class:`.Reconstructed` is the electric field at every time and position of the
+coaxial, it is rebuilt from analytical laws fitted on the :class:`.FieldProbe`.
+Both these classes inherit from :class:`.IElectricField`.
+
+"""

multipac_testbench/instruments/electric_field/field_probe.py

@@ -0,0 +1,106 @@
+"""Define field probe to measure electric field."""
+
+from functools import partial
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from multipac_testbench.instruments.electric_field.i_electric_field import (
+    IElectricField,
+)
+from multipac_testbench.util.post_treaters import (
+    v_acquisition_to_v_coax,
+    v_coax_to_v_acquisition,
+)
+
+
+class FieldProbe(IElectricField):
+    """A probe to measure electric field."""
+
+    def __init__(
+        self,
+        *args,
+        g_probe: float | None = None,
+        calibration_file: str | None = None,
+        patch: bool = False,
+        **kwargs,
+    ) -> None:
+        r"""Instantiate with some specific arguments.
+
+        Parameters
+        ----------
+        g_probe :
+            Total attenuation. Probe specific, also depends on frequency.
+        a_rack :
+            Rack calibration slope in :unit:`V/dBm`.
+        b_rack :
+            Rack calibration constant in :unit:`dBm`.
+
+        """
+        super().__init__(*args, **kwargs)
+        self._g_probe = g_probe
+
+        self._a_rack: float
+        self._b_rack: float
+        if calibration_file is not None:
+            self._a_rack, self._b_rack = self._load_calibration_file(
+                Path(calibration_file)
+            )
+        if patch:
+            self._patch_data()
+
+    @classmethod
+    def ylabel(cls) -> str:
+        """Label used for plots."""
+        return r"Measured voltage [V]"
+
+    def _patch_data(self, g_probe_in_labview: float = -1.0) -> None:
+        """Correct  ``raw_data`` when ``g_probe`` in LabVIEWER is wrong.
+
+        The default value for ``g_probe_in_labview`` is only a guess.
+
+        """
+        assert hasattr(self, "_a_rack")
+        assert hasattr(self, "_b_rack")
+        assert self._g_probe is not None
+        fun1 = partial(
+            v_coax_to_v_acquisition,
+            g_probe=g_probe_in_labview,
+            a_rack=self._a_rack,
+            b_rack=self._b_rack,
+            z_0=50.0,
+        )
+        fun2 = partial(
+            v_acquisition_to_v_coax,
+            g_probe=self._g_probe,
+            a_rack=self._a_rack,
+            b_rack=self._b_rack,
+            z_0=50.0,
+        )
+        self._raw_data = fun1(self._raw_data)
+        self._raw_data = fun2(self._raw_data)
+
+    def _load_calibration_file(
+        self,
+        calibration_file: Path,
+        freq_mhz: float = 120.0,
+        freq_col: str = "Frequency [MHz]",
+        a_col: str = "a [dBm / V]",
+        b_col: str = "b [dBm]",
+    ) -> tuple[float, float]:
+        """Load calibration file, interpolate proper calibration data."""
+        data = pd.read_csv(
+            calibration_file,
+            sep="\t",
+            comment="#",
+            index_col=freq_col,
+            usecols=[a_col, b_col, freq_col],
+        )
+        if freq_mhz not in data.index:
+            data.loc[freq_mhz] = [np.nan, np.nan]
+            data.sort_index(inplace=True)
+            data.interpolate(inplace=True)
+        ser = data.loc[freq_mhz]
+        a_rack = ser[a_col]
+        b_rack = ser[b_col]
+        return a_rack, b_rack

multipac_testbench/instruments/electric_field/i_electric_field.py

@@ -0,0 +1,22 @@
+"""Define mother class for all instruments measuring electric fields."""
+
+import pandas as pd
+from multipac_testbench.instruments.instrument import Instrument
+
+
+class IElectricField(Instrument):
+    """A generic instrument for electric fields."""
+
+    def __init__(
+        self,
+        name: str,
+        raw_data: pd.Series,
+        **kwargs,
+    ) -> None:
+        """Instantiate the class."""
+        super().__init__(name, raw_data, **kwargs)
+
+    @classmethod
+    def ylabel(cls) -> str:
+        """Label used for plots."""
+        return r"Voltage [V]"

multipac_testbench/instruments/electric_field/reconstructed.py

@@ -0,0 +1,253 @@
+"""Define voltage along line.
+
+.. todo::
+    voltage fitting, overload: they work but this not clean, not clean at all
+
+"""
+
+import logging
+from collections.abc import Sequence
+from functools import partial
+from typing import overload
+
+import numpy as np
+import pandas as pd
+from multipac_testbench.instruments.electric_field.field_probe import (
+    FieldProbe,
+)
+from multipac_testbench.instruments.electric_field.i_electric_field import (
+    IElectricField,
+)
+from multipac_testbench.instruments.power import ForwardPower
+from multipac_testbench.instruments.reflection_coefficient import (
+    ReflectionCoefficient,
+)
+from multipac_testbench.util.helper import r_squared
+from numpy.typing import NDArray
+from scipy import optimize
+from scipy.constants import c
+
+
+class Reconstructed(IElectricField):
+    """Voltage in the coaxial waveguide, fitted with e field probes."""
+
+    def __init__(
+        self,
+        name: str,
+        raw_data: pd.Series | None,
+        e_field_probes: Sequence[FieldProbe],
+        forward_power: ForwardPower,
+        reflection: ReflectionCoefficient,
+        freq_mhz: float,
+        position: NDArray[np.float64] | None = None,
+        z_ohm: float = 50.0,
+        **kwargs,
+    ) -> None:
+        """Just instantiate."""
+        if position is None:
+            position = np.linspace(0.0, 1.3, 201, dtype=np.float64)
+        # from_array maybe
+        super().__init__(
+            name, raw_data, position=position, is_2d=True, **kwargs
+        )
+        self._e_field_probes = e_field_probes
+        self._forward_power = forward_power
+        self._reflection = reflection
+        self._sample_indexes = self._e_field_probes[0]._raw_data.index
+        self._beta = c / freq_mhz * 1e-6
+
+        self._psi_0: float
+        self._data: NDArray[np.float64] | None = None
+        self._z_ohm = z_ohm
+        self._r_squared: float
+
+    @classmethod
+    def ylabel(cls) -> str:
+        """Label used for plots."""
+        return r"Reconstructed voltage [V]"
+
+    @property
+    def data(self) -> NDArray[np.float64]:
+        """Give the calculated voltage at every pos and sample index.
+
+        .. note::
+            In contrary to most :class:`.Instrument` objects, here ``data`` is
+            2D. Axis are the following: ``data[sample_index, position_index]``
+
+        """
+        if self._data is not None:
+            return self._data
+
+        assert hasattr(self, "_psi_0")
+
+        data = []
+        for power, reflection in zip(
+            self._forward_power.data, self._reflection.data
+        ):
+            v_f = _power_to_volt(power, z_ohm=self._z_ohm)
+            data.append(
+                voltage_vs_position(
+                    self.position, v_f, reflection, self._beta, self._psi_0
+                )
+            )
+        self._data = np.array(data)
+        return self._data
+
+    @property
+    def fit_info(self) -> str:
+        """Print compact info on fit."""
+        out = rf"$\psi_0 = ${self._psi_0:2.3f}"
+        if not hasattr(self, "_r_squared"):
+            return out
+
+        return "\n".join([out, rf"$r^2 = ${self._r_squared:2.3f}"])
+
+    @property
+    def label(self) -> str:
+        """Label used for legends in plots vs position."""
+        return self.fit_info
+
+    def fit_voltage(self, full_output: bool = True) -> None:
+        r"""Find out the proper voltage parameters.
+
+        Idea is the following: for every sample index we know the forward
+        (injected) power :math:`P_f`, :math:`\Gamma`, and
+        :math:`V_\mathrm{coax}` at several pick-ups. We try to find
+        :math:`\psi_0` to verify:
+
+        .. math::
+            |V_\mathrm{coax}(z)| = 2\sqrt{P_f Z} \sqrt{1 + |\Gamma|^2
+            + 2|\Gamma| \cos{(2\beta z + \psi_0)}}
+
+        """
+        x_0 = np.array([np.pi])
+        bounds = ([-2.0 * np.pi], [2.0 * np.pi])
+        xdata = []
+        data = []
+        for e_probe in self._e_field_probes:
+            for p_f, reflection, e_field in zip(
+                self._forward_power.data, self._reflection.data, e_probe.data
+            ):
+                xdata.append([p_f, reflection, e_probe.position])
+                data.append(e_field)
+
+        to_fit = partial(_model, beta=self._beta, z_ohm=self._z_ohm)
+        result = optimize.curve_fit(
+            to_fit,
+            xdata=xdata,  # [power, pos] combinations
+            ydata=data,  # resulting voltages
+            p0=x_0,
+            bounds=bounds,
+            full_output=full_output,
+        )
+        self._psi_0 = result[0][0]
+        if full_output:
+            self._r_squared = r_squared(result[2]["fvec"], np.array(data))
+            # res_squared = result[2]['fvec']**2
+            # expected = np.array(data)
+
+            # ss_err = np.sum(res_squared)
+            # ss_tot = np.sum((expected - expected.mean())**2)
+            # r_squared = 1. - ss_err / ss_tot
+            # self._r_squared = r_squared
+            logging.debug(self.fit_info)
+
+
+def _model(
+    var: NDArray[np.float64],
+    psi_0: float,
+    beta: float,
+    z_ohm: float = 50.0,
+) -> float:
+    r"""Give voltage for given set of parameters, at proper power and position.
+
+    Parameters
+    ----------
+    var :
+        Variables, namely :math:`[P_f, R, z]`.
+
+    Returns
+    -------
+    v :
+        Voltage at position :math:`z` for forward power :math:`P_f`.
+
+    """
+    power, reflection, pos = var[:, 0], var[:, 1], var[:, 2]
+    v_f = _power_to_volt(power, z_ohm=z_ohm)
+    return voltage_vs_position(pos, v_f, reflection, beta, psi_0)
+
+
+def _power_to_volt(
+    power: NDArray[np.float64], z_ohm: float = 50.0
+) -> NDArray[np.float64]:
+    return 2.0 * np.sqrt(power * z_ohm)
+
+
+@overload
+def voltage_vs_position(
+    pos: float,
+    v_f: float,
+    reflection: float,
+    beta: float,
+    psi_0: float,
+) -> float: ...
+
+
+@overload
+def voltage_vs_position(
+    pos: NDArray[np.float64],
+    v_f: float,
+    reflection: float,
+    beta: float,
+    psi_0: float,
+) -> NDArray[np.float64]: ...
+
+
+def voltage_vs_position(
+    pos: float | NDArray[np.float64],
+    v_f: float,
+    reflection: float,
+    beta: float,
+    psi_0: float,
+) -> float | NDArray[np.float64]:
+    r"""Compute voltage in coaxial line at given position.
+
+    The equation is:
+
+    .. math::
+        |V(z)| = |V_f| \sqrt{1 + |\Gamma|^2 + 2|\Gamma|\cos{(2\beta z +
+        \psi_0)}}
+
+    which comes from:
+
+    .. math::
+        V(z) = V_f \mathrm{e}^{-j\beta z} + \Gamma V_f \mathrm{e}^{j\beta z}
+
+    Parameters
+    ----------
+    pos :
+        :math:`z` position in :unit:`m`.
+    v_f :
+        Forward voltage :math:`V_f` in :unit:`V`.
+    gamma :
+        Voltage reflexion coefficient :math:`\Gamma`.
+    beta :
+        Propagation constant :math:`\beta` in :unit:`m^{-1}`.
+    psi_0 :
+        Dephasing constant :math:`\psi_0`.
+
+    Returns
+    -------
+    voltage :
+        :math:`V(z)` at proper position in :unit:`V`.
+
+    """
+    assert not isinstance(v_f, complex), "not implemented"
+    assert not isinstance(reflection, complex), "not implemented"
+
+    voltage = v_f * np.sqrt(
+        1.0
+        + reflection**2
+        + 2.0 * reflection * np.cos(2.0 * beta * pos + psi_0)
+    )
+    return voltage

multipac_testbench/instruments/factory.py

@@ -0,0 +1,171 @@
+"""Define a class to create the proper :class:`.Instrument`."""
+
+import logging
+from collections.abc import Sequence
+from typing import Any, Literal
+
+import multipac_testbench.instruments as ins
+import pandas as pd
+
+STRING_TO_INSTRUMENT_CLASS = {
+    "CurrentProbe": ins.CurrentProbe,
+    "ElectricFieldProbe": ins.FieldProbe,
+    "FieldProbe": ins.FieldProbe,
+    "ForwardPower": ins.ForwardPower,
+    "OpticalFibre": ins.OpticalFibre,
+    "Penning": ins.Penning,
+    "ReflectedPower": ins.ReflectedPower,
+}  #:
+INSTRUMENT_NAME_T = Literal[
+    "CurrentProbe",
+    "ElectricFieldProbe",
+    "FieldProbe",
+    "ForwardPower",
+    "OpticalFibre",
+    "Penning",
+    "ReflectedPower",
+]
+
+
+class InstrumentFactory:
+    """Class to create instruments."""
+
+    def __init__(self, freq_mhz: float | None = None) -> None:
+        """Set user-defined constants to create correspondig instrument."""
+        self.freq_mhz = freq_mhz
+
+    def run(
+        self,
+        name: str,
+        df_data: pd.DataFrame,
+        class_name: INSTRUMENT_NAME_T,
+        column_header: str | list[str] | None = None,
+        **instruments_kw: Any,
+    ) -> ins.Instrument:
+        """Take the proper subclass, instantiate it and return it.
+
+        Parameters
+        ----------
+        name :
+            Name of the instrument. For clarity, it should match the name of a
+            column in ``df_data`` when it is possible.
+        df_data :
+            Content of the multipactor tests results ``CSV`` file.
+        class_name :
+            Name of the instrument class, as given in the ``TOML`` file.
+        column_header :
+            Name of the column(s) from which the data of the instrument will
+            be taken. The default is None, in which case ``column_header`` is
+            set to ``name``. In general it is not necessary to provide it. An
+            exception is when several ``CSV`` columns should be loaded in the
+            instrument.
+        instruments_kw :
+            Other keyword arguments in the ``TOML`` file.
+
+        Returns
+        -------
+        instrument :
+            Instrument properly subclassed.
+
+        """
+        assert class_name in STRING_TO_INSTRUMENT_CLASS, (
+            f"{class_name = } not recognized, check STRING_TO_INSTRUMENT_CLASS"
+            "in instrument/factory.py"
+        )
+        instrument_class = STRING_TO_INSTRUMENT_CLASS[class_name]
+
+        if column_header is None:
+            column_header = name
+
+        raw_data = df_data[column_header]
+
+        if isinstance(raw_data, pd.DataFrame):
+            return instrument_class.from_pd_dataframe(
+                name, raw_data, **instruments_kw
+            )
+        return instrument_class(name, raw_data, **instruments_kw)
+
+    def run_virtual(
+        self,
+        instruments: Sequence[ins.Instrument],
+        is_global: bool = False,
+        **kwargs,
+    ) -> list[ins.VirtualInstrument]:
+        """Add the implemented :class:`.VirtualInstrument`.
+
+        Parameters
+        ----------
+        instruments :
+            The :class:`.Instrument` that were already created. They are used
+            to compute derived quantities, in particular :math:`SWR` and
+            :math:`R`.
+        is_global :
+            Tells if the :class:`.IMeasurementPoint` from which this method is
+            called is global. It allows to forbid creation of one
+            :class:`.Frequency` or one :class:`.SWR` instrument per
+            :class:`.IMeasurementPoint`.
+        kwargs :
+            Other keyword arguments passed to :meth:`._power_related`.
+
+        Returns
+        -------
+        virtuals :
+            The created virtual instruments.
+
+        """
+        virtuals = []
+
+        power_related = []
+        if is_global:
+            power_related = self._power_related(instruments, **kwargs)
+        if len(power_related) > 0:
+            virtuals += power_related
+
+        n_points = len(instruments[0].data_as_pd)
+        constants = []
+        if is_global:
+            constants = self._constant_values_defined_by_user(n_points)
+        if len(constants) > 0:
+            virtuals += constants
+
+        return virtuals
+
+    def _power_related(
+        self, instruments: Sequence[ins.Instrument], **kwargs
+    ) -> Sequence[ins.VirtualInstrument]:
+        """Create :class:`.ReflectionCoefficient` and :class:`.SWR`."""
+        forwards = [x for x in instruments if isinstance(x, ins.ForwardPower)]
+        reflecteds = [
+            x for x in instruments if isinstance(x, ins.ReflectedPower)
+        ]
+        if len(forwards) != 1 or len(reflecteds) != 1:
+            logging.error(
+                "Should have exactly one ForwardPower and one ReflectedPower "
+                "instruments. Skipping SWR and R, this may create problems in "
+                "the future."
+            )
+            return ()
+
+        forward = forwards[0]
+        reflected = reflecteds[0]
+        reflection_coefficient = ins.ReflectionCoefficient.from_powers(
+            forward, reflected, **kwargs
+        )
+        swr = ins.SWR.from_reflection_coefficient(
+            reflection_coefficient, **kwargs
+        )
+        return reflection_coefficient, swr
+
+    def _constant_values_defined_by_user(
+        self,
+        n_points: int,
+    ) -> Sequence[ins.VirtualInstrument]:
+        """Define a fake frequency probe. Maybe a fake SWR, fake R later."""
+        constants = []
+        if self.freq_mhz is not None:
+            constants.append(
+                ins.Frequency.from_user_defined_frequency(
+                    self.freq_mhz, n_points
+                )
+            )
+        return constants

multipac_testbench/instruments/frequency.py

@@ -0,0 +1,51 @@
+"""Define a fake frequency probe."""
+
+from typing import Self
+
+import numpy as np
+import pandas as pd
+from multipac_testbench.instruments.virtual_instrument import VirtualInstrument
+
+
+class Frequency(VirtualInstrument):
+    r"""Store a frequency.
+
+    By default, the frequency is in :unit:`MHz`.
+
+    """
+
+    @classmethod
+    def from_user_defined_frequency(
+        cls,
+        freq_mhz: float,
+        n_points: int,
+        name: str = "Reference frequency",
+        **kwargs,
+    ) -> Self:
+        r"""Instantiate the object with a constant frequency.
+
+        Parameters
+        ----------
+        freq_mhz :
+            Frequency in :unit:`MHz`.
+        n_points :
+            Number of points to fill.
+        name :
+            Name of the series and of the instrument.
+        kwargs :
+            Other keyword arguments passed to ``pd.Series`` and constructor.
+
+        Returns
+        -------
+        frequency :
+            Instantiated object.
+
+        """
+        raw_data = np.full(n_points, freq_mhz)
+        df_data = pd.Series(raw_data, name=name, **kwargs)
+        return cls(name, df_data, position=np.nan, **kwargs)
+
+    @classmethod
+    def ylabel(cls) -> str:
+        """Label used for plots."""
+        return r"RF frequency $f~[\mathrm{MHz}]$"