Add streaming filter support for conv1d, resample_poly, channelize_poly (#1209)

* Add streaming filter support for conv1d, resample_poly, channelize_poly

Add Conv1DStream, ResamplePolyStream, and ChannelizePolyStream objects
that filter arbitrarily long signals delivered in segments. Segments of
any size are supplied via feed() and a final flush() emits the trailing
outputs and ends the stream. The concatenated outputs match the
corresponding one-shot transform. Objects are created with the
make_*_stream() factories and support CUDA and host executors.

Each object retains only a small history buffer between calls, and
feed()/flush() write into a caller-provided output buffer sized once
via max_output(), so no allocation occurs during streaming. conv1d
supports FULL/SAME/VALID modes. To support the internal windowed
one-shot calls, the resample_poly and channelize_poly transforms and
kernels gain output-window offset parameters.

See examples/streaming.cu and the API Reference section Signal and
Image Processing / Streaming for usage and per-transform caveats.
Tests cover one-shot equivalence across filter/segment configurations,
varying segment schedules, end-of-stream semantics, and host executors.

Signed-off-by: Thomas Benson <tbenson@nvidia.com>

Author: tbensonatl

docs_input/api/signalimage/index.rst

@@ -10,3 +10,4 @@ Signal and Image Processing
    filtering/index.rst
    general/index.rst
    radar/index.rst
+   streaming/index.rst

docs_input/api/signalimage/streaming/channelize_poly_stream.rst

@@ -0,0 +1,33 @@
+.. _make_channelize_poly_stream_func:
+
+make_channelize_poly_stream
+===========================
+
+Streaming polyphase channelizer: channelize a signal delivered in segments,
+equivalent to a one-shot :ref:`channelize_poly <channelize_poly_func>` over
+the concatenated stream
+
+.. versionadded:: 1.1.0
+
+.. doxygenstruct:: matx::ChannelizePolyStreamParams
+   :members:
+
+.. doxygenfunction:: matx::make_channelize_poly_stream
+
+.. doxygenclass:: matx::ChannelizePolyStream
+   :members:
+
+Examples
+~~~~~~~~
+
+.. literalinclude:: ../../../../examples/streaming.cu
+   :language: cpp
+   :start-after: example-begin channelize_poly_stream-1
+   :end-before: example-end channelize_poly_stream-1
+   :dedent:
+
+.. literalinclude:: ../../../../examples/streaming.cu
+   :language: cpp
+   :start-after: example-begin channelize_poly_stream-2
+   :end-before: example-end channelize_poly_stream-2
+   :dedent:

docs_input/api/signalimage/streaming/conv1d_stream.rst

@@ -0,0 +1,37 @@
+.. _make_conv1d_stream_func:
+
+make_conv1d_stream
+==================
+
+Streaming 1D convolution: filter a signal delivered in segments. The concatenated
+output equals a one-shot :ref:`conv1d <conv1d_func>` over the whole stream when the
+total signal length is at least the filter length. For shorter signals one-shot
+conv1d swaps the operand roles, while the streaming object keeps the signal and
+filter roles fixed and returns the input-aligned result. FULL mode is
+role-symmetric and matches for any length. The convolution uses the direct
+(time-domain) method, which limits the filter to 1024 taps.
+
+.. versionadded:: 1.1.0
+
+.. doxygenstruct:: matx::Conv1DStreamParams
+   :members:
+
+.. doxygenfunction:: matx::make_conv1d_stream
+
+.. doxygenclass:: matx::Conv1DStream
+   :members:
+
+Examples
+~~~~~~~~
+
+.. literalinclude:: ../../../../examples/streaming.cu
+   :language: cpp
+   :start-after: example-begin conv1d_stream-1
+   :end-before: example-end conv1d_stream-1
+   :dedent:
+
+.. literalinclude:: ../../../../examples/streaming.cu
+   :language: cpp
+   :start-after: example-begin conv1d_stream-2
+   :end-before: example-end conv1d_stream-2
+   :dedent:

docs_input/api/signalimage/streaming/index.rst

@@ -0,0 +1,32 @@
+.. _streaming:
+
+Streaming
+#########
+
+Streaming objects process arbitrarily long signals delivered in segments. An
+object is constructed once via its ``make_*_stream()`` factory, then fed
+segments of any (possibly varying) size with ``feed()``. A final ``flush()`` is called
+at the end of the stream to emit any trailing outputs. ``flush()`` ends the stream:
+further ``flush()`` calls return 0, and ``feed()`` throws until
+``reset()`` starts a new stream. The concatenation of the
+produced outputs equals a single one-shot call of the corresponding transform
+over the whole signal, with a few caveats as documented for each streaming object.
+Each object owns only a small history buffer that scales with the filter and some
+object parameters (e.g., the downsampling factor for ``resample_poly``). No object-owned
+allocation scales directly with the segment size.
+All work runs asynchronously on the executor bound at construction.
+
+The canonical pattern sizes one reusable output buffer with
+``max_output(largest_input_segment_size)`` and passes it to every ``feed()`` and
+``flush()`` call. Each call writes its outputs to the front of that buffer and
+returns the number written (which may be 0). Consume the produced region
+``slice(out, {0}, {count})`` before reusing the buffer. Note that zero-sized slices
+are not valid, so check ``count > 0`` before creating and using the slice.
+This pattern prevents any dynamic memory allocation for the outputs during the streaming operation.
+See ``examples/streaming.cu`` for complete programs.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

docs_input/api/signalimage/streaming/resample_poly_stream.rst

@@ -0,0 +1,33 @@
+.. _make_resample_poly_stream_func:
+
+make_resample_poly_stream
+=========================
+
+Streaming polyphase resampler: resample a signal delivered in segments,
+equivalent to a one-shot :ref:`resample_poly <resample_poly_func>` over the
+concatenated stream
+
+.. versionadded:: 1.1.0
+
+.. doxygenstruct:: matx::ResamplePolyStreamParams
+   :members:
+
+.. doxygenfunction:: matx::make_resample_poly_stream
+
+.. doxygenclass:: matx::ResamplePolyStream
+   :members:
+
+Examples
+~~~~~~~~
+
+.. literalinclude:: ../../../../examples/streaming.cu
+   :language: cpp
+   :start-after: example-begin resample_poly_stream-1
+   :end-before: example-end resample_poly_stream-1
+   :dedent:
+
+.. literalinclude:: ../../../../examples/streaming.cu
+   :language: cpp
+   :start-after: example-begin resample_poly_stream-2
+   :end-before: example-end resample_poly_stream-2
+   :dedent:

docs_input/executor_compatibility.rst

@@ -140,6 +140,9 @@ fused JIT expression; non-JIT CUDA execution through cudaExecutor remains availa
    "log2", "|yes|", "|yes|", "|yes|", "Element-wise expression."
    "logspace", "|yes|", "|yes|", "|yes|", "Generator expression."
    "lu", "|yes|", "|yes|", "|yes|", "Host support requires the CPU solver backend. CUDAJITExecutor supports cuSolverDx-backed lazy projections for supported types and shapes."
+   "make_channelize_poly_stream", "|yes|", "|yes|", "|no|", "Streaming (segmented) polyphase channelizer object; feeds segments through the one-shot channelize_poly over a retained history. Host and CUDA executors; the streaming object is a stateful driver, not a JIT-fusable expression."
+   "make_conv1d_stream", "|yes|", "|yes|", "|no|", "Streaming (segmented) 1D convolution object built on the direct conv1d; host and CUDA executors. The direct method limits the filter to 1024 taps. The streaming object is a stateful driver, not a JIT-fusable expression."
+   "make_resample_poly_stream", "|yes|", "|yes|", "|no|", "Streaming (segmented) polyphase resampler object; feeds segments through the one-shot resample_poly over a retained history. Host and CUDA executors; the streaming object is a stateful driver, not a JIT-fusable expression."
    "matmul", "|yes|", "|yes|", "|yes|", "Host support requires the CPU BLAS backend and supported floating or complex types. CUDAJITExecutor support uses cuBLASDx through MathDx for supported runtime shapes, precisions, layouts, and block-size intersections."
    "matrix_norm", "|partial|", "|yes|", "|no|", "Reduction transform; host execution is available but reductions are not generally parallelized across host threads."
    "matvec", "|yes|", "|yes|", "|yes|", "Host support requires the CPU BLAS backend and supported floating or complex types. CUDAJITExecutor support follows cuBLASDx matmul constraints."

examples/CMakeLists.txt

@@ -21,7 +21,8 @@ set(examples
     svd_power
     qr
     black_scholes
-    print_styles)
+    print_styles
+    streaming)