Corrected errors in beta_range defaults, simplified discretization pf schedule, added documentation, and beta_schedule parameter

[jackraymond]

it makes sense to update neal default beta_range correcting inconsistencies and other anomalies:

• beta_range (per spin) is miscalculated, the energy gaps are wrong by a factor 2. To understand this consider the description in comments _default_ising_beta_range when applied to the one-spin problem H(s) = s (rate of excitations is not 1%, it is much lower, 0.01%). A correction is added.
• beta_range[1] under defaults only protects against single spin excitations, change to protect against a collection of spin excitations to allow ground states to be found for large problems. To understand this, consider the description (0.5.7) and defaults applied to a large system of independent spins H(s) = sum_i s_i (the ground state all -1 cannot be achieved for large N, with high probability without this change). A correction is added.
• get rid of wacky undocumened discretization issue that occurs when num_sweeps>1999 and not a multiple of 1000. This is corrected. Using parameters 'num_betas' and 'num_sweeps_per_beta' is much cleaner than using 'num_sweeps'.
• When num_betas = 1, set beta= beta_range[1] (the target model), rather than beta= beta_range[0] (fast mixing starting point). 1-beta value is an important special case that should be properly handled, and now is.
• Allow beta_schedule to be provided as a parameter bypassing linear and geometric defaulting routines. This involves adding optional parameter 'beta_schedule'. This gives users flexibility to work around issues with the defaults.
• Add some additional value checking
• Improved documentation

Performance of time to solution under defaults in a variety of standard models is not significantly changed at QPU relevant scales: 3 regular 3XORSAT, SK model, Viana Bray model, Code Division Multiple Access problems, pegasus structured spin-glasses and cubic lattice spin glasses have been tested. See internal (D-Wave) documentation for further details.

[randomir]

I love this update, @jackraymond! The new API makes much more sense! Few minor comments to follow in the review.

[jackraymond]

I had a discussion with benchmarking (Pau Farre) at D-Wave. The use of the dwave-neal sample() call is so widespread in benchmarking he indicated it would be extremely inconvenient to change the function signature. In this pull request I suggested num_sweeps -> replaced by two arguments (matching underlying C++ code) num_betas and num_sweeps_per_beta. As a compromise, I think a good solution would be just to add the argument num_sweeps_per_beta, along with a requirement that num_sweeps is integer divisible by num_sweeps_per_beta. I think it makes everyone happy, also maintains compatibility with the new 'beta_schedule' parameter.

[randomir]

Hey @pau557, could you please qualify the impact of the new default beta schedule on some standard problems? Ideally, compare it with the old behavior (neal in master). Thanks!

[codecov-commenter]

Codecov Report

Merging #91 (7c539d6) into master (27797d0) will decrease coverage by 14.45%. The diff coverage is 77.01%.

@@             Coverage Diff             @@
##           master      #91       +/-   ##
===========================================
- Coverage   98.66%   84.21%   -14.46%     
===========================================
  Files           3        3               
  Lines          75      133       +58     
===========================================
+ Hits           74      112       +38     
- Misses          1       21       +20     

Impacted Files	Coverage Δ
neal/sampler.py	83.06% <77.01%> (-15.43%)	:arrow_down:

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 27797d0...7c539d6. Read the comment docs.

[necaisej]

Merge conflict introduced by commit in master updating return type from Response to SampleSet; simple conflict should be resolved @jackraymond