Can anyone provide details of how the STREAMLINE plotting function works? The Help for it is quite non-descriptive, and the results of STREAMLINE are often rather confusing.

1) I assume that streamlines should be (as in physics, etc.) curves that are everywhere locally tangent to the vector field (u,v). However, this is often not the case for this function; consider for example streamlines that begin along the y-axis (x=0), in the code

;;----- begin code snippet--------------------
;; set up grid points
gridmin = 0.
gridmax = 2.
ngrid = 15
xgrid = findgen(ngrid)/float(ngrid-1) * (gridmax-gridmin) + gridmin
ygrid = xgrid

;; define vector field: u = x, v = -y
xvecs = rebin(xgrid, ngrid, ngrid)
yvecs = rebin(transpose(-ygrid), ngrid, ngrid)

;; plot streamlines
nParticles = 7
stream = streamline(xvecs, yvecs, xgrid, ygrid, x_streamparticles = nParticles, $
y_streamparticles = nParticles, auto_color=1, rgb_table=34, $
aspect_ratio=1)

;; overplot vectors, whose *tails* are at grid points
vecs = vector(xvecs, yvecs, xgrid, ygrid,/overplot, data_location=0, head_size = 0.5)

end
;; -------------- end of code snippet -------------------

The vector field points vertically downward when x=0, but streamlines are launched at an angle there. Why?

The same code with only a change to nParticles = 15 (or larger) now produces correct behavior at x=0. Why?

(The same issue can be shown by running the example code from the Harris website at https://www.harrisgeospatial.com/docs/Streamlines.html ; add the single line
vec = vector(u, v, x, y, /overplot,/auto_subsample)
at the end, and witness vectors that *cross* streamlines instead of always running tangent to them. Why?

2) What is the function of auto_color=1? The Help says: "Color according to the distance moved by the particle at each point along the streamline." But there is no description here or anywhere about moving particles. Does this mean the code assumes that (u,v) are velocity components? If so, "distance moved by the particle" depends on how long the time step is -- not mentioned. But even if I take this to mean "color proportionally to magnitude of vector field at each drawing step", that is clearly not what is happening, example code above reveals. I don't know what the color is encoding, but it's not vector magnitude.

3) the keyword properties STREAMLINE_NSTEPS and STREAMLINE_STEPSIZE set the "number of steps to take" and "normalized size of each step" in a streamline... but since nowhere are the relationships between streamlines and these "steps" described, nor do we now what sizes are normalized *to*, they're not particularly useful.

4) X/Y_STREAMPARTICLES -- changing this property has odd results. In the example code/figure at top of Harris help page https://www.harrisgeospatial.com/docs/streamline.html , simply changing the number of particles can subtly shift where the attractors are located in this "Van der Pol Oscillator phase portrait". The example graphic there, for example, does *not* show a phase plot centered at (0,0), *but it should* given that xdot and ydot are defined so as both to be odd functions, symmetric about the origin except for a sign flip. Changing the number of stream particles or density of the vector field grid can produce better-centered plots. But we shouldn't be able to shift the figure this way...

I think the STREAMLINE function might be really useful to me, but its behavior and lack of detailed description make it hard to understand!
Thanks,
Nathaniel