Merge pull request #18 from ChitambarLab/chsh-user-guide

Chsh user guide

CITATION.bib

@@ -3,7 +3,7 @@ @misc{BellScenario.jl
 	title   = {BellScenario.jl},
 	howpublished =  {\url{https://github.com/ChitambarLab/BellScenario.jl}},
 	url     = {https://github.com/ChitambarLab/BellScenario.jl},
-	version = {v0.1.1},
+	version = {v0.1.2},
 	year    = {2020},
 	month   = {6}
 }

Project.toml

@@ -1,14 +1,15 @@
 name = "BellScenario"
 uuid = "4e58fcc1-4405-48af-b0f2-42df636d9190"
 authors = ["Brian Doolittle"]
-version = "0.1.1"
+version = "0.1.2"
 
 [deps]
 Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
 Convex = "f65535da-76fb-5f13-bab9-19810c17039a"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Polyhedra = "67491407-f73d-577b-9b50-8179a7c68029"
 QBase = "e52e8ede-12bf-4731-8af7-b01f6064cb11"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SCS = "c946c3f1-0d1f-5ce8-9dea-7daa1f7e2d13"
@@ -18,6 +19,7 @@ XPORTA = "8c143463-af6f-456f-8aed-72447cb569d2"
 Combinatorics = "1"
 Convex = "0.14"
 JSON = "0.21"
+Polyhedra = "0.6"
 QBase = "0.2"
 SCS = "0.7"
 XPORTA = "0.1"

docs/src/LocalPolytope/vertices.md

@@ -5,10 +5,17 @@ CurrentModule = LocalPolytope
 
 Vertices are extreme points of the local polytope.
 They correspond to deterministic strategies.
+The vertex representation of a convex polytope can be computed via the
+[Polyhedra.jl](https://github.com/JuliaPolyhedra/Polyhedra.jl) interface.
+
+```@docs
+vrep
+```
 
 ## Vertex Enumeration
 
-Enumerate the local polytope vertices for the specified Bell [`Scenario`](@ref).
+The vertices of each local polytope can be enumerated for the specified
+Bell [`Scenario`](@ref).
 
 ```@docs
 vertices

docs/src/user_guide.md

@@ -1,5 +1,102 @@
 # User Guide
 
+## Quickstart
+
 ```julia
-using Pkg; Pkg.add("BellScenario")
+julia> using Pkg; Pkg.add("BellScenario")
+```
+
+```@example tutorial
+using BellScenario
+```
+
+## CHSH Scenario
+
+The CHSH scenario is a [`BipartiteNonSignaling`](@ref) scenario where Alice and Bob
+each have a black-box with binary inputs and outputs.
+
+![Classical CHSH Scenario](assets/scenario_images/classical_chsh_scenario.png)
+
+This scenario is significant because it is the simplest Bell scenario in which
+quantum nonlocality can be observed.
+We will use BellScenario.jl to compute the CH Bell inequality and optimize quantum
+measurements to violate the CH inequality.
+First, create a CHSH `Scenario` to specify the black-box arrangement in the figure
+above.
+
+```@example tutorial
+# (num_out_A, num_out_B, num_in_A, num_in_B)
+chsh_scenario = BipartiteNonSignaling(2,2,2,2)
+```
+
+Bell inequalities bound the set of local (classical) correlations.
+The local set is a convex polytope referred to as the *local polytope* and the
+facets of the local polytope are Bell inequalities.
+The standard method of computing Bell inequalities is to first compute the local
+polytope vertices, then apply a polytope transformation algorithm to compute the
+Bell inequalities.
+
+The BellScenario.jl package provides the [`LocalPolytope`](@ref) module to compute
+Bell inequalities.
+The first step is to commpute the vertex representation for the CHSH scenario.
+
+```@example tutorial
+chsh_polytope = LocalPolytope.vrep(chsh_scenario)
+```
+
+Then, the Bell inequalities can computed using the [`LocalPolytope.facets`](@ref)
+function.
+
+```@example tutorial
+chsh_facets = LocalPolytope.facets(chsh_polytope)
+```
+
+We'll take ``15^{th}`` facet as it represents the CH inequality
+
+```math
+- P_A(1|2) - P_B(1|1) + P(11|11) - P(11|12) + P(11|21) + P(11|22) \leq 0.
+```
+
+In fact, this inequality is equivalent to the more celebrated CHSH inequality.
+The difference is that the CH inequality is expressed in terms of probabilities
+whereas the CHSH inequality is expressed in terms of bipartite correlators.
+
+```@example tutorial
+ch_inequality = chsh_facets[15]
+```
+
+Now that we have computed a Bell inequality, we can find a quantum violation using
+the [`Nonlocality`](@ref) module.
+In this example, we will fix Alice's measurement and the quantum state shared
+between Alice and Bob.
+
+```@example tutorial
+# maximally entangled state
+ρ_AB = [1 0 0 1;0 0 0 0;0 0 0 0;1 0 0 1]/2
+
+# Alice's measurement bases
+Π_ax = [
+    [[1 0;0 0], [0 0;0 1]],      # Pauli Z basis
+    [[1 1;1 1]/2, [1 -1;-1 1]/2] # Pauli X basis
+]
+```
+
+Then, we convert the `ch_inequality` into a general representation of a [`BellGame`](@ref).
+
+```@example tutorial
+ch_game = convert(BellGame, ch_inequality, chsh_scenario)
+```
+
+Finally, we optimize Bob's measurement with respect to the fixed state and measurements.
+
+```@example tutorial
+opt_dict = Nonlocality.optimize_measurement(
+    chsh_scenario, ch_game, ρ_AB, A_POVMs=Π_ax
+)
+```
+
+We see that the inequality is violated for the optimized measurement and states.
+
+```@example tutorial
+opt_dict["violation"]
 ```

src/LocalPolytope/LocalPolytope.jl

@@ -45,21 +45,45 @@ however, it is important to note that a Bell violation can simply mean that more
 resources were used than anticipated.
 
 ### Module Exports:
-* [`vertices`](@ref) - Compute the set of extreme-points for the Local Polytope.
-* [`facets`](@ref) - Compute the linear inequalities which bound the Local Polytope.
+* [`vertices`](@ref) - Compute the set of extreme-points for the local polytope.
+* [`num_vertices`](@ref) - The number of vertices for the local polytope.
+* [`vrep`](@ref) - Construct a [`Polyhedron`](https://juliapolyhedra.github.io/Polyhedra.jl/stable/polyhedron/)
+    in the vertex representation.
+* [`facets`](@ref) - Compute the linear inequalities which bound the local polytope.
 * [`generator_vertex`](@ref) - Provide a canonical form for a vertex.
 * [`generator_facet`](@ref) - Provide a canonical form for a facet.
-* [`adjacency_decomposition`](@ref) - Efficiently compute the generating facets for the Local
-    Polytope using the adjacency decomposition technique.
+* [`adjacency_decomposition`](@ref) - Efficiently compute the generator facets for the local
+    polytope using the adjacency decomposition technique.
 """
 module LocalPolytope
 
 using LinearAlgebra, Combinatorics
-using XPORTA
+using XPORTA, Polyhedra
+
+import Polyhedra: vrep
 
 using ..BellScenario
 
 include("./vertices.jl")
+
+"""
+    vrep(scenario::Scenario; vertices_kwargs...) :: XPORTA.Polyhedron
+
+Constructs a `Polyhedron` using the vertex representation.
+See [Polyhedra.jl](https://github.com/JuliaPolyhedra/Polyhedra.jl)
+for more details.
+The `vertices_kwargs` keyword arguments are passed through to the `vertices`
+function for each `Scenario`.
+
+!!! note "Return Type"
+    This function differs from the Polyhedra.jl implementation in that it returns
+    a `Polyhedron` type rather than a `V-Representation`.
+    This is done to reduce the number of steps required to construct a polyhedron.
+"""
+function vrep(scenario::Scenario; vertices_kwargs...) :: XPORTA.Polyhedron
+    polyhedron(vrep(vertices(scenario; vertices_kwargs...)), XPORTA.Library())
+end
+
 include("./facets.jl")
 include("./generators.jl")
 include("./adjacency_decomposition.jl")

src/LocalPolytope/facets.jl

@@ -55,3 +55,15 @@ function facets(
         "equalities" => map(row_id -> equalities[row_id,:], 1:size(equalities,1))
     )
 end
+
+"""
+    facets(poly::Polyhedron) :: Vector{Vector{Int64}}
+
+Returns the facets of the local polytope `poly`. If the facets have not already
+been computed, then they are transformed into the half-space representation from
+the vertex representation.
+"""
+function facets(poly::Polyhedron) :: Vector{Vector{Int64}}
+    inequalities = convert.(Int64, hrep(poly).inequalities)
+    map(row_id -> inequalities[row_id,:] , 1:size(inequalities,1))
+end