### Example Search: std::vec

Source: https://docs.rs/decaf377/latest/decaf377/fields/index.html?search=

Demonstrates a basic search example for 'std::vec'.

```rust
std::vec
```

--------------------------------

### Example Search: Option<T> mapping

Source: https://docs.rs/decaf377/latest/decaf377/fields/index.html?search=

Demonstrates a search example for mapping a function over an 'Option<T>' type.

```rust
Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### Example Search: u32 to bool

Source: https://docs.rs/decaf377/latest/decaf377/fields/index.html?search=

Demonstrates a search example for type conversion from 'u32' to 'bool'.

```rust
u32 -> bool
```

--------------------------------

### Fq Small Multiplication Example

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/arkworks.rs.html

Shows a basic multiplication example with a small Fq value.

```rust
#[test]
    fn test_small_multiplication_examples() {
        let z1: Fq = BigInt([1, 0, 0, 0]).into();

```

--------------------------------

### Fq Addition Example

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/arkworks.rs.html?search=

Illustrates basic addition of two Fq elements, showing the expected result.

```rust
fn test_addition_examples() {
        let z1: Fq = BigInt([1, 1, 1, 1]).into();
        let z2: Fq = BigInt([2, 2, 2, 2]).into();
        let z3: Fq = BigInt([3, 3, 3, 3]).into();

        assert_eq!(z3, z1 + z2);
    }
```

--------------------------------

### Addition Examples

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/arkworks.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Illustrates basic addition of two field elements and verifies the result.

```rust
fn test_addition_examples() {
    let z1: Fq = BigInt([1, 1, 1, 1]).into();
    let z2: Fq = BigInt([2, 2, 2, 2]).into();
    let z3: Fq = BigInt([3, 3, 3, 3]).into();

    assert_eq!(z3, z1 + z2);
}
```

--------------------------------

### fq_addcarryx_u32 Example

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/u32/fiat.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates the usage of fq_addcarryx_u32 for modular addition with carry.

```rust
fq_addcarryx_u32(&mut x458, &mut x459, x457, x411, x441);
    let mut x460: u32 = 0;
    let mut x461: FqU1 = 0;
    fq_addcarryx_u32(&mut x460, &mut x461, x459, x413, x443);
    let mut x462: u32 = 0;
    let mut x463: FqU1 = 0;
    fq_addcarryx_u32(&mut x462, &mut x463, x461, x415, x445);
    let mut x464: u32 = 0;
    let mut x465: FqU1 = 0;
    fq_addcarryx_u32(&mut x464, &mut x465, x463, x417, x447);
    let mut x466: u32 = 0;
    let mut x467: FqU1 = 0;
    fq_addcarryx_u32(&mut x466, &mut x467, x465, x419, x449);
    let mut x468: u32 = 0;
    let mut x469: FqU1 = 0;
    fq_addcarryx_u32(&mut x468, &mut x469, x467, x421, x451);
    let mut x470: u32 = 0;
    let mut x471: FqU1 = 0;
    fq_addcarryx_u32(&mut x470, &mut x471, x469, x423, x453);
    let mut x472: u32 = 0;
    let mut x473: FqU1 = 0;
    fq_addcarryx_u32(&mut x472, &mut x473, x471, x425, x455);
    let x474: u32 = ((x473 as u32) + (x426 as u32));
```

--------------------------------

### fq_mulx_u32 Example

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/u32/fiat.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates the usage of fq_mulx_u32 for modular multiplication with carry.

```rust
fq_mulx_u32(&mut x475, &mut x476, x5, (arg1[7]));
    let mut x477: u32 = 0;
    let mut x478: u32 = 0;
    fq_mulx_u32(&mut x477, &mut x478, x5, (arg1[6]));
    let mut x479: u32 = 0;
    let mut x480: u32 = 0;
    fq_mulx_u32(&mut x479, &mut x480, x5, (arg1[5]));
    let mut x481: u32 = 0;
    let mut x482: u32 = 0;
    fq_mulx_u32(&mut x481, &mut x482, x5, (arg1[4]));
    let mut x483: u32 = 0;
    let mut x484: u32 = 0;
    fq_mulx_u32(&mut x483, &mut x484, x5, (arg1[3]));
    let mut x485: u32 = 0;
    let mut x486: u32 = 0;
    fq_mulx_u32(&mut x485, &mut x486, x5, (arg1[2]));
    let mut x487: u32 = 0;
    let mut x488: u32 = 0;
    fq_mulx_u32(&mut x487, &mut x488, x5, (arg1[1]));
    let mut x489: u32 = 0;
    let mut x490: u32 = 0;
    fq_mulx_u32(&mut x489, &mut x490, x5, (arg1[0]));
```

--------------------------------

### Small Multiplication Examples

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/arkworks.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows a basic multiplication example with a field element initialized from a small big integer.

```rust
fn test_small_multiplication_examples() {
    let z1: Fq = BigInt([1, 0, 0, 0]).into();

```

--------------------------------

### fq_add Example

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/u32/fiat.rs.html?search=u32+-%3E+bool

Implements modular addition for field elements in Montgomery domain using `fq_addcarryx_u32` and `fq_subborrowx_u32`. Ensures results are within the field modulus.

```rust
let mut x1: u32 = 0;
    let mut x2: FqU1 = 0;
    fq_addcarryx_u32(&mut x1, &mut x2, 0x0, (arg1[0]), (arg2[0]));
    let mut x3: u32 = 0;
    let mut x4: FqU1 = 0;
    fq_addcarryx_u32(&mut x3, &mut x4, x2, (arg1[1]), (arg2[1]));
    let mut x5: u32 = 0;
    let mut x6: FqU1 = 0;
    fq_addcarryx_u32(&mut x5, &mut x6, x4, (arg1[2]), (arg2[2]));
    let mut x7: u32 = 0;
    let mut x8: FqU1 = 0;
    fq_addcarryx_u32(&mut x7, &mut x8, x6, (arg1[3]), (arg2[3]));
    let mut x9: u32 = 0;
    let mut x10: FqU1 = 0;
    fq_addcarryx_u32(&mut x9, &mut x10, x8, (arg1[4]), (arg2[4]));
    let mut x11: u32 = 0;
    let mut x12: FqU1 = 0;
    fq_addcarryx_u32(&mut x11, &mut x12, x10, (arg1[5]), (arg2[5]));
    let mut x13: u32 = 0;
    let mut x14: FqU1 = 0;
    fq_addcarryx_u32(&mut x13, &mut x14, x12, (arg1[6]), (arg2[6]));
    let mut x15: u32 = 0;
    let mut x16: FqU1 = 0;
    fq_addcarryx_u32(&mut x15, &mut x16, x14, (arg1[7]), (arg2[7]));
    let mut x17: u32 = 0;
    let mut x18: FqU1 = 0;
    fq_subborrowx_u32(&mut x17, &mut x18, 0x0, x1, (0x1 as u32));
    let mut x19: u32 = 0;
    let mut x20: FqU1 = 0;
    fq_subborrowx_u32(&mut x19, &mut x20, x18, x3, 0xa118000);
    let mut x21: u32 = 0;
    let mut x22: FqU1 = 0;
    fq_subborrowx_u32(&mut x21, &mut x22, x20, x5, 0xd0000001);
    let mut x23: u32 = 0;
    let mut x24: FqU1 = 0;
    fq_subborrowx_u32(&mut x23, &mut x24, x22, x7, 0x59aa76fe);
    let mut x25: u32 = 0;
    let mut x26: FqU1 = 0;
    fq_subborrowx_u32(&mut x25, &mut x26, x24, x9, 0x5c37b001);
    let mut x27: u32 = 0;
    let mut x28: FqU1 = 0;
    fq_subborrowx_u32(&mut x27, &mut x28, x26, x11, 0x60b44d1e);
    let mut x29: u32 = 0;
    let mut x30: FqU1 = 0;
    fq_subborrowx_u32(&mut x29, &mut x30, x28, x13, 0x9a2ca556);
    let mut x31: u32 = 0;
    let mut x32: FqU1 = 0;
    fq_subborrowx_u32(&mut x31, &mut x32, x30, x15, 0x12ab655e);
    let mut x33: u32 = 0;
    let mut x34: FqU1 = 0;
    fq_subborrowx_u32(&mut x33, &mut x34, x32, (x16 as u32), (0x0 as u32));
    let mut x35: u32 = 0;
    fq_cmovznz_u32(&mut x35, x34, x17, x1);
    let mut x36: u32 = 0;
    fq_cmovznz_u32(&mut x36, x34, x19, x3);
    let mut x37: u32 = 0;
    fq_cmovznz_u32(&mut x37, x34, x21, x5);
    let mut x38: u32 = 0;
    fq_cmovznz_u32(&mut x38, x34, x23, x7);
    let mut x39: u32 = 0;
    fq_cmovznz_u32(&mut x39, x34, x25, x9);
    let mut x40: u32 = 0;
    fq_cmovznz_u32(&mut x40, x34, x27, x11);
    let mut x41: u32 = 0;
    fq_cmovznz_u32(&mut x41, x34, x29, x13);
    let mut x42: u32 = 0;
    fq_cmovznz_u32(&mut x42, x34, x31, x15);
    out1[0] = x35;
    out1[1] = x36;
    out1[2] = x37;
    out1[3] = x38;
    out1[4] = x39;
    out1[5] = x40;
    out1[6] = x41;
    out1[7] = x42;
```

--------------------------------

### From LE Bytes Mod Order Examples

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/arkworks.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates the usage of `from_le_bytes_mod_order` with specific byte arrays, including converting to one and verifying the byte representation.

```rust
fn test_from_le_bytes_mod_order_examples() {
    let p_plus_1_bytes: [u8; 32] = [
        2, 0, 0, 0, 0, 128, 17, 10, 1, 0, 0, 208, 254, 118, 170, 89, 1, 176, 55, 92, 30, 77,
        180, 96, 86, 165, 44, 154, 94, 101, 171, 18,
    ];
    let bytes_for_1 = {
        let mut out = [0u8; 32];
        out[0] = 1;
        out
    };

    assert_eq!(Fq::from_le_bytes_mod_order(&p_plus_1_bytes), Fq::one());
    assert_eq!(Fq::from_le_bytes_mod_order(&p_plus_1_bytes).to_bytes_le(), bytes_for_1);
}
```

--------------------------------

### Example: From LE Bytes Mod Order for One

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fp/arkworks.rs.html?search=

Demonstrates the `from_le_bytes_mod_order` function with specific byte inputs that should result in the field element one.

```rust
#[test]
    fn test_from_le_bytes_mod_order_examples() {
        let p_plus_1_bytes: [u8; 48] = [
            2, 0, 0, 0, 0, 192, 8, 133, 0, 0, 0, 48, 68, 93, 11, 23, 0, 72, 9, 186, 47, 98, 243,
            30, 143, 19, 245, 0, 243, 217, 34, 26, 59, 73, 161, 108, 192, 5, 59, 198, 234, 16, 197,
            23, 70, 58, 174, 1,
        ];
        let bytes_for_1 = {
            let mut out = [0u8; 48];
            out[0] = 1;
            out
        };

        assert_eq!(Fp::from_le_bytes_mod_order(&p_plus_1_bytes), Fp::one());
        assert_eq!(
            Fp::from_le_bytes_mod_order(&p_plus_1_bytes).to_bytes_le(),
            bytes_for_1
        );
    }
```

--------------------------------

### Fq Small Multiplication Example

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/arkworks.rs.html?search=

Shows a simple multiplication involving an Fq element initialized from a BigInt.

```rust
fn test_small_multiplication_examples() {
        let z1: Fq = BigInt([1, 0, 0, 0]).into();
    }
```

--------------------------------

### Fq Subtraction Example

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/arkworks.rs.html?search=

Demonstrates in-place subtraction of an Fq element from itself, resulting in zero.

```rust
fn test_subtraction_examples() {
        let mut z1: Fq = BigInt([1, 1, 1, 1]).into();
        z1 -= z1;

        assert_eq!(z1, Fq::ZERO);
    }
```

--------------------------------

### Fq From LE Bytes Mod Order Examples

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/arkworks.rs.html?search=

Demonstrates the usage of `from_le_bytes_mod_order` with specific byte arrays, including one that represents Fq::ONE.

```rust
fn test_from_le_bytes_mod_order_examples() {
        let p_plus_1_bytes: [u8; 32] = [
            2, 0, 0, 0, 0, 128, 17, 10, 1, 0, 0, 208, 254, 118, 170, 89, 1, 176, 55, 92, 30, 77,
            180, 96, 86, 165, 44, 154, 94, 101, 171, 18,
        ];
        let bytes_for_1 = {
            let mut out = [0u8; 32];
            out[0] = 1;
            out
        };

        assert_eq!(Fq::from_le_bytes_mod_order(&p_plus_1_bytes), Fq::one());
        assert_eq!( 
            Fq::from_le_bytes_mod_order(&p_plus_1_bytes).to_bytes_le(),
            bytes_for_1
        );
    }
```

--------------------------------

### Example: Addition of Field Elements

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fp/arkworks.rs.html?search=

Demonstrates the addition operation between two Decaf377 field elements.

```rust
#[test]
    fn test_addition_examples() {
        let z1: Fp = BigInt([1, 1, 1, 1, 1, 1]).into();
        let z2: Fp = BigInt([2, 2, 2, 2, 2, 2]).into();
        let z3: Fp = BigInt([3, 3, 3, 3, 3, 3]).into();

        assert_eq!(z3, z1 + z2);
    }
```

--------------------------------

### From LE Bytes Mod Order Examples

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fp/arkworks.rs.html?search=std%3A%3Avec

Demonstrates the `from_le_bytes_mod_order` function with specific byte arrays, including one that represents Fp::one() and its conversion back to bytes.

```rust
#[test]
    fn test_from_le_bytes_mod_order_examples() {
        let p_plus_1_bytes: [u8; 48] = [
            2, 0, 0, 0, 0, 192, 8, 133, 0, 0, 0, 48, 68, 93, 11, 23, 0, 72, 9, 186, 47, 98, 243,
            30, 143, 19, 245, 0, 243, 217, 34, 26, 59, 73, 161, 108, 192, 5, 59, 198, 234, 16, 197,
            23, 70, 58, 174, 1,
        ];
        let bytes_for_1 = {
            let mut out = [0u8; 48];
            out[0] = 1;
            out
        };

        assert_eq!(Fp::from_le_bytes_mod_order(&p_plus_1_bytes), Fp::one());
        assert_eq!( 
            Fp::from_le_bytes_mod_order(&p_plus_1_bytes).to_bytes_le(),
            bytes_for_1
        );
    }
```

--------------------------------

### Test Small Multiplication Examples

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fp/arkworks.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Verifies basic multiplication and addition properties for small field elements.

```rust
let z1: Fp = BigInt([1, 0, 0, 0, 0, 0]).into();
        let z2: Fp = BigInt([2, 0, 0, 0, 0, 0]).into();
        let z3: Fp = BigInt([3, 0, 0, 0, 0, 0]).into();

        assert_eq!(z1 + z1, z1 * z2);
        assert_eq!(z1 + z1 + z1, z1 * z3);
```

--------------------------------

### Fq Zero and One Implementations

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/arkworks.rs.html?search=std%3A%3Avec

Provides implementations for the Zero and One traits, defining how to get the additive identity (zero) and multiplicative identity (one) for the Fq field.

```rust
impl Zero for Fq {
    #[inline]
    fn zero() -> Self {
        Fq::ZERO
    }

    #[inline]
    fn is_zero(&self) -> bool {
        *self == Fq::ZERO
    }
}

impl One for Fq {
    #[inline]
    fn one() -> Self {
        Fq::ONE
    }

    #[inline]
    fn is_one(&self) -> bool {
        *self == Fq::ONE
    }
}
```

--------------------------------

### Fq Instantiation and Constants

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/u64/wrapper.rs.html?search=u32+-%3E+bool

Provides methods for creating Fq instances from raw bytes, little-endian limbs, and Montgomery limbs. Also exposes constant values for zero, one, and a sentinel.

```APIDOC
## Fq Instantiation and Constants

### `from_le_limbs(limbs: [u64; N_64]) -> Fq`

Creates an `Fq` instance from an array of little-endian `u64` limbs.

### `from_raw_bytes(bytes: &[u8; N_8]) -> Fq`

Creates an `Fq` instance from a raw byte array of `N_8` bytes in little-endian order.

### `from_montgomery_limbs(limbs: [u64; N]) -> Fq`

Instantiates a constant field element from its Montgomery limbs. This method is intended for internal use by those familiar with the library's internals.

### Constants

*   `ZERO`: Represents the additive identity (0).
*   `ONE`: Represents the multiplicative identity (1).
*   `SENTINEL`: A special value that is not equal to any other field element. Operations involving this value are undefined.
```

--------------------------------

### Decaf377 Library Setup

Source: https://docs.rs/decaf377/latest/src/decaf377/lib.rs.html

This snippet shows the basic setup for the decaf377 library, including disabling the standard library and importing necessary modules. It conditionally includes arkworks integration based on the 'arkworks' feature flag.

```rust
#![no_std]
//! `decaf377` [instantiates Decaf over the BLS12-377 scalar
//! field](https://penumbra.zone/crypto/primitives/decaf377.html).
1//!
use cfg_if::cfg_if;

pub mod fields;
pub use fields::{fp::Fp, fq::Fq, fr::Fr};
mod sign;

mod error;
pub use error::EncodingError;

cfg_if! {
    if #[cfg(feature = "arkworks")] {
        mod ark_curve;

        pub use ark_curve::{Element, Encoding, ZETA};

        pub use ark_curve::bls12_377::Bls12_377;

        #[cfg(feature = "r1cs")]
        pub use ark_curve::r1cs;


    } else {
        mod min_curve;

        pub use min_curve::{Element, Encoding, ZETA};
    }
}
```

--------------------------------

### Get Zero Element

Source: https://docs.rs/decaf377/latest/decaf377/struct.Element.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the additive identity element.

```APIDOC
## fn zero() -> Self

### Description
Returns the additive identity element of `Self`, which is `0`.

### Method
N/A (associated function)

### Returns
- `Self`: The zero element.
```

--------------------------------

### Get Identity Element

Source: https://docs.rs/decaf377/latest/decaf377/struct.Element.html

Represents the identity element for the decaf377 curve.

```rust
pub const IDENTITY: Self
```

--------------------------------

### Get Conventional Generator

Source: https://docs.rs/decaf377/latest/decaf377/struct.Element.html

Retrieves the conventional generator for the decaf377 curve.

```rust
pub const GENERATOR: Self
```

--------------------------------

### Fq Constructors and Constants

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/u64/wrapper.rs.html?search=

Provides methods for creating new Fq instances and accessing predefined constants like ZERO and ONE.

```APIDOC
## Constants

### `ZERO`

Represents the additive identity (0) for the field.

### `ONE`

Represents the multiplicative identity (1) for the field.

### `SENTINEL`

A special value that is not equal to any other field element. Operations involving this value are undefined.
```

--------------------------------

### Fq Addition with Carry (Intermediate Steps)

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/u32/fiat.rs.html?search=u32+-%3E+bool

Demonstrates intermediate steps in a sequence of Fq additions with carry, showing how carry values propagate through multiple u32 operations.

```rust
fq_addcarryx_u32(&mut x346, &mut x347, 0x0, x345, x342);
    fq_addcarryx_u32(&mut x348, &mut x349, x347, x343, x340);
    fq_addcarryx_u32(&mut x350, &mut x351, x349, x341, x338);
    fq_addcarryx_u32(&mut x352, &mut x353, x351, x339, x336);
    fq_addcarryx_u32(&mut x354, &mut x355, x353, x337, x334);
    fq_addcarryx_u32(&mut x356, &mut x357, x355, x335, x332);
    let x358: u32 = ((x357 as u32) + x333);
```

--------------------------------

### Fq Conversion and Utility Methods

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/u64/wrapper.rs.html?search=std%3A%3Avec

Details methods for converting Fq elements to and from byte slices and u64 limbs, as well as utility functions like checking for sentinel values and constant time equality comparison.

```APIDOC
## Fq Conversion and Utility Methods

### Description
Details methods for converting Fq elements to and from byte slices and u64 limbs, as well as utility functions like checking for sentinel values and constant time equality comparison.

### Methods

- **`from_le_limbs(limbs: [u64; N_64]) -> Fq`**: Creates an Fq element from little-endian u64 limbs.
- **`from_raw_bytes(bytes: &[u8; N_8]) -> Fq`**: Creates an Fq element from a raw byte array.
- **`to_le_limbs(self) -> [u64; N_64]`**: Converts the Fq element to little-endian u64 limbs.
- **`to_bytes_le(self) -> [u8; N_8]`**: Converts the Fq element to a little-endian byte array.
- **`ct_eq(self, other: &Fq) -> Choice`**: Performs a constant-time equality check between two Fq elements.
- **`is_sentinel(self) -> bool`**: Checks if the Fq element is the sentinel value.
```

--------------------------------

### Conversions to Fq

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/ops.rs.html?search=u32+-%3E+bool

Demonstrates how to convert primitive integer types (u128, u64, u32, u16, u8, bool) into Fq field elements.

```APIDOC
## Conversions to Fq

This section details the implementation of the `From` trait for converting various primitive integer types into `Fq` field elements.

### `impl From<u128> for Fq`
Converts a `u128` into an `Fq` element.

### `impl From<u64> for Fq`
Converts a `u64` into an `Fq` element by first converting it to `u128`.

### `impl From<u32> for Fq`
Converts a `u32` into an `Fq` element by first converting it to `u128`.

### `impl From<u16> for Fq`
Converts a `u16` into an `Fq` element by first converting it to `u128`.

### `impl From<u8> for Fq`
Converts a `u8` into an `Fq` element by first converting it to `u128`.

### `impl From<bool> for Fq`
Converts a `bool` into an `Fq` element (0 for false, 1 for true) by first converting it to `u128`.
```

--------------------------------

### Test Small Multiplication Examples

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fp/arkworks.rs.html?search=

Tests basic multiplication of field elements representing small integers.

```rust
fn test_small_multiplication_examples() {
        let z1: Fp = BigInt([1, 0, 0, 0, 0, 0]).into();
        let z2: Fp = BigInt([2, 0, 0, 0, 0, 0]).into();
        let z3: Fp = BigInt([3, 0, 0, 0, 0, 0]).into();

        assert_eq!(z1 + z1, z1 * z2);
        assert_eq!(z1 + z1 + z1, z1 * z3);
    }
```

--------------------------------

### Fq Product Implementations

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/ops.rs.html

Provides implementations for calculating the product of elements of Fq, both by value and by reference, using iterators.

```rust
impl Product<Self> for Fq {
    fn product<I: Iterator<Item = Self>>(iter: I) -> Self {
        iter.fold(Self::ONE, Mul::mul)
    }
}

impl<'a> Product<&'a Self> for Fq {
    fn product<I: Iterator<Item = &'a Self>>(iter: I) -> Self {
        iter.fold(Self::ONE, Mul::mul)
    }
}
```

--------------------------------

### Precomputation for Field Multiplication

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fp/u32/wrapper.rs.html?search=u32+-%3E+bool

Precomputes values needed for field multiplication. This is a setup step for efficient multiplication.

```rust
let mut pre_comp: [u32; N] = [0u32; N];
        fiat::fp_divstep_precomp(&mut pre_comp);
```

--------------------------------

### fq_set_one

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/u32/fiat.rs.html?search=

Initializes a mutable FqMontgomeryDomainFieldElement to the multiplicative identity (one). This is crucial for operations that require a starting value of 1.

```APIDOC
## fq_set_one

### Description
Initializes a mutable FqMontgomeryDomainFieldElement to the multiplicative identity (one). This is crucial for operations that require a starting value of 1.

### Postconditions
- `eval (from_montgomery out1) mod m = 1 mod m`
- `0 ≤ eval out1 < m`

### Parameters
#### Path Parameters
- **out1** (&mut FqMontgomeryDomainFieldElement) - The mutable field element to set to one.

### Method
Rust function call

### Endpoint
N/A (Rust function)

### Code Example
```rust
let mut element: FqMontgomeryDomainFieldElement = /* ... initialization ... */;
fq_set_one(&mut element);
```
```

--------------------------------

### fq_subborrowx_u32 Example

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/u32/fiat.rs.html?search=u32+-%3E+bool

Demonstrates the usage of `fq_subborrowx_u32` for modular subtraction with borrow. This function is used internally for field element subtraction.

```rust
let mut x774: u32 = 0;
    let mut x775: FqU1 = 0;
    fq_subborrowx_u32(&mut x774, &mut x775, x773, x757, 0x5c37b001);
    let mut x776: u32 = 0;
    let mut x777: FqU1 = 0;
    fq_subborrowx_u32(&mut x776, &mut x777, x775, x759, 0x60b44d1e);
    let mut x778: u32 = 0;
    let mut x779: FqU1 = 0;
    fq_subborrowx_u32(&mut x778, &mut x779, x777, x761, 0x9a2ca556);
    let mut x780: u32 = 0;
    let mut x781: FqU1 = 0;
    fq_subborrowx_u32(&mut x780, &mut x781, x779, x763, 0x12ab655e);
    let mut x782: u32 = 0;
    let mut x783: FqU1 = 0;
    fq_subborrowx_u32(&mut x782, &mut x783, x781, x765, (0x0 as u32));
    let mut x784: u32 = 0;
    fq_cmovznz_u32(&mut x784, x783, x766, x749);
    let mut x785: u32 = 0;
    fq_cmovznz_u32(&mut x785, x783, x768, x751);
    let mut x786: u32 = 0;
    fq_cmovznz_u32(&mut x786, x783, x770, x753);
    let mut x787: u32 = 0;
    fq_cmovznz_u32(&mut x787, x783, x772, x755);
    let mut x788: u32 = 0;
    fq_cmovznz_u32(&mut x788, x783, x774, x757);
    let mut x789: u32 = 0;
    fq_cmovznz_u32(&mut x789, x783, x776, x759);
    let mut x790: u32 = 0;
    fq_cmovznz_u32(&mut x790, x783, x778, x761);
    let mut x791: u32 = 0;
    fq_cmovznz_u32(&mut x791, x783, x780, x763);
    out1[0] = x784;
    out1[1] = x785;
    out1[2] = x786;
    out1[3] = x787;
    out1[4] = x788;
    out1[5] = x789;
    out1[6] = x790;
    out1[7] = x791;
```

--------------------------------

### Fp Struct and Core Methods

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fp/u32/wrapper.rs.html?search=

Provides an overview of the Fp struct, its constructors, conversion methods, and basic arithmetic operations like square and inverse.

```APIDOC
## Fp Struct

Represents a field element using `fiat::FpMontgomeryDomainFieldElement`.

### Constants

- `ZERO`: The additive identity (0).
- `ONE`: The multiplicative identity (1).
- `QUADRATIC_NON_RESIDUE`: A quadratic non-residue in the field.
- `MINUS_ONE`: The additive inverse of ONE (-1).

### Constructors and Conversions

- `from_le_limbs(limbs: [u64; N_64]) -> Fp`: Creates an Fp element from little-endian u64 limbs.
- `from_raw_bytes(bytes: &[u8; N_8]) -> Fp`: Creates an Fp element from a byte array in little-endian order.
- `to_le_limbs(&self) -> [u64; N_64]`: Converts the Fp element to little-endian u64 limbs.
- `to_bytes_le(&self) -> [u8; N_8]`: Converts the Fp element to a byte array in little-endian order.
- `from_montgomery_limbs_backend(limbs: [u32; N]) -> Fp`: Internal constructor from u32 limbs.
- `from_montgomery_limbs(limbs: [u64; N_64]) -> Fp`: Creates an Fp element from u64 limbs assuming Montgomery form.

### Arithmetic Operations

- `square(&self) -> Fp`: Computes the square of the Fp element.
- `inverse(&self) -> Option<Self>`: Computes the modular multiplicative inverse of the Fp element. Returns `None` if the element is zero.
```

--------------------------------

### Example: Subtraction of Field Elements

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fp/arkworks.rs.html?search=

Demonstrates the in-place subtraction operation for Decaf377 field elements, showing that subtracting an element from itself results in zero.

```rust
#[test]
    fn test_subtraction_examples() {
        let mut z1: Fp = BigInt([1, 1, 1, 1, 1, 1]).into();
        z1 -= z1;

        assert_eq!(z1, Fp::ZERO);
    }
```

--------------------------------

### Fq Addition with Carry (u32 limbs) - Intermediate Steps

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/u32/fiat.rs.html?search=u32+-%3E+bool

Demonstrates intermediate steps in a sequence of additions with carry operations, utilizing u32 limbs for field arithmetic.

```rust
let mut x250: u32 = 0;
let mut x251: FqU1 = 0;
fq_addcarryx_u32(&mut x250, &mut x251, 0x0, x249, x246);
let mut x252: u32 = 0;
let mut x253: FqU1 = 0;
fq_addcarryx_u32(&mut x252, &mut x253, x251, x247, x244);
let mut x254: u32 = 0;
let mut x255: FqU1 = 0;
fq_addcarryx_u32(&mut x254, &mut x255, x253, x245, x242);
let mut x256: u32 = 0;
let mut x257: FqU1 = 0;
fq_addcarryx_u32(&mut x256, &mut x257, x255, x243, x240);
let mut x258: u32 = 0;
let mut x259: FqU1 = 0;
fq_addcarryx_u32(&mut x258, &mut x259, x257, x241, x238);
let mut x260: u32 = 0;
let mut x261: FqU1 = 0;
fq_addcarryx_u32(&mut x260, &mut x261, x259, x239, x236);
```

--------------------------------

### Fq Canonical Serialization

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/arkworks.rs.html?search=

Implements canonical serialization for Fq field elements, delegating to `serialize_with_flags` and providing a method to get the serialized size.

```rust
impl CanonicalSerialize for Fq {
    #[inline]
    fn serialize_with_mode<W: ark_std::io::Write>(
        &self,
        writer: W,
        _compress: Compress,
    ) -> Result<(), SerializationError> {
        self.serialize_with_flags(writer, EmptyFlags)
    }

    #[inline]
    fn serialized_size(&self, _compress: Compress) -> usize {
        self.serialized_size_with_flags::<EmptyFlags>()
    }
}
```

--------------------------------

### Fq Implementations

Source: https://docs.rs/decaf377/latest/decaf377/fields/fq/type.Fq.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides various constants and methods for working with Fq field elements, including conversions, random sampling, exponentiation, and square root computations.

```APIDOC
### impl Fq

#### Constants

- `MODULUS_LIMBS`: Array of u64 representing the modulus.
- `MODULUS_MINUS_ONE_DIV_TWO_LIMBS`: Array of u64 for modulus minus one divided by two.
- `MODULUS_BIT_SIZE`: The bit size of the modulus.
- `TRACE_LIMBS`: Array of u64 for trace.
- `TRACE_MINUS_ONE_DIV_TWO_LIMBS`: Array of u64 for trace minus one divided by two.
- `TWO_ADICITY`: The two-adic root of unity.
- `QUADRATIC_NON_RESIDUE_TO_TRACE`: A quadratic non-residue related to the trace.
- `MULTIPLICATIVE_GENERATOR`: The multiplicative generator of the field.
- `TWO_ADIC_ROOT_OF_UNITY`: The two-adic root of unity.
- `FIELD_SIZE_POWER_OF_TWO`: A power of two related to the field size.

#### Methods

- `from_le_bytes_mod_order(bytes: &[u8]) -> Self`: Converts a byte slice to an Fq element using little-endian order, modulo the field order.
- `from_bytes_checked(bytes: &[u8; 32]) -> Result<Self, EncodingError>`: Converts a 32-byte array into an Fq element, returning an error if the bytes are not reduced modulo the field order, enforcing canonical serialization.
- `to_bytes(&self) -> [u8; 32]`: Converts the Fq element to a 32-byte array.
- `rand<R: CryptoRngCore>(rng: &mut R) -> Self`: Samples a random field element uniformly using a provided random number generator.
- `power<S: AsRef<[u64]>>(&self, exp: S) -> Self`: Raises the field element to a given power. (Note: Arkworks provides `pow` for this purpose.)

### impl Fq

#### Method

- `sqrt_ratio_zeta(num: &Self, den: &Self) -> (bool, Self)`: Computes the square root of a ratio of field elements (`num/den`). Returns `(true, sqrt)` if the ratio is a quadratic residue, `(true, 0)` if `num` is zero, `(false, 0)` if `den` is zero, or `(false, sqrt(zeta*num/den))` if the ratio is a quadratic non-residue.
```

--------------------------------

### Fq Addition with Carry (u32) - Intermediate Steps

Source: https://docs.rs/decaf377/latest/src/decaf377/fields/fq/u32/fiat.rs.html?search=std%3A%3Avec

Demonstrates intermediate addition steps with carry, combining results from previous operations. Used in complex field arithmetic.

```rust
let mut x250: u32 = 0;
    let mut x251: FqU1 = 0;
    fq_addcarryx_u32(&mut x250, &mut x251, 0x0, x249, x246);
    let mut x252: u32 = 0;
    let mut x253: FqU1 = 0;
    fq_addcarryx_u32(&mut x252, &mut x253, x251, x247, x244);
    let mut x254: u32 = 0;
    let mut x255: FqU1 = 0;
    fq_addcarryx_u32(&mut x254, &mut x255, x253, x245, x242);
    let mut x256: u32 = 0;
    let mut x257: FqU1 = 0;
    fq_addcarryx_u32(&mut x256, &mut x257, x255, x243, x240);
    let mut x258: u32 = 0;
    let mut x259: FqU1 = 0;
    fq_addcarryx_u32(&mut x258, &mut x259, x257, x241, x238);
    let mut x260: u32 = 0;
    let mut x261: FqU1 = 0;
    fq_addcarryx_u32(&mut x260, &mut x261, x259, x239, x236);
```

--------------------------------

### Fq Implementations

Source: https://docs.rs/decaf377/latest/decaf377/fields/fq/type.Fq.html

Provides details on the various implementations available for the Fq type, including constants, conversion functions, and mathematical operations.

```APIDOC
## Implementations for Fq

### Constants

- `MODULUS_LIMBS`: Array of u64 representing the modulus of the field.
- `MODULUS_MINUS_ONE_DIV_TWO_LIMBS`: Array of u64 representing (MODULUS - 1) / 2.
- `MODULUS_BIT_SIZE`: The bit size of the modulus.
- `TRACE_LIMBS`: Array of u64 representing the trace of the field.
- `TRACE_MINUS_ONE_DIV_TWO_LIMBS`: Array of u64 representing (TRACE - 1) / 2.
- `TWO_ADICITY`: The 2-adicity of the field.
- `QUADRATIC_NON_RESIDUE_TO_TRACE`: A quadratic non-residue raised to the power of the trace.
- `MULTIPLICATIVE_GENERATOR`: A multiplicative generator of the field.
- `TWO_ADIC_ROOT_OF_UNITY`: A 2-adic root of unity.
- `FIELD_SIZE_POWER_OF_TWO`: A power of two related to the field size.

### Conversion Methods

- `from_le_bytes_mod_order(bytes: &[u8]) -> Self`
  Converts a byte slice into an `Fq` element, assuming little-endian order and that the value is already reduced modulo the field's order.

- `from_bytes_checked(bytes: &[u8; 32]) -> Result<Self, EncodingError>`
  Converts a 32-byte array into an `Fq` element. Returns `Ok(Self)` if the bytes represent a value already reduced modulo the field's order, otherwise returns `Err(EncodingError)`. This enforces canonical serialization.

- `to_bytes(&self) -> [u8; 32]`
  Converts the `Fq` element into a 32-byte array.

- `rand<R: CryptoRngCore>(rng: &mut R) -> Self`
  Samples a random `Fq` element uniformly using a provided random number generator.

### Mathematical Operations

- `power<S: AsRef<[u64]>>(&self, exp: S) -> Self`
  Raises the `Fq` element to a given power. Note that Arkworks provides an alternative `pow` method.

- `sqrt_ratio_zeta(num: &Self, den: &Self) -> (bool, Self)`
  Computes the square root of a ratio of field elements (`num / den`).
  Returns a tuple `(is_square, sqrt_value)`:
  - `(true, sqrt(num/den))` if `num` and `den` are non-zero and `num/den` is a quadratic residue.
  - `(true, 0)` if `num` is zero.
  - `(false, 0)` if `den` is zero.
  - `(false, sqrt(zeta*num/den))` if `num` and `den` are non-zero and `num/den` is a quadratic non-residue (where `zeta` is a specific field constant).
```

--------------------------------

### Fq Implementations

Source: https://docs.rs/decaf377/latest/decaf377/fields/fq/type.Fq.html?search=u32+-%3E+bool

Provides details on the constants and methods available for the Fq type, covering field properties, byte conversions, random generation, and exponentiation.

```APIDOC
### impl Fq

Source
#### pub const MODULUS_LIMBS: [u64; 4]

#### pub const MODULUS_MINUS_ONE_DIV_TWO_LIMBS: [u64; 4]

#### pub const MODULUS_BIT_SIZE: u32 = 0xfd

#### pub const TRACE_LIMBS: [u64; 4]

#### pub const TRACE_MINUS_ONE_DIV_TWO_LIMBS: [u64; 4]

#### pub const TWO_ADICITY: u32 = 0x2f

#### pub const QUADRATIC_NON_RESIDUE_TO_TRACE: Self

#### pub const MULTIPLICATIVE_GENERATOR: Self

#### pub const TWO_ADIC_ROOT_OF_UNITY: Self

#### pub const FIELD_SIZE_POWER_OF_TWO: Self

#### pub fn from_le_bytes_mod_order(bytes: &[u8]) -> Self

#### pub fn from_bytes_checked(bytes: &[u8; 32]) -> Result<Self, EncodingError>
Convert bytes into an Fq element, returning None if these bytes are not already reduced.
This means that values that cannot be produced by encoding a field element will return None, enforcing canonical serialization.

#### pub fn to_bytes(&self) -> [u8; 32]

#### pub fn rand<R: CryptoRngCore>(rng: &mut R) -> Self
Sample a random field element uniformly.

#### pub fn power<S: AsRef<[u64]>>(&self, exp: S) -> Self
Raise this element to a given power.
Note: Arkworks provides another method for this, called `pow`.
```