zn api

Spqlios ZN-arithmetic api

The spqlios arithmetic library provides fast vector x prepared matrix products over int32 matrices (mod $2^{32}$).

Summary of main modules

Elementary operations

/** @brief obtain a z-module info: currently, only DEFAULT mode is supported
    delete with delete_rnx_module_info */
EXPORT MOD_Z* new_z_module_info(Z_MODULE_TYPE mode);

TN32_APPROXDEC_GADGET* new_tn32_approxdec_gadget(
    const MOD_Z* module,
    uint64_t k, uint64_t ell, // base 2^k, and size
);

/** @brief sets res = gadget_decompose(a) (int8_t* output) */
void zn8_approxdec_from_tnx32(
    const MOD_Z* module,                  // N
    const TN32_APPROXDEC_GADGET* gadget,  // gadget
    int8_t* res, uint64_t res_size,       // res (in general, size ell.a_size)
    const int32_t* a, uint64_t a_size     // a
);
/** @brief sets res = gadget_decompose(a) (int16_t* output) */
void zn16_approxdec_from_tnx32(<same>);
/** @brief sets res = gadget_decompose(a) (int32_t* output) */
void zn32_approxdec_from_tnx32(<same>);

Vector-matrix products (vmp)

1. Allocate the space for a pmat matrix to the right dimension

   /** @brief allocates a prepared matrix (release with delete_zn32_vmp_pmat) */
   ZN32_VMP_PMAT* new_zn32_vmp_pmat(
       const MOD_Z* module,              // N
       uint64_t nrows, uint64_t ncols);  // dimensions
   
   // it also is possible to use a standard allocation function: 
   // malloc/free, new int8_t[...]/delete[],
   // or spqlios_alloc/spqlios_free
   // in this case, the number of bytes to allocate are: 
   
   /** @brief number of bytes in a RNX_VMP_PMAT (for manual allocation) */
   uint64_t bytes_of_zn32_vmp_pmat(
       const MOD_Z* module,           // N
       uint64_t nrows, uint64_t ncols); // dimensions

2. Prepare the matrix

   /** @brief prepares a vmp matrix (contiguous row-major version) */
   void zn32_vmp_prepare_contiguous(
       const MOD_Z* module,
       ZN32_VMP_PMAT* pmat,                                   // output
       const uint32_t* mat, uint64_t nrows, uint64_t ncols);  // a

3. Execute a vector matrix product

   /** @brief applies a vmp product (int32_t* input) */
   void zn32_vmp_apply_a32(
       const MOD_Z* module,                                         // N
       int32_t* res, uint64_t res_size, uint64_t res_sl,            // res
       const int32_t* a, uint64_t a_size, uint64_t a_sl,            // a
       const ZN32_VMP_PMAT* pmat, uint64_t nrows, uint64_t ncols);  // prep matrix
   
   /** @brief applies a vmp product (int16_t* input) */
   void zn32_vmp_apply_a16(<same>);
   /** @brief applies a vmp product (int8_t* input) */
   void zn32_vmp_apply_a8(<same>);

   It is possible to use dimensions a_size <= nrows and res_size <= ncols. If the dimensions are smaller, this function will do a product with a submatrix.