From 78a903cde3fdde6a3aed1e1eed93e7cb2ad0821d Mon Sep 17 00:00:00 2001
From: Oscar Dowson <odow@users.noreply.github.com>
Date: Wed, 19 Apr 2023 11:07:00 +1200
Subject: [PATCH] [README] clarify mode options (#55)

Co-authored-by: Eric Hanson <5846501+ericphanson@users.noreply.github.com>
---
 README.md | 63 ++++++++++++++++++++++++++++++-------------------------
 1 file changed, 35 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index 17dd592..d5d605a 100644
--- a/README.md
+++ b/README.md
@@ -74,34 +74,34 @@ List of supported model attributes:
 
 ## Options
 
-SDPA has 3 modes that give values to all 10 parameters. By default, we put SDPA
-in the `PARAMETER_DEFAULT` mode.
-
-The three modes are as follow:
-
-| Mode    | Name                          |
-| ------- | ----------------------------- |
-| Default | `SDPA.PARAMETER_DEFAULT`           |
-| Fast    | `SDPA.PARAMETER_UNSTABLE_BUT_FAST` |
-| Slow    | `SDPA.PARAMETER_STABLE_BUT_SLOW`   |
-
-The following table gives the default value for each parameter.
-
-| Parameter name | Default | Fast   | Slow   |
-| -------------- | ------- | ------ | ------ |
-| MaxIteration   | 100     | 100    | 1000   |
-| EpsilonStar    | 1.0e-7  | 1.0e-7 | 1.0e-7 |
-| LambdaStar     | 1.0e+2  | 1.0e+2 | 1.0e+4 |
-| OmegaStar      | 2.0     | 2.0    | 2.0    |
-| LowerBound     | 1.0e+5  | 1.0e+5 | 1.0e+5 |
-| UpperBound     | 1.0e+5  | 1.0e+5 | 1.0e+5 |
-| BetaStar       | 0.1     | 0.01   | 0.1    |
-| BetaBar        | 0.2     | 0.02   | 0.3    |
-| GammaStar      | 0.9     | 0.95   | 0.8    |
-| EpsilonDash    | 1.0e-7  | 1.0e-7 | 1.0e-7 |
-
-Note that the parameters are set in the order they are given, so you can set it
-in a mode and then modify one parameter from this mode.
+SDPA has three modes that give default value to all ten parameters.
+
+The following table gives the default values for each parameter and mode.
+
+| Parameter    | `PARAMETER_DEFAULT` | `PARAMETER_UNSTABLE_BUT_FAST` | `PARAMETER_STABLE_BUT_SLOW` |
+| ------------ | ------- | ------ | ------ |
+| MaxIteration | 100     | 100    | 1000   |
+| EpsilonStar  | 1.0e-7  | 1.0e-7 | 1.0e-7 |
+| LambdaStar   | 1.0e+2  | 1.0e+2 | 1.0e+4 |
+| OmegaStar    | 2.0     | 2.0    | 2.0    |
+| LowerBound   | 1.0e+5  | 1.0e+5 | 1.0e+5 |
+| UpperBound   | 1.0e+5  | 1.0e+5 | 1.0e+5 |
+| BetaStar     | 0.1     | 0.01   | 0.1    |
+| BetaBar      | 0.2     | 0.02   | 0.3    |
+| GammaStar    | 0.9     | 0.95   | 0.8    |
+| EpsilonDash  | 1.0e-7  | 1.0e-7 | 1.0e-7 |
+
+By default, we put SDPA in the `SDPA.PARAMETER_DEFAULT` mode.
+
+Change the mode using the `"Mode"` option:
+```julia
+using JuMP, SDPA
+model = Model(SDPA.Optimizer)
+set_attribute(model, "Mode", SDPA.PARAMETER_STABLE_BUT_SLOW)
+```
+
+Note that the parameters are set in the order they are given, so you can set
+a mode and then modify parameters from this mode.
 
 ```julia
 using JuMP, SDPA
@@ -109,3 +109,10 @@ model = Model(SDPA.Optimizer)
 set_attribute(model, "Mode", SDPA.PARAMETER_STABLE_BUT_SLOW)
 set_attribute(model, "MaxIteration", 100)
 ```
+
+The choice of parameter mode has a large impact on the performance and stability
+of SDPA, and not necessarily in the way implied by the names of the modes; for
+example, `PARAMETER_UNSTABLE_BUT_FAST` can be more stable than the other modes
+for some problems. You should try each mode to see how it performs on your
+specific problem. See [SDPA.jl#17](https://github.com/jump-dev/SDPA.jl/issues/17)
+for more details.