Skip to content

Instantly share code, notes, and snippets.

@HB-Stratos
Last active January 24, 2025 22:36
Show Gist options
  • Save HB-Stratos/afede7c04ddc5bf4f3f0f9f6dd8f5e4d to your computer and use it in GitHub Desktop.
Save HB-Stratos/afede7c04ddc5bf4f3f0f9f6dd8f5e4d to your computer and use it in GitHub Desktop.
How to use the OpenVSP Python API

WRITING STATUS: Unfinished

How to use the OpenVSP Python API (Unofficial Beginners Guide)

This guide will attempt to teach you how to set up the OpenVSP Python API for automated airplane analysis from zero to extracting the VSPAERO solver data into python data structures. This is not a comprehensive guide of the API as there are several areas of it that I have not touched yet and therefore can't teach.

This guide also assumes you have some base knowledge of how to use OpenVSP through the GUI. Should you not have this knowledge yet, the OpenVSP Ground School is one of the best tutorial series for a program I have ever come across. You can find it here

Note

This guide was not written by an expert, just your everyday end user who learnt the API in a week for a university project. Do take everything said here with a grain of salt, though I do hope the content is useful. Thank you to Rob McDonald on the Google Group for answering my many questions while learning.

Note

A lot of this guide is most likely also applicable to the C++ and AngelScript APIs as their usage is very similar.

RTFM: Where to find the documentation, code examples, and more

Almost every function in the OpenVSP API is documented, though unfortunately their combined usage to achieve a goal is not. Regardless, the documentation still often proves to be a useful tool.

Beyond this, you can often find some smaller code snippets and answers by searching the google group. You can also ask for help there: https://groups.google.com/g/openvsp

OpenVSP also comes with various script examples written in AngelScript, but transfer almost exactly to python: https://github.com/OpenVSP/OpenVSP/tree/main/examples/scripts

Software Setup

The README in the python folder of your OpenVSP distribution describes the basic software setup. This presentation from the 2020 OpenVSP workshop also does a good job of explaining how to set up the Python and Matlab APIs, should you need more details.

Important

The Python version you will develop your tooling with must match the python version OpenVSP was compiled for. At time of writing, OpenVSP ships precompiled for either Python 3.9 or 3.11, make sure to download the correct one.

Should you need a Python version other than those offered, you will have to compile OpenVSP from scratch. The 2020 Workshop also has a guide for that, here

Prerequisites

  1. You must have either Anaconda, Miniconda or another compatible conda installed. You can find both Anaconda and Miniconda here. At time of writing, OpenVSP 3.41.2 worked flawlessly with the latest available Anaconda version, 24.11.3.

Note

Conda is package management tool for Python and more, developed by the scientific Python community. You can read more about the reasons for conda and the differences here

Miniconda is just that, the package management tool with nothing else

Anaconda is Miniconda, but also adds a large amount of scientific python packages into every created environment. It also comes with code editors and other software tools, the usefullness of which only you can judge.

  1. You must have OpenVSP downloaded somewhere on your computer. This does not need to be in your Python developement environment. You can find the latest downloads here, and should you need an older version, those are found here
  2. You need a code editor of your choice. I used Pycharm Community, which is available for free here (scroll down). The guide will focus on developing with Pycharm, however most things should be easily transferrable to e.g. VS Code.

Tip

If this is your first time with Pycharm, consider looking at these useful plugins:

HighlightBracketPair, Rainbow Brackets Lite, Indent Rainbow, Mypy, Pylint

Conda Environment Setup

This section follows the README in the python folder of the OpenVSP distribution. The instructions here may be out of date, said README is where you can find up-to-date information.

Note

OpenVSP comes with API installation scripts for Linux, Mac and Windows. However, on my machine PowerShell scripts are disabled by default, so I ran the commands manually.

  1. Find a terminal in which you can access Conda. If you added Conda to your global PATHon Windows or otherwise made it globally available in terminals, this will be any terminal you can find. I often used the terminal integrated with Pycharm. If you do not wish to make Conda globally available, it also installs a program called [Ana/Mini]conda Prompt with the installation, in which you can interact with Conda. To confirm you can access Conda, just type conda into your terminal and see if it responds with a help message.
  2. Navigate to <Your OpenVSP Installation Path>/OpenVSP-<Version>-<OS>/pythonwith your terminal. In case you're not familiar with a terminal, cd is the command you are looking for. This guide assumes some familiarity with the terminal from here on out, but you will be able to find your way around using a search engine of your choice.
  3. Run conda env create -f .\environment.yml. This will create a Conda environment as specified in the environment.yml file.
  4. Run conda activate vsppytools. This will activate the environment you just created. You should see (vsppytools) appear at the start of your terminal prompt.
  5. Run pip install -r requirements-dev.txt. This will set up all the python packages included with OpenVSP. As pip installs, you will see some depeciation warnings. At time of writing, these could be safely ignored and everything worked as expected.

Note

pip itself may not work in your conda terminal. If it is broken, you can work around it by using pyton -m pip ...

You now have a Conda environment set up which contains the various OpenVSP python modules you will use.

Note

You now have one Conda environment. If you're familiar with pip, you can treat this like one venv. This means any packages you install will be shared between every user of this environment.

I recommend you create a new Conda environment for each Python project in which you interact with the API. You can do this by changing the name in the environment.ymland setup.ps1 files.

Pycharm Setup

Setting Pycharm is quite straightforward. Simply click on your currently selected interpreter (this may be <no interpreter>) on the bottom right corner, then select Add New Interpreter -> Add Local Interpreter -> Conda Environment -> Use existing environment -> Select your environment, vsppytools is the default.

Using the API

We will be building a small script that creates a simple aircraft model from scratch and analyzes it. Code snippets will be provided along the way. The full script is included below.

Finding Example Code

You can look at https://github.com/OpenVSP/OpenVSP/tree/main/examples/scripts. These scripts are written in AngelScript, however as the API usage matches almost exactly they can be transferred to Python by merely adding a vsp. before every API function call.

Config Options

import openvsp_config

openvsp_config.LOAD_GRAPHICS = False
openvsp_config.LOAD_FACADE = False

import openvsp as vsp

You can use openvsp_config to set config options. These must be set before you import openvsp. LOAD_GRAPHICS is relatively self-explanatory. It loads the OpenVSP UI so you can see what is going on. In this case we do not need them, so it are disabled. Should you want to use the GUI, you also need to call vsp.InitGUI() follwed by vsp.StartGUI().

LOAD_FACADE controls whether or not to use the interface layer. If enabled OpenVSP will be spawned separately and communicate with python via a network layer, which we do not need in this case.

Creating an Aircraft

Important

Everything you do while interacting with the API is global. OpenVSP keeps state on C++ side and you interact with it similarly to interacting with it through the UI. This also means you can not have two different aircrafts loaded at the same time.

Very recently, OpenVSP introduced MULTI_FACADE, which allows you to interact with multiple backend C++ instances, allowing you to have multiple separate instances of global state. I have not yet had the time to explore this.

Note

According to Rob McDonald, the OpenVSP API was not originally designed with the usecase of creating an entire aircraft from scratch exclusively in code. It is in fact often easier to create an aircraft in the GUI, then load the vsp3 file from the API and only make the modifications you wish to make in an automated manner. However, creating an aircraft entirely in code also has its advantages, such as being entirely deterministic and reproducible without having to distribute a vsp3 file alongside your code.

Regardless, we will be creating a full aircraft from scratch to show off the process used.

Following the above, let's now create a simple wing.

import openvsp as vsp
from pathlib import Path

vsp.VSPCheckSetup()  # Verify everything is working as expected
vsp.VSPRenew()  # Clear all global state

output_path = Path.cwd() / "vsp_output"  # Define an output path for VSP
output_path.mkdir(parents=True, exist_ok=True)  # Create the output folder if it doesn't already exist
output_file = output_path / "tutorial_aircraft.vsp3"

wing_id = vsp.AddGeom("WING")  # Create a default wing geometry
vsp.SetGeomName(wing_id, "TutorialWing")

vsp.WriteVSPFile(output_file.as_posix())  # For now write this to file so we can inspect it.

vsp.AddGeom() is used to add new geometries. You can find the full list of Geometries you can add by opening OpenVSP normally and looking at the dropdown in the GeomBrowser.

grafik

Note

Looking at the UI to understand how things are done, then transferring them to code will be a recurring theme. As the API and GUI usage are very similar, this often proves useful.

Do also note that we save the output of AddGeom into wing_id. AddGeom returns a unique identifier string for the geometry you have just added. In my case, this was 'NWRFIVLBJF', though it will be different every time you run the code. These identifiers are a common theme when interacting with the API and are often a required input for functions interacting with the object you're dealing with.

On the other hand, WriteVSPFile does not take any identifiers, a good illustration of the fact that you are dealing with global state as if you were using the GUI.

Looking at the file we have saved, we see it indeed contains a default Wing, named TutorialWing. Success!

grafik

Now let's say we want to change the root chord of this wing. To do that we need to know which parameter we need to modify. In the GUI, we open the geometry editor for our TutorialWing, switch to section settings and find that the slider next to Root C of wing section 1 modifies the parameter we would like to modify. Therefore we click on Root C, and a Param window opens with all the details we need to know.

grafik

We can see that the parameter name we need to modify is Root_Chord under XSec_1. Therefore we add to our script:

vsp.SetGeomName(wing_id, "TutorialWing")

vsp.SetParmVal(wing_id, "Root_Chord", "XSec_1", 1)

vsp.WriteVSPFile(output_file.as_posix())
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment