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 .. code-block:: bash python src/viz/generate_vtk_output.py -h This displays the usage information for the script .. code-block:: text 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 .. code-block:: bash pip install numpy netcdf4 vtk pyyaml Or if you're using conda .. code-block:: bash 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 .. code-block:: bash 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 .. code-block:: bash 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 .. code-block:: bash 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 .. code-block:: bash 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//`` 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 :math:`(0,0,0)` to :math:`(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. .. youtube:: 5z8oQr2XyDc?si=TqYs2xVkJAyxoPIj :width: 640 :height: 480 :align: center 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: :math:`(2, 0, 0)` m from origin - Initial angular velocity: :math:`\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. .. youtube:: LDk0f3pxPb8?si=FSnXFo6wQmh0Fn1_ :width: 640 :height: 480 :align: center 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 :doc:`floating_platform`. 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: :math:`1.419625 \times 10^7` kg (14,200 tons) * Platform moments of inertia: :math:`[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: :math:`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: :math:`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): :math:`5 \times 10^5` N⋅m oscillating at 0.067 Hz (15 s period) * Pitch moment (Ry): :math:`1 \times 10^6` N⋅m oscillating at 0.033 Hz (30 s period) * Yaw moment (Rz): :math:`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. .. youtube:: zPF4K1FPVMw?si=L04MVLnenX1MzJFl :width: 640 :height: 480 :align: center 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. .. youtube:: QommrkhmfDQ?si=D3tBRDd3VZr36YAR :width: 640 :height: 480 :align: center