CUSTOMIZATION OF DECODING

OVERVIEW

It is easy to control what algorithms are used by decoding, for example if you want to replace unvariate polynomial multiplication with your own function or if the ring you are implementing has caracteristic 2.

DESCRIPTION

TYPE AND NAME OF A RING

The two macros defined below control the name of the ring and the C type used to represent its elements. These macros are at the disposal of the end-user.

#define R Name: R contains the name Name of the ring you are implementing. See decoding-rings(3) for details.
#define RING_NAME Name: RING_NAME contains the name you want to give the ring you are using. It must a valid C type identifier as it will be used by you and decoding to designate the C type corresponding the the ring you want to use. See decoding-alphabets(3) for more details.

MACROS THAT CONTROL OPTIMIZATIONS

The file include/decoding/rings/GF5.c is an example of how to use macros defined below. We first list all the macros concerning the behavior of the ring. When these macros are defined certain optimizations are done by decoding. These macros are at the disposal of the library developpers but can be used by the end-user if he knows what he is doing.

#define RING_COMM: Indicates that the ring is commutative.
#define RING_CHAR_UMA: Indicates that the characteristic of the ring can hold within a uma integer.
#define RING_CHAR_MPZ: Indicates that the characteristic of the ring cannot hold, a priori within a uma integer. If it is the case then R_uma_char will be -1 otherwise R_uma_char must hold the characteristic of the ring even if RING_CHAR_MPZ defined.
#define RING_CHAR2: Indicates that the ring has characteristic 2.
#define RING_FF: Indicates that the ring is in fact a finite field.
#define RING_MODN_WORD: Tell decoding that the ring is Z/nZ where n holds within a machine word. It can corresponds, for example, to the unsigned char, unsigned short, unsigned int or unsigned long C type. The WORD_TYPE macro must be defined to the C type that represents the elements of your ring.
#define RING_CHAR2_WORD: Tell decoding that the ring is F_{2^n} where n holds within a machine word. It can corresponds, for example, to the unsigned char, unsigned short, unsigned int or unsigned long C type. The WORD_TYPE macro must be defined to the C type that represents the elements of your ring.

MACROS FOR FUNCTION REPLACEMENT

Each macro below can be used so that the user supplies his own function in place of the one provided by decoding. For example if the end-user wants to use his own univariate polynomial multiplication algorithm, he can use the MY_UPOL_MUL macro.

#include <decoding/rings/some_ring.c>

#define MY_UPOL_MUL my_super_multiplication
void my_super_multiplication(R *r,R *a,uma na,R *b,uma nb) {
  /* my super multiplication function */
}

#include <decoding/algos.c>

int main(void) {
  /* some stuff */
  return 0;
}

All the following macros are to be used as follows.

#define MACRO myfunc

In the above example MACRO is a macro listed below and myfunc is the name of the end-user's function which is to be used. See decoding-lowlevels(3) for the prototype that must have myfunc. The following macros are at the disposal of the end-user.

MY_UPOL_EVAL for replacing ll_upol_eval.
MY_UPOL_MUL for replacing ll_upol_mul.
MY_UPOL_SQUARE for replacing ll_upol_square.
MY_UPOL_PTHROOT for replacing ll_upol_pthroot.
MY_UPOL_SHIFT for replacing ll_upol_shift.
MY_UPOL_QUOREM for replacing ll_upol_quorem.
MY_UPOL_QUO for replacing ll_upol_quo.
MY_UPOL_REM for replacing ll_upol_rem.
MY_UPOL_GCD for replacing ll_upol_gcd.
MY_UPOL_EEA for replacing ll_upol_eea.
MY_UPOL_PARTIAL_EEA for replacing ll_upol_partial_eea.
MY_UPOL_INTERPOLATION for replacing ll_upol_interpolation.
MY_UPOL_ROOTS_FQ for replacing ll_upol_roots_fq.
MY_UPOL_ROOTS for replacing ll_upol_roots.
MY_UPOL_POW_MOD for replacing ll_upol_pow_mod.
MY_UPOL_POW_MOD_UMA for replacing ll_upol_pow_mod_uma.
MY_UPOL_DERIVATIVE for replacing ll_upol_derivative.
MY_UPOL_DIV_BY_AFFINE for replacing ll_upol_div_by_affine.
MY_DBPOL_MUL for replacing ll_dbpol_mul.
MY_DBPOL_SHIFT for replacing ll_dbpol_shift.
MY_DBPOL_XROOTS for replacing ll_dbpol_Xroots.
MY_VEC_ADD for replacing ll_vec_add.
MY_VEC_NEG for replacing ll_vec_neg.
MY_VEC_SUB for replacing ll_vec_sub.
MY_VEC_SUB_SUB for replacing ll_vec_sub_sub.
MY_VEC_ADD_MUL for replacing ll_vec_add_mul.
MY_VEC_MUL_BY_CTE for replacing ll_vec_mul_by_cte.
MY_VEC_ADD_MUL_BY_CTE for replacing ll_vec_add_mul_by_cte.
MY_VEC_SUB_MUL for replacing ll_vec_sub_mul.
MY_VEC_PROD for replacing ll_vec_prod.

MEMORY MANAGEMENT

Decoding provides no garbage collectors by default. The memory is manually allocated and freed with the standard libc functions stdlib.h(0P). You can replace the memory management functions with your own or use an external garbage collector if you wish with the MY_*ALLOC macros.

#define MY_MALLOC myfunc: Replace the malloc function by myfunc. By default the libc malloc is used. myfunc must have the same prototype as malloc. See malloc(3) for more details.
#define MY_REALLOC myfunc: Replace the realloc function by myfunc. By default the libc realloc is used. myfunc must have the same prototype as realloc. See realloc(3) for more details.
#define MY_CALLOC myfunc: Replace the calloc function by myfunc. By default the libc calloc is used. myfunc must have the same prototype as calloc. See calloc(3) for more details.
#define MY_FREE myfunc: Replace the free function by myfunc. By default the libc free is used. myfunc must have the same prototype as free. See free(3) for more details.

AUTHOR

Written by Guillaume Quintin (coincoin169g@gmail.com).