Skip to content

Expand dimod.make_quadratic documentation #1415

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
iamashwin99 wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Expand dimod.make_quadratic documentation #1415

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2b9c399
Add example output for make_quadratic function
iamashwin99 Feb 23, 2026
548b385
Enhance docstring for make_quadratic function
iamashwin99 Feb 23, 2026
3103d0f
Update dimod/higherorder/utils.py
iamashwin99 Feb 23, 2026
708c4f1
Update dimod/higherorder/utils.py
iamashwin99 Feb 23, 2026
bb4f9bb
Update dimod/higherorder/utils.py based on JoelPasvolsky suggestion
iamashwin99 Feb 25, 2026
fb8aae9
Update dimod/higherorder/utils.py based on JoelPasvolsky suggestion
iamashwin99 Feb 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions dimod/higherorder/utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -297,10 +297,27 @@ def make_quadratic(poly: Union[Polynomial, BinaryPolynomial], strength: float,
Terms of the reduced polynomial are added to this binary quadratic model.
If not provided, a new binary quadratic model is created.

Returns:
:class:`~dimod.binary.BinaryQuadraticModel`: A binary quadratic model
with three types of variables:

* Original variables: Variables mapped directly from the input
polynomial (e.g., ``0``, ``1``, ``12``).
* Product variables: Intermediate variables introduced to reduce
higher-order terms, representing the product of two variables. These
are typically named by joining the original variables (e.g., ``0*1``
represents the product of ``0`` and ``1``).
* Auxiliary variables: Variables introduced to enforce the penalty
constraints that ensure the mathematical relationship of the product
variables holds true at the ground state (e.g., ``aux0,1`` enforces
the constraint for ``0*1``).

Examples:

>>> poly = {(0,): -1, (1,): 1, (2,): 1.5, (0, 1): -1, (0, 1, 2): -2}
>>> bqm = dimod.make_quadratic(poly, 5.0, dimod.SPIN)
>>> bqm
BinaryQuadraticModel({0: -3.5, 1: -1.5, '0*1': -2.5, 'aux0,1': -5.0, 2: 1.5}, {(1, 0): 1.5, ('0*1', 0): 2.5, ('0*1', 1): 2.5, ('aux0,1', 0): 5.0, ('aux0,1', 1): 5.0, ('aux0,1', '0*1'): 5.0, (2, '0*1'): -2.0}, 10.0, 'SPIN')
Comment on lines +319 to +320
Copy link
Contributor

@JoelPasvolsky JoelPasvolsky Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
>>> bqm
BinaryQuadraticModel({0: -3.5, 1: -1.5, '0*1': -2.5, 'aux0,1': -5.0, 2: 1.5}, {(1, 0): 1.5, ('0*1', 0): 2.5, ('0*1', 1): 2.5, ('aux0,1', 0): 5.0, ('aux0,1', 1): 5.0, ('aux0,1', '0*1'): 5.0, (2, '0*1'): -2.0}, 10.0, 'SPIN')
>>> list(bqm.variables)
[0, 1, '0*1', 'aux0,1', 2]

More readable and short.

Copy link
Author

@iamashwin99 iamashwin99 Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the full bqm would be a better description. It would also give hint about how the auxiliary qubits are generated. What do you think?

Copy link
Contributor

@JoelPasvolsky JoelPasvolsky Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unless it provides high value to users (e.g., a list of parameters, typical timing), we try to avoid long outputs because they're not easy to parse, make the example look daunting, and can require maintenance (e.g., the recent backward-incompatible NumPy update that changes formats). My thinking is that such a short example lets users easily copy & paste so those who want to see the exact BQM structure can do so without difficulty. The list output highlights the generated variables you describe and additional, more robust ways to provide an output with more information could be

>>> len(bqm.linear) + len(bqm.quadratic)
12

or

>>> print(bqm.to_polystring())
10 - 3.5*v0 - 1.5*v1 - 2.5*0*1 - 5*aux0,1 + 1.5*v2 + 1.5*v0*v1 + 2.5*v0*0*1 + 2.5*v1*0*1 + 5*v0*aux0,1 + 5*v1*aux0,1 + 5*0*1*aux0,1 - 2*0*1*v2

and even for the latter, preferably shorten it with ellipses for readability, something perhaps like:

>>> print(bqm.to_polystring())
10 - ... 2.5*0*1 - 5*aux0,1 + ... 2.5*v1*0*1 + 5*v0*aux0,1 + 5*v1*aux0,1 + ...

Can one of these or another robust & short output do most of the work? If yes, that would be preferable. Thank you!


"""
from dimod.generators import and_gate
Expand Down