streamlines and streamtube

Author: emmanuelle

python/streamline-plots.md

@@ -0,0 +1,112 @@
+---
+jupyter:
+  jupytext:
+    notebook_metadata_filter: all
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.1'
+      jupytext_version: 1.1.1
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+  language_info:
+    codemirror_mode:
+      name: ipython
+      version: 3
+    file_extension: .py
+    mimetype: text/x-python
+    name: python
+    nbconvert_exporter: python
+    pygments_lexer: ipython3
+    version: 3.7.3
+  plotly:
+    description: How to make a streamline plot in Python. A streamline plot displays
+      vector field data.
+    display_as: scientific
+    has_thumbnail: true
+    ipynb: ~notebook_demo/43
+    language: python
+    layout: user-guide
+    name: Streamline Plots
+    order: 13
+    permalink: python/streamline-plots/
+    thumbnail: thumbnail/streamline.jpg
+    title: Python Streamline Plots | plotly
+---
+
+A Streamline plot is a representation based on a 2-D vector field interpreted as a velocity field, consisting of closed curves tangent to the velocity field. In the case of a stationary velocity field, streamlines coincide with trajectories (see also the [Wikipedia page on streamlines, streaklines and pathlines](https://en.wikipedia.org/wiki/Streamlines,_streaklines,_and_pathlines)).
+
+For the streamline figure factory, one needs to provide
+- uniformly spaced ranges of `x` and `y` values (1D)
+- 2-D velocity values `u` and `v` defined on the cross-product (`np.meshgrid(x, y)`) of `x` and `y`.
+
+Velocity values are interpolated when determining the streamlines. Streamlines are initialized on the boundary of the `x-y` domain. 
+
+#### Basic Streamline Plot
+
+```python
+import plotly.figure_factory as ff
+
+import numpy as np
+
+x = np.linspace(-3, 3, 100)
+y = np.linspace(-3, 3, 100)
+Y, X = np.meshgrid(x, y)
+u = -1 - X**2 + Y
+v = 1 + X - Y**2
+
+# Create streamline figure
+fig = ff.create_streamline(x, y, u, v, arrow_scale=.1)
+fig.show()
+```
+
+#### Streamline and Source Point Plot
+
+```python
+import plotly.figure_factory as ff
+import plotly.graph_objects as go
+
+import numpy as np
+
+N = 50
+x_start, x_end = -2.0, 2.0
+y_start, y_end = -1.0, 1.0
+x = np.linspace(x_start, x_end, N)
+y = np.linspace(y_start, y_end, N)
+X, Y = np.meshgrid(x, y)
+source_strength = 5.0
+x_source, y_source = -1.0, 0.0
+
+# Compute the velocity field on the mesh grid
+u = (source_strength/(2*np.pi) *
+     (X - x_source)/((X - x_source)**2 + (Y - y_source)**2))
+v = (source_strength/(2*np.pi) *
+     (Y - y_source)/((X - x_source)**2 + (Y - y_source)**2))
+
+# Create streamline figure
+fig = ff.create_streamline(x, y, u, v,
+                           name='streamline')
+
+# Add source point
+fig.add_trace(go.Scatter(x=[x_source], y=[y_source],
+                          mode='markers',
+                          marker_size=14,
+                          name='source point'))
+
+fig.show()
+```
+
+#### See also
+
+For a 3D version of streamlines, use the trace `go.Streamtube` documented [here](./streamtube-plot/).
+
+For representing the 2-D vector field as arrows, see the [quiver plot tutorial](./quiver-plots/).
+
+
+#### Reference
+
+```python
+help(ff.create_streamline)
+```

python/streamtube-plot.md

@@ -40,195 +40,23 @@ jupyter:
 ### Introduction
 
 
-In streamtube plots, attributes inlcude `x`, `y`, and `z`, which set the coordinates of the vector field, and `u`, `v`, and `w`, which sets the x, y, and z components of the vector field. Additionally, you can use `starts` to determine the streamtube's starting position. Lastly, `maxdisplayed` determines the maximum segments displayed in a streamtube.
+In streamtube plots, attributes include `x`, `y`, and `z`, which set the coordinates of the vector field, and `u`, `v`, and `w`, which set the x, y, and z components of the vector field. Additionally, you can use `starts` to determine the streamtube's starting position. 
 
 
 ### Basic Streamtube Plot
 
 ```python
 import plotly.graph_objects as go
 
-import pandas as pd
-
-df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/streamtube-basic.csv')
-
-fig = go.Figure(data=go.Streamtube(
-    x = df['x'],
-    y = df['y'],
-    z = df['z'],
-    u = df['u'],
-    v = df['v'],
-    w = df['w'],
-    sizeref = 0.5,
-    colorscale = 'Blues',
-    cmin = 0,
-    cmax = 3
-))
-
-
-fig.update_layout(
-    scene = dict(
-      camera = dict(
-        eye = dict(
-          x = -0.7243612458865182,
-          y = 1.9269804254717962,
-          z = 0.6704828299861716
-        )
-      )
-    )
-)
-
-fig.show()
-```
-
-```python
-import plotly.graph_objects as go
-
-fig = go.Figure(data=go.Streamtube(x=[0, 0, 0], y=[0, 1, 2], z=[0, 0, 0], u=[0, 0, 0], v=[1, 2, 3], w=[0, 0, 0]))
+fig = go.Figure(data=go.Streamtube(x=[0, 0, 0], y=[0, 1, 2], z=[0, 0, 0], 
+                                   u=[0, 0, 0], v=[1, 1, 1], w=[0, 0, 0]))
 fig.show()
 ```
 
-```python
-import plotly.graph_objects as go
-
-fig = go.Figure(data=go.Streamtube(x=[0, 1, 2], y=[0, 0, 0], z=[0, 0, 0], u=[1, 2, 3], v=[0, 0, 0], w=[0, 0, 0],
-                                  starts=dict(x=[0],
-                             y=[0],
-                             z=[0],)))
-fig.show()
-```
-
-```python
-import plotly.graph_objects as go
-
-fig = go.Figure(data=go.Streamtube(x=[0, 0, 0], y=[0, 0, 0], z=[0, 1, 2], u=[0, 0, 0], v=[0, 0, 0], w=[1, 2, 3],
-                                  starts=dict(x=[0],
-                             y=[0],
-                             z=[0],)))
-fig.show()
-```
-
-```python
-import numpy as np
-import plotly.graph_objects as go
-
-x, y, z = np.mgrid[1:4:10j, 1:4:10j, 1:4:10j] 
-u = 0.001 * x
-v = 0.001 * y
-w = 0.1 * z
-
-sx=np.linspace(1, 4, 10, endpoint=True)
-sx, sy=np.meshgrid(sx, sx)
-sz=np.ones(sx.shape)
-
-
-fig = go.Figure(data=go.Streamtube(
-    x=x.ravel(), 
-    y=y.ravel(), 
-    z=z.ravel(), 
-    u=u.ravel(), 
-    v=v.ravel(), 
-    w=w.ravel(), 
-    starts=dict(x=sx.flatten(),
-                             y=sy.flatten(),
-                             z=sz.flatten()),
-    hoverinfo='x+y+z+u+v+w+norm',
-    #sizeref=0.3
-))
-fig.show()
-```
-
-```python
-import numpy as np
-import plotly.graph_objects as go
-
-x, y, z = np.mgrid[1:4:10j, 1:4:10j, 1:4:10j] 
-u = 0.000 * x**2
-v = 0.00 * np.random.random(y.shape)
-w = 0.1 * y
-
-sx=np.linspace(1, 4, 10, endpoint=True)
-sx, sy=np.meshgrid(sx, sx)
-sz=np.ones(sx.shape)
-
-
-fig = go.Figure(data=go.Streamtube(
-    x=x.ravel(), 
-    y=y.ravel(), 
-    z=z.ravel(), 
-    u=u.ravel(), 
-    v=v.ravel(), 
-    w=w.ravel(), 
-    starts=dict(x=sx.flatten(),
-                             y=sy.flatten(),
-                             z=sz.flatten()),
-    hoverinfo='x+y+z+u+v+w+norm',
-    sizeref=0.3
-))
-fig.show()
-```
-
-```python
-import numpy as np
-import plotly.graph_objects as go
-
-x, y, z = np.mgrid[1:2:4j, 1:2:4j, 1:2:4j]
-u = np.zeros_like(x)
-v = x.copy()
-w = np.zeros_like(z)
-
-fig = go.Figure(data=go.Streamtube(x=x.ravel(), y=y.ravel(), z=z.ravel(),
-                                   u=u.ravel(), v=v.ravel(), w=w.ravel(),
-                                   hoverinfo=['x', 'y']
-))
-fig.show()
-```
-
-```python
-x.ravel(), y.ravel(), z.ravel(), v.ravel()
-```
-
-```python
-v.ravel()
-```
-
-```
-fig.data
-
-```
-
-```python
-import numpy as np
-import plotly.graph_objects as go
-
-x, y, z = np.mgrid[-4:4:20j, -4:4:20j, 0:4:20j] 
-r = np.sqrt(x ** 2 + y ** 2 + z ** 2 + 0.1) 
-#u = 0.1 * y * np.sin(r) / r 
-u = 0.005 * np.random.random(x.shape)
-v = 0.005 * np.random.random(y.shape)
-#v = -0.1 * x * np.sin(r) / r 
-w = 0.1 * z
-
-sx=np.linspace(-4, 4, 10)
-sx, sy=np.meshgrid(sx, sx)
-sz=np.ones(sx.shape)
-
-
-fig = go.Figure(data=go.Streamtube(
-    x=x.ravel(), y=y.ravel(), z=z.ravel(), u=u.ravel(), v=v.ravel(), w=w.ravel(), 
-    starts=dict(x=sx.flatten(),
-                             y=sy.flatten(),
-                             z=sz.flatten()),
-))
-fig.show()
-```
-
-```python
-df
-```
-
 ### Starting Position and Segments
 
+By default, streamlines are initialized in the x-z plane of minimal y value. You can change this behaviour by providing directly the starting points of streamtubes.
+
 ```python
 import plotly.graph_objects as go
 
@@ -273,8 +101,36 @@ fig.update_layout(
 fig.show()
 ```
 
+### Tube color and diameter
+
+The color of tubes is determined by their local norm, and the diameter of the field by the local [divergence](https://en.wikipedia.org/wiki/Divergence) of the vector field. 
+
+In all cases below the norm is proportional to `z**2` but the direction of the vector is different, resulting in a different divergence field. 
+
 ```python
-df
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+import numpy as np
+
+x, y, z = np.mgrid[0:10, 0:10, 0:10] 
+x = x.T.flatten() 
+y = y.T.flatten()
+z = z.T.flatten()
+
+u = np.zeros_like(x)
+v = np.zeros_like(y)
+w = z**2
+
+fig = make_subplots(rows=1, cols=3, specs=[[{'is_3d': True}, {'is_3d': True}, {'is_3d':True}]])
+
+fig.add_trace(go.Streamtube(x=x, y=y, z=z, u=u, v=v, w=w), 1, 1)
+fig.add_trace(go.Streamtube(x=x, y=y, z=z, u=w, v=v, w=u), 1, 2)
+fig.add_trace(go.Streamtube(x=x, y=y, z=z, u=u, v=w, w=v), 1, 3)
+
+fig.update_layout(scene_camera_eye=dict(x=2, y=2, z=2),
+                  scene2_camera_eye=dict(x=2, y=2, z=2),
+                  scene3_camera_eye=dict(x=2, y=2, z=2))
+fig.show()
 ```
 
 #### Reference