update build instructions

PythonOptimizers · Apr 12, 2016 · 4de3e5d · 4de3e5d
1 parent b7065a2
commit 4de3e5d
Show file tree

Hide file tree

Showing 2 changed files with 140 additions and 38 deletions.
diff --git a/README.md b/README.md
@@ -1,46 +1,64 @@
 # NLP.py
 
+[![Build Status](https://travis-ci.com/PythonOptimizers/NLP.py.svg?token=MZezWHtArpsrWZ3Yyqzx&branch=develop)](https://travis-ci.com/PythonOptimizers/NLP.py)
+
 `NLP.py` is a Python package for modeling and solving continuous optimization problems.
 
 ## Dependencies
 
-- Numpy
+- [`Numpy`](http://www.numpy.org)
 - [`PyKrylov`](https://github.com/PythonOptimizers/pykrylov)
 
 ## Optional dependencies
 
-A strongly recommended dependency is the AMPL modeling language Solver Library. On OSX, the simplest is to use [Homebrew](https://brew.sh):
-```
-brew tap homebrew/science
-brew install asl
-```
+### Sparse matrix storage
 
-Python dependencies:
+One of:
 
-- [`CySparse`](https://github.com/PythonOptimizers/cysparse) (the successor of PySparse)
+- [`CySparse`](https://github.com/PythonOptimizers/cysparse) (recommended)
 - [`PySparse`](https://github.com/optimizers/pysparse.git)
-- [`Scipy`](http://scipy.org/scipylib)
+- [`Scipy`](http://scipy.org/scipylib) (does not have full support yet)
+
+Only certain numerical methods and functionalities are available without sparse matrix support.
+
+### Derivatives computation
+
+At least one of the following, depending on requirements:
+
+- [`ASL`](https://github.com/ampl/mp)
 - [`pyadolc`](https://github.com/b45ch1/pyadolc.git)
 - [`algopy`](https://github.com/b45ch1/algopy.git)
 - [`pycppad`](https://github.com/b45ch1/pycppad.git)
+
+Without one of the above dependencies, at least the first derivatives must be coded by hand. Second derivatives may be approximated used a quasi-Newton scheme.
+
+### Factorizations
+
+One or more of the following, depending on requirements:
+
 - [`HSL.py`](https://github.com/PythonOptimizers/HSL.py)
 - [`MUMPS.py`](https://github.com/PythonOptimizers/MUMPS.py)
 - [`qr_mumps.py`](https://github.com/PythonOptimizers/qr_mumps.py)
 - [`SuiteSparse.py`](https://github.com/PythonOptimizers/SuiteSparse.py)
 
-## Installation
-
-1. Clone this repo::
+Only matrix-free methods are available without one of the above factorizations.
 
-        git clone https://github.com/PythonOptimizers/NLP.py
-
-
-2. Copy `site.template.cfg` to `site.cfg` and modify `site.cfg` to match your configuration::
+## Installation
 
-        cp site.template.cfg site.cfg
+1. Clone this repo:
+   ```bash
+   git clone https://github.com/PythonOptimizers/NLP.py
+   ```
 
+2. Optional: Install optional dependencies. OSX users, see `Readme.osx`.
 
-3. Install::
+3. Optional: if you would like ASL support, copy `site.template.cfg` to `site.cfg` and modify `site.cfg` to match your configuration::
+    ```bash
+    cp site.template.cfg site.cfg
+    ```
 
-        python setup.py build
-        python setup.py install [--prefix=...]
+4. Install:
+    ```bash
+    python setup.py build
+    python setup.py install [--prefix=...]
+    ```
diff --git a/Readme.macosx.md b/Readme.macosx.md
@@ -1,34 +1,118 @@
 # Build instructions for Mac OS/X users
 
-Installing NLP.py will be much easier if you use [Homebrew](https://brew.sh).
-Follow the instructions to install Homebrew.
-Then, the following dependencies can be installed automatically:
+If you require one of ASL, `pyadolc`, `pycppad`, MUMPS, qr_mumps or SuiteSparse, installing `NLP.py` will be much easier if you use [Homebrew](https://brew.sh).
+Follow the instructions to install Homebrew and import the *science* formulas:
+```bash
+brew tap homebrew/science
+```
+
+## Requirements
 
+Install `numpy` and `PyKrylov`:
 ```bash
-brew install gcc  # currently v5. Contains gfortran
+pip install -q numpy
+pip install -q git+https://github.com/PythonOptimizers/pykrylov.git@develop
+```
 
-brew tap homebrew/science
-brew install adol-c                             # will also install Colpack
-brew install boost --with-mpi --without-single  # to use pycppad
-brew install cppad --with-adol-c --with-boost --cc=gcc-5
+## Optional Dependencies
+
+### Sparse Matrix Storage
+
+#### CySparse
+
+```bash
+pip install -q git+https://github.com/PythonOptimizers/cysparse.git
+```
+
+#### PySparse
+
+```bash
+pip install -q git+https://github.com/optimizers/pysparse.git
+```
+
+### SciPy
+
+```bash
+pip install -q scipy
+```
+
+### Derivatives Computation
+
+#### ASL
+
+The ASL will allow [AMPL](http://www.ampl.com) models to be loaded in `NLP.py` after they have been decoded to a `.nl` file.
+Creating the `.nl` file for anything else than small models requires an AMPL license.
+A few sample `.nl` files are included with `NLP.py`.
+The ASL will compute sparse first and second derivatives.
+
+The ASL may be installed from Homebrew:
+```bash
 brew install asl
-brew install metis
+```
+Specify the location of the ASL in `setup.cfg`:
+```bash
+echo "[ASL]" > site.cfg
+echo "asl_dir = $(brew --prefix asl)" >> site.cfg
+```
+
+#### ADOL-C
+
+ADOL-C will allow models to be coded up directly in Python and sparse first and second derivatives to be computed via automatic differentiation.
+This is the preferred way to model large-scale problems in Python.
+First install ADOL-C:
+```bash
+brew install adol-c  # will also install Colpack
+brew install boost-python
+```
+Then install `pyadolc`:
+```bash
+cd $HOME  # or another local
+git clone https://github.com/b45ch1/pyadolc.git && cd pyadolc
+python setup.py install  # press [Enter] when prompted
+```
+
+#### CppAD
 
-pip install algopy
-pip install git+https://github.com/b45ch1/pycppad.git
+CppAD will allow models to be coded up directly in Python and *dense* first and second derivatives to be computed via automatic differentiation.
+
+First install CppAD:
+```bash
+brew install cppad [--with-adol-c] --with-openmp
+```
+Then install `pycppad`:
+```bash
+pip install -q git+https://github.com/b45ch1/pycppad.git
 ```
 
-## Installing PyAdolc
+#### AlgoPy
+
+AlgoPy will allow models to be coded up directly in Python and *dense* first and second derivatives to be computed via automatic differentiation.
 
 ```bash
-git clone https://github.com/b45ch1/pyadolc.git
-cd pyadolc
-BOOST_DIR=$(brew --prefix boost-python) ADOLC_DIR=$(brew --prefix adol-c) COLPACK_DIR=$(brew --prefix colpack) CC=clang CXX=clang++ python setup.py install
-cd
-python -c "import adolc; adolc.test()"
+pip install -q algopy
 ```
 
-If you encounter build errors, edit and change `setup.py` as follows:
+### Factorizations
+
+#### HSL.py
+
+Follow instructions at https://github.com/PythonOptimizers/HSL.py
+
+#### MUMPS.py
+
+Follow instructions at https://github.com/PythonOptimizers/MUMPS.py
+
+#### qr_mumps.py
+
+Follow instructions at https://github.com/PythonOptimizers/qr_mumps.py
+
+#### SuiteSparse.py
+
+Follow instructions at https://github.com/PythonOptimizers/SuiteSparse.py
+
+## Troubleshooting
+
+If you encounter build errors while installing `pyadolc`, edit and change `setup.py` as follows:
 ```diff
 diff --git a/setup.py b/setup.py
 index 5e6e695..68f5c68 100644