bh_spc.hpp

/*
 * This file is part of libtcspc
 * Copyright 2019-2026 Board of Regents of the University of Wisconsin System
 * SPDX-License-Identifier: MIT
 */
 
#pragma once
 
#include "common.hpp"
#include "core.hpp"
#include "int_arith.hpp"
#include "int_types.hpp"
#include "introspect.hpp"
#include "npint.hpp"
#include "npint_ops.hpp"
#include "numeric_traits.hpp"
#include "processor.hpp"
#include "read_integers.hpp"
#include "time_tagged_events.hpp"
 
#include <array>
#include <cstddef>
#include <ostream>
#include <span>
#include <stdexcept>
#include <type_traits>
#include <utility>
 
namespace tcspc {
 
// Raw photon event data formats are documented in The bh TCSPC Handbook (see
// section on FIFO Files in the chapter on Data file structure).

struct bh_spc_event {
    std::array<std::byte, 4> bytes;

    static constexpr u32 macrotime_overflow_period = 1 << 12;

    static constexpr bool has_markers = true;

    [[nodiscard]] constexpr auto adc_value() const noexcept -> u16np {
        return read_u16le_at<2>(std::span(bytes)) & 0x0fff_u16np;
    }

    [[nodiscard]] constexpr auto routing_signals() const noexcept -> u8np {
        // The documentation somewhat confusingly says that these bits are
        // "inverted", but what they mean is that the TTL inputs are active
        // low. The bits in the FIFO data are not inverted.
        return read_u8_at<1>(std::span(bytes)) >> 4;
    }

    [[nodiscard]] constexpr auto macrotime() const noexcept -> u16np {
        return read_u16le_at<0>(std::span(bytes)) & 0x0fff_u16np;
    }

    [[nodiscard]] constexpr auto marker_flag() const noexcept -> bool {
        return (read_u8_at<3>(std::span(bytes)) & (1_u8np << 4)) != 0_u8np;
    }

    [[nodiscard]] constexpr auto marker_bits() const noexcept -> u8np {
        return routing_signals();
    }

    [[nodiscard]] constexpr auto gap_flag() const noexcept -> bool {
        return (read_u8_at<3>(std::span(bytes)) & (1_u8np << 5)) != 0_u8np;
    }

    [[nodiscard]] constexpr auto macrotime_overflow_flag() const noexcept
        -> bool {
        return (read_u8_at<3>(std::span(bytes)) & (1_u8np << 6)) != 0_u8np;
    }

    [[nodiscard]] constexpr auto invalid_flag() const noexcept -> bool {
        return (read_u8_at<3>(std::span(bytes)) & (1_u8np << 7)) != 0_u8np;
    }

    [[nodiscard]] constexpr auto
    is_multiple_macrotime_overflow() const noexcept -> bool {
        // Although documentation is not clear, a marker can share an event
        // record with a (single) macrotime overflow, just as a photon can.
        return macrotime_overflow_flag() && invalid_flag() && !marker_flag();
    }

    [[nodiscard]] constexpr auto
    multiple_macrotime_overflow_count() const noexcept -> u32np {
        return read_u32le_at<0>(std::span(bytes)) & 0x0fff'ffff_u32np;
    }

    static constexpr auto make_photon(u16np macrotime, u16np adc_value,
                                      u8np route,
                                      bool macrotime_overflow = false)
        -> bh_spc_event {
        return make_from_fields(false, macrotime_overflow, false, false,
                                adc_value, route, macrotime);
    }

    static constexpr auto make_invalid_photon(u16np macrotime, u16np adc_value)
        -> bh_spc_event {
        // N.B. No MTOV.
        return make_from_fields(true, false, false, false, adc_value, 0_u8np,
                                macrotime);
    }

    static constexpr auto make_marker(u16np macrotime, u8np marker_bits,
                                      bool macrotime_overflow = false)
        -> bh_spc_event {
        return make_from_fields(true, macrotime_overflow, false, true, 0_u16np,
                                marker_bits, macrotime);
    }

    static constexpr auto make_marker0_with_intensity_count(
        u16np macrotime, u8np marker_bits, u16np count,
        bool macrotime_overflow = false) -> bh_spc_event {
        if ((marker_bits & 0x01_u8np) == 0_u8np)
            throw std::invalid_argument(
                "bit for marker 0 must be set in intensity counter event");
        return make_from_fields(true, macrotime_overflow, false, true, count,
                                marker_bits, macrotime);
    }

    static constexpr auto make_multiple_macrotime_overflow(u32np count)
        -> bh_spc_event {
        constexpr auto flags = 0b1100'0000_u8np;
        return bh_spc_event{{
            std::byte(u8np(count >> 0).value()),
            std::byte(u8np(count >> 8).value()),
            std::byte(u8np(count >> 16).value()),
            std::byte((flags | (u8np(count >> 24) & 0x0f_u8np)).value()),
        }};
    }

    auto gap_flag(bool gap) noexcept -> bh_spc_event & {
        static constexpr auto gap_bit = std::byte(0b0010'0000);
        bytes[3] = (bytes[3] & ~gap_bit) | (gap ? gap_bit : std::byte(0));
        return *this;
    }

    friend auto operator==(bh_spc_event const &lhs,
                           bh_spc_event const &rhs) noexcept -> bool = default;

    friend auto operator<<(std::ostream &strm, bh_spc_event const &e)
        -> std::ostream & {
        return strm << "bh_spc(MT=" << e.macrotime()
                    << ", ROUT=" << unsigned(e.routing_signals().value())
                    << ", ADC=" << e.adc_value()
                    << ", INVALID=" << e.invalid_flag()
                    << ", MTOV=" << e.macrotime_overflow_flag()
                    << ", GAP=" << e.gap_flag() << ", MARK=" << e.marker_flag()
                    << ", CNT=" << e.multiple_macrotime_overflow_count()
                    << ")";
    }
 
  private:
    static constexpr auto make_from_fields(bool invalid, bool mtov, bool gap,
                                           bool mark, u16np adc, u8np rout,
                                           u16np mt) -> bh_spc_event {
        auto const flags = (u8np(u8(invalid)) << 7) | (u8np(u8(mtov)) << 6) |
                           (u8np(u8(gap)) << 5) | (u8np(u8(mark)) << 4);
        return bh_spc_event{{
            std::byte(u8np(mt).value()),
            std::byte(((rout << 4) | (u8np(mt >> 8) & 0x0f_u8np)).value()),
            std::byte(u8np(adc).value()),
            std::byte((flags | (u8np(adc >> 8) & 0x0f_u8np)).value()),
        }};
    }
};

struct bh_spc600_4096ch_event {
    std::array<std::byte, 6> bytes;

    static constexpr u32 macrotime_overflow_period = 1 << 24;

    static constexpr bool has_markers = false;

    [[nodiscard]] constexpr auto adc_value() const noexcept -> u16np {
        return read_u16le_at<0>(std::span(bytes)) & 0x0fff_u16np;
    }

    [[nodiscard]] constexpr auto routing_signals() const noexcept -> u8np {
        return read_u8_at<3>(std::span(bytes));
    }

    [[nodiscard]] constexpr auto macrotime() const noexcept -> u32np {
        auto const lo8 = u32np(read_u8_at<4>(std::span(bytes)));
        auto const mid8 = u32np(read_u8_at<5>(std::span(bytes)));
        auto const hi8 = u32np(read_u8_at<2>(std::span(bytes)));
        return lo8 | (mid8 << 8) | (hi8 << 16);
    }

    [[nodiscard]] static constexpr auto marker_flag() noexcept -> bool {
        return false;
    }

    [[nodiscard]] static constexpr auto marker_bits() noexcept -> u8np {
        return 0_u8np;
    }

    [[nodiscard]] constexpr auto gap_flag() const noexcept -> bool {
        return (read_u8_at<1>(std::span(bytes)) & (1_u8np << 6)) != 0_u8np;
    }

    [[nodiscard]] constexpr auto macrotime_overflow_flag() const noexcept
        -> bool {
        return (read_u8_at<1>(std::span(bytes)) & (1_u8np << 5)) != 0_u8np;
    }

    [[nodiscard]] constexpr auto invalid_flag() const noexcept -> bool {
        return (read_u8_at<1>(std::span(bytes)) & (1_u8np << 4)) != 0_u8np;
    }

    [[nodiscard]] static constexpr auto
    is_multiple_macrotime_overflow() noexcept -> bool {
        return false;
    }

    [[nodiscard]] static constexpr auto
    multiple_macrotime_overflow_count() noexcept -> u32np {
        return 0_u32np;
    }

    static constexpr auto make_photon(u32np macrotime, u16np adc_value,
                                      u8np route,
                                      bool macrotime_overflow = false)
        -> bh_spc600_4096ch_event {
        return make_from_fields(macrotime, route, false, macrotime_overflow,
                                false, adc_value);
    }

    static constexpr auto make_invalid_photon(u32np macrotime, u16np adc_value,
                                              bool macrotime_overflow = false)
        -> bh_spc600_4096ch_event {
        return make_from_fields(macrotime, 0_u8np, false, macrotime_overflow,
                                true, adc_value);
    }

    auto gap_flag(bool gap) noexcept -> bh_spc600_4096ch_event & {
        static constexpr auto gap_bit = std::byte(0b0100'0000);
        bytes[1] = (bytes[1] & ~gap_bit) | (gap ? gap_bit : std::byte(0));
        return *this;
    }

    friend auto operator==(bh_spc600_4096ch_event const &lhs,
                           bh_spc600_4096ch_event const &rhs) noexcept
        -> bool = default;

    friend auto operator<<(std::ostream &strm, bh_spc600_4096ch_event const &e)
        -> std::ostream & {
        bool const unused_bit =
            (read_u8_at<1>(std::span(e.bytes)) & (1_u8np << 7)) != 0_u8np;
        return strm << "bh_spc600_4096ch(MT=" << e.macrotime()
                    << ", R=" << unsigned(e.routing_signals().value())
                    << ", ADC=" << e.adc_value()
                    << ", INVALID=" << e.invalid_flag()
                    << ", MTOV=" << e.macrotime_overflow_flag()
                    << ", GAP=" << e.gap_flag() << ", bit15=" << unused_bit
                    << ")";
    }
 
  private:
    static constexpr auto make_from_fields(u32np mt, u8np r, bool gap,
                                           bool mtov, bool invalid, u16np adc)
        -> bh_spc600_4096ch_event {
        auto const flags = (u8np(u8(gap)) << 6) | (u8np(u8(mtov)) << 5) |
                           (u8np(u8(invalid)) << 4);
        return bh_spc600_4096ch_event{{
            std::byte(u8np(adc).value()),
            std::byte((flags | (u8np(adc >> 8) & 0x0f_u8np)).value()),
            std::byte(u8np(mt >> 16).value()),
            std::byte(r.value()),
            std::byte(u8np(mt >> 0).value()),
            std::byte(u8np(mt >> 8).value()),
        }};
    }
};

struct bh_spc600_256ch_event {
    std::array<std::byte, 4> bytes;

    static constexpr u32 macrotime_overflow_period = 1 << 17;

    static constexpr bool has_markers = false;

    [[nodiscard]] constexpr auto adc_value() const noexcept -> u16np {
        return u16np(read_u8_at<0>(std::span(bytes)));
    }

    [[nodiscard]] constexpr auto routing_signals() const noexcept -> u8np {
        return (read_u8_at<3>(std::span(bytes)) & 0x0f_u8np) >> 1;
    }

    [[nodiscard]] constexpr auto macrotime() const noexcept -> u32np {
        auto const lo8 = u32np(read_u8_at<1>(std::span(bytes)));
        auto const mid8 = u32np(read_u8_at<2>(std::span(bytes)));
        auto const hi1 = u32np(read_u8_at<3>(std::span(bytes))) & 1_u32np;
        return lo8 | (mid8 << 8) | (hi1 << 16);
    }

    [[nodiscard]] static constexpr auto marker_flag() noexcept -> bool {
        return false;
    }

    [[nodiscard]] static constexpr auto marker_bits() noexcept -> u8np {
        return 0_u8np;
    }

    [[nodiscard]] constexpr auto gap_flag() const noexcept -> bool {
        return (read_u8_at<3>(std::span(bytes)) & (1_u8np << 5)) != 0_u8np;
    }

    [[nodiscard]] constexpr auto macrotime_overflow_flag() const noexcept
        -> bool {
        return (read_u8_at<3>(std::span(bytes)) & (1_u8np << 6)) != 0_u8np;
    }

    [[nodiscard]] constexpr auto invalid_flag() const noexcept -> bool {
        return (read_u8_at<3>(std::span(bytes)) & (1_u8np << 7)) != 0_u8np;
    }

    [[nodiscard]] constexpr auto
    is_multiple_macrotime_overflow() const noexcept -> bool {
        return macrotime_overflow_flag() && invalid_flag();
    }

    [[nodiscard]] constexpr auto
    multiple_macrotime_overflow_count() const noexcept -> u32np {
        return read_u32le_at<0>(std::span(bytes)) & 0x0fff'ffff_u32np;
    }

    static constexpr auto make_photon(u32np macrotime, u8np adc_value,
                                      u8np route,
                                      bool macrotime_overflow = false)
        -> bh_spc600_256ch_event {
        return make_from_fields(false, macrotime_overflow, false, route,
                                macrotime, adc_value);
    }

    static constexpr auto make_invalid_photon(u32np macrotime, u8np adc_value)
        -> bh_spc600_256ch_event {
        // N.B. No MTOV.
        return make_from_fields(true, false, false, 0_u8np, macrotime,
                                adc_value);
    }

    static constexpr auto make_multiple_macrotime_overflow(u32np count)
        -> bh_spc600_256ch_event {
        constexpr auto flags = 0b1100'0000_u8np;
        return bh_spc600_256ch_event{{
            std::byte(u8np(count >> 0).value()),
            std::byte(u8np(count >> 8).value()),
            std::byte(u8np(count >> 16).value()),
            std::byte((flags | (u8np(count >> 24) & 0x0f_u8np)).value()),
        }};
    }

    auto gap_flag(bool gap) noexcept -> bh_spc600_256ch_event & {
        static constexpr auto gap_bit = std::byte(0b0010'0000);
        bytes[3] = (bytes[3] & ~gap_bit) | (gap ? gap_bit : std::byte(0));
        return *this;
    }

    friend auto operator==(bh_spc600_256ch_event const &lhs,
                           bh_spc600_256ch_event const &rhs) noexcept
        -> bool = default;

    friend auto operator<<(std::ostream &strm, bh_spc600_256ch_event const &e)
        -> std::ostream & {
        bool const unused_bit =
            (read_u8_at<3>(std::span(e.bytes)) & (1_u8np << 4)) != 0_u8np;
        return strm << "bh_spc600_256ch(MT=" << e.macrotime()
                    << ", R=" << unsigned(e.routing_signals().value())
                    << ", ADC=" << e.adc_value()
                    << ", INVALID=" << e.invalid_flag()
                    << ", MTOV=" << e.macrotime_overflow_flag()
                    << ", GAP=" << e.gap_flag() << ", bit28=" << unused_bit
                    << ", CNT=" << e.multiple_macrotime_overflow_count()
                    << ")";
    }
 
  private:
    static constexpr auto make_from_fields(bool invalid, bool mtov, bool gap,
                                           u8np r, u32np mt, u8np adc)
        -> bh_spc600_256ch_event {
        auto const flags = (u8np(u8(invalid)) << 7) | (u8np(u8(mtov)) << 6) |
                           (u8np(u8(gap)) << 5);
        return bh_spc600_256ch_event{{
            std::byte(adc.value()),
            std::byte(u8np(mt).value()),
            std::byte(u8np(mt >> 8).value()),
            std::byte((flags | ((r << 1) & 0b1110_u8np) |
                       (u8np(mt >> 16) & 0x01_u8np))
                          .value()),
        }};
    }
};
 
namespace internal {
 
// Common implementation for decode_bh_spc*.
// BHEvent is the binary record event class.
template <typename NumericTraits, typename BHSPCEvent,
          bool HasIntensityCounter, typename Downstream>
    requires processor<Downstream, time_reached_event<NumericTraits>,
                       time_correlated_detection_event<NumericTraits>,
                       data_lost_event<NumericTraits>, warning_event> &&
             (handler_for<Downstream, bulk_counts_event<NumericTraits>> ||
              not HasIntensityCounter) &&
             (handler_for<Downstream, marker_event<NumericTraits>> ||
              not BHSPCEvent::has_markers)
class decode_bh_spc {
    static_assert(
        same_as_any_of<BHSPCEvent, bh_spc_event, bh_spc600_256ch_event,
                       bh_spc600_4096ch_event>);
 
    // 32-bit abstime can work for a few seconds, though 64-bit is recommended.
    static_assert(sizeof(typename NumericTraits::abstime_type) >= 4);
 
    static_assert(std::in_range<typename NumericTraits::channel_type>(255) ||
                  (not std::is_same_v<BHSPCEvent, bh_spc600_4096ch_event> &&
                   std::in_range<typename NumericTraits::channel_type>(15)));
 
    static_assert(std::in_range<typename NumericTraits::difftime_type>(4095) ||
                  (std::is_same_v<BHSPCEvent, bh_spc600_256ch_event> &&
                   std::in_range<typename NumericTraits::difftime_type>(255)));
 
    static_assert(std::in_range<typename NumericTraits::count_type>(4095) ||
                  not HasIntensityCounter);
 
    using abstime_type = NumericTraits::abstime_type;
 
    abstime_type abstime_base = 0; // Time of last overflow
 
    Downstream downstream;
 
    LIBTCSPC_NOINLINE void issue_warning(char const *message) {
        downstream.handle(warning_event{message});
    }
 
    void handle_bh(BHSPCEvent const &event) {
        if (event.is_multiple_macrotime_overflow()) {
            abstime_base +=
                abstime_type(BHSPCEvent::macrotime_overflow_period) *
                event.multiple_macrotime_overflow_count().value();
            if (event.gap_flag())
                downstream.handle(
                    data_lost_event<NumericTraits>{abstime_base});
            return downstream.handle(
                time_reached_event<NumericTraits>{abstime_base});
        }
 
        if (event.macrotime_overflow_flag())
            abstime_base += BHSPCEvent::macrotime_overflow_period;
        abstime_type const abstime = abstime_base + event.macrotime().value();
 
        if (event.gap_flag())
            downstream.handle(data_lost_event<NumericTraits>{abstime});
 
        if (not event.marker_flag()) {
            if (not event.invalid_flag()) { // Valid photon
                downstream.handle(
                    time_correlated_detection_event<NumericTraits>{
                        abstime, event.routing_signals().value(),
                        event.adc_value().value()});
            } else { // Invalid photon
                downstream.handle(time_reached_event<NumericTraits>{abstime});
            }
        } else {
            if (event.invalid_flag()) { // Marker
                auto const bits = u32np(event.marker_bits());
                if constexpr (HasIntensityCounter) {    // SPC-160, 180N
                    if ((bits & 0x01_u32np) != 0_u32np) // Marker 0
                        downstream.handle(bulk_counts_event<NumericTraits>{
                            abstime, -1, event.adc_value().value()});
                }
                if constexpr (BHSPCEvent::has_markers) {
                    for_each_set_bit(bits, [&](int b) {
                        downstream.handle(marker_event<NumericTraits>{
                            abstime,
                            static_cast<NumericTraits::channel_type>(b)});
                    });
                }
            } else {
                // Although not clearly documented, the combination of
                // INV=0, MARK=1 is not currently used.
                issue_warning(
                    "unexpected BH SPC event flags: marker bit set but invalid bit cleared");
            }
        }
    }
 
  public:
    explicit decode_bh_spc(Downstream downstream)
        : downstream(std::move(downstream)) {}
 
    [[nodiscard]] auto introspect_node() const -> processor_info {
        return processor_info(this, "decode_bh_spc");
    }
 
    [[nodiscard]] auto introspect_graph() const -> processor_graph {
        return downstream.introspect_graph().push_entry_point(this);
    }
 
    template <typename Event>
        requires std::convertible_to<std::remove_cvref_t<Event>, BHSPCEvent>
    void handle(Event &&event) {
        handle_bh(event);
    }
 
    template <typename Event>
        requires(
            not std::convertible_to<std::remove_cvref_t<Event>, BHSPCEvent> and
            handler_for<Downstream, std::remove_cvref_t<Event>>)
    void handle(Event &&event) {
        downstream.handle(std::forward<Event>(event));
    }
 
    void flush() { downstream.flush(); }
};
 
} // namespace internal

template <typename NumericTraits = default_numeric_traits, typename Downstream>
auto decode_bh_spc(Downstream downstream) {
    return internal::decode_bh_spc<NumericTraits, bh_spc_event, false,
                                   Downstream>(std::move(downstream));
}

template <typename NumericTraits = default_numeric_traits, typename Downstream>
auto decode_bh_spc_with_intensity_counter(Downstream downstream) {
    return internal::decode_bh_spc<NumericTraits, bh_spc_event, true,
                                   Downstream>(std::move(downstream));
}

template <typename NumericTraits = default_numeric_traits, typename Downstream>
auto decode_bh_spc600_4096ch(Downstream downstream) {
    return internal::decode_bh_spc<NumericTraits, bh_spc600_4096ch_event,
                                   false, Downstream>(std::move(downstream));
}

template <typename NumericTraits = default_numeric_traits, typename Downstream>
auto decode_bh_spc600_256ch(Downstream downstream) {
    return internal::decode_bh_spc<NumericTraits, bh_spc600_256ch_event, false,
                                   Downstream>(std::move(downstream));
}
 
} // namespace tcspc