teraflash-ctrl 1.4.0__py3-none-any.whl

__init__.py

@@ -0,0 +1,8 @@
+"""
+Copyright (c) 2026 University of Bern, Space Research & Planetary Sciences, Linus Leo Stöckli.
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/
+"""

interface.py

@@ -0,0 +1,356 @@
+"""
+Copyright (c) 2026 University of Bern, Space Research & Planetary Sciences, Linus Leo Stöckli.
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/
+"""
+
+import time
+from queue import Queue, Empty
+import threading
+
+import numpy as np
+import platform
+import socket
+import subprocess
+import logging
+
+from math_utils import get_fft
+
+
+class DataContainer:
+
+    def __init__(self, n=1000):
+        """
+            Data container that stores the data sent by the instrument
+        Args:
+            n: length of dataset (depends on the selected range)
+        """
+        self.time = np.zeros(n)
+        self.freq = np.zeros(n)
+
+        self.signal_1 = np.zeros(n)
+        self.fft_1_amp = np.zeros(n)
+        self.fft_1_phase = np.zeros(n)
+
+        self.signal_2 = np.zeros(n)
+        self.fft_2_amp = np.zeros(n)
+        self.fft_2_phase = np.zeros(n)
+
+
+# global variables for thread communication
+data = DataContainer()
+n_avg = 0
+status = ""
+
+
+class TopticaSocket:
+    def __init__(self,
+                 ip: str,
+                 running: threading.Event,
+                 connected: threading.Event,
+                 cmd_ack: threading.Event,
+                 buffer_emptied: threading.Event,
+                 range_changed: threading.Event,
+                 acq_running: threading.Event,
+                 avg_data: threading.Event):
+        """
+            TCP Socket struct, used for the communication between the server (Computer) and the client (instrument)
+            with two TCP connections (one for configuration and one for data transmission)
+        Args:
+            ip: ip address
+            running: threading event that signals if the application is running
+            connected: threading event that signals if a client is connected
+            cmd_ack: threading event that signals when a command is acknowledged
+            range_changed: threading event that signals when the range has been changed in the configuration
+        """
+        self.send_header = b'\xcd\xef\x124x\x9a\xfe\xdc\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00'
+        self.r_stat_header = b'\xcd\xef\x124x\x9a\xfe\xdc\x00\x00\x00\x03\x00\x00\x00\x00\x00\x00\x02'
+        self.r_dat_header = b'\xcd\xef\x124x\x9a\xfe\xdc\x00\x00\x00\x01\x00\t\x1a\xe6\x03\xe8\x00\x00\x04L\x00\x00\x0c\xcc\xcc\xcc\x00\x00\x16\x0b\x00\x00]\xd8\x00\x00\x00\x01\x00\x00\x00\x01\x00\x00\x00\x01\x00\x00\x00\x00'
+        self.r_dat_header = b'\xcd\xef\x124x\x9a\xfe'
+        self.full_data_header_len = 52
+        self.read_header_len = 19
+        self.data_header_len = 7
+
+        self.avg_countdown = 0
+
+        self.config_server_address = (ip, 6341)
+        self.data_server_address = (ip, 6342)
+
+        self.t_begin = 1000.00
+        self.range = 50
+        self.antenna_range = 1000.0
+
+        self.running = running
+        self.connected = connected
+        self.cmd_ack = cmd_ack
+        self.range_changed = range_changed
+        self.buffer_emptied = buffer_emptied
+        self.acq_running = acq_running
+        self.avg_data = avg_data
+
+        if not self.ping(ip):
+            raise ConnectionError
+
+    @staticmethod
+    def ping(host: str):
+        """
+            determines whether a device is connected or not
+        Args:
+            host: IP address as a string
+
+        Returns: True for connected, False for not connected
+
+        """
+        res = False
+        ping_param = "-n" if platform.system().lower() == "windows" else "-c"
+        command = ['ping', ping_param, '1', host]
+        result = subprocess.call(command)
+        if result == 0:
+            res = True
+        return res
+
+    def wait_for_answer(self, client: socket, length: int = 1024):
+        """
+            waits for the device to acknowledge the previously sent command
+        Args:
+            client: socket object
+            length: length of the buffer
+
+        Returns: True for valid response, False for error
+
+        """
+        while self.running.is_set():
+            _data = client.recv(length)[self.read_header_len:]
+            if _data:
+                _data_decoded = _data.decode("utf-8", "ignore")
+                if "OK" in _data_decoded:
+                    logging.debug(f"[TCP CONF] received: {_data_decoded}")
+                    return True
+                elif "MON" in _data_decoded:
+                    return True
+                logging.debug(f"[TCP CONF] received: {_data_decoded}")
+            else:
+                logging.error(f"[TCP CONF] No valid reply from device: {_data.decode('utf-8', 'ignore')}")
+                return False
+
+    def run_conf_tcp(self, cmd_queue: Queue):
+        """
+            Config TCP thread on port 6341. This handles all the configurations for the device.
+        Args:
+            cmd_queue: Queue from main thread with all the interactive
+
+        Returns:
+
+        """
+        global status
+        global data
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            # Set the SO_REUSEADDR option to allow reuse of the port
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+
+            # bind server to the address (only works when the address exists)
+            s.bind(self.config_server_address)
+            logging.info(f"[TCP CONF] Starting server at address {self.config_server_address}")
+            # wait for connections
+            s.listen()
+            # accept connection from device
+            client, addr = s.accept()
+            logging.info(f"[TCP CONF] Connected by client with address {addr}")
+            # now we are connected
+            self.connected.set()
+
+            while self.running.is_set():
+                # check the queue for commands
+                try:
+                    cmd = cmd_queue.get(block=False)
+                    logging.debug(f"[TCP CONF] sending: {cmd}")
+                    (b, c) = cmd
+                    message = self.send_header + b + c.encode()
+                    # send command
+                    client.send(message)
+                    if b == b'\x14':
+                        # if we request the status, save the response
+                        status = client.recv(2048)[self.read_header_len:].decode("utf-8", "ignore")
+                        self.cmd_ack.set()
+                    elif "RANGE" in c:
+                        # if we change the range, also change it for the data thread
+                        parts = c.split(" ")
+                        self.range = float(parts[-1])
+                        data.time = np.linspace(self.t_begin, self.t_begin + self.range, 20 * int(self.range) + 1)
+                        # wait for acknowledge
+                        if not self.wait_for_answer(client):
+                            return
+                        self.cmd_ack.set()
+                    elif "BEGIN" in c:
+                        # if we change the range, also change it for the data thread
+                        parts = c.split(" ")
+                        self.t_begin = float(parts[-1])
+                        data.time = np.linspace(self.t_begin, self.t_begin + self.range, 20 * int(self.range) + 1)
+                        # wait for acknowledge
+                        if not self.wait_for_answer(client):
+                            return
+                        self.cmd_ack.set()
+                    else:
+                        # wait for acknowledge
+                        if not self.wait_for_answer(client):
+                            return
+                        self.cmd_ack.set()
+                except Empty:
+                    # just to a simple heartbeat
+                    (b, c) = (b'\x12', "SYSTEM : MONITOR 1")
+                    message = self.send_header + b + c.encode()
+                    client.send(message)
+                    # wait for acknowledge
+                    if not self.wait_for_answer(client):
+                        return
+                time.sleep(0.25)
+
+    def run_tcp_dat(self, cmd_queue: Queue, config_queue: Queue):
+        """
+            Data TCP thread on port 6342. This handles receives all the streamed data from the device and decodes it.
+        """
+        global data
+        global n_avg
+        types = np.dtype([
+            ("signal_1", np.int32),
+            ("signal_2", np.int32),
+        ])
+        antenna_range = 1000.0
+
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            # Set the SO_REUSEADDR option to allow reuse of the port
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+
+            # bind server to the address (only works when the address exists)
+            s.bind(self.data_server_address)
+            logging.info(f"[TCP DAT] Starting server at address {self.data_server_address}")
+            # wait for connections
+            s.listen()
+            # accept connection from device
+            client, addr = s.accept()
+            client.settimeout(2)
+
+            logging.info(f"[TCP DAT] Connected by client with address {addr}")
+            # now we are connected
+            while self.running.is_set():
+                if self.range_changed.is_set():
+                    # range has changed and needs to be adjusted
+                    # need to empty the read buffer
+                    while self.running.is_set():
+                        logging.debug(f"emptying buffer...")
+                        try:
+                            client.recv(32100)
+                        except socket.timeout:
+                            break
+                    self.buffer_emptied.set()
+                    self.range_changed.clear()
+
+                # data always comes in the shape of 4 datasets each as 16bit ints with length of
+                # (20 * self.range + 1)
+                # the header is 52 8 bit ints and since we read 8 bit ints we need to multiply the data by 2
+                if self.range_changed.is_set():
+                    continue
+                if not self.acq_running.is_set():
+                    # no data received
+                    time.sleep(1.0)
+                    continue
+                try:
+                    raw_data = client.recv(2 * 4 * (20 * int(self.range) + 1) + self.full_data_header_len)
+                except socket.timeout:
+                    continue
+                if not raw_data:
+                    # no data received
+                    time.sleep(1.0)
+                    continue
+
+                if raw_data[:self.data_header_len] != self.r_dat_header:
+                    continue
+
+                if len(raw_data) != 2 * 4 * (20 * int(self.range) + 1) + self.full_data_header_len:
+                    skip_this = False
+                    while self.running.is_set():
+                        try:
+                            to_append = client.recv(
+                                2 * 4 * (20 * int(self.range) + 1) + self.full_data_header_len - len(raw_data))
+                            raw_data += to_append
+                            if len(raw_data) == 2 * 4 * (20 * int(self.range) + 1) + self.full_data_header_len:
+                                break
+                            if len(raw_data) == 2 * 4 * (20 * int(self.range) + 1) + self.full_data_header_len:
+                                skip_this = True
+                                break
+                        except socket.timeout:
+                            skip_this = True
+                            break
+                    if skip_this:
+                        continue
+
+                # TODO: the following code is not properly implemented yet, we need
+                # to check how we handle it, if the data comes not in the proper packet length
+
+                _data = raw_data[self.full_data_header_len:]
+
+                # check if header is at the beginning of the received payload
+                # if raw_data[:self.data_header_len] == self.r_dat_header:
+                #     # remove the header
+                #     _data = raw_data[self.data_header_len:]
+                # else:
+                #     _data = raw_data[self.data_header_len:]
+                #     # print("header not in the beginning")
+                #     while self.running.is_set():
+                #         logging.info("data does not have correct length...")
+                #
+                #         # check if the data is of the correct length
+                #         if len(_data) != 2 * 4 * (20 * self.range + 1):
+                #             _data = _data + client.recv(2 * 4 * (20 * int(self.range) + 1) - len(_data))
+                #         else:
+                #             break
+                try:
+                    # decode received payload to 32 bit ints
+                    types = types.newbyteorder('>')
+                    arr = np.frombuffer(_data, dtype=types)
+
+                    if not config_queue.empty():
+                        antenna_range = config_queue.get()
+
+                    scale_factor = 20.0 * 1000.0 / antenna_range;
+
+                    # TODO: make subtracting offset optional.
+                    signal_1 = arr['signal_1'] / scale_factor / 2 ** 16 - arr['signal_1'][0] / scale_factor / 2 ** 16
+                    signal_2 = arr['signal_2'] / scale_factor / 2 ** 16 - arr['signal_2'][0] / scale_factor / 2 ** 16
+
+                    if self.avg_data.is_set():
+                        if data.signal_1.shape == signal_1.shape:
+                            data.signal_1 += signal_1
+                        else:
+                            data.signal_1 = signal_1
+                        if data.signal_2.shape == signal_2.shape:
+                            data.signal_2 += signal_2
+                        n_avg += 1
+                    else:
+                        data.signal_1 = signal_1
+                        data.signal_2 = signal_2
+                        n_avg = 0
+
+                    # do fft of signal 1
+                    pulse = data.signal_1
+                    f, a, arg = get_fft(data.time, pulse)
+                    data.freq = f
+                    data.fft_1_amp = a / np.max(a)
+                    data.fft_1_phase = arg
+
+                    # do fft of signal 2
+                    pulse = data.signal_2
+                    f, a, arg = get_fft(data.time, pulse)
+                    data.fft_2_amp = a / np.max(a)
+                    data.fft_2_phase = arg
+
+                    # update avg countdown
+                    if self.avg_countdown > 0:
+                        self.avg_countdown -= 1
+
+                except Exception as e:
+                    logging.error(e)
+                    logging.error(f"{len(data.signal_1)=}")

io.py

@@ -0,0 +1,139 @@
+"""
+Copyright (c) 2026 University of Bern, Space Research & Planetary Sciences, Linus Leo Stöckli.
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/
+"""
+
+from pathlib import Path
+from typing import Optional
+
+import h5py
+import numpy as np
+from datetime import datetime
+
+
+def save_thz(filename: Path, time: np.ndarray, pulse: np.ndarray, reference: Optional[np.ndarray] = None,
+             coordinates: np.ndarray = np.array([0.0, 0.0]), thickness: float = 1.0, temperature: float = 298.15,
+             mode: str = 'THz-TDS/Transmission', meta: dict = dict(),
+             user: str = "0000-0000-1111-2222 / J Doe / J.Doe @ thz.ac.uk / University  of Terawick, UK"):
+    # Create and save to HDF5 file
+    # Get current date and time
+    now = datetime.now()
+    # Format date as YYYY-MM-DD
+    date = now.strftime("%Y-%m-%d")
+    # Format time as HH:MM:SS
+    timestamp = now.strftime("%H:%M:%S")
+    with h5py.File(filename, 'w') as f:
+        # Save main datasets
+        # Better to only save the time array once, than for every pixel, right?
+        f.create_dataset('ds1', data=np.array([time, pulse]))
+        if reference:
+            f.create_dataset('ds2', data=np.array([time, reference]))
+            f.attrs['dsDescription'] = ["ds1:Sample", "ds2:Ref"]
+        else:
+            f.attrs['dsDescription'] = ["ds1:Sample"]
+
+        # Save metadata
+
+        f.attrs['date'] = date
+        f.attrs['description'] = 'sample material name or description'
+        f.attrs['instrument'] = 'TeraFlash Pro / Toptica'
+        f.attrs['md1'] = thickness  # thickness in mm
+        f.attrs['md2'] = temperature  # temperature
+
+        # how do we save coordinates?
+        f.attrs['coordinates'] = coordinates
+
+        meta_data_counter = 3
+        for k in meta.keys():
+            f.attrs[f"md{meta_data_counter}"] = meta[k]
+            meta_data_counter += 1
+
+        f.attrs['mdDescription'] = ["Thickness (mm)", "Temperature (K)"] + list(meta.keys())
+        f.attrs['mode'] = mode
+        f.attrs["thzVer"] = "1.00"
+        f.attrs["time"] = timestamp
+        f.attrs["user"] = user
+
+    # Open the HDF5 file in read mode
+    with h5py.File('test.thz', 'r') as f:
+        # Load the datasets
+        print(f.keys())
+        print(f.attrs.keys())
+
+
+def save_thz_image(filename: Path, time: np.ndarray, image: np.ndarray,
+                   x_min: float, x_max: float, dx: float, y_min: float, y_max: float, dy: float,
+                   mode: str = 'THz-TDS/Transmission', meta: dict = dict(),
+                   user: str = "0000-0000-1111-2222 / J Doe / J.Doe @ thz.ac.uk / University  of Terawick, UK"):
+    # Create and save to HDF5 file
+    # Get current date and time
+    now = datetime.now()
+    # Format date as YYYY-MM-DD
+    date = now.strftime("%Y-%m-%d")
+    # Format time as HH:MM:SS
+    timestamp = now.strftime("%H:%M:%S")
+    with h5py.File(filename, 'w') as f:
+        # Save main datasets
+        # Better to only save the time array once, than for every pixel, right?
+        f.create_dataset('ds1', data=time)
+        f.create_dataset('ds2', data=image)
+        f.attrs['dsDescription'] = ["ds1:Time", "ds2:Image"]
+
+        # Save metadata
+        f.attrs['date'] = date
+        f.attrs['description'] = 'sample material name or description'
+        f.attrs['instrument'] = 'TeraFlash Pro / Toptica'
+        f.attrs['md1'] = 1  # thickness in mm
+        f.attrs['md2'] = 298.15  # temperature
+        # might seem better to just save x_min, x_max and dx (vice versa for y) instead of a full array?
+        f.attrs['md3'] = x_min
+        f.attrs['md4'] = x_max
+        f.attrs['md5'] = dx
+        f.attrs['md6'] = y_min
+        f.attrs['md7'] = y_max
+        f.attrs['md8'] = dy
+        # how do we save coordinates?
+        meta_data_counter = 9
+        for k in meta.keys():
+            f.attrs[f"md{meta_data_counter}"] = meta[k]
+            meta_data_counter += 1
+
+        f.attrs['mdDescription'] = ["Thickness (mm)", "Temperature (K)", "x_min (mm)", "x_max (mm)", "dx (mm)",
+                                    "y_min (mm)", "y_max (mm)", "dy (mm)"] + list(meta.keys())
+        f.attrs['mode'] = mode
+        f.attrs["thzVer"] = "1.00"
+        f.attrs["time"] = timestamp
+        f.attrs["user"] = user
+
+    # Open the HDF5 file in read mode
+    with h5py.File('test.thz', 'r') as f:
+        # Load the datasets
+        print(f.keys())
+        print(f.attrs.keys())
+
+
+if __name__ == '__main__':
+
+    time = np.linspace(0, 1, 100)  # your time array
+    data = np.random.rand(100)  # example 3D data array
+
+    print(time.shape, data.shape)
+
+    meta = {
+        "test value": 0.0,
+        "content": "nothing",
+    }
+
+    save_thz(Path("test.thz"), time, data)
+
+    with h5py.File("test.thz", 'r') as f:
+        # Load the datasets
+        print(f.keys())
+        print(f.attrs.keys())
+        data = f['ds1'][()]
+        for key in f.attrs.keys():
+            print(key, f.attrs[key])

math_utils.py

@@ -0,0 +1,115 @@
+"""
+Copyright (c) 2026 University of Bern, Space Research & Planetary Sciences, Linus Leo Stöckli.
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/
+"""
+
+import numpy as np
+from scipy.fft import rfft, rfftfreq, irfft
+
+
+def blackman_func(n, M):
+    return 0.42 - 0.5 * np.cos(2 * np.pi * n / M) + 0.08 * np.cos(4 * np.pi * n / M)
+
+
+def toptica_window(t, start=1, end=7):
+    window = np.ones(t.shape)
+    a = t[t <= (t[0] + start)]
+    b = t[t >= (t[-1] - end)]
+    a = blackman_func(a - a[0], 2 * (a[-1] - a[0]))
+    b = blackman_func(b + b[-1] - b[0] - b[0], 2 * (b[-1] - b[0]))
+    window[t <= (t[0] + start)] = a
+    window[t >= (t[-1] - end)] = b
+    return window
+
+
+def zero_padding(time, pulse, df_padded=0.01):
+    # Calculate the total time span of the original data
+    T = time[-1] - time[0]
+
+    # Find the length of the original signal
+    N_original = len(pulse)
+
+    # Calculate the original time step (assuming uniform sampling in the time array)
+    dt = time[1] - time[0]
+
+    N_padded = (1 / df_padded - T) / dt
+
+    N_padded = int(N_padded) + N_original
+
+    # If padding is needed, apply zero-padding and extend the time array
+    if N_padded > N_original:
+        # Pad the pulse array with zeros to match the required length
+        padded_pulse = np.pad(pulse, (0, N_padded - N_original), mode='constant')
+        # Create an extended time array with the same timestep (dt)
+        extended_time = np.arange(time[0], time[0] + N_padded * dt, dt)
+    else:
+        # If no padding is needed, return the original arrays
+        padded_pulse = pulse
+        extended_time = time
+    return extended_time, padded_pulse
+
+
+def unwrap_phase(phase):
+    threshold = np.pi
+    N = len(phase)
+
+    for i in range(N - 1):
+        if phase[i + 1] - phase[i] > threshold:
+            for j in range(i + 1, N):
+                phase[j] -= 2 * np.pi
+        elif phase[i + 1] - phase[i] < -threshold:
+            for j in range(i + 1, N):
+                phase[j] += 2 * np.pi
+    return phase
+
+
+def get_fft(t, p, df=0.01, window_start=1, window_end=2, return_td=False):
+    t = np.array(t)
+    p = np.array(p) * toptica_window(t, window_start, window_end)
+    t, p = zero_padding(t, p, df_padded=df)
+
+    sample_rate = 1 / (t[1] - t[0]) * 1e12
+    n = len(p)
+    fft = rfft(p)
+    a = np.abs(fft)
+    angle = np.angle(fft)
+    arg = np.unwrap(angle)
+    f = rfftfreq(n, 1 / sample_rate) / 1e12
+    # a = a[f >= 0.1]
+    # arg = arg[f >= 0.1]
+    # f = f[f >= 0.1]
+    if return_td:
+        return t, p, f, a, np.abs(arg)
+    else:
+        return f, a, np.abs(arg)
+
+
+def get_ifft(frequencies, amplitudes, phases, t0=0):
+    fft = amplitudes * np.exp(1j * phases)
+    signal = irfft(fft)
+    delta_f = frequencies[1] - frequencies[0]
+    sample_rate = 2 * (len(frequencies) - 1) * delta_f
+    N = len(signal)  # Number of samples
+    T = 1.0 / sample_rate  # Sample spacing (inverse of the sampling rate)
+    time = np.linspace(0.0, N * T, N, endpoint=False)
+    return t0 - time + time[-1], signal
+
+
+if __name__ == '__main__':
+    import matplotlib.pyplot as plt
+
+    t = np.arange(1935, 1965.05, 0.05, )
+    p = np.ones(t.shape)
+    print(f"{t=}")
+    print(f"{p=}")
+
+    plt.plot(t, p)
+    t_padded, p_padded = zero_padding(t, p)
+    p_windowed = p * toptica_window(t)
+    t_windowed, p_windowed = zero_padding(t, p_windowed)
+    plt.plot(t_windowed, p_windowed)
+    plt.show()

pulse_detection.py

@@ -0,0 +1,37 @@
+"""
+Copyright (c) 2026 University of Bern, Space Research & Planetary Sciences, Linus Leo Stöckli.
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/
+"""
+
+import numpy as np
+from scipy.signal import hilbert
+from typing import Optional
+
+
+def detect_pulse(time: np.array, signal: np.array) -> Optional[int]:
+    # Compute the analytic signal using Hilbert transform
+    analytic_signal = hilbert(signal)
+    envelope = np.abs(analytic_signal)
+
+    # Detect the main pulse in the envelope
+    max_index = np.argmax(envelope)
+    main_pulse_time = time[max_index]
+
+    # Define a threshold to find the start and end of the pulse
+    threshold = envelope[max_index] * 0.5
+    pulse_indices = np.where(envelope > threshold)[0]
+    _pulse_start_time = time[pulse_indices[0]]
+    _pulse_end_time = time[pulse_indices[-1]]
+
+    # always start 15 ps before pulse begins
+    main_pulse_time -= 15.0
+
+    # only return the pulse if it is above the noise level
+    if envelope[max_index] > 7.0:
+        return int(main_pulse_time)
+    else:
+        return None

teraflash.py

@@ -0,0 +1,561 @@
+"""
+Copyright (c) 2026 University of Bern, Space Research & Planetary Sciences, Linus Leo Stöckli.
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/
+"""
+
+import logging
+import queue
+import threading
+import time
+import re
+
+import numpy as np
+import os
+
+from interface import TopticaSocket
+import interface
+from pulse_detection import detect_pulse
+
+
+class TeraFlash:
+
+    def __init__(self,
+                 ip: str = "169.254.84.101",
+                 rng: int = 50,
+                 t_begin: float = 1000.0,
+                 antenna_range: float = 1000.0,
+                 avg: int = 2,
+                 log_file=None):
+        """
+            TeraFlash object used to handle all top level interactions with the user
+        Args:
+            ip: ip-address of the device (instrument)
+            rng: initial range in ps
+            t_begin: initial start time of the window in ps
+            avg: initial number of measurements to average
+            log_file: name of the logfile, if required
+        """
+        self.r_dat_header = b'\xcd\xef\x124x\x9a\xfe\xdc\x00\x00\x00\x01\x00\xff\x91\xe7\x03\xe8\x00\x00'
+        self.send_header = b'\xcd\xef\x124x\x9a\xfe\xdc\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00'
+        self.r_stat_header = b'\xcd\xef\x124x\x9a\xfe\xdc\x00\x00\x00\x03\x00\x00\x00\x00\x00\x00\x02'
+        self.r_dat_header = b'\xcd\xef\x124x\x9a\xfe\xdc\x00\x00\x00\x01\x00\xff\x91\xe7\x03\xe8\x00'
+
+        if log_file:
+            if not os.path.isdir("logs"):
+                os.mkdir("logs")
+            if not log_file.endswith(".log"):
+                log_file += ".log"
+            if os.path.exists(f"logs/{log_file}"):
+                log_file = f"{int(time.time())}" + log_file
+            logging.basicConfig(filename=f"logs/{log_file}", level=logging.DEBUG)
+        logging.getLogger().addHandler(logging.StreamHandler())
+
+        self.laser = False
+        self.emitter = [False, False]
+        self.acquisition = False
+        self.allowed_antenna_ranges = [str(antenna_range)]
+        self.antenna_range = antenna_range
+        self.range = rng
+        self.t_begin = t_begin
+        self.avg = avg
+
+        self.ip = ip
+
+        self.cmd_queue = queue.Queue()
+        self.config_queue = queue.Queue()
+        self.running = threading.Event()
+        self.connected = threading.Event()
+        self.cmd_ack = threading.Event()
+        self.buffer_emptied = threading.Event()
+        self.range_changed = threading.Event()
+        self.acq_running = threading.Event()
+        self.avg_data = threading.Event()
+        self.cmd_ack.clear()
+        self.connected.clear()
+        self.running.set()
+        self.buffer_emptied.set()
+        self.range_changed.clear()
+        self.acq_running.clear()
+        self.avg_data.clear()
+
+        try:
+            self.socket = TopticaSocket(self.ip, self.running, self.connected, self.cmd_ack, self.buffer_emptied,
+                                        self.range_changed, self.acq_running, self.avg_data)
+        except ConnectionError:
+            logging.error("[INIT] Device is not connected. Check cabling")
+            exit()
+
+        # configure tcp config socket
+        self.config_thread = threading.Thread(target=self.socket.run_conf_tcp, args=(self.cmd_queue,))
+
+        # configure tcp data socket
+        self.data_thread = threading.Thread(target=self.socket.run_tcp_dat, args=(self.cmd_queue, self.config_queue))
+
+        # launch threads
+        self.data_thread.start()
+        self.config_thread.start()
+
+        # wait until a device is connected
+        self.connected.wait()
+
+        # start setup sequence
+        self.setup()
+
+        # wait some time to gather data
+        time.sleep(3)
+
+    def __enter__(self):
+        """
+            Entry point of the context manager
+        Returns: self
+
+        """
+        return self
+
+    def __exit__(self, tp, value, traceback):
+        """
+            Exit point of the context manager, closes the TCP connection properly
+        Args:
+            tp: -
+            value: -
+            traceback: -
+        """
+        # disconnect routine
+        self.disconnect()
+        time.sleep(1)
+        self.running.clear()
+        # if a device was connected, wait for the TCP threads to finish
+        if self.connected.is_set():
+            self.data_thread.join()
+            self.config_thread.join()
+        logging.debug("[EXIT] disconnected from device")
+
+    @staticmethod
+    def reset_tcp_avg():
+        # reset global variable avg
+        shape = interface.data.signal_1.shape
+        interface.data.signal_1 = np.zeros(shape)
+        interface.data.signal_2 = np.zeros(shape)
+        interface.n_avg = 0
+
+    @staticmethod
+    def get_n_avg():
+        # return global variable
+        return interface.n_avg
+
+    @staticmethod
+    def get_data():
+        # return global variable
+        return interface.data
+
+    @staticmethod
+    def get_status():
+        # return global variable
+        return interface.status
+
+    def setup(self):
+        """
+            performs the setup sequence of the device as reconstructed
+            by using wireshark on the official application
+        """
+
+        logging.info("[INIT] setting up the device...")
+        self.get_sys_status()
+        time.sleep(1)
+
+        # wait for status to be available
+        while "TIA-Sens(nA)" not in self.get_status():
+            self.get_sys_status()
+            time.sleep(1)
+
+        self.allowed_antenna_ranges = self.extract_tia_sens(self.get_status())
+        self.set_channel()
+        self.set_mode()
+        self.set_transmission()
+        self.set_antenna_range(1000.0)  # always set to +/- 1000 nA first
+        self.set_acq_begin(self.t_begin)
+        self.set_acq_avg()
+        self.set_acq_stop()
+        self.set_acq_range(self.range)
+        self.get_sys_monitor()
+        self.set_acq_avg(self.avg)
+        self.set_acq_range(self.range)
+        self.get_sys_monitor()
+        self.get_sys_status()
+        self.range_changed.clear()
+        logging.info("[INIT] device is ready.")
+
+    def disconnect(self):
+        """
+            disconnects from the device, order of calls is important!
+        """
+        logging.debug("[CMD] disconnecting from device")
+        self.set_acq_stop()
+        self.set_emitter(1, False)
+        self.set_emitter(2, False)
+        self.set_laser(False)
+
+    def get_sys_status(self):
+        """
+            request the system status string
+        """
+        logging.debug("[CMD] requesting status")
+        cmd = (b'\x14', "SYSTEM : TELL STATUS")
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+
+    def extract_tia_sens(self, text: str) -> list[float]:
+        """
+        Extracts TIA-Sens(nA) values from the given string.
+        Returns a list of floats, or None if not found.
+        """
+
+        match = re.search(r"TIA-Sens\(nA\):\s*([0-9.,\s]+)", text)
+        if not match:
+            logging.error(f"[INIT] no supported ranges found: {text}")
+            return []
+
+        values_str = match.group(1)
+
+        # Split by comma, trim, and convert to floats
+        values = [str(float(v.strip())) for v in values_str.split(",") if v.strip()]
+        logging.debug(f"[INIT] supported antenna ranges: {values}")
+
+        return values
+
+    def get_sys_monitor(self):
+        """
+            this is repeatedly called in the official application
+        """
+        cmd = (b'\x12', "SYSTEM : MONITOR 1")
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+
+    def set_channel(self, channel: str = "D"):
+        """
+            sets dual or single channel mode
+        Args:
+            channel: The desired mode
+        """
+        logging.debug(f"[CMD] setting channel: {channel}")
+        cmd = (b'\x0b', f"CHANNEL : {channel}")
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+
+    def set_mode(self, motion: str = "NORMAL"):
+        """
+            sets the motion mode
+        Args:
+            motion: The desired motion mode
+        """
+        logging.debug(f"[CMD] setting motion: {motion}")
+        cmd = (b'\x0f', f"MOTION : {motion}")
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+
+    def set_transmission(self, transmission: str = "SLIDING"):
+        """
+            sets the desired transmission mode
+        Args:
+            transmission: the desired transmission mode. "SLIDING" or "BLOCK"
+        """
+        logging.debug(f"[CMD] setting transmission: {transmission}")
+        cmd = (b'\x16', f"TRANSMISSION : {transmission}")
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+
+    def set_antenna_range(self, antenna_range: float):
+        """
+            sets the antenna range by value (needs to be an allowed value of the instrument)
+        """
+        antenna_range = float(antenna_range)
+
+        print(self.allowed_antenna_ranges)
+        print(antenna_range)
+        i = self.allowed_antenna_ranges.index(str(antenna_range))
+        self.antenna_range = antenna_range
+        self.config_queue.put(self.antenna_range)
+
+        if i == 0:
+            string = "FULL"
+        else:
+            string = f"ATN{i}"
+
+        logging.debug(f"[CMD] setting antenna: TIA {string}")
+        cmd = (b'\x11', f"SYSTEM : TIA {string}")
+
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+
+    def set_antenna_range_index(self, i):
+        """
+            sets the antenna range by index
+        """
+
+        self.antenna_range = float(self.allowed_antenna_ranges[i])
+        self.config_queue.put(self.antenna_range)
+
+        if i == 0:
+            string = "FULL"
+        else:
+            string = f"ATN{i}"
+
+        logging.debug(f"[CMD] setting antenna: TIA {string}")
+        cmd = (b'\x11', f"SYSTEM : TIA {string}")
+
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+
+    def set_acq_begin(self, t_begin: float = 1000.0):
+        """
+            sets the start time of the time domain window.
+        Args:
+            t_begin: The desired start time
+        """
+        logging.debug(f"[CMD] setting acq begin: {t_begin}")
+        if t_begin < 10:
+            b = b'\x18'
+        elif t_begin < 100:
+            b = b'\x19'
+        else:
+            b = b'\x1a'
+        cmd = (b, f"ACQUISITION : BEGIN {t_begin:.1f}")
+        measurement_was_running = self.acquisition
+        # need to stop the measurement before changing the range
+        logging.debug(f"stopping acquisition because of t_begin change! will restart late: {measurement_was_running}")
+        self.range_changed.set()
+        logging.debug(f"range changed set")
+        self.set_acq_stop()
+        logging.debug(f"stopped acq")
+        self.cmd_queue.put(cmd)
+        logging.debug(f"put cmd")
+        self.cmd_ack.wait()
+        logging.debug(f"wait for cmd ack")
+        self.cmd_ack.clear()
+        logging.debug(f"set t_begin")
+        self.t_begin = t_begin
+        logging.debug(f"waiting for buffer to be emptied")
+        self.buffer_emptied.wait()
+        self.buffer_emptied.clear()
+        logging.debug(f"buffer is emptied")
+        if measurement_was_running:
+            # if the measurement was running, restart it
+            self.set_acq_start()
+
+    @staticmethod
+    def nearest_entry(t_range: float, available_ranges: list):
+        """
+
+        Args:
+            t_range: range provided by the user
+            available_ranges: available ranges
+
+        Returns: the nearest available range to the provided range
+
+        """
+        nearest = available_ranges[0]
+        for num in available_ranges:
+            if abs(t_range - num) < abs(t_range - nearest):
+                nearest = num
+        return nearest
+
+    def set_acq_range(self, t_range: float = 50.0):
+        """
+            sets the range/width in the time domain window.
+            available: 5, 10, 15, 20, 35, 50, 70, 100, 120, 150 or 200
+        Args:
+            t_range: The desired range
+        """
+        available_ranges = [5, 10, 15, 20, 35, 50, 70, 100, 120, 150, 200]
+        if t_range not in available_ranges:
+            logging.info(f"[CMD] {t_range} is not supported. Only {available_ranges} are supported.")
+            t_range = self.nearest_entry(t_range, available_ranges)
+        logging.debug(f"[CMD] setting acq range: {t_range}")
+        if t_range <= 5.0:
+            b = b'\x18'
+        elif t_range <= 70.0:
+            b = b'\x19'
+        else:
+            b = b'\x1a'
+        cmd = (b, f"ACQUISITION : RANGE {t_range:.2f}")
+        measurement_was_running = self.acquisition
+        # need to stop the measurement before changing the range
+        logging.debug(f"stopping acquisition because of range change! will restart late: {measurement_was_running}")
+        self.range_changed.set()
+        self.set_acq_stop()
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+        self.range = t_range
+        self.buffer_emptied.wait()
+        self.buffer_emptied.clear()
+        if measurement_was_running:
+            # if the measurement was running, restart it
+            self.set_acq_start()
+
+    def set_acq_avg(self, avg: int = 2):
+        """
+            sets the width of the moving average to be performed by the device
+        Args:
+            avg: The desired averages
+        """
+        logging.debug(f"[CMD] setting acq avg: {avg}")
+        if avg < 10:
+            b = b'\x17'
+        elif avg < 100:
+            b = b'\x18'
+        elif avg < 1000:
+            b = b'\x19'
+        else:
+            b = b'\x1a'
+        cmd = (b, f"ACQUISITION : AVERAGE {avg}")
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+        # reset the average after it was changed
+        self.reset_acq_avg()
+        self.avg = avg
+        self.socket.avg_countdown = avg
+
+    def reset_acq_avg(self):
+        """
+            resets the acquisition moving average to be performed by the device
+        """
+        logging.debug("[CMD] resetting acq avg")
+
+        cmd = (b'\x17', "ACQUISITION : RESET AVG")
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+        self.socket.avg_countdown = self.avg
+
+    def wait_for_avg(self):
+        while self.socket.avg_countdown > 0:
+            time.sleep(0.1)
+
+    def set_laser(self, state: bool):
+        """
+            sets the laser mode ON or OFF
+        Args:
+            state: True for ON, False for OFF
+        """
+        if state:
+            logging.debug("[CMD] setting laser on")
+            cmd = (b'\x0a', "LASER : ON")
+        else:
+            # emitter bias must be turned off before we turn of the laser
+            if self.emitter:
+                self.set_emitter(1, False)
+                self.set_emitter(2, False)
+            logging.debug("[CMD] setting laser off")
+            cmd = (b'\x0b', "LASER : OFF")
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+        self.laser = state
+
+    def set_emitter(self, emitter: int, state: bool):
+        """
+            sets the state of the emitter ON or OFF
+        Args:
+            emitter: Emitter 1 or 2
+            state: True for ON, False for OFF
+        """
+        if emitter not in [1, 2]:
+            logging.info(f"emitter {emitter} is invalid, please use 1 or 2 as emitter value")
+            return
+        if state:
+            # laser must be running before we turn on the emitter bias
+            if not self.laser:
+                self.set_laser(True)
+            logging.debug(f"[CMD] setting emitter {emitter} on")
+            cmd = (b'\x0a', f"VOLT{emitter} : ON")
+        else:
+            logging.debug(f"[CMD] setting emitter {emitter} off")
+            cmd = (b'\x0b', f"VOLT{emitter} : OFF")
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+        self.emitter[emitter - 1] = state
+
+    def set_acq_start(self):
+        """
+            start the acquisition (data streaming)
+        """
+        logging.debug("[CMD] starting acquisition")
+        cmd = (b'\x13', "ACQUISITION : START")
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+        self.acq_running.set()
+        self.acquisition = True
+
+    def set_acq_stop(self):
+        """
+            stop the acquisition (data streaming)
+        """
+        logging.debug("[CMD] stopping acquisition")
+        cmd = (b'\x12', "ACQUISITION : STOP")
+        self.cmd_queue.put(cmd)
+        self.cmd_ack.wait()
+        self.cmd_ack.clear()
+        self.acq_running.clear()
+        self.acquisition = False
+
+    def auto_pulse_detection(self, lower: int, upper: int, detection_window: int = 100, detection_avg: int = 10):
+        """
+
+        Auto detection function of pulse.
+        Spectrometer needs to be running (laser, emitter, acq) before calling this
+
+        :param lower: lower end of detection window
+        :param upper: upper end of detection window
+        :param detection_window: detection window width
+        :param detection_avg: detection avg to smooth out noise
+        :return: detected pulse or None
+        """
+
+        previous_range = self.range
+        previous_avg = self.avg
+        logging.info(f"Searching pulses in range from {lower} to {upper}")
+
+        # setup
+        self.set_acq_range(detection_window)
+        self.set_acq_avg(detection_avg)
+        self.reset_acq_avg()
+        detected_pulse = None
+
+        # search in range
+        for t_begin in range(lower, upper, detection_window):
+            self.set_acq_begin(t_begin)
+            self.reset_acq_avg()
+            self.wait_for_avg()
+
+            timestamp = self.get_data().time.astype(np.float32)
+            pulse = self.get_data().signal_1.astype(np.float32)
+            detected_pulse = detect_pulse(timestamp, pulse)
+            if detected_pulse:
+                # found a pulse
+                logging.info(f"Found pulse at {detected_pulse}")
+                self.set_acq_begin(detected_pulse)
+                break
+
+        # revert to previous settings
+        self.set_acq_avg(previous_avg)
+        self.set_acq_range(previous_range)
+
+        # if no pulse has been detected, raise error
+        if not detected_pulse:
+            logging.error(f"No pulse detected in range from {lower} to {upper}")
+            raise Exception(f"No pulse detected in the range from {lower} to {upper}")

teraflash_ctrl-1.4.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: teraflash-ctrl
+Version: 1.4.0
+Summary: This Python package allows the configuration and readout of the TeraFlash Pro THz spectrometer.
+Author-email: Linus Leo Stöckli <linus.stoeckli@unibe.ch>
+Project-URL: Homepage, https://github.com/unibe-icelab/teraflash-ctrl-python
+Project-URL: Bug Tracker, https://github.com/unibe-icelab/teraflash-ctrl-python/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+
+# TeraFlash Pro Python Package
+
+<a href="https://github.com/unibe-icelab/teraflash-ctrl-python/releases"><img src="icons/icon.png" alt=“” width="100" height="100"> </img> </a>
+
+This code is developed by the University of Bern and is no official product of Toptica Photonics AG.  
+This Python Package allows the configuration and readout of the TeraFlash Pro THz spectrometer.  
+The TCP communication protocol is probably incomplete and features may be missing as it was reverse engineered using
+wireshark. The scanning stage is not supported but a list of other features is.
+
+This is a simple library with no persistence settings (the configurations of the previous run will not be stored when the python session is closed).
+A complete GUI written in Rust is also available [here](https://github.com/unibe-icelab/teraflash-ctrl).
+
+Features:  
+- [x] Select begin time for the time window
+- [x] Select range
+- [x] Select average
+- [x] Start/Stop Laser
+- [x] Start/Stop Emitters
+- [x] Start/Stop Acquisition
+- [x] Set transmission
+- [x] Set motion mode
+- [x] Set channel
+- [x] Get status
+- [x] Get data (time domain and frequency domain)
+- [x] auto pulse detection function
+- [X] Set antenna range
+- [ ] ...
+
+## I. Installation
+Download the [latest release](https://github.com/unibe-icelab/teraflash-ctrl-python/releases) or the [current state](https://github.com/unibe-icelab/teraflash-ctrl-python/archive/refs/heads/main.zip)
+as a zip archive, move it into your working directory and then run:
+```shell
+pip install teraflash-ctrl-python-v1.4.0.zip
+```
+for the latest version or
+```shell
+pip install teraflash-ctrl-python-main.zip
+```
+for the current state of the main branch to install the package for your virtual python environment or system-wide.
+
+## II. Taking a measurement
+When connected to the device, you can turn on the laser and then the emitter.
+After starting the acquisition, new data should be continuously updated and the most recent dataset can be obtained using `device.get_data()`:
+
+```python
+from teraflash import TeraFlash
+
+if __name__ == "__main__":
+    ip = "169.254.84.101"
+    with TeraFlash(ip) as device:
+        print(device.get_status())
+        device.set_laser(True)
+        device.set_emitter(1, True)
+        device.set_acq_start()
+        print(device.get_data())
+```
+
+Always use the context manager to ensure that the connection is properly closed upon exiting!  
+Consult the [`example.py`](example.py) for usage.  
+  
+  
+_Disclaimer: This package is provided on a best effort basis with no guarantee as to the functionality and correctness. Use at your
+own risk.
+Users are encouraged to contribute by submitting [issues](https://github.com/unibe-icelab/teraflash-ctrl-python/issues) and/or [pull requests](https://github.com/unibe-icelab/teraflash-ctrl-python/pulls) for bug reporting or feature requests._
+
+
+Copyright (c) 2026 University of Bern, Space Research & Planetary Sciences, Linus Leo Stöckli.
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/

teraflash_ctrl-1.4.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+__init__.py,sha256=Kidj6FQez2ufYQrtqvK3JEIIP2JOB87rVi8AWBM6mn0,292
+interface.py,sha256=ARUpyLKe78A--m5wkMUYpZKBGxNYqYtEsMVX8hmzT2M,14718
+io.py,sha256=pnMGiXGNv4Y6AYplfXy2P9LZigxmM_nvv5mSIvHcDwk,5057
+math_utils.py,sha256=ggw-_n6sHJFYRSJEz-H414gFgUHsJKtot0k6LuXyd0g,3528
+pulse_detection.py,sha256=RbilZCaN54KJgIVXpIZyT-8i6dazoj4rislbLlzTp38,1187
+teraflash.py,sha256=hCtJ_LrHFGElH13Tpytw8oBeC5JF3pCWLv_dTW9Ldu4,18660
+teraflash_ctrl-1.4.0.dist-info/METADATA,sha256=9RtKVs1WUczogZYN3mDB2Z8_SgmhbFYtrxsprh_yrsY,3768
+teraflash_ctrl-1.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+teraflash_ctrl-1.4.0.dist-info/top_level.txt,sha256=9rQxSaNdCCnCem0znghBa3xxZozxLtKmDFOXDASglas,59
+teraflash_ctrl-1.4.0.dist-info/RECORD,,

teraflash_ctrl-1.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

teraflash_ctrl-1.4.0.dist-info/top_level.txt

@@ -0,0 +1,6 @@
+__init__
+interface
+io
+math_utils
+pulse_detection
+teraflash