1 - Flow5 API & Wing Parameterization

This repository provides a comprehensive suite of Python tools designed to automate geometry generation, analysis configuration, and result extraction for the Flow5 aerodynamic analysis software.

Next months i will update this repository with a module for airfoil generation and visualization functions and a XFOIL bridge module. I need some time for code cleanup and documentation.

This API supports Windows only. For Linux or macOS support, please submit a request via GitHub issues if you want. I need to fix only the flow5_run function.

The examples folder contains several scripts demonstrating how to use this library.

MATLAB API Wrapper

In addition to the native Python environment, this repository provides a MATLAB API Wrapper. This interface enables execution of the core automation functions directly from MATLAB by interfacing with the underlying Python engine. The MATLAB functions are similar to the python ones, as you can see in the examples. The function are the same, except for the plot_3d_live that uses plots generated by MATLAB, that doesn't need finalize_plot_3d_live and flow5_results return the results values separately from the headers list.

Installation

Ensure you have Python 3.7+ installed.

For Python installation you need to run install_framework.bat or run the following command pip install -e .. This installs also the following dependencies: numpy, pyvista, scipy and vtk.

MATLAB users after the Python installation need to link the "matlab" folder present in this repository into their projects like addpath("path of the 'matlab' folder");, as in the examples.

Modules

1. bridge

This module handles the interface between Python and Flow5, managing the creation of the folder structure and writing the configuration XML files.

flow5_case

Creates the folder structure and the case.xml file for Flow5.

• Args:
  • Path (str): The path of the main folder.
  • Threads (int): The number of threads to use for the analyses.
  • Fl5File (bool): If True, creates a .fl5 file for each analysis. Default is False.
  • StoreOP (bool): If True, stores the Operating Points for each analysis. Default is False. Flow5 7.55 is a bit bugged, for now is better to set it False.
  • Gate (bool, optional): If False, no file/folder is modified or created. Default is True.
• Returns:
  • CaseRes (dict): A dictionary with the paths of the folders and the case.xml file.

flow5_element

Generates a dictionary for the geometry visualization and another dictionary for element generation in Flow5.

• Args:
  • Name (str): The name of the element.
  • Type (str): The type of element (MAINWING, OTHERWING, ELEVATOR, FIN).
  • WingGeo (dict): A dictionary containing the geometric data of the element. It must contain the following keys:
    • FullWing (bool): If True, the element is symmetric with respect to the YZ plane (wing or half-wing). Default is False.
    • SecData (float list): A list of data for each section of the element. Each section must be represented by 5 values in that order:
      • Position along the y-axis (m).;
      • Chord length (m).
      • Offset (m).
      • Twist angle (deg).
      • Dihedral angle (deg).
  • Airfoils (str list): A list of file names for the airfoils corresponding to each section. Intermediate sections are represented by two profiles: one for the left side and one for the right side.
  • WingPos (float list): A list of three numbers representing the position in m of the * `element in the aircraft reference system (x, y, z).
  • WingTilt (float list): A list of two numbers representing the rotation angle in deg of the element around the x, y axes (Rx, Ry).
  • Panels (int, optional): TThe number of panels to use along the x-direction (chord). Default is 25.
• Returns:
  • GeoElem (dict): A dictionary containing the geometric data of the element for the visualization.
  • Element (dict): A dictionary containing the geometric data for the generation of the element in Flow5.

flow5_plane

Creates an XML file for the definition of an aircraft in Flow5.

• Args:
  • CaseRes (dict): The dictionary returned by flow5_case.
  • Name (str): The name of the aircraft.
  • MassRes (dict list): A list of dictionaries with the mass data for each element of the aircraft. Each dictionary must contain: -the keys "coord" (a list of three numbers for the coordinates x, y, z in m), "mass" (the mass in kg) and "tag" (a name to identify the mass point); -if the key "coord" is the name of the element, the key "mass" is its mass in kg (automatically distributed over the entire element by flow5) and there is no key "tag".
  • Elements (dict list): A list of dictionaries with the geometric data for each element of the aircraft obtained through flow5_element.
  • AirfoilsDir (string): The path of the folder containing the airfoils .dat files.
  • PolarsDir (string): The path of the folder containing the polars .plr or .txt files.
  • BankAng (float, optional): The bank angle in deg to apply to the entire aircraft (positive is clockwise rotation around the x-axis). Default is 0 deg.
  • TotRefS (bool, optional): If True, considers the total surface area of the aircraft as reference for the analyses (include OTHERWING elements). Default is False.
  • Gate (bool, optional): If False no file/folder is modified or created. Default is True.
• Returns:
  • PlaneRes (dict): A dictionary with the data related to the aircraft.

flow5_analysis

Creates an XML file for a Flow5 analysis.

• Args:
  • PlaneRes (dict): The dictionary returned by flow5_plane.
  • Name (str): The name of the analysis.
  • Type (str): The type of analysis (T1, T2, T3, T5, T8).
  • Method (str): The analysis method (LLT, VLM1, VLM2, QUADS, TRIUNIFORM, TRILINEAR).
  • ThinSurf (bool, optional): If True, considers thin surfaces. Default is True.
  • GrdEff (bool, optional): If True, considers ground effect. Default is False.
  • Height (float, optional): The height above ground for ground effect. Default is 0.
  • Viscosity (float, optional): The kinematic viscosity of the fluid. Default is 1.5e-05m^2/s.
  • Density (float, optional): The density of the fluid. Default is 1.225kg/m^3.
  • Viscous (bool, optional): If True, performs a viscous analysis. Default is True.
  • Xflr5Visc (bool, optional): If True uses CL data for viscous analysis (XFLR5 method). Default is True.
  • FixTAS (float, optional): The fixed velocity for fixed speed analyses. Default is 0m/s.
  • FixAoA (float, optional): The fixed angle of attack for fixed angle of attack analyses. Default is 0deg.
  • Optional (dict, optional): A dictionary with any additional parameters to include in the XML file. The key must be the XML parameter path like "Polar/Viscous_Analysis/TransAtHinge" associated to its value.
  • Gate (bool, optional): If False no file/folder is modified or created. Default is True.
• Returns:
  • AnalysisRes (dict): A dictionary with the data related to the analysis.

flow5_run

Executes the analyses in Flow5.

• Args:
  • ExePath (str): The path of the Flow5 executable.
  • AnalysisRes (dict list): A list of dictionaries with the data for each analysis obtained through flow5_analysis.
  • T12Range (float list, optional): A list of three numbers representing the range and step of the angle of attack in deg [min, max, step] for T1 and T2 analyses. Default is [0, 0, 0].
  • T3Range (float list, optional): A list of three numbers representing the range and step of the angle of attack in deg [min, max, step] for T3 analyses. Default is [0, 0, 0].
  • T5Range (float list, optional): A list of three numbers representing the range and step of the sideslip angle in deg [min, max, step] for T5 analyses. Default is [0, 0, 0].
  • T8Range (float list, optional): A list of three numbers representing the angle of attack (deg), sideslip angle (deg) and speed (m/s) of the drone [AoA, Beta, Speed] for T8 analyses. Default is [0, 0, 0].
  • Run (bool, optional): If True, executes the analyses. Default is True.
  • Store (bool, optional): If True, stores the results in the "stored" folder. Default is False.
  • Gate (bool, optional): If False no file/folder is modified or created and no analyses are executed. Default is True.
• Returns:
  • RunRes (dict list): A list of dictionaries with the data related to the results of each analysis.

flow5_results

Collects the results of the analyses in Flow5.

• Args:
  • RunRes (dict): A dictionary with the data related to the results of an analysis executed by flow5_run.
  • Data (str list): A list of names of data to collect. They must be present in the files containing the results obtained from Flow5 (without any parentheses that may contain the units).
  • OpPoints (bool, optional): If True, also reads the results from the individual Operating Points files. Default is False. Flow5 7.55 is a bit bugged, for now is better to set it False.
• Returns:
  • Results (str/float tuple): The results obtained from reading the analysis files (headers and values).
  • Analysis (str): The name of the analysis.

---

2. geometry

This repository contains a set of Python tools designed to automate geometry generation for the Flow5 aerodynamic analysis software.

trapez_wing

Generates wing geometry parameters based on the input specifications. Units are in meters and degrees.

• Args:
  • FullWing (bool): Indicates if the wing is full or half.
  • MiddleGap (float): The gap between the two halves of the wing if FullWing is False.
  • GorV (bool list): A list of booleans indicating which parameters are describe by a Gene value (from 0 to 10) or by its actual value (m and deg) The order of the list corresponds to the parameters: [Span, Chord, Offset, Twist, Dihedral].
  • SpanG (float list): A list of span values for each segment of the wing.
  • TaperG (float list): A list of taper ratios for each segment of the wing.
  • OffsetG (float list): A list of offset values for each segment of the wing.
  • TwistG (float list): A list of twist values for each section (number of segment+1) of the wing.
  • DihedralG (float list): A list of dihedral angles for each segment of the wing.
  • TargetS (float): The target wing area for the optimization.
  • MaxSpan (float): The maximum allowed wingspan for the optimization.
  • MinSeg (float): The minimum allowed segment length for the optimization.
  • ChordLim (float list): A list of limits for the chord length of the wing segments [min,max].
  • TwistLim (float list): A list of limits for the twist angles of the wing segments [min,max].
  • DihedLim (float list): A list of limits for the dihedral angles of the wing [min,max].
  • Accuracy (float, opzionale): The acceptable accuracy for an iterative loop (if used). Default is 0.001.
• Returns:
  • WingData (dict): A dictionary containing the generated wing geometry parameters, including:
    • "FullWing": The input FullWing value.
    • "SecData": A flattened list of section data for each segment of the wing, each section is described by [span posistion, chord, offset, twist, dihedral].
    • "S": The calculated wing area based on the generated geometry.
    • "WingSpan": The calculated wingspan based on the generated geometry.
    • "MAC": The calculated mean aerodynamic chord based on the generated geometry.
    • "AR": The calculated aspect ratio based on the generated geometry.

plot_3d

Plots the 3D elements using PyVista.

• Args:
  • GeoElems (dict list): List of geometric elements, each containing geometric data for the visualization.
  • AirfoilsDir (str): Directory path where airfoil coordinate files are stored.

plot_3d_live

Plots the 3D elements using PyVista. The graph do not stop the progress of the script and can be updated during loops. Args: * GeoElems (dict list): List of geometric elements, each containing geometric data for the visualization. * AirfoilsDir (str): Directory path where airfoil coordinate files are stored.

finalize_plot_3d_live

Finalizes the PyVista plot_3d_live and waits for the window to be closed by the user.