1. Preface

This book describes different methods for installing the Coopr software. Coopr is a collection of Python software packages that supports a diverse set of optimization capabilities for formulating and analyzing optimization models. A central component of Coopr is Pyomo, which supports the formulation and analysis of mathematical models for complex optimization applications. This capability is commonly associated with algebraic modeling languages (AMLs), which support the description and analysis of mathematical models with a high-level language. Although most AMLs are implemented in custom modeling languages, Pyomo’s modeling objects are embedded within Python, a full-featured high-level programming language that contains a rich set of supporting libraries.

1.1. Goals of the Book

Unfortunately, Coopr is a complex software package that can be difficult to install. Coopr is comprised of a set of independent Python packages that need to be installed together. Coopr also depends on a variety of third-party Python packages, some of which have very different installation processes on different computer operating systems. Furthermore, Coopr can execute third-party optimization solvers, whose installation and configuration is completely independent of Coopr.

In this book, we outline a variety of installation options for different computer operating systems and for different usage models. These installation options reflect the different ways that Coopr developers and users have used Coopr, and they account for user access to system resources.

1.2. Comments and Questions

Further information about Pyomo and Coopr is available on the Coopr wiki:

https://software.sandia.gov/trac/coopr

Coopr is also hosted at COIN-OR:

https://projects.coin-or.org/Coopr

We strongly encourage feedback from readers about the software on the Coopr Forum:

coopr-forum@googlegroups.com

We hope this will include feedback on typos and errors in our examples in this book.

Good Luck!

2. Quick Start

This section provides a quick guide for installing and using the latest Coopr release. Note that the following installation instructions assume that the user has network access. Strategies for off-line installation are described later in this book.

There are two easy ways to install the latest release: (1) using the pip command and (2) using the coopr_install command. These two options have different strengths: installing with pip requires one less step for the latest version of python, and the coopr_install script includes additional options to install other packages that Coopr can leverage. These options are described in the following two sections.

2.1. Installing the Latest Coopr Release With pip

Step 0: Install Python

Linux, Mac OS/X and other Unix variants typically have python pre-installed. But MS Windows does not! Make sure that your PATH environment includes the directory that contains python’s executables.

Step 1: Install pip

The pip package is used to download and install the latest Coopr release. For python versions before 3.4, the pip package will need to be explicitly installed. On Linux, you may be able to install pip with a package manager like yum or apt-get. Alternatively, you can securely download the get-pip.py script using your web browser (or a command-line tool like curl). Then, you execute the following in a shell:

python get-pip.py
Step 2: Install Coopr

The following are alternatives for installing Coopr in different locations on your system.

  • System Python Installation

    If you have administrator access, then you can install Coopr in your system python installation. Execute the following in a shell:

    pip install Coopr

    This installs Coopr in your system python installation.

  • Python’s Alternate User Installation

    You can install Coopr in the user’s home directory. This does not require administrator access, but the Coopr package appears to be installed with the system python. Execute the following in a shell:

    pip install --user Coopr

You can start getting help information for Coopr by executing the following in a shell:

coopr --help
Step 3: Install Third-Party Packages

Coopr has conditional dependencies on a variety of third-party packages. These are not installed with Coopr, and many of them can be installed with the coopr.extras package. The pip command can be used to install this package as follows:

pip install coopr.extras

Note that Coopr has a conditional dependency on the numpy and scipy packages. These are not installed by coopr.extras; they will need to be installed separately by the user. Further, coopr.extras should be installed after these packages are installed; coopr.extras will conditionally install packages that depend on numpy and scipy.

2.2. Installing the Latest Coopr Release With coopr_install

Step 0: Install Python

Linux, Mac OS/X and other Unix variants typically have python pre-installed. But MS Windows does not! Make sure that your PATH environment includes the directory that contains python’s executables.

Step 1: Download coopr_install

The coopr_install script is used to download and install the latest Coopr release. You can download the coopr_install script using your web browser, or you can download from the link coopr_install using a command-line tool like curl.

Step 2: Install Coopr

The following are alternatives for installing Coopr in different locations on your system.

  • System Python Installation

    If you have administrator access, then you can install Coopr in your system python installation. Execute the following in a shell:

    coopr_install

    This installs Coopr in your system python installation.

  • Python’s Alternate User Installation

    You can install Coopr in the user’s home directory. This does not require administrator access, but the Coopr package appears to be installed with the system python. Execute the following in a shell:

    coopr_install --user

You can start getting help information for Coopr by executing the following in a shell:

coopr --help
Step 3: Install Third-Party Packages

Coopr has conditional dependencies on a variety of third-party packages. These are not installed with Coopr, and many of them can be installed with the coopr.extras package. You can install coopr.extras with Coopr by simply using the --with-extras option when running coopr_install. Alternatively, you can directly install coopr.extras using pip:

pip install coopr.extras

Note that Coopr has a conditional dependency on the numpy and scipy packages. These are not installed by coopr.extras; they will need to be installed separately by the user. Further, coopr.extras should be installed after these packages are installed; coopr.extras will conditionally install packages that depend on numpy and scipy.

2.3. Getting Started

2.3.1. Install Third-Party Solvers

Most users will want to install third-party solvers to analyze optimization models built with Coopr. The command

coopr solvers

provides documentation about Coopr’s solver interfaces, and it will dynamically check for available solvers.

Note Users with network access can remotely optimize Coopr models on the NEOS server, so optimization solvers do not need to be installed to get started with Coopr.

2.3.2. Run Python with Coopr Installed

If the PATH environment has been configured to include the system python installation, then the Coopr scripts can be executed without further configuration. The simplest way to get started with Coopr is to import the coopr package that you wish to work with. For example, you would import coopr.pyomo to use Pyomo:

\$ python
Python 2.7.5 (default, Aug  1 2013, 01:01:17)
[GCC 4.2.1 Compatible Apple Clang 4.1 ((tags/Apple/clang-421.11.66))] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import coopr.pyomo
>>>

See Getting Started with Coopr for further discussion of how to use Coopr packages.

2.3.3. Run A NEOS Optimizer

As a quick test of your installation, you can used Coopr to analyze the diet problem. Download the diet.py model file and diet1.dat data file here: https://software.sandia.gov/svn/public/coopr/coopr.pyomo/trunk/examples/pyomo/diet. If you have network access, then you can run the pyomo command to optimize this model:

pyomo --solver-manager=neos --solver=cbc diet1.py diet.dat

You should get an output like the following:

[    0.00] Setting up Pyomo environment
[    0.00] Applying Pyomo preprocessing actions
[    0.00] Creating model
[    0.03] Applying solver
[    0.05] Processing results
    Number of solutions: 1
    Solution Information
      Gap: 0.0
      Status: optimal
      Function Value: 2.81
    Solver results file: results.json
[    0.14] Applying Pyomo postprocessing actions
[    0.14] Pyomo Finished

2.3.4. Run A Locally Installed Optimizer

The pyomo command can also use a solver that is installed locally. For example, if you have installed the glpk software, then you can optimize this model as follows:

pyomo --solver=glpk diet1.py diet.dat

3. Overview

Coopr is available under the BSD open-source license. The following table describes different installation options that are described below:

Installation Overview

Installation options can be differentiated based on where the Coopr source is downloaded and where Coopr is installed. Coopr can be installed from

  1. PyPI - the standard python distribution server

  2. ZIP File - a ZIP file that contains Coopr source files

  3. Trunk - the subversion repository that contains the latest Coopr revisions.

Coopr can be installed in

  1. System Python - python’s site packages directory

  2. User HOME - the user’s HOME directory

  3. Virtual Environment - a python virtual environment that is created in a user-specified directory

Only a subset of these options are recommended for general users, and only a few others are supported for developers.

The Prerequisites chapter discusses packages that you may need to install Coopr. Coopr requires one of the following python versions: 2.6 2.7, 3.2, 3.3 or 3.4. Coopr also requires the installation of several freely available python libraries, but these are automatically installed with Coopr. This chapter also describes python packages that may influence the installation of the coopr.extras package, which installs python packages that enhance Coopr’s functionality.

Chapter Installing Coopr for Users describes four installation options for Coopr users. This chapter discusses installation with coopr_install, pip and MS Windows installers. Chapter Installing Coopr for Developers describes three additional installation options for Coopr developers. These installation options can only be performed with coopr_install.

Additional installation details are provided in subsequent chapters:

  • Optional Packages: Other packages that Coopr can optionally leverage.

  • Installation Issues: Helpful information for resolving issues with Coopr installation.

  • Platform Notes: Documentation of platform-specific issues, especially for installation.

  • Solver Notes: Documentation for third-party solvers that can be called from Coopr.

4. Prerequisites

4.1. Python Version

Coopr requires Python versions 2.6, 2.7, 3.2, 3.3 or 3.4. In particular, some components rely on Python modules that exhibited known bugs in Python 2.4. Further, we rely on and benefit from several packages and performance improvements introduced in Python 2.6.

  • Windows users:

    The Python web site provides binary downloads for MS Windows installers. Recall that the PATH environment variable may need to be updated, as the installers typically do not update it automatically. On Windows, this can be easily accomplished via the Control Panel "Advanced System Settings" panel.

  • Linux/UNIX users:

    Most flavors of Unix ship with Python, and a compatible version of Python can often be easily installed using your distribution’s package manager. Note that you will need to install both the python package and (if separate) the python-devel package (to get the Python header files that are needed to compile some external applications distributed with Coopr). Most Linux installers put the Python executable on a common location on your path. If this is not the case for your particular distribution, you can add the location to your shell’s PATH environment variable.

  • Mac users:

    The Python web site provides binary downloads for Mac installers. Recall that the PATH environment variable may need to be updated, as these installers typically do not update it automatically.

Please be aware of 32-bit versus 64-bit issues, particularly if you are running Windows. In particular, if running a 64-bit Windows OS (likely at this point, but not so with XP or earlier versions), you should use the Python 2.X.Y Windows X86-64 installer, as opposed to the (32-bit) Python 2.X.Y Windows installer. If you run 32-bit Python on a 64-bit Windows platform, for example, you will not have access to more than 3GB of RAM (actually a bit less) - even when your machine has more.

Note that several Python distributions are available that are bundled with third-party packages (e.g. SciPy and MatPlotLib):

4.2. Installers

Installing Coopr requires that one of the following installation tools or executables be downloaded: the pip python package, the coopr_install script or the MS Windows installer executable.

4.2.1. Pip

The pip package can be used to download and install the latest Coopr release. For python versions before 3.4, the pip package will need to be explicitly installed. On Linux, you may be able to install pip with a package manager like yum or apt-get. Alternatively, you can securely download the get-pip.py script using your web browser (or a command-line tool like curl). Then, you execute the following in a shell:

python get-pip.py

The pip command requires internet access to download Coopr and the packages it depends on. You need to specify the HTTP_PROXY environment to install from PyPI through a proxy server.

4.2.2. The coopr_install Script

The coopr_install script is used to download and install the latest Coopr release. The coopr_install has a --help option that provides detailed help instructions.

You can download the coopr_install script using your web browser, or you can download from the link coopr_install using a command-line tool like curl.

Depending on the command-line options, the coopr_install command may require internet access to download Coopr and the packages it depends on. Specifically, you may need to specify the HTTP_PROXY environment to install from PyPI through a proxy server. Also, developers installing the Coopr trunk may need to configure their subversion configuration to specify a proxy server.

Note The coopr_install command has not been developed or tested on MS Windows. Although some of the installation strategies supported by coopr_install may work on MS Windows, this installer is not recommended for that platform.
Note The coopr_install is a rework of earlier Coopr installation scripts, one of which had the name coopr_install. This new script does not bundle Python packages. Instead, it either installs packages from PyPI or it installs from a ZIP file.

4.2.3. The MS Windows Installer

MS Windows installers are available for Coopr to install the latest Coopr release. These executables install Coopr in the system Python installation. Additionally, these installers do not require internet access, since they bundle the Coopr packages along with the third-party packages that are required by Coopr.

You can download the Coopr installers from the Coopr download site. The installers have the name Coopr_VERSION_DATE-setup.exe.

4.3. Numpy and Scipy

Coopr leverages the numpy and scipy packages to support scipy optimizers and to enable the initialization of Coopr models with numpy data structures. As we noted earlier, these packages are bundled with some Python distributions. See the SciPy Installation Guide for further guidance installing these packages.

4.4. Subversion (For Developers)

Installation of the Coopr trunk requires the subversion software. On Unix systems, this is commonly pre-installed. On Windows, subversion installers can be obtained from CollabNet.

Only the command-line client is necessary; specifically, the "CollabNet Subversion Command Line" distribution should be used. Do 'not' install "CollabNet Subversion Edge", as it downloads and installs Python 2.5. While the CollabNet download is free, CollabNet will require you to create a login - presumably to track usage statistics. The installer updates the system PATH variable automatically.

5. Installing Coopr for Users

The following table summarizes the different installation options that are recommended for users:

Installation Recommendations for Users

Users can install Coopr from PyPI or a ZIP file, and Coopr can be installed either in the system python directories or in the user’s HOME directory. Each of these options are described in the following sections; there may be multiple ways to install a specific installation option, and these are documented together.

Note Installing from a ZIP file is supported to enable users to install a snapshot of Coopr. Daily snapshots are available from the Coopr download site; download the file coopr_votd.zip.

5.1. Option 1a: Installation from PyPI into the System Python Directory

This installation option downloads the latest Coopr release from PyPI that is installed in the system python installation. Note that this installation option requires administrator access.

The following command uses pip to download and install Coopr:

pip install Coopr

On Linux and Mac systems, you may need to run this command with sudo to provide administrator access:

sudo pip install Coopr

Similarly, the following command uses coopr_install to download and install Coopr:

coopr_install

The sudo command may also be required on Linux and Mac systems.

5.2. Option 1b: Installation from PyPI into the User’s HOME Directory

This installation option downloads the latest Coopr release from PyPI that is installed using python’s alternate user installation. The alternate user installation is included in python’s packages, so this installation option does not require additional customization of python.

Note This installation strategy installs Coopr in the user’s HOME directory. The specific directory name depends on the type of machine; see the python documentation for further details.

The following command uses pip to download and install Coopr:

pip install --user Coopr

Similarly, the following command uses coopr_install to download and install Coopr:

coopr_install --user

5.3. Option 2a: Installation from a ZIP File into the System Python Directory

This installation option installs Coopr from a ZIP file, and Coopr is installed in the system python installation. Note that this installation option requires administrator access. This installation is done offline; no external dependencies are installed and no network access is required.

The following command uses coopr_install to extract files from the ZIP file and install Coopr:

coopr_install --zip=coopr_votd.zip

Similarly, MS Windows installers can be used to install Coopr releases in the system python installation. An installer executable is simply executed to perform installation. However, the ZIP file is not specified when executing this installer; Coopr ZIP files are bundled with the MS Windows installers.

A user can customize the installation process as follows:

  • The registry is checked to see if a previous Coopr installation needs to be uninstalled

  • The user can optionally install additional Python packages that are used by Coopr (e.g. PyYAML and PyQt)

  • A log of the install process is captured to help diagnose errors

Note The PATH environment must be edited to include the Scripts directory in their Python installation. For example, Python 2.6 is normally installed in C:\Python26\Scripts. The PATH environment would need to be appended with ;C:\Python26\Scripts for the Coopr executables to be executed from a DOS shell.

5.4. Option 2b: Installation from a ZIP File into the User’s HOME Directory

This installation option installs Coopr from a ZIP file, and Coopr is installed using python’s alternate user installation. This installation is done offline; no external dependencies are installed and no network access is required. The alternate user installation is included in python’s packages, so this installation option does not require additional customization of python.

Note This installation strategy installs Coopr in the user’s HOME directory. The specific directory name depends on the type of machine; see the python documentation for further details.

The following command uses coopr_install to extract files from the ZIP file and install Coopr:

coopr_install --zip=coopr_votd.zip --user

6. Installing Coopr for Developers

The following table summarizes all of the different installation options that are supported for Coopr:

Installation Recommendations for Developers

There are three additional options that are supported for developers, all of which install Coopr in a virtual python environment. A virtual python environment is an isolated python installation that depends on the system python installation, but which mimics a complete python installation. A virtual python environment can be created by a user in their directory without requiring administrative privileges.

6.1. Option 1c: Installation from PyPI into a Virtual Environment

This installation option downloads the latest Coopr release from PyPI that is installed in a virtual python environment.

The following command uses coopr_install to download and install Coopr:

coopr_install --venv=coopr

The virtual python environment is created in the coopr directory, and the command coopr/bin/python executes a virtual python environment into which Coopr has been installed.

6.2. Option 2c: Installation from a ZIP File into a Virtual Environment

This installation option installs Coopr from a ZIP file, and Coopr is installed in a virtual python environment. This installation is done offline; no external dependencies are installed and no network access is required.

The following command uses coopr_install to extract files from the ZIP file and install Coopr:

coopr_install --zip=coopr_votd.zip --venv=coopr

The virtual python environment is created in the coopr directory, and the command coopr/bin/python executes a virtual python environment into which Coopr has been installed.

6.3. Option 3c: Installation from Trunk into a Virtual Environment

This installation option uses subversion to checkout Coopr packages, and Coopr is installed in a virtual python environment.

The following command uses coopr_install to extract files from the ZIP file and install Coopr:

coopr_install --trunk --venv=coopr

The virtual python environment is created in the coopr directory, and the command coopr/bin/python executes a virtual python environment into which Coopr has been installed.

7. Optional Packages

7.1. coopr.extras

The coopr.extras packages installs a variety of packages that extend Coopr’s functionality, including:

  • Pyro - This library supports distributed parallel communication in python.

  • Suds - This library provides a lightweight SOAP client that is used by coopr.neos to remotely launch optimizers on the NEOS server.

  • PyYaml - When this library is installed, many Coopr packages will Yaml instead of Json for user-friendly I/O.

  • OpenOpt - This library provides interfaces for a variety of optimizers.

7.2. Pywin32

On Windows, it may be necessary to install the Python Windows extensions. This package enables Python to support Windows COM interfaces, and specifically it allows Pyomo to work with Excel spreadsheets. Note that "pywin32" is a bit of a misnomer, in that it works fine on 64-bit platforms; based on what we can tell, the "32" just means "non-16-bit".

The installer for this extension is available from http://sourceforge.net/projects/pywin32. This install simply updates the python site packages.

7.3. PyODBC

Coopr uses the PyODBC package to access ODBC data sources. On Windows, the PyODBC package can be installed by downloading a Windows installer, or by executing easy_install:

easy_install pyodbc

On Linux and Mac OS X, you need to install several system-level packages for proper ODBC functionality. These include:

  • unixODBC: provides generic ODBC connectivity

  • unixODBC-devel: includes ODBC development headers for linking with other libraries

  • mdbtools: implements Microsoft Jet (Access) database interaction

  • libmdbodbc: bridges Jet databases via ODBC

Finally, users on such Unix-based systems may have to configure their local ODBC installations for Jet databases if using Microsoft Access. To do so, add the following to the file /etc/odbcinst.ini:

[Microsoft Access Driver (*.mdb)]
Description = MDB Tools ODBC drivers
Driver      = /usr/lib/libmdbodbc.so.0
Setup       =
FileUsage   = 2

Pyomo will attempt to add any further ODBC information as needed.

8. Installation Issues

Here are some of the most common issues encountered by Coopr users. If you do not see your question answered here, the best route for getting an answer is by engaging the Coopr community through the coopr-forum mailing list.

8.1. Python Installation

The standard Python distribution is built with the C language, and thus this is sometimes called CPython. CPython distributions are available for all major platforms, and this is the most common version of Python that is used in practice. Linux and Macintosh distributions commonly include CPython, and no additional configuration is required to execute the Python interpreter.

On Windows platforms, CPython can be easily installed with an installer executable. However, the user must edit the PATH environment variable to include the Python installation path.

Other noteworthy implementations of Python are Jython, written in Java, IronPython, written for the Common Language Runtime, and PyPy, a Python interpreter writen in Python. A major difference between CPython, Jython and IronPython is that they support extensions with C, Java and .NET application framework respectively. PyPy supports these extensions depending on the underlying Python interpreter, and it uses a JIT compiler to improve the execution of Python code.

Coopr is developed and tested using CPython. Other Python implementations have been evaluated, and their status is summarized here:

  • Jython: The virtualenv package is not supported in Jython. This package is critical for the development, testing and deployment of Coopr.

  • IronPython: This Python implementation does not currently support installation with setuptools or distribute, which are commonly used installation mechanisms in CPython. Coopr depends on these packages.

  • PyPy: Many Coopr package install with PyPy. There remain some issues with reference counting in Python, which are documented in Coopr ticket #4437.

Most Coopr packages are designed to work with version 2.6 and 2.7. The Python language underwent some rather large changes in version 3.0. These changes are not directly backward-compatible with Python 2.x, and consequently Coopr does not currently work with Python 3.x.

8.2. Coopr Installation

8.2.1. Help with coopr_install

There are numerous options to the coopr_install script, which can be displayed by typing:

./coopr_install --help
Important Make sure you do 'not' have the PYTHONHOME environment variable defined prior to installing Coopr. Such a definition interferes with the construction of the Coopr virtualized Python environment.

8.2.2. Using the HTTP_PROXY Environment Variable

In many computing environments, it may be necessary to set the HTTP_PROXY environment variable to use the wget and coopr_install commands. A typical value for this variable is something like "http://foo.institution.domain:80". Your local system administrator can help you assess whether you need an HTTP proxy for web access. For example, at Sandia (New Mexico only) the proxy http://sonproxy.sandia.gov:80 is used for the SON network, and http://wwwproxy.sandia.gov:80 is used for the SRN network.

8.2.3. Installing on MS Windows

There is a known problem with MS Windows Coopr installations. Coopr depends on the PyYAML package, which does not install under MS Windows with the 64-bit Python build. Thus, Coopr requires the 32-bit build for MS Windows.

8.2.4. Installation error: Filename … does not start with any of these prefixes: …

We have seen the error:

Installation error: Filename ... does not start with any of these prefixes: ...]

when installing on Windows. This appears to be a limitation of the virtual environment logic. Specifically, this was triggered by explicitly specifying the Python path with a lower-case drive name. For example:

c:\Python27\python.exe coopr_install

Using a capital drive name resolved this issue:

C:\Python27\python.exe coopr_install

8.2.5. Installation error: Setup script exited with error: command gcc failed …

Several Python packages that Coopr relies on (e.g., coverage and PyYAML) include compiled "C" extensions. This error indicated that the extensions did not successfully compile. In most cases, the root cause is that the Python C headers are not installed or available on your system. For Linux/UNIX users, make sure you have the python-devel package installed.

8.3. Using Subversion with a Proxy

Subversion does not use the HTTP_PROXY environment variable to configure its behavior. Rather, this must be done by modifying the local subversion configuration. As expected, this differs on Windows and Unix platforms, and is environment-specific. However, the step-by-step process is somewhat generic. Sandia-specific instructions can be found [sandbox:UsingSubversion here]. The same instructions should be applicable in other environments by appropriately substituting the name of your local proxy server.

8.4. Python environment variables

The PYTHONPATH and PYTHONHOME environment variables are used to customize the way that Python is configured. The PYTHONHOME variable defines the location of the standard Python libraries that are used, and PYTHONPATH augments the default search path for module files.

Since Coopr is installed in a virtual Python environment, these environment variables are generally not necessary. We have seen many cases where Coopr scripts failed to operate properly when these variables were defines, so we generally recommend that the user disable these variables before installing Coopr and executing Coopr scripts.

9. Platform Notes

We have successfully installed and executed Coopr on a wide range of platforms. In the course of doing so (and helping other users do so), we have identified a number of issues that are worth mentioning, and easily correctable.

9.1. Windows XP, Vista, and 7

An issue we have observed on Windows Vista is the following error:

WindowsError: [Error 740] The requested operation requires elevation

This issue is due to the new and "improved" Windows Vista permissions scheme. Basically, python.exe needs to run with administrator privileges, e.g., to compile things in site packages. To accomplish this, simply navigate via Explorer to where python.exe is located (typically C:\Python2.6) and right-click on the python.exe icon. Then, select the "Compatability" tab and check the "Run this program as an administrator" box.

In addition, some distributions of CPLEX and AMPL appear to have overloaded the name for the CPLEX.exe executable. Coopr currently interacts with CPLEX via the command-line, interactive version, and not the version with the AMPL/NL driver. The symptom of this situation is a failed solve, which can be easily diagnosed by turning on the "--keepfiles" option in pyomo and looking at the CPLEX output log. The fix is to simply make sure the interactive CPLEX is first in your PATH environment variable.

9.2. Windows 7

To install on Windows 7 (and possibly other Windows systems), it is necessary to run with administrator privileges when installing Coopr. Otherwise, the coopr_install script will generate error messages indicating the lack of write permission in various directories. If installing from the command prompt, one can right-click on the "Command Prompt" icon and select "Run as administrator" to obtain such permissions. It is worth noting that this is not always necessary, as in many environments users are automatically granted administrator privileges.

Various users have observed issues when running coopr_install under Windows 7, related to the subversion client obtained from http://tortoisesvn.tigris.org. In particular, you may observe the following error:

Can't move '.svn/tmp/entries' to '.svn/entries': The file or directory is corrupted and unreadable.

To quote the Tigris site:

This error message typically occurs when you try to update or commit
your working copy, and seems to be common on Windows 7 systems. It
is due to another process holding a handle on a file that Subversion
needs to move or modify. This might be a virus scanner, but on
Windows 7 it is likely to be the Windows Indexing Service. Turn off
the indexing service on your working copies and repositories, and
exclude them from virus scans.

Some combination of disabling the indexer and the antivirus software seems to correct the problem; please let us know if this is not the case.

9.3. Red Hat Linux

No issues involving installation on Red Hat systems have been observed.

9.4. Ubuntu Linux

Some distributions of Ubuntu do not install by default with subversion. Users and/or their system administrators will need to install this package.

Similarly, some Ubuntu distributions do not appear to have a full python 2.6 install. Specifically, the cProfile package can be missing, and will need to be installed.

9.5. MacOS (Snow Leopard)

At least one user has reported problems during execution of the coopr_install script on MacOS, specifically related to the installation of the "psutils" package. When attempting to compile this package, one may observe numerous compile errors relating to various system header files. This issue appears to be due to ARCHFLAGS on some systems defaulting to the PowerPC architecture. To fix this issue, first execute:

sudo ARCHFLAGS="-arch i386 -arch x86_64" easy_install psutil

Next, re-execute coopr_install. With psutil successfully installed, coopr_install will simply use the installed package and skip the re-install.

10. Solver Notes

Coopr includes interfaces to a variety of third-party solvers. We do not attempt to document the installation of these packages. This chapter provides notes for how the user environment needs to be configured so Coopr can automatically detect and execute these solvers.

10.1. ASL Solvers

The AMPL Solver Library (ASL) provides a general interface for reading an AMPL NL file. Coopr provides a general interface for any solver that employs that ASL. That is, Coopr executes ASL solvers with the same command-line syntax that is used by AMPL, and the SOL result files are read to represent the solver results in Coopr. Coopr can execute NL files generated by AMPL or Coopr’s Pyomo modeling package.

See the AMPL web pages for a summary of the ASL solvers that are available. Many of these have commercial support, and there are a variety of mature open source ASL solvers.

10.2. CBC

CBC is an open-source solver for linear programs and mixed-integer linear programs. CBC is written in C+\+, and it provides a stand-alone executable.

See the CBC wiki for download and installation instructions. The directory containing the cbc executable must be in the list of paths defined by the PATH environment variable.

10.3. CPLEX

The IBM ILOG CPLEX Optimizer includes commercial mathematical programming solvers for linear programming, mixed integer programming, quadratic programming, and quadratically constrained programming problems.

Coopr has solver interfaces for the CPLEX command as well as the CPLEX Python environment. To use the CPLEX command, the directory containing the cplex executable must be in the list of paths defined by the PATH environment variable. There are a variety of ways that the CPLEX Python environment can be used with Coopr. Perhaps the simplest is to install the CPLEX python package.

For example, if the CPLEX Python directory is /usr/local/ilog/cplex/python, then you can install Coopr with this package installed as follows:

coopr_install --venv=coopr
cd /usr/local/ilog/cplex/python
coopr_python setup.py develop

The last step installs CPLEX’s python package within Coopr’s virtual environment in developer mode.

10.4. GLPK

The GLPK (GNU Linear Programming Kit) package is intended for solving large-scale linear programming (LP), mixed integer programming (MIP), and other related problems. It is a set of routines written in ANSI C and organized in the form of a callable library.

See the GLPK website for download and installation instructions. The directory containing the glpsol executable must be in the list of paths defined by the PATH environment variable.

10.5. GUROBI

The Gurobi Optimizer is a commercial solver for linear programming (LP), quadratic programming (QP) and mixed-integer programming (MILP and MIQP).

Although Gurobi Optimizer supports a Python environment, Coopr only interfaces with the Gurobi command. The directory containing the gurobi.sh (Linux) or gurobi.bat (MS Windows) executable must be in the list of paths defined by the PATH environment variable.

10.6. PICO

PICO is a solver for linear programming and mixed-integer linear programming problems that can perform parallel optimization on distributed memory machines.

PICO is a component of Acro, an open-source software project that integrates a variety of optimization software packages, including both libraries developed at Sandia National Laboratories as well as publicly available third-party libraries. Acro’s Getting Started wiki pages provides instructions for downloading and installing Acro projects that include PICO. The directory containing the PICO executable must be in the list of paths defined by the PATH environment variable; typically this will be the acro/bin directory.

11. Colophon

This book was created using asciidoc software.

The Sandia National Laboratories Laboratory-Directed Research and Development Program and the U.S. Department of Energy Office of Science Advanced Scientific Computing Research Program funded portions of this work.

Sandia National Laboratories is a multi-program laboratory managed and operated by Sandia Corporation, a wholly owned subsidiary of Lockheed Martin Corporation, for the U.S. Department of Energy’s National Nuclear Security Administration under contract DE-AC04-94AL85000. SAND 2012-1572P.

Sandia National Laboratories
United States Department of Energy