Metadata-Version: 2.1
Name: krotov
Version: 1.2.1
Summary: Python implementation of Krotov's method for quantum optimal control
Home-page: https://github.com/qucontrol/krotov
Author: Michael Goerz
Author-email: mail@michaelgoerz.net
License: BSD license
Keywords: krotov
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Framework :: Jupyter
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: ~=3.5
Description-Content-Type: text/x-rst
Requires-Dist: glom
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: qutip (>=4.3.1)
Requires-Dist: threadpoolctl
Requires-Dist: grapheme
Requires-Dist: loky
Provides-Extra: dev
Requires-Dist: better-apidoc (==0.3.1) ; extra == 'dev'
Requires-Dist: click ; extra == 'dev'
Requires-Dist: codecov ; extra == 'dev'
Requires-Dist: coverage (<5.0) ; extra == 'dev'
Requires-Dist: doctr ; extra == 'dev'
Requires-Dist: doctr-versions-menu ; extra == 'dev'
Requires-Dist: flake8 ; extra == 'dev'
Requires-Dist: gitpython ; extra == 'dev'
Requires-Dist: isort (==4.3.*) ; extra == 'dev'
Requires-Dist: jupyter ; extra == 'dev'
Requires-Dist: loky ; extra == 'dev'
Requires-Dist: matplotlib ; extra == 'dev'
Requires-Dist: nbsphinx ; extra == 'dev'
Requires-Dist: nbval ; extra == 'dev'
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: pybtex ; extra == 'dev'
Requires-Dist: pylint ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-cov (<=2.6.1) ; extra == 'dev'
Requires-Dist: pytest-xdist ; extra == 'dev'
Requires-Dist: sphinx ; extra == 'dev'
Requires-Dist: sphinx-autobuild ; extra == 'dev'
Requires-Dist: sphinx-copybutton ; extra == 'dev'
Requires-Dist: sphinx-rtd-theme ; extra == 'dev'
Requires-Dist: sphinxcontrib-bibtex ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'
Requires-Dist: watermark ; extra == 'dev'
Requires-Dist: weylchamber (>=0.3.2) ; extra == 'dev'
Requires-Dist: wheel ; extra == 'dev'
Requires-Dist: black ; extra == 'dev'
Requires-Dist: zip-files ; extra == 'dev'
Provides-Extra: extras
Requires-Dist: jupyterlab ; extra == 'extras'
Requires-Dist: pdbpp ; extra == 'extras'

=====================
Krotov Python Package
=====================

.. image:: https://img.shields.io/badge/github-qucontrol/krotov-blue.svg
   :alt: Source code on Github
   :target: https://github.com/qucontrol/krotov
.. image:: https://img.shields.io/badge/docs-gh--pages-blue.svg
   :alt: Documentation
   :target: https://qucontrol.github.io/krotov
.. image:: https://img.shields.io/pypi/v/krotov.svg
   :alt: Krotov on the Python Package Index
   :target: https://pypi.python.org/pypi/krotov
.. image:: https://badges.gitter.im/qucontrol_krotov/Lobby.svg
   :alt: Join the chat at https://gitter.im/qucontrol_krotov/Lobby
   :target: https://gitter.im/qucontrol_krotov/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
.. image:: https://github.com/qucontrol/krotov/workflows/Docs/badge.svg?branch=master
   :alt: Docs
   :target: https://github.com/qucontrol/krotov/actions?query=workflow%3ADocs
.. image:: https://github.com/qucontrol/krotov/workflows/Tests/badge.svg?branch=master
   :alt: Tests
   :target: https://github.com/qucontrol/krotov/actions?query=workflow%3ATests
.. image:: https://codecov.io/gh/qucontrol/krotov/branch/master/graph/badge.svg
   :alt: Codecov
   :target: https://codecov.io/gh/qucontrol/krotov
.. image:: https://img.shields.io/badge/License-BSD-green.svg
   :alt: BSD License
   :target: https://opensource.org/licenses/BSD-3-Clause
.. image:: https://mybinder.org/badge_logo.svg
   :alt: Launch Binder
   :target: https://mybinder.org/v2/gh/qucontrol/krotov/v1.2.1?filepath=docs%2Fnotebooks
.. image:: https://img.shields.io/badge/DOI-10.21468/SciPostPhys.7.6.080-blue.svg
   :alt: DOI
   :target: https://doi.org/10.21468/SciPostPhys.7.6.080

Python implementation of Krotov's method for quantum optimal control.

This implementation follows the original implementation in the `QDYN Fortran library`_.

The ``krotov`` package is built on top of `QuTiP`_.

Development happens on `Github`_. You can read the full documentation `online`__ or `download a PDF version`_.

.. _Documentation: https://qucontrol.github.io/krotov
__ Documentation_

If you use the ``krotov`` package in your research, please `cite it <https://qucontrol.github.io/krotov/v1.2.1/01_overview.html#citing-the-krotov-package>`_.

.. _QDYN Fortran library: https://www.qdyn-library.net
.. _QuTiP: http://qutip.org
.. _download a PDF version: https://github.com/qucontrol/krotov/tree/master/docs/pdf


Purpose
-------

Optimal control is a cornerstone of quantum technology: relying not
just on a passive understanding of quantum mechanics, but on the *active*
utilization of the quantum properties of matter. Quantum optimal control asks
how to manipulate the dynamics of a quantum system in some desired
way. This is essential for the realization of quantum computers and
related technologies such as quantum sensing.

Krotov's method and GRAPE are the two leading gradient-based optimization
algorithms used in numerical quantum optimal control. Krotov's method
distinguishes itself by guaranteeing monotonic convergence for near-continuous
control fields. This makes is particularly useful for exploring the limits of
controllability in a physical system.
While GRAPE is found in various software packages, there has not been an open
source implementation of Krotov's method to date. Our package provides that
missing implementation.

The Krotov package targets both students wishing to enter the field
of quantum control and researchers in the field. It was designed towards
the following goals:

* Leverage the `QuTiP`_ library as a platform for numerically describing
  quantum systems.
* Provide a collection of examples inspired by recent publications in
  the `Jupyter notebook`_ format, allowing for interactive exploration of the
  method.
* Define a general interface for formulating *any* quantum control problem,
  which may extend to other optimization methods in the future.
* Serve as a reference implementation of Krotov's method, and as a foundation
  against which to test other implementations.
* Enable the more widespread use of Krotov's method, for example in the design
  of experiments.


Prerequisites
-------------

The Krotov package is available for Python versions >= 3.5. Its main dependency is `QuTiP`_
(apart from the `core packages of the Python scientific ecosystem`_).
Thus, you should consider `QuTiP's installation instructions`_.

In any case, using some sort of `virtual environment`_ is strongly encouraged.
Most packages in the Python scientific ecosystem are now available as
`wheels`_, making installation via `pip`_ easy. However, `QuTiP currently does
not provide wheels`_. Thus, on systems that do not have the necessary compilers
installed (Windows, macOS), the `conda`_ package manager provides a good solution.

Assuming ``conda`` is installed (e.g. through `Miniconda`_), the following
commands set up a virtual (conda) environment into which the Krotov package can
then be installed:

.. code-block:: shell

    conda create -n qucontrolenv "python=3.7"
    conda activate qucontrolenv
    conda config --append channels conda-forge
    conda install qutip

.. _core packages of the Python scientific ecosystem: https://www.scipy.org
.. _QuTiP's installation instructions: http://qutip.org/docs/latest/installation.html
.. _virtual environment: https://docs.python.org/3/glossary.html#term-virtual-environment
.. _wheels: https://packaging.python.org/tutorials/installing-packages/#source-distributions-vs-wheels
.. _QuTiP currently does not provide wheels: https://github.com/qutip/qutip/issues/933
.. _conda: https://conda.io/docs/index.html
.. _Miniconda: https://conda.io/miniconda.html


Installation
------------
To install the latest released version of ``krotov`` into your current (conda)
environment, run this command in your terminal:

.. code-block:: shell

    python -m pip install krotov

This is the preferred method to install the ``krotov`` package, as it will always install the most recent stable release.

You may also do

.. code-block:: shell

    python -m pip install krotov[dev,extras]

to install additional development dependencies, including packages required to run the example notebooks.

If you don't have `pip`_ installed, the `Python installation guide`_, respectively the `Python Packaging User Guide`_ can guide
you through the process.

.. _pip: https://pip.pypa.io
.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
.. _Python Packaging User Guide: https://packaging.python.org/tutorials/installing-packages/


To install the latest development version of ``krotov`` from `Github`_:

.. code-block:: shell

    python -m pip install git+https://github.com/qucontrol/krotov.git@master#egg=krotov

.. _Github: https://github.com/qucontrol/krotov

Usage
-----

To use Krotov's method for quantum optimal control in a Python script or
`Jupyter notebook`_, start with::

    import krotov
    import qutip

Then,

1. define the necessary quantum operators and states using `QuTiP`_.
2. create a list of objectives, as instances of
   |krotov.Objective|_.
3. call |krotov.optimize_pulses|_ to perform an optimization of an arbitrary
   number of control fields over all the objectives.

.. |krotov.Objective| replace:: ``krotov.Objective``
.. _krotov.Objective: https://qucontrol.github.io/krotov/v1.2.1/API/krotov.objectives.html#krotov.objectives.Objective

.. |krotov.optimize_pulses| replace:: ``krotov.optimize_pulses``
.. _krotov.optimize_pulses: https://qucontrol.github.io/krotov/v1.2.1/API/krotov.optimize.html#krotov.optimize.optimize_pulses

See `Using Krotov with QuTiP <https://qucontrol.github.io/krotov/v1.2.1/08_qutip_usage.html#using-krotov-with-qutip>`_ and `Examples <https://qucontrol.github.io/krotov/v1.2.1/09_examples.html>`_ for details.

.. _Jupyter notebook: https://jupyter.org


=======
History
=======

1.2.1 (2021-01-13)
------------------

* Bugfix: Crash when initializing discretized numpy-array controls (`#79`_, thanks to `@loganbvh`_)
* Bugfix: Corrected definition of co-states in Dissipative Qubit Reset example (`#80`_, thanks to `Alberto Castro`_)
* Update: Switched Testing and Documentation deployment from Travis to Github Actions (`#82`_)

1.2.0 (2020-08-17)
------------------

* Added: ``via_midpoints`` argument to ``krotov.conversions.discretize`` function
* Changed: Controls and update shapes are now discretized in a way that ensures numerical stability (`#74`_, thanks to `@zachmanson`_)
* Changed: Replaced ``uniseg`` dependency with ``grapheme`` (`#76`_)

Note: due to the changes in the time discretization of the controls and update shapes, this version will generally not reproduce optimization results from previous versions to machine precision.


1.1.0 (2020-03-24)
------------------

* Added: Support for Python 3.8
* Added: Support for QuTiP 4.5.0
* Added: Support for parallelization with loky_ (`#72`_)
* Added: ``krotov.parallelization.set_parallelization`` function
* Added: ``krotov.parallelization.parallel_map`` function (improved implementation of QuTiP's ``parallel_map``)
* Added: Ability to use threadpoolctl_ to limit unwanted threading
* Added: `limit_thread_pool` option to ``krotov.optimize_pulses``
* Changed: ``krotov.propagators.expm`` now guarantees single-threaded execution


1.0.0 (2019-12-16)
------------------

* Update: Citation info now points to `SciPost paper <https://scipost.org/SciPostPhys.7.6.080>`_ (`#61`_)
* Added: parameters `col_formats` and `col_headers` to customize the output of ``krotov.info_hooks.print_table`` (`#65`_)
* Added: info-hooks now have access to the additional arguments `propagator`, `chi_constructor`, `mu`, `sigma`, `iter_start`, and `iter_stop` (`#66`_)
* Added: parameter `keep_original_objectives` to ``krotov.objectives.ensemble_objectives`` (`#67`_)
* Added: "Related Software" in the documentation
* Update: Documentation is now hosted on gh-pages_ and deployed by Doctr_ (`#68`_)


0.5.0 (2019-12-04)
------------------

* Update: Documentation now contains all information from https://arxiv.org/abs/1902.11284v5
* Added: Allow to pass `args` to time-dependent control functions (`#56`_, thanks to `@timohillmann`_)
* Changed: Renamed ``krotov.structural_conversions`` to ``krotov.conversions``
* Bugfix: Crash when ``krotov.optimize_pulses`` is called with ``iter_stop=0`` (`#58`_)
* Added: ``krotov.result.Result`` is now exposed at the top level of the API, as ``krotov.Result`` (`#59`_, thanks to `@nathanshammah`_)
* Added: str-representation of ``krotov.result.Result`` now includes the total running time (`#60`_, thanks to `@nathanshammah`_)


0.4.1 (2019-10-11)
------------------

* Update: Documentation now contains all information from https://arxiv.org/abs/1902.11284v4 (`#54`_)
* Added: a PDF of the documentation is now available at https://github.com/qucontrol/krotov/tree/master/docs/pdf (`#52`_, thanks to `@TejasAvinashShetty`_)


0.4.0 (2019-10-08)
------------------

* Added: Support for Python 3.7
* Changed: The ``'shape'`` key in ``pulse_options`` was renamed to ``'update_shape'``, to further avoid confusion between pulse shapes and update shapes.
* Changed: The ``.adjoint`` property of ``Objective`` is now a method
* Added: Ability to not use QuTiP ``Qobj`` objects, but arbitrary low-level objects instead.
* Improved: Printing an ``Objective`` now uses internal counters and a symbolic notation to identify objects shared between different objectives. (`#43`_)
* Improved: ``gate_objectives`` now takes into account if target states are (reshuffled) basis states and does not create unnecessary new copies.
* Bugfix: Two ``Objective`` instances that contain numpy arrays as controls can now be compared with ``==`` (`#44`_)
* Bugfix: Custom attributes (such as ``weight``) are now preserved when copying an ``Objective`` (`#44`_)
* Bugfix: Calling ``copy.deepcopy`` on an ``Objective`` now preserves control functions (`#44`_)
* Improved: The ``Objective.mesolve`` and ``Objective.propagate`` methods can now receive arguments ``H`` and ``c_ops`` to override the respective attributes of the objectives. This make is easier to analyze perform a robustness analysis, where the result of an optimization should be propagated under a perturbed Hamiltonian.
* Improved: The ``print_table`` and ``print_debug_information`` info-hooks now flush their output buffers after each iteration. As a result, when writing to a file, that file can be watched with ``tail -f``.
* Changed: Redefine ``tau_vals`` as their complex conjugate, fixing a bug in ``chis_ss`` and ``chis_sm`` (`#46`_)
* Bugfix: Correctly calculate ∂H/∂ϵ if ϵ occurs in H multiple times (`#47`_, thanks to `@uiofgh`_)
* Bugfix: Correctly calculate ∂H/∂ϵ=0 if the specific ϵ currently being updated does not occur in H (`#48`_)
* Added: Method ``objectives_with_controls`` for ``Result`` object.


0.3.0 (2019-03-01)
------------------

* Added: Preprint citation information (``krotov.__arxiv__``, ``krotov.__citation__``, ``krotov.__bibtex__``)
* Added: Ability to continue from a previous optimization (`#26`_)
* Added: Parameter ``out`` to ``print_table`` info-hook
* Added: Parameter ``finalize`` to ``Result.load``
* Added: Ability to dump optimization result every so many iterations (``dump_result`` check-convergence routine)
* Added: `re-entrant` option for ``DensityMatrixODEPropagator``
* Bugfix: Discretize controls to float values (`#41`_)
* Bugfix: Fix overlap for non-Hermitian operators (`#39`_)
* Bugfix: Interface for passing ``tau_vals`` to ``chi_constructor`` (`#36`_)
* Added: function ``above_value`` for convergence check (`#35`_)


0.2.0 (2019-02-14)
------------------

* Added: Implementation of all the standard functionals
* Added: The ``info_hook`` receives additional information, including ∫gₐ(t)dt (`#32`_)
* Added: Initialization of objectives for gate optimization in Liouville space
* Added: A new propagator ``DensityMatrixODEPropagator`` for faster density matrix propagation
* Added: Support for "stateful" propagators by subclassing from ``krotov.propagators.Propagator``
* Changed: more flexibility for parallelization (`#29`_)
* Added: Support for the second-order pulse update
* Changed: The options for the controls (λₐ, update-shape) are now passed through a simplified ``dict`` interface, instead of a custom ``PulseOptions`` class.


0.1.0 (2018-12-24)
------------------

* Initial release with complete implementation of first-order Krotov's method
* Support for state-to-state and gate optimization, for both closed and open systems


.. _loky: https://loky.readthedocs.io/
.. _gh-pages: https://qucontrol.github.io/krotov
.. _Doctr: https://drdoctr.github.io
.. _threadpoolctl: https://github.com/joblib/threadpoolctl
.. _@uiofgh: https://github.com/uiofgh
.. _@TejasAvinashShetty: https://github.com/TejasAvinashShetty
.. _@timohillmann: https://github.com/timohillmann
.. _@nathanshammah: https://github.com/nathanshammah
.. _@zachmanson: https://github.com/zachmanson
.. _@loganbvh: https://github.com/loganbvh
.. _Alberto Castro: https://www.bifi.es/~acastro/
.. _#26: https://github.com/qucontrol/krotov/issues/26
.. _#29: https://github.com/qucontrol/krotov/issues/29
.. _#32: https://github.com/qucontrol/krotov/issues/32
.. _#35: https://github.com/qucontrol/krotov/issues/35
.. _#36: https://github.com/qucontrol/krotov/issues/36
.. _#39: https://github.com/qucontrol/krotov/issues/39
.. _#41: https://github.com/qucontrol/krotov/issues/41
.. _#43: https://github.com/qucontrol/krotov/issues/43
.. _#44: https://github.com/qucontrol/krotov/issues/44
.. _#46: https://github.com/qucontrol/krotov/issues/46
.. _#47: https://github.com/qucontrol/krotov/issues/47
.. _#48: https://github.com/qucontrol/krotov/issues/48
.. _#52: https://github.com/qucontrol/krotov/issues/42
.. _#54: https://github.com/qucontrol/krotov/issues/54
.. _#56: https://github.com/qucontrol/krotov/issues/56
.. _#58: https://github.com/qucontrol/krotov/issues/58
.. _#59: https://github.com/qucontrol/krotov/issues/59
.. _#60: https://github.com/qucontrol/krotov/issues/60
.. _#61: https://github.com/qucontrol/krotov/issues/61
.. _#65: https://github.com/qucontrol/krotov/issues/65
.. _#66: https://github.com/qucontrol/krotov/issues/66
.. _#67: https://github.com/qucontrol/krotov/issues/67
.. _#68: https://github.com/qucontrol/krotov/issues/68
.. _#72: https://github.com/qucontrol/krotov/issues/72
.. _#74: https://github.com/qucontrol/krotov/issues/74
.. _#76: https://github.com/qucontrol/krotov/issues/76
.. _#79: https://github.com/qucontrol/krotov/issues/79
.. _#80: https://github.com/qucontrol/krotov/issues/80
.. _#82: https://github.com/qucontrol/krotov/issues/82


