rtint 0.0.3__py3-none-any.whl

rtint/rtint_generator.py

@@ -0,0 +1,577 @@
+# This file is part of the mechatronic project
+#
+# Copyright (c) Beamline Control Unit, ESRF
+# Distributed under the GNU LGPLv3. See LICENSE for more info.
+
+"""
+REAL-TIME TARGET Signal Generators
+"""
+
+import enum
+import math
+import numpy as np
+from datetime import datetime
+from scipy.signal import chirp
+from tabulate import tabulate
+
+RED = "\033[31m"
+GREEN = "\033[32m"
+RESET = "\033[0m"
+
+
+def _force_fft_symmetry(X: np.ndarray) -> np.ndarray:
+    """Force conjugate symmetry so IFFT yields a real signal."""
+    Y = X.copy()
+    N = len(X)
+    half_floor = N // 2
+    half_ceil = math.ceil(N / 2)
+    Y[half_ceil + 1 :] = np.conj(X[1:half_floor][::-1])
+    return Y
+
+
+def _schroeder_phases(Ns: int, mag: np.ndarray) -> np.ndarray:
+    """Schroeder phases for minimum crest factor (Schroeder 1970)."""
+    rel_mag = mag / mag.sum()
+    phase = np.zeros(Ns)
+    for n in range(1, Ns // 2 + 1):
+        ll = np.arange(n)
+        phase[n] = -2 * np.pi * np.sum((n - ll) * rel_mag[ll])
+    return phase
+
+
+def _generate_multisine(
+    Fs: float,
+    Ns: int,
+    asd: np.ndarray = None,
+    phase_type: str = "schroeder",
+) -> np.ndarray:
+    """Generate a multi-sine excitation signal.
+
+    Args:
+        Fs: Sampling frequency [Hz].
+        Ns: Number of samples in the signal.
+        asd: Amplitude spectral density [unit/sqrt(Hz)], length Ns.
+             If None, a flat unitary ASD is used.
+        phase_type: 'schroeder' (deterministic, low crest factor) or 'normal' (random).
+
+    Returns:
+        Real-valued signal of length Ns, phase-shifted to start at the
+        minimum-gradient zero crossing.
+    """
+    # --- magnitude ---
+    if asd is None:
+        mag = (np.ones(Ns) * 2 * np.sqrt(Fs) / np.sqrt(Ns)) ** 2
+        mag[Ns // 2 :] = 0
+    else:
+        asd = np.asarray(asd, dtype=float)
+        if len(asd) != Ns:
+            raise ValueError(f"asd must have length Ns={Ns}, got {len(asd)}")
+        mag = (asd * 2 * np.sqrt(Fs) / np.sqrt(Ns)) ** 2
+
+    if np.any(mag[Ns // 2 :]):
+        print(
+            f"{RED}WARNING: Non-zero magnitude values present outside of frequency limits.{RESET}"
+        )
+        mag[Ns // 2 :] = 0
+
+    # --- phase ---
+    if phase_type == "schroeder":
+        if mag.sum() == 0:
+            raise ValueError("All magnitude bins are zero — frequency band is empty.")
+        phase = _schroeder_phases(Ns, mag)
+    elif phase_type == "normal":
+        phase = np.random.randn(Ns)
+    else:
+        raise ValueError("phase_type must be 'schroeder' or 'normal'")
+
+    # --- frequency → time domain ---
+    Y = np.sqrt(mag / 2) * np.exp(1j * phase)
+    y = np.fft.ifft(_force_fft_symmetry(Y)).real * (Ns / 2)
+
+    # --- align to minimum-gradient zero crossing ---
+    y_sign = y > 0
+    zero_inds = np.where(y_sign[1:] != y_sign[:-1])[0]
+    zero_grad = np.abs(y[zero_inds] - y[zero_inds + 1])
+    start = zero_inds[np.argmin(zero_grad)]
+    return np.concatenate([y[start:], y[:start]])
+
+
+class RtintHdwGeneratorController:
+    def __init__(self, tg):
+        self._tg = tg
+        self._generators: dict[str, RtintHdwGenerator] | None = None
+        self._load()
+
+    def __info__(self, debug=False):
+        if self._generators is None:
+            return "\n    No Generator in the model"
+
+        if debug:
+            lines = [
+                [
+                    "Name",
+                    "State",
+                    "Duration [s]",
+                    "Repeat",
+                    "Unique Name",
+                    "Max Duration [s]",
+                    "Period [s]",
+                ]
+            ]
+        else:
+            lines = [["Name", "State", "Duration [s]", "Repeat"]]
+        for gen in self._generators.values():
+            repeat_str = f"True ({gen.period:.3f} s)" if gen.repeat else "False"
+            row = [
+                gen._name,
+                gen.state.name,
+                f"{gen.duration:.3f}",
+                repeat_str,
+            ]
+            if debug:
+                row += [
+                    gen._unique_name,
+                    f"{gen.max_duration:.3f}",
+                    f"{gen.period:.3f}",
+                ]
+            lines.append(row)
+        return "\n" + tabulate(lines, headers="firstrow", tablefmt="grid", stralign="left")
+
+    def _load(self):
+        generators = self._tg._get_all_objects_from_key("bliss_signalgen")
+        if len(generators) > 0:
+            self._generators = {}
+            for generator in generators:
+                tg_generator = RtintHdwGenerator(self._tg, generator)
+                if hasattr(self, tg_generator._name):
+                    print(
+                        f"{RED}WARNING: Generator '{tg_generator._name}' already exists{RESET}"
+                    )
+                    return
+                else:
+                    setattr(self, tg_generator._name, tg_generator)
+                    self._generators[tg_generator._name] = tg_generator
+
+
+class GeneratorState(enum.IntEnum):
+    Idle = 0
+    Moving = 1
+    Stopped = 2
+    Fault = 3
+
+
+class RtintHdwGenerator:
+    def __init__(self, tg, unique_name):
+        self._tg = tg
+        self._unique_name = unique_name
+        self._max_samples: int = self._tg._program.tree.params[
+            f"{self._tg._program.name}/{self._unique_name}/samples/Value"
+        ].shape[0]
+
+    def __info__(self):
+        Ts = self._tg._Ts
+        n_active = round(self.duration / Ts)
+        lines = [
+            ["Name", self._name],
+            ["Unique name", self._unique_name],
+            ["", ""],
+            ["State", self.state.name],
+            ["", ""],
+            ["Duration", f"{self.duration:.3f} s  ({n_active} samples)"],
+            [
+                "Max duration",
+                f"{self.max_duration:.3f} s  ({self._max_samples} samples)",
+            ],
+            [
+                "Repeat",
+                (
+                    f"True ({self.period:.3f} s, {self._period_samples} samples)"
+                    if self.repeat
+                    else "False"
+                ),
+            ],
+        ]
+        return tabulate(lines, tablefmt="plain", stralign="right")
+
+    def _tree(self):
+        print("Parameters:")
+        self._tg.parameter._tree.subtree(
+            self._tg._program.name + "/" + self._unique_name
+        ).show()
+        print("Signals:")
+        self._tg.signal._tree.subtree(
+            self._tg._program.name + "/" + self._unique_name
+        ).show()
+
+    @property
+    def _name(self):
+        return self._tg.parameter.get(
+            f"{self._unique_name}/bliss_signalgen/String"
+        )
+
+    # --- read-only ---
+
+    @property
+    def max_duration(self) -> float:
+        """Maximum signal duration [s], fixed at model compile time."""
+        return self._max_samples * self._tg._Ts
+
+    @property
+    def state(self) -> GeneratorState:
+        return GeneratorState(
+            int(self._tg.signal.get(f"{self._unique_name}/state"))
+        )
+
+    @property
+    def output(self) -> float:
+        return self._tg.signal.get(f"{self._unique_name}/gen_signal")
+
+    # --- samples ---
+
+    @property
+    def samples(self) -> np.ndarray:
+        return self._tg.parameter.get(f"{self._unique_name}/samples/Value")
+
+    @samples.setter
+    def samples(self, value):
+        signal = np.asarray(value, dtype=float).flatten()
+        if len(signal) > self._max_samples:
+            raise ValueError(
+                f"Signal length ({len(signal)} samples = {len(signal) * self._tg._Ts:.3f} s) "
+                f"exceeds maximum ({self._max_samples} samples = {self.max_duration:.3f} s)"
+            )
+        # Add zeros at the end of the vector if necessary
+        if len(signal) < self._max_samples:
+            signal = np.pad(signal, (0, self._max_samples - len(signal)))
+        self._tg.parameter.set(f"{self._unique_name}/samples/Value", signal)
+
+    # --- parameters ---
+
+    @property
+    def duration(self) -> float:
+        """Total playback duration [s]. Output is zero after this time."""
+        return self._tg.parameter.get(f"{self._unique_name}/duration/Value")
+
+    @duration.setter
+    def duration(self, value: float):
+        self._tg.parameter.set(f"{self._unique_name}/duration/Value", value)
+
+    @property
+    def repeat(self) -> bool:
+        """If True, the signal pattern cycles over period [s]."""
+        return bool(self._tg.parameter.get(f"{self._unique_name}/repeat/Value"))
+
+    @repeat.setter
+    def repeat(self, value: bool):
+        self._tg.parameter.set(f"{self._unique_name}/repeat/Value", int(value))
+
+    @property
+    def _period_samples(self) -> int:
+        return int(self._tg.parameter.get(f"{self._unique_name}/period/Value"))
+
+    @property
+    def period(self) -> float:
+        """Signal pattern period [s]. Stored as samples on the real-time target."""
+        return self._period_samples * self._tg._Ts
+
+    @period.setter
+    def period(self, value: float):
+        """Set signal pattern period [s]. Converted to samples internally."""
+        self._tg.parameter.set(
+            f"{self._unique_name}/period/Value", round(value / self._tg._Ts)
+        )
+
+    # --- start / stop ---
+
+    def start(self):
+        start_trigger = int(
+            self._tg.parameter.get(f"{self._unique_name}/start_trigger/Bias")
+        )
+        self._tg.parameter.set(
+            f"{self._unique_name}/start_trigger/Bias", start_trigger + 1
+        )
+
+    def stop(self):
+        stop_trigger = int(
+            self._tg.parameter.get(f"{self._unique_name}/stop_trigger/Bias")
+        )
+        self._tg.parameter.set(
+            f"{self._unique_name}/stop_trigger/Bias", stop_trigger + 1
+        )
+
+    # --- internal ---
+
+    @staticmethod
+    def _prepend_zeros(signal: np.ndarray, start_time: float, Ts: float) -> np.ndarray:
+        if start_time > 0:
+            return np.concatenate([np.zeros(int(start_time / Ts)), signal])
+        return signal
+
+    def _upload(self, signal: np.ndarray, duration: float = None):
+        """Upload signal pattern. Sets samples, period (= pattern length), and duration."""
+        self.samples = signal
+        pattern_duration = len(signal) * self._tg._Ts
+        self.period = pattern_duration
+        self.duration = duration if duration is not None else pattern_duration
+
+    # --- convenience methods ---
+    # Periodic signals (sinus, triangle, noise): upload one natural period, repeat=True by default.
+    #   Pass duration= to set total playback time in the same call.
+    #   Example: gen.sinus(1e-6, 1.0, duration=100); gen.start()
+    # One-shot signals (step, ramp, sweep, impulse): repeat=False by default.
+
+    def sinus(
+        self,
+        amplitude: float,
+        frequency: float,
+        offset: float = 0,
+        duration: float = None,
+        repeat: bool = True,
+    ):
+        """Upload one cycle of a sinus at frequency [Hz]. Repeats by default."""
+        Ts = self._tg._Ts
+        t = np.arange(0, 1.0 / frequency, Ts)
+        self._upload(offset + amplitude * np.sin(2 * np.pi * frequency * t), duration)
+        self.repeat = repeat
+
+    def triangle(
+        self,
+        amplitude: float,
+        frequency: float,
+        offset: float = 0,
+        duration: float = None,
+        repeat: bool = True,
+    ):
+        """Upload one cycle of a triangle wave at frequency [Hz]. Repeats by default."""
+        Ts = self._tg._Ts
+        period = 1.0 / frequency
+        t = np.arange(0, period, Ts)
+        slope = 4 * amplitude * frequency
+        t_mod = np.mod(t, period)
+        signal = np.where(
+            t_mod <= period / 4,
+            slope * t_mod,
+            np.where(
+                t_mod <= 3 * period / 4,
+                amplitude - slope * (t_mod - period / 4),
+                -amplitude + slope * (t_mod - 3 * period / 4),
+            ),
+        )
+        self._upload(offset + signal, duration)
+        self.repeat = repeat
+
+    def uniform_white_noise(
+        self,
+        amplitude: float,
+        pattern_duration: float,
+        offset: float = 0,
+        duration: float = None,
+        repeat: bool = True,
+    ):
+        """Upload a uniform noise pattern of pattern_duration [s]. Repeats by default."""
+        Ts = self._tg._Ts
+        n = int(pattern_duration / Ts)
+        self._upload(
+            offset + 2 * amplitude * (np.random.uniform(size=n) - 0.5), duration
+        )
+        self.repeat = repeat
+
+    def normal_white_noise(
+        self,
+        amplitude: float,
+        pattern_duration: float,
+        offset: float = 0,
+        duration: float = None,
+        repeat: bool = True,
+    ):
+        """Upload a normal noise pattern of pattern_duration [s]. Repeats by default."""
+        Ts = self._tg._Ts
+        n = int(pattern_duration / Ts)
+        self._upload(offset + 2 * amplitude * np.random.randn(n), duration)
+        self.repeat = repeat
+
+    def multisine(
+        self,
+        amplitude: float,
+        pattern_duration: float,
+        f_min: float = None,
+        f_max: float = None,
+        offset: float = 0,
+        duration: float = None,
+        asd: np.ndarray = None,
+        phase_type: str = "schroeder",
+        repeat: bool = True,
+    ):
+        """Upload a multi-sine excitation signal.
+
+        Args:
+            amplitude: Peak amplitude of the generated signal [unit].
+                       The signal is scaled so max(|signal|) == amplitude.
+            pattern_duration: Length of one signal period [s].
+            f_min: Lower frequency bound [Hz]. Bins below are zeroed.
+            f_max: Upper frequency bound [Hz]. Must not exceed Fs/2.
+            offset: DC offset added to the signal.
+            duration: Total playback duration [s]. Defaults to pattern_duration.
+            asd: Optional shaped ASD array (relative weights), length Ns=int(pattern_duration/Ts).
+                 When provided, shapes the frequency content; amplitude still sets the peak.
+            phase_type: 'schroeder' or 'normal'.
+            repeat: If True, the pattern cycles. Default True.
+        """
+        Ts = self._tg._Ts
+        Fs = 1.0 / Ts
+        Ns = int(pattern_duration / Ts)
+
+        if f_max is not None and f_max > Fs / 2:
+            raise ValueError(
+                f"f_max ({f_max} Hz) exceeds Nyquist frequency ({Fs / 2} Hz)"
+            )
+
+        if asd is None:
+            asd = np.ones(Ns, dtype=float)
+            if f_min is not None:
+                asd[: round(Ns * f_min / Fs)] = 0
+            if f_max is not None:
+                asd[round(Ns * f_max / Fs) + 1 :] = 0
+
+        signal = _generate_multisine(Fs, Ns, asd=asd, phase_type=phase_type)
+        signal *= amplitude / np.max(np.abs(signal))
+        self._upload(offset + signal, duration)
+        self.repeat = repeat
+
+    def step(
+        self,
+        amplitude: float,
+        duration: float,
+        offset: float = 0,
+        start_time: float = 0,
+        repeat: bool = False,
+    ):
+        Ts = self._tg._Ts
+        t = np.arange(0, duration, Ts)
+        self._upload(
+            self._prepend_zeros(offset + np.full_like(t, amplitude), start_time, Ts),
+            start_time + duration,
+        )
+        self.repeat = repeat
+
+    def impulse(
+        self,
+        amplitude: float,
+        start_time: float = 0,
+        offset: float = 0,
+        repeat: bool = False,
+    ):
+        Ts = self._tg._Ts
+        start_idx = int(start_time / Ts)
+        signal = np.zeros(start_idx + 1)
+        signal[start_idx] = amplitude
+        self._upload(offset + signal, start_time + Ts)
+        self.repeat = repeat
+
+    def ramp(
+        self,
+        amplitude: float,
+        duration: float,
+        offset: float = 0,
+        start_time: float = 0,
+        repeat: bool = False,
+    ):
+        Ts = self._tg._Ts
+        t = np.arange(0, duration, Ts)
+        self._upload(
+            self._prepend_zeros(offset + amplitude * (t / duration), start_time, Ts),
+            start_time + duration,
+        )
+        self.repeat = repeat
+
+    def linear_sweep(
+        self,
+        amplitude: float,
+        duration: float,
+        start_freq: float,
+        end_freq: float,
+        offset: float = 0,
+        start_time: float = 0,
+        repeat: bool = False,
+    ):
+        Ts = self._tg._Ts
+        t = np.arange(0, duration, Ts)
+        signal = amplitude * chirp(
+            t, f0=start_freq, f1=end_freq, t1=duration, method="linear"
+        )
+        self._upload(
+            self._prepend_zeros(offset + signal, start_time, Ts),
+            start_time + duration,
+        )
+        self.repeat = repeat
+
+    def log_sweep(
+        self,
+        amplitude: float,
+        duration: float,
+        start_freq: float,
+        end_freq: float,
+        offset: float = 0,
+        start_time: float = 0,
+        repeat: bool = False,
+    ):
+        Ts = self._tg._Ts
+        t = np.arange(0, duration, Ts)
+        signal = amplitude * chirp(
+            t, f0=start_freq, f1=end_freq, t1=duration, method="logarithmic"
+        )
+        self._upload(
+            self._prepend_zeros(offset + signal, start_time, Ts),
+            start_time + duration,
+        )
+        self.repeat = repeat
+
+    # --- plot ---
+
+    def plot(self, directory=None, file_name=None):
+
+        import matplotlib.pyplot as plt
+
+        Ts = self._tg._Ts
+        n_active = round(self.duration / Ts)
+
+        if self.repeat:
+            n_period = self._period_samples
+            period_signal = self.samples[:n_period]
+            n_repeats = int(np.ceil(n_active / n_period))
+            signal_plot = np.tile(period_signal, n_repeats)[:n_active]
+            x = np.arange(len(signal_plot)) * Ts
+            fig, ax = plt.subplots(figsize=(10, 3))
+            ax.plot(x, signal_plot)
+            for k in range(1, n_repeats):
+                ax.axvline(
+                    k * n_period * Ts,
+                    color="r",
+                    linestyle="--",
+                    alpha=0.6,
+                    label="Period boundary" if k == 1 else "",
+                )
+            if n_repeats > 1:
+                ax.legend()
+            ax.set_title(
+                f"Signal (repeat, period={self.period:.3f} s, duration={self.duration:.3f} s)"
+            )
+        else:
+            signal_plot = self.samples[:n_active]
+            x = np.arange(len(signal_plot)) * Ts
+            fig, ax = plt.subplots(figsize=(10, 3))
+            ax.plot(x, signal_plot)
+            ax.set_title(f"Signal (duration={self.duration:.3f} s)")
+
+        ax.set_xlabel("Time [s]")
+        ax.set_ylabel("Amplitude")
+        ax.grid(True)
+        plt.tight_layout()
+
+        if directory is not None and file_name is not None:
+            now = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+            fig.savefig(f"{directory}/{now}_{file_name}.pdf")
+            fig.savefig(f"{directory}/{now}_{file_name}.png")
+            plt.close(fig)
+        else:
+            plt.show()