Add notes on units to docs (#23)

* add notes on units to docs
* add factor of 2pi to dwave parse annealing schedule parser
* add note to changelog
closes #17

CHANGELOG.md

@@ -5,6 +5,7 @@ QuantumAnnealing.jl Change Log
 - Add variant of `solve_de` with adaptive solve tolerance
 - Add tools for working with classical Ising models (#8)
 - Add data processing tools (#6)
+- Fix units in dwave annealing schedules (#17)
 
 ### v0.0.1
 - Initial release

docs/src/index.md

@@ -8,7 +8,7 @@ CurrentModule = QuantumAnnealing
 
 QuantumAnnealing is a Julia package for simulation of quantum annealing protocols.
 Due to the complexity of modeling quantum systems QuantumAnnealing is not expected to scale to systems with more than 20 qubits.
-QuantumAnnealing provides tools for emulating the quantum annealing protocols that are implemented in hardware by D-Wave Systems.
+QuantumAnnealing also provides tools for emulating the quantum annealing protocols that are implemented in hardware by D-Wave Systems.
 
 
 ## Installation
@@ -35,7 +35,7 @@ Test that the package works by running
 ## What is Quantum Annealing?
 
 The objective of QuantumAnnealing is to solve ODEs arising in dynamic quantum systems.
-Specifically it solves the Schrödinger equation with a time dependent Hamiltonian $H(t)$, acting over a set of 1-to-$n$ qubits, as follows,
+Specifically it solves the Schrödinger equation with a time dependent Hamiltonian $H(t)$, acting over a set of $n$ qubits in natural units, as follows,
 ```math
 i \frac{d}{dt}\left|\Psi(t)\right\rangle = H(t)\left|\Psi(t)\right\rangle
 ```
@@ -156,3 +156,10 @@ QuantumAnnealing assumes that annealing functions are univariate and specified o
 The sign conventions of this implementation ensure that:
 - Hamiltonians with positive fields, i.e. $h>0$, are minimized by $\left|\downarrow\right\rangle$ states in the adiabatic limit.
 - Hamiltonians with negative couplings, i.e. $J<0$, are ferromagnetic and are minimized by $\left|\uparrow \uparrow \right\rangle$ and $\left|\downarrow \downarrow \right\rangle$ states in the adiabatic limit.
+
+
+### Units
+
+The underlying mathematics of QuantumAnnealing assumes a natural unit system. However, in practice it is convent to define the annealing schedule in terms of gigahertz (GHz) and in this case after applying a suitable Plank constant the annealing time has units of nanoseconds.
+The Ising model parameters are not assumed to be given any particular units but it is common to use values of $h,J$ in the range of -1.0-to-1.0.
+

src/dwave.jl

@@ -20,11 +20,11 @@ const AS_DW_QUADRATIC = AnnealingSchedule(
         if s >= 0.69
             return 0
         else
-            return -6.366401*((1.449275)^2*s^2 + (-2.898551)*s + 1.0)/2.0
+            return (6.366401*((1.449275)^2*s^2 + (-2.898551)*s + 1.0)*(2.0*π))/-2.0
         end
     end,
     function B(s)
-        return 14.55571*(0.85*s^2 + 0.15*s + 0.0)/2.0
+        return (14.55571*(0.85*s^2 + 0.15*s + 0.0)*(2.0*π))/2.0
     end,
     default_dwave_initial_state
 )
@@ -154,6 +154,10 @@ function parse_dwave_annealing_schedule(infile; header=1, delim=',', interpolati
         push!(b_values, row[3])
     end
 
+    # change from GHz to natural units (annealing time in nanoseconds)
+    a_values = a_values .* (2.0*π)
+    b_values = b_values .* (2.0*π)
+
     # rescale and swap sign based on D-Wave hamiltonian convention
     # https://docs.dwavesys.com/docs/latest/c_qpu_annealing.html
     a_values = a_values ./ -2.0

test/base.jl

@@ -144,7 +144,7 @@ end
 
     @testset "piecewise constant" begin
         deltas = [AS_CIRCULAR.A(s) - AS_CIRCULAR_pwc_csv_100.A(s) for s in s_100]
-        @test isapprox(maximum(abs.(deltas)), 0.0)
+        @test isapprox(maximum(abs.(deltas)), 0.0, atol=1e-15)
 
         deltas = [AS_CIRCULAR.A(s) - AS_CIRCULAR_pwc_csv_100.A(s) for s in s_10000]
         @test isapprox(maximum(abs.(deltas)), 0.015708868493240165, atol=1e-5)

test/data/generate_schedule_csvs.jl

@@ -2,8 +2,8 @@ using DelimitedFiles
 
 # add a factor of 2x and sign inversion based on D-Wave Hamiltonian convention
 # https://docs.dwavesys.com/docs/latest/c_qpu_annealing.html
-A = (s) -> -2.0*cos(π/2*s)
-B = (s) ->  2.0*sin(π/2*s)
+A = (s) -> -2.0*cos(π/2*s)/(2.0*π)
+B = (s) ->  2.0*sin(π/2*s)/(2.0*π)
 
 header = ["s", "A(s)", "B(s)"]
 

test/data/trig_sched_100.csv

@@ -1,101 +1,101 @@
 s,A(s),B(s)
-0.0,-2.0,0.0
-0.010101010101010102,-1.9997482553477501,0.031731927669615856
-0.020202020202020204,-1.9989930847663702,0.0634558669961353
-0.030303030303030304,-1.997734678366016,0.09516383164748458
-0.04040404040404041,-1.9959733529437689,0.126847839313129
-0.050505050505050504,-1.9937095519038848,0.1584999137135769
-0.06060606060606061,-1.9909438451461692,0.19011208660836532
-0.0707070707070707,-1.9876769289225082,0.221676399802022
-0.08080808080808081,-1.9839096256615907,0.25318490714749853
-0.09090909090909091,-1.9796428837618654,0.2846296765465703
-0.10101010101010101,-1.9748777773527886,0.3160027919466998
-0.1111111111111111,-1.969615506024416,0.34729635533386066
-0.12121212121212122,-1.9638573945254134,0.3785024887208204
-0.13131313131313133,-1.9576048924295575,0.40961333613038137
-0.1414141414141414,-1.950859573770814,0.4406210655730812
-0.15151515151515152,-1.9436231366470833,0.47151787101885445
-0.16161616161616163,-1.9358974027927125,0.5022959743621584
-0.1717171717171717,-1.927684317119884,0.53294762738007
-0.18181818181818182,-1.9189859472289947,0.5634651136828593
-0.1919191919191919,-1.9098044828881477,0.5938407506565497
-0.20202020202020202,-1.9001422354818909,0.6240668913969741
-0.21212121212121213,-1.890001637429337,0.6541359266348432
-0.2222222222222222,-1.8793852415718169,0.6840402866513374
-0.23232323232323232,-1.8682957205302135,0.7137724431837437
-0.24242424242424243,-1.8567358660321451,0.743324911320655
-0.25252525252525254,-1.8447085882091627,0.7726902513862574
-0.26262626262626265,-1.8322169148641392,0.8018610708132274
-0.2727272727272727,-1.8192639907090369,0.8308300260037728
-0.2828282828282828,-1.8058530765732426,0.8595898241783432
-0.29292929292929293,-1.7919875485826717,0.8881332252115481
-0.30303030303030304,-1.777670897309847,0.9164530434548208
-0.31313131313131315,-1.7629067268951641,0.9445421495453654
-0.32323232323232326,-1.7476987541395699,0.9723934722009374
-0.3333333333333333,-1.7320508075688774,0.9999999999999999
-0.3434343434343434,-1.7159668264699541,1.0273547831468126
-0.35353535353535354,-1.6994508598990288,1.0544509352210047
-0.36363636363636365,-1.6825070656623624,1.081281634911195
-0.37373737373737376,-1.6651397092695426,1.1078401277322205
-0.3838383838383838,-1.6473531628596656,1.1341197277255415
-0.3939393939393939,-1.6291519041006715,1.1601138191423963
-0.40404040404040403,-1.6105405150621173,1.1858158581092808
-0.41414141414141414,-1.5915236810616642,1.2112193742753334
-0.42424242424242425,-1.572106189485575,1.2363179724412103
-0.43434343434343436,-1.5522929285835136,1.261105334169045
-0.4444444444444444,-1.532088886237956,1.2855752193730785
-0.45454545454545453,-1.5114991487085168,1.30972146789057
-0.46464646464646464,-1.4905288993515096,1.3335380010325832
-0.47474747474747475,-1.4691834173150666,1.3570188231142644
-0.48484848484848486,-1.4474680762101404,1.3801580229642239
-0.494949494949495,-1.4253883427577259,1.4029497754126425
-0.5050505050505051,-1.4029497754126425,1.4253883427577259
-0.5151515151515151,-1.380158022964224,1.4474680762101404
-0.5252525252525253,-1.3570188231142644,1.4691834173150666
-0.5353535353535354,-1.3335380010325832,1.4905288993515093
-0.5454545454545454,-1.3097214678905702,1.5114991487085165
-0.5555555555555556,-1.2855752193730787,1.532088886237956
-0.5656565656565656,-1.261105334169045,1.5522929285835136
-0.5757575757575758,-1.2363179724412103,1.572106189485575
-0.5858585858585859,-1.2112193742753334,1.5915236810616642
-0.5959595959595959,-1.1858158581092813,1.610540515062117
-0.6060606060606061,-1.1601138191423963,1.6291519041006715
-0.6161616161616161,-1.1341197277255415,1.6473531628596656
-0.6262626262626263,-1.1078401277322205,1.6651397092695428
-0.6363636363636364,-1.0812816349111953,1.6825070656623622
-0.6464646464646465,-1.0544509352210047,1.6994508598990288
-0.6565656565656566,-1.0273547831468128,1.715966826469954
-0.6666666666666666,-1.0000000000000002,1.7320508075688772
-0.6767676767676768,-0.9723934722009373,1.7476987541395699
-0.6868686868686869,-0.9445421495453654,1.7629067268951641
-0.696969696969697,-0.9164530434548209,1.777670897309847
-0.7070707070707071,-0.8881332252115485,1.7919875485826717
-0.7171717171717171,-0.8595898241783435,1.8058530765732423
-0.7272727272727273,-0.8308300260037729,1.8192639907090367
-0.7373737373737373,-0.8018610708132275,1.8322169148641392
-0.7474747474747475,-0.7726902513862571,1.844708588209163
-0.7575757575757576,-0.743324911320655,1.8567358660321451
-0.7676767676767676,-0.7137724431837438,1.8682957205302133
-0.7777777777777778,-0.6840402866513376,1.8793852415718166
-0.7878787878787878,-0.6541359266348435,1.890001637429337
-0.797979797979798,-0.6240668913969742,1.9001422354818909
-0.8080808080808081,-0.5938407506565498,1.9098044828881477
-0.8181818181818182,-0.5634651136828592,1.9189859472289947
-0.8282828282828283,-0.53294762738007,1.927684317119884
-0.8383838383838383,-0.5022959743621584,1.9358974027927125
-0.8484848484848485,-0.47151787101885456,1.9436231366470833
-0.8585858585858586,-0.4406210655730815,1.950859573770814
-0.8686868686868687,-0.4096133361303813,1.9576048924295575
-0.8787878787878788,-0.37850248872082043,1.9638573945254134
-0.8888888888888888,-0.34729635533386083,1.969615506024416
-0.898989898989899,-0.31600279194670006,1.9748777773527886
-0.9090909090909091,-0.2846296765465707,1.9796428837618654
-0.9191919191919192,-0.2531849071474986,1.9839096256615907
-0.9292929292929293,-0.2216763998020222,1.9876769289225082
-0.9393939393939394,-0.19011208660836518,1.9909438451461692
-0.9494949494949495,-0.15849991371357688,1.9937095519038848
-0.9595959595959596,-0.12684783931312912,1.9959733529437689
-0.9696969696969697,-0.0951638316474848,1.997734678366016
-0.9797979797979798,-0.06345586699613563,1.9989930847663702
-0.98989898989899,-0.03173192766961586,1.9997482553477501
-1.0,-1.2246467991473532e-16,2.0
+0.0,-0.3183098861837907,0.0
+0.010101010101010102,-0.3182698197779882,0.005050293142453851
+0.020202020202020204,-0.31814963064708396,0.010099314900616793
+0.030303030303030304,-0.3179493490480491,0.015145794210262117
+0.04040404040404041,-0.3176690254007051,0.020188460647210933
+0.050505050505050504,-0.3173087302750309,0.025226044747154657
+0.06060606060606061,-0.31686855437339784,0.03025727832523586
+0.0707070707070707,-0.3163486085077351,0.03528089479530705
+0.08080808080808081,-0.31574902357163387,0.040295629488786934
+0.09090909090909091,-0.3150699505073953,0.045300219973033976
+0.10101010101010101,-0.3143115602680318,0.050293406369157044
+0.1111111111111111,-0.3134740437742306,0.055273931669183256
+0.12121212121212122,-0.31255761186629005,0.06024054205250293
+0.13131313131313133,-0.3115624952510421,0.06519198720151224
+0.1414141414141414,-0.3104889444437731,0.07012702061637403
+0.15151515151515152,-0.30933722970515765,0.07504439992881742
+0.16161616161616163,-0.30810764097322213,0.07994288721489745
+0.1717171717171717,-0.3068004877903543,0.08482124930663568
+0.18181818181818182,-0.30541609922537755,0.08967825810246381
+0.1919191919191919,-0.30395482379070976,0.09451269087639158
+0.20202020202020202,-0.30241702935462716,0.09932333058582145
+0.21212121212121213,-0.30080310304865515,0.1041089661779327
+0.2222222222222222,-0.2991134511701105,0.10886839289455738
+0.23232323232323232,-0.29734849907981775,0.11360041257547182
+0.24242424242424243,-0.2955086910950271,0.118303833960027
+0.25252525252525254,-0.2935944903775599,0.12297747298704209
+0.26262626262626265,-0.29160637881721013,0.12762015309288546
+0.2727272727272727,-0.2895448569104312,0.13223070550766838
+0.2828282828282828,-0.28741044363433854,0.13680796954947652
+0.29292929292929293,-0.28520367631606014,0.1413507929165654
+0.30303030303030304,-0.2829251104974672,0.1458580319774463
+0.31313131313131315,-0.28057531979531936,0.15032855205878914
+0.32323232323232326,-0.27815489575685964,0.1547612277310707
+0.3333333333333333,-0.27566444771089604,0.15915494309189532
+0.3434343434343434,-0.2731046026144058,0.16350859204691745
+0.35353535353535354,-0.2704760048947025,0.16782107858829484
+0.36363636363636365,-0.2677793162872051,0.17209131707060282
+0.37373737373737376,-0.2650152156688492,0.17631823248413964
+0.3838383838383838,-0.26218439888718387,0.1805007607255544
+0.3939393939393939,-0.2592875785851953,0.18463784886572945
+0.40404040404040403,-0.2563254840219031,0.18872845541484962
+0.41414141414141414,-0.25329886088877296,0.19277155058459178
+0.42424242424242425,-0.2502084711219931,0.19676611654736825
+0.43434343434343436,-0.24705509271066067,0.20071114769256002
+0.4444444444444444,-0.24383951950092722,0.20460565087967317
+0.45454545454545453,-0.24056256099615225,0.2084486456883573
+0.46464646464646464,-0.2372250421531149,0.21223916466522066
+0.47474747474747475,-0.23382780317433577,0.21597625356738154
+0.48484848484848486,-0.23037169929656012,0.21965897160269382
+0.494949494949495,-0.22685760057545687,0.22328639166658648
+0.5050505050505051,-0.22328639166658648,0.22685760057545687
+0.5151515151515151,-0.21965897160269388,0.23037169929656012
+0.5252525252525253,-0.21597625356738154,0.23382780317433577
+0.5353535353535354,-0.21223916466522066,0.23722504215311488
+0.5454545454545454,-0.20844864568835733,0.2405625609961522
+0.5555555555555556,-0.20460565087967322,0.24383951950092722
+0.5656565656565656,-0.20071114769256002,0.24705509271066067
+0.5757575757575758,-0.19676611654736825,0.2502084711219931
+0.5858585858585859,-0.19277155058459178,0.25329886088877296
+0.5959595959595959,-0.1887284554148497,0.256325484021903
+0.6060606060606061,-0.18463784886572945,0.2592875785851953
+0.6161616161616161,-0.1805007607255544,0.26218439888718387
+0.6262626262626263,-0.17631823248413964,0.2650152156688492
+0.6363636363636364,-0.17209131707060285,0.2677793162872051
+0.6464646464646465,-0.16782107858829484,0.2704760048947025
+0.6565656565656566,-0.16350859204691748,0.2731046026144058
+0.6666666666666666,-0.15915494309189537,0.27566444771089604
+0.6767676767676768,-0.1547612277310707,0.27815489575685964
+0.6868686868686869,-0.15032855205878914,0.28057531979531936
+0.696969696969697,-0.14585803197744632,0.2829251104974672
+0.7070707070707071,-0.14135079291656547,0.28520367631606014
+0.7171717171717171,-0.13680796954947658,0.2874104436343385
+0.7272727272727273,-0.1322307055076684,0.28954485691043114
+0.7373737373737373,-0.1276201530928855,0.29160637881721013
+0.7474747474747475,-0.12297747298704206,0.2935944903775599
+0.7575757575757576,-0.118303833960027,0.2955086910950271
+0.7676767676767676,-0.11360041257547185,0.2973484990798177
+0.7777777777777778,-0.10886839289455742,0.29911345117011046
+0.7878787878787878,-0.10410896617793275,0.30080310304865515
+0.797979797979798,-0.09932333058582146,0.30241702935462716
+0.8080808080808081,-0.09451269087639161,0.30395482379070976
+0.8181818181818182,-0.0896782581024638,0.30541609922537755
+0.8282828282828283,-0.08482124930663568,0.3068004877903543
+0.8383838383838383,-0.07994288721489745,0.30810764097322213
+0.8484848484848485,-0.07504439992881745,0.30933722970515765
+0.8585858585858586,-0.07012702061637408,0.3104889444437731
+0.8686868686868687,-0.06519198720151223,0.3115624952510421
+0.8787878787878788,-0.060240542052502934,0.31255761186629005
+0.8888888888888888,-0.055273931669183284,0.3134740437742306
+0.898989898989899,-0.05029340636915709,0.3143115602680318
+0.9090909090909091,-0.04530021997303403,0.3150699505073953
+0.9191919191919192,-0.04029562948878694,0.31574902357163387
+0.9292929292929293,-0.035280894795307084,0.3163486085077351
+0.9393939393939394,-0.030257278325235837,0.31686855437339784
+0.9494949494949495,-0.02522604474715465,0.3173087302750309
+0.9595959595959596,-0.02018846064721095,0.3176690254007051
+0.9696969696969697,-0.015145794210262154,0.3179493490480491
+0.9797979797979798,-0.010099314900616847,0.31814963064708396
+0.98989898989899,-0.005050293142453852,0.3182698197779882
+1.0,-1.9490859162596877e-17,0.3183098861837907