VTK Visualization

This guide demonstrates how to generate VTK visualization files from Kynema simulation outputs using the generate_vtk_output.py script. VTK (Visualization Toolkit) files can be opened in visualization software such as ParaView, VisIt, or other VTK-compatible viewers to create plots, movies, and interactive visualizations of your simulation results. This workflow has been tested with ParaView version 5.11.2 on macOS.

Tip

For the most up to date and working version of this script, see src/viz/generate_vtk_output.py.

To get help on using the script, run

python src/viz/generate_vtk_output.py -h

This displays the usage information for the script

usage: generate_vtk_output.py [-h] [--output_dir OUTPUT_DIR] [--start-timestep START_TIMESTEP] [--end-timestep END_TIMESTEP]
                              netcdf_file connectivity_file

Generate VTK files from Kynema NetCDF output

positional arguments:
  netcdf_file           Path to Kynema NetCDF output file e.g. blade_interface.nc
  connectivity_file     Path to mesh connectivity YAML file e.g. mesh_connectivity.yaml

options:
  -h, --help            show this help message and exit
  --output_dir, -o OUTPUT_DIR
                        Directory for writing the vtk output files
  --start-timestep, -s START_TIMESTEP
                        Starting timestep to visualize (default: 0)
  --end-timestep, -e END_TIMESTEP
                        Ending timestep to visualize (default: last timestep)

Overview

The generate_vtk_output.py script is a post-processing tool that converts Kynema simulation outputs into VTK (Visualization Toolkit) format for visualization and subsequent analysis. The script performs the following operations.

  1. Data Conversion: Reads time-series simulation data from NetCDF files and mesh connectivity information from YAML files, then converts this data into VTK’s unstructured grid format (vtkUnstructuredGrid). An unstructured grid is a flexible data structure that stores a collection of points and heterogeneous cells (each with a VTK cell type and point connectivity) without requiring a regular lattice structure. This makes it well-suited for flexible multibody systems where elements may have varying connectivity patterns and types.

  2. Element Visualization: Creates appropriate VTK representations for different Kynema elements:

    • Beam elements: Represented as polyline cells connecting multiple nodes

    • Mass elements: Represented as vertex cells at single nodes

    • Spring elements: Represented as line cells connecting two nodes

    • Constraint elements: Represented as line cells connecting constrained nodes

  3. Data Fields: Extracts and includes comprehensive node data in the VTK output:

    • Position and orientation: Node positions and 3×3 rotation matrices derived from quaternions

    • Velocities and accelerations: Translational and rotational velocities and accelerations

    • Forces and moments: Applied loads (when available in simulation output)

    • Deformation: Structural deformation data (when available)

    • Element metadata: Element IDs, types, and node connectivity information

  4. Time Series Support: Generates individual VTK files for each simulation timestep and creates a ParaView Data (PVD) collection file that groups all timesteps together, enabling time-based animation and analysis in ParaView.

Prerequisites

Before using the VTK visualization script, you’ll need the following Python packages installed in your environment.

  • numpy: For numerical operations

  • netCDF4: For reading Kynema NetCDF output files

  • vtk: For creating VTK visualization files

  • PyYAML: For reading yaml-based mesh connectivity files

You can install these dependencies using pip

pip install numpy netcdf4 vtk pyyaml

Or if you’re using conda

conda install numpy netcdf4 vtk pyyaml

Required Input Files

The VTK visualization script requires two input files, which are generated automatically when running simulations via Kynema APIs found in src/interfaces.

  1. NetCDF Output File: The primary output file generated by Kynema during simulation. It contains time-series data for all nodes including position, velocity, acceleration, forces, and moments. This file is generated automatically when running simulations via the high-level Kynema APIs provided in src/interfaces. File naming follows this pattern:

    • TurbineInterface API generates turbine_interface.nc

    • CFDInterface API generates cfd_interface.nc

    • BladeInterface API generates blade_interface.nc

  2. Mesh Connectivity File: A YAML file that describes the connectivity between nodes for different element types (beams, masses, springs, constraints). This file is generated during the simulation setup process and is named mesh_connectivity.yaml by default.

Note

To generate these files during simulation, ensure that the appropriate output configuration is set. For example, in test cases, verify that write_output is set to true to enable file output. The output file name can be specified using builder.Solution().SetOutputFile("filename").

Basic Usage

The simplest way to generate VTK files is to run the script with the required input files

python src/viz/generate_vtk_output.py simulation_output.nc mesh_connectivity.yaml

This creates VTK files for all timesteps in the output directory vtk_output/ in the current working directory.

Command Line Options

The script supports several command line options to customize the visualization output

python src/viz/generate_vtk_output.py netcdf_file connectivity_file [OPTIONS]

Required Arguments

  • netcdf_file: Path to Kynema NetCDF output file (e.g., turbine_interface.nc)

  • connectivity_file: Path to mesh connectivity YAML file (e.g., mesh_connectivity.yaml)

Optional Arguments

  • --output_dir, -o: Directory for writing VTK output files (default: vtk_output)

  • --start-timestep, -s: Starting timestep to visualize (default: 0)

  • --end-timestep, -e: Ending timestep to visualize (default: last timestep)

Example Usage

Generate VTK files for all timesteps for the IEA 15 MW reference turbine test case

python src/viz/generate_vtk_output.py \
    tests/regression_tests/TurbineInterfaceTest.IEA15/turbine_interface.nc \
    tests/regression_tests/TurbineInterfaceTest.IEA15/mesh_connectivity.yaml

Generate VTK files for a specific time range

python src/viz/generate_vtk_output.py \
    tests/regression_tests/TurbineInterfaceTest.IEA15/turbine_interface.nc \
    tests/regression_tests/TurbineInterfaceTest.IEA15/mesh_connectivity.yaml \
    --output_dir my_visualization \
    --start-timestep 0 \
    --end-timestep 50

Output Files

File Locations

  • For interface tests run from the tests/regression_tests/interfaces/ directory, output files are written to the build/tests/regression_tests/<TestName>/ directory

  • For custom simulations: Current working directory or a specified output path via the --output_dir option

Data Arrays Included

Point Data (per node)

  • Node identification numbers (NodeID)

  • Orientation data (3×3 rotation matrix components): - OrientationX - OrientationY - OrientationZ

  • Translational and rotational velocities

  • Translational and rotational accelerations

Cell Data (per element)

  • Element type information for filtering (numeric IDs (ElementType) and string names (ElementTypeName))

  • Element identification numbers (ElementID)

Visualization in ParaView

Opening the Collection File

  1. Launch ParaView

  2. Open the simulation.pvd file from your output directory

  3. This loads all timesteps as a time series

Basic Controls for Animation and Visualization

  • Use the animation controls to play through timesteps

  • Set the animation speed and range as desired

  • Export animations as movies using File → Save Animation

  • Select different data arrays from the “Coloring” dropdown menus

Tip

For detailed ParaView usage instructions, refer to the ParaView User’s Guide and ParaView Tutorials.

Examples

This section showcases some examples of the types of visualizations and animations that can be generated by the VTK script by leveraging the Kynema interfaces/APIs via the regression tests.

Static Curled Beam Visualization

This example demonstrates a static beam analysis with increasing tip moments, as described in the BladeInterfaceTest.StaticCurledBeam test of the regression suite. This test simulates a 10-meter long straight beam with applied moments at the tip, causing the beam to curl and deform progressively as the moment magnitude increases.

Beam Configuration

  • Beam length: 10 meters

  • Element order: 10 (high-order elements for accuracy)

  • Reference axis: Straight line along X-axis from \((0,0,0)\) to \((10,0,0)\)

  • Twist: No twist (0° at both root and tip)

  • Root boundary condition: Fixed (prescribed root motion)

Applied Loads

The test applies progressively increasing moments about the Y-axis at the beam tip:

  • 0 N⋅m (undeformed state)

  • 10,920 N⋅m

  • 21,840 N⋅m

  • 32,761 N⋅m

  • 43,681 N⋅m

  • 54,601 N⋅m

Simulation Parameters

  • Analysis type: Static

The visualization shows the beam’s deformation progression as the tip moment increases, demonstrating the nonlinear geometric effects as the beam curls into a circular arc. The beam tip moves from its initial undeformed position to various deformed positions, with the final state showing significant nonlinear deformation.

Rotating Beam Visualization

This example illustrates a rotating beam, as provided in the BladeInterfaceTest.RotatingBeam test of the regression test suite. This test simulates a straight, flexible beam with prescribed root motion rotating around the Z-axis with uniform angular velocity, representing a simplified wind turbine blade or helicopter rotor blade model.

Initial Conditions

  • Beam root position: \((2, 0, 0)\) m from origin

  • Initial angular velocity: \(\omega = [0, 0, 2]\) rad/s i.e. ~20 rpm (rotation around Z-axis)

  • Root motion: Prescribed BC

  • Gravity: Not prescribed

Simulation Parameters

  • Duration: 5 seconds with 0.01 s time steps

The animation demonstrates the beam’s elastic deformation as it rotates, including tip deflection due to centrifugal loading and the dynamic response of the flexible structure under the applied uniform angular velocity, particularly evident during the initial transient response. The legend shows the rotational velocity of the beam in rad/s.

Point Mass Rigid Body With Mooring Lines Visualization

The following animation demonstrates visualization of a point mass rigid body with three mooring lines from the CFDInterfaceTest.FloatingPlatform regression test. This test simulates a lumped mass rigid body with three tensioned mooring lines subjected to time-varying loads representing buoyancy and wave forces, similar to the example described in Example: Rigid body with three springs. The mooring lines are modeled as linear springs and are connected to the platform at the fairlead points and to the seabed at the anchor points.

Platform Properties

  • Platform mass: \(1.419625 \times 10^7\) kg (14,200 tons)

  • Platform moments of inertia: \([1.2898 \times 10^{10}, 1.2851 \times 10^{10}, 1.4189 \times 10^{10}]\) kg⋅m²

  • Platform modeled as a rigid body point mass i.e. a point mass with inertia

  • Gravity: \(9.8124\) m/s² in negative Z direction

Mooring System Configuration

  • Number of mooring lines: 3 (linear spring elements)

Applied Time-Varying Loads

  • Y-direction force: \(1 \times 10^6\) N oscillating at 0.05 Hz (20 s period)

  • Z-direction buoyancy: Base buoyancy force + oscillating component at 0.05 Hz (20 s period)

  • Roll moment (Rx): \(5 \times 10^5\) N⋅m oscillating at 0.067 Hz (15 s period)

  • Pitch moment (Ry): \(1 \times 10^6\) N⋅m oscillating at 0.033 Hz (30 s period)

  • Yaw moment (Rz): \(2 \times 10^7\) N⋅m oscillating at 0.017 Hz (60 s period)

Simulation Parameters

  • Duration: 120 seconds with 0.1 s time steps

The animation demonstrates all six degrees of freedom: surge, sway, heave, roll, pitch, and yaw motions as the floating platform responds to the oscillatory loads while being restrained by the three-point mooring system.

Turbine Structure Visualization

The following animation demonstrates the flexible multibody dynamics of a wind turbine structure during dynamic simulation, utilizing the TurbineInterfaceTest.IEA15_Structure regression test. This test builds the IEA‑15‑240‑RWT turbine structure from a WindIO YAML file with the following initial conditions and applied loads:

Initial Conditions

  • Initial rotor azimuth angle: 0° i.e. blade 1 is at 12 o’clock position

  • Initial blade pitch angles: 0° (all blades)

  • Initial nacelle yaw angle: 0°

  • Tower base: Fixed BC

  • Gravity: 9.81 m/s² in negative Z direction

Applied Loads and Controls

  • Tower load: 100 kN at the tower‑top node

  • Generator torque: 100 MNm applied to the turbine shaft

  • Time‑varying blade‑3 pitch: 0.5 rad/s rate (t * 0.5)

  • Time‑varying yaw angle: 0.3 rad/s rate (t * 0.3)

Simulation Parameters

  • Duration: 5 seconds with 0.01 s time steps

Note

This is a flexible multibody dynamics simulation of the IEA‑15‑240‑RWT wind turbine under an unrealistically aggressive start-up with prescribed blade pitch and yaw. The turbine is under gravity loading, but there are no aerodynamic forces. The simulation was created to demonstrate the robustness of the Kynema model, even under fast, large nonlinear deflections.

This is a turbine start-up simulation i.e. the turbine is started from rest with the applied generator torque and blade pitch and yaw control inputs. The animation demonstrates blade deformation, tower motion, nacelle yaw rotation, blade pitch changes, and overall structural response during the simulation duration.