plonky2/src/generator.rs

use std::collections::{HashMap, HashSet};
use std::convert::identity;
use std::fmt::Debug;

use crate::field::extension_field::target::ExtensionTarget;
use crate::field::extension_field::{Extendable, FieldExtension};
use crate::field::field::Field;
use crate::proof::{Hash, HashTarget};
use crate::target::Target;
use crate::wire::Wire;
use crate::witness::PartialWitness;

/// Given a `PartialWitness` that has only inputs set, populates the rest of the witness using the
/// given set of generators.
pub(crate) fn generate_partial_witness<F: Field>(
    witness: &mut PartialWitness<F>,
    generators: &[Box<dyn WitnessGenerator<F>>],
) {
    // Index generator indices by their watched targets.
    let mut generator_indices_by_watches = HashMap::new();
    for (i, generator) in generators.iter().enumerate() {
        for watch in generator.watch_list() {
            generator_indices_by_watches
                .entry(watch)
                .or_insert_with(Vec::new)
                .push(i);
        }
    }

    // Build a list of "pending" generators which are queued to be run. Initially, all generators
    // are queued.
    let mut pending_generator_indices: HashSet<_> = (0..generators.len()).collect();

    // We also track a list of "expired" generators which have already returned false.
    let mut generator_is_expired = vec![false; generators.len()];

    // Keep running generators until no generators are queued.
    while !pending_generator_indices.is_empty() {
        let mut next_pending_generator_indices = HashSet::new();

        for &generator_idx in &pending_generator_indices {
            let (result, finished) = generators[generator_idx].run(&witness);
            if finished {
                generator_is_expired[generator_idx] = true;
            }

            // Enqueue unfinished generators that were watching one of the newly populated targets.
            for (watch, _) in &result.target_values {
                if let Some(watching_generator_indices) = generator_indices_by_watches.get(watch) {
                    for &watching_generator_idx in watching_generator_indices {
                        if !generator_is_expired[watching_generator_idx] {
                            next_pending_generator_indices.insert(watching_generator_idx);
                        }
                    }
                }
            }

            witness.extend(result);
        }

        pending_generator_indices = next_pending_generator_indices;
    }

    assert!(
        generator_is_expired.into_iter().all(identity),
        "Some generators weren't run."
    );
}

/// A generator participates in the generation of the witness.
pub trait WitnessGenerator<F: Field>: 'static + Send + Sync {
    /// Targets to be "watched" by this generator. Whenever a target in the watch list is populated,
    /// the generator will be queued to run.
    fn watch_list(&self) -> Vec<Target>;

    /// Run this generator, returning a `PartialWitness` containing any new witness elements, and a
    /// flag indicating whether the generator is finished. If the flag is true, the generator will
    /// never be run again, otherwise it will be queued for another run next time a target in its
    /// watch list is populated.
    fn run(&self, witness: &PartialWitness<F>) -> (GeneratedValues<F>, bool);
}

/// Values generated by a generator invocation.
pub struct GeneratedValues<F: Field> {
    pub(crate) target_values: Vec<(Target, F)>,
}

impl<F: Field> From<Vec<(Target, F)>> for GeneratedValues<F> {
    fn from(target_values: Vec<(Target, F)>) -> Self {
        Self { target_values }
    }
}

impl<F: Field> GeneratedValues<F> {
    pub fn with_capacity(capacity: usize) -> Self {
        Vec::with_capacity(capacity).into()
    }

    pub fn empty() -> Self {
        Vec::new().into()
    }

    pub fn singleton_wire(wire: Wire, value: F) -> Self {
        Self::singleton_target(Target::Wire(wire), value)
    }

    pub fn singleton_target(target: Target, value: F) -> Self {
        vec![(target, value)].into()
    }

    pub fn singleton_extension_target<const D: usize>(
        et: ExtensionTarget<D>,
        value: F::Extension,
    ) -> Self
    where
        F: Extendable<D>,
    {
        let mut witness = Self::with_capacity(D);
        witness.set_extension_target(et, value);
        witness
    }

    pub fn set_target(&mut self, target: Target, value: F) {
        self.target_values.push((target, value))
    }

    pub fn set_hash_target(&mut self, ht: HashTarget, value: Hash<F>) {
        ht.elements
            .iter()
            .zip(value.elements)
            .for_each(|(&t, x)| self.set_target(t, x));
    }

    pub fn set_extension_target<const D: usize>(
        &mut self,
        et: ExtensionTarget<D>,
        value: F::Extension,
    ) where
        F: Extendable<D>,
    {
        let limbs = value.to_basefield_array();
        (0..D).for_each(|i| {
            self.set_target(et.0[i], limbs[i]);
        });
    }

    pub fn set_wire(&mut self, wire: Wire, value: F) {
        self.set_target(Target::Wire(wire), value)
    }

    pub fn set_wires<W>(&mut self, wires: W, values: &[F])
    where
        W: IntoIterator<Item = Wire>,
    {
        // If we used itertools, we could use zip_eq for extra safety.
        for (wire, &value) in wires.into_iter().zip(values) {
            self.set_wire(wire, value);
        }
    }

    pub fn set_ext_wires<W, const D: usize>(&mut self, wires: W, value: F::Extension)
    where
        F: Extendable<D>,
        W: IntoIterator<Item = Wire>,
    {
        self.set_wires(wires, &value.to_basefield_array());
    }
}

/// A generator which runs once after a list of dependencies is present in the witness.
pub trait SimpleGenerator<F: Field>: 'static + Send + Sync {
    fn dependencies(&self) -> Vec<Target>;

    fn run_once(&self, witness: &PartialWitness<F>) -> GeneratedValues<F>;
}

impl<F: Field, SG: SimpleGenerator<F>> WitnessGenerator<F> for SG {
    fn watch_list(&self) -> Vec<Target> {
        self.dependencies()
    }

    fn run(&self, witness: &PartialWitness<F>) -> (GeneratedValues<F>, bool) {
        if witness.contains_all(&self.dependencies()) {
            (self.run_once(witness), true)
        } else {
            (GeneratedValues::empty(), false)
        }
    }
}

/// A generator which copies one wire to another.
#[derive(Debug)]
pub(crate) struct CopyGenerator {
    pub(crate) src: Target,
    pub(crate) dst: Target,
}

impl<F: Field> SimpleGenerator<F> for CopyGenerator {
    fn dependencies(&self) -> Vec<Target> {
        vec![self.src]
    }

    fn run_once(&self, witness: &PartialWitness<F>) -> GeneratedValues<F> {
        let value = witness.get_target(self.src);
        GeneratedValues::singleton_target(self.dst, value)
    }
}

/// A generator for including a random value
pub(crate) struct RandomValueGenerator {
    pub(crate) target: Target,
}

impl<F: Field> SimpleGenerator<F> for RandomValueGenerator {
    fn dependencies(&self) -> Vec<Target> {
        Vec::new()
    }

    fn run_once(&self, _witness: &PartialWitness<F>) -> GeneratedValues<F> {
        let random_value = F::rand();

        GeneratedValues::singleton_target(self.target, random_value)
    }
}

/// A generator for testing if a value equals zero
pub(crate) struct NonzeroTestGenerator {
    pub(crate) to_test: Target,
    pub(crate) dummy: Target,
}

impl<F: Field> SimpleGenerator<F> for NonzeroTestGenerator {
    fn dependencies(&self) -> Vec<Target> {
        vec![self.to_test]
    }

    fn run_once(&self, witness: &PartialWitness<F>) -> GeneratedValues<F> {
        let to_test_value = witness.get_target(self.to_test);

        let dummy_value = if to_test_value == F::ZERO {
            F::ONE
        } else {
            to_test_value.inverse()
        };

        GeneratedValues::singleton_target(self.dummy, dummy_value)
    }
}