Merge pull request #28 from TAMUparametric/easymodeler

Easier Interface for generating Models

Author: DKenefake

doc/conf.py

@@ -29,7 +29,7 @@
 author = "Dustin Kenefake, Efstratios Pistikopoulos"
 
 # The full version, including alpha/beta/rc tags
-release = "1.4.0"
+release = "1.6.0"
 
 # -- General configuration ---------------------------------------------------
 
@@ -57,5 +57,5 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-source_suffix = [".rst", ".md"]
-nbsphinx_execute = "never"
+source_suffix = {".rst": 'restructuredtext', ".md": 'markdown'}
+nbsphinx_execute = "never"

doc/index.rst

@@ -16,7 +16,6 @@ Tutorial
     control_allocation_example
     portfolio
     mpc
-    mpoc_examples
 
 
 API

doc/mplp_tut.rst

@@ -20,7 +20,7 @@ This optimization problem leads to the following multiparametric optimization pr
 
 Using PPOPT, this is translated as the following python code. (The latex above was generated for me with ``prog.latex()`` if you were wondering if I typed that all out by hand.)
 
-.. code:: python
+.. code-block:: python
 
     import numpy
     from ppopt.mpqp_program import MPLP_Program
@@ -35,6 +35,45 @@ Using PPOPT, this is translated as the following python code. (The latex above w
 
     prog = MPLP_Program(A, b, c, H, CRa, CRb, F)
 
+Alternatively, we can use ``MPModeler`` to build the program. This can be a more user-friendly way to build the program, and it is easier to read and understand. It does not require the user to specify the problem data as matrices, but uses an interface that is more similar to a mathematical formulation.
+
+.. code-block:: python
+
+    from itertools import product
+    from ppopt.mpmodel import MPModeler
+
+    model = MPModeler()
+
+    # define problem data
+    factories = ['se', 'sd']
+    markets = ['ch', 'to']
+    capacities = {'se': 350, 'sd': 600}
+    cost = {('se', 'ch'): 178, ('se', 'to'): 187, ('sd', 'ch'): 187, ('sd', 'to'): 151}
+
+    # make a variable for each factory-market production pair
+    x = {(f, m): model.add_var(name=f'x[{f},{m}]') for f, m in product(factories, markets)}
+
+    # make a parameter for each market demand
+    d = {m: model.add_param(name=f'd_[{m}]') for m in markets}
+
+    # bounds on the production capacity of each factory
+    model.add_constrs(sum(x[f, m] for m in markets) <= capacities[f] for f in factories)
+
+    # demand satisfaction for each market
+    model.add_constrs(sum(x[f, m] for f in factories) >= d[m] for m in markets)
+
+    # bounds on the parametric demand
+    model.add_constrs(d[m] <= 1000 for m in markets)
+    model.add_constrs(d[m] >= 0 for m in markets)
+
+    # non-negativity of the production variables
+    model.add_constrs(x[f, m] >= 0 for f, m in product(factories, markets))
+
+    # set the objective to minimize the total cost
+    model.set_objective(sum(cost[f, m] * x[f, m] for f, m in product(factories, markets)))
+
+    prog = model.formulate_problem()
+
 
 But before you go forward and solve this, I would always recommend processing the constraints. Removing all strongly and weakly redundant constraints and rescaling them leads to significant performance increases and robustifying the numerical stability. In PPOPT, processing the constraints is a simple task.
 
@@ -57,15 +96,15 @@ This results in the following (identical) multiparametric optimization problem.
 
 That wasn't that bad, and we were able to cut away some constraints that didn't matter in the process! Now we are ready to solve it. We import the solver functionalities and then specify an algorithm to use. Here we are specifying the combinatorial algorithm. Even though we are using the ``solve_mpqp`` function, this is also the main backend to solve mpLPs!
 
-.. code:: python
+.. code-block:: python
 
     from ppopt.mp_solvers.solve_mpqp import solve_mpqp, mpqp_algorithm
     solution = solve_mpqp(prog, mpqp_algorithm.combinatorial)
 
 
 Now we have the solution, we can either export the solution via the micropop module, or we can plot it. Let's plot it here. The extra arguments mean we are saving a picture of the plot and displaying it to the user (you can give a file path, so it saves somewhere that is not the current working directory).
 
-.. code:: python
+.. code-block:: python
 
     from ppopt.plot import parametric_plot
 

doc/mpoc_examples.ipynb

@@ -25,7 +25,7 @@ Here the covariance matrix and the return coefficients were generated from rando
     S = S@S.T / 10
     mu = numpy.random.rand(num_assets)/100
 
-Here is the problem that we are going to be tackling in this post. Some of the constraints have been noticeably modified. This is due to a standard preprocessing pass that ``ppopt`` runs. This modification increases numerical stability for ill-conditioned optimization problems but has nearly for the problem we are looking at in this example, as it is numerically well conditioned. 
+Here is the problem that we are going to be tackling in this tutorial. Some of the constraints have been noticeably modified. This is due to a standard preprocessing pass that ``ppopt`` runs. This modification increases numerical stability for ill-conditioned optimization problems but has nearly for the problem we are looking at in this example, as it is numerically well conditioned.
 
 .. code-block:: python
 
@@ -42,6 +42,39 @@ Here is the problem that we are going to be tackling in this post. Some of the c
     H = numpy.zeros((A.shape[1],F.shape[1]))
     portfolio = MPQP_Program(A, b, c, H, Q, A_t, b_t, F,equality_indices= [0,1])
 
+Alternatively, we can use ``MPModeler`` to build the program. This can be a more user-friendly way to build the program, and it is easier to read and understand. It does not require the user to specify the problem data as matrices, but uses an interface that is more similar to a mathematical formulation.
+
+.. code-block:: python
+
+    import numpy
+    from ppopt.mpmodel import MPModeler
+
+    model = MPModeler()
+
+    # make a variable for each asset
+    assets = [model.add_var(name=f'w[{i}]') for i in range(num_assets)]
+
+    # define the parametric return
+    r = model.add_param(name='R')
+
+    # investment must add to one
+    model.add_constr(sum(assets) == 1)
+
+    # the expected return must be r
+    model.add_constr(sum(mu[i] * assets[i] for i in range(num_assets)) == r)
+
+    # all assets must be non-negative (no shorting)
+    model.add_constrs(asset >= 0 for asset in assets)
+
+    # parametric return must be constrained to be [min(mu), max(mu)]
+    model.add_constr(r >= min(mu))
+    model.add_constr(r <= max(mu))
+
+    # set the objective to minimize the risk
+    model.set_objective(sum(S[i, j] * assets[i] * assets[j] for i in range(num_assets) for j in range(num_assets)))
+
+    portfolio = model.formulate_problem()
+
 This formulates the parametric problem as follows, we want to parameterize the return :math:`R^*` as :math:`\theta`, so that we can solve over all feasible bounds of return.
 
 .. math::

doc/portfolio.rst

@@ -3,4 +3,6 @@ sphinx_mdinclude
 sphinx-rtd-theme
 nbsphinx
 ipykernel
-ipython
+ipython
+lxml[html_clean]
+pandoc

doc/requirements.txt

@@ -19,7 +19,7 @@ This optimization problem leads to the following multiparametric optimization pr
 
 Using PPOPT, this is translated as the following python code. (The latex above was generated for me with ``prog.latex()`` if you were wondering if I typed that all out by hand.)
 
-.. code:: python
+.. code-block:: python
 
     import numpy
     from ppopt.mpqp_program import MPQP_Program
@@ -36,9 +36,51 @@ Using PPOPT, this is translated as the following python code. (The latex above w
     prog = MPQP_Program(A, b, c, H, Q, CRa, CRb, F)
 
 
+Alternatively, we can use ``MPModeler`` to build the program. This can be a more user-friendly way to build the program, and it is easier to read and understand. It does not require the user to specify the problem data as matrices, but uses an interface that is more similar to a mathematical formulation.
+
+.. code-block:: python
+
+    from itertools import product
+    from ppopt.mpmodel import MPModeler
+
+    model = MPModeler()
+
+    # define problem data
+    factories = ['se', 'sd']
+    markets = ['ch', 'to']
+    capacities = {'se': 350, 'sd': 600}
+    cost = {('se', 'ch'): 178, ('se', 'to'): 187, ('sd', 'ch'): 187, ('sd', 'to'): 151}
+
+    # make a variable for each factory-market production pair
+    x = {(f, m): model.add_var(name=f'x[{f},{m}]') for f, m in product(factories, markets)}
+
+    # make a parameter for each market demand
+    d = {m: model.add_param(name=f'd_[{m}]') for m in markets}
+
+    # bounds on the production capacity of each factory
+    model.add_constrs(sum(x[f, m] for m in markets) <= capacities[f] for f in factories)
+
+    # demand satisfaction for each market
+    model.add_constrs(sum(x[f, m] for f in factories) >= d[m] for m in markets)
+
+    # bounds on the parametric demand
+    model.add_constrs(d[m] <= 1000 for m in markets)
+    model.add_constrs(d[m] >= 0 for m in markets)
+
+    # non-negativity of the production variables
+    model.add_constrs(x[f, m] >= 0 for f, m in product(factories, markets))
+
+    # set the objective to minimize the total cost
+    model.set_objective(sum(cost[f, m] * x[f, m] ** 2 + 25 * x[f, m] for f, m in product(factories, markets)))
+
+    prog = model.formulate_problem()
+
+
 But before you go forward and solve this, I would always recommend processing the constraints. Removing all strongly and weakly redundant constraints and rescaling them leads to significant performance increases and robustifying the numerical stability. In PPOPT, processing the constraints is a simple task.
 
-.. code:: python
+
+
+.. code-block:: python
 
     prog.process_constraints()
 
@@ -57,15 +99,15 @@ This results in the following (identical) multiparametric optimization problem.
 
 That wasn't that bad, and we were able to cut away some constraints that didn't matter in the process! Now we are ready to solve it. We import the solver functionalities and then specify an algorithm to use. Here we are specifying the combinatorial algorithm.
 
-.. code:: python
+.. code-block:: python
 
     from ppopt.mp_solvers.solve_mpqp import solve_mpqp, mpqp_algorithm
     solution = solve_mpqp(prog, mpqp_algorithm.combinatorial)
 
 
 Now we have the solution, we can either export the solution via the micropop module, or we can plot it. Let's plot it here. The extra arguments mean we are saving a picture of the plot and displaying it to the user (you can give a file path, so it saves somewhere that is not the current working directory).
 
-.. code:: python
+.. code-block:: python
 
     from ppopt.plot import parametric_plot
     

doc/tutorial.rst

@@ -25,4 +25,6 @@ dependencies:
     - ipykernel
     - ipython
     - daqp
+    - lxml[html_clean]
+    - pandoc
 prefix: /home/docs/.conda/envs/PPOPT

environment.yml

@@ -1,6 +1,6 @@
 from setuptools import find_packages, setup
 
-__version__ = "1.5.1"
+__version__ = "1.6.0"
 
 short_desc = (
     "Extensible Multiparametric Solver in Python"

setup.py

@@ -5,4 +5,4 @@
 os.environ["OPENBLAS_NUM_THREADS"] = "1"  # export OPENBLAS_NUM_THREADS=1
 os.environ["MKL_NUM_THREADS"] = "1"  # export MKL_NUM_THREADS=1
 os.environ["VECLIB_MAXIMUM_THREADS"] = "1"  # export VECLIB_MAXIMUM_THREADS=1
-os.environ["NUMEXPR_NUM_THREADS"] = "1"  # export NUMEXPR_NUM_THREADS=1
+os.environ["NUMEXPR_NUM_THREADS"] = "1"  # export NUMEXPR_NUM_THREADS=1