[docs] rsp approaches and other cleanups.

docs/source/commands.rst

@@ -1,6 +1,8 @@
 More advanced commands
 ======================
 
+*[Documentation work in progress...]*
+
 **robust** has a variety of tools beyond the basics
 to aid engineering design under uncertainty.
 
@@ -9,15 +11,33 @@ code repository, which defines the models used in [Ozturk, 2019].
 
 .. _robustSPpaper: https://github.com/1ozturkbe/robustSPpaper/tree/master/code
 
-Choosing between RGP approximation methods
-------------------------------------------
+Choosing between RGP approximation methods and uncertainty sets
+---------------------------------------------------------------
 
-We prefer to define the methods in a dict
+There are many possible ``**options`` to ``RobustModel``, but the primary function
+of the options is to be able to choose between the different RGP approximation methods,
+which have differing levels of conservativeness.
+We prefer to define the three methods in a dict for ease access, and call ``RobustModel``, for example
+for Best Pairs, as follows:
 
-.. code-blocK:: python
+.. code-block:: python
 
     methods = [{'name': 'Best Pairs', 'twoTerm': True, 'boyd': False, 'simpleModel': False},
                {'name': 'Linearized Perturbations', 'twoTerm': False, 'boyd': False, 'simpleModel': False},
                {'name': 'Simple Conservative', 'twoTerm': False, 'boyd': False, 'simpleModel': True}]
+    method = methods[0] # Best Pairs
+    robust_model = RobustModel(m, uncertainty_set, gamma=Gamma, twoTerm=method['twoTerm'],
+                                   boyd=method['boyd'], simpleModel=method['simpleModel'])
+
+For ``uncertainty_set``, ``'box'`` and ``'elliptical'`` are currently supported, and
+define the :math:`\infty`- and 2-norms respectively.
+
+Coming soon...
+
+Simulating robust designs
+-------------------------
+
+How to generate samples of uncertain parameters...
 
-and choose the appropriate
+How to perform a Monte Carlo based probability of failure analysis
+based on constraint satisfaction, i.e. feasibility solves...

docs/source/goal.rst

@@ -34,8 +34,8 @@ design variable against with all objectives can be weighed.
 Implementation
 --------------
 
-To use the goal programming functions in **robust**, you can use the ```simulate.variable_goal_results```
-function, which has the same inputs as ```simulate.variable_gamma_result``` except for
+To use the goal programming functions in **robust**, you can use the ``simulate.variable_goal_results``
+function, which has the same inputs as ``simulate.variable_gamma_results`` except for
 having the penalty parameter :math:`\delta` instead of the uncertainty set size :math:`\Gamma` as its input.
 
 What occurs to the solved nominal model under the hood is the following:

docs/source/methods.rst

@@ -6,7 +6,7 @@ GPs, which can then be extended to SPs through heuristics
 The methods are detailed at a high level below, in decreasing order of conservativeness.
 Please see [Saab, 2018] for further details.
 
-*(The following overview has been paraphrased from [Ozturk, 2019].)*
+*(paraphrased from [Ozturk, 2019])*
 
 The robust counterpart of an uncertain geometric program is:
 

docs/source/rspapproaches.rst

@@ -3,11 +3,73 @@
 Approaches to solving robust SPs
 ================================
 
-*[borrowed from [Ozturk, 2019]*
+*(borrowed from [Ozturk, 2019])*
+
+This section presents a heuristic algorithm to solve a RSP
+based on our previous discussion on robust geometric programming.
+
+General RSP Solver
+------------------
+
+A common heuristic algorithm to solve a SP is
+by sequentially solving local GP approximations.
+Similarly, our approach to solve a RSP is based on solving
+a sequence of local RGP approximations. 
+In this heuristic, a good initial guess will lead to faster
+convergence and possibly a better solution.
+The deterministic solution of the uncertain SP is in general a good candidate :math:`x_0`.
 
 |rspSolve|
 
 .. |rspSolve| image:: rspSolve.png
         :width: 80%
 
+For comparisons between methods ahead, we write the algorithm explicitly as follows:
+
+    - Choose an initial guess :math:`x_0`.
+    - Repeat:
+
+      - Find the local GP approximation of the SP at :math:`x_i`.
+      - Find the RGP formulation of the GP.
+      - Solve the RGP to obtain :math:`x_{i+1}`.
+      - If :math:`x_{i+1} \approx x_{i}`: break
+
+
+Any of the previously mentioned methodologies can be used to formulate the local RGP approximation. 
+However, depending on the RGP formulation chosen to solve a RSP, the formulation and solution
+blocks in the above figure are adjusted.
+
+Best Pairs RSP Solver
+---------------------
+
+If the Best Pairs methodology is exploited, then the above algorithm would change so that
+each iteration would solve the local RGP approximation and choose the best permutation
+for each large posynomial. The modified algorithm would become as follows:
+
+    - Choose an initial guess :math:`x_0`.
+    - Repeat:
+
+      - Find the local GP approximation of the SP at :math:`x_i`.
+      - For each large posynomial constraint, select the new permutation :math:`\phi` such that :math:`\phi` minimizes the robust large constraint evaluated at :math:`x_i`.
+      - Solve the approximate tractable counterparts of the local GP, and let :math:`\mathbf{x}_{i+1}` be the solution.
+      - If :math:`x_{i+1} \approx x_{i}`: break.
+
+Linearized Perturbations RSP Solver
+-----------------------------------
+
+On the other hand, if the Linearized Perturbations formulation is to be used,
+then we can avoid solving a SP at each iteration by first
+approximating the original SP constraints locally, and in the same loop approximating
+the robustified possibly signomial constraints locally, thus solving a
+GP at each iteration instead of a SP. The algorithm would then become as follows:
+
+    - Choose an initial guess :math:`x_0`.
+    - Repeat:
+
+      - Find the local GP approximation of the SP at :math:`x_i`.
+      - Robustify the constraints of the local GP approximation using the Linearized Perturbations methodology.
+      - Find the local GP approximation of the resulting local SP at :math:`x_i`.
+      - Solve the local GP approximation in step c to obtain $x_{i+1}$.
+      - If :math:`x_{i+1} \approx x_{i}`: break.
+
 Work in progress...