From 75662eb35133eea6cec26974b7818686f78b9e68 Mon Sep 17 00:00:00 2001 From: Paul Brossier Date: Thu, 24 Jan 2019 00:24:14 +0100 Subject: [PATCH] [batchnorm] add basic documentation, shuffle declarations to match usage order --- src/ai/batchnorm.h | 137 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 124 insertions(+), 13 deletions(-) diff --git a/src/ai/batchnorm.h b/src/ai/batchnorm.h index 6c0e44f4..8d389a54 100644 --- a/src/ai/batchnorm.h +++ b/src/ai/batchnorm.h @@ -21,10 +21,6 @@ #ifndef AUBIO_BATCHNORM_H #define AUBIO_BATCHNORM_H -#ifdef __cplusplus -extern "C" { -#endif - /** \file Batch normalization layer. @@ -38,27 +34,142 @@ extern "C" { */ +#ifdef __cplusplus +extern "C" { +#endif + +/** batch normalization layer */ typedef struct _aubio_batchnorm_t aubio_batchnorm_t; +/** create a new batch normalization layer + + This layer takes no parameters. The number of output channels will be + determined as the inner-most dimension of the input tensor when calling + ::aubio_batchnorm_get_output_shape. + +*/ aubio_batchnorm_t *new_aubio_batchnorm(void); -void aubio_batchnorm_do(aubio_batchnorm_t *t, - aubio_tensor_t *input_tensor, - aubio_tensor_t *activations); +/** get output shape of the layer -uint_t aubio_batchnorm_set_gamma(aubio_batchnorm_t *t, fvec_t *gamma); -uint_t aubio_batchnorm_set_beta(aubio_batchnorm_t *t, fvec_t *beta); -uint_t aubio_batchnorm_set_moving_mean(aubio_batchnorm_t *t, fvec_t *moving_mean); -uint_t aubio_batchnorm_set_moving_variance(aubio_batchnorm_t *t, fvec_t *moving_variance); + \param t ::aubio_batchnorm_t layer + \param input input tensor + \param shape output shape + + This function determines the number of output channels required and allocate + the vectors of weights. The ouptut shape of this layer is identical to the + input shape. + +*/ +uint_t aubio_batchnorm_get_output_shape(aubio_batchnorm_t *t, + aubio_tensor_t *input, uint_t *shape); +/** get a pointer to the gamma vector + + \param t ::aubio_batchnorm_t layer + + \return pointer to `fvec_t` holding the gamma parameters + + When called after ::aubio_batchnorm_get_output_shape, this function will + return a pointer to the vector allocated to hold the `gamma` weights. + + A NULL pointer will be returned if ::aubio_batchnorm_get_output_shape has not + been called yet. + +*/ fvec_t *aubio_batchnorm_get_gamma(aubio_batchnorm_t *t); + +/** get a pointer to the beta vector + + \param t ::aubio_batchnorm_t layer + + \return pointer to `fvec_t` holding the beta parameters +*/ fvec_t *aubio_batchnorm_get_beta(aubio_batchnorm_t *t); + +/** get a pointer to the moving mean vector + + \param t ::aubio_batchnorm_t layer + + \return pointer to `fvec_t` holding the moving mean parameters + +*/ fvec_t *aubio_batchnorm_get_moving_mean(aubio_batchnorm_t *t); + +/** get a pointer to the moving variance vector + + \param t ::aubio_batchnorm_t layer + + \return pointer to `fvec_t` holding the moving variance parameters + +*/ fvec_t *aubio_batchnorm_get_moving_variance(aubio_batchnorm_t *t); -uint_t aubio_batchnorm_get_output_shape(aubio_batchnorm_t *t, - aubio_tensor_t *input, uint_t *shape); +/** set gamma vector of batchnorm layer + + \param t ::aubio_batchnorm_t layer + \param gamma ::fvec_t containing the weights + + \return 0 on success, non-zero otherwise. + + This function will copy the content of an existing vector into + the corresponding vector of weights in `t`. + + Note: to spare a copy and load directly the data in `t`, + ::aubio_batchnorm_get_gamma can be used instead. + +*/ +uint_t aubio_batchnorm_set_gamma(aubio_batchnorm_t *t, fvec_t *gamma); + +/** set beta vector of a batchnorm layer + + \param t ::aubio_batchnorm_t layer + \param beta ::fvec_t containing the weights + + \return 0 on success, non-zero otherwise. + +*/ +uint_t aubio_batchnorm_set_beta(aubio_batchnorm_t *t, fvec_t *beta); + +/** set moving mean vector of batchnorm layer + \param t ::aubio_batchnorm_t layer + \param moving_mean ::fvec_t containing the weights + + \return 0 on success, non-zero otherwise. + +*/ +uint_t aubio_batchnorm_set_moving_mean(aubio_batchnorm_t *t, + fvec_t *moving_mean); + +/** set moving variance vector of batchnorm layer + + \param t ::aubio_batchnorm_t layer + \param moving_variance ::fvec_t containing the weights + + \return 0 on success, non-zero otherwise. + +*/ +uint_t aubio_batchnorm_set_moving_variance(aubio_batchnorm_t *t, + fvec_t *moving_variance); + +/** compute batch normalization layer + + \param t ::aubio_batchnorm_t layer + \param input_tensor input tensor + \param activations output tensor + + \return 0 on success, non-zero otherwise. + +*/ +void aubio_batchnorm_do(aubio_batchnorm_t *t, aubio_tensor_t *input_tensor, + aubio_tensor_t *activations); + +/** delete batch normalization layer + + \param t ::aubio_batchnorm_t layer to delete + +*/ void del_aubio_batchnorm(aubio_batchnorm_t *t); #ifdef __cplusplus -- 2.11.0