RelationOperators.hpp

Go to the documentation of this file.

#pragma once
 
#include "NetworkOperator.hpp"
 
#include "MayaFlux/Kinesis/Stochastic/Weights.hpp"
#include "MayaFlux/Nodes/Network/NodeNetwork.hpp"
#include "MayaFlux/Nodes/Network/RelationSlot.hpp"
 
namespace MayaFlux::Nodes::Network {
 
class RelationNetwork;
 
/**
 * @class Source
 * @brief Anything that can supply a number when evaluated
 *
 * The right-hand side of a mapping wherever an operator parameter should be
 * drivable by whatever is at hand:
 * - A constant returns itself.
 * - A node returns its get_last_output().
 * - A NodeNetwork plus an index returns that network's
 *   get_node_output(index), or 0.0 if it has nothing there. Works the same
 *   whether the network is this RelationNetwork or any other NodeNetwork.
 * - A callable is invoked on whichever thread evaluates the source, so it
 *   follows the same rules as a node hook on the audio thread.
 */
class Source {
public:
    using Function = std::function<double()>;
 
    Source(double constant)
        : m_value(constant)
    {
    }
 
    template <std::derived_from<Node> NodeType>
    Source(std::shared_ptr<NodeType> node)
        : m_value(std::shared_ptr<Node>(std::move(node)))
    {
    }
 
    /**
     * @brief One indexed output of a NodeNetwork
     * @param network Read through get_node_output(index) on every evaluate()
     * @param index Position within network, the same index
     *              NodeNetwork::map_parameter's ONE_TO_ONE mode and
     *              apply_one_to_one() read
     */
    template <std::derived_from<NodeNetwork> NetworkType>
    Source(std::shared_ptr<NetworkType> network, size_t index)
        : m_value(NetworkIndex { .network = std::shared_ptr<NodeNetwork>(std::move(network)), .index = index })
    {
    }
 
    template <typename Callable>
        requires(!std::same_as<std::remove_cvref_t<Callable>, Source>
            && std::is_invocable_r_v<double, Callable&>)
    Source(Callable&& callable)
        : m_value(Function(std::forward<Callable>(callable)))
    {
    }
 
    /**
     * @brief Current value
     * @return The constant, the node's last output, the network index's
     *         output, or the callable's result. Zero for an empty node, a
     *         network index the network has no value for, or an empty
     *         callable.
     */
    [[nodiscard]] double evaluate() const
    {
        if (const auto* constant = std::get_if<double>(&m_value)) {
            return *constant;
        }
        if (const auto* node = std::get_if<std::shared_ptr<Node>>(&m_value)) {
            return *node ? (*node)->get_last_output() : 0.0;
        }
        if (const auto* index = std::get_if<NetworkIndex>(&m_value)) {
            return index->network ? index->network->get_node_output(index->index).value_or(0.0) : 0.0;
        }
        const auto& function = std::get<Function>(m_value);
        return function ? function() : 0.0;
    }
 
private:
    struct NetworkIndex {
        std::shared_ptr<NodeNetwork> network;
        size_t index;
    };
 
    std::variant<double, std::shared_ptr<Node>, NetworkIndex, Function> m_value;
};
 
/**
 * @class RelationOperator
 * @brief Operator that acts on a network's slots over one block at a time
 *
 * The network supplies the current slot storage through set_slots(), called
 * once when the operator is added and again at the start of every
 * process_batch(). An operator never caches a slot address past the current
 * cycle, since the network's slot storage can grow (and reallocate) between
 * cycles.
 *
 * A concrete operator has no generic initialize()/reset() lifecycle: it
 * sizes any internal state from its own constructor arguments.
 *
 * Once per block the host calls begin_block(), which applies mapped
 * parameters, then process(frames).
 *
 * An operator has no clock of its own; process_batch() is its only cadence.
 * Anything finer (per-sample or event-driven behavior) is composed from
 * outside: node hooks, tasks, or direct calls to the operator's own public
 * methods. An operator that acts only when called leaves process() empty.
 * Operators communicate through slots: level and activity writes, and
 * rendered blocks.
 *
 * An operator that publishes signals overrides publishes_output(),
 * get_output_count(), and get_output_block().
 */
class MAYAFLUX_API RelationOperator : public NetworkOperator {
public:
    /**
     * @brief Supply the current slot storage
     * @param slots RelationNetwork's slot storage, valid only for the caller's
     *              current cycle
     * @note Called by RelationNetwork::add() and at the start of every
     *       process_batch(). An operator is not usable before the first call.
     */
    void set_slots(std::vector<RelationSlot>& slots) noexcept { m_slots = &slots; }
 
    /**
     * @brief Apply mapped parameters at the start of a block
     */
    void begin_block()
    {
        for (const auto& binding : m_bindings) {
            set_parameter(binding.parameter, binding.source.evaluate());
        }
    }
 
    /**
     * @brief Drive an operator parameter from a source
     * @param parameter Name passed to set_parameter
     * @param source Evaluated once per block, at begin_block()
     *
     * A parameter has at most one mapping. Mapping it again replaces the
     * source. Must not run concurrently with begin_block().
     */
    void map(std::string parameter, Source source)
    {
        auto it = std::ranges::find(m_bindings, parameter, &Binding::parameter);
        if (it != m_bindings.end()) {
            it->source = std::move(source);
        } else {
            m_bindings.push_back({ .parameter = std::move(parameter), .source = std::move(source) });
        }
    }
 
    /**
     * @brief Remove the mapping of a parameter. No-op when absent.
     * @note Must not run concurrently with begin_block().
     */
    void unmap(std::string_view parameter)
    {
        std::erase_if(m_bindings, [&](const Binding& b) { return b.parameter == parameter; });
    }
 
    [[nodiscard]] virtual bool publishes_output() const { return false; }
    [[nodiscard]] virtual size_t get_output_count() const { return 0; }
    [[nodiscard]] virtual std::span<const double> get_output_block(size_t /*index*/) const { return {}; }
 
protected:
    [[nodiscard]] std::span<RelationSlot> slots() const noexcept
    {
        return m_slots ? std::span<RelationSlot>(*m_slots) : std::span<RelationSlot> {};
    }
 
private:
    struct Binding {
        std::string parameter;
        Source source;
    };
 
    std::vector<Binding> m_bindings;
    std::vector<RelationSlot>* m_slots { nullptr };
};
 
/**
 * @class StepOperator
 * @brief General operator whose body is a callable, run once per block
 *
 * Mapped parameters are stored by name and readable from the body through
 * parameter().
 *
 * @code
 * net->add<StepOperator>([](const std::shared_ptr<StepOperator>& self, std::span<RelationSlot> slots, uint32_t frames) {
 *     for (auto& slot : slots) {
 *         if (slot.level > self->parameter("limit")) {
 *             slot.set_active(false);
 *         }
 *     }
 * });
 * @endcode
 */
class MAYAFLUX_API StepOperator final : public RelationOperator, public std::enable_shared_from_this<StepOperator> {
public:
    using Body = std::function<void(const std::shared_ptr<StepOperator>& self, std::span<RelationSlot> slots, uint32_t frames)>;
 
    explicit StepOperator(Body body)
        : m_body(std::move(body))
    {
    }
 
    void process(float frames) override;
    void set_parameter(std::string_view param, double value) override;
    [[nodiscard]] std::optional<double> query_state(std::string_view query) const override;
    [[nodiscard]] std::string_view get_type_name() const override { return "Step"; }
 
    /**
     * @brief Value of a mapped or set parameter
     * @return The value, or 0.0 when the parameter was never set
     */
    [[nodiscard]] double parameter(std::string_view name) const;
 
private:
    Body m_body;
    std::map<std::string, double, std::less<>> m_parameters;
};
 
/**
 * @class AdvanceOperator
 * @brief Produces every slot's signal for the block
 *
 * For each slot with a node, advances it for the whole block through
 * extract_node_samples(). A slot without a node keeps its stored
 * level for every frame.
 *
 * @note Muting (slot.active == false) zeroes what gets published to the
 *       slot's block, but never its level: level always reflects the slot's
 *       real current value, muted or not. Gating a slot from its own level
 *       (an envelope follower, a threshold trigger) works as expected
 *       because of this.
 *
 * A node's hooks (on_impulse, on_phase_wrap, on_tick, ...) fire during this
 * advance, since set_node() enables them.
 *
 * Activity is read once per slot per block, at the start of process(). Place
 * AdvanceOperator after operators whose slot writes should apply this block,
 * and before DeriveOperator and CombineOperator, which read rendered blocks.
 */
class MAYAFLUX_API AdvanceOperator final : public RelationOperator {
public:
    void process(float frames) override;
 
    /** @note AdvanceOperator has no parameters. */
    void set_parameter(std::string_view /*param*/, double /*value*/) override { }
    [[nodiscard]] std::optional<double> query_state(std::string_view /*query*/) const override { return std::nullopt; }
    [[nodiscard]] std::string_view get_type_name() const override { return "Advance"; }
 
private:
    std::vector<double> m_scratch;
    size_t m_scratch_pos {};
};
 
/**
 * @class DeriveOperator
 * @brief Defines one slot's block as a function of other slots' blocks
 *
 * For each frame, calls the function with the input slots' values in the order
 * given and writes the result to the target slot's block. An input equal to
 * the target reads that slot's previous frame, or its previous block's last
 * value at frame 0. Place after AdvanceOperator.
 *
 * Three forms of rule:
 * - a plain function of the input values;
 * - a function of the input values and a coefficient array, which keeps the
 *   rule's state and can be retuned, saved and shared between rules;
 * - a boolean function of the input values and a coefficient array, such as
 *   the parallel kernels of Kinesis::Discrete (Boolean.hpp). The block holds
 *   0 or 1, and the target's activity follows the result, so its on_enter and
 *   on_leave callbacks fire on each change.
 *
 * Coefficients are parameters "c0", "c1", ...: map("c2", source) retunes
 * coefficient 2 at the start of every block.
 *
 * @code
 * namespace D = Kinesis::Discrete;
 * n->add<DeriveOperator>(2, std::vector<size_t> { 0, 1 }, D::comparator, D::comparator_state(0.2));
 * n->get_slot(2).on_enter.push_back([bell] { bell->excite(0.6); });
 * @endcode
 */
class MAYAFLUX_API DeriveOperator final : public RelationOperator {
public:
    using Function = std::function<double(std::span<const double>)>;
    using CoefFunction = std::function<double(std::span<const double>, std::span<double>)>;
 
    /**
     * @param target Index of the slot written
     * @param inputs Indices of the slots read
     * @param function Receives the input values of one frame
     */
    DeriveOperator(size_t target, std::vector<size_t> inputs, Function function);
 
    /**
     * @param target Index of the slot written
     * @param inputs Indices of the slots read
     * @param function Receives the input values of one frame and the coefficients
     * @param coefficients Starting coefficients, owned by this operator
     */
    DeriveOperator(size_t target, std::vector<size_t> inputs, CoefFunction function, std::vector<double> coefficients);
 
    /**
     * @param target Index of the slot written
     * @param inputs Indices of the slots read
     * @param function Callable returning exactly bool, taking the input values
     *                 of one frame as a const std::vector<double>& and the
     *                 coefficients as a std::span<double>
     * @param coefficients Starting coefficients, owned by this operator
     */
    template <typename Gate>
        requires(std::invocable<Gate&, const std::vector<double>&, std::span<double>>
            && std::same_as<std::invoke_result_t<Gate&, const std::vector<double>&, std::span<double>>, bool>)
    DeriveOperator(size_t target, std::vector<size_t> inputs, Gate function, std::vector<double> coefficients)
        : m_target(target)
        , m_inputs(std::move(inputs))
        , m_values(m_inputs.size(), 0.0)
        , m_coefficients(std::move(coefficients))
        , m_kernel([gate = std::move(function)](const std::vector<double>& values, std::span<double> coefs) {
            return gate(values, coefs) ? 1.0 : 0.0;
        })
        , m_gate(true)
    {
    }
 
    void process(float frames) override;
 
    /**
     * @brief Set one coefficient
     * @param param "c" followed by the coefficient's index, for example "c2".
     *              Anything else, or an index past the array, is ignored.
     */
    void set_parameter(std::string_view param, double value) override;
 
    /**
     * @return The coefficient named as in set_parameter(), or nullopt
     */
    [[nodiscard]] std::optional<double> query_state(std::string_view query) const override;
 
    [[nodiscard]] std::string_view get_type_name() const override { return "Derive"; }
 
    /**
     * @brief Replace the coefficient array
     * @note Must not run concurrently with process(); to retune during a
     *       block use map() or set_parameter() instead.
     */
    void set_coefficients(std::vector<double> coefficients) { m_coefficients = std::move(coefficients); }
 
    [[nodiscard]] const std::vector<double>& get_coefficients() const noexcept { return m_coefficients; }
 
private:
    using Kernel = std::function<double(const std::vector<double>&, std::span<double>)>;
 
    [[nodiscard]] static std::optional<size_t> coefficient_index(std::string_view param);
 
    size_t m_target;
    std::vector<size_t> m_inputs;
    std::vector<double> m_values;
    std::vector<double> m_coefficients;
    Kernel m_kernel;
    bool m_gate {};
};
 
/**
 * @class CombineOperator
 * @brief Turns slot blocks into published outputs
 *
 * Holds a slots-by-outputs table of weights, shareable through weights(), and
 * one block per output. Each
 * output is the weighted sum of slot values in that frame, or, when a combine
 * function is set on it, the function's result over all slot values of the
 * frame. Place after AdvanceOperator and DeriveOperator.
 *
 * Construction sets weight 1.0 from every slot to output 0 and zero
 * elsewhere. Weight cells may be written from any thread.
 *
 * @note weights() keeps the row count given at construction; it does not
 *       grow when the network's slot count does. A slot beyond that row
 *       count is simply left out of every output until weights()->assign()
 *       is called to match, which re-seeds every cell.
 */
class MAYAFLUX_API CombineOperator final : public RelationOperator {
public:
    /**
     * @class Output
     * @brief One published signal
     */
    class Output {
    public:
        using Function = std::function<double(std::span<const double>)>;
 
        /**
         * @brief Replace the weighted sum with a function of all slot values
         * @param function Called once per frame with the frame's slot values
         */
        void combine(Function function)
        {
            m_function = std::move(function);
        }
 
        /** @brief Return to the weighted sum */
        void clear_combine()
        {
            m_function = nullptr;
        }
 
        [[nodiscard]] bool has_combine() const noexcept { return static_cast<bool>(m_function); }
        [[nodiscard]] std::span<const double> block() const noexcept { return m_block; }
 
    private:
        friend class CombineOperator;
 
        Function m_function;
        std::vector<double> m_block;
    };
 
    /**
     * @param slot_count Number of slots of the host network
     * @param output_count Number of outputs published
     */
    explicit CombineOperator(size_t slot_count, size_t output_count = 1);
 
    /**
     * @brief Combine through a table shared with other operators
     * @param table Slot-to-output weights, one row per slot. Not re-seeded.
     *              One output is published per column.
     * @throws std::invalid_argument when table is null
     */
    explicit CombineOperator(std::shared_ptr<Kinesis::Stochastic::Weights> table);
 
    void process(float frames) override;
 
    /** @note CombineOperator has no parameters. */
    void set_parameter(std::string_view /*param*/, double /*value*/) override { }
    [[nodiscard]] std::optional<double> query_state(std::string_view /*query*/) const override { return std::nullopt; }
    [[nodiscard]] std::string_view get_type_name() const override { return "Combine"; }
 
    [[nodiscard]] bool publishes_output() const override { return true; }
    [[nodiscard]] size_t get_output_count() const override { return m_outputs.size(); }
    [[nodiscard]] std::span<const double> get_output_block(size_t index) const override;
 
    /**
     * @brief Slot-to-output weights, slot_count rows by output_count columns
     */
    [[nodiscard]] const std::shared_ptr<Kinesis::Stochastic::Weights>& weights() const noexcept { return m_weights; }
 
    /**
     * @brief One weight cell, readable and assignable from any thread
     * @param slot Row, the slot index
     * @param output Column, the output index
     * @throws std::out_of_range when slot or output lies outside the table.
     *         The row count is fixed at construction, so a slot added to the
     *         network afterwards has no row until weights()->assign().
     * @note The returned cell must not be kept across weights()->assign().
     */
    [[nodiscard]] Kinesis::Stochastic::Weights::Cell weight(size_t slot, size_t output);
 
    [[nodiscard]] Output& output(size_t index) { return m_outputs[index]; }
    [[nodiscard]] const Output& output(size_t index) const { return m_outputs[index]; }
 
private:
    std::shared_ptr<Kinesis::Stochastic::Weights> m_weights;
    std::vector<Output> m_outputs;
    std::vector<double> m_values;
};
 
} // namespace MayaFlux::Nodes::Network