pydust-utils 0.1.8

Python utilities for DUST pre- and postprocessing

PyDUST Utils

Python utilities for DUST pre- and post-processing.

Features

• Mesh Generation: Create pointwise and parametric meshes for DUST simulations
• C81 Airfoil Data: Generate aerodynamic tables using NeuralFoil/AeroSandbox
• Post-Processing: Parse and analyze DUST output files (sectional loads, probes, integral forces)
• Visualization: 3D visualization of meshes, flow fields, and vortex structures with PyVista

Installation

Simple installation from PyPI:

pip install pydust-utils

For development:

git clone [e-mail]:Alecocco.1994/dust-private.git
cd dust-private/pydust_utils
pip install -e ".[dev,docs]"

Quick Start

Generation of Pointwise Mesh

from pydust_utils.build_mesh import MeshConfig, PointwiseMesh

# Create mesh configuration
config = MeshConfig(
    title='Wing Mesh',
    el_type='v',  # vortex-lattice
    nelem_chord=20,
    type_chord='cosine_le'
)

# Access nested Point and Line classes
Point = PointwiseMesh.Point
Line = PointwiseMesh.Line

# Define wing geometry with points
points = [
    Point(
        id=1,
        coordinates=[0.0, 0.0, 0.0],
        chord=1.0,
        twist=0.0,
        airfoil='naca0012',
        airfoil_table='naca0012'
    ),
    Point(
        id=2,
        coordinates=[0.0, 5.0, 0.5],
        chord=0.8,
        twist=-2.0,
        airfoil='naca0012',
        airfoil_table='naca0012'
    ),
]

# Connect points with lines
lines = [
    Line(
        type='spline',
        nelem_line=10,
        end_points=[1, 2],
        type_span='uniform'
    )
]

# Create mesh and write to file
mesh = PointwiseMesh(config, points, lines)
mesh.write('wing_pointwise.in')

Generation of Parametric Mesh

from pydust_utils.build_mesh import MeshConfig, ParametricMesh

# Create mesh configuration
config = MeshConfig(
    title='Wing Mesh',
    el_type='v',  # vortex-lattice
    nelem_chord=20,
    type_chord='cosine_le'
)

# Access nested Section and Region classes
Section = ParametricMesh.Section
Region = ParametricMesh.Region

# Define wing geometry with sections
sections = [
    Section(
        chord=1.0,
        twist=0.0,
        airfoil='naca0012',
        airfoil_table='naca0012'
    ),
    Section(
        chord=0.8,
        twist=-2.0,
        airfoil='naca0012',
        airfoil_table='naca0012'
    ),
]

# Define spanwise regions
regions = [
    Region(
        span=5.0,
        sweep=0.0,
        dihed=2.0,
        nelem_span=10,
        type_span='uniform'
    )
]

# Create mesh and write to file
mesh = ParametricMesh(config, sections, regions)
mesh.write('wing_parametric.in')

C81 Airfoil Data Generation

from pydust_utils.c81generator import Airfoil

# Generate C81 aerodynamic table
airfoil = Airfoil.generate(
    file_name='naca0012',
    pathprofile='airfoils/',
    reynolds=1e6,
    mach_range=(0.0, 0.3),
    n_mach=10,
    mbdynformat=False  # Use DUST format
)

# Or with multiple Reynolds numbers
airfoil = Airfoil.generate(
    file_name='naca0012',
    pathprofile='airfoils/',
    reynolds=[1e5, 5e5, 1e6],
    mach_range=(0.0, 0.3),
    n_mach=5
)

Post-Processing

from pydust_utils import SectionalData, ProbesData, IntegralData

# Read sectional loads
sectional_data = SectionalData.from_file('sectional_loads.dat')
print(sectional_data.sec.shape)  # (n_time, n_sec)

# Read probe velocities
probe_data = ProbesData.from_file('probes_velocity.dat')
print(probe_data.velocities.shape)  # (n_time, n_probes, 3)

# Read integral loads
integral_data = IntegralData.from_file('integral_loads.dat')
lift = integral_data.forces[:, 2]  # Extract lift force

Visualization

import h5py
import pyvista as pv
from pydust_utils import ColorMapManager, FlowPostProcessor, plot_dustpre_pv

# Visualize DUST pre-processor mesh from HDF5 output
with h5py.File('geo_input.h5', 'r') as f:
    rr = f['Components/Comp001/Geometry/rr'][:]
    ee = f['Components/Comp001/Geometry/ee'][:]

plotter = plot_dustpre_pv(rr, ee, title="Blade Mesh", rendering_backend="trame")

# Load custom colormap and create flow post-processor
cm_manager = ColorMapManager('colormaps/cool_warm.json')
flow_viz = FlowPostProcessor(colormap_manager=cm_manager)

# Visualize Q-criterion for vortex identification
flow_data = pv.read('flow_volume.vtr')
plotter = flow_viz.visualize_q_criterion(
    flow_data,
    q_min=0.01,
    q_max=10.0,
    opacity=0.3,
    colormap='cool_warm'
)
plotter.show()

# Visualize vorticity with vector glyphs
flow_slice = pv.read('flow_slice.vtr')
plotter = flow_viz.visualize_vorticity_glyphs(
    flow_slice,
    scale=0.1,
    opacity=0.7,
    glyph_type='arrow'
)
plotter.show()

Available Features

Mesh Generation (build_mesh)

• Three main classes: MeshConfig, PointwiseMesh, ParametricMesh
• Pointwise meshes: Define geometry with specific control points
  • Nested classes: PointwiseMesh.Point and PointwiseMesh.Line
  • Write method: mesh.write(filename)
• Parametric meshes: Use sections and regions for automatic interpolation
  • Nested classes: ParametricMesh.Section and ParametricMesh.Region
  • Write method: mesh.write(filename)
• Multiple element types: Vortex-lattice ('v'), lifting-line ('l'), panel ('p')
• Advanced distributions: Uniform, cosine, geometric series with refinement options

Airfoil Data (c81generator)

• C81 table generation: Create aerodynamic coefficient tables
• NeuralFoil integration: Use neural networks for predictions
• Multiple Reynolds numbers: Support for Re-dependent tables
• DUST and MBDyn formats: Compatible with multiple solvers

Post-Processing (parse_postpro_files)

• read_sectional - Sectional aerodynamic loads
• read_probes - Velocity probe data
• read_chordwise - Chordwise pressure distributions
• read_integral - Integral loads and forces
• read_hinge - Hinge loads for control surfaces

Visualization (visualization)

• plot_dustpre_pv: Visualize DUST pre-processor mesh output (HDF5 files)
  • Interactive (trame) and static rendering modes
  • Support for main and virtual mesh elements
  • Customizable colors, edges, and camera settings
• ColorMapManager: Load and manage custom colormaps from ParaView/Matplotlib
• FlowPostProcessor: Advanced flow field visualization
  • Q-criterion and Lambda2 vortex identification
  • Vorticity magnitude and vector field glyphs
  • Sectional flow visualization with customizable styling

Documentation

• PyPI: https://pypi.org/project/pydust-utils/
• Online Docs: https://alecocco.1994.gitlab.io/dust-private/ (GitLab Pages)

Build documentation locally:

cd pydust_utils
pip install -e ".[docs]"
sphinx-build -b html docs/source docs/build/html

Running Tests

pip install -e ".[dev]"
pytest tests/

Current Status: 156 tests, 94% coverage

Contributing

This package is developed and maintained by the DUST team at Politecnico di Milano.

Publishing

Build and upload to PyPI (maintainers only):

# Build distribution
pip install build
python -m build

# Upload to PyPI
pip install twine
twine upload dist/*

Links

• PyPI Package: https://pypi.org/project/pydust-utils/
• Documentation: https://alecocco.1994.gitlab.io/dust-private/
• DUST Homepage: https://www.dust.polimi.it/
• Repository: https://public.gitlab.polimi.it/DAER/dust

License

MIT License - Copyright (c) 2025 Alessandro Cocco, Politecnico di Milano

---

Made with ❤️ by the DUST team at Politecnico di Milano