streamtracer¶

streamtracer is a python package for rapid streamline tracing. It is a wrapper to compiled fortran code that does the heavy lifting, and is therefore relatively fast.

To use, create a streamtracer.StreamTracer object

import numpy as np
from streamtracer import StreamTracer, VectorGrid

nsteps = 10000
step_size = 0.1
tracer = StreamTracer(nsteps, step_size)

and a streamtracer.VectorGrid

field = np.ones((10, 10, 10, 3))
grid_spacing = [1, 2, 1]
grid = VectorGrid(field, grid_spacing)

This can then be used to trace lines through a 3D cartesian vector field

seeds = np.array([[0, 0, 0], [0, 0, 1]])
tracer.trace(seeds, grid)

and the traced field lines can be accessed via. the .xs attribute

print(f'Number of traced lines: {len(tracer.xs)}')
line_lengths = [len(x) for x in tracer.xs]
print(f'Line lengths: {line_lengths}')

Number of traced lines: 2
Line lengths: [158, 141]

For more information see the streamtracer API docs.

Boundary handling¶

When the stream tracer steps outside the boundary of the grid, the first point outside the grid is saved in the traced stream line.

Installing¶

In theory, it should be possible to build and install streamtracer in one go with:

pip install streamtracer

Note that this requires a fortran compiler; currently known to work is gfortran. If you have problems installing, please open an issue at https://github.com/dstansby/streamtracer/issues

Code reference¶

streamtracer Package

Changelog¶

1.1.2¶

Fixed the example code listed above.

1.1.1¶

Fixed wheel building to use the oldest supported version of numpy for each major version of python. This fixes errors like “module compiled against API version 0xe but this version of numpy is 0xd” that were in the 1.1.0 wheels.

1.1.0¶

Fixed handling of steps going out of bounds. Previously, in the forward direction a single step would be saved out of bounds, but in the backwards direction the streamline ended before going out of bounds. Now both the forward and negative directions both save a single out of bounds step in each stream line.
Linux and macOS binary distributions (wheels) are now automatically built and uploaded, meaning you should no longer need a FORTRAN compiler installed locally to use streamtracer.
Minor performance and memory improvements have been made.

1.0.1¶

Fix compilation issues on MacOS Big Sur.

1.0.0¶

Nothing major, just re-versioning to a stable release number.

0.1.2¶

Make sure to install numpy before trying to install streamtracer.

0.1.1¶

Added validation for the max_steps argument to StreamTracer.

0.1.0¶

First streamtracer release.

Indices and tables¶

streamtracer Package