viscid.seed module

Helpers to generate seed points for streamlines

viscid.seed.to_seeds(pts)

Try to turn anything into a set of seeds

Parameters:points (ndarray or list) – should look like something that np.array(points) can turn to an Nx3 array of xyz points. This can be 3xN so long as N != 3.

class viscid.seed.SeedGen(cache=False, dtype=None, fill_holes=True)

Bases: object

All about seeds

These objects are good for defining the root points of streamlines or locations for interpolation.

• For Developers

  • Mandatory

    Subclasses must override

    • get_nr_points(): get total number of seeds
    • get_uv_shape(): get the shape of the ndarray of uv mesh coordinates IF there exists a 2D representation of the seeds
    • get_local_shape(): get the shape of the ndarray of local coordinates
    • uv_to_local(): transform 2d representation to local representation
    • to_3d(): transform an array in local coordinates to 3D space. Should return a 3xN ndarray.
    • to_local(): transform a 3xN ndarray to an ndarray of coordinates in local space. It’s ok to raise NotImplementedError.
    • _make_local_points(): Make an ndarray that is used in _make_3d_points()
    • _make_uv_axes(): Make axes for 2d mesh representation, i.e., matches uv_shape
    • _make_local_axes(): Make a tuple of arrays with lengths that match local_shape. It’s ok to raise NotImplementedError if the local representation has no axes.

  • Optional

    Subclasses may override

    • _make_3d_points(): By default, this is a combination of _make_local_points() and to_3d(). It can be overridden if there is a more efficient way te get points in 3d.
    • iter_points(): If a seed generator can be made lazy, then this should return an iterator that yields (x, y, z) points.
    • get_rotation(): This should return an orthonormal rotation matrix if there is some rotation required to go from local coordinates to 3D space.
    • as_mesh()
    • as_uv_coordinates()
    • as_local_coordinates()
    • wrap_field()

  • Off Limits

    Don’t override unless you know what you’re doing

    • get_points()

• For Users

  • 3D

    These attributes give the seed points in 3D (xyz) space

    • nr_points
    • get_points()
    • iter_points()
    • to_3d()

  • Generator Specific

    There is also the concept of local points, which are points that are meaningful for the specific SeedGen subclass. For example, for the Sphere subclass, local points are labled with (theta, phi) on the surface of the sphere. As such, wrap_field() can be used to facilitate wrapping the result of trilin_interp() for easy plotting.

    • uv_shape
    • local_shape
    • uv_to_local()
    • to_local()
    • as_mesh()
    • as_uv_coordinates()
    • as_local_coordinates()
    • wrap_field()

arr2mesh(arr, fill_holes=<class 'viscid.NOT_SPECIFIED'>)

as_local_coordinates()

Make Coordinates for the local representation

as_mesh(fill_holes=<class 'viscid.NOT_SPECIFIED'>)

Make a 3xUxV array that describes a 3D mesh surface

as_uv_coordinates()

Make Coordinates for the uv representation

dtype = None

fill_holes = None

get_local_shape(**kwargs)

get_nr_points(**kwargs)

get_points(**kwargs)

Get a 3xN ndarray of N xyz points

get_rotation()

Make a rotation matrix to go local -> real 3D space

get_uv_shape(**kwargs)

iter_points(**kwargs)

Make an iterator that yields (x, y, z) points

This can be overridden in a subclass if it’s more efficient to iterate than a call to _make_points(). Calling iter_points should make an effort to be the fastest way to iterate through the points, regardless of caching.

Note

In Cython, it seems to take twice the time to iterate over a generator than to use a for loop over indices of an array, but only if the array already exists.

local_extent

Try to get low and high coordnate values of local points

Raises:NotImplementedError – If subclass can’t make local mesh

local_shape

Shape of local representation of seeds

local_to_3d(pts_local)

Transform points from the seed coordinate space to 3d

Parameters:pts_local (ndarray) – An array of points in local crds Returns:3xN ndarray of N xyz points

nr_points

points(**kwargs)

Alias for get_points()

to_local(pts_3d)

Transform points from 3d to the seed coordinate space

Parameters:pts_local (ndarray) – A 3xN array of N points in 3d Returns:ndarray similar in shape to self.local_shape

uv_extent

Try to get low and high coordnate values of uv points

Raises:NotImplementedError – If subclass can’t make uv mesh

uv_shape

Shape of uv representation of seeds

uv_to_3d(pts_uv)

uv_to_local(pts_uv)

wrap_field(data, name='NoName', fldtype='scalar', **kwargs)

Wrap an ndarray into a field in the local representation

wrap_mesh(*arrs, **kwargs)

class viscid.seed.Point(pts, local_crds=None, cache=False, dtype=None, **kwargs)

Bases: viscid.seed.SeedGen

Collection of points

as_local_coordinates()

Make Coordinates for the local representation

get_local_shape(**kwargs)

get_nr_points(**kwargs)

to_3d(pts_local)

to_local(pts_3d)

Transform points from 3d to the seed coordinate space

Parameters:pts_local (ndarray) – A 3xN array of N points in 3d Returns:ndarray similar in shape to self.local_shape

class viscid.seed.MeshPoints(pts, cache=False, dtype=None, **kwargs)

Bases: viscid.seed.SeedGen

Generic points with 2d mesh information

arr2mesh(arr, fill_holes=<class 'viscid.NOT_SPECIFIED'>)

as_local_coordinates()

Make Coordinates for the local representation

as_mesh(fill_holes=<class 'viscid.NOT_SPECIFIED'>)

Make a 3xUxV array that describes a 3D mesh surface

as_uv_coordinates()

Make Coordinates for the uv representation

get_local_shape(**kwargs)

get_nr_points(**kwargs)

get_uv_shape(**kwargs)

to_3d(pts_local)

to_local(pts_3d)

Transform points from 3d to the seed coordinate space

Parameters:pts_local (ndarray) – A 3xN array of N points in 3d Returns:ndarray similar in shape to self.local_shape

uv_to_local(pts_uv)

class viscid.seed.RectilinearMeshPoints(pts, mesh_axes='xy', cache=False, dtype=None, **kwargs)

Bases: viscid.seed.MeshPoints

Generic seeds with 2d rect mesh topology

class viscid.seed.Line(p0=(0, 0, 0), p1=(1, 0, 0), n=20, cache=False, dtype=None, **kwargs)

Bases: viscid.seed.SeedGen

A line of seed points

as_local_coordinates()

Make Coordinates for the local representation

as_mesh(fill_holes=<class 'viscid.NOT_SPECIFIED'>)

Make a 3xUxV array that describes a 3D mesh surface

as_uv_coordinates()

Make Coordinates for the uv representation

get_local_shape(**kwargs)

get_nr_points(**kwargs)

get_uv_shape(**kwargs)

to_3d(pts_local)

to_local(pts_3d)

Transform points from 3d to the seed coordinate space

Parameters:pts_local (ndarray) – A 3xN array of N points in 3d Returns:ndarray similar in shape to self.local_shape

uv_to_local(pts_uv)

class viscid.seed.Spline(knots, n=-5, splprep_kw=None, cache=False, dtype=None, **kwargs)

Bases: viscid.seed.SeedGen

A spline of seed points

as_local_coordinates()

Make Coordinates for the local representation

as_mesh(fill_holes=<class 'viscid.NOT_SPECIFIED'>)

Make a 3xUxV array that describes a 3D mesh surface

as_uv_coordinates()

Make Coordinates for the uv representation

get_local_shape(**kwargs)

get_nr_points(**kwargs)

get_uv_shape(**kwargs)

to_3d(pts_local, **kwargs)

to_local(pts_3d)

Transform points from 3d to the seed coordinate space

Parameters:pts_local (ndarray) – A 3xN array of N points in 3d Returns:ndarray similar in shape to self.local_shape

uv_to_local(pts_uv)

class viscid.seed.Plane(p0=(0, 0, 0), pN=(0, 0, 1), pL=(1, 0, 0), len_l=2, len_m=2, nl=20, nm=20, NL_are_vectors=True, cache=False, dtype=None, **kwargs)

Bases: viscid.seed.SeedGen

A plane of seed points

arr2mesh(arr, fill_holes=<class 'viscid.NOT_SPECIFIED'>)

as_local_coordinates()

Make Coordinates for the local representation

as_mesh(fill_holes=<class 'viscid.NOT_SPECIFIED'>)

Make a 3xUxV array that describes a 3D mesh surface

as_uv_coordinates()

Make Coordinates for the uv representation

get_local_shape()

get_nr_points(**kwargs)

get_rotation()

Get rotation from lmn -> xyz

To transform xyz -> lmn, transpose the result since it’s an orthogonal matrix.

Note

Remember that the p0 offset (the center of the plane) is not done with the rotation.

Returns:3x3 ndarray

Example

>>> # Transform a set of points from lmn coordinates to xyz
>>> import numpy as np
>>> import viscid
>>>
>>> # p0 is the origin of the plane
>>> p0 = np.array([0, 0, 0]).reshape(-1, 1)
>>> plane = viscid.Plane(p0=p0, pN=(1, 1, 0),
>>>                      pL=(1, -1, 0),
>>>                      len_l=2.0, len_m=2.0)
>>> lmn_to_xyz = plane.get_rotation()
>>>
>>> # make 10 random points in lmn coorinates
>>> lmn = 2 * np.random.rand(3, 10) - 1
>>> lmn[2] = 0.0
>>> xyz = p0 + np.dot(lmn_to_xyz, lmn)
>>>
>>> from viscid.plot import vlab
>>> vlab.mesh_from_seeds(plane)
>>> vlab.points3d(xyz[0], xyz[1], xyz[2])
>>> vlab.show()

>>> # Transform vector compenents from xyz to lmn
>>> import numpy as np
>>> import viscid
>>>
>>> x = np.linspace(-1, 1, 32)
>>> y = np.linspace(-1, 1, 32)
>>> z = np.linspace(-1, 1, 32)
>>> Bxyz = viscid.zeros([x, y, z], center='node',
>>>                     nr_comps=3, layout="interlaced")
>>> Bxyz['x'] = 1.0
>>>
>>> plane = viscid.Plane(p0=[0, 0, 0], pN=[1, 1, 0],
>>>                      pL=[1, -1, 1],
>>>                      len_l=0.5, len_m=0.5)
>>> vals = viscid.interp_trilin(Bxyz, plane)
>>> B_interp = plane.wrap_field(vals, fldtype='vector',
>>>                             layout='interlaced')
>>> xyz_to_lmn = plane.get_rotation().T
>>> Blmn = np.einsum("ij,lmj->lmi", xyz_to_lmn, B_interp)
>>> Blmn = B_interp.wrap(Blmn)
>>>
>>> # use xyz to show in 3d via mayavi
>>> from viscid.plot import vlab
>>> verts, s = plane.wrap_mesh(Blmn['z'].data)
>>> vlab.mesh(verts[0], verts[1], verts[2], scalars=s)
>>> verts, vx, vy, vz = plane.wrap_mesh(B_interp['x'].data,
>>>                                      B_interp['y'].data,
>>>                                      B_interp['z'].data)
>>> vlab.quiver3d(verts[0], verts[1], verts[2], vx, vy, vz)
>>> vlab.show()
>>>
>>> # use lmn to show in-plane / out-of-plane
>>> from viscid.plot import vpyplot as vlt
>>> from matplotlib import pyplot as plt
>>> vlt.plot(Blmn['z'])  # z means n here
>>> vlt.plot2d_quiver(Blmn)
>>> plt.show()

get_uv_shape()

to_3d(pts_local)

to_local(pts_3d)

Transform points from 3d to the seed coordinate space

Parameters:pts_local (ndarray) – A 3xN array of N points in 3d Returns:ndarray similar in shape to self.local_shape

uv_to_local(pts_uv)

class viscid.seed.Volume(xl=(-1, -1, -1), xh=(1, 1, 1), n=(20, 20, 20), cache=False, dtype=None, **kwargs)

Bases: viscid.seed.SeedGen

A volume of seed points

Defined by two opposite corners of a box in 3D

arr2mesh(arr, fill_holes=<class 'viscid.NOT_SPECIFIED'>)

as_local_coordinates()

Make Coordinates for the local representation

as_mesh(fill_holes=<class 'viscid.NOT_SPECIFIED'>)

Make a 3xUxV array that describes a 3D mesh surface

as_uv_coordinates()

Make Coordinates for the uv representation

get_local_shape(**kwargs)

get_nr_points(**kwargs)

get_uv_shape(**kwargs)

iter_points(**kwargs)

Make an iterator that yields (x, y, z) points

This can be overridden in a subclass if it’s more efficient to iterate than a call to _make_points(). Calling iter_points should make an effort to be the fastest way to iterate through the points, regardless of caching.

Note

In Cython, it seems to take twice the time to iterate over a generator than to use a for loop over indices of an array, but only if the array already exists.

to_3d(pts_local)

to_local(pts_3d)

Transform points from 3d to the seed coordinate space

Parameters:pts_local (ndarray) – A 3xN array of N points in 3d Returns:ndarray similar in shape to self.local_shape

uv_to_local(pts_uv)

class viscid.seed.Sphere(p0=(0, 0, 0), r=0.0, pole=(0, 0, 1), ntheta=20, nphi=20, thetalim=(0, 180.0), philim=(0, 360.0), roll=0.0, crd_system=None, theta_endpoint='auto', phi_endpoint='auto', pole_is_vector=True, theta_phi=False, cache=False, dtype=None, **kwargs)

Bases: viscid.seed.SeedGen

Make seeds on the surface of a sphere

arr2mesh(arr, fill_holes=<class 'viscid.NOT_SPECIFIED'>)

as_local_coordinates()

Make Coordinates for the local representation

as_mesh(fill_holes=<class 'viscid.NOT_SPECIFIED'>)

Make a 3xUxV array that describes a 3D mesh surface

as_uv_coordinates()

Make Coordinates for the uv representation

get_local_shape(**kwargs)

get_nr_points(**kwargs)

get_rotation()

Make a rotation matrix to go local -> real 3D space

get_uv_shape(**kwargs)

periodic

pt_bnds

to_3d(pts_local)

to_local(pts_3d)

Transform points from 3d to the seed coordinate space

Parameters:pts_local (ndarray) – A 3xN array of N points in 3d Returns:ndarray similar in shape to self.local_shape

uv_to_local(pts_uv)

class viscid.seed.SphericalCap(angle0=0.0, angle=90.0, theta_endpoint=[True, False], **kwargs)

Bases: viscid.seed.Sphere

A spherical cone or cap of seeds

Defined by a center, and a point indicating the direction of the cone, and the half angle of the cone.

This is mostly a wrapper for Sphere that sets thetalim, but it also does some special stuff when wrapping meshes to remove the last theta value so that the cap isn’t closed at the bottom.

angle

angle0

to_local(pts_3d)

Transform points from 3d to the seed coordinate space

Parameters:pts_local (ndarray) – A 3xN array of N points in 3d Returns:ndarray similar in shape to self.local_shape

class viscid.seed.Circle(n=20, endpoint=None, **kwargs)

Bases: viscid.seed.SphericalCap

A circle of seeds

Defined by a center and a point normal to the plane of the circle

endpoint

n

to_local(pts_3d)

Transform points from 3d to the seed coordinate space

Parameters:pts_local (ndarray) – A 3xN array of N points in 3d Returns:ndarray similar in shape to self.local_shape

class viscid.seed.SphericalPatch(p0=(0, 0, 0), p1=(0, 0, 1), max_alpha=45, max_beta=45, nalpha=20, nbeta=20, roll=0.0, r=0.0, p1_is_vector=True, cache=False, dtype=None, **kwargs)

Bases: viscid.seed.SeedGen

Make a rectangular (in theta and phi) patch on a sphere

arr2mesh(arr, fill_holes=<class 'viscid.NOT_SPECIFIED'>)

as_local_coordinates()

Make Coordinates for the local representation

as_mesh(fill_holes=<class 'viscid.NOT_SPECIFIED'>)

Make a 3xUxV array that describes a 3D mesh surface

as_uv_coordinates()

Make Coordinates for the uv representation

get_local_shape(**kwargs)

get_nr_points(**kwargs)

get_rotation()

Make a rotation matrix to go local -> real 3D space

get_uv_shape(**kwargs)

to_3d(pts_local)

to_local(pts_3d)

Transform points from 3d to the seed coordinate space

Parameters:pts_local (ndarray) – A 3xN array of N points in 3d Returns:ndarray similar in shape to self.local_shape

uv_to_local(pts_uv)

class viscid.seed.PolarIonosphere(*args, **kwargs)

Bases: viscid.seed.Sphere

Place holder for future seed to cover N+S poles

to_local(**kwargs)

Transform points from 3d to the seed coordinate space

Parameters:pts_local (ndarray) – A 3xN array of N points in 3d Returns:ndarray similar in shape to self.local_shape