streamline

# Streamline (Gs) module

class vcs.streamline.Gs(Gs_name, Gs_name_src='default')

The streamline graphics method displays a streamline plot of a 2D streamline field. A streamline is a path that a massless particle takes in a vector field. Streamlines are computed through numerical integration. Vcs can draw regular streamlines or evenly spaced streamlines.

This class is used to define an streamline table entry used in VCS, or it can be used to change some or all of the streamline attributes in an existing streamline table entry.

Useful Functions:

# Constructor
a=vcs.init()
# Show predefined streamline graphics methods
a.show('streamline')
# Show predefined VCS line objects
a.show('line')
# Change the VCS color Map
a.setcolormap("AMIP")
# Plot 's1', and 's2' with streamline 'v' and 'default' template
a.streamline(s1, s2, v,'default')
# Updates the VCS Canvas at user's request
a.update()

Make a Canvas object to work with:

a=vcs.init()

Create a new instance of streamline:

# Copies content of 'quick' to 'new'
vc=a.createstreamline('new','quick')
# Copies content of 'default' to 'new'
vc=a.createstreamline('new')

Modify an existing streamline:

vc=a.getstreamline('AMIP_psl')

Overview of streamline attributes:

• List all attributes:

  # Will list all the streamline attribute values
  vc.list()
  

• Set axis attributes:

  # Can only be 'linear'
  vc.projection='linear'
  lon30={-180:'180W',-150:'150W',0:'Eq'}
  vc.xticlabels1=lon30
  vc.xticlabels2=lon30
  # Will set them both
  vc.xticlabels(lon30, lon30)
  vc.xmtics1=''
  vc.xmtics2=''
  # Will set them both
  vc.xmtics(lon30, lon30)
  vc.yticlabels1=lat10
  vc.yticlabels2=lat10
  # Will set them both
  vc.yticlabels(lat10, lat10)
  vc.ymtics1=''
  vc.ymtics2=''
  # Will set them both
  vc.ymtics(lat10, lat10)
  vc.datawc_y1=-90.0
  vc.datawc_y2=90.0
  vc.datawc_x1=-180.0
  vc.datawc_x2=180.0
  # Will set them all
  vc.datawc(-90, 90, -180, 180)
  xaxisconvert='linear'
  yaxisconvert='linear'
  # Will set them both
  vc.xyscale('linear', 'area_wt')
  

• Specify the line style:

  # Same as vc.line='solid'
  vc.line=0
  # Same as vc.line='dash'
  vc.line=1
  # Same as vc.line='dot'
  vc.line=2
  # Same as vc.line='dash-dot'
  vc.line=3
  # Same as vc.line='long-dot'
  vc.line=4
  

• Specify the line color of the streamlines:

  # Color range: 16 to 230, default line color is black
  vc.linecolor=16
  # Width range: 1 to 100, default size is 1
  vc.linewidth=1
  

• Specify the streamline reference:

  # Can be an integer or float
  vc.reference=4
  

property closedloopmaximumdistance

Integrator type. Can be 0 for Runge-Kutta 2, 1 for Runge-Kutta 4 and 2 for Runge-Kutta 4-5. Default is 1 - Runge-Kutta 4 for evenly spaced streamlines and 2 - Runge-Kutta 4-5 for regular streamlines.

property coloredbyvector

Number of glyphs per streamline. The default is one, in which case the glyph is placed at the position where the streamline was seeded. Otherwise glyphs are placed equally spaced along the streamline. Not all streamlines will contain all glyphs as streamlines have different lenghts.

property evenlyspaced

Number of random seeds for starting streamlines. Default is 500. Not used for evenly spaced streamlines.

property ext_1

Turns on extensions arrows for values before the first level

property ext_2

Turns on extensions arrows for values after the last level

property filledglyph

If true streamlines are colored by vector magnitude. The mapping between vector magnitude and colors is controlled by levels, ext_1, ext_2 and fillareacolors. If false, streamlines have only one color linecolor.

property glyphbasefactor

Do we draw the arrow glyph filled or we draw only edges

property glyphscalefactor

The constant multiplier used to scale the glyph base for the arrow showing the flow. The default is 0.75 for which the width of the arrow is 0.75 of its height.

property initialsteplength

When using the Runge-Kutta 4-5 integrator, this property specifies the minimum integration step size. Default is 0.1 Not used for evenly spaced streamlines. Expressed in integrationstepunit.

property integrationdirection

Integration stepunit. Can be 1 - length or 2 - cell length. Default is 2 - cell length.

property integrationstepunit

This property specifies the initial integration step size expressed in integrationstepunit. For non-adaptive integrators (Runge-Kutta 2 and Runge-Kutta 4), it is fixed (always equal to this initial value) throughout the integration. For an adaptive integrator (Runge-Kutta 4-5), the actual step size varies such that the numerical error is less than a specified threshold. Default is 0.2

property integratortype

Integration direction. Can be 0 - forward, 1 - backward or 2 - both. Default is 2 - both. For evenly spaced streamlines integration direction is always 2.

property levels

Sets the levels on a graphic method, optionally turns on/off extensions arrows

property maximumerror

The constant multiplier used to scale the glyph showing the direction of the flow. One represents the diagonal of the bounding box of the dataset. Default value is 0.01

property maximumsteplength

This property specifies the maximum number of steps, beyond which streamline integration is terminated. Default is 200.

property maximumsteps

This property specifies the maximum streamline length (i.e., physical arc length), beyond which line integration is terminated. This is specified as a percentage of the diagonal of the dataset. The default is 0.25.

property maximumstreamlinelength

This property specifies the terminal speed, below which particle advection/integration is terminated.

property minimumsteplength

When using the Runge-Kutta 4-5 integrator, this property specifies the maximum integration step size. Default is 0.5 Not used for evenly spaced streamlines. Expressed in integrationstepunit.

property numberofseeds

Position of the start seed. Used only for evenly spaced streamlines. By default is set to None which is taken to mean the middle of the domain.

property reference

Display evenly spaced streamlines.

script(script_filename=None, mode=None)

Saves out a copy of the streamline graphics method, in JSON or Python format to a designated file.

Note

If the the filename has a ‘.py’ at the end, it will produce a Python script. If no extension is given, then by default a .json file containing a JSON serialization of the object’s data will be produced.

Warning

VCS Scripts Deprecated. SCR script files are no longer generated by this function.

Example

>>> a=vcs.init()
>>> ex=a.getstreamline()
>>> ex.script('filename.py') # append to 'filename.py'
>>> ex.script('filename','w') # make/overwrite 'filename.json'

Parameters

• script_filename (str) – Output name of the script file. If no extension is specified, a .json object is created.

• mode (str) – Either ‘w’ for replace, or ‘a’ for append. Defaults to ‘a’, if not specified.

property separatingdistance

If the current streamline gets closer than separatingdistance * separatingdistanceratio to other streamlines the current streamline is terminated.

property separatingdistanceratio

Maximum distance between two points that form a closed loop. Used only for evenly spaced streamlines. Should be set about the same as self.initialsteplength. Expressed in integrationstepunit.

setLineAttributes(line)

Set attributes linecolor, linewidth and linetype from line l. l can be a line name defined in vcs.elements or a line object

property startseed

Separating distance between equaly spaced streamlines at seeding time. It is expressed in integrationstepunit.

property terminalspeed

This property specifies the maximum error (for Runge-Kutta 4-5) tolerated throughout streamline integration. The Runge-Kutta 4-5 integrator tries to adjust the step size such that the estimated error is less than this threshold. Not used for evenly spaced streamlines.