Streamtube and quiver tutorials (#124)

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

@@ -0,0 +1,138 @@
+---
+jupyter:
+  jupytext:
+    notebook_metadata_filter: all
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.1'
+      jupytext_version: 1.2.3
+  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 3D streamtube plots in Python with Plotly.
+    display_as: 3d_charts
+    has_thumbnail: true
+    ipynb: ~notebook_demo/207
+    language: python
+    layout: user-guide
+    name: 3D Streamtube Plots
+    order: 21
+    page_type: u-guide
+    permalink: python/streamtube-plot/
+    thumbnail: thumbnail/streamtube.jpg
+    title: 3D Streamtube Plots | Plotly
+---
+
+
+### Introduction
+
+
+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
+
+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()
+```
+
+### 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
+
+import pandas as pd
+
+df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/streamtube-wind.csv').drop(['Unnamed: 0'],axis=1)
+
+fig = go.Figure(data=go.Streamtube(
+    x = df['x'],
+    y = df['y'],
+    z = df['z'],
+    u = df['u'],
+    v = df['v'],
+    w = df['w'],
+    starts = dict(
+        x = [80] * 16,
+        y = [20,30,40,50] * 4,
+        z = [0,0,0,0,5,5,5,5,10,10,10,10,15,15,15,15]
+    ),
+    sizeref = 0.3,
+    colorscale = 'Portland',
+    showscale = False,
+    maxdisplayed = 3000
+))
+
+fig.update_layout(
+    scene = dict(
+        aspectratio = dict(
+            x = 2,
+            y = 1,
+            z = 0.3
+        )
+    ),
+    margin = dict(
+        t = 20,
+        b = 20,
+        l = 20,
+        r = 20
+    )
+)
+
+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
+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
+See https://plot.ly/python/reference/#streamtube for more information and chart attribute options!
+