From a4dbb9da6781eae380e80f446a64148ce92a1cb7 Mon Sep 17 00:00:00 2001
From: Brian Doolittle <brian.d.doolittle@gmail.com>
Date: Tue, 5 Dec 2023 18:08:31 -0500
Subject: [PATCH] nonclassicality witness docstring

---
 docs/src/LocalPolytope/facets.md              |  2 +-
 .../linear_nonclassicality_witnesses.jl       | 34 ++++++++++++++++---
 2 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/docs/src/LocalPolytope/facets.md b/docs/src/LocalPolytope/facets.md
index 375437f..5747933 100644
--- a/docs/src/LocalPolytope/facets.md
+++ b/docs/src/LocalPolytope/facets.md
@@ -7,7 +7,7 @@ CurrentModule = LocalPolytope
 facets
 ```
 
-## Obtaining Nonclassicality Witnesses through Linear Programming
+## Linear Programming of Facets
 
 ```@docs
 linear_nonclassicality_witness
diff --git a/src/LocalPolytope/linear_nonclassicality_witnesses.jl b/src/LocalPolytope/linear_nonclassicality_witnesses.jl
index df73a69..217c349 100644
--- a/src/LocalPolytope/linear_nonclassicality_witnesses.jl
+++ b/src/LocalPolytope/linear_nonclassicality_witnesses.jl
@@ -5,10 +5,36 @@
         verbose=false :: Bool
     ) :: Vector{Float64}
 
-Implements a linear program that obtains a linear inequality that witnesses the nonclassciality of
-the provided `test_behavior` (see https://arxiv.org/abs/1303.2849 Eq. 19). A complete set of
-enumerated vertices are required as input. The optimized facet inequality is returned in vector
-form with the classical bound being appended to the end.
+Obtains a linear inequality ``(\\mathbf{G}^\\star, \\beta^\\star)`` bounding the convex hull of the
+set of `vertices` (``\\mathcal{V}``) and is violated by the `test_behavior` ``(\\mathbf{P}\\notin \\text{Conv}(\\mathcal{V}))``.
+This task is achieved using the  linear program described by Brunner et al. in Eq. 19 of
+[https://arxiv.org/abs/1303.2849](https://arxiv.org/abs/1303.2849). The linear program is
+
+
+```math
+\\begin{align}
+    \\min_{(\\mathbf{G}, \\beta)} \\quad & \\langle \\mathbf{G},\\mathbf{P}\\rangle - \\beta & \\notag\\\\
+    \\text{s.t.} \\quad  & \\langle \\mathbf{G}, \\mathbf{V} \\rangle - \\beta \\leq 0 & \\quad \\forall \\;\\; \\mathbf{V} \\in \\mathcal{V}  \\notag\\\\
+    & \\langle \\mathbf{G}, \\mathbf{P} \\rangle \\leq 1 & \\notag\\\\
+\\end{align}
+```
+
+The solution to the linear program is a linear nonclassicality witness ``(\\mathbf{G}^\\star, \\beta^\\star)`` becuase the
+constraint ``\\lange\\mathbf{G}^\\star, \\mathbf{V} \\rangle - \\beta^\\star \\leq 0`` ensures that no behavior in the polytope
+``\\text{Conv}(\\mathcal{V})`` can violate the inequality. Provided that ``\\mathbf{P} \\notin \\text{Conv}(\\mathcal{V})``
+technique the output linear inequality witnesses the nonclassicality of the `test_behavior`.
+
+The optimized facet inequality ``(\\mathbf{G}^\\star, \\beta^\\star)`` is returned as a vector ``(G^\\star_{0,0}, \\dots, G^\\star_{Y,X}, -\\beta^\\star)``
+where ``G^\\star_{y,x}`` are the elements of ``\\mathbf{G}^\\star``.
+
+!!! note "Converting Output into Bell Game"
+    The linear programming software outputs numerical values that have numerical error. Moreover, the linear inequality is
+    scaled such that the classical bound is zero and the `test_behavior` score is one. In order to convert the output
+    inequality into a `BellGame`, care must be taken to obtain the correct scaling factor to ensure that elements are integers.
+
+!!! note "Classical Test Behavior"
+    If the `test_behavior` ``\\mathbf{P}`` is classical, meaning it satisfies ``\\mathbf{P}\\in\\text{Conv}(\\mathcal{V})``,
+    then the optimized linear inequality is the zeros vector.
 """
 function linear_nonclassicality_witness(
     vertices :: Vector{Vector{T}} where T <: Real,