MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Sorter.hpp
Go to the documentation of this file.
1#pragma once
2
6
7#include "SortingHelper.hpp"
8
9/**
10 * @file Sorter.hpp
11 * @brief Modern, digital-first sorting framework for Maya Flux
12 *
13 * The Sorter system provides a clean, extensible foundation for data sorting
14 * in the Maya Flux ecosystem. Unlike traditional sorting which operates on simple containers,
15 * this embraces the digital paradigm: data-driven workflows, composability, and type safety.
16 *
17 * ## Core Philosophy
18 * A sorter **organizes ComputeData** through digital-first approaches:
19 * 1. **Algorithmic sorting:** Advanced mathematical operations, not simple comparisons
20 * 2. **Multi-dimensional sorting:** N-dimensional sort keys, not just single values
21 * 3. **Temporal sorting:** Sort based on time-series patterns, predictions
22 * 4. **Cross-modal sorting:** Sort audio by visual features, video by audio, etc.
23 * 5. **Computational sorting:** Leverage digital capabilities beyond analog metaphors
24 *
25 * ## Key Features
26 * - **Flexible input/output:** Template-based I/O types defined at instantiation
27 * - **Type-safe sorting:** C++20 concepts and compile-time guarantees
28 * - **Sorting strategies:** Algorithmic, pattern-based, predictive
29 * - **Composable operations:** Integrates with ComputeMatrix execution modes
30 * - **Digital-first design:** Embraces computational possibilities beyond analog metaphors
31 *
32 * ## Usage Examples
33 * ```cpp
34 * // Sort DataVariant containing vectors
35 * auto sorter = std::make_shared<MySorter<Kakshya::DataVariant>>();
36 *
37 * // Sort regions by custom criteria
38 * auto region_sorter = std::make_shared<MySorter<
39 * std::vector<Kakshya::Region>,
40 * std::vector<Kakshya::Region>>>();
41 *
42 * // Sort with mathematical transformation
43 * auto matrix_sorter = std::make_shared<MySorter<
44 * Eigen::MatrixXd,
45 * Eigen::MatrixXd>>();
46 * ```
47 */
48
49namespace MayaFlux::Yantra {
50
51/**
52 * @enum SortingType
53 * @brief Categories of sorting operations for discovery and organization
54 */
55enum class SortingType : uint8_t {
56 STANDARD, ///< Traditional comparison-based sorting
57 ALGORITHMIC, ///< Mathematical/computational sorting algorithms
58 PATTERN_BASED, ///< Sort based on pattern recognition
59 TEMPORAL, ///< Time-series aware sorting
60 SPATIAL, ///< Multi-dimensional spatial sorting
61 PREDICTIVE, ///< ML/AI-based predictive sorting
62 CROSS_MODAL, ///< Sort one modality by features of another
63 RECURSIVE, ///< Recursive/hierarchical sorting
64 CUSTOM ///< User-defined sorting types
65};
66
67/**
68 * @enum SortingStrategy
69 * @brief Sorting execution strategies
70 */
71enum class SortingStrategy : uint8_t {
72 IN_PLACE, ///< Sort data in-place (modifies input)
73 COPY_SORT, ///< Create sorted copy (preserves input)
74 INDEX_ONLY, ///< Generate sort indices only
75 PARTIAL_SORT, ///< Sort only top-K elements
76 LAZY_SORT, ///< Lazy evaluation sorting (future: coroutines)
77 CHUNKED_SORT, ///< Sort in chunks for large datasets
78 PARALLEL_SORT ///< Parallel/concurrent sorting
79};
80
81/**
82 * @struct SorterConfig
83 * @brief Parent of every sorter's config struct.
84 *
85 * Holds no settings. Each sorter's config struct adds the fields that sorter reads,
86 * and is stored whole, keyed by type, in the operation's facets.
87 */
90
92
93/**
94 * @class Sorter
95 * @brief Template-flexible sorter base with instance-defined I/O types
96 *
97 * The Sorter provides a clean, concept-based foundation for all sorting
98 * operations. I/O types are defined at instantiation time, providing maximum flexibility
99 * while maintaining type safety through C++20 concepts.
100 *
101 * Unlike traditional sorters that only handle simple containers, this embraces the
102 * digital paradigm with analyzer delegation, cross-modal sorting, and computational
103 * approaches that go beyond analog metaphors.
104 */
105template <ComputeData InputType = std::vector<Kakshya::DataVariant>, ComputeData OutputType = InputType>
106class Sorter : public ComputeOperation<InputType, OutputType> {
107public:
111
112 virtual ~Sorter() = default;
113
114 /**
115 * @brief Gets the sorting type category for this sorter
116 * @return SortingType enum value
117 */
118 [[nodiscard]] virtual SortingType get_sorting_type() const = 0;
119
120 /**
121 * @brief Gets human-readable name for this sorter
122 * @return String identifier for the sorter
123 */
124 [[nodiscard]] std::string get_name() const override
125 {
126 return get_sorter_name();
127 }
128
129 [[nodiscard]] OperationType get_operation_type() const override
130 {
132 }
133
134 [[nodiscard]] ConfigRefs configs() const override
135 {
136 return this->stored_configs(Supports<SorterConfig> {});
137 }
138
139protected:
140 /**
141 * @brief Core operation implementation - called by ComputeOperation interface
142 * @param input Input data with metadata
143 * @return Output data with metadata
144 */
146 {
147 return sort_implementation(input);
148 }
149
150 /**
151 * @brief Pure virtual sorting implementation - derived classes implement this
152 * @param input Input data with metadata
153 * @return Sorted output
154 */
155 virtual output_type sort_implementation(const input_type& input) = 0;
156
157 /**
158 * @brief Get sorter-specific name (derived classes override this)
159 * @return Sorter name string
160 */
161 [[nodiscard]] virtual std::string get_sorter_name() const { return "Sorter"; }
162
163 /**
164 * @brief Input validation (override for custom validation logic)
165 */
166 virtual bool validate_sorting_input(const input_type& /*input*/) const
167 {
168 // Default: accept any input that satisfies ComputeData concept
169 return true;
170 }
171};
172
173/// Sorter that takes DataVariant and produces DataVariant
174template <ComputeData OutputType = std::vector<Kakshya::DataVariant>>
176
177/// Sorter for signal container processing
178template <ComputeData OutputType = std::shared_ptr<Kakshya::SignalSourceContainer>>
180
181/// Sorter for region-based sorting
182template <ComputeData OutputType = Kakshya::Region>
184
185/// Sorter for region group processing
186template <ComputeData OutputType = Kakshya::RegionGroup>
188
189/// Sorter for segment processing
190template <ComputeData OutputType = std::vector<Kakshya::RegionSegment>>
192
193/// Sorter that produces Eigen matrices
194template <ComputeData InputType = std::vector<Kakshya::DataVariant>>
196
197/// Sorter that produces Eigen vectors
198template <ComputeData InputType = std::vector<Kakshya::DataVariant>>
200
201/// Sorter for vector containers
202template <typename T, ComputeData OutputType = std::vector<std::vector<T>>>
204
205/// Sorter for indices generation
206template <ComputeData InputType = std::vector<Kakshya::DataVariant>>
208
209// ============================================================================
210// UNIVERSAL COMPUTE DATA FUNCTIONS
211// ============================================================================
212
213} // namespace MayaFlux::Yantra
214#include "Sorter.describe.hpp"
#define MF_DESCRIBE(...)
Requests a generated member description for a struct at namespace scope.
Definition Describe.hpp:14
ConfigRefs stored_configs(Supports< Configs... >) const
The stored configs among those listed, in listed order.
ComputeOperation()
Constructor with data type validation warnings.
virtual bool validate_sorting_input(const input_type &) const
Input validation (override for custom validation logic).
Definition Sorter.hpp:166
virtual output_type sort_implementation(const input_type &input)=0
Pure virtual sorting implementation - derived classes implement this.
virtual ~Sorter()=default
ConfigRefs configs() const override
The base view of the config structs this operation holds.
Definition Sorter.hpp:134
virtual std::string get_sorter_name() const
Get sorter-specific name (derived classes override this).
Definition Sorter.hpp:161
output_type operation_function(const input_type &input) override
Core operation implementation - called by ComputeOperation interface.
Definition Sorter.hpp:145
virtual SortingType get_sorting_type() const =0
Gets the sorting type category for this sorter.
OperationType get_operation_type() const override
Returns the category of this operation for grammar and registry discovery.
Definition Sorter.hpp:129
std::string get_name() const override
Gets human-readable name for this sorter.
Definition Sorter.hpp:124
Template-flexible sorter base with instance-defined I/O types.
Definition Sorter.hpp:106
Sorter< InputType, std::vector< std::vector< size_t > > > IndexSorter
Sorter for indices generation.
Definition Sorter.hpp:207
@ TEMPORAL
Time-based patterns, onset detection.
Definition Analyzer.hpp:36
@ CUSTOM
User-defined analysis types.
Definition Analyzer.hpp:41
@ SPATIAL
Multi-dimensional geometric analysis.
Definition Analyzer.hpp:37
@ RECURSIVE
Recursive/nested extraction.
Definition Extractor.hpp:53
@ PATTERN_BASED
Extract based on pattern recognition.
Definition Extractor.hpp:51
Sorter< Kakshya::RegionGroup, OutputType > RegionGroupSorter
Sorter for region group processing.
Definition Sorter.hpp:187
Sorter< InputType, Eigen::MatrixXd > MatrixSorter
Sorter that produces Eigen matrices.
Definition Sorter.hpp:195
OperationType
Operation categories for organization and discovery.
SortingStrategy
Sorting execution strategies.
Definition Sorter.hpp:71
@ LAZY_SORT
Lazy evaluation sorting (future: coroutines).
Definition Sorter.hpp:76
@ PARTIAL_SORT
Sort only top-K elements.
Definition Sorter.hpp:75
@ IN_PLACE
Sort data in-place (modifies input).
Definition Sorter.hpp:72
@ COPY_SORT
Create sorted copy (preserves input).
Definition Sorter.hpp:73
@ CHUNKED_SORT
Sort in chunks for large datasets.
Definition Sorter.hpp:77
@ PARALLEL_SORT
Parallel/concurrent sorting.
Definition Sorter.hpp:78
@ INDEX_ONLY
Generate sort indices only.
Definition Sorter.hpp:74
Sorter< InputType, Eigen::VectorXd > VectorSorter
Sorter that produces Eigen vectors.
Definition Sorter.hpp:199
Sorter< std::vector< std::vector< T > >, OutputType > VectorContainerSorter
Sorter for vector containers.
Definition Sorter.hpp:203
SortingType
Categories of sorting operations for discovery and organization.
Definition Sorter.hpp:55
@ CROSS_MODAL
Sort one modality by features of another.
Definition Sorter.hpp:62
@ STANDARD
Traditional comparison-based sorting.
Definition Sorter.hpp:56
@ PREDICTIVE
ML/AI-based predictive sorting.
Definition Sorter.hpp:61
@ ALGORITHMIC
Mathematical/computational sorting algorithms.
Definition Sorter.hpp:57
Sorter< std::shared_ptr< Kakshya::SignalSourceContainer >, OutputType > ContainerSorter
Sorter for signal container processing.
Definition Sorter.hpp:179
Sorter< Kakshya::Region, OutputType > RegionSorter
Sorter for region-based sorting.
Definition Sorter.hpp:183
Sorter< std::vector< Kakshya::RegionSegment >, OutputType > SegmentSorter
Sorter for segment processing.
Definition Sorter.hpp:191
Sorter< std::vector< Kakshya::DataVariant >, OutputType > DataSorter
Sorter that takes DataVariant and produces DataVariant.
Definition Sorter.hpp:175
std::vector< std::reference_wrapper< const OperationConfig > > ConfigRefs
Borrowed views of the configs an operation holds.
Input/Output container for computation pipeline data flow with structure preservation.
Definition DataIO.hpp:63
Parent of every sorter's config struct.
Definition Sorter.hpp:88
The config structs an operation class accepts, declared as using supports.