spacepy.pybats.ImfInput

class spacepy.pybats.ImfInput(filename=False, load=True, npoints=0, *args, **kwargs)

A class to read, write, manipulate, and visualize solar wind upstream input files for SWMF simulations.

Kwarg	Description
filename	Set the input/output file name.
load	Read file upon instantiation? Defaults to True
npoints	For empty data sets, sets number of points (default is 0)

Changed in version 0.5.0: Default variable names for temperature and density are now ‘t’ and ‘n’.

__init__(filename=False, load=True, npoints=0, *args, **kwargs)

Base class for “Data Model” representation data

Abstract method, reimplement

Attributes:

attrsdict

dictionary of the attributes of the SpaceData object

Methods

add_pram_bz([target, loc, pcol, bcol, xlim, ...])	Plot, on a single set of axes, both ram pressure and IMF Bz for a quick-look summary of an event.
calc_alf()	Calculate the solar wind Alfven speed in $km/s$.
calc_alfmach()	Calculate the Alvenic Mach number and save as self['machA'].
calc_b()	Calculate the magnitude of the IMF in nT.
calc_clock()	Calculate and store IMF clock angle, defined as the angle of the interplanetary magnetic field (IMF) in the GSM Y-Z plane.
calc_epsilon()	Calculate the epsilon parameter, an approximation of power input into the magnetosphere.
calc_pram()	Calculate ram pressure from SW conditions.
calc_u()	Calculate the magnitude of the total solar wind bulk velocity.
quicklook([plotvars, timerange, legloc, ...])	Generate a quick-look plot of solar wind conditions driving the SWMF.
read(infile)	Read an SWMF IMF/solar wind input file into a newly instantiated imfinput object.
varcheck()	Ensure that the variable list, which gives the order of the variables as they are written to file, correctly corresponds to the variables stored in the ImfInput object.
write([outfile])	Write the ImfInput object to file.

Attributes

attrs

add_pram_bz(target=None, loc=111, pcol='#CC3300', bcol='#3333CC', xlim=None, plim=None, blim=None, epoch=None)

Plot, on a single set of axes, both ram pressure and IMF Bz for a quick-look summary of an event.

The figure and main axes object are returned.

Parameters:

targetFigure or Axes

If None (default), a new figure is generated from scratch. If a matplotlib Figure object, a new axis is created to fill that figure. If a matplotlib Axes object, the plot is placed into that axis.

locint

Use to specify the subplot placement of the axis (e.g. loc=212, etc.) Used if target is a Figure or None. Default 111 (single plot).

pcolmatplotlib color specifier

Set the line and label color for ram pressure.

bcolmatplotlib color specifier

Set the line and label color for IMF Bz.

xlim2-element list of datetimes, optional

Set the time range for the plot. Defaults to full range.

plim2-element list

Set the y-axis range for dynamic pressure.

blim2-element list

Set the y-axis range for IMF Bz.

epochdatetime.datetime

Create an epoch marker (vertical line) at time=epoch.

Returns:

figmatplotlib figure object

ax1matplotlib axes object for the Pdyn plot.

ax2matplotlib axes object for the Bz plot.

calc_alf()

Calculate the solar wind Alfven speed in $km/s$. Result is stored internally as self[‘vAlf’]

calc_alfmach()

Calculate the Alvenic Mach number and save as self[‘machA’]. Units default to $km/s$.

calc_b()

Calculate the magnitude of the IMF in nT. Store as self[‘b’].

calc_clock()

Calculate and store IMF clock angle, defined as the angle of the interplanetary magnetic field (IMF) in the GSM Y-Z plane. A clock angle of zero represents purely northward IMF while 180 represents purely southward configuration.

The resulting value is stored as self['clock'] in units of degrees.

Notes

Added in version 0.6.0.

calc_epsilon()

Calculate the epsilon parameter, an approximation of power input into the magnetosphere. It is Poynting flux ($E imes B / mu_0$) scaled to the solar wind clock angle. Thus, it is an energy flux, or, equivalently, power-per-unit area.

The resultant quantity is stored as self['epsilon'] and has units of $W/m^2$.

For full details, see Perreault and Akasofu(1978), https://doi.org/10.1111/j.1365-246X.1978.tb05494.x.

Notes

Added in version 0.6.0.

calc_pram()

Calculate ram pressure from SW conditions. Output units in nPa. If object was instantiated via an existing imf file, this value is calculated automatically.

calc_u()

Calculate the magnitude of the total solar wind bulk velocity. Store internally as self[‘u’].

quicklook(plotvars=None, timerange=None, legloc='best', colors=None, title=None)

Generate a quick-look plot of solar wind conditions driving the SWMF. Default behavior creates a figure showing the three components of IMF, solar wind density, and Earthward velocity. The resulting figure will be a paper-sized plot with one axes object per entry in plotvars.

The plotvars keyword controls the behavior of the resulting plot. For example, ['rho', 'pram', ['bx','by','bz']] will create three subplots with the three IMF components on a single axes.

Additional empty axes can be added by specifying a plotvar entry that is not a valid key to the ImfInput object. This is useful in some circumstances, e.g., cases where the user may want to plot a non-solar wind value, such as Dst, from another source. The plotvar string will be used as the y-axis label.

Other Parameters:

plotvarslist of variable names, optional

The variables to plot given as a list of ImfInput object keys. Use a nested list to plot more than one variable on a single axes object.

colorslist of strings, optional

The colors of the resulting lines as a list of Matplotlib color compatible strings (e.g., ‘#000000’, ‘k’, ‘lightgrey’). The shape of the list should match that of plotvars; if not, quicklook will fill in with default colors. Any axes with multiple plotvars specified but only a single color will have that color repeated for each line placed on the axes. Default behavior is to use the current Matplotlib color cycle.

timerangearray-like of datetimes

An array-like structure of datetimes marking the time range of the resulting plot.

titlestr, optional

Title to place at the top of the figure, defaults to, ‘Solar Wind Drivers {self.attrs["coor"] Coordinates)’

leglocstr, default=’best’

Location of any legends place on axes with more than one variable.

Examples

The following examples use the data from the Spacepy test suite. Open an IMF object, create the default quicklook plot:

>>> import matplotlib.pyplot as plt
>>> from spacepy.pybats import ImfInput
>>> imf = ImfInput('spacepy/tests/data/pybats_test/imf_single.dat')
>>> imf.quicklook()
>>> plt.show()

Create a customized quicklook plot with two axes: one with 3 variables, another with 2 variables. Specify custom line colors.

>>> imf = ImfInput('spacepy/tests/data/pybats_test/imf_multi.dat')
>>> imf.quicklook([['bx', 'by', 'bz'], ['SwRho', 'IonoRho']],
                  colors=[['r', 'g', 'b'], ['orange', 'cyan']])
>>> plt.show()

read(infile)

Read an SWMF IMF/solar wind input file into a newly instantiated imfinput object.

varcheck()

Ensure that the variable list, which gives the order of the variables as they are written to file, correctly corresponds to the variables stored in the ImfInput object.

Returns True on success, returns warnings and False on fail.

write(outfile=False)

Write the ImfInput object to file. Kwarg outfile can be used to specify the path of the output file; if it is not set, self.attrs[‘file’] is used. If this is not set, default to “imfinput.dat”.

attrs: collections.abc.Mapping