Metadata-Version: 2.4
Name: dwave-optimization
Version: 0.7.0
Summary: Enables the formulation of nonlinear models for industrial optimization problems.
Author-Email: "D-Wave Inc." <tools@dwavesys.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Project-URL: Changelog, https://github.com/dwavesystems/dwave-optimization/releases
Project-URL: Documentation, https://docs.dwavequantum.com
Project-URL: Source Code, https://github.com/dwavesystems/dwave-optimization
Requires-Python: >=3.10
Requires-Dist: numpy>=1.21.3
Provides-Extra: all
Requires-Dist: dimod>=0.12.0; extra == "all"
Requires-Dist: scikit-learn>=1.6.0; extra == "all"
Description-Content-Type: text/x-rst

.. image:: https://img.shields.io/pypi/v/dwave-optimization.svg?style=svg
    :target: https://pypi.org/project/dwave-optimization

.. image:: https://img.shields.io/pypi/pyversions/dwave-optimization.svg?style=svg
    :target: https://pypi.python.org/pypi/dwave-optimization

.. image:: https://circleci.com/gh/dwavesystems/dwave-optimization.svg?style=svg
    :target: https://circleci.com/gh/dwavesystems/dwave-optimization

.. image:: https://raw.githubusercontent.com/dwavesystems/dwave-optimization/main/docs/_images/optimization_stride_logo_blue_light_dark.svg
    :class: only-light
    :target: https://docs.dwavequantum.com/en/latest/industrial_optimization/index.html
    :width: 225
    :align: left

.. start_optimization_about

**dwave-optimization** is an open-source library for formulating nonlinear optimization
models for use with D-Wave's Stride™ hybrid solver.
Models are constructed symbolically using an array-based syntax inspired by NumPy.

The package includes:

*   A class for nonlinear models used by the Stride quantum-classical
    hybrid nonlinear solver.
*   Model generators for common optimization problems.

.. end_optimization_about

Example Usage
=============

.. start_optimization_examples

The `quadratic assignment problem <https://w.wiki/HhHL>`_ problem is a combinatorial
optimization problem.
There are ``n`` facilities and ``n`` potential locations, a flow between each pair
of facilities, and a distance between each pair of locations.
The problem is to assign each facility to a location in order to minimize the
sum of each distance multiplied by each matching flow.

This small example builds a quadratic assignment using *dwave-optimization*
symbols. There is also a
`generator <https://docs.dwavequantum.com/en/latest/ocean/api_ref_optimization/generators.html>`_
for this problem.

.. code-block:: python

    from dwave.optimization import Model

    model = Model()

    flows = model.constant([[0, 4, 2],
                            [3, 0, 7],
                            [1, 8, 0]])
    distances = model.constant([[0, 1, 2],
                                [1, 0, 3],
                                [2, 3, 0]])

    assignment = model.list(3)

    model.minimize((flows * distances[assignment, :][:, assignment]).sum())

.. end_optimization_examples

For explanations of the terminology, see the
`Ocean glossary <https://docs.dwavequantum.com/en/latest/concepts/index.html>`_.

For a discussion about performance, see
`Performance Benchmarks <https://docs.dwavequantum.com/en/latest/industrial_optimization/index_vignettes.html>`_.

Installation
============

Installation from `PyPI <https://pypi.org/project/dwave-optimization>`_:

.. code-block:: bash

    pip install dwave-optimization

During package development, it is often convenient to use an editable install.
See `meson-python's editable installs
<https://meson-python.readthedocs.io/en/latest/how-to-guides/editable-installs.html>`_
for more details.

.. code-block:: bash

    pip install --group dev --group blas
    pip install --editable . \
        --no-build-isolation \
        --config-settings=editable-verbose=true \
        --config-settings=setup-args="-Dblas=enabled"

Testing
=======

All code should be thoroughly tested and all pull requests should include tests.

To run the Python tests, first install the package using an editable install
as described above. The tests can then be run with
`unittest <https://docs.python.org/3/library/unittest.html>`_.

.. code-block:: bash

    python -m unittest

To run the C++ tests, first install the project dependencies, then setup a
``meson`` build directory. You must configure the build as a debug build for
the tests to run.

.. code-block:: bash

    pip install --group dev --group blas
    meson setup build -Dbuildtype=debug -Dblas=enabled

You can then run the tests using
`meson's test framework <https://mesonbuild.com/Unit-tests.html>`_.

.. code-block:: bash

    meson test -Cbuild

To run the doctests, install the docs requirements:

.. code-block:: bash

    pip install --group docs

You can then run them using the `docs/Makefile`.

.. code-block:: bash

    make -C docs doctest
