:py:mod:`qsearch.multistart_solvers`
====================================

.. py:module:: qsearch.multistart_solvers

.. autoapi-nested-parse::

   This module defines solvers that use multiple starting points in order to have a higher chance at finding the global minimum.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   qsearch.multistart_solvers.MultiStart_Solver
   qsearch.multistart_solvers.NaiveMultiStart_Solver



Functions
~~~~~~~~~

.. autoapisummary::

   qsearch.multistart_solvers.distance_for_x
   qsearch.multistart_solvers.optimize_worker



.. py:function:: distance_for_x(x, options, circuit)

   Calculate the distance between circuit and the target for input x based on the distance metric


.. py:function:: optimize_worker(circuit, options, q, x0, error_func)

   Worker function used to run the inner solver in parallel


.. py:class:: MultiStart_Solver(num_threads)

   Bases: :py:obj:`qsearch.solvers.Solver`

   A higher accuracy solver based on APOSMM https://www.mcs.anl.gov/~jlarson/APOSMM/

   MultiStart_Solver generally gets better results than other optimizers due to the advanced algorithm
   to start multiple local optimizers ("inner solvers") and find the global optimum more often.

   Create a MultiStart_Solver instance. Pass num_threads to set how many threads to use in parallel optimization runs

   .. py:method:: solve_for_unitary(self, circuit, options, x0=None)

      Optimize the given circuit based on the provided options with initial point x0 (optional).

      :param circuit: A qsearch.gates.Gate describing the circuit to optimize
      :param options: This uses the following options:
                      - inner_solver : which optimizer to use for local optimization runs
                      - target : the target unitary of synthesis
                      - logger : A qsearch.logging.Logger that will be used for logging the synthesis process.
                      - error_func : The function that the Solver will attempt to minimize.
                      - error_residuals : A function that returns an array of real-valued residuals to be used by a least-squares-based Solver.
      :param x0: the starting point for the optimzier



.. py:class:: NaiveMultiStart_Solver(num_threads)

   Bases: :py:obj:`qsearch.solvers.Solver`

   A naive but effective multi-start solver which tries to cover as much of the optimization space at once

   Create a NaiveMultiStart_Solver instance. Pass num_threads to set how many threads to use in parallel optimization runs

   .. py:method:: solve_for_unitary(self, circuit, options, x0=None)

      Finds the best parameters that minimize error_func or error_residuals between the unitary from the circuit and options.target.