Solar Wind Prediction

To predict the solar wind, primesw includes the prime class. This class loads a pretrained implemetation of the PRIME algorithm, and includes several methods to help users make predictions on grids and/or with synthetic data. It is recommended to instantiate prime objects in their default configuration:

import primesw as psw
propagator = psw.prime()

The prime class method prime.predict() is the way that most users will interface with PRIME. To generate solar wind predictions from Wind spacecraft data, specify start and stop times for the desired prediction. start and stop are strings with format 'YYYY-MM-DD HH:MM:SS'.

import primesw as psw
propagator = psw.prime()
propagator.predict(start = '2020-01-01 00:00:00', stop = '2020-01-02 00:00:00')

If using data from an L1 monitor to make predictions, pass the input data using input argument. If input is specified, start and stop should not be (and vice versa). input is also useful for making predicitons from synthetic solar wind data (see prime.build_synth_input). For instance, one can predict what the solar wind at the bow shock nose would be if the solar wind flow at L1 was 700km/s:

import primesw as psw
propagator = psw.prime()
propagator.predict(input = propagator.build_synth_input(vx=-700))

By default, predictions are made at the average location of the nose of Earth’s bow shock 13.25 Earth Radii upstream on the Geocentric Solar Ecliptic (GSE) x-axis. One can also specify a position to propagate to besides the default by specifying pos:

import primesw as psw
propagator = psw.prime()
propagator.predict(start = '2020-01-01 00:00:00', stop = '2020-01-02 00:00:00', pos = [13.25, 5, 0])

All positions are in GSE coordinates with units of Earth Radii. It is not recommended to make predictions outside of the region PRIME was trained on (within 30 Earth radii of the Earth on the dayside).

class primesw.prime(model=None, in_scaler=None, tar_scaler=None, in_keys=None, tar_keys=None, out_keys=None, hps=[60, 15, 0.08333333333333333])[source]

This class wraps an instance of PRIME for solar wind prediciton.

When instantiating a prime object, one can specify a predefined model to be used instead of the automatically-loaded PRIME model. In that case, the scaling functions for the input and target datasets (in_scaler and tar_scaler), the input and target features (in_keys and tar_keys), and the output features (out_keys) must be specified. The full list of arguments that can be passed to prime is given below, but they are not recommended for general use.

Parameters:

model – Keras model for predicitons. If None, PRIME is loaded from the package.
in_scaler – Scikitlearn preprocessing scaler for input arrays. If None, pre-fit RobustScaler is loaded from the package.
tar_scaler – Scikitlearn preprocessing scaler for output arrays. If None, pre-fit RobustScaler is loaded from the package.
in_keys – Features used as inputs. If None, defaults are loaded from the package.
tar_keys – Features used as targets. If None, defaults are loaded from the package.
out_keys – Features used as outputs. If None, defaults are loaded from the package.

build_model(units=[352, 192, 48, 48], activation='elu', dropout=0.2, lr=0.0001)[source]: Builds the underlying PRIME model with no weights or biases loaded. Deprecated as of keras introducing the .keras model save routine. Units are the layer size of the GRU layer and three dense layers. Normalization and dropout applied at each layer.

build_real_input(start, stop, pos=[13.25, 0, 0], load_freq='3M')[source]

Load Wind spacecraft input data for PRIME in between specified date strings.

Parameters:

start (string): The start date of the data to load (‘YYYY-MM-DD’)
end (string): The end date of the data to load (‘YYYY-MM-DD’)
pos (list): Location of propagation in GSE coordinates (Earth Radii). Default [13.25, 0, 0].
load_freq (string): Max length of data loaded by CdasWs. If throwing RuntimeError, try modifying this parameter. Default ‘3M’ (three months).

Return:

input (Dataframe): Input dataframe suitable to predict from with self.predict().

build_synth_input(epoch=Timestamp('1970-01-01 00:00:00+0000', tz='UTC'), bx=0, by=0, bz=-5, vx=-400, vy=0, vz=0, ni=5, vt=30, rx=200, ry=0, rz=0, tar_rx=13.25, tar_ry=0, tar_rz=0)[source]

Builds a synthetic input array from user-specified quantities at L1. For input arrays made from measured data at L1, see prime.build_real_input.

Parameters:

epoch (datetime): Datetime of start of input Dataframe.
bx (float, array-like): IMF Bx value (nT).
by (float, array-like): IMF By value (nT).
bz (float, array-like): IMF Bz value (nT).
vx (float, array-like): Solar wind Vx value ().
vy (float, array-like): Solar wind Vy value.
vz (float, array-like): Solar wind Vz value.
ni (float, array-like): Solar wind ion density value.
vt (float, array-like): Solar wind ion thermal speed value.
rx (float, array-like): Wind spacecraft position x value.
ry (float, array-like): Wind spacecraft position y value.
rz (float, array-like): Wind spacecraft position z value.
tar_rx (float, array-like): Propagation target position x value.
tar_ry (float, array-like): Propagation target position y value.
tar_rz (float, array-like): Propagation target position z value.

Returns:

input (Dataframe): Input dataframe suitable to predict from with self.predict().

fraction: Maximum fraction of input timeseries that can be interpolated, in 100s units. Specified via hps argument.

predict(input=None, start=None, stop=None, pos=[13.25, 0, 0])[source]: Method that produces a dataframe of PRIME solar wind predictions.

predict_grid(gridsize, x_extent, framenum, bx, by, bz, vx, vy, vz, ni, vt, rx, ry, rz, y_extent=None, z_extent=None, y=0, z=0, subtract_ecliptic=False)[source]

Generate predictions from PRIME on a grid of points in GSE coordinates.

Parameters:

gridsize (float): Spacing of grid points (RE)
x_extent (list): Range of x values to calculate on (GSE RE).
framenum (int): Number of frames to calculate (GSE RE).
bx (float, array-like): IMF Bx value (nT). If array like, must be of length framenum.
by (float, array-like): IMF By value (nT). If array like, must be of length framenum.
bz (float, array-like): IMF Bz value (nT). If array like, must be of length framenum.
vx (float, array-like): Solar wind Vx value (km/s). If array like, must be of length framenum.
vy (float, array-like): Solar wind Vy value (km/s). If array like, must be of length framenum.
vz (float, array-like): Solar wind Vz value (km/s). If array like, must be of length framenum.
ni (float, array-like): Solar wind ion density value (cm^-3). If array like, must be of length framenum.
vt (float, array-like): Solar wind ion thermal speed value (km/s). If array like, must be of length framenum.
rx (float, array-like): Wind spacecraft position x value (GSE RE). If array like, must be of length framenum.
ry (float, array-like): Wind spacecraft position y value (GSE RE). If array like, must be of length framenum.
rz (float, array-like): Wind spacecraft position z value (GSE RE). If array like, must be of length framenum.
y_extent (list): Range of y values to calculate on (GSE RE). If None, z_extent must be specified.
z_extent (list): Range of z values to calculate on (GSE RE). If None, y_extent must be specified.
y (float, array-like): Y position (GSE RE) that is held constant if y_extent is not specified. Default 0.
z (float, array-like): Z position (GSE RE) that is held constant if z_extent is not specified. Default 0.
subtract_ecliptic (bool): Whether or not to subtract the Earth’s motion in the ecliptic from Vy. Default False.

Returns:

output_grid (ndarray): Array of predicted values on the grid. Shape (framenum, x_extent/gridsize, y_extent/gridsize, 14). Features as in prime.out_keys.

predict_raw(input)[source]: Generates PRIME predictions from input dataframe. Assumes that input has keys specified by prime.in_keys. It is generally recommended to use prime.predict instead.

stride: Prediction lead time, in 100s units. Specified via hps argument.

window: Length of input timeseries, in 100s units. Specified via hps argument.