1

OpenVSP API & MATLAB/Python Integration

Presented by:
Justin Gravett
[Link]@[Link]
Empirical Systems Aerospace, Inc. (ESAero)

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
 2

Agenda

• Introduction

• C++ API

• AngelScript API

• Python API

• MATLAB API Overview

• MATLAB API Build Instructions*

*Recommended: Building OpenVSP from Source Presentation

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
 3

Introduction

• API: Application Programming Interface

• Languages:
– C++
– AngelScript (close to C++)
– Python
– MATLAB (experimental)
• What is it used for?
– Headless operating systems
– Automation
– Integration with other codes
– Test suites
– Custom Geoms
• How to learn:
– Old way: study the source code
– Examples
– New: Doxygen documentation of functions and classes
– Workshop presentations
Empirical Systems Aerospace, Inc. [Link] NNX09CC86P
OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
 4

API Functions

• API Documentation: [Link]

– Available for direct download
• Analysis and Results Manager:
– Generic functions to setup analysis inputs, execute analyses, and collect results
– Strings used to identify available analysis types
• i.e. "VSPAEROComputeGeometry“
– Preferred approach for running analyses when available
– Use “ListAnalysis()” to identify available analysis strings
– Used “PrintAnalysisInputs( “analysis” ) to identify available inputs
– Arrays used for analysis input and result data
• Parms Through the API
– Generic functions for controlling Parms
– Values cast to double type in API
– Parms identified by ID or Container, Group,
and Name
• Identifying Parm Info:
– OpenVSP *.vsp3 file
– Click and drag GUI device to text editor
– Click on the GUI Parm button

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
 5

C++ API

• Basis for all other supported languages – OpenVSP’s

primary language is C++
• Functions written in VSP_Geom_API (geom_api
project)
• Exposes core functionality to higher level abstraction
• Used for API testing
– Test suites for Parasite Drag, Mass Properties, VSPAERO,
and more
• src -> geom_api folder of repository (apitest project)
• CFD Mesh test suite in progress
– Run prior to each release to help catch bugs
– Intended to be included with continuous integration builds, but
currently too time consuming

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
 6

AngelScript API

• Very similar to C++

– Must declare variable types
– “main” function required
• Same language used in Advanced Links and for
Custom Geom scripts
• *.vspscript file extension required
• C++ API functions, classes, and enums are
registered through AngelScript
• 30+ example scripts provided in scripts directory
– Demonstrate how to use various API functionality
– Examples of API automation
– Most advanced: Master_VSP_VV_Script.vspscript
• 2 ways to run *vspscript files:
1. OpenVSP GUI: File -> Run Script…
2. VSPSCRIPT executable:
• Run through command terminal
• Example: vspscript -script "scripts/[Link]"

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
 7

Python API

• SWIG: Simplified Wrapper and Interface Generator

– Wraps C++ API for Python
• Python version when importing OpenVSP API
must match version used by SWIG
– Python 3.6: latest version used with OpenVSP
distribution
– Must compile OpenVSP yourself if alternative Python
version is desired
• *Windows 3.21.2 initially released without Python
API – fixed and updated

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
 8

Python API

• Installation instructions available in python folder

of OpenVSP distribution – see README
– [Link]
/python_api/packages
– Open a command terminal in the same directory
– Recommended (Windows) – use the “dev” API
installation version
• Test installation
– Open command terminal and type:
– “python”
– “import openvsp as vsp”
– “[Link]()” or “[Link]()”
Empirical Systems Aerospace, Inc. [Link] NNX09CC86P
OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
 9

Python API – Common Errors

• DLL load error?

– Check your python version matches version compiled
with OpenVSP
• Missing VSPAERO solver, viewer, or slicer?
– Copy executables to Python directory

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
10

MATLAB API

• Advanced and experimental

– Not recommended for new API
users
– Requires existing software
development skills
• Requires unreleased version of
SWIG

ESAero Support
• Integrated MATLAB API with
PANTHER toolset in Phase I SBIR
• Minor modifications made to
OpenVSP – released publicly NASA SBIR PHASE I - UAM Disturbance
Rejection in Conceptual Design
– Duplicated test suite to verify
functionality
– Tried to keep the build process as
simple as possible

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
11

Software – Python API

Install Anaconda
• Anaconda Version Archive
– Version 5.2.0 – Includes
Python 3.6, compatible with
OpenVSP 3.21.2
• Latest Version
– Only use this version if
compiling OpenVSP
yourself
• Add to PATH
– Recommend through
installation option
– Could manually adding to
system PATH
Empirical Systems Aerospace, Inc. [Link] NNX09CC86P
OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
12

SWIG - Python

• Only needed if compiling OpenVSP

• SWIG – Simplified Wrapper and Interface
Generator
– Official distribution
– Used to provide python interface to C-API
– [Link]
– Recent CMake issue with OpenVSP finding 4.0.2
– could use 4.0.1 instead

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
13

SWIG - MATLAB

• SWIG - MATLAB
– Unofficial SWIG build with MATLAB bindings
– [Link]
• User must compile OpenVSP
• Git required
– Sourcetree recommended Git GUI
• MinGW, MSYS, & PCRE used

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
14

Build Process – Overview

1. Clone the swig-matlab repo & checkout matlab-customdoc

2. Compile swig-matlab from source and generate a [Link]

3. Create a 'matlab_api' (use the 'python_api' as a template)

4. Point the VSP CMAKE options to look for the [Link] that you just created

5. Compile OpenVSP (Build solution, Build INSTALL)

6. Delete duplicate SwigClear(self) function in SwigRef.m

7. Build some test scripts in MATLAB to verify everything is working

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
15

Build Process – Overview

1. Clone the swig-matlab repo & checkout matlab-customdoc

2. Compile swig-matlab from source and generate a [Link]

3. Create a 'matlab_api' (use the 'python_api' as a template)

4. Point the VSP CMAKE options to look for the [Link] that you just created

5. Compile OpenVSP (Build solution, Build INSTALL)

6. Delete duplicate SwigClear(self) function in SwigRef.m

7. Build some test scripts in MATLAB to verify everything is working

These are the most challenging steps

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
16

Build Process – 1
1. Clone the swig-matlab repo & checkout matlab-customdoc
2. Compile swig-matlab from source and generate a [Link]
3. Create a 'matlab_api' (use the 'python_api' as a template)
4. Point the VSP CMAKE options to look for the [Link] that you just created
5. Compile OpenVSP (Build solution, Build INSTALL)
6. Delete duplicate SwigClear(self) function in SwigRef.m
7. Build some test scripts in MATLAB to verify everything is working

SWIG-MATLAB
Origin: [Link]
Branch: matlab-customdoc
ESAero branch off of 0fc411742bdfb36c3180d5b671a1da92766af90e
Two commits cherry picked:
Use Latest Git SHA: 82ca29bc9889792856a5d98c5903fb168a5e42f7
Empirical Systems Aerospace, Inc. [Link] NNX09CC86P
OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
17

Build Process – 2
1. Clone the swig-matlab repo & checkout matlab-customdoc
2. Compile swig-matlab from source and generate a [Link]
3. Create a 'matlab_api' (use the 'python_api' as a template)
4. Point the VSP CMAKE options to look for the [Link] that you just created
5. Compile OpenVSP (Build solution, Build INSTALL)
6. Delete duplicate SwigClear(self) function in SwigRef.m
7. Build some test scripts in MATLAB to verify everything is working

Documentation in source repository:

Doc\Manual\[Link]

Instructions exist to build using

• MinGW & MSYS – ESAero Tested
• Cygwin
• VisualStudio IDE (challenging)

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
18

Build Process – 2
1. Clone the swig-matlab repo & checkout matlab-customdoc
2. Compile swig-matlab from source and generate a [Link]
3. Create a 'matlab_api' (use the 'python_api' as a template)
4. Point the VSP CMAKE options to look for the [Link] that you just created
5. Compile OpenVSP (Build solution, Build INSTALL)
6. Delete duplicate SwigClear(self) function in SwigRef.m
7. Build some test scripts in matlab to verify everything is working

Add MinGW and

MinGW Installation Packages MSYS to Path

• No need to install bison, automake, and autoconf separately (already included)

• PCRE ([Link]): [Link] or
[Link]
• Follow instructions to extract in Swig source repository and run “Tools/pcre-
[Link]”
Empirical Systems Aerospace, Inc. [Link] NNX09CC86P
OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
19

Build Process – 2
1. Clone the swig-matlab repo & checkout matlab-customdoc
2. Compile swig-matlab from source and generate a [Link]
3. Create a 'matlab_api' (use the 'python_api' as a template)
4. Point the VSP CMAKE options to look for the [Link] that you just created
5. Compile OpenVSP (Build solution, Build INSTALL)
6. Delete duplicate SwigClear(self) function in SwigRef.m
7. Build some test scripts in matlab to verify everything is working

Solution to error after calling “bash configure”:

1. Delete configure file
2. Rerun “bash [Link]”
3. Open configure – delete lines 5773 through 6027
Empirical Systems Aerospace, Inc. [Link] NNX09CC86P
OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
20

Build Process – 3
1. Clone the swig-matlab repo & checkout matlab-customdoc
2. Compile swig-matlab from source and generate a [Link]
3. Create a 'matlab_api' (use the 'python_api' as a template)
4. Point the VSP CMAKE options to look for the [Link] that you just created
5. Compile OpenVSP (Build solution, Build INSTALL)
6. Delete duplicate SwigClear(self) function in SwigRef.m
7. Build some test scripts in MATLAB to verify everything is working

Tells CMAKE where

the source code is for
the MATLAB API is

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
21

Build Process – 3
1. Clone the swig-matlab repo & checkout matlab-customdoc
2. Compile swig-matlab from source and generate a [Link]
3. Create a 'matlab_api' (use the 'python_api' as a template)
4. Point the VSP CMAKE options to look for the [Link] that you just created
5. Compile OpenVSP (Build solution, Build INSTALL)
6. Delete duplicate SwigClear(self) function in SwigRef.m
7. Build some test scripts in MATLAB to verify everything is working

Copy *.i files from python API example

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P
OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
22

Build Process – 3
1. Clone the swig-matlab repo & checkout matlab-customdoc
2. Compile swig-matlab from source and generate a [Link]
3. Create a 'matlab_api' (use the 'python_api' as a template)
4. Point the VSP CMAKE options to look for the [Link] that you just created
5. Compile OpenVSP (Build solution, Build INSTALL)
6. Delete duplicate SwigClear(self) function in SwigRef.m
7. Build some test scripts in MATLAB to verify everything is working

Key changes to VSP source

• Explicit control of VSPAERO path
• Reference to Matrix.h

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
23

Build Process – 4
1. Clone the swig-matlab repo & checkout matlab-customdoc
2. Compile swig-matlab from source and generate a [Link]
3. Create a 'matlab_api' (use the 'python_api' as a template)
4. Point the VSP CMAKE options to look for the [Link] that you just created
5. Compile OpenVSP (Build solution, Build INSTALL)
6. Delete duplicate SwigClear(self) function in SwigRef.m
7. Build some test scripts in MATLAB to verify everything is working

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
24

Build Process – 4
1. Clone the swig-matlab repo & checkout matlab-customdoc
2. Compile swig-matlab from source and generate a [Link]
3. Create a 'matlab_api' (use the 'python_api' as a template)
4. Point the VSP CMAKE options to look for the [Link] that you just created
5. Compile OpenVSP (Build solution, Build INSTALL)
6. Delete duplicate SwigClear(self) function in SwigRef.m
7. Build some test scripts in matlab to verify everything is working
If you are successful….

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
25

Build Process – 5
1. Clone the swig-matlab repo & checkout matlab-customdoc
2. Compile swig-matlab from source and generate a [Link]
3. Create a 'matlab_api' (use the 'python_api' as a template)
4. Point the VSP CMAKE options to look for the [Link] that you just created
5. Compile OpenVSP (Build solution, Build INSTALL)
6. Delete duplicate SwigClear(self) function in SwigRef.m
7. Build some test scripts in matlab to verify everything is working

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
26

Build Process – 6
1. Clone the swig-matlab repo & checkout matlab-customdoc
2. Compile swig-matlab from source and generate a [Link]
3. Create a 'matlab_api' (use the 'python_api' as a template)
4. Point the VSP CMAKE options to look for the [Link] that you just created
5. Compile OpenVSP (Build solution, Build INSTALL)
6. Delete duplicate SwigClear(self) function in SwigRef.m
7. Build some test scripts in matlab to verify everything is working

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
27

Build Process – 7
1. Clone the swig-matlab repo & checkout matlab-customdoc
2. Compile swig-matlab from source and generate a [Link]
3. Create a 'matlab_api' (use the 'python_api' as a template)
4. Point the VSP CMAKE options to look for the [Link] that you just created
5. Compile OpenVSP (Build solution, Build INSTALL)
6. Delete duplicate SwigClear(self) function in SwigRef.m
7. Build some test scripts in matlab to verify everything is working
APITestMain.m APITestSuiteTest.m

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th
28

Questions?

Empirical Systems Aerospace, Inc. [Link] NNX09CC86P

OpenVSP
SBIR Review,
Workshop
Presented
2020to
Sept.
NASA, – Sept.
15thJuly 7th, 2009
17th