add ising state analysis tools, closes #8

docs/src/api.md

@@ -32,6 +32,14 @@ AS_CIRCULAR
 AS_DW_QUADRATIC
 ```
 
+## Ising Functions
+```@autodocs
+Modules = [QuantumAnnealing]
+Pages   = ["ising.jl"]
+Order   = [:function]
+Private  = true
+```
+
 # D-Wave Functions
 ```@autodocs
 Modules = [QuantumAnnealing]

src/ising.jl

@@ -1,6 +1,9 @@
 ### Helper Functions for Classical Ising Models ###
 
-
+"""
+given a state vector of spin values and an Ising model
+computes the energy of that spin configuration
+"""
 function eval_ising_state_energy(spin_state::Vector, ising_model::Dict)
     energy = 0.0
     for (ids,v) in ising_model
@@ -13,7 +16,10 @@ function eval_ising_state_energy(spin_state::Vector, ising_model::Dict)
     return energy
 end
 
-function compute_state_energies(ising_model::Dict)
+"""
+given an Ising model computes a mapping from state integers to energy values
+"""
+function compute_ising_state_energies(ising_model::Dict)
     n = _check_ising_model_ids(ising_model)
 
     state_energy = Dict{Int,Float64}()
@@ -26,8 +32,11 @@ function compute_state_energies(ising_model::Dict)
     return state_energy
 end
 
-function print_state_energies(ising_model::Dict)
-    state_energies = compute_state_energies(ising_model)
+"""
+given an Ising model computes a mapping from energy values to collections of state integers
+"""
+function compute_ising_energy_levels(ising_model::Dict)
+    state_energies = compute_ising_state_energies(ising_model)
 
     energy_levels = Dict{Float64,Set{Int}}()
     for (state_id, energy) in state_energies
@@ -37,10 +46,26 @@ function print_state_energies(ising_model::Dict)
         push!(energy_levels[energy], state_id)
     end
 
-    energies = sort(collect(keys(energy_levels)))
+    return energy_levels
+end
 
-    n = round(Int, log2(length(state_energies)))
+"""
+given an Ising model prints state strings by ascending energy levels
+"""
+function print_ising_energy_levels(ising_model::Dict)
+    n = 1
 
+    for (k,v) in ising_model
+        for qid in k
+            if qid > n
+                n = qid
+            end
+        end
+    end
+
+    energy_levels = compute_ising_energy_levels(ising_model)
+
+    energies = sort(collect(keys(energy_levels)))
 
     for energy in energies
         state_ids = energy_levels[energy]
@@ -51,5 +76,4 @@ function print_state_energies(ising_model::Dict)
             println("   $(state_string)")
         end
     end
-
 end

test/base.jl

@@ -40,32 +40,40 @@
 end
 
 @testset "ising energy computations" begin
+
     @testset "single qubit, single state" begin
         @test isapprox(eval_ising_state_energy([1],Dict((1,) => 1)), 1)
         @test isapprox(eval_ising_state_energy([-1],Dict((1,) => 1)), -1)
     end
 
     @testset "single qubit, all states" begin
-        energies = compute_state_energies(Dict((1,) => 1))
+        energies = compute_ising_state_energies(Dict((1,) => 1))
         @test isapprox(energies[0], 1)
         @test isapprox(energies[1], -1)
     end
 
-    @testset "double qubit, single state" begin
+    @testset "two qubit, single state" begin
         ising_model = Dict((1,) => 1, (2,) => 1, (1,2) => -1)
         @test isapprox(eval_ising_state_energy([1, 1], ising_model), 1)
         @test isapprox(eval_ising_state_energy([1, -1], ising_model), 1)
         @test isapprox(eval_ising_state_energy([-1, 1], ising_model), 1)
         @test isapprox(eval_ising_state_energy([-1, -1], ising_model), -3)
     end
 
-    @testset "double qubit, all states" begin
-        energies = compute_state_energies(Dict((1,) => 1, (2,) => 1, (1,2) => -1))
-        @test isapprox(energies[0], 1)
-        @test isapprox(energies[1], 1)
-        @test isapprox(energies[2], 1)
-        @test isapprox(energies[3], -3)
-    end 
+    @testset "two qubit, all state energies" begin
+        energies = compute_ising_state_energies(Dict((1,) => 1, (1,2) => -1))
+        @test isapprox(energies[0], 0)
+        @test isapprox(energies[1], 0)
+        @test isapprox(energies[2], 2)
+        @test isapprox(energies[3], -2)
+    end
+
+    @testset "two qubit, energy levels" begin
+        energy_levels = compute_ising_energy_levels(Dict((1,2) => -1))
+        @test energy_levels[-1.0] == Set([0,3])
+        @test energy_levels[1.0] == Set([1,2])
+    end
+
 end
 
 @testset "csv annealing schedules" begin