Trait Field

Source

pub trait Field:
    Algebra<Self, Output = Self::Packing, Output = Self::Packing, Output = Self::Packing>
    + RawDataSerializable
    + Packable
    + 'static
    + Copy
    + Div<Output = Self>
    + DivAssign
    + Add<Self::Packing>
    + Sub<Self::Packing>
    + Mul<Self::Packing>
    + Eq
    + Hash
    + Send
    + Sync
    + Display
    + Serialize
    + DeserializeOwned {
    type Packing: PackedField<Scalar = Self>;

    const GENERATOR: Self;
    const BENEFITS_FROM_LOCKSTEP_EVALUATION: bool = false;

    // Required methods
    fn try_inverse(&self) -> Option<Self>;
    fn order() -> BigUint;

    // Provided methods
    fn is_zero(&self) -> bool { ... }
    fn is_one(&self) -> bool { ... }
    fn inverse(&self) -> Self { ... }
    fn try_sqrt(&self) -> Option<Self> { ... }
    fn interpolation_node(i: usize) -> Self { ... }
    fn add_slices(slice_1: &mut [Self], slice_2: &[Self]) { ... }
    fn batched_columnwise_dot_product<EF, R, I, const N: usize>(
        acc: &mut [<EF as ExtensionField<Self>>::ExtensionPacking],
        items: I,
    )
       where EF: ExtensionField<Self>,
             R: Iterator<Item = Self::Packing>,
             I: Iterator<Item = (R, [EF; N])> { ... }
    fn bits() -> usize { ... }
}

Expand description

A field F. This permits both modular fields ℤ/p along with their field extensions.

A ring is a field if every element x has a unique multiplicative inverse x^{-1} which satisfies x * x^{-1} = F::ONE.

Required Associated Constants§

Source

const GENERATOR: Self

A generator of this field’s multiplicative group.

Provided Associated Constants§

Source

const BENEFITS_FROM_LOCKSTEP_EVALUATION: bool = false

Whether evaluating multiple packed vectors of this field in lockstep (to overlap independent dependency chains and hide packed-multiplication latency) is expected to help throughput for this field.

Only p3_uni_stark::quotient_values’s aarch64 (neon)-gated path reads this constant; on every other target it has no effect, so leaving it at the default is always safe there.

Defaults to false, so fields fail safe into the plain (non-lockstep) path unless explicitly measured to benefit. Override to true only once benchmarks confirm the field’s packed multiplication is latency-bound enough for lockstep evaluation to help.

Required Associated Types§

Source

type Packing: PackedField<Scalar = Self>

Required Methods§

Source

fn try_inverse(&self) -> Option<Self>

The multiplicative inverse of this field element, if it exists.

NOTE: The inverse of 0 is undefined and will return None.

Source

fn order() -> BigUint

The number of elements in the field.

This will either be prime if the field is a PrimeField or a power of a prime if the field is an extension field.

Provided Methods§

Source

fn is_zero(&self) -> bool

Check if the given field element is equal to the unique additive identity (ZERO).

Source

fn is_one(&self) -> bool

Check if the given field element is equal to the unique multiplicative identity (ONE).

Source

fn inverse(&self) -> Self

The multiplicative inverse of this field element.

§Panics

The function will panic if the field element is 0. Use try_inverse if you want to handle this case.

Source

fn try_sqrt(&self) -> Option<Self>

A square root of this field element, if one exists.

Returns Some(r) with r * r == *self when this element is a quadratic residue, and None when it is a quadratic non-residue. ZERO returns Some(ZERO). When two square roots exist, which one is returned is unspecified.

The default implementation uses the Tonelli–Shanks algorithm. Fields with a more direct formula (e.g. those with |F| ≡ 3 mod 4) may override it.

Source

fn interpolation_node(i: usize) -> Self

The i-th element of a fixed injective enumeration of Self, used as an interpolation node. Must satisfy interpolation_node(0) == ZERO and interpolation_node(1) == ONE, and be injective for every i below the size of the field — no enumeration can do better, and a field smaller than the degree of the polynomial being interpolated is unusable for that protocol anyway. Round-polynomial degrees are tiny, so 0..min(64, |Self|) is the tested range.

The default maps i through the prime subfield and is injective only while i is below the characteristic. Fields of characteristic below 2^32 must override it.

Source

fn add_slices(slice_1: &mut [Self], slice_2: &[Self])

Add two slices of field elements together, returning the result in the first slice.

Makes use of packing to speed up the addition.

This is optimal for cases where the two slices are small to medium length. E.g. between F::Packing::WIDTH and roughly however many elements fit in a cache line.

For larger slices, it’s likely worthwhile to use parallelization before calling this. Similarly if you need to add a large number of slices together, it’s best to break them into small chunks and call this on the smaller chunks.

§Panics

The function will panic if the lengths of the two slices are not equal.

Source

fn batched_columnwise_dot_product<EF, R, I, const N: usize>( acc: &mut [<EF as ExtensionField<Self>>::ExtensionPacking], items: I, )
where EF: ExtensionField<Self>, R: Iterator<Item = Self::Packing>, I: Iterator<Item = (R, [EF; N])>,

Accumulate acc[c * N + j] += scales[j] * row[c] over a stream of packed rows.

Each item provides one matrix row as acc.len() / N packed base-field words, together with the row’s N extension-field weights. acc is laid out with the N weights of each word group adjacent, and its length must be a multiple of N.

This is the inner kernel of batched columnwise (weighted-sum-of-rows) dot products. Fields may override it to defer modular reductions across rows.

Source