# package bls12-381

Library

Module

Module type

Parameter

Class

Class type

`include Ff_sig.PRIME`

`include Ff_sig.BASE`

`exception Not_in_field of Bytes.t`

`val order : Z.t`

The order of the finite field

`val zero : t`

The neutral element for the addition

`val one : t`

The neutral element for the multiplication

`val is_zero : t -> bool`

`is_zero x`

returns `true`

if `x`

is the neutral element for the addition

`val is_one : t -> bool`

`is_one x`

returns `true`

if `x`

is the neutral element for the multiplication

`val random : ?state:Random.State.t -> unit -> t`

Use carefully! `random ()`

returns a random element of the field. A state for the PRNG can be given to initialize the PRNG in the requested state. If no state is given, no initialisation is performed

`val non_null_random : ?state:Random.State.t -> unit -> t`

Use carefully! `non_null_random ()`

returns a non null random element of the field. A state for the PRNG can be given to initialize the PRNG in the requested state. If no state is given, no initialisation is performed

`negate x`

returns `-x mod order`

. Equivalently, `negate x`

returns the unique `y`

such that `x + y mod order = 0`

Construct a value of type `t`

from the bytes representation in little endian of the field element. For non prime fields, the encoding starts with the coefficient of the constant monomial. Raise `Not_in_field`

if the bytes do not represent an element in the field.

From a predefined little endian bytes representation, construct a value of type `t`

. The same representation than `of_bytes_exn`

is used. Return `None`

if the bytes do not represent an element in the field.

Convert the value t to a bytes representation. The number of bytes is `size_in_bytes`

and the encoding must be in little endian. For instance, the encoding of `1`

in prime fields is always a bytes sequence of size `size_in_bytes`

starting with the byte `0b00000001`

. For non prime fields, the encoding starts with the coefficient of the constant monomial.

`val factor_power_of_two : int * Z.t`

Returns `s, q`

such that `order - 1 = 2^s * q`

`val of_string : string -> t`

Create a value t from a predefined string representation. It is not required that to_string of_string t = t. By default, decimal representation of the number is used, modulo the order of the field

`val to_string : t -> string`

String representation of a value t. It is not required that to_string of_string t = t. By default, decimal representation of the number is used

`of_z x`

builds an element t from the Zarith element `x`

. `mod order`

is applied if `x >= order`

`to_z x`

builds a Zarith element, using the decimal representation. Arithmetic on the result can be done using the modular functions on integers

Returns the Legendre symbol of the parameter. Note it does not work for `p = 2`

`val is_quadratic_residue : t -> bool`

`is_quadratic_residue x`

returns `true`

if `x`

is a quadratic residue i.e. if there exists `n`

such that `n^2 mod p = 1`

`val check_bytes : Bytes.t -> bool`

Check if a point, represented as a byte array, is in the field *

`fft ~domain ~points`

performs a Fourier transform on `points`

using `domain`

The domain should be of the form `w^{i}`

where `w`

is a principal root of unity. If the domain is of size `n`

, `w`

must be a `n`

-th principal root of unity. The number of points can be smaller than the domain size, but not larger. The complexity is in `O(n log(m))`

where `n`

is the domain size and `m`

the number of points. A new array of size `n`

is allocated and is returned. The parameters are not modified.

`fft_inplace ~domain ~points`

performs a Fourier transform on `points`

using `domain`

The domain should be of the form `w^{i}`

where `w`

is a principal root of unity. If the domain is of size `n`

, `w`

must be a `n`

-th principal root of unity. The number of points must be in the same size than the domain. It does not return anything but modified the points directly. It does only perform one allocation of a scalar for the FFT. It is recommended to use this function if side-effect is acceptable.

`ifft ~domain ~points`

performs an inverse Fourier transform on `points`

using `domain`

. The domain should be of the form `w^{-i}`

(i.e the "inverse domain") where `w`

is a principal root of unity. If the domain is of size `n`

, `w`

must be a `n`

-th principal root of unity. The domain size must be exactly the same than the number of points. The complexity is O(n log(n)) where `n`

is the domain size. A new array of size `n`

is allocated and is returned. The parameters are not modified.

`ifft_inplace ~domain ~points`

is the same than `ifft`

but modifies the array `points`

instead of returning a new array

`add_inplace res a b`

is the same than `add`

but writes the result in `res`

. No allocation happens.

`sub_inplace res a b`

is the same than `sub`

but writes the result in `res`

. No allocation happens.

`mul_inplace res a b`

is the same than `sub`

but writes the result in `res`

. No allocation happens.

`inverse_exn_inplace res a`

is the same than `inverse_exn`

but writes the result in `res`

. No allocation happens.

`double_inplace res a`

is the same than `double`

but writes the result in `res`

. No allocation happens.

`square_inplace res a`

is the same than `square`

but writes the result in `res`

. No allocation happens.

`negate_inplace res a`

is the same than `negate`

but writes the result in `res`

. No allocation happens.

`add_bulk xs`

returns the sum of the elements of `xs`

by performing only one allocation for the output. This method is recommended to save the allocation overhead of using `n`

times `add`

.

`mul_bulk xs`

returns the product of the elements of `xs`

by performing only one allocation for the output. This method is recommended to save the allocation overhead of using `n`

times `mul`

.

`compare a b`

compares the elements `a`

and `b`

based on their bytes representation

`inner_product_exn a b`

returns the inner product of `a`

and `b`

, i.e. `sum(a_i * b_i)`

. Raise `Invalid_argument`

if the arguments are not of the same length. Only two allocations are used.

Same than `inner_product_exn`

but returns an option instead of raising an exception.

`val of_int : int -> t`

`of_int x`

is equivalent to `of_z (Z.of_int x)`

. If `x`

is is negative, returns the element `order - |x|`

.