Helpers: compute streamlines

examples/06-plotting/08_plot_3d_streamlines.py → examples/12-streamlines/00_plot_3d_streamlines.py

@@ -1,16 +1,17 @@
 """
 .. _plot_3d_streamlines:
 
-Plot 3D streamlines
-~~~~~~~~~~~~~~~~~~~
-This example shows you how to plot streamlines of fluid simulation results,
+Compute and plot 3D streamlines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This example shows you how to compute and
+plot streamlines of fluid simulation results,
 for 3D models.
 
 """
 
 ###############################################################################
-# Plot streamlines from single source
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Compute and plot streamlines from single source
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ###############################################################################
 # Import modules, create the data sources and the model
@@ -19,6 +20,7 @@
 
 from ansys.dpf import core as dpf
 from ansys.dpf.core import examples
+from ansys.dpf.core.helpers.streamlines import compute_streamlines
 from ansys.dpf.core.plotter import DpfPlotter
 
 ###############################################################################
@@ -38,48 +40,58 @@
 # Meshed region is used as geometric base to compute the streamlines.
 # Velocity data is used to compute the streamlines. The velocity data must be nodal.
 
+###############################################################################
 # Get the meshed region:
 meshed_region = m_fluent.metadata.meshed_region
 
+###############################################################################
 # Get the velocity result at nodes:
 velocity_op = m_fluent.results.velocity()
 fc = velocity_op.outputs.fields_container()
 field = dpf.operators.averaging.to_nodal_fc(fields_container=fc).outputs.fields_container()[0]
 
 ###############################################################################
-# Plot the streamlines adjusting the request
-# ------------------------------------------
+# Compute and plot the streamlines adjusting the request
+# ------------------------------------------------------
 # The following steps show you how to create streamlines using DpfPlotter, with several sets
 # of parameters. It demonstrates the issues that can happen and the adjustments that you can make.
 
+###############################################################################
 # First, a DpfPlotter is created and the streamline is created with default values.
 pl0 = DpfPlotter()
 try:
+    streamline_obj = compute_streamlines(meshed_region=meshed_region, field=field)
     pl0.add_mesh(meshed_region=meshed_region, opacity=0.3)
-    pl0.add_streamlines(meshed_region=meshed_region, field=field)
+    pl0.add_streamlines(streamlines=streamline_obj)
     pl0.show_figure(show_axes=True)
 except:
     # It throws an error and ends here, because source points are not set correctly.
     # To fix this issue, the source_center parameter is used to move
     # the streamlines source center.
     pass
 
+###############################################################################
 # Then, you can correctly set the source coordinates using the
 # "source_center" argument that moves the source center,
 # the "return_source" arguments that displays the source, and
 # "permissive" option that allows you to display the source even, if the computed
 # streamline size is zero.
-pl1 = DpfPlotter()
-pl1.add_mesh(meshed_region=meshed_region, opacity=0.3)
-pl1.add_streamlines(
+streamline_obj, source_obj = compute_streamlines(
     meshed_region=meshed_region,
     field=field,
     return_source=True,
     source_center=(0.1, 0.1, 0.2),
+)
+pl1 = DpfPlotter()
+pl1.add_mesh(meshed_region=meshed_region, opacity=0.3)
+pl1.add_streamlines(
+    streamlines=streamline_obj,
+    source=source_obj,
     permissive=True,
 )
 pl1.show_figure(show_axes=True)
 
+###############################################################################
 # After the adjustment, the correct values for the "source_center" argument are set.
 # You can remove the "permissive" option.
 # You can display velocity data with a small opacity value to avoid hiding the streamlines.
@@ -89,23 +101,27 @@
 # - n_points: source number of points
 # - source_radius
 # - max_time: allows the streamline to be computed along a certain length
-pl2 = DpfPlotter()
-pl2.add_field(field, meshed_region, opacity=0.2)
-pl2.add_streamlines(
+streamline_obj, source_obj = compute_streamlines(
     meshed_region=meshed_region,
     field=field,
     return_source=True,
     source_center=(0.56, 0.48, 0.0),
-    radius=0.001,
     n_points=10,
     source_radius=0.075,
     max_time=10.0,
 )
+pl2 = DpfPlotter()
+pl2.add_field(field, meshed_region, opacity=0.2)
+pl2.add_streamlines(
+    streamlines=streamline_obj,
+    source=source_obj,
+    radius=0.001,
+)
 pl2.show_figure(show_axes=True)
 
 ###############################################################################
-# Plot streamlines from several sources
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Compute and plot streamlines from several sources
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ###############################################################################
 # Get data to plot
@@ -128,44 +144,64 @@
 field = velocity_op.outputs.fields_container()[0]
 
 ###############################################################################
-# Compute streamlines from different sources and plot
-# ---------------------------------------------------
+# Compute streamlines from different sources
+# ------------------------------------------
 
-# Add streamlines from different sources:
-pl = DpfPlotter()
-pl.add_field(field, meshed_region, opacity=0.2)
-pl.add_streamlines(
+###############################################################################
+# Compute streamlines from different sources:
+streamline_1, source_1 = compute_streamlines(
     meshed_region=meshed_region,
     field=field,
-    radius=0.007,
     return_source=True,
     source_radius=0.25,
     source_center=(0.75, 0.0, 0.0),
 )
-pl.add_streamlines(
+streamline_2, source_2 = compute_streamlines(
     meshed_region=meshed_region,
     field=field,
-    radius=0.007,
     return_source=True,
     source_radius=0.25,
     source_center=(0.0, 0.75, 0.0),
 )
-pl.add_streamlines(
+streamline_3, source_3 = compute_streamlines(
     meshed_region=meshed_region,
     field=field,
-    radius=0.007,
     return_source=True,
     source_radius=0.25,
     source_center=(-0.75, 0.0, 0.0),
 )
-pl.add_streamlines(
+streamline_4, source_4 = compute_streamlines(
     meshed_region=meshed_region,
     field=field,
-    radius=0.007,
     return_source=True,
     source_radius=0.25,
     source_center=(0.0, -0.75, 0.0),
 )
 
-# Plot:
+###############################################################################
+# Plot streamlines from different sources
+# ---------------------------------------
+
+pl = DpfPlotter()
+pl.add_field(field, meshed_region, opacity=0.2)
+pl.add_streamlines(
+    streamlines=streamline_1,
+    source=source_1,
+    radius=0.007,
+)
+pl.add_streamlines(
+    streamlines=streamline_2,
+    source=source_2,
+    radius=0.007,
+)
+pl.add_streamlines(
+    streamlines=streamline_3,
+    source=source_3,
+    radius=0.007,
+)
+pl.add_streamlines(
+    streamlines=streamline_4,
+    source=source_4,
+    radius=0.007,
+)
 pl.show_figure(show_axes=True)

examples/06-plotting/09_plot_surface_streamlines.py → examples/12-streamlines/01_plot_surface_streamlines.py

@@ -1,10 +1,10 @@
 """
 .. _plot_surf_streamlines:
 
-Plot 2D streamlines
-~~~~~~~~~~~~~~~~~~~
-This example shows you how to plot streamlines of fluid simulation results,
-for 2D models.
+Compute and plot 2D streamlines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This example shows you how to compute and plot
+streamlines of fluid simulation results, for 2D models.
 
 """
 
@@ -19,6 +19,7 @@
 
 from ansys.dpf import core as dpf
 from ansys.dpf.core import examples
+from ansys.dpf.core.helpers.streamlines import compute_streamlines
 from ansys.dpf.core.plotter import DpfPlotter
 
 ###############################################################################
@@ -38,29 +39,54 @@
 # Meshed region is used as the geometric base to compute the streamlines.
 # Velocity data is used to compute the streamlines. The velocity data must be nodal.
 
+###############################################################################
 # Get the meshed region:
 meshed_region = m_fluent.metadata.meshed_region
 
+###############################################################################
 # Get the velocity result at nodes:
 velocity_op = m_fluent.results.velocity()
 fc = velocity_op.outputs.fields_container()
 field = dpf.operators.averaging.to_nodal_fc(fields_container=fc).outputs.fields_container()[0]
 
+###############################################################################
+# Compute single streamline
+# -------------------------
+
+single_2d_streamline, single_2d_source = compute_streamlines(
+    meshed_region=meshed_region,
+    field=field,
+    start_position=(0.005, 0.0005, 0.0),
+    surface_streamlines=True,
+    return_source=True,
+)
+
 ###############################################################################
 # Plot single streamline
 # ----------------------
 
 pl_single = DpfPlotter()
 pl_single.add_field(field, meshed_region, opacity=0.2)
 pl_single.add_streamlines(
+    streamlines=single_2d_streamline,
+    source=single_2d_source,
+    radius=0.00002,
+)
+pl_single.show_figure(show_axes=True)
+
+###############################################################################
+# Compute multiple streamlines
+# ----------------------------
+multiple_2d_streamlines, multiple_2d_source = compute_streamlines(
     meshed_region=meshed_region,
     field=field,
-    return_source=True,
-    radius=0.00002,
-    start_position=(0.005, 0.0005, 0.0),
+    pointa=(0.005, 0.0001, 0.0),
+    pointb=(0.005, 0.001, 0.0),
+    n_points=10,
     surface_streamlines=True,
+    return_source=True,
 )
-pl_single.show_figure(show_axes=True)
+
 
 ###############################################################################
 # Plot multiple streamlines
@@ -69,13 +95,8 @@
 pl_multiple = DpfPlotter()
 pl_multiple.add_field(field, meshed_region, opacity=0.2)
 pl_multiple.add_streamlines(
-    meshed_region=meshed_region,
-    field=field,
-    return_source=True,
+    streamlines=multiple_2d_streamlines,
+    source=multiple_2d_source,
     radius=0.000015,
-    pointa=(0.005, 0.0001, 0.0),
-    pointb=(0.005, 0.001, 0.0),
-    n_points=10,
-    surface_streamlines=True,
 )
 pl_multiple.show_figure(plane="xy", show_axes=True)

examples/12-streamlines/README.txt

@@ -0,0 +1,6 @@
+.. _examples_streamlines:
+
+Streamlines examples
+====================
+These examples show how compute and plot streamlines.
+

src/ansys/dpf/core/animator.py

@@ -9,7 +9,8 @@
 from typing import Union, Sequence
 
 import ansys.dpf.core as core
-from ansys.dpf.core.plotter import _sort_supported_kwargs, _PyVistaPlotter
+from ansys.dpf.core.helpers.utils import _sort_supported_kwargs
+from ansys.dpf.core.plotter import _PyVistaPlotter
 
 
 class _InternalAnimatorFactory: