June 29, 2015: A new tutorial is under construction and will be updated to include the operation with OpenVSP 3.x.x. A tutorial video introducing the use of VSPAERO through the OpenVSP GUI can be found in this VSPAERO Tutorial video. Information related to the older VSPAERO v.1.0 is displayed below the heading “VSPAERO 1.X”.
VSPAERO is a fast, linear, vortex lattice solver which integrates actuator disks that can be accurately and easily described for aero-propulsive analysis. Discrete vortices are applied to each panel generated in the OpenVSP degenerate geometry file and then evaluated over the entire surface to obtain a pressure distribution, and thus force. This information can be used to find lift, drag, slip, and (x,y,z) forces and moments. The flow over a section of panels behind a propeller can be analyzed by implementing actuator disks into the solver, which modifies the local freestream to account for increased speed and vorticity induced by the propeller. The actuator disks may be left inactive (empty) if the freestream/glide condition is to be analyzed. VSPAERO also has the ability to calculate the skin friction drag of each component in a model by applying a simple flat-plate drag model to each panel.
VSPAERO also comes with an attached Viewer application which displays wakes and Delta-CP gradients (pressure coefficient change). This application is particularly useful in locating problem areas in a model or visualizing trailing vortex formation - see below. Some theory behind the Vortex Lattice Method (VLM) can be found here.
VSPAERO was developed by David Kinney, Ph.D. at NASA Ames Research Center.
Once you have an appropriately defined model that you would like to analyze (see Modeling for VSPAERO), you will need to generate a degenerate geometry file, generate a setup file, and define any additional parameters to be considered. The process begins with DegenGeom.
Degenerate geometry files are representations of three dimensional models in progressively simple frames. For example, a three dimensional model is represented in its entirety, followed by a flat-plate representation, followed by a stick representation. More detail on degenerate geometry can be found here in the 2013 OpenVSP workshop presentation by Rob McDonald of CalPoly. These files can be used in several different physical applications such as Euler-Bernoulli beam theory and vortex lattice solvers.
It is important to note that DegenGeom will write ALL of the components in a model unless you specify a geometry set! The degenerate geometry files for your selected set of components are written from OpenVSP either by choosing
DegenGeom under the
Analysis menu or by opening the
VSPAERO GUI and clicking
Generate Geometry. This will write a comma separated value (.CSV) file and a MATLAB (.M) file. VSPAERO is primarily concerned with the CSV file. If you choose, you can open these files in a code viewer (in the case of the CSV you may use Excel or similar) and see all of the points that describe a component. A free, open-source code editor that is commonly used is Notepad ++.
You MUST have a DegenGeom file written to perform this step in OpenVSP!
Now that your model has an associated DegenGeom file, you can begin writing your setup file. VSPAERO recognizes this file by the name
modelname_DegenGeom.vspaero. This can be done several ways, some of which are faster and more accurate than others. The Setup file must be in the same directory as the DegenGeom file for VSPAERO to successfully launch. Note that the following descriptions use the VSP coordinate system.
If you are using VSPAERO from the Command Prompt window, you are able to write some of the setup information into a file associated with your model. This process is covered in the VSPAERO from Command Prompt Window section.
You may also manually write the inputs by using your favorite text editor. This is useful if you already have a .vspaero file with the desired inputs and simply wish to paste the information to a new file. Be aware that the extension MUST be
.vspaero! In Notepad, for example, you must choose “all file types” and type the extension after the file name for the file to save correctly. This method is also important if you are unable to use the VSPAERO GUI in OpenVSP for any reason. Shown below is an example of a Setup file. Feel free to copy this template into your own setup file as a guide. The descriptions shown in parentheses should be removed prior to running the solver.
Sref = 143.903061 (The wing planform reference area in square feet) Cref = 3.918 (The mean geometric chord of the wing in feet) Bref = 38.300000 (The projected span of the wing in feet) X_cg = 10.183607 (The vehicle CG X distance in feet from the origin) Y_cg = 0.000081 (The vehicle CG Y distance in feet from the origin) Z_cg = -0.036126 (The vehicle CG Z distance in feet from the origin) Mach = 0.27992 (Mach number) AoA = 0.23023 (Angle of attack or alpha in degrees) Beta = 0.000000 (Side-slip angle in degrees) Vinf = 303.8058 (Freestream velocity in ft/sec) Rho = 0.00186846 (Air density at the desired altitude in slug per cubic feet) ReCref = 6.220E+06 (Reynolds number based on altitude, speed, and Cref) ClMax = -1.000000 (Max sectional lift coefficient limit, -1 = No Limit) Symmetry = no (Defines a plane of symmetry. No=no symmetry. Y=symmetric across XZ plane. X=symmetric across YZ plane. Z=symmetric across XY plane.) FarDist = -1.000000 (Distance where wakes return to freestream, -1 = VSPAERO computes the distance) NumWakeNodes = 0 (Defines the number of wake nodes. 0=free.) WakeIters = 5 (Number of iterations to compute in the solver) NumberOfRotors= 1 (Defines the number of actuator discs in the model) PropElement_1 (Name of disc element) 1 (Disc ID) 1.15 0 0 (Disc center location in X Y Z) 1.00 0.00 0.00 (Disc unit normal vector in X Y Z) 3.25 (Disc radius in feet) 0.5 (Disc hub radius in feet) -2600 (Disc RPM. Positive indicates counter-clockwise as viewed from the pilot.) 0.057797173 (Thrust coefficient) 0.07248844 (Power coefficient)
Another way of generating a Setup file for your model is to use the VSAPERO GUI within OpenVSP. This may be the easiest way to generate a file from scratch for a new model but be aware that you will most likely need to make adjustments in the
Setup console tab (this is just a nested text editor).
Overview tab, you'll find several different sliders and inputs that will help you define a Setup file. More detail in the use of this console is covered in the "Introduction to VSPAERO" video. Once each value is defined for the flow conditions to be analyzed, click the
Setup Input File button.
If you select the
Setup tab, you should see that most of the values have been written in. Note that the Setup tab does NOT have the ability to define actuator discs at this time. These values must be written in manually. VSPAERO will run with the Setup file as-is, however if you want to conduct a more detailed analysis you must further specify the values in the file. Reynolds number, density, Vinf, among others are not written for you. Simply change the values in the Setup console and click the
Save Setup button to save your changes. The console will automatically save the file with the proper extension in the correct directory for you.
When running VSPAERO through the OpenVSP GUI, the program will automatically read and write the appropriate files in the directory that you are currently working. This is particularly useful for organizing the many files associated with the program. If you are running VSPAERO via the Command Prompt window, you generally need to have all of the DegenGeom and Setup files in the same directory where vspaero.exe is located. More information on running VSPAERO without the GUI is found in the VSPAERO from Command Prompt Window section.
You'll notice that the
Overview tab in the VSPAERO console has a
Num CPU entry. This feature allows you to specify how many of your computer's processors you wish to use. If, for example, you are working on something else and don't want all of your resources taken by the solver, just set the number to 1 or 2 depending on your computer setup. This will make the solver run slower, but free up resources for you to perform other tasks. However, if you want the solver to run as fast as possible you should set the number to the full number of processors installed on your computer. If you set the number greater than the number of processors installed, it will use all installed processors. Keep in mind that VSPAERO has been optimized to run on fewer processors than previous versions. This means that the more processors you run in parallel, the faster it will run but with diminishing returns. Above around 10, the code itself becomes a limiting factor and not the processor power. It is strongly recommended that you conduct a performance test with some simple cases if you are able to run on more than 10 processors to determine the optimal number for your situation.
To run VSPAERO, simply click the
Launch Solver button on the bottom left of the console. The buttons should fade and the
Kill Solver button should activate. This is used to stop the solver should you find a mistake in the setup file or if the solver is not converging. If you select the
Solver tab, you will see the printed text of VSPAERO running through iterations. The solver is done running when there is extra space at the bottom of the readout (you'll recognize it) and when the buttons on the
Overview tab are once again active. The appropriate output files will be placed in the working directory.
VSPAERO may be run from the Command Prompt if you wish to override some settings, cannot operate the GUI, or want to explore some of the other capabilities of the application.
paste. The entry should look like this:
Current Directory>CD NewDirectoryPath.
enter. You should now see the address of the VSPAERO home folder displayed as the working directory.
vspaerowill display the usage for the
vspaerocommand. Suppose that you want to solve using 4 processors and you also want to calculate some of the stability derivatives for your model. An example of the command for this would be:
vspaero -omp 4 -stab modelname_degengeom.
VSPAERO will write several files containing information important to analyzing models. A discussion of each file type and their associated values is shown below.
The History file contains the integrated values as computed by VSPAERO for each iteration. Here is where you will find much of the “big picture” data that you will need for baseline aerodynamic analyses such as the lift coefficient, induced drag, force and moment coefficients, etc…
Please scroll to see all values.
Iter Mach AoA Beta CL CDo CDi CDtot CS L/D E CFx CFy CFz CMx CMy CMz T/QS 1 0.30000 1.35135 0.00000 6.40445 0.18157 0.20966 0.39123 -0.00000 16.36998 13.32467 0.05856 -0.00000 6.40761 -0.00000 -20.59945 -0.00000 0.00000 2 0.30000 1.35135 0.00000 6.38714 0.18157 0.20837 0.38994 -0.00000 16.37977 13.33483 0.05768 -0.00000 6.39028 -0.00000 -20.49960 -0.00000 0.00000 3 0.30000 1.35135 0.00000 6.38287 0.18157 0.20847 0.39004 -0.00000 16.36450 13.31043 0.05788 -0.00000 6.38601 -0.00000 -20.47561 -0.00000 0.00000 4 0.30000 1.35135 0.00000 6.38143 0.18157 0.20860 0.39017 -0.00000 16.35533 13.29609 0.05805 -0.00000 6.38457 -0.00000 -20.46889 -0.00000 0.00000 5 0.30000 1.35135 0.00000 6.38071 0.18157 0.20865 0.39023 0.00000 16.35134 13.28984 0.05811 0.00000 6.38385 -0.00000 -20.46609 -0.00000 0.00000 Skin Fiction Drag Break Out: Surface CDo WingGeom : 0.09079 WingGeom : 0.09079
|HISTORY FILE KEY|
|Iter||Iteration Number||L/D||Lift to Drag Ratio (CL/CDtot)|
|Mach||Mach Number||E||Oswald Efficiency Factor (Span Efficiency)|
|AoA||Angle of Attack (Alpha)||CFx||X Direction Force Coefficient|
|Beta||Sideslip Angle (Beta)||CFy||Y Direction Force Coefficient|
|CL||Total Integrated Lift Coefficient||CFz||Z Direction Force Coefficient|
|CDo||Skin Friction Drag Coefficient (Estimated parasite drag)||CMx||X-Axis Moment Coefficient|
|CDi||Integrated Induced Drag Coefficient||CMy||Y-Axis Moment Coefficient|
|CDtot||Total Drag Coefficient (sum of CDo and CDi)||CMz||Z-Axis Moment Coefficient|
|CS||Side Force Coefficient||T/QS||Thrust/(Dynamic Pressure x Ref. Area)|
Note that the History file also breaks down the skin friction drag into the model's individual component contributions. Typically, full wings will have two contributions while body components, such as a fuselage, will have four contributions, one for each section of the flat plate cruciform.
The LOD file is a spanwise representation of the local lift, drag, and side force coefficients. It is useful for plotting the distribution of forces along a wing or body component to locate problem areas, drag sources, peak lifting sections, and slipstream effects. This file will also aid in the refinement of wing planforms if you are trying to find a particular wing loading curve.
Below is an example of a LOD file.
Wing Yavg Chord Cl Cd Cs 1 0.30805 4.97235 0.14922 -0.00563 -0.03691 1 0.92415 4.97235 0.29786 0.00878 0.00085 1 1.51729 4.90506 0.27234 0.00812 -0.01657 1 2.09007 4.77050 0.25547 0.00669 -0.01533 1 3.02089 4.61508 0.24144 0.00590 -0.01961 1 4.31511 4.43881 0.27181 0.00106 -0.02284 1 5.60931 4.26254 0.28315 0.00170 -0.02376 1 6.90350 4.08627 0.29164 0.00298 -0.02415 1 8.19767 3.91000 0.29676 0.00304 -0.02443 1 9.49182 3.73373 0.30041 0.00282 -0.02472 1 10.46638 3.60152 0.30167 0.00265 -0.02436 1 11.11354 3.51339 0.30050 0.00251 -0.02438 1 11.76070 3.42525 0.29967 0.00248 -0.02434 . . (more data points) . Comp Component-Name Mach AoA Beta CL CDi CS CFx CFy CFz Cmx Cmy Cmz 1 Wing 0.27992 0.31258 0.00000 0.13595 0.00163 -0.01056 0.00089 -0.01056 0.13596 0.03047 -0.03872 -0.00053 2 Wing 0.27992 0.31258 0.00000 0.16425 0.00088 0.01280 -0.00002 0.01280 0.16425 -0.03265 -0.04407 0.00049 3 Horz 0.27992 0.31258 0.00000 -0.01920 -0.00031 -0.00010 -0.00021 -0.00010 -0.01920 -0.00117 0.06480 -0.00003 4 Horz 0.27992 0.31258 0.00000 -0.00702 0.00004 0.00013 0.00007 0.00013 -0.00702 0.00066 0.02363 0.00005
|LOD FILE KEY|
|Wing||Wing/Body Component ID. Components are defined by the order in the OpenVSP geometry browser.|
|Yavg||Average Y-axis location of the section in feet|
|Chord||Section average chord length in feet|
|Cl||Local lift coefficient|
|Cd||Local drag coefficient|
|Cs||Local side force coefficient|
|Comp/Name||Component ID legend|
|AoA||Angle of attack (alpha) in degrees|
|CL||Component integrated lift coefficient|
|CDi||Component integrated induced drag coefficient|
|CS||Component integrated side force coefficient|
|CFx||Component integrated X force coefficient|
|CFy||Component integrated Y force coefficient|
|CFz||Component integrated Z force coefficient|
|Cmx||Component integrated X moment coefficient|
|Cmy||Component integrated Y moment coefficient|
|Cmz||Component integrated Z moment coefficient|
Information about ADB here.
Stability calculations can only be performed in VSPAERO from the Command Prompt (as of OpenVSP v.3.1.2). The stability derivatives are calculated by finding a “base” set of values specified from the input VSPAERO file then performing a further 6 solutions based on small step changes in 6 different parameters. This information is then used to find the slope between the calculated points. Note that these values are approximations!! As always, the accuracy of your results will depend highly on the fidelity and accuracy of your model.
An example of a stability file is shown below.
Sref_: 90.0000 Cref_: 3.0000 Bref_: 30.0000 Xcg_: 1.2474 Ycg_: -0.0000 Zcg_: 0.0000 AoA: 1.0000 Beta_: 0.0000 Mach_: 0.2720 Rho_: 0.0024 Vinf_: 100.0000 # Case CFx CFy CFz CMx CMy CMz CL CD CS # Base Aero -0.0012727 -0.0000000 0.0861266 -0.0000000 0.0147249 -0.0000000 0.0861357 0.0002306 -0.0000000 Alpha + 0.100 -0.0015400 -0.0000000 0.0947405 -0.0000000 0.0161975 -0.0000000 0.0947526 0.0002791 -0.0000000 Beta + 0.100 -0.0012727 -0.0000000 0.0861308 0.0000083 0.0147255 -0.0000001 0.0861399 0.0002306 0.0000004 Roll + 0.001 -0.0012728 0.0000017 0.0861337 0.0000982 0.0147262 0.0000028 0.0861427 0.0002306 0.0000017 Pitch + 0.001 -0.0012729 0.0000000 0.0861773 -0.0000000 0.0147226 -0.0000000 0.0861864 0.0002313 0.0000000 Yaw + 0.001 -0.0012727 0.0000000 0.0861292 -0.0000020 0.0147252 -0.0000000 0.0861383 0.0002306 0.0000000 Mach + 0.100 -0.0013044 0.0000000 0.0886562 -0.0000000 0.0151898 -0.0000000 0.0886654 0.0002431 0.0000000 Mach: 0.27200000 Alpha: 1.00000000 Density: 0.00237700 Uo: 100.00000000 # # Base Derivative: # Aero wrt wrt wrt wrt wrt wrt wrt # Coef Alpha Beta p q r Mach U # per per per per per per per # rad rad rad rad rad rad rad # CFx -0.0012727 -0.1531478 -0.0000241 -0.0006334 -0.0110894 -0.0001774 -0.0003165 -0.0000861 CFy -0.0000000 0.0000000 -0.0000093 0.0110526 0.0000000 0.0000000 0.0000000 0.0000000 CFz 0.0861266 4.9353572 0.0023587 0.0467516 3.3747551 0.0168161 0.0252952 0.0068803 CMx -0.0000000 0.0000000 0.0047814 0.6549244 0.0000000 -0.0133888 0.0000000 0.0000000 CMy 0.0147249 0.8437398 0.0003658 0.0087383 -0.1511212 0.0023092 0.0046487 0.0012644 CMz -0.0000000 -0.0000000 -0.0000739 0.0186758 -0.0000000 -0.0000000 -0.0000000 -0.0000000 CL 0.0861357 4.9370820 0.0023587 0.0467556 3.3744346 0.0168166 0.0252969 0.0068807 CD 0.0002306 0.0277621 0.0000168 0.0001826 0.0478099 0.0001161 0.0001250 0.0000340 CS -0.0000000 0.0000000 0.0002213 0.0110526 0.0000000 0.0000000 0.0000000 0.0000000 #
The information below this line is intended for use with VSPAERO v.1.0
VSPAERO requires degenerate geometry files generated using OpenVSP. It is helpful to remember that the software only uses lifting surfaces to determine lift induced drag and that the surfaces themselves are not required to be excessively smooth. The more detail that you can leave out of the model, the faster the software will run. You will, however, begin to lose information when the tessellation and number of interpolated sections become too low. The recommended tessellation for “simple” geometry wings is between 20 and 40 and the recommended cross section density is about 1 per foot (2 to 3 per meter).
As yet, the software will not recognize body components as generating lift. It is therefore recommended that, for preliminary analyses, you leave out the body objects (FUSE2 objects). This will not only reduce the possibility for computation error but will also greatly reduce processing times.
In order for VSPAERO to function properly, only MS_WING and FUSE2 components should be used in the simplified model to be analyzed. Under no circumstances will the software accept “open” components such as jet engine nacelles. If any component is not water tight, the DegenGeom function of OpenVSP will fail and VSP will crash. As always, save often.
DegenGeom function of OpenVSP can be found under the
Geom menu tab. Execute the operation to generate the files needed from VSP.
The VSPAERO input file is where a lot of mistakes can be made. Incorrect entry of information into the file will result in data inaccuracies or software failure. When you write the files, it is important to minimize the number of unnecessary spaces and returns to reduce the possibility of read error by the software.
In Notepad (or similar text only editing) create a document that has the following format exactly (copy and paste):
Sref= #### Cref= #### Bref= #### X_cg= 0 Y_cg= 0 Z_cg= 0 Mach= #### AoA= #### Beta= 0 Vinf= #### Rho= 0.0023769 WakeIters= 3 NumberOfRotors= 2 PropElement_1 1 #### #### #### 1.0 0 0 #### 0.00 #### #### #### PropElement_2 1 #### #### #### 1.000000 0.000000 0.000000 #### 0.00000 #### #### ####
Example) Piper Seminole PA-44-180
Sref=183.794 Cref=4.904 Bref=38.6 X_cg=0 Y_cg=0 Z_cg=0 Mach=0.256595212 AoA=-5 Beta=0 Vinf=278.48865 Rho=0.00186846 WakeIters=1 NumberOfRotors=2 PropElement_1 1 4.950000 -6.350000 1.050000 1.000000 0.000000 0.000000 3.083333333 0.00000 2700.000000 0.048727959 0.048901562 PropElement_2 1 4.950000 6.350000 1.050000 1.000000 0.000000 0.000000 3.080000 0.00000 -2700.000000 0.048727959 0.048901562
This will greatly simplify your efforts in writing an input file. The entries in the above text follow this key:
|Sref||Wing Surface Area (S)||Square Feet|
|Cref||Mean Aerodynamic Chord (MAC or C)||Feet|
|X_cg||X-Axis Center of Gravity Coordinate||Feet|
|Y_cg||Y-Axis Center of Gravity Coordinate||Feet|
|Z_cg||Z-Axis Center of Gravity Coordinate||Feet|
|AoA||Angle of Attack (Alpha)||Degrees|
|Vinf||Free Stream Velocity||Feet/Sec|
|Rho||Air Density at Altitude||Slug/Cubic Foot|
|WakeIters||Number of Wake Iterations to Perform||None|
|NumberOfRotors||Number of Rotors for the Condition||None|
|PropElement_N||The Nth Rotor Element Number||None|
|n||The Rotor Number||None|
|XXXX YYYY ZZZZ||Rotor Center Coordinates||Feet|
|XnXn YnYn ZnZn||Rotor Plane Normal Unit Vector||None|
|rrrr||Rotor Hub Radius||Feet|
|+(-) RPM|| Rotor Turning Speed (minus indicates CCW|
rotation as seen from front of A/C)
|CT||Rotor Thrust Coefficient||None|
|CP||Rotor Power Coefficient||None|
The values in this file should be found using your OpenVSP model, the POH for the aircraft, and the Drag Buildup Workbook. In OpenVSP, the AeroRef tool will provide the values for the first three entries. The POH will have power settings and propeller dimensions. The Drag Buildup Workbook will provide Air Density, Free Stream Velocity, Mach Number, Thrust Coefficient and Power Coefficient from the Flight Conditions section.
Once the proper entries have been made, save the file under the EXACT same name as the DegenGeom files written by OpenVSP with the file extension
Now you have the three files that VSPAERO needs to run the model. Copy or move all three files to the folder containing VSPAERO and Viewer (also holding the required .dll files to run) and you are ready to run VSPAERO from the command prompt.
VSPAERO is operated from the command prompt (Windows) or from the Unix shell. For this tutorial, it will be assumed that you are using Windows, however the commands are similar for Unix.
>vspaero –omp N modelname_degengeom.
Set Contour Levels. A normal range for viewer is -2 to 1.
modelname_degengeom.vspaerofile and save the document.
Use of the data obtained from VSPAERO is discussed further in the Drag Buildup Workbook section and in the Drag Buildup Workbook User Manual.
This page was created and edited by: — Brandon Litherland 2015/07/01 06:56