INSTALLATION.md

AeroSandbox Installation

In short:

• pip install aerosandbox[full] for a complete install.

• pip install aerosandbox for a lighter-weight installation. All optimization, numerics, and physics models are included, along with 2D plotting via matplotlib; optional dependencies for 3D visualization, CAD export, and geometry manipulation (e.g., plotly, pyvista, trimesh, cadquery) are skipped.

More detail:

1. First, install Python via the Anaconda distribution, available here. During the installation, it is recommended that you add Python to your PATH ("What does this mean?"), which can be conveniently done by checking a checkbox.

   • The minimum-required Python version is given by the requires-python line in pyproject.toml. At the time of writing, the minimum required Python version is 3.10.

2. Verify that your installation has completed correctly by opening up a Terminal (Command Prompt on Windows) and executing the following commands. You should see something similar to the below:

   Windows:

   C:\Users\peter>where python
   C:\ProgramData\Anaconda3\python.exe
   
   C:\Users\peter>where pip
   C:\ProgramData\Anaconda3\Scripts\pip.exe

   Mac/Linux:

   (base) peter@Peter-PC:/mnt/c/Users/peter$ which python
   /home/peter/anaconda3/bin/python
   
   (base) peter@Peter-PC:/mnt/c/Users/peter$ which pip
   /home/peter/anaconda3/bin/pip

   Basically, we're checking that the aliases python and pip both:

   1. refer to essentially the same folder, and

   2. that folder is our recently-installed Anaconda distribution.

   For reference, pip is Python's built-in package manager, which lets you easily use others' open-source code (such as AeroSandbox) in your own projects.

3. (Optional) Install a Python IDE, if desired. I like using PyCharm, which offers a feature-rich "Community Edition" for free, or an even-better "Professional Edition" which is free for students, open-source developers, and many other groups. Another popular choice is Visual Studio Code, which is also free.

4. Install AeroSandbox by typing the following into your terminal:

   pip install aerosandbox[full]

   If all goes well, you should see a bunch of output as it first downloads & installs dependencies, then downloads & installs the latest version of AeroSandbox.

5. Congrats! You've installed Anaconda Python and AeroSandbox. If desired, you can test your install by following steps in the "Testing" section of this document, but it's not necessary.

   To start learning how to use AeroSandbox on your problems, we recommend you check out the tutorials folder here.

Testing

If desired, you can test that AeroSandbox functions properly on your system by:

1. Installing with the [test] flag, so:

   pip install aerosandbox[full,test] 

   for a new install, or, if you already have an existing installation:

   pip install --upgrade aerosandbox[full,test]

2. Then, as shown below: open up a terminal, launch into Python, and execute these commands:

C:\Users\peter>python
Python 3.9.7 (default, Sep 16 2021, 16:59:28) [MSC v.1916 64 bit (AMD64)] :: Anaconda, Inc. on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import aerosandbox as asb
>>> asb.run_tests()

A bunch of tests should run, hopefully terminating with a message like:

====================== 214 passed, 47 warnings in 17.89s =======================

If you get any failing tests, that is considered a bug, and we hope you'll report it to us by creating an issue ticket.

Troubleshooting

Permissions Errors

If you get any permissions issues, try the following:

1. Windows: Run Command Prompt as Administrator and try again. If that still doesn't work, try also adding the --user flag to the installation command, so:

   pip install --user aerosandbox[full] 

2. Mac/Linux: Do not use sudo with pip - modern Linux distributions block installs into the system Python (PEP 668), and it can break system packages. Instead, install into a virtual environment:

   python -m venv venv
   source venv/bin/activate
   pip install "aerosandbox[full]"

   Or, install into your user site-packages by adding the --user flag:

   pip install --user "aerosandbox[full]"

SSL Certificate Errors

If you get any SSL certificate errors (sometimes seen with VPN connections on very-restricted corporate networks):

Execute the following commands in your terminal:

>>> conda activate base
>>> pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org aerosandbox[full]

The first command explicitly puts you into a Conda environment called "base", which is the default environment - basically, this will ensure that whatever you install is accessible anytime you use Python on your system.

The second command is our standard install command, except the --trusted-host additions tell pip to ignore any SSL certificate errors.

(Advanced users: if this is a recurring annoyance on your network, consider editing pip.conf and adding these targets to trusted-host under the global parameter.)

Other Problems

For all other issues, start a discussion on the Discussions page.