.. toctree::
   :hidden:

   self
   walkthru
   api

Quick start
===========

What is cvxstoc?
----------------
cvxstoc is a Python package (built on top of `cvxpy <http://www.cvxpy.org/en/latest/>`_) that makes it easy to code and solve `stochastic optimization problems <http://stanford.edu/class/ee364a/lectures/stoch_prog.pdf>`_, i.e., `convex optimization problems <http://stanford.edu/class/ee364a/lectures/intro.pdf>`_ that include random variables.

What can I do with cvxstoc?
---------------------------

Here is a quick example of the kinds of problems you can tackle with cvxstoc (see the `gentle walkthrough <walkthru.html>`_ for more examples).

Suppose we are interested in a stochastic variation on a `portfolio optimization <https://en.wikipedia.org/wiki/Portfolio_optimization>`_ problem, i.e., we wish to allocate our wealth across :math:`n` assets such that the returns on our investments are (on average) maximized, so long as we keep the probability of a (catastrophic) loss as low as possible; we model our investment choices as a vector :math:`x \in {\bf R}^n_+` (we require that the components of :math:`x` sum to one), the (uncertain) price change of each asset as a vector :math:`p \in {\bf R}^n \sim \textrm{Normal}(\mu, \Sigma)` for simplicity, and our loss threshold and tolerance as :math:`\alpha` and :math:`\beta`, respectively (typically, :math:`\alpha` is negative and :math:`\beta` is small, e.g., 0.05).

These considerations lead us to the following (convex) optimization problem:

.. math::
   \begin{equation}
   \begin{array}{ll}
   \mbox{maximize} & \mathop{\bf E{}} p^T x \\
   \mbox{subject to} & x \succeq 0, \quad {\mathbf 1}^T x = 1, \quad {\mathop{\bf Prob}} ( p^T x \leq \alpha ) \leq \beta
   \end{array}
   \end{equation}
   :label: portopt

with variable :math:`x`.

We can directly express :eq:`portopt` using cvxstoc as follows:
 
.. literalinclude:: ../walkthru_code/walkthru_code4.py
   :language: python

How do I install cvxstoc?
-------------------------

On Mac OS X:

1. Follow the `instructions <http://www.cvxpy.org/en/latest/install/>`_ for installing cvxpy.
2. From the terminal, type: ``pip install cvxstoc`` (note: doing this will install `PyMC <https://pymc-devs.github.io/pymc/>`_, which cvxstoc depends on).
3. Done!

Where can I learn more about cvxstoc?
-------------------------------------

- See the `gentle walkthrough <walkthru.html>`_.
- The cvxstoc `paper <http://stanford.edu/~boyd/papers/dcsp.html>`_ contains much more (mathematical) detail as well as examples.
- The `cvxpy <mailto:cvxpy@googlegroups.com>`_ and/or `cvxstoc <mailto:cvxstoc@googlegroups.com>`_ email lists are great places to ask questions --- please feel free to get in touch!
- Please feel free to grab the `source code <https://github.com/alnurali/cvxstoc>`_ and contribute!