viscid.cython.streamline module

All streamlines all the time

Calculate streamlines of a vector field on as many processors as your heart desires. The only function you need here is streamlines(); everything else is for fused types (templates) or other cython performance considerations.

Note

When nr_procs > 1, fields are shared to child processes using a global variable so that on *nix there is no need to picklel and copy the entire field. This will only work on *nix, and I have absolutely no idea what will happen on Windows.

viscid.cython.streamline.calc_streamlines()

Trace streamlines

Warning

For streamlines that reach max_length or max_t, the line segments at the ends will be trimmed. This may be confusing when using a non-adaptive integrator (ds will be different for the 1st and last segments). Bear this in mind when doing math on the result.

Parameters:
  • vfield – A VectorField with 3 components, If this field is not 3D, then vfield.atleast_3d() is called
  • seed – can be a Seeds instance or a Coordinates instance, or anything that exposes an iter_points method
  • nr_procs – how many processes for streamlines (>1 only works on *nix systems)
  • force_subprocess (bool) – always calc streamlines in a separate process, even if nr_procs == 1
  • chunk_factor (int) – Valid range is [1, nr_seeds // nr_procs]. 1 indicates a single chunk per process; use this for perfectly balanced streamlines. nr_seeds // nr_procs indicates one chunk per seed; this solves load balancing, but the overhead of assembling results makes this undesirable. Start with 1 and bump this up if load balancing is still an issue.
  • wrap (bool) – if true, then call seed.wrap_field on topology
  • **kwargs – more arguments for streamlines
Keyword Arguments:
 
  • ds0 (float) – initial spatial step for streamlines (if 0.0, it will be ds0_frac * the minimum d[xyz])
  • ds0_frac (float) – If an absolute spatial step ds0 is not given, then it will be set to ds0_frac * min_dx where min_dx is the smallest dimenstion of the smallest grid cell of the vfield. Defaults to 0.5.
  • ibound (float) – Inner boundary as distance from (0, 0, 0)
  • obound0 (array-like) – lower corner of outer boundary (x, y, z)
  • obound1 (array-like) – upper corner of outer boundary (x, y, z)
  • obound_r (float) – Outer boundary as distance from (0, 0, 0)
  • maxit (int) – maximum number of line segments
  • max_length (float) – maximum streamline length (int ds)
  • max_t (float) – max value for t (int ds / v). I.e., stop a streamline after a fluid element travels dt along a streamline. This has no obvious use for mag field lines.
  • stream_dir (int) – one of DIR_FORWARD, DIR_BACKWARD, DIR_BOTH
  • output (int) – which output to provide, one of OUTPUT_STREAMLINE, OUTPUT_TOPOLOGY, or OUTPUT_BOTH
  • method (int) – integrator, one of EULER1, RK2, RK4, EULER1a (adaptive), RK12 (adaptive, midpoint), RK45 (adaptive, Fehlberg). Note that sometimes RK45 is faster than lower order adaptive methods since it can take much larger step sizes
  • max_error (float) – max allowed error between methods for adaptive integrators. This should be as a fraction of ds (i.e., between 0 and 1). The default value is 4e-2 for euler1a, 1.5e-2 for rk12, and 1e-5 for rk45.
  • smallest_ds (float) – smallest absolute spatial step. If not set then smallest_ds = smallest_ds_frac * ds0
  • largest_ds (float) – largest absolute spatial step. If not set then largest_ds = largest_ds_frac * ds0
  • smallest_ds_frac (float) – smallest spatial step as fraction of ds0
  • largest_ds_frac (float) – largest spatial step as fraction of ds0
  • topo_style (str) – how to map end point bitmask to a topology. ‘msphere’ means map to TOPOLOGY_MS_* and ‘generic’ means leave topology as a bitmask of END_*
Returns:

(lines, topo), either can be None depending on output

  • lines: list of nr_streams ndarrays, each ndarray has shape (3, nr_points_in_stream). The nr_points_in_stream can be different for each line
  • topo: ndarray with shape (nr_streams,) of topology bitmask with values depending on the topo_style
viscid.cython.streamline.streamlines()

Trace streamlines

Warning

For streamlines that reach max_length or max_t, the line segments at the ends will be trimmed. This may be confusing when using a non-adaptive integrator (ds will be different for the 1st and last segments). Bear this in mind when doing math on the result.

Parameters:
  • vfield – A VectorField with 3 components, If this field is not 3D, then vfield.atleast_3d() is called
  • seed – can be a Seeds instance or a Coordinates instance, or anything that exposes an iter_points method
  • nr_procs – how many processes for streamlines (>1 only works on *nix systems)
  • force_subprocess (bool) – always calc streamlines in a separate process, even if nr_procs == 1
  • chunk_factor (int) – Valid range is [1, nr_seeds // nr_procs]. 1 indicates a single chunk per process; use this for perfectly balanced streamlines. nr_seeds // nr_procs indicates one chunk per seed; this solves load balancing, but the overhead of assembling results makes this undesirable. Start with 1 and bump this up if load balancing is still an issue.
  • wrap (bool) – if true, then call seed.wrap_field on topology
  • **kwargs – more arguments for streamlines
Keyword Arguments:
 
  • ds0 (float) – initial spatial step for streamlines (if 0.0, it will be ds0_frac * the minimum d[xyz])
  • ds0_frac (float) – If an absolute spatial step ds0 is not given, then it will be set to ds0_frac * min_dx where min_dx is the smallest dimenstion of the smallest grid cell of the vfield. Defaults to 0.5.
  • ibound (float) – Inner boundary as distance from (0, 0, 0)
  • obound0 (array-like) – lower corner of outer boundary (x, y, z)
  • obound1 (array-like) – upper corner of outer boundary (x, y, z)
  • obound_r (float) – Outer boundary as distance from (0, 0, 0)
  • maxit (int) – maximum number of line segments
  • max_length (float) – maximum streamline length (int ds)
  • max_t (float) – max value for t (int ds / v). I.e., stop a streamline after a fluid element travels dt along a streamline. This has no obvious use for mag field lines.
  • stream_dir (int) – one of DIR_FORWARD, DIR_BACKWARD, DIR_BOTH
  • output (int) – which output to provide, one of OUTPUT_STREAMLINE, OUTPUT_TOPOLOGY, or OUTPUT_BOTH
  • method (int) – integrator, one of EULER1, RK2, RK4, EULER1a (adaptive), RK12 (adaptive, midpoint), RK45 (adaptive, Fehlberg). Note that sometimes RK45 is faster than lower order adaptive methods since it can take much larger step sizes
  • max_error (float) – max allowed error between methods for adaptive integrators. This should be as a fraction of ds (i.e., between 0 and 1). The default value is 4e-2 for euler1a, 1.5e-2 for rk12, and 1e-5 for rk45.
  • smallest_ds (float) – smallest absolute spatial step. If not set then smallest_ds = smallest_ds_frac * ds0
  • largest_ds (float) – largest absolute spatial step. If not set then largest_ds = largest_ds_frac * ds0
  • smallest_ds_frac (float) – smallest spatial step as fraction of ds0
  • largest_ds_frac (float) – largest spatial step as fraction of ds0
  • topo_style (str) – how to map end point bitmask to a topology. ‘msphere’ means map to TOPOLOGY_MS_* and ‘generic’ means leave topology as a bitmask of END_*
Returns:

(lines, topo), either can be None depending on output

  • lines: list of nr_streams ndarrays, each ndarray has shape (3, nr_points_in_stream). The nr_points_in_stream can be different for each line
  • topo: ndarray with shape (nr_streams,) of topology bitmask with values depending on the topo_style