Installation#
Quick start installation#
Note
If you do not already have Python installed, we recommend installing condaforge. The minimum supported version of Python is 3.9; we recommend using the latest release of Python.
The simplest way to install Aviary to use pip in a terminal:
pip install om-aviary
This will install the latest release of Aviary and all of its dependencies.
That’s it! If you’ve done that successfully, you can now use Aviary in your Python environment.
More in-depth installation instructions#
If you want to instead clone the Aviary repository and install from source (this is useful if you modify any of Aviary’s internal code), follow the instructions below.
Once you have cloned the Aviary repo, change directories into the top-level Aviary folder (not within the aviary
folder) and run the following command:
pip install .
If you also want to install all packages used for the Aviary tests and external subsystem examples, you can instead run:
pip install .[all]
If you are a developer and plan to modify parts of the Aviary code, install in an “editable mode” with pip
:
pip install -e .
This installs the package in the current environment such that changes to the Python code don’t require re-installation.
This command should be performed while in the folder containing setup.py
.
Note
You can do this editable installation with any of the [test]
or [all]
options as well.
Note
You can install the optional package pyOptSparse by following the instructions here. If you do not need the SNOPT optimizer, installing pyOptSparse is as simple as running conda install -c conda-forge pyoptsparse
. This will install pyOptSparse as well as the IPOPT optimizer.
Installation Troubleshooting#
Note
If you encounter issues during pip installation, you may need run pip install packaging
before you can pip install Aviary.
Installation on Linux for Developers#
As an example, let us do a step-by-step installation from scratch on your Linux operating system. We assume that you have Anaconda and your new environment will be built on top of it. In this section, we assume you are a developer and hence you will need developer’s versions of OpenMDAO and Dymos. As a result, you will need Git. We also assume that you have a bash shell.
We will be installing some Python packages from source in this part of the docs. Depending on the system you’re installing on, the OpenMDAO repositories might require a password-protected SSH key. This means that users need to generate a new SSH key and add it to the ssh-agent and then add the new SSH key to your GitHub account. We assume you already have access to the OpenMDAO repos as shown below or that you’ve already added an SSH key.
Preparing your Anaconda Environment#
On the Linux system, log in to your account and create your working directory.
For this doc we will use workspace
:
$ mkdir ~/workspace
Then cd
to this newly created directory. Please note that ~/workspace
is just an example. In fact, you can install Aviary wherever you want on your system. Save the following as a file named aviary-linux-dev-modified.yml
to this directory:
name: av1
channels:
- defaults
dependencies:
- python=3
- numpy=1
- scipy=1
- matplotlib
- pandas
- jupyter
- pip
- pip:
- parameterized
- testflo
- jupyter-book
- mdolab-baseclasses
- sqlitedict
- f90nml
- bokeh
In this file, the name
can be anything you like. The version of python is not limited to 3.9, but we recommend that you stay with this version because it is the version that we use to fully test Aviary and that it is required for some packages later on. For example, if you are going to add OpenVSP
to your environment, you will find that you need this version.
In the list, we see the popular Python packages for scientific computations: numpy
, scipy
, matplotlib
and pandas
. Aviary follows a standard source code formatting convention. autopep8
provides an easy way to check your source code for this purpose. jupyter
and jupyter-book
are used to create Aviary manual. parameterized
and testflo
are for Aviary testing. Aviary uses a lot of packages developed by MDOLab. So, we want to include its base classes. OpenMDAO records data in SQLite database and that is what sqlitedict
comes for. f90nml
is A Python module and command line tool for parsing Fortran namelist files. bokeh
is an interactive visualization library for modern web browsers. It is needed to generate Aviary output (traj_results_report.html).
Since we are going to depend on OpenMDAO
and dymos
, we could have included them in the pip
list. We leave them out because we will install the developer version later. In this way, we will get the latest working copies that Aviary depends on. But we do not intend to make changes to them.
pre-commit and autopep8 formatter are additionally required for developers who wish to contribute to the Aviary repository. Read our coding standards for more information.
Now, run create your new conda environment using this .yml
file:
$ conda env create -n av1 --file aviary-linux-dev-modified.yml
Suppose everything runs smoothly. You have a new conda environment av1
. You can start your conda environment:
$ conda activate av1
Installing Additional Dependencies#
Aviary can run in MPI.
You do not need the mpi4py
or petsc4py
packages to use Aviary.
They are useful when running large OpenMDAO models in parallel.
If needed, you can install them with the following command:
$ conda install -c conda-forge mpi4py petsc4py
Download developer version of OpenMDAO
:
$ cd ~/workspace
$ git clone git@github.com:OpenMDAO/OpenMDAO.git
You have a new subdirectory workspace/OpenMDAO
. You are not expected to modify source code of OpenMDAO, but you want to keep up with the latests version of it. The best way to do is to install OpenMDAO in developer mode. This removes the need to reinstall OpenMDAO after changes are made. Go to this directory where you see a file setup.py
. Run
$ cd OpenMDAO
$ pip install -e .
You should see something like the following:
Successfully installed networkx-3.1 openmdao-3.29.1.dev0
Now, let us install dymos
in a similar way:
$ cd ~/workspace/
$ git clone git@github.com:OpenMDAO/dymos.git
$ cd dymos
$ pip install -e .
You should see something like the following:
Successfully installed dymos-1.9.2.dev0
Installing pyOptSparse#
Next, we will install pyoptsparse
.
If you want to easily install and use pyOptSparse, follow the installation instructions on the pyOptSparse docs.
Specifically, if you do not need the SNOPT optimizer and want to run Aviary with IPOPT, you can install pyOptSparse using the following command:
conda install -c conda-forge pyoptsparse
The OpenMDAO team provides a build_pyoptsparse
package to help users install MDO Lab’s pyOptSparse, optionally including the SNOPT
and IPOPT
optimizers.
This process depends on certain libraries.
One of them is the Lapack Fortran library.
If you don’t have Lapack
, you can either build it from source or try one of the prebuilt binaries.
We are assuming you have Lapack installed correctly.
Now do the following:
$ cd ~/workspace/
$ git clone git@github.com:OpenMDAO/build_pyoptsparse.git
$ python -m pip install ./build_pyoptsparse
Note
SNOPT
is a commercial optimizer that is free for academic use and available for purchase for commercial use. Users must obtain it themselves.
Assuming you have the SNOPT
source code already, copy it to the workspace
directory.
Run:
$ build_pyoptsparse -d -s ~/workspace/SNOPT_Source/
Note that you should provide the absolute – not relative – path to your SNOPT source files. If successful, you should get the following:
---------------------- The pyOptSparse build is complete ----------------------
NOTE: Set the following environment variable before using this installation:
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib
Otherwise, you may encounter errors such as:
"pyOptSparse Error: There was an error importing the compiled IPOPT module"
----------------------------------- SUCCESS! ----------------------------------
So, let us add this environment variable to your bash shell:
$ export LD_LIBRARY_PATH=$CONDA_PREFIX/lib
If you don’t have the Lapack package and you don’t plan to build it by yourself, you can build pyOptSparse
with SNOPT
by adding an option --no-ipopt
to your build_pyoptsparse
command.
Alternatively, if build_pyoptsparse
fails again and you have SNOPT
source code, you still can build pyOptSparse
with SNOPT
by directly building pyOptSparse.
First, clone the pyOptSparse
repository:
$ cd ~/workspace/
$ git clone https://github.com/mdolab/pyoptsparse
You will see a pySNOPT
subdirectory in it. Go to your SNOPT
source folder and copy all Fortran source code files into this directory:
$ cp -a * ~/workspace/pyoptsparse/pyoptsparse/pySNOPT/source/
You are ready to install pyoptsparse
(with SNOPT
):
$ cd ~/workspace/pyoptsparse/
$ pip install -e .
You should see something like the following:
Successfully built pyoptsparse
Installing collected packages: pyoptsparse
Successfully installed pyoptsparse-2.10.1
Installing Aviary and Running Tests#
Now, we are ready to install Aviary. Assuming that you will become a contributor sooner or later, we want to install a copy from the main source. (You will need a GitHub account for this) Let us open https://github.com/openMDAO/om-aviary/
in a web browser and click fork on the top-right corner. You then have created your own copy of Aviary on GitHub website. Now we create a copy on your local drive (supposing USER_ID
is your GitHub account ID):
$ cd ~/workspace
$ git clone git@github.com:USER_ID/Aviary.git
$ cd Aviary
$ pip install -e .
When it is done, let us run test:
$ testflo .
If you run into an MPI error, you can add --nompi
option to testflo
command run. If everything runs, you will get something like the following:
Passed: 1065
Failed: 0
Skipped: 3
Ran 1065 tests using 1 processes
Wall clock time: 00:02:47.31
To find which tests are skipped, we can add --show_skipped
option:
The following tests were skipped:
test_conventional_problem.py:TestConventionalProblem.test_conventional_problem_ipopt
test_conventional_problem.py:TestConventionalProblem.test_conventional_problem_snopt
test_cruise.py:TestCruise.test_cruise_result
Actually, those three tests were skipped on purpose. Depending on what optimizers are installed, the number of skipped tests may be different. Your installation is successful.
To see the test name before each unit test and push all outputs to standard outputs:
$ testflo -s --pre_announce .
Run testflo --help
to see other options. For example, we have a set of longer tests (called bench tests) that perform full trajectory optimizations. To run all the bench tests, you can run this:
$ cd ~/Aviary/aviary
$ python run_all_benchmarks.py
If you want to test a particular case (e.g. test_simplified_takeoff.py
):
$ testflo test_simplified_takeoff.py