Changeset 7f270f8 for src/ai/batchnorm.h

Timestamp:

Dec 29, 2021, 5:52:00 PM (3 years ago)

Author:

Paul Brossier <piem@piem.org>

Branches:

feature/crepe

Children:

e7779f0

Parents:

e75bd80

git-author:

Paul Brossier <piem@piem.org> (01/24/19 00:24:14)

git-committer:

Paul Brossier <piem@piem.org> (12/29/21 17:52:00)

Message:

[batchnorm] add basic documentation, shuffle declarations to match usage order

File:

• src/ai/batchnorm.h (modified) (2 diffs)

src/ai/batchnorm.h

@@ -22 +22 @@
 #define AUBIO_BATCHNORM_H
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /** \file
 
@@ -39 +35 @@
 */
 
+#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
 
-fvec_t *aubio_batchnorm_get_gamma(aubio_batchnorm_t *t);
-fvec_t *aubio_batchnorm_get_beta(aubio_batchnorm_t *t);
-fvec_t *aubio_batchnorm_get_moving_mean(aubio_batchnorm_t *t);
-fvec_t *aubio_batchnorm_get_moving_variance(aubio_batchnorm_t *t);
+  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);
+
+/** 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);