Useful Functions¶

Utility Functions
Fields
Calculations
Matplotlib
Mayavi

Utility Functions ¶

Function	Description
`viscid.load_file()`	Load a single file, or glob of a single time series
`viscid.load_files()`	Load multiple files
`viscid.unload_all_files()`	Clear the cache of loaded files
`viscid.interact()`	Stop the program and get an interactive prompt at any point (uses IPython if it’s installed).

Fields ¶

For easy field creation.

Function	Description
`viscid.arrays2field()`	Field from arrays for data and coordinates
`viscid.dat2field()`	Field from data array
`viscid.empty()`	Make an empty field from coordinate arrays
`viscid.full()`	Make an initialized field from coordinate arrays
`viscid.zeros()`	Make an field of 0s from coordinate arrays
`viscid.ones()`	Make an field of 1s from coordinate arrays
`viscid.empty_like()`	Make an empty field like another
`viscid.full_like()`	Make an initialized field like another
`viscid.zeros_like()`	Make a field of 1s like another
`viscid.ones_like()`	Make a field of 0s like another

Calculations ¶

Streamlines and Interpolation ¶

Class	Description
`viscid.calc_streamlines()`	Calculate streamlines
`viscid.interp()`	Interpolation, use kind kwarg for trilinear / nearest neighbor
`viscid.Point`	Collection of hand picked points
`viscid.RectilinearMeshPoints`	Points that can be 2d plotted using [u, :, 0] and [v, 0, :] slices of pts as coordinate arrays
`viscid.Line`	A line between 2 points
`viscid.Spline`	A spline given a series of knots
`viscid.Plane`	A plane defined by an origin and a normal vector
`viscid.Volume`	A Volume of points on a uniform cartesian grid
`viscid.Sphere`	Points on the surface of a sphere
`viscid.SphericalCap`	A cap of points around the pole of a sphere
`viscid.Circle`	Just a circle
`viscid.SphericalPatch`	A rectangular patch on the surface of a sphere

Math ¶

These functions will by accelerated by Numexpr if it is installed. All functions below are also available from the viscid namespace.

Function	Description
`viscid.calculator.calc.add()`	Add two fields
`viscid.calculator.calc.diff()`	Subtract a field from another
`viscid.calculator.calc.mul()`	Multiply two fields
`viscid.calculator.calc.relative_diff()`	Divide the difference by the magnitude
`viscid.calculator.calc.abs_diff()`	Absolute value of the difference
`viscid.calculator.calc.abs_val()`	Absolute value
`viscid.calculator.calc.abs_max()`	Max of the absolute value
`viscid.calculator.calc.abs_min()`	Min of the absolute value
`viscid.calculator.calc.magnitude()`	Magnitude of a `viscid.field.VectorField`
`viscid.calculator.calc.dot()`	Dot product of two `viscid.field.VectorField`
`viscid.calculator.calc.cross()`	Cross product of two `viscid.field.VectorField`
`viscid.calculator.calc.grad()`	Gradient of a `viscid.field.ScalarField`
`viscid.calculator.calc.convective_deriv()`	A dot grad B for vector field A and scalar/vector filed B
`viscid.calculator.calc.div()`	Divergence of a `viscid.field.VectorField`
`viscid.calculator.calc.curl()`	Curl of a `viscid.field.VectorField`
`viscid.calculator.calc.normalize()`	Divide a vector field by its magnitude
`viscid.calculator.calc.project()`	Project one `viscid.field.VectorField` onto another, i.e., a dot b / \|b\|
`viscid.set_in_region()`	Set values in one field from another given a mask
`viscid.calculator.calc.project_vector()`	Project VectorField a onto b in the direction of b, i.e., (a dot b / \|b\|) * (b / \|b\|)
`viscid.project_along_line()`	Project a Vector Field Parallel to a streamline.
`viscid.resample_lines()`	Resample a list of lines to either more or fewer points. With scipy, oversampling can be done with any type of interpolation that `scipy.interpolate.interp1d()` understands.
`viscid.integrate_along_lines()`	Integrate a field along streamlines
`viscid.field.Field.trapz()`	2nd order integration of field
`viscid.field.Field.cumtrapz()`	2nd order indefinite integration of field
`viscid.calc_psi()`	Calculate a 2D flux function
`viscid.calc_beta()`	Calculate plasma beta

Geospace Tools ¶

These functions allow for transforming between geophysical coordinate systems, and adding a magnetic dipole to a field.

Function	Description
`viscid.Cotr()`	Object that facilitates geospace coordinate transformations at a given UT time
`viscid.cotr_transform()`	Transform a vector from one crd system to another at a given UT time
`viscid.get_dipole_moment()`	Get Earth’s dipole moment at a given time in any coordinate system
`viscid.get_dipole_moment_ang()`	Get dipole moment given gsm-tilt and dipole-tilt angles in gse or mhd crds
`viscid.make_dipole()`	Create new dipole vector field to an existing field given dipole moment vector
`viscid.fill_dipole()`	Add dipole vector field to an existing field given dipole moment vector (can be masked)
`viscid.make_spherical_mask()`	Make a spherically shaped mask (useful in conjunction with `viscid.fill_dipole()`)

Magnetosphere Tools ¶

Some tools for dealing with magnetospheric specific things. Refer to Extracting Magnetopause Information for an example

Function	Description
`viscid.get_mp_info()`	Extract magnetopause info (possibly cached)
`viscid.find_mp_edges()`	Find edges of the magnetopause current sheet

Magnetic Topology and Separator Tools ¶

For using the separator tools, you may want to refer to Magnetic Topology.

Function	Description
`viscid.topology2color()`	Turn topology bitmask into colors
`viscid.trace_separator()`	Still in testing Trace a separator line using bisection algorithm
`viscid.get_sep_pts_bisect()`	Still in testing Use bisection algorithm to find one or more separators locations for a seed
`viscid.get_sep_pts_bitor()`	Still in testing Use bitwise-or algorithm to find one or more separators locations for a seed
`viscid.topology_bitor_clusters()`	Use bitwise-or algorithm to find one or more separators in a topology Field

Matplotlib ¶

General Matplotlib Functions ¶

These functions wrap Matplotlib with useful boilerplate type hacks.

Function	Description
`viscid.plot.vpyplot.auto_adjust_subplots()`	Use Matplotlib’s tight layout with some necessary hacks
`viscid.plot.vpyplot.apply_labels()`	Write labels onto a plot similar to a legend, but place the labels next to the data. This adheres to the principle that you shouldn’t make the reader learn a key just to read a single plot.
`viscid.plot.vpyplot.despine()`	Remove some spines to reduce chart clutter, this is the exact same as seaborn’s despine.

2D Matplotlib Plots ¶

These functions wrap Matplotlib with useful boilerplate type hacks.

Function	Description
`viscid.plot.vpyplot.plot()`	Meta function for plotting `viscid.field.Field` objects. This one will automatically delegate to `viscid.plot.vpyplot.plot1d_field()`, `viscid.plot.vpyplot.plot2d_field()`, or `viscid.plot.vpyplot.plot2d_mapfield()`.
`viscid.plot.vpyplot.plot1d_field()`	Line plots of a 1D field.
`viscid.plot.vpyplot.plot2d_field()`	Colored plots (pcolormesh, contour, contourf) of 2D fields
`viscid.plot.vpyplot.plot2d_mapfield()`	Plots on the surface of a sphere (like ionosphere plots)
`viscid.plot.vpyplot.plot_iono()`	make annotated polar plots of ionosphere quantities, this is just a wrapper for plot2d_mapfield that handles small annyoances and annotations
`viscid.plot.vpyplot.plot2d_lines()`	Plot a list of colored lines parallel-projected into 2D
`viscid.plot.vpyplot.plot2d_quiver()`	Plot a `viscid.field.VectorField` using Matplotlib’s quivers.
`viscid.plot.vpyplot.streamplot()`	Plot a `viscid.field.VectorField` using Matplotlib’s streamplot.
`viscid.plot.vpyplot.plot_earth()`	Plot an Earth with black for nightside and white for dayside

3D Matplotlib Plots ¶

These functions wrap Matplotlib in 3D with useful boilerplate type hacks.

Function	Description
`viscid.plot.vpyplot.plot3d_lines()`	Plot a list of colored lines on 3D axes
`viscid.plot.vpyplot.scatter_3d()`	Plot a glyphs on 3D axes

Mayavi is the preferred library for making 3D plots with Viscid. It’s a little unwieldy, but for the moment, it’s still the best Python interface to VTK. Mayavi has two ways to discover its API (the documentation is only marginally helpful). The first is to make the change interactively while using the record feature. The other is to throw import IPython; IPython.embed() into your script and go spelunking. Most Mayavi objects come from Traited VTK, which means they have a print_traits() method. This method will print out all the attributes that you may want to tweak.

Between the example and the functions you see below, you should be able figure out most things without too much hassle.

Note

Installing Mayavi can be tricky. Please read this before attempting to install it.

Mayavi Workarounds ¶

Mayavi has various platform specific bugs. The following functions will try to apply workarounds so that they always give the expected result.

Function	Description
`viscid.plot.vlab.clf()`	Uses some hacks to clear a figure and make sure memory is freed
`viscid.plot.vlab.remove_source()`	Safely remove a specific vtk source (and its memory)
`viscid.plot.vlab.resize()`	default resize is unreliable on OS X / Linux
`viscid.plot.vlab.savefig()`	offscreen rendering hack

Mayavi Wrappers ¶

Chances are that you want to use these functions. They let you make most Mayavi objects from Viscid data structures (i.e., Fields and SeedGens). In addition, all of these functions allow you to specify a Matplotlib colormap for the data, and it picks up the default colormaps from Matplotlib’s rcParams and viscidrc files. How cool is that‽

Function	Description
`viscid.plot.vlab.plot_lines()`	Plot colored lines in 3D
`viscid.plot.vlab.scalar_cut_plane()`	Make a scalar cut plane of a Field or existing Mayavi source
`viscid.plot.vlab.vector_cut_plane()`	Make a vector cut plane of a Field or existing Mayavi source with optional scalar data.
`viscid.plot.vlab.mesh()`	Make a mesh from a 2D array of vertices with optional scalar data
`viscid.plot.vlab.mesh_from_seeds()`	Make a mesh from a Viscid SeedGen object with optional scalar data. Useful for displaying the result of interpolating a field onto a plane or sphere.
`viscid.plot.vlab.streamline()`	Use the interactive Mayavi (VTK) streamline tracer with optional scalar data
`viscid.plot.vlab.iso_surface()`	Make volumetric contours of a Field or existing Mayavi source
`viscid.plot.vlab.points3d()`	Plot a list of points
`viscid.plot.vlab.quiver3d()`	Plot a list of vector arrows with optional scalar data
`viscid.plot.vlab.colorbar()`	Wrap mayavi.mlab.colorbar, then change the colormap if any `viscid.plot.vlab.apply_cmap()` kwargs are provided
`viscid.plot.vlab.scalarbar()`	Wrap mayavi.mlab.scalarbar, then change the colormap if any `viscid.plot.vlab.apply_cmap()` kwargs are provided
`viscid.plot.vlab.vectorbar()`	Wrap mayavi.mlab.vectorbar, then change the colormap if any `viscid.plot.vlab.apply_cmap()` kwargs are provided
`viscid.plot.vlab.fancy_axes()`	Make axes with 3 shaded walls and a grid similar to what matplotlib and paraview have
`viscid.plot.vlab.axes()`	Wrap mayavi.mlab.axes
`viscid.plot.vlab.xlabel()`	Wrap mayavi.mlab.xlabel
`viscid.plot.vlab.ylabel()`	Wrap mayavi.mlab.ylabel
`viscid.plot.vlab.zlabel()`	Wrap mayavi.mlab.zlabel
`viscid.plot.vlab.title()`	Wrap mayavi.mlab.title
`viscid.plot.vlab.outline()`	Wrap mayavi.mlab.outline
`viscid.plot.vlab.orientation_axes()`	Wrap mayavi.mlab.orientation_axes, adds the little xyz arrows
`viscid.plot.vlab.view()`	Wrap mayavi.mlab.view, adjusts the focal point, distance, and various angles of the camera

Mayavi Plots ¶

These functions make some commonly used objects.

Function	Description
`viscid.plot.vlab.plot_ionosphere()`	Plot an ionospheric Field in 3D on the surface of a sphere
`viscid.plot.vlab.plot_blue_marble()`	Plot an Earth using the blue marble NASA image
`viscid.plot.vlab.plot_earth_3d()`	Plot an Earth with black for nightside and white for dayside

Mayavi Pipeline ¶

Here are some functions to quickly bring Viscid datastructures into the Mayavi pipeline.

Function	Description
`viscid.plot.vlab.add_source()`	Given a VTKDataSource, add it to a figure
`viscid.plot.vlab.add_lines()`	Given a list of lines, add them to a figure as a data source
`viscid.plot.vlab.add_field()`	Given a `viscid.field.Field`, add it to a figure as a data source
`viscid.plot.vlab.insert_filter()`	Insert a filter above a module_manager.
`viscid.plot.vlab.apply_cmap()`	Apply a colormap to an existing Mayavi object. This also lets you quickly rescale the limits on the colorbar, or switch to a log scale.