time_correlate.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 "arg_wrappers.hpp"
#include "common.hpp"
#include "data_types.hpp"
#include "int_arith.hpp"
#include "introspect.hpp"
#include "processor.hpp"
#include "time_tagged_events.hpp"
 
#include <array>
#include <cmath>
#include <stdexcept>
#include <type_traits>
#include <utility>
 
namespace tcspc {
 
namespace internal {
 
// For now, we only support setting the emitted event's abstime to the start
// time, stop time, or midpoint. For CFD-like usage, it is potentially useful
// to split the time in arbitrary ratios other than 1:1; this could be
// supported, but probably should use a run-time floating point ratio, given
// that the ratio would be something experimentally determined and not a simple
// integer ratio.
 
template <typename DataTypes, bool UseStartTimeAndChannel, typename Downstream>
class time_correlate_at_start_or_stop {
    static_assert(
        processor<Downstream, time_correlated_detection_event<DataTypes>>);
 
    Downstream downstream;
 
  public:
    explicit time_correlate_at_start_or_stop(Downstream downstream)
        : downstream(std::move(downstream)) {}
 
    [[nodiscard]] auto introspect_node() const -> processor_info {
        return processor_info(this, "time_correlate_at_start_or_stop");
    }
 
    [[nodiscard]] auto introspect_graph() const -> processor_graph {
        return downstream.introspect_graph().push_entry_point(this);
    }
 
    template <typename DT>
    void handle(std::array<detection_event<DT>, 2> const &event) {
        static_assert(std::is_same_v<typename DT::abstime_type,
                                     typename DataTypes::abstime_type>);
        static_assert(std::is_same_v<typename DT::channel_type,
                                     typename DataTypes::channel_type>);
        auto const &anchor = UseStartTimeAndChannel ? event[0] : event[1];
        auto const difftime =
            convert_with_check<typename DataTypes::difftime_type>(
                subtract_with_check(event[1].abstime, event[0].abstime));
        downstream.handle(time_correlated_detection_event<DataTypes>{
            anchor.abstime, anchor.channel, difftime});
    }
 
    template <typename DT>
    // NOLINTNEXTLINE(cppcoreguidelines-rvalue-reference-param-not-moved)
    void handle(std::array<detection_event<DT>, 2> &&event) {
        handle(static_cast<std::array<detection_event<DT>, 2> const &>(event));
    }
 
    template <typename OtherEvent>
        requires handler_for<Downstream, std::remove_cvref_t<OtherEvent>>
    void handle(OtherEvent &&event) {
        downstream.handle(std::forward<OtherEvent>(event));
    }
 
    void flush() { downstream.flush(); }
};
 
template <typename DataTypes, bool UseStartChannel, typename Downstream>
class time_correlate_at_midpoint {
    static_assert(
        processor<Downstream, time_correlated_detection_event<DataTypes>>);
 
    Downstream downstream;
 
  public:
    explicit time_correlate_at_midpoint(Downstream downstream)
        : downstream(std::move(downstream)) {}
 
    [[nodiscard]] auto introspect_node() const -> processor_info {
        return processor_info(this, "time_correlate_at_midpoint");
    }
 
    [[nodiscard]] auto introspect_graph() const -> processor_graph {
        return downstream.introspect_graph().push_entry_point(this);
    }
 
    template <typename DT>
    void handle(std::array<detection_event<DT>, 2> const &event) {
        static_assert(std::is_same_v<typename DT::abstime_type,
                                     typename DataTypes::abstime_type>);
        static_assert(std::is_same_v<typename DT::channel_type,
                                     typename DataTypes::channel_type>);
        auto const difftime =
            subtract_with_check(event[1].abstime, event[0].abstime);
        auto const abstime = event[0].abstime + difftime / 2;
        auto const channel =
            UseStartChannel ? event[0].channel : event[1].channel;
        downstream.handle(time_correlated_detection_event<DataTypes>{
            abstime, channel,
            convert_with_check<typename DataTypes::difftime_type>(difftime)});
    }
 
    template <typename DT>
    // NOLINTNEXTLINE(cppcoreguidelines-rvalue-reference-param-not-moved)
    void handle(std::array<detection_event<DT>, 2> &&event) {
        handle(static_cast<std::array<detection_event<DT>, 2> const &>(event));
    }
 
    template <typename OtherEvent>
        requires handler_for<Downstream, std::remove_cvref_t<OtherEvent>>
    void handle(OtherEvent &&event) {
        downstream.handle(std::forward<OtherEvent>(event));
    }
 
    void flush() { downstream.flush(); }
};
 
template <typename DataTypes, bool UseStartChannel, typename Downstream>
class time_correlate_at_fraction {
    static_assert(
        processor<Downstream, time_correlated_detection_event<DataTypes>>);
 
    double frac; // 0.0-1.0 for internal division of start-stop
    Downstream downstream;
 
  public:
    explicit time_correlate_at_fraction(arg::fraction<double> fraction,
                                        Downstream downstream)
        : frac(fraction.value), downstream(std::move(downstream)) {
        if (frac < 0.0 || frac > 1.0)
            throw std::invalid_argument(
                "time_correlate_at_fraction fraction must be in range [0.0, 1.0]");
    }
 
    [[nodiscard]] auto introspect_node() const -> processor_info {
        return processor_info(this, "time_correlate_at_fraction");
    }
 
    [[nodiscard]] auto introspect_graph() const -> processor_graph {
        return downstream.introspect_graph().push_entry_point(this);
    }
 
    template <typename DT>
    void handle(std::array<detection_event<DT>, 2> const &event) {
        static_assert(std::is_same_v<typename DT::abstime_type,
                                     typename DataTypes::abstime_type>);
        static_assert(std::is_same_v<typename DT::channel_type,
                                     typename DataTypes::channel_type>);
        auto const difftime =
            subtract_with_check(event[1].abstime, event[0].abstime);
        auto const abstime =
            event[0].abstime +
            static_cast<typename DataTypes::abstime_type>(
                std::llround(static_cast<double>(difftime) * frac));
        auto const channel =
            UseStartChannel ? event[0].channel : event[1].channel;
        downstream.handle(time_correlated_detection_event<DataTypes>{
            abstime, channel,
            convert_with_check<typename DataTypes::difftime_type>(difftime)});
    }
 
    template <typename DT>
    // NOLINTNEXTLINE(cppcoreguidelines-rvalue-reference-param-not-moved)
    void handle(std::array<detection_event<DT>, 2> &&event) {
        handle(static_cast<std::array<detection_event<DT>, 2> const &>(event));
    }
 
    template <typename OtherEvent>
        requires handler_for<Downstream, std::remove_cvref_t<OtherEvent>>
    void handle(OtherEvent &&event) {
        downstream.handle(std::forward<OtherEvent>(event));
    }
 
    void flush() { downstream.flush(); }
};
 
} // namespace internal

template <typename DataTypes = default_data_types, typename Downstream>
auto time_correlate_at_start(Downstream downstream) {
    return internal::time_correlate_at_start_or_stop<DataTypes, true,
                                                     Downstream>(
        std::move(downstream));
}

template <typename DataTypes = default_data_types, typename Downstream>
auto time_correlate_at_stop(Downstream downstream) {
    return internal::time_correlate_at_start_or_stop<DataTypes, false,
                                                     Downstream>(
        std::move(downstream));
}

template <typename DataTypes = default_data_types,
          bool UseStartChannel = false, typename Downstream>
auto time_correlate_at_midpoint(Downstream downstream) {
    return internal::time_correlate_at_midpoint<DataTypes, UseStartChannel,
                                                Downstream>(
        std::move(downstream));
}

template <typename DataTypes = default_data_types,
          bool UseStartChannel = false, typename Downstream>
auto time_correlate_at_fraction(arg::fraction<double> fraction,
                                Downstream downstream) {
    return internal::time_correlate_at_fraction<DataTypes, UseStartChannel,
                                                Downstream>(
        fraction, std::move(downstream));
}
 
namespace internal {
 
template <typename DataTypes, typename Downstream> class negate_difftime {
    static_assert(
        processor<Downstream, time_correlated_detection_event<DataTypes>>);
 
    Downstream downstream;
 
  public:
    explicit negate_difftime(Downstream downstream)
        : downstream(std::move(downstream)) {}
 
    [[nodiscard]] auto introspect_node() const -> processor_info {
        return processor_info(this, "negate_difftime");
    }
 
    [[nodiscard]] auto introspect_graph() const -> processor_graph {
        return downstream.introspect_graph().push_entry_point(this);
    }
 
    template <typename DT>
    void handle(time_correlated_detection_event<DT> const &event) {
        static_assert(std::is_same_v<typename DT::difftime_type,
                                     typename DataTypes::difftime_type>);
        static_assert(
            std::is_signed_v<typename DT::difftime_type>,
            "difftime_type of time_correlated_detection_event used with negate_difftime must be a signed integer type");
        time_correlated_detection_event<DT> copy(event);
        copy.difftime =
            static_cast<typename DT::difftime_type>(-event.difftime);
        downstream.handle(std::move(copy));
    }
 
    template <typename DT>
    // NOLINTNEXTLINE(cppcoreguidelines-rvalue-reference-param-not-moved)
    void handle(time_correlated_detection_event<DT> &&event) {
        handle(
            static_cast<time_correlated_detection_event<DT> const &>(event));
    }
 
    template <typename OtherEvent>
        requires handler_for<Downstream, std::remove_cvref_t<OtherEvent>>
    void handle(OtherEvent &&event) {
        downstream.handle(std::forward<OtherEvent>(event));
    }
 
    void flush() { downstream.flush(); }
};
 
template <typename DataTypes, typename Downstream>
class remove_time_correlation {
    static_assert(processor<Downstream, detection_event<DataTypes>>);
 
    Downstream downstream;
 
  public:
    explicit remove_time_correlation(Downstream downstream)
        : downstream(std::move(downstream)) {}
 
    [[nodiscard]] auto introspect_node() const -> processor_info {
        return processor_info(this, "remove_time_correlation");
    }
 
    [[nodiscard]] auto introspect_graph() const -> processor_graph {
        return downstream.introspect_graph().push_entry_point(this);
    }
 
    template <typename DT>
    void handle(time_correlated_detection_event<DT> const &event) {
        static_assert(std::is_same_v<typename DT::abstime_type,
                                     typename DataTypes::abstime_type>);
        static_assert(std::is_same_v<typename DT::channel_type,
                                     typename DataTypes::channel_type>);
 
        downstream.handle(
            detection_event<DataTypes>{event.abstime, event.channel});
    }
 
    template <typename DT>
    // NOLINTNEXTLINE(cppcoreguidelines-rvalue-reference-param-not-moved)
    void handle(time_correlated_detection_event<DT> &&event) {
        handle(
            static_cast<time_correlated_detection_event<DT> const &>(event));
    }
 
    template <typename OtherEvent>
        requires handler_for<Downstream, std::remove_cvref_t<OtherEvent>>
    void handle(OtherEvent &&event) {
        downstream.handle(std::forward<OtherEvent>(event));
    }
 
    void flush() { downstream.flush(); }
};
 
} // namespace internal

template <typename DataTypes = default_data_types, typename Downstream>
auto negate_difftime(Downstream downstream) {
    return internal::negate_difftime<DataTypes, Downstream>(
        std::move(downstream));
}

template <typename DataTypes = default_data_types, typename Downstream>
auto remove_time_correlation(Downstream downstream) {
    return internal::remove_time_correlation<DataTypes, Downstream>(
        std::move(downstream));
}
 
} // namespace tcspc