reducemaps.lib

//############################# reducemaps.lib ###############################
// A library providing reduce/map operations in Faust. Its official prefix is
// `rm`. The basic idea behind _reduce_ operations is to combine several values
// into a single one by repeatedly applying a binary operation. A typical
// example is finding the maximum of a set of values by repeatedly applying the
// binary operation `max`.
//
// In this reducemaps library, you'll find two types of _reduce_, depending on
// whether you want to reduce n consecutive samples of the same signal or a set
// of n parallel signals.
//
// #### References
// * <https://github.com/grame-cncm/faustlibraries/blob/master/reducemaps.lib>
//#############################################################################

/************************************************************************
************************************************************************
FAUST library file
Copyright (C) 2023 Yann Orlarey
Copyright (C) 2010-2023 GRAME, Centre National de Creation Musicale
---------------------------------------------------------------------
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as 
published by the Free Software Foundation; either version 2.1 of the 
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with the GNU C Library; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA. 

EXCEPTION TO THE LGPL LICENSE : As a special exception, you may create a
larger FAUST program which directly or indirectly imports this library
file and still distribute the compiled code generated by the FAUST
compiler, or a modified version of this compiled code, under your own
copyright and license. This EXCEPTION TO THE LGPL LICENSE explicitly
grants you the right to freely choose the license for the resulting
compiled code. In particular the resulting compiled code has no obligation
to be LGPL or GPL. For example you are free to choose a commercial or
closed source license or any other license if you decide so.
************************************************************************
************************************************************************/

ba = library("basics.lib");

declare name "Reduce Library";
declare author "Yann Orlarey";
declare copyright "Grame and Yann Orlarey";
declare version "1.2.0";
declare license "LGPL with exception"; 



//----------------------------`(rm.)parReduce`--------------------------------
// `parReduce(op,N)` combines a set of `N` parallel signals into a single one
// using a binary operation `op`.
//
// With `parReduce`, this reduction process simultaneously occurs on each half
// of the incoming signals. In other words, `parReduce(max,256)` is equivalent
// to `parReduce(max,128),parReduce(max,128) : max`.
//
// To be used with `parReduce`, binary operation `op` must be associative.
// Additionally, the concept of a binary operation extends to operations
// that have `2*n` inputs and `n` outputs. For example, complex signals can be
// simulated using two signals for the real and imaginary parts. In
// such case, a binary operation would have 4 inputs and 2 outputs.
//
// Please note also that `parReduce` is faster than `topReduce` or `botReduce`
// for large number of signals. It is therefore the recommended operation
// whenever `op` is associative.
//
// #### Usage
//
// ```
// _,...,_ : parReduce(op, N) : _
// ```
//
// Where:
//
// * `op`: is a binary operation 
// * `N`: is the number of incomming signals (`N>0`). We use a capital letter
// here to indicate that the number of incomming signals must be constant and
// known at compile time.
//-----------------------------------------------------------------------------

parReduce(op,1) = par(i,outputs(op),_);
parReduce(op,2) = op;
parReduce(op,N) = parReduce(op,int(N/2)), parReduce(op,N-int(N/2)) : op;




//----------------------------`(rm.)topReduce`--------------------------------
// `topReduce(op,N)` involves combining a set of `N` parallel signals into a
// single one using a binary operation `op`. With `topReduce`, the reduction
// process starts from the top two incoming signals, down to the bottom. In
// other words, `topReduce(max,256)` is equivalent to `topReduce(max,255),_ : max`.
//
// Contrary to `parReduce`, the binary operation `op` doesn't have to be
// associative here. Like with `parReduce` the concept of a binary operation can be
// extended to operations that have 2*n inputs and n outputs. For example,
// complex signals can be simulated using two signals representing the real and
// imaginary parts. In such cases, a binary operation would have 4 inputs and 2
// outputs.
//
// #### Usage
//
// ```
//  _,...,_ : topReduce(op, N) : _
// ```
//
// Where:
//
// * `op`: is a binary operation
// * `N`: is the number of incomming signals (`N>0`). We use a capital letter
// here to indicate that the number of incomming signals must be constant and
// known at compile time.
//-----------------------------------------------------------------------------

topReduce(op,1) = par(i,outputs(op),_);
topReduce(op,2) = op;
topReduce(op,N) = topReduce(op,N-1), par(i,outputs(op),_) : op;



//----------------------------`(rm.)botReduce`--------------------------------
// `botReduce(op,N)` combines a set of `N` parallel signals into a single one
// using a binary operation `op`. With `botReduce`, the reduction process starts
// from the bottom two incoming signals, up to the top. In other words,
// `botReduce(max,256)` is equivalent to `_,botReduce(max,255): max`.
//
// Contrary to `parReduce`, the binary operation `op` doesn't have to be
// associative here. Like with `parReduce` the concept of a binary operation can be
// extended to operations that have 2*n inputs and n outputs. For example,
// complex signals can be simulated using two signals representing the real and
// imaginary parts. In such cases, a binary operation would have 4 inputs and 2
// outputs.
//
// #### Usage
//
// ```
//  _,...,_ : botReduce(op, N) : _
// ```
//
// Where:
//
// * op: is a binary operation
// * N: is the number of incomming signals (`N>0`). We use a capital letter
// here to indicate that the number of incomming signals must be constant and
// known at compile time.
//-----------------------------------------------------------------------------

botReduce(op,1) = par(i,outputs(op),_);
botReduce(op,2) = op;
botReduce(op,n) = par(i,outputs(op),_), botReduce(op,n-1) : op;


//--------------------------------`(rm.)reduce`--------------------------------
// Reduce a block of `n` consecutive samples of the incomming signal using a
// binary operation `op`. For example: `reduce(max,128)` will compute the
// maximun value of each block of 128 samples. Please note that the resulting
// value, while computed continuously, will be constant for the duration of a
// block. A new value is only produced at the end of a block. Note also that
// blocks should be of at least one sample (n>0).
//
// #### Usage
//
// ```
// _ : reduce(op, n) : _
// ```
//
// Where:
//
// * `op`: is a binary operation
// * `n`: is the number of consecutive samples in a block. 
//-----------------------------------------------------------------------------

reduce(op, n, x) = compute ~ (_,_,_) : (!,!,_)
    with {
        compute(acc, count, val) =
            ba.if(count<n, op(acc,x), x), // new acc
            ba.if(count<n, count+1, 1),   // new count
            ba.if(count<n, val, acc);     // new val
    };


//--------------------`(rm.)reducemap`---------------------------
// Like `reduce` but a `foo` function is applied to the result. From
// a mathematical point of view:
// `reducemap(op,foo,n)` is equivalent to `reduce(op,n):foo`
// but more efficient.
//
// #### Usage
//
// ```
// _ : reducemap(op, foo, n) : _
// ```
//
// Where:
//
// * `op`: is a binary operation
// * `foo`: is a function applied to the result of the reduction
// * `n`: is the number of consecutive samples in a block. 
//-----------------------------------------------------------------------------

reducemap(op, foo, n, x) = compute ~ (_,_,_) : (!,!,_)
    with {
        compute(acc, count, val) =
            ba.if(count<n, op(acc,x), x),   // new acc
            ba.if(count<n, count+1, 1),     // new count
            ba.if(count<n, val, foo(acc));  // new val
    };

// Some examples using `reduce`and `reducemap`
//
// the sum of the amplitudes of the input signal
sumn(n) = reduce(+,n);

// the maximum amplitude of the input signal
maxn(n) = reduce(max,n);

// the minimum amplitude of the input signal
minn(n) = reduce(min,n);

// the average amplitude of the input signal
mean(n) = reducemap(+, /(n), n);

// RMS
RMS(n) = float : ^(2) : reducemap(+, (/(n):sqrt), n);