spacepy.pybats

Module for reading, manipulating, and visualizing BATS-R-US and SWMF output.

For more information on the SWMF, please visit the Center for Space Environment Modeling.

For additional documentation PyBats - SWMF & BATS-R-US Analysis Tools

Copyright ©2010 Los Alamos National Security, LLC.

Submodules

bats	A PyBats module for handling input, output, and visualization of binary SWMF output files taylored to BATS-R-US-type data.
batsmath	Functions for common math problems such as derivatives, etc.
dgcpm	The PyBats submodule for handling input and output for the Dynamic Global Core Plasma Model (DGCPM), a plasmasphere module of the SWMF.
dipole	Some functions for the generation of a dipole field.
gitm	PyBats submodule for handling input/output for the Global Ionosphere-Thermosphere Model (GITM), one of the choices for the UA module in the SWMF.
interact	Tools for creating interactive PyBats GUIs.
kyoto	kyoto is a tool set for obtaining and handling geomagnetic indices stored at the Kyoto World Data Center (WDC) website.
pwom	PyBats submodule for handling input/output for the Polar Wind Outflow Model (PWOM), one of the choices for the PW module in the SWMF.
qotree	A class for building QO trees for Bats2d objects.
ram	A module for reading, handling, and plotting RAM-SCB output.
rim	Classes, functions, and methods for reading, writing, and plotting output from the Ridley Ionosphere Model (RIM) and the similar legacy code, Ridley Serial.
trace2d	A set of routines for fast field line tracing.

Functions

add_body(ax[, rad, facecolor, show_planet, ...])	Creates a circle of radius=self.attrs['rbody'] and returns the MatPlotLib Ellipse patch object for plotting.
add_planet(ax[, rad, ang, add_night, zorder])	Creates a circle of radius=self.para['rbody'] and returns the MatPlotLib Ellipse patch object for plotting.
calc_wrapper(meth)	This is a decorator for self.calc_* object methods.
mhdname_to_tex(varname)	Convert common MHD variable and unit names into LaTeX-formated strings.
parse_filename_time(filename)	Given an SWMF file whose name follows the usual standards (see below), attempt to parse the file name to extract information about the iteration, runtime and date/time at which the file was written.
parse_tecvars(line)	Parse the VARIABLES line from a TecPlot-formatted ascii data file.
readarray(f[, dtype, inttype])	Read an array from an unformatted binary file written out by a Fortran program.

Classes

IdlFile(filename[, iframe, header, keep_case])	An object class that reads/parses an IDL-formatted output file from the SWMF and places it into a spacepy.pybats.PbData object.
ImfInput([filename, load, npoints])	A class to read, write, manipulate, and visualize solar wind upstream input files for SWMF simulations.
LogFile(filename[, starttime, keep_case])	An object to read and handle SWMF-type logfiles.
NgdcIndex([filename, load])	Many models incorporated into the SWMF rely on National Geophysical Data Center (NGDC) provided index files (especially F10.7 and Kp).
PbData(*args, **kwargs)	The base class for all PyBats data container classes.
SatOrbit([filename])	An class to load, read, write, and handle BATS-R-US satellite orbit input files.

spacepy.pybats.add_body(ax, rad=2.5, facecolor='lightgrey', show_planet=True, ang=0.0, add_night=True, zorder=1000, **extra_kwargs)

Creates a circle of radius=self.attrs[‘rbody’] and returns the MatPlotLib Ellipse patch object for plotting. If an axis is specified using the “ax” keyword, the patch is added to the plot. Default color is light grey; extra keywords are handed to the Ellipse generator function.

Because the body is rarely the size of the planet at the center of the modeling domain, add_planet is automatically called. This can be negated by using the show_planet kwarg.

Parameters:

axMatplotlib Axes object

Set the axes on which to place planet.

Other Parameters:

radfloat

Set radius of the inner boundary. Defaults to 2.5.

facecolorstring

Set color of face of inner boundary circle via Matplotlib color selectors (name, hex, etc.) Defaults to ‘lightgrey’.

show_planetboolean

Turns on/off planet indicator inside inner boundary. Defaults to True

angfloat

Set the rotation of the day-night terminator from the y-axis, in degrees Defaults to zero (terminator is aligned with Y-axis.)

add_nightboolean

Add night hemisphere. Defaults to True

zorderint

Set the matplotlib zorder of the patch to set how other plot elements order with the inner boundary patch. Defaults to 1000. If a planet is added, it is given a zorder of zorder + 5.

spacepy.pybats.add_planet(ax, rad=1.0, ang=0.0, add_night=True, zorder=1000, **extra_kwargs)

Creates a circle of radius=self.para['rbody'] and returns the MatPlotLib Ellipse patch object for plotting. If an axis is specified using the ax keyword, the patch is added to the plot.

Unlike the add_body method, the circle is colored half white (dayside) and half black (nightside) to coincide with the direction of the sun. Additionally, because the size of the planet is not intrinsically known to the MHD file, the kwarg “rad”, defaulting to 1.0, sets the size of the planet. add_night can turn off this behavior.

Extra keywords are handed to the Ellipse generator function.

Parameters:

axMatplotlib Axes object

Set the axes on which to place planet.

Other Parameters:

radfloat

Set radius of planet. Defaults to 1.

angfloat

Set the rotation of the day-night terminator from the y-axis, in degrees Defaults to zero (terminator is aligned with Y-axis.)

add_nightboolean

Add night hemisphere. Defaults to True

zorderint

Set the matplotlib zorder of the patch to set how other plot elements order with the inner boundary patch. Defaults to 1000, nightside patch is given zorder of zorder+5.

spacepy.pybats.calc_wrapper(meth)

This is a decorator for self.calc_* object methods. It establishes self._calcs, a list of calcuation functions that have been called, and adds the called function to that list to keep track of which calculations have already been performed for the object. If a calculation has already been performed, it is skipped in order to reduce effort.

spacepy.pybats.mhdname_to_tex(varname)

Convert common MHD variable and unit names into LaTeX-formated strings.

spacepy.pybats.parse_filename_time(filename)

Given an SWMF file whose name follows the usual standards (see below), attempt to parse the file name to extract information about the iteration, runtime and date/time at which the file was written. All three are returned to the caller in that order. If any cannot be found in the file name, “None” is returned in its place.

For ‘*’.outs files, ranges of times and iterations can be given in the file names. If this is the case, a list of values will be returned for that entry (see third example below).

Information on the format of time strings contained within SWMF output file names can be found in the SWMF User Manual.

Parameters:

filenamestring

An SWMF output file name.

Returns:

i_iterinteger, list of integers, or None

The iteration at which the file was written, if found.

runtimefloat, list of floats, or None

The run time (in seconds) at which the file was written, if found.

timedatetime.datetime, list of datetimes, or None

Either a datetime object or None, depending on the success of the file name parsing.

Examples

>>> from spacepy.pybats import parse_filename_time
>>> parse_filename_time('z=0_mhd_2_t00050000_n00249620.out')
(249620, 50000.0, None)

>>> parse_filename_time('mag_grid_e20130924-232600.out')
(None, None, datetime.datetime(2013, 9, 24, 23, 26))

>>> parse_filename_time('z=0_mhd_2_e20140410-000000-000_20140410-000300-000.outs')
(None, None, [datetime.datetime(2014, 4, 10, 0, 0), datetime.datetime(2014, 4, 10, 0, 3)])

spacepy.pybats.parse_tecvars(line)

Parse the VARIABLES line from a TecPlot-formatted ascii data file. Create a list of name-unit tuples for each variable.

spacepy.pybats.readarray(f, dtype=<class 'numpy.float32'>, inttype=<class 'numpy.int32'>)

Read an array from an unformatted binary file written out by a Fortran program.

Parameters:

fBinary file object

The file from which to read the array of values.

Returns:

numpy.arrayNumpy array

Return the data read from file as a 1-dimensional array.

Other Parameters:

dtypedata type

The data type used for data conversion.

inttypeNumpy integer type

Set the precision for the integers that store the size of each entry. Defaults to numpy.int32