From bb48cabdb19c0de801255b2a5418afc459f691f5 Mon Sep 17 00:00:00 2001 From: Robin Salen <30937548+Nashtare@users.noreply.github.com> Date: Fri, 12 Jan 2024 17:07:18 +0100 Subject: [PATCH] Add math rendering with Katex (#1459) --- .cargo/katex-header.html | 30 ++++++++++++++++++++++++ evm/.cargo/katex-header.html | 1 + evm/Cargo.toml | 4 ++++ field/.cargo/katex-header.html | 1 + field/Cargo.toml | 4 ++++ maybe_rayon/.cargo/katex-header.html | 1 + maybe_rayon/Cargo.toml | 4 ++++ plonky2/.cargo/katex-header.html | 1 + plonky2/Cargo.toml | 4 ++++ plonky2/src/gates/coset_interpolation.rs | 25 +++++++++++--------- plonky2/src/gates/gate.rs | 13 +++++----- plonky2/src/gates/mod.rs | 11 +++++---- starky/.cargo/katex-header.html | 1 + starky/Cargo.toml | 4 ++++ util/.cargo/katex-header.html | 1 + util/Cargo.toml | 4 ++++ 16 files changed, 87 insertions(+), 22 deletions(-) create mode 100644 .cargo/katex-header.html create mode 100644 evm/.cargo/katex-header.html create mode 100644 field/.cargo/katex-header.html create mode 100644 maybe_rayon/.cargo/katex-header.html create mode 100644 plonky2/.cargo/katex-header.html create mode 100644 starky/.cargo/katex-header.html create mode 100644 util/.cargo/katex-header.html diff --git a/.cargo/katex-header.html b/.cargo/katex-header.html new file mode 100644 index 00000000..5db5bc0b --- /dev/null +++ b/.cargo/katex-header.html @@ -0,0 +1,30 @@ + + + + \ No newline at end of file diff --git a/evm/.cargo/katex-header.html b/evm/.cargo/katex-header.html new file mode 100644 index 00000000..20723b5d --- /dev/null +++ b/evm/.cargo/katex-header.html @@ -0,0 +1 @@ +../../.cargo/katex-header.html \ No newline at end of file diff --git a/evm/Cargo.toml b/evm/Cargo.toml index a6a99639..8701a279 100644 --- a/evm/Cargo.toml +++ b/evm/Cargo.toml @@ -59,3 +59,7 @@ required-features = ["asmtools"] [[bench]] name = "stack_manipulation" harness = false + +# Display math equations properly in documentation +[package.metadata.docs.rs] +rustdoc-args = ["--html-in-header", ".cargo/katex-header.html"] diff --git a/field/.cargo/katex-header.html b/field/.cargo/katex-header.html new file mode 100644 index 00000000..20723b5d --- /dev/null +++ b/field/.cargo/katex-header.html @@ -0,0 +1 @@ +../../.cargo/katex-header.html \ No newline at end of file diff --git a/field/Cargo.toml b/field/Cargo.toml index ed5ef27b..72408c49 100644 --- a/field/Cargo.toml +++ b/field/Cargo.toml @@ -15,3 +15,7 @@ rand = { version = "0.8.5", default-features = false, features = ["getrandom"] } serde = { version = "1.0", default-features = false, features = ["alloc", "derive"] } static_assertions = { version = "1.1.0", default-features = false } unroll = { version = "0.1.5", default-features = false } + +# Display math equations properly in documentation +[package.metadata.docs.rs] +rustdoc-args = ["--html-in-header", ".cargo/katex-header.html"] diff --git a/maybe_rayon/.cargo/katex-header.html b/maybe_rayon/.cargo/katex-header.html new file mode 100644 index 00000000..20723b5d --- /dev/null +++ b/maybe_rayon/.cargo/katex-header.html @@ -0,0 +1 @@ +../../.cargo/katex-header.html \ No newline at end of file diff --git a/maybe_rayon/Cargo.toml b/maybe_rayon/Cargo.toml index 89499e74..e4365632 100644 --- a/maybe_rayon/Cargo.toml +++ b/maybe_rayon/Cargo.toml @@ -10,3 +10,7 @@ parallel = ["rayon"] [dependencies] rayon = { version = "1.5.3", optional = true } + +# Display math equations properly in documentation +[package.metadata.docs.rs] +rustdoc-args = ["--html-in-header", ".cargo/katex-header.html"] diff --git a/plonky2/.cargo/katex-header.html b/plonky2/.cargo/katex-header.html new file mode 100644 index 00000000..20723b5d --- /dev/null +++ b/plonky2/.cargo/katex-header.html @@ -0,0 +1 @@ +../../.cargo/katex-header.html \ No newline at end of file diff --git a/plonky2/Cargo.toml b/plonky2/Cargo.toml index ad586679..d2727853 100644 --- a/plonky2/Cargo.toml +++ b/plonky2/Cargo.toml @@ -78,3 +78,7 @@ harness = false [[bench]] name = "reverse_index_bits" harness = false + +# Display math equations properly in documentation +[package.metadata.docs.rs] +rustdoc-args = ["--html-in-header", ".cargo/katex-header.html"] diff --git a/plonky2/src/gates/coset_interpolation.rs b/plonky2/src/gates/coset_interpolation.rs index 331f1820..ab69f698 100644 --- a/plonky2/src/gates/coset_interpolation.rs +++ b/plonky2/src/gates/coset_interpolation.rs @@ -29,23 +29,26 @@ use crate::util::serialization::{Buffer, IoResult, Read, Write}; /// - the values that the interpolated polynomial takes on the coset /// - the evaluation point /// -/// The evaluation strategy is based on the observation that if P(X) is the interpolant of some -/// values over a coset and P'(X) is the interpolant of those values over the subgroup, then -/// P(X) = P'(X `shift`^{-1}). Interpolating P'(X) is preferable because when subgroup is fixed +/// The evaluation strategy is based on the observation that if $P(X)$ is the interpolant of some +/// values over a coset and $P'(X)$ is the interpolant of those values over the subgroup, then +/// $P(X) = P'(X \cdot \mathrm{shift}^{-1})$. Interpolating $P'(X)$ is preferable because when subgroup is fixed /// then so are the Barycentric weights and both can be hardcoded into the constraint polynomials. /// /// A full interpolation of N values corresponds to the evaluation of a degree-N polynomial. This /// gate can however be configured with a bounded degree of at least 2 by introducing more -/// non-routed wires. Let x[] be the domain points, v[] be the values, w[] be the Barycentric -/// weights and z be the evaluation point. Define the sequences +/// non-routed wires. Let $x[]$ be the domain points, $v[]$ be the values, $w[]$ be the Barycentric +/// weights and $z$ be the evaluation point. Define the sequences /// -/// p[0] = 1 -/// p[i] = p[i - 1] * (z - x[i - 1]) -/// e[0] = 0, -/// e[i] = e[i - 1] * (z - x[i - 1]) + w[i - 1] * v[i - 1] * p[i - 1] +/// $p[0] = 1,$ /// -/// Then e[N] is the final interpolated value. The non-routed wires hold every (d - 1)'th -/// intermediate value of p and e, starting at p[d] and e[d], where d is the gate degree. +/// $p[i] = p[i - 1] \cdot (z - x[i - 1]),$ +/// +/// $e[0] = 0,$ +/// +/// $e[i] = e[i - 1] ] \cdot (z - x[i - 1]) + w[i - 1] \cdot v[i - 1] \cdot p[i - 1]$ +/// +/// Then $e[N]$ is the final interpolated value. The non-routed wires hold every $(d - 1)$'th +/// intermediate value of $p$ and $e$, starting at $p[d]$ and $e[d]$, where $d$ is the gate degree. #[derive(Clone, Debug, Default)] pub struct CosetInterpolationGate, const D: usize> { pub subgroup_bits: usize, diff --git a/plonky2/src/gates/gate.rs b/plonky2/src/gates/gate.rs index 3087b74c..6dbed3fb 100644 --- a/plonky2/src/gates/gate.rs +++ b/plonky2/src/gates/gate.rs @@ -30,16 +30,17 @@ use crate::util::serialization::{Buffer, IoResult}; /// Vanilla Plonk arithmetization only supports basic fan-in 2 / fan-out 1 arithmetic gates, /// each of the form /// -/// $$ a.b.q_M + a.q_L + b.q_R + c.q_O + q_C = 0 $$ +/// $$ a.b \cdot q_M + a \cdot q_L + b \cdot q_R + c \cdot q_O + q_C = 0 $$ /// /// where: -/// - q_M, q_L, q_R and q_O are boolean selectors, -/// - a, b and c are values used as inputs and output respectively, -/// - q_C is a constant (possibly 0). +/// - $q_M$, $q_L$, $q_R$ and $q_O$ are boolean selectors, +/// - $a$, $b$ and $c$ are values used as inputs and output respectively, +/// - $q_C$ is a constant (possibly 0). /// /// This allows expressing simple operations like multiplication, addition, etc. For -/// instance, to define a multiplication, one can set q_M=1, q_L=q_R=0, q_O = -1 and q_C = 0. -/// Hence, the gate equation simplifies to a.b - c = 0, or a.b = c. +/// instance, to define a multiplication, one can set $q_M=1$, $q_L=q_R=0$, $q_O = -1$ and $q_C = 0$. +/// +/// Hence, the gate equation simplifies to $a.b - c = 0$, or equivalently to $a.b = c$. /// /// However, such a gate is fairly limited for more complex computations. Hence, when a computation may /// require too many of these "vanilla" gates, or when a computation arises often within the same circuit, diff --git a/plonky2/src/gates/mod.rs b/plonky2/src/gates/mod.rs index b490e12e..e349cf75 100644 --- a/plonky2/src/gates/mod.rs +++ b/plonky2/src/gates/mod.rs @@ -6,13 +6,14 @@ //! $$ a.b.q_M + a.q_L + b.q_R + c.q_O + q_C = 0 $$ //! //! where: -//! - q_M, q_L, q_R and q_O are boolean selectors, -//! - a, b and c are values used as inputs and output respectively, -//! - q_C is a constant (possibly 0). +//! - $q_M$, $q_L$, $q_R$ and $q_O$ are boolean selectors, +//! - $a$, $b$ and $c$ are values used as inputs and output respectively, +//! - $q_C$ is a constant (possibly 0). //! //! This allows expressing simple operations like multiplication, addition, etc. For -//! instance, to define a multiplication, one can set q_M=1, q_L=q_R=0, q_O = -1 and q_C = 0. -//! Hence, the gate equation simplifies to a.b - c = 0, or a.b = c. +//! instance, to define a multiplication, one can set $q_M=1$, $q_L=q_R=0$, $q_O = -1$ and $q_C = 0$. +//! +//! Hence, the gate equation simplifies to $a.b - c = 0$, or equivalently to $a.b = c$. //! //! However, such a gate is fairly limited for more complex computations. Hence, when a computation may //! require too many of these "vanilla" gates, or when a computation arises often within the same circuit, diff --git a/starky/.cargo/katex-header.html b/starky/.cargo/katex-header.html new file mode 100644 index 00000000..20723b5d --- /dev/null +++ b/starky/.cargo/katex-header.html @@ -0,0 +1 @@ +../../.cargo/katex-header.html \ No newline at end of file diff --git a/starky/Cargo.toml b/starky/Cargo.toml index 62a67ee7..a3f9b37c 100644 --- a/starky/Cargo.toml +++ b/starky/Cargo.toml @@ -25,3 +25,7 @@ plonky2 = { path = "../plonky2", default-features = false } [dev-dependencies] env_logger = { version = "0.9.0", default-features = false } + +# Display math equations properly in documentation +[package.metadata.docs.rs] +rustdoc-args = ["--html-in-header", ".cargo/katex-header.html"] diff --git a/util/.cargo/katex-header.html b/util/.cargo/katex-header.html new file mode 100644 index 00000000..20723b5d --- /dev/null +++ b/util/.cargo/katex-header.html @@ -0,0 +1 @@ +../../.cargo/katex-header.html \ No newline at end of file diff --git a/util/Cargo.toml b/util/Cargo.toml index 1ece1e57..758391c3 100644 --- a/util/Cargo.toml +++ b/util/Cargo.toml @@ -7,3 +7,7 @@ edition = "2021" [dev-dependencies] rand = { version = "0.8.5", default-features = false, features = ["getrandom"] } + +# Display math equations properly in documentation +[package.metadata.docs.rs] +rustdoc-args = ["--html-in-header", ".cargo/katex-header.html"]