fpfind 3.3.0__py3-none-any.whl

fpfind/__init__.py

@@ -0,0 +1,14 @@
+from importlib.metadata import version
+
+import fpfind.lib
+from fpfind.lib.constants import NP_PRECISEFLOAT, TSRES
+from fpfind.lib.utils import get_overlap
+
+__all__ = [
+    "fpfind",
+    "NP_PRECISEFLOAT",
+    "TSRES",
+    "get_overlap",  # used in tests
+]
+
+VERSION = version("fpfind")

fpfind/_postinstall

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Performs post-installation compilation of freqcd. Do not modify.
+TARGET=freqcd
+if [ ! -z "$1" ]; then TARGET="$1"; fi
+gcc -o ${TARGET} freqcd.c lib/getopt.c -lm

fpfind/apps/fpplot.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""NOT FOR PRODUCTION USE - but in main branch for ease of maintenance ;)
+
+Changelog:
+    2024-02-02, Justin: Init
+"""
+
+import argparse
+import logging
+import sys
+
+import kochen  # v0.2024.4
+import kochen.logging
+import kochen.scriptutil
+import matplotlib.pyplot as plt
+import numpy as np
+from S15lib.g2lib.g2lib import histogram
+
+from fpfind.lib.parse_timestamps import read_a1_overlapping
+from fpfind.lib.utils import (
+    get_first_overlapping_epoch,
+    get_timestamp_pattern,
+    normalize_timestamps,
+)
+
+_ENABLE_BREAKPOINT = False
+logger = logging.getLogger(__name__)
+
+
+def plotter(
+    alice,
+    bob,
+    freq,
+    time,
+    width,
+    resolution,
+    window=800,
+    save=False,
+    normalize=False,
+    decimation=1,
+):
+    bob = (bob - time) / (1 + freq)
+    ys, xs, stats = histogram(
+        alice,
+        bob,
+        duration=width,
+        resolution=resolution,
+        statistics=True,
+        window=window,
+    )
+    # Custom breakpoint for experimentation
+    if _ENABLE_BREAKPOINT:
+        globals().update(locals())  # write all local variables to global scope
+        raise  # noqa: PLE0704
+
+    if decimation > 1:
+        ys = ys[::decimation]
+        xs = xs[::decimation]
+
+    elapsed = (alice[-1] - alice[0]) * 1e-9
+    _center = ys[500:1500]
+    _sides = np.array(list(ys[:500]) + list(ys[1500:]))
+    coincidences = np.sum(_center) - np.sum(_sides) * len(_center) / len(_sides)
+
+    s1 = len(alice) / elapsed
+    s2 = len(bob) / elapsed
+    c = coincidences / elapsed
+    print("Totals:")
+    print(f"  S1: {len(alice):d}")
+    print(f"  S2: {len(bob):d}")
+    print(f"  C:  {coincidences:.0f}")
+    print(f"Time elapsed: {elapsed:.3f}s")
+    print(f"  s1: {s1:.0f}")
+    print(f"  s2: {s2:.0f}")
+    print(f"  sg: {(len(alice) * len(bob)) ** 0.5 / elapsed:.0f}")
+    print(f"  c:  {c:.0f}")
+    print(f"Efficiency: {100 * c / np.sqrt(s1 * s2):.1f}%")
+
+    # Normalize?
+    plt.subplots(figsize=(5, 3.5))
+    if normalize:
+        accs = s1 * s2 * elapsed * resolution * 1e-9
+        yerrs = np.sqrt(ys) / accs
+        ys = ys / accs
+        print(f"Normalizing by background = {accs}")
+        plt.errorbar(xs, ys, yerrs, fmt=".", markersize=3, elinewidth=1)
+
+    else:
+        plt.plot(xs, ys, linewidth=1)
+
+    plt.xlabel("Delay, $\\tau$ (ns)")
+    plt.ylabel("$g^{(2)}(\\tau)$")
+    plt.tight_layout()
+    if save:
+        plt.xlim(np.min(xs), np.max(xs))
+        plt.tight_layout()
+        plt.savefig(save, dpi=250)
+    plt.show()
+    globals().update(locals())
+    raise  # noqa: PLE0704
+
+
+def attenuate(ts, transmission=1):
+    if transmission >= 1:
+        return ts
+    mask = np.random.random(size=ts.size) < transmission
+    return ts[mask]
+
+
+def main():  # noqa: PLR0915
+    global _ENABLE_BREAKPOINT  # noqa: PLW0603
+    parser = kochen.scriptutil.generate_default_parser(__doc__, "fpfind")
+
+    # Boilerplate
+    # fmt: off
+    pgroup_config = parser.add_argument_group("display/configuration")
+    pgroup_config.add_argument(
+        "-h", "--help", action="store_true",
+        help="Show this help message and exit")
+    pgroup_config.add_argument(
+        "-v", "--verbosity", action="count", default=0,
+        help="Specify debug verbosity, e.g. -vv for more verbosity")
+    pgroup_config.add_argument(
+        "-L", "--logging", metavar="",
+        help="Log to file, if specified. Log level follows verbosity.")
+    pgroup_config.add_argument(
+        "--quiet", action="store_true",
+        help="Suppress errors, but will not block logging")
+    pgroup_config.add_argument(
+        "--config", metavar="", is_config_file_arg=True,
+        help="Path to configuration file")
+    pgroup_config.add_argument(
+        "--save", metavar="", is_write_out_config_file_arg=True,
+        help="Path to configuration file for saving, then immediately exit")
+    pgroup_config.add_argument(
+        "--experiment", action="store_true",
+        help=argparse.SUPPRESS)
+
+    # Timestamp importing arguments
+    pgroup_ts = parser.add_argument_group("importing timestamps")
+    pgroup_ts.add_argument(
+        "-t", "--reference", metavar="",
+        help="Timestamp file in 'a1' format, from low-count side (reference)")
+    pgroup_ts.add_argument(
+        "-T", "--target", metavar="",
+        help="Timestamp file in 'a1' format, from high-count side")
+    pgroup_ts.add_argument(
+        "-X", "--legacy", action="store_true",
+        help="Parse raw timestamps in legacy mode (default: %(default)s)")
+    pgroup_ts.add_argument(
+        "-Z", "--skip-duration", metavar="", type=float, default=0,
+        help="Specify initial duration to skip, in seconds (default: %(default)s)")
+
+    # Epoch importing arguments
+    pgroup_ep = parser.add_argument_group("importing epochs")
+    pgroup_ep.add_argument(
+        "-d", "--sendfiles", metavar="",
+        help="SENDFILES, from low-count side (reference)")
+    pgroup_ep.add_argument(
+        "-D", "--t1files", metavar="",
+        help="T1FILES, from high-count side")
+    pgroup_ep.add_argument(
+        "-e", "--first-epoch", metavar="",
+        help="Specify filename of first overlapping epoch, optional")
+    pgroup_ep.add_argument(
+        "-n", "--num-epochs", metavar="", type=int, default=1,
+        help="Specify number of epochs to import (default: %(default)d)")
+    pgroup_ep.add_argument(
+        "-z", "--skip-epochs", metavar="", type=int, default=0,
+        help="Specify number of initial epochs to skip (default: %(default)d)")
+
+    # Epoch importing arguments
+    pgroup_chselect = parser.add_argument_group("channel selection")
+    pgroup_chselect.add_argument(
+        "-m", "--reference-pattern", metavar="", type=int,
+        help="Pattern mask for selecting detector events from low-count side")
+    pgroup_chselect.add_argument(
+        "-M", "--target-pattern", metavar="", type=int,
+        help="Pattern mask for selecting detector events from high-count side")
+
+    # Plotting parameters
+    pgroup = parser.add_argument_group("plotting")
+    pgroup.add_argument(
+        "--df", type=float, default=0.0,
+        help="Specify clock skew, in absolute units (default: %(default)f)")
+    pgroup.add_argument(
+        "--dt", type=float, default=0.0,
+        help="Specify time delay, in units of ns (default: %(default)f)")
+    pgroup.add_argument(
+        "--width", type=float, default=1000,
+        help="Specify one-sided width of histogram, in units of ns (default: %(default)f)")  # noqa: E501
+    pgroup.add_argument(
+        "-r", "--resolution", "--final-res", type=float, default=1,
+        help="Specify resolution of histogram, in units of ns (default: %(default)f)")
+    pgroup.add_argument(
+        "--duration", type=float, default=1,
+        help="Specify duration of timestamps to use, units of s (default: %(default)f)")
+    pgroup.add_argument(
+        "--save-plot",
+        help="Specify filename to save the plot to")
+    pgroup.add_argument(
+        "--normalize", action="store_true",
+        help="Normalize g(2) plot")
+    pgroup.add_argument(
+        "--decimation", type=int, default=1,
+        help="Take only every N-th point, for clarity (default: %(default)d)")
+    # fmt: on
+
+    # Parse arguments and configure logging
+    args = kochen.scriptutil.parse_args_or_help(parser, ignore_unknown=True)
+    kochen.logging.set_default_handlers(logger, file=args.logging)
+    kochen.logging.set_logging_level(logger, args.verbosity)
+    logger.debug("%s", args)
+
+    # Set experimental mode
+    if args.experiment:
+        _ENABLE_BREAKPOINT = True
+
+    # Obtain timestamps needed for fpplot
+    #   alice: low count side - chopper - HeadT2 - sendfiles (reference)
+    #   bob: high count side - chopper2 - HeadT1 - t1files
+    if args.sendfiles is not None and args.t1files is not None:
+        logger.info("  Reading from epoch directories...")
+        _is_reading_ts = False
+
+        # Automatically choose first overlapping epoch if not supplied manually
+        first_epoch, available_epochs = get_first_overlapping_epoch(
+            args.sendfiles,
+            args.t1files,
+            first_epoch=args.first_epoch,
+            return_length=True,
+        )
+        if available_epochs < args.num_epochs + args.skip_epochs:
+            logger.warning("  Insufficient epochs")
+
+        # Read epochs
+        alice, aps = get_timestamp_pattern(
+            args.sendfiles, "T2", first_epoch, args.skip_epochs, args.num_epochs
+        )
+        bob, bps = get_timestamp_pattern(
+            args.t1files, "T1", first_epoch, args.skip_epochs, args.num_epochs
+        )
+
+    elif args.target is not None and args.reference is not None:
+        logger.info("  Reading from timestamp files...")
+        _is_reading_ts = True
+        (alice, bob), (aps, bps) = read_a1_overlapping(
+            args.reference,
+            args.target,
+            legacy=args.legacy,
+            duration=args.duration + args.skip_duration,
+        )
+
+    else:
+        logger.error("Timestamp files/epochs must be supplied with -tT/-dD")
+        sys.exit(1)
+
+    # Select events only from specified channels
+    if args.reference_pattern is not None:
+        alice = alice[(aps & args.reference_pattern).astype(bool)]
+    if args.target_pattern is not None:
+        bob = bob[(bps & args.target_pattern).astype(bool)]
+
+    # Normalize timestamps to common time reference near start, so that
+    # frequency compensation will not shift the timing difference too far
+    skip = args.skip_duration if _is_reading_ts else 0
+    alice, bob = normalize_timestamps(alice, bob, skip=skip)
+
+    alice = attenuate(alice, 1)
+    bob = attenuate(bob, 1)
+
+    plotter(
+        alice,
+        bob,
+        args.df,
+        args.dt,
+        2 * args.width,
+        resolution=args.resolution,
+        save=args.save_plot,
+        normalize=args.normalize,
+        decimation=args.decimation,
+    )
+
+
+if __name__ == "__main__":
+    main()

fpfind/apps/g2_two_timestamps.py

@@ -0,0 +1,38 @@
+import numpy as np
+import matplotlib.pyplot as plt
+import parse_timestamps as parser
+
+Ta = 2**27
+N = 2**18
+# binwidth = 32
+
+def g2(arr1, arr2, start_time, delta_t):
+    maxdelay = 10000000
+    arr1 = arr1[np.where((arr1 > start_time) & (arr1 <= start_time + Ta))]
+    arr2 = arr2[np.where((arr2 > start_time) & (arr2 <= start_time + Ta))]
+    arr3 = np.zeros(N, dtype = np.int32)
+    delay = 0
+
+    for event in arr2:
+        while arr1.size > 1:
+            if (event - arr1[0] >= maxdelay):
+                # np.delete(arr1, 0)
+                arr1 = arr1[1:]
+                # del arr1[:1]
+            else: break
+        for stamp in arr1:
+            delay = event - stamp
+            arr3[int(delay // delta_t) % N] += 1
+
+    return arr3
+
+# alice1 = parser.read_a1('./data/1_rawevents/raw_alice_20221109170747.dat', legacy = True)
+# bob1 = parser.read_a1('./data/1_rawevents/raw_bob_20221109170747.dat', legacy = True)
+# start = max(alice1[0], bob1[0])
+# alice_pro = alice1[np.where((alice1 > start) & (alice1 <= start + Ta))]
+# bob_pro = bob1[np.where((bob1 > start) & (bob1 <= start + Ta))]
+# print(alice_pro.size)
+# print(bob_pro.size)
+# g2alicebob = g2(alice_pro, bob_pro)
+# plt.plot(g2alicebob)
+# plt.show()

fpfind/apps/generate_freqcd_testcase.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+# Companion script to create sample binary timestamps for freqcd.c
+#   Justin, 2023-02-03
+#
+# Examples:
+#
+#   1. Generate legacy timestamps and save to file:
+#
+#      ./generate_freqcd_testcase.py \
+#          -o .input \
+#          -t 0 1000000000 2000000000 \
+#          -x
+#      ./freqcd -f 1000000 < .input
+#
+#   2. Pipe timestamps directly into freqcd
+#
+#      ./generate_freqcd_testcase.py -t 0 1000000000 2000000000 |\
+#          ./freqcd -f 1000000 |\
+#          ./freqcd -f -999933 -o .output
+#
+#   3. Dynamically generate timestamps via command line and save to file
+#
+#      ./generate_freqcd_testcase.py -o .input
+#
+#   4. Read timestamps from event supplied via command line or file
+#
+#      cat .input | ./generate_freqcd_testcase.py
+#      ./generate_freqcd_testcase.py .input
+#
+
+import argparse
+import pathlib
+import secrets
+import struct
+import sys
+import warnings
+
+import fpfind.lib.parse_timestamps as ts_parser
+
+warnings.simplefilter(action="once", category=UserWarning)
+
+LEGACY = False
+
+def get_event(timestamp, detectors: int = 0b0001):
+    """
+
+    Timestamps are not restricted to the (1 << 54) cap, to reflect the
+    filespec of truncating the excess significant bits. Use case in
+    having user see that the timestamps have indeed overflowed, e.g. for
+    verifying overflow response. A warning will be issued for precaution.
+    """
+    assert isinstance(timestamp, int) and (0 <= timestamp)
+    if timestamp >= (1 << 54):
+        warnings.warn(
+            f"Timestamp overflow detected, "
+            "will truncate accordingly."
+        )
+        timestamp = timestamp & 0x3FFFFFFFFFFFFF
+    assert isinstance(detectors, int) and (0 <= detectors < 16)
+    event = (timestamp << 10) + detectors
+    if LEGACY:
+        event = ((event & 0xFFFFFFFF) << 32) + (event >> 32)
+    return struct.pack("=Q", event)
+
+def fwrite(event, filename: str = ".freqcd.input"):
+    with open(filename, "ab") as f:
+        f.write(event)
+
+def owrite(event):
+    sys.stdout.buffer.write(event)
+    sys.stdout.flush()
+
+def main():
+    global LEGACY
+    parser = argparse.ArgumentParser(description="Generates binary timestamp events for testing freqcd.")
+    parser.add_argument("-o", help="output file, defaults to stdout stream")
+    parser.add_argument("-t", type=int, nargs="+", help="list of timestamps in decimal")
+    parser.add_argument("-x", action="store_true", help="legacy format")
+    parser.add_argument("infile", nargs="?", help="optional filename of events ('-' if reading from stdin)")
+
+    # Print help if no arguments supplied
+    if len(sys.argv) == 1:
+        parser.print_help(sys.stderr)
+        sys.exit(1)
+
+    args = parser.parse_args()
+    if args.x:
+        LEGACY = True
+
+    # Modify method of writing
+    write = owrite
+    if args.o:
+        write = lambda e: fwrite(e, args.o)
+        open(args.o, "wb").close()  # truncate file
+
+    # Different methods of reading timestamps
+    # 1. Read decimal timestamps from command line
+    #    e.g. "-t 0 1000 2000"
+    if args.t:
+        for ts in args.t:
+            write(get_event(ts))
+
+    # 2. Read raw timestamps from file and print as decimal
+    #    e.g. "filename.dat"
+    # 3. Read raw timestamps from stdin
+    #    e.g. "-"
+    elif args.infile:
+        inputfile = args.infile
+
+        # Direct reading from stdin currently not supported
+        # instead creating a temporary file to store binary data
+        HAS_TEMP_FILE = args.infile == "-"
+        if HAS_TEMP_FILE:
+            inputfile = pathlib.Path(secrets.token_hex(5) + "_tempinput")
+
+        # Read binary timestamps from file
+        try:
+            if HAS_TEMP_FILE:
+                with open(inputfile, "wb") as f:
+                    f.write(sys.stdin.buffer.read())
+
+            # Parsing binary timestamps
+            ts, _ = ts_parser.read_a1(inputfile, args.x)
+            for t in ts:
+                print(int(t * ts_parser.TSRES.PS4.value))
+
+        # Clean up
+        finally:
+            if HAS_TEMP_FILE:
+                inputfile.unlink()
+
+    # 4. Read decimal timestamps from interactive prompt,
+    #    note output file in this case should be supplied.
+    #    This is only for testing purposes.
+    else:
+        # Read from stdin
+        print("Enter timestamps in decimal separated by newlines.")
+        print("Press Ctrl-C to stop input.")
+        try:
+            while True:
+                try:
+                    event = get_event(int(input()))
+                    write(event)
+                except ValueError:
+                    pass
+        except KeyboardInterrupt:
+            pass
+
+if __name__ == "__main__":
+    main()

fpfind/apps/generate_freqdetuneg2.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+# Justin, 2022-10-07
+# From single timestamp g(2) file, generate increasingly frequency detuned timestamping.
+#
+# Worked out the theory with Darren:
+#   Given a clock rate of f Hz, and the detuning offset denoted D,
+#   the detuned frequency is f + D, where D/f = detuning ratio (e.g. 1e-9).
+#   
+#   Here's an example to illustrate the relationship:
+#      The device keeps time via the clock rate. Suppose the clock fed to it
+#      is 10Hz, then the device which registers 10 clock ticks as 1 second will
+#      read out 1 second. The same device with 15 Hz will then read 1.5 seconds,
+#      i.e. faster clock => timestamp is faster relative to actual time.
+#
+#   Given a detuning ratio R, the frequency fed to the device is now
+#   f + R*f, so the effective timestamp has an additional (1+R) product.
+
+import parse_timestamps as parser
+import numpy as np
+
+DATA_DIR = "./Clock-sync/20221007_freqdetuneg2"
+FILE = DATA_DIR + "/singletimestampnodelay.a1.dat"
+
+# Read file
+t, p = parser.read_a1(FILE, legacy=True)
+
+# Perform frequency detuning of timestamp clock
+def detune(t: np.ndarray, p: np.ndarray, channel: int, ratio: float = 0, offset: float = 0):
+    """Performs frequency detuning of timestamp clock on one channel.
+
+    Args:
+        t: Timestamp data
+        p: Detector channel pattern
+        channel: Choice of channel, follows detector pattern, i.e. 0b0100 for channel 3
+        ratio: Frequency detuning ratio, i.e. 0 is no detuning
+        offset: Performs fixed timing offset, optional
+    """
+    tc, pc = t[p==channel], p[p==channel]
+    tc = (tc-t[0])*(1+ratio) + t[0] + offset  # assume both devices are synchronized t
+    return tc, pc
+
+parser.write_a2(DATA_DIR + "/c1_a2.dat", t[p==1], p[p==1], legacy=True)
+parser.write_a1(DATA_DIR + "/c4e10.dat", *detune(t, p, 8, 1e-10), legacy=True)
+parser.write_a1(DATA_DIR + "/c4e9.dat", *detune(t, p, 8, 1e-9), legacy=True)
+parser.write_a1(DATA_DIR + "/c4e8.dat", *detune(t, p, 8, 1e-8), legacy=True)
+parser.write_a1(DATA_DIR + "/c4e7.dat", *detune(t, p, 8, 1e-7), legacy=True)
+parser.write_a1(DATA_DIR + "/c4e6.dat", *detune(t, p, 8, 1e-6), legacy=True)
+parser.write_a1(DATA_DIR + "/c4e5.dat", *detune(t, p, 8, 1e-5), legacy=True)
+parser.write_a1(DATA_DIR + "/c4e4.dat", *detune(t, p, 8, 1e-4), legacy=True)
+parser.write_a1(DATA_DIR + "/c4e3.dat", *detune(t, p, 8, 1e-3), legacy=True)

fpfind/apps/show-timestamps

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Prints 'a1' timestamp files as binary text
+# Justin, 2025-08-27
+#
+# Useful for downstream textual processing, e.g. regex-filtering with grep.
+# Pass '-' as argument to read from standard input instead of a file.
+#
+# Example:
+#   00000000: 01011000110100001111011100001000 00000000000000000000000000000111
+#   00000008: 00000010110000111111001100100001 00000000000000000000000000001010
+#   00000010: 01011111000110000100101100001000 00000000000000000000000000010000
+#   00000018: 01101111101000111111101100101000 00000000000000000000000000010000
+#   ...
+
+test -z "$1" && { echo "usage: show-timestamps {<FILE>|-}"; exit 1; }
+xxd -e -g 4 -c 8 "$1" | cut -b11-27 | xxd -r -p - | xxd -b -g 4 -c 8 | cut -b1-75

fpfind/apps/show-timestamps-hex

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Prints 'a1' timestamp files as hexadecimal text
+# Justin, 2025-08-27
+#
+# Useful for downstream textual processing, e.g. regex-filtering with grep.
+# Pass '-' as argument to read from standard input instead of a file.
+#
+# Example:
+#   00000000: 58d0f708 00000007
+#   00000008: 02c3f321 0000000a
+#   00000010: 5f184b08 00000010
+#   00000018: 6fa3fb28 00000010
+#   ...
+
+test -z "$1" && { echo "usage: show-timestamps-hex {<FILE>|-}"; exit 1; }
+xxd -e -g 4 -c 8 "$1" | cut -b1-27

fpfind/apps/tsviz.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+# Visualize timestamp file
+# Justin, 2025-04-07
+#
+# Currently hardcoded with read_a1(legacy=True).
+
+import sys
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+import fpfind.lib.parse_timestamps as parser
+
+if len(sys.argv) < 2:
+    print("usage: tsviz.py <FILE> [legacy]")
+    sys.exit(1)
+
+legacy = len(sys.argv) >= 3
+filename = sys.argv[1]
+ts, ps = parser.read_a1(filename, legacy=legacy, ignore_rollover=True)
+
+
+def generate_xy(ts, ps, ch):
+    """
+    Args:
+        ch: Channel number, i.e. between 1 and 4 inclusive.
+    """
+    p = int(2 ** (ch - 1))
+    xs = ts[(ps & p).astype(bool)]
+    ys = np.ones(xs.size) * ch
+    return xs, ys
+
+
+args = ["x"]
+kwargs = {"markersize": 3}
+
+fig, ax = plt.subplots(figsize=(12, 3))
+plt.plot(*generate_xy(ts, ps, 1), *args, **kwargs)
+plt.plot(*generate_xy(ts, ps, 2), *args, **kwargs)
+plt.plot(*generate_xy(ts, ps, 3), *args, **kwargs)
+plt.plot(*generate_xy(ts, ps, 4), *args, **kwargs)
+
+plt.ylim([-1, 6])
+plt.yticks([1, 2, 3, 4])
+plt.gca().invert_yaxis()
+plt.ylabel("Channel")
+plt.xlabel("Time (ns)")
+plt.tight_layout()
+
+plt.show()