Add math rendering with Katex (#1459)

.cargo/katex-header.html

@@ -0,0 +1,30 @@
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css"
+    integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous">
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.js"
+    integrity="sha384-y23I5Q6l+B6vatafAwxRu/0oK/79VlbSz7Q9aiSZUvyWYIYsd+qj+o24G5ZU2zJz"
+    crossorigin="anonymous"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/contrib/auto-render.min.js"
+    integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI"
+    crossorigin="anonymous"></script>
+<script>
+    document.addEventListener("DOMContentLoaded", function () {
+        renderMathInElement(document.body, {
+            fleqn: false,
+            macros: {
+                "\\F": "\\mathbb{F}",
+                "\\G": "\\mathbb{G}",
+                "\\O": "\\mathcal{O}",
+                "\\(": "\\left(",
+                "\\)": "\\right)",
+                "\\norm": "\\left\\vert #1 \\right\\vert",
+                "\\set": "\\mathcal{ #1 }",
+            },
+            delimiters: [
+                { left: "$$", right: "$$", display: true },
+                { left: "\\(", right: "\\)", display: false },
+                { left: "$", right: "$", display: false },
+                { left: "\\[", right: "\\]", display: true }
+            ]
+        });
+    });
+</script>

evm/.cargo/katex-header.html

@@ -0,0 +1 @@
+../../.cargo/katex-header.html

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"]

field/.cargo/katex-header.html

@@ -0,0 +1 @@
+../../.cargo/katex-header.html

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"]

maybe_rayon/.cargo/katex-header.html

@@ -0,0 +1 @@
+../../.cargo/katex-header.html

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"]

plonky2/.cargo/katex-header.html

@@ -0,0 +1 @@
+../../.cargo/katex-header.html

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"]

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<F: RichField + Extendable<D>, const D: usize> {
     pub subgroup_bits: usize,

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,

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,

starky/.cargo/katex-header.html

@@ -0,0 +1 @@
+../../.cargo/katex-header.html

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"]

util/.cargo/katex-header.html

@@ -0,0 +1 @@
+../../.cargo/katex-header.html

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"]