
\chapter{Introduction}

This is a preliminary draft at a Pyomo Reference manual.  There are some big picture issues that need to be addressed:
\begin{itemize}
\item What is the scope of this document?  Should it include Coopr Opt?  How about PySP?
\item Should this include all aspects of Coopr?
\item What specific chapters should we include ... even if we stay focused on Pyomo?
\end{itemize}

\section{Introduction}

The Python Optimization Modeling Objects (Pyomo) software package
supports the definition and solution of optimization applications using
the Python scripting language.  Python is a powerful dynamic programming
language that has a very clear, readable syntax and intuitive object
orientation.  Pyomo includes Python classes for sparse sets, parameters,
and variables, which can be used to formulate algebraic expressions that
define objectives and constraints.  Thus, Pyomo can be used to concisely
represent mixed-integer linear programming (MILP) models for large-scale,
real-world problems that involve thousands of constraints and variables.
Further, Pyomo includes a flexible framework for applying optimizers to
analyze these models.

The design of Pyomo is motivated by a variety of factors that have
impacted applications at Sandia National Laboratories.  Sandia's discrete
mathematics group has successfully used AMPL~\citep{AMPL,FouGay03}
to model and solve large-scale integer programs for many years.
This application experience has highlighted the value of Algebraic
Modeling Languages (AMLs) for solving real-world applications, and AMLs
are now an integral part of operations research solutions at Sandia.

Pyomo was developed to provide an alternative platform for developing math
programming models that leverages Python's rich programming environment to
facilitate the application and deployment of optimization capabilities.
Pyomo is not intended to perform modeling {\em better} than existing
tools.  Instead, it supports a different modeling approach for which
the software is designed for flexibility, extensibility, portability,
and maintainability.

TODO: Review our goals?  1) Fully embedded modeling language, 2) Open source, 3) generic solvers, 4) extensibility.  We review our goals in detail in the next section, so it seems funny to summarize them here.  NOTE: we don't mention generic solvers later.  Do we really have space to include that in this paper???

TODO: mention Open Source here?  The point would be to say that the goal of Pyomo is not just
to provide a free framework, but instead provide a framework that can be customized and extended.  I'm not sure how to blend that theme with the previous paragraph

TODO: introduce Coopr here

Pyomo is integrated into Coopr, a COmmon Optimization
Python Repository. The Coopr Opt package supports the execution of models
developed with Pyomo using standard MILP solvers.


\if 0
Section~\ref{sec:design} describes the motivation and design philosophy
behind Pyomo, including why Python was chosen for the design of
Pyomo.  Section~\ref{sec:bg} describes related high-level modeling
approaches, including other Python packages for modeling math programs.
Section~\ref{sec:pyomo} compares and contrasts the use of AMPL and
Pyomo on a simple application.  Section~\ref{sec:opt} describes how
Pyomo leverages the capabilities in the Coopr Opt package.  Finally,
Section~\ref{sec:discussion} describes future Pyomo developments that
are planned.
\fi


\section{Design Goals and Requirements}
\label{sec:design}

The following sections describe the design goals and requirements that
have guided the development of Pyomo.  The design of Pyomo has been driven
by a two different types of projects at Sandia.  First, Pyomo has been
used by research projects that need a flexible framework for customizing
the formulation and evaluation of math programming models.  Second,
projects with external users often require that math programming modeling
techniques be deployed without commercial licenses.

\subsection{Open Source}

A key goal of Pyomo is to provide an open-source math programming
modeling capability.  Although open-source optimization solvers are widely
available in packages like COIN-OR, surprisingly few open-source tools
have been developed to model optimization applications.  An open-source
capability for Pyomo is motivated by several factors:
\begin{itemize}

\item {\bf Transparency and Reliability}: When managed well,
open-source projects facilitate transparency in the software design and
implementation. Since any developer can study and modify the software,
bugs and performance limitations can be identified and resolved by a wide
range of developers with diverse software experience.  Consequently,
there is growing evidence that managing software as open-source can
improve its reliability.

\item {\bf Flexible Licensing}: A variety of significant operations
research applications at Sandia have required the use of a modeling tool
with a non-commercial license.  There have been many different reasons
for this requirement, including the need to support open-source analysis
tools, limitations for software deployment on classified computers,
and licensing policies for commercial partners (e.g. that are motivated
by minimizing the costs of deploying an application model internally
within a large company).  The Coopr software, which contains Pyomo,
is licensed under the BSD.

\end{itemize} Although the use of an open-source model is not a panacea;
ensuring high reliability of the software requires careful software
management and a commited developer community.  However, there is
increasing recognition that open source software provides many advantages
beyond simple cost savings~\citep{Forrester}, including supporting open
standards and avoiding being locked in to a single vendor.


\subsection{Customizable Capability}

A key limitation of commercial modeling tools is the ability to customize
the modeling or optimization process.  Pyomo's open-source project model
allows a diverse range of developers to prototype new capabilities.
Thus, developers can customize the software for specific applications,
and they can prototype capabilites that are integrated into future

More generally, Pyomo is designed to support a ``stone soup'' development
model where each developer ``scratches their own itch''.  A key element
of this design is the plugin framework that Pyomo uses to integrate
components like optimizers, optimizater managers, and model format
conversions.  This framework manages the registration of components,
and it automates the interaction of these components through well-defined
interfaces.  Thus, users can customize Pyomo in a modular manner without
risk of destabilizing core functionality.


\subsection{Solver Integration}

Modeling tools can be roughly categorized into two classes based on
how they integrate with optimization solvers: {\em tightly coupled}
modeling tools directly link in optimization solver libraries (including
dynamic linking), and {\em loosely coupled} modeling tools apply external
optimization executables (e.g. through system calls).  Of course, these
options are not exclusive, and a goal of Pyomo is to support both types
of solver interfaces.

This design goal has led to a distinction in Pyomo between model
formulation and optimization execution.  Pyomo uses a high level
programming language to formulate a problem that can be solved by
optimizers written in low-level languages.  This two-language approach
leverages the flexibility of the high-level language for formulating
optimization problems and the efficiency of the low-level language for
numerical computations.


\subsection{Abstract Models}

A requirement of Pyomo's design is that it support the definition of
abstract models in a manner similar to the AMPL.  AMPL separates the
declaration of a model from the data that generates a model instance.
This is supports an extremely flexible modeling capability, which has
been leveraged extensively in applications at Sandia.

To mimic this capability, Pyomo uses a symbolic representation of data,
variables, constraints, etc.  Model instances are then generated from
external data sets using construction routines that are provided by the
user when defining sets, parameters, etc.  Further, Pyomo is designed
to use data sets in the AMPL format to facilitate translation of models
between AMPL and Pyomo.


\subsection{Flexible Modeling Language}

Another goal of Pyomo is to directly use a modern programming language
to support the definition of math programming models.  In this
manner, Pyomo is similar to tools like FlopC++~\citep{flopcpp}
and OptimJ~\citep{OptimJ}, which support modeling in C++ and Java
respectively.  The use of an existing programming language has several
advantages:
\begin{itemize}

\item {\bf Extensibility and Robustness}: A well-used modern programming
language provides a robust foundation for developing and applying models,
because the language has been well-tested in a wide variety of contexts.
Further, extensions typically do not require changes to the language
but instead involve additional classes and modeling routines that can
be used in the modeling process.  Thus, support of the modeling language
is not a long-term factor when managing the software.

\item {\bf Documentation}: Modern programming languages are typically
well-documented, and there is often a large on-line community to provide
feedback to new users.

\item {\bf Standard Libraries}: Languages like Java and Python have a
rich set of libraries for tackling just about every programming task.
For example, standard libraries can support capabilities like data
integration (e.g. working with spreadsheets), thereby avoiding the need
to directly support this in a modeling tool.

\end{itemize}
An additional aspect of general-purpose programming languages is that
they can support modern language features, like classes and first-class
functions, that can be critical when defining complex models.

Pyomo is implemented in Python, a powerful dynamic programming language
that has a very clear, readable syntax and intuitive object orientation.
When compared with AMLs like AMPL, Pyomo has a more verbose and complex
syntax.   Thus, a key issue with this approach concerns the target user
community and their level of comfort with standard programming concepts.
Our examples in this paper compare and contrast AMPL and Pyomo models,
which illustrate this trade-off.


\subsection{Portability}

A requirement of Pyomo's design is that it work on a diverse range of
compute platforms.  In particular, working well on both MS Windows and
Linux platforms is a key requirement for many Sandia applications.
The main impact of this requirement has been to limit the choice
of programming languages.  For example, the .Net languages were not
considered for the design of Pyomo due to portability considerations.



\section{Why Python?}
\label{sec:python}

Pyomo has been developed in Python for a variety of reasons.  First, Python meets the criteria outlined in the previous section:
\begin{itemize}

\item {\bf Open Source License:} Python is freely available, and its
liberal open source license lets you modify and distribute a Python-based
application with few restrictions.

\item {\bf Features:} Python has a rich set of datatypes, support for
object oriented programming, namespaces, exceptions, and dynamic loading.

\item {\bf Support and Stability:} Python is highly stable, and it is
well supported through newsgroups and special interest groups.

\item {\bf Documentation:} Users can learn about Python from extensive
online documentation, and a number of excellent books that are commonly
available.

\item {\bf Standard Library:} Python includes a large number of useful modules.

\item {\bf Extendability and Customization:} Python has a simple model
for loading Python code developed by a user.  Additionally, compiled
code packages that optimize computational kernels can be easily used.
Python includes support for shared libraries and dynamic loading, so
new capabilities can be dynamically integrated into Python applications.

\item {\bf Portability:} Python is available on a wide range of compute
platforms, so portability is typically not a limitation for Python-based
applications.

\end{itemize}


Several other popular programming languages were also considered for Pyomo.  However, in most cases Python appears to have distinct advantages:
\begin{itemize}

\item {\bf .Net:} As mentioned earlier, the .Net languages are not
portable to Linux platforms, and thus they were not suitable for Pyomo.

\item {\bf Ruby:} At the moment, Python and Ruby appear to be the two
most widely recommended scripting languages that are portable to Linux
platforms, and comparisons suggest that their core functionality is
similar.  Our preference for Python is largely based on the fact that
it has a nice syntax that does not require users to type weird symbols
(e.g. \$, \%, @).  Thus, we expect this will be a more natural language
for expressing math programming models.

\item {\bf Java:} Java has a lot of the same strengths as Python, and
it is arguably as good a choice for Pyomo.  However, Python has a
powerful interactive interpreter that allows realtime code development
and encourages experimentation with Python software.  Thus, users can work
interactively with Pyomo models to become familiar with these objects and
to diagnose bugs.  

\item {\bf C++:} Models formulated with the FlopC++~\citep{flopcpp}
package are similar to models developed with Pyomo.  They are be
specified in a declarative style using classes to represent model
components (e.g. sets, variables and constraints).  However, C++
requires explicit compilation to execute code, and it does not support
an interactive interpreter.  Thus, we believe that Python will provide
a more flexible language for users.

\end{itemize}

We also considered developing a domain-specific AML.  Domain-specific
AMLs have can support a concise, expressive syntax, with a clear semantic
interpretation.  However, it is difficult to develop and maintain an AML.
For example, there is extensive documentation on Python and other standard
programming languages.   By comparison, AMLs for math programming are
sparsely documented.  Additionally, it is a significant commitment to
develop an AML that provides the full suite of capabilities that are
available in modern programming languages (e.g. standard libraries,
and interoperability with different programming languages).

Finally, we note that run-time performance was not a key factor in
our decision to use Python.  Recent emperical comparisons suggest
that scripting languages offer reasonable alternatives to languages
like C and C++, even for tasks that must handle fair amounts of
computation and data~\citep{621567}.  Further, there is evidence
that dynamically typed languages like python allow users to be
more productive than with statically typed languages like C++ and
Java~\citep{tratt__dyamically_typed_languages,PythonVSJava}.  It is widely
acknowledged that Python's dynamic typing and compact, concise syntax
makes software development quick and easy.   Thus, it is not surprising
that Python is widely used in the scientific community~\citep{Oli07}.
Large Python projects like SciPy~\citep{SciPy} and SAGE~\citep{SAGE}
strongly leverage a diverse set of Python packages to perform complex
numerical calculations.




\section{Background}
\label{sec:bg}

A variety of different strategies have been developed to facilitate the
formulation and solution of complex optimization models.  For restricted
problem domains, optimizers can be directly interfaced with application
modeling tools.  For example, modern spreadsheets like Excel integrate
optimizers that can be applied to linear programming and simple nonlinear
programming problems in a natural way.

Algebraic Modeling Languages (AMLs) are alternative approach that allows
applications to be interfaced with optimizers that can exploit problem
structure.  AMLs are high-level programming languages for describing
and solving mathematical problems, particularly optimization-related
problems~\citep{Kal04}.  AMLs like AIMMS~\citep{AIMMS},
AMPL~\citep{AMPL,FouGay03} and GAMS~\citep{GAMS} have programming
languages with an intuitive mathematical syntax that supports concepts
like sparse sets, indices, and algebraic expressions.  AMLs provide
a mechanism for defining variables and generating constraints with a
concise mathematical representation, which is essential for large-scale,
real-world problems that involve thousands of constraints and variables.

% TODO: cite mathprog and ZIMPL here?
% MathProg (GLPK)
% ZIMPL http://zimpl.zib.de/

Standard programming languages can also be used to formulate optimization
models when used  in conjunction with a software library that uses
object-oriented design to support mathematical concepts.
Although these modeling libraries sacrifice some of the intuitive
mathematical syntax of an AML, they allow the user to leverage the
greater flexibility of standard programming languages.  For example,
modeling tools like FlopC++~\citep{flopcpp}, OPL~\citep{OPL} and
OptimJ~\citep{OptimJ} can be used to formulate and solve optimization models.

%PuLP http://code.google.com/p/pulp-or/
%POAMS
%APLEpy http://sourceforge.net/projects/aplepy/  http://aplepy.sourceforge.net/  

A related strategy is to use a high-level programming language to
formulate optimization models that are solved with optimizers written in
low-level languages.  This two-language approach leverages the flexibility
of the high-level language for formulating optimization problems and
the efficiency of the low-level language for numerical computations.
This approach is increasingly common in scientific computing tools, and
the Matlab TOMLAB Optimization Environment~\citep{TOMLAB} is probably
the most mature optimization software using this approach.  However, 
Python has been used to implement a variety of optimization packages that use this approach:
\begin{itemize}

\item {\bf APLEpy:} A package that can be used to describe linear programming and mixed-integer linear programming optimization problems~\citep{APLEpy,KurGra07}. 

\item {\bf CVXOPT:} A package for convex optimization~\citep{CVXOPT}.

\item {\bf PuLP:} A package that can be used to describe linear programming and mixed-integer linear programming optimization problems~\citep{PuLP}. 

\item {\bf POAMS:} A modeling tool for linear and mixed-integer linear programs that defines Python objects for abstract sets, constraints, objectives, decision variables, and solver interfaces.  

\item {\bf OpenOpt:} A numerical optimization framework that is closely coupled with the SciPy scientific Python package~\citep{OpenOpt}.   

\item {\bf NLPy:} An optimization framework that leverages AMPL to create problem instances, which can then be processed in Python~\citep{NLPy}.
\end{itemize}

Pyomo is similar to APLEpy, PuLP and POAMS.  All of these packages
define Python objects that can be used to express models. POAMS and Pyomo support
a clear distinction between abstract models and problem
instances.  This design has several advantages, which were summarized by Fourer and Gay~\citep{FouGay03} when presenting AMPL:
\begin{itemize}

\item The statement of the symbolic model can be made compact and understandable,

\item The independent specification of a symbolic model facilitates the specification of the validity of the associated data,

\item Data from different sources can be used with the symbolic model, depending on the computing environment,
\end{itemize}

The main high-level feature that distinguishes Pyomo from POAMS is Pyomo's support for an
instance construction process that is automated by object properties.
This is akin to the capabilities of AML's like AMPL and GAMS, and it
provides a standardized technique for constructing model instances.
Hart~\citep{Har09a} provides Python examples that illustrate
the differences between PuLP, POAMS and Pyomo.


