add LinearAncillaComposite

[pau557]

In scenarios where the h biases are not available or sufficient in range, one can use auxiliary qubits polarized with a large flux bias and coupled to the data qubit. This method:

• Requires that each qubit is coupled to a non-programmed qubit
• But, ancilla qubits can be shared between data qubits
• The magnitude of the bias is limited by the magnitude of the coupler, but in the case of asymetric coupling range, one can use the strongest coupling available and control the bias sign with the flux bias sign

This PR adds a LinearAncillaComposite that implements this technique.

For the reviewers, please take into account future extensions of this method:

• One can use multiple ancilla qubits to extend the h-range and avoid shrinking energy scales of the problem. This is relevant for QUBO --> Ising translation.
• While the current implementation may work on embedded problems as is, we need an embedding-aware version that relaxes the condition of each qubit being coupled to an ancilla to each chain being coupled to at least one ancilla.

Please educate me on how to use the correct Sphynx syntax

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 83.33333% with 12 lines in your changes missing coverage. Please review.

Project coverage is 86.57%. Comparing base (b233941) to head (5867eba). Report is 31 commits behind head on master.

Files with missing lines	Patch %	Lines
dwave/system/composites/linear_ancilla.py	83.09%	12 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #530      +/-   ##
==========================================
- Coverage   89.65%   86.57%   -3.09%     
==========================================
  Files          24       25       +1     
  Lines        1760     1832      +72     
==========================================
+ Hits         1578     1586       +8     
- Misses        182      246      +64     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests

[pau557]

Any more comments or ready to merge?

[JoelPasvolsky]

Any more comments or ready to merge?

@pau557 there are comments I think you might have missed, especially ones that use GitHub Suggested Change that have not been added. Examples: 1, 2, 3, 4, 5, etc. Can you look through the comments again?

[pau557]

I had missed many comments, apologies @JoelPasvolsky. I think everything is addressed now

[randomir]

@pau557, I think we can merge this when docs comments are addressed.

[pau557]

How do I tell CircleCI not to run this example with a mock sampler?

/home/circleci/project/dwave/system/testing.py:325: UserWarning: 'flux_biases' parameter is valid for DWaveSampler(), but not mocked in MockDWaveSampler().
  warnings.warn(f'{kw!r} parameter is valid for DWaveSampler(), '
/home/circleci/project/dwave/system/testing.py:325: UserWarning: 'fast_anneal' parameter is valid for DWaveSampler(), but not mocked in MockDWaveSampler().
  warnings.warn(f'{kw!r} parameter is valid for DWaveSampler(), '
WARNING: **********************************************************************
File "../dwave/system/composites/linear_ancilla.py", line ?, in default
Failed example:
    sampleset.first.energy
Expected:
    -3
Got:
    1.0

[jackraymond]

How do I tell CircleCI not to run this example with a mock sampler?

/home/circleci/project/dwave/system/testing.py:325: UserWarning: 'flux_biases' parameter is valid for DWaveSampler(), but not mocked in MockDWaveSampler().
  warnings.warn(f'{kw!r} parameter is valid for DWaveSampler(), '
/home/circleci/project/dwave/system/testing.py:325: UserWarning: 'fast_anneal' parameter is valid for DWaveSampler(), but not mocked in MockDWaveSampler().
  warnings.warn(f'{kw!r} parameter is valid for DWaveSampler(), '
WARNING: **********************************************************************
File "../dwave/system/composites/linear_ancilla.py", line ?, in default
Failed example:
    sampleset.first.energy
Expected:
    -3
Got:
    1.0

You can mock the flux_biases parameter with h if you want this to behave correctly. You can also suppress the warnings. e.g. https://github.com/AndyZzzZzzZzz/shimming-tutorial/blob/development/tutorial_code/helpers/sampler_wrapper.py I think its worth testing

[JoelPasvolsky]

Looks like an incorrect rebase: did you miss pulling the latest master branch?

[pau557]

Looks like an incorrect rebase: did you miss pulling the latest master branch?

Yes, I did it wrong. @randomir is helping with it.

[randomir]

Because this PR was opened from a fork's master branch, rebasing would be messy, i.e. history would be pretty much lost.

In order to keep the conversation here relevant (and retain @pau557's authorship of commits), I have rebased in a new branch and verified all tests pass in a separate draft PR, https://github.com/dwavesystems/dwave-system/pull/546. So we can merge this as-is.