[docs] robust101, and getting started.

docs/source/gettingstarted.rst

@@ -0,0 +1,46 @@
+Getting started
+===============
+
+Once you have installed **robust**, and have a GP or SP model, you are ready to begin.
+From here onward, we will use *nominal* to describe models with no uncertainty straight
+out of GPkit, and *robust* to describe models that have been robustified using **robust**.
+
+The uncertainties in **robust** are defined by adding attribute *pr* to any variable
+in your model. This attribute
+describes the :math:`3\sigma` uncertainty for the given parameter, normalized by its mean (otherwise known
+as 3 times the coefficient of variation, eg. :math:`pr = 10`
+would specify a 10% 3CV). Note that these attributes
+are carried by nominal models but only come into effect when **robust** is applied.
+
+.. code-block:: python
+
+    from gpkit import Variable, Model
+    x = Variable('x', pr = 10)
+    % ...
+    % after more variables, constraints
+    % ...
+    m = Model(objective, constraints, substitutions)
+
+Once you have added uncertainties to parameters, and created a GPkit model,
+robustifying said model and solving it is easy. The most straight-forward
+inputs for uncertainty_set are 'box' or 'elliptical'. *gamma* defines the size of
+the uncertainty set protected against, where *gamma=1* protects against :math:`3\sigma`
+uncertainty.
+
+.. code-block:: python
+
+    from robust.robust import RobustModel
+    rm = RobustModel(m, uncertainty_set, gamma = float)
+    rsol = rm.robustsolve()
+
+You have solved your robust model! To be able to quickly compare the robust solution *rsol* with the nominal solution *sol*,
+we recommend you try 'diffing' the two, which is done as follows:
+
+.. code-block:: python
+
+    print rsol.diff(sol)
+
+This will allow you to see the percent differences between the two designs!
+Since the robust design protects against uncertainty in the parameters, it will necessarily
+have lower performance than the nominal design.
+If this has piqued your interest, please continue to explore the documentation.

docs/source/index.rst

@@ -25,9 +25,11 @@ Table of contents:
 
    robust101
    installation
+   gettingstarted
    whyro
    math
    methods
+   simulation
    goal
    references
 

docs/source/references.rst

@@ -1,4 +1,8 @@
 References
 **********
 
+*[Ozturk, 2019] Ozturk, B. and Saab, A., "Optimal Aircraft Design Decisions Under Uncertainty via Robust Signomial Programming", AIAA Aviation 2019 Conference Proceedings.
+
+*[Saab, 2018] Saab, A., Burnell, E., and Hoburg, W., "Robust Designs via Geometric Programming", arXiv:1808.07192v1.
+
 Work in progress...

docs/source/robust101.rst

@@ -1,16 +1,50 @@
-Robust 101
-**********
+Robust optimization 101
+***********************
 
-This section will help you understand the basic ideas behind robust optimization (RO),
-and get started with **robust** provided that you have a GP- or SP-compatible model.
-
-What is RO?
------------
+This section will help you understand the basic ideas behind robust optimization (RO).
 
 RO is a tractable method for optimization under uncertainty, and specifically under uncertain
 parameters. It optimizes the worst-case objective outcome over uncertainty sets,
 unlike general stochastic optimization methods which optimize statistics of the distribution
 of the objective over probability distributions of uncertain parameters. As such, RO
 sacrifices generality for tractability, probabilistic guarantees and engineering intuition.
 
+Basic mathematical principle
+----------------------------
+
+[*paraphrased from Ozturk and Saab, 2019*]
+
+Given a general optimization problem under parametric uncertainty, we define the set of possible
+realizations of uncertain vector of parameters :math:`u` in the uncertainty set :math:`\mathcal{U}`. This
+allows us to define the problem under uncertainty below.
+
+.. math::
+
+    \text{min} &~~f_0(x) \\
+    \text{s.t.}     &~~f_i(x,u) \leq 0,~\forall u \in \mathcal{U},~i = 1,\ldots,n
+
+This problem is infinite-dimensional, since it is possible to formulate an infinite number of constraints
+with the countably infinite number of possible realizations of :math:`u \in \mathcal{U}`. To circumvent this issue,
+we can define the following robust formulation of the uncertain problem below.
+
+.. math::
+
+    \text{min} &~~f_0(x) \\
+    \text{s.t.}     &~~\underset{u \in \mathcal{U}}{\text{max}}~f_i(x,u) \leq 0,~i = 1,\ldots,n
+
+This formulation hedges against the worst-case realization of the uncertainty in the defined uncertainty
+set. The set is often described by a norm, which contains possible uncertain outcomes from distributions with
+bounded support
+
+.. math::
+
+    \begin{split}
+        \text{min} &~~f_0(x) \\
+    \text{s.t.}     &~~\underset{u}{\text{max}}~f_i(x,u) \leq 0,~i = 1,\ldots,n \\
+                    &~~\left\lVert u \right\rVert \leq \Gamma \\
+        \end{split}
+
+where :math:`\Gamma` is defined by the user as a global uncertainty bound. The larger the :math:`\Gamma`,
+the greater the size of the uncertainty set that is protected against.
+
 Work in progress...

docs/source/simulation.rst

@@ -0,0 +1,4 @@
+Simulation capabilities
+=======================
+
+Work in progress...