Documentation update

doc/advanced.rst

@@ -190,12 +190,12 @@ The successive approximation method
 
 Prior to version 1.2, the functions ``exp``, ``log``, ``log_det``,
 and other functions from the exponential family could not be used within
-CVX. Unfortunately, CVX utilizes symmetric primal/dual solvers that
-simply cannot support those functions natively [4]_, and a variety of factors
-prevent us from incorporating other types of solvers into CVX.
+CVX. Until recently, CVX utilized so-called symmetric primal/dual solvers that
+simply cannot support those functions natively [4]_. More recently, solvers
+such as Mosek have added support for the exponential cone.
 
-Nevertheless, support for these functions was requested quite frequently.
-For this reason, we constructed a *successive approximation* heuristic that
+For solvers that do not natively support the exponential cone,
+we constructed a *successive approximation* heuristic that
 allows the symmetric primal/dual solvers to support the exponential
 family of functions. A precise description of the approach is beyond the
 scope of this text, but roughly speaking, the method proceeds as follows:
@@ -220,7 +220,10 @@ Even when it does converge, it is several times slower than the standard solver,
 due to its iterative approach. Therefore, it is best to use it sparingly and carefully.
 Here are some specific usage tips:
 
-- First, confirm that the log/exp/entropy terms are truly necessary for your model. In 
+- First, if you have access to Mosek, use it, as native support for the exponential
+  cone was added with version 9.
+
+- Barring this, confirm that the log/exp/entropy terms are truly necessary for your model. In 
   many cases, an exactly equivalent model can be constructed without them, and that should
   always be preferred. For instance, the constraint
 
@@ -262,8 +265,8 @@ Here are some specific usage tips:
   
         minimize( log_det(X) + trace(C*X) )
    
-- Second, try different solvers. For instance, SeDuMi and MOSEK
-  tend to be more effective with the successive approximation method
+- Third, try different solvers. SeDuMi tends
+  to be more effective with the successive approximation method
   than SDPT3. So if the default solver choice fails to give a 
   solution to your model, try switching to one of these solvers.
 

doc/conf.py

@@ -50,9 +50,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.1'
+version = '2.2'
 # The full version, including alpha/beta/rc tags.
-release = '2.1'
+release = '2.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/funcref.rst

@@ -8,12 +8,15 @@ In this section we describe each operator, function, set, and command that you a
 likely to encounter in CVX. In some cases, limitations of the underlying solver
 place certain restrictions or caveats on their use:
 
--  Functions marked with a dagger (†) are not supported natively by the
-   solvers that CVX uses. They are handled using a successive
+-  Functions marked with a dagger (†) are not supported natively by manu
+   solvers that CVX uses. Models incorporating these functions will be solved
+   most effectively by Mosek, the only bundled solver with support for the
+   exponential cone upon which these functions are constructed. For all
+   other solvers, these functions are handled using a successive
    approximation method which makes multiple calls to the underlying
-   solver, achieving the same final precision. If you use one of these
-   functions, you will be warned that successive approximation will be
-   used. This technique is discussed further in
+   solver, achieving the same final precision. If your problem requires the use
+   of the successive approximation method, a warning will be issued.
+   This technique is discussed further in
    :ref:`successive`. As this section discusses, this is an experimental
    approach that works well in many cases, but cannot be guaranteed.
 

doc/gp.rst

@@ -38,11 +38,13 @@ GP. More information about generalized geometric programs is provided in
 this
 `tutorial <http://www.stanford.edu/~boyd/papers/gp_tutorial.html>`_.
 
-The solvers used in this version of CVX do not support geometric
-programming natively. Instead, they are solved using the successive
-approximation technique described in :ref:`successive`.
-This means that solving GPs can be slow, but for small and medium sized problems, the method
-works well.
+We strongly recommend the use of Mosek 9.0 or later—including the version
+that ships with CVX 2.2 and later—for solving geometric programs. Its native
+support for the exponential cone ensures the best reliability, accuracy,
+and speed. For other solvers, CVX must
+use the successive approximation technique described in :ref:`successive`.
+This means that solving GPs can be slow, but for small and medium sized problems,
+the method works well.
 
 In the remainder of this section, we will describe specific rules that
 apply when constructing models in GP mode.

doc/gurobi.rst

@@ -8,95 +8,72 @@ About Gurobi
 ------------
 
 `Gurobi Optimization <http://www.gurobi.com>`_ was founded in 2008 by some of the most
-experienced and respected members of the optimization community. The Gurobi solver quickly became an industry performance leader in linear, quadratic, and mixed-integer programming. Gurobi is a fantastic solver for use with CVX, particularly with the new integer and binary variable capability added in CVX 2.0.
+experienced and respected members of the optimization community. The Gurobi solver quickly
+became an industry performance leader in linear, quadratic, and mixed-integer programming.
+Gurobi is a fantastic solver for use with CVX, particularly with the integer and binary
+variable capability added in CVX 2.0.
 
-Using CVX with Gurobi requires both a CVX Professional license and a
-Gurobi license. Please visit `Licensing`_ for information about
-CVX licensing, and Gurobi's `Licensing Overview <http://www.gurobi.com/products/licensing-and-pricing/licensing-overview>`_
-page for information about Gurobi licenses.
+Using Gurobi with CVX requires a valid license:
 
-Academic users can obtain both licenses at no charge. An academic
-CVX Professional license is obtained by submitting an `Academic License Request`_. 
-For instructions on obtaining an academic license for Gurobi, please see
-Gurobi's `Academic Licenses <http://www.gurobi.com/products/licensing-and-pricing/academic-licensing>`_ page.
+* *Academic users*: information about obtaining a license can be found on the
+  `Gurobi Academic Program`_ page.
+* *Commercial users* must purchase one of our CVX Professional licenses:
 
-.. _gurobilic:
-
-Using the bundled version of Gurobi
------------------------------------
-
-.. note:: 
-
-    The bundled version of Gurobi can only be used within CVX. If you wish to use Gurobi
-    outside of CVX as well, you will need a standalone Gurobi installation.
+  * A *bundled CVX + Gurobi license* allows Gurobi to be used exclusively within
+    CVX. This is the most cost-effective approach for users who do not intend
+    to use Gurobi outside of CVX and/or MATLAB.
+  * A *bring-your-own-solver (BYOS)* license allows CVX to be paired with a
+    separate Gurobi license, enabling the same installation to be used within
+    CVX and separate from it.
 
-If you wish to use CVX with the bundled version of Gurobi, you will need three things:
+  Please contact `CVX Sales`_ for more information about either option, and
+  `Gurobi Sales`_ for pricing information for standalone Gurobi licenses.
 
-* A CVX Professional Solver Bundle, available `here <http://cvxr.com/cvx/download>`_.
-* A Gurobi license code, which is composed of 32 hexidecimal digits in the format
-  ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``. If you purchase a commercial CVX+Gurobi
-  package, you will receive this code in an email from CVX Research. If you are an
-  academic user, you will receive it directly from Gurobi.
-* A CVX Professional license, saved to a convenient location on your local disk.
-
-Installation proceeds as follows:
+.. _gurobilic:
 
-* First, install CVX in the standard manner according to the directions found in
-  :ref:`install`. Do not attempt to install either license at this stage.
-* Next, retrieve your Gurobi license key by running the command ``cvx_grbgetkey`` *{code}*,
-  where *{code}* is the 32-digit Gurobi key. The command will look something like this::
+Using Gurobi with CVX
+---------------------
+
+1. Download the the appropriate CVX bundle from the `CVX download page`_
+   and following the regular installation instructions at :ref:`install`.
+   The standard bundles include a CVX-specific version of the Gurobi version 9.0.
+
+2. Obtain the licenses for Gurobi and/or CVX, as needed:
+
+   * A Gurobi license code, which is composed of 32 hexidecimal digits in the format
+     ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``. If you purchase a commercial CVX+Gurobi
+     package, you will receive this code in an email from CVX Research. If you are an
+     academic user, you will receive it directly from the `Gurobi academic license request`_ page.
+   * A CVX license should be saved in a convenient location for Step 4. You
+     will need to be able to supply its full path to the ``cvx_setup`` command.
+
+3. If you need a full installation of Gurobi—because you wish to use a
+   different version than is bundled with CVX, or because you wish to use Gurobi
+   outside of CVX—obtain an appropriate installer from the `Gurobi Download Center`_ 
+   and follow their instructions. Confirm that it can be successfully run from
+   the MATLAB command line *before* proceeding with Step 2.
+
+4. Next, retrieve your Gurobi license key by running the command ``cvx_grbgetkey``
+   *{code}*, where *{code}* is the 32-digit Gurobi key. This is a convenience
+   wrapper around Gurobi's own ``grbgetkey`` script. The command will look 
+   something like this::
 
     cvx_grbgetkey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
     
-  *Important note for academic users:* this step must be run from a computer
-  connected to your university network (a VPN is usually sufficient). Please
-  consult `this page <http://www.gurobi.com/documentation/5.5/quick-start-guide/node9>`_
-  of the Gurobi documentation for details.
-* Finally, install your CVX Professional license according to the directions
-  found in :ref:`licinstall`. 
-
-If you complete these steps successfully, ``cvx_setup`` will add Gurobi to its solver
-list. If you have an academic or dual-solver CVX Professional license, the MOSEK solver
-will be added to the solver list as well. If for some reason installation fails, the
-output of ``cvx_setup`` will provide diagnostic information that you can use to rectify
-the problem. If you are still unable to complete the installation, feel free to contact
-`CVX Support`_.
-
-.. _gurobistandalone:
-
-Using CVX with a standalone Gurobi installation
------------------------------------------------
-
-If you wish to use CVX with a standalone installation of Gurobi, you will
-need the following four things:
-
-* A Gurobi installation package, or a pre-existing Gurobi installation. 
-  CVX works with Gurobi 5.0 or later, but use
-  of the latest version is always recommended.
-* A Gurobi license code or key file, if you are installing Gurobi for the first time.
-* A standard CVX package, available `here <http://cvxr.com/cvx/download>`_.
-  You do not need the Professional Solver bundle.
-* A CVX Professional license, saved to a convenient location on your local disk.
-
-Installation proceeds as follows:
-
-* *Install Gurobi*. See `Downloading and Installation <http://www.gurobi.com/documentation/5.5/quick-start-guide/node1>`_
-  from the Gurobi Quick Start Guide.
-* *Install the Gurobi license.* See `How to Obtain and Install a Gurobi License <http://www.gurobi.com/documentation/5.5/quick-start-guide/node5>`_.
-* *Connect your Gurobi installation to MATLAB.* See `Setting up Gurobi for MATLAB 
-  <http://www.gurobi.com/documentation/5.5/quick-start-guide/node120>`_.
-* *Install CVX and/or the CVX Professional license*. See :ref:`install` and :ref:`licinstall`.
-  Even if these have already been installed, you *must* at least re-run ``cvx_setup``
-  so that CVX can locate Gurobi and add it to your solver list.
-
-If you complete these steps successfully, ``cvx_setup`` will show that Gurobi has been
-recognized and added to the solver list. If for some reason installation fails, the
-output of ``cvx_setup`` will provide diagnostic information that you can use to rectify
-the problem. If you are still unable to complete the installation, feel free to contact
-`CVX Support`_.
+   *Important note for academic users:* this step must be run from a computer
+   connected to your university network (a VPN is usually sufficient).
+   Please consult the Gurobi documentation for more details.
+
+5. Re-run ``cvx_setup`` so that the new Gurobi and/or CVX licenses can be detected.
+   If a CVX Professional license was obtained, supply the path to this file as the
+   argument to the ``cvx_setup`` command, as discussed in :ref:`licinstall`.
+
+If successful, the output of step 4 should show that Gurobi is among the list
+of available solvers. If you installed both a standalone Gurobi bundled version of Gurobi,
+they should both be available after setup.
 
 Selecting Gurobi as your default solver
----------------------------------------
+--------------------------------------
 
 Even if Gurobi is successfully added to your solver list, it will not automatically
 be selected as your default solver. To change this, type the following two commands
@@ -106,21 +83,36 @@ on the MATLAB command line:
 
     cvx_solver gurobi
     cvx_save_prefs
-    
+
 The first command changes the active solver to Gurobi, but only for the current session.
 The second line saves that change to CVX's preference file, so that Gurobi will be 
 selected as the active solver every time you start MATLAB.
 
+If multiple versions of Gurobi were found on the MATLAB path, then CVX will append a
+numeral to the end of the solver name, allowing you to switch between them; e.g.,
+
+::
+
+    cvx_solver gurobi
+    cvx_solver gurobi_2
+    cvx_solver gurobi_3
+
+and so forth.
+
 Obtaining support for CVX and Gurobi
 ------------------------------------
 
 If you encounter problems using CVX and Gurobi, please contact 
-`CVX Support`_ first instead of Gurobi Optimization.
+`CVX Support`_ first instead of Gurobi.
 If we can reproduce your problem, we will determine whether or not it is an
 issue that is unique to CVX or needs to be forwarded to Gurobi for further
 analysis.
 
+.. _Gurobi Optimization LLC: https://gurobi.com/
 .. _CVX Support: http://support.cvxr.com/
+.. _CVX download page: http://cvxr.com/cvx/download
 .. _CVX Sales: mailto:[email protected]   
-.. _Licensing: http://cvxr.com/cvx/licensing
-.. _Academic License Request: http://cvxr.com/cvx/academic
+.. _Gurobi Academic Program: https://www.gurobi.com/academia/academic-program-and-licenses/
+.. _Gurobi academic license request: https://www.gurobi.com/downloads/end-user-license-agreement-academic/
+.. _Gurobi Download Center: https://www.gurobi.com/downloads/
+.. _Gurobi Sales: mailto:[email protected]