Installation Instructions

Conda

Conda packages are available on conda-forge and can be installed via

conda install -c conda-forge pyoptsparse

This would install pyOptSparse with the built-in optimizers, as well as IPOPT. If you wish to use optimizers not packaged by conda, e.g. SNOPT, then you must either build the package from source or use the installation script below. If you have the SNOPT precompiled library available, it is possible to dynamically link it to pyOptSparse following the instructions on the SNOPT installation page.

Using an installation script

You can build and install pyOptsparse using a Python script developed by the OpenMDAO team. For usage, see the instruction on the README of the repo.

This script is particularly useful for installing IPOPT and its dependencies. It can also support SNOPT installation if you have access to the SNOPT source code.

Building from source

Requirements

pyOptSparse has the following dependencies:

  • Python 3.7 or 3.8, though other Python 3 versions will likely work

  • C and Fortran compilers. We recommend gcc and gfortran which can be installed via the package manager for your operating system.

Please make sure these are installed and available for use. In order to use NSGA2, SWIG (v1.3+) is also required, which can be installed via the package manager. Python dependencies are automatically handled by pip, so they do not need to be installed separately.

Note

  • In Linux, the python header files (python-dev) are also required.

  • We do not support operating systems other than Linux. For macOS users, the conda package may work out of the box if you do not need any non-default optimizers. Also, the installation script by OpenMDAO likely works on macOS. For Windows users, a conda package is on the way, if it’s not already in the repos. This comes with the same disclaimer as the macOS conda package. Alternatively, follow the conda build instructions below as this will work on any platform.

Installation

The easiest and recommended way to install pyOptSparse is with pip. First clone the repository into a location which is not on the $PYTHONPATH, for example $HOME/packages/. Then in the root pyoptsparse folder type

pip install .

For those not using virtual environments, a user install may be needed

pip install . --user

If you plan to modify pyOptSparse, installing with the developer option, i.e. with -e, will save you from re-installing each time you modify the Python code.

Note

Some optimizers are proprietary, and their sources are not distributed with pyOptSparse. To use them, please follow the instructions on specific optimizer pages.

Specifying compilers

To specify a non-default compiler (e.g. something other than /usr/bin/gcc), meson recognizes certain special environment variables. For example, to specify the Intel compilers, simply run

FC=$(which ifort) CC=$(which icc) pip install .

Installing OptView

OptView and OptView-Dash have separate dependencies that must be installed. To install pyOptSparse including those dependencies, run

pip install .[optview]

Testing

pyOptSparse provides a set of unit and regression tests to verify the installation. To run these tests, first install testflo which is a testing framework developed by the OpenMDAO team:

pip install testflo

Then, in the project root directory, type:

testflo . -v

to run all tests.

If there are failed tests, or tests were skipped involving optimizers that should be installed, then refer to the debugging section below.

Debugging Installation Problems

You may encounter issues such as

There was an error importing the compiled slsqp module

The first thing to do is to do a clean install. This involves the following steps:

  1. Uninstall the package via pip

  2. If you did a developer install (with -e), check if there are .so files in the subdirectories, e.g. pyoptsparse/pySLSQP. If so, manually delete all .so files.

  3. Remove the meson_build directory if present.

  4. Run pip install again and test the installation.

If the issue persists, there is probably a linking or runtime issue. This can be verified by manually importing the compiled library that’s causing the issue, for example with:

from pyoptsparse.pySLSQP import slsqp

If this throws a missing symbol error, then there is likely a linking issue at compile time. If, on the other hand, this throws a error while loading shared libraries, then it’s probably a runtime issue with a shared library. Check to make sure that the $LD_LIBRARY_PATH is set correctly, for example when running IPOPT.

Update or Uninstall

To update pyOptSparse, first delete the meson_build directory, then update the package using git. For stability, users are encouraged to stick to tagged releases. Install the package normally via pip.

To uninstall the package, type

pip uninstall pyoptsparse

Conda Build Instructions

The following instructions explain how to build and install pyOptSparse in a conda environment. This has the advantage that conda can be used to install all the necessary dependencies in an isolated and reproducible environment. Considering how finicky Windows can be with ABI compatibility among various compilers, this is the recommended approach. The guide will work on any platform, however.

The only build requirement for the build is a working conda installation as all compilers and dependencies are pulled from the conda-forge repos, with the exception of a Windows build, which requires Visual Studio 2017 C++ Build Tools.

First, we need to create the conda environment. An environment.yml file is provided in the pyoptsparse repo:

conda create -y -n pyos-build
conda activate pyos-build
conda config --env --add channels conda-forge
conda config --env --set channel_priority strict

conda env update -f .github/environment.yml

Next, we need to tell the compiler where to find IPOPT:

export IPOPT_DIR="$CONDA_PREFIX"

Finally, build the wheel and install it using pip:

# build wheel
python -m build -n -x .

# install wheel
pip install --no-deps --no-index --find-links dist pyoptsparse