Magnetosheath Prediction

To predict the magnetosheath, primesw includes the primesh class. This class loads a pretrained implemetation of the PRIME-SH algorithm, much in the same way that prime loads PRIME. It is recommended to instantiate primesh objects in their default configuration:

import primesw as psw
propagator = psw.primesh()

The primesh class method primesh.predict() is the way that most users will interface with PRIME-SH. To generate magnetosheath 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.primesh()
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 primesh.build_synth_input). For instance, one can predict what the solar wind at the magnetopause nose would be if the solar wind density at L1 is 20 ions per cc:

import primesw as psw
propagator = psw.primesh()
propagator.predict(input = propagator.build_synth_input(n=20))

By default, predictions are made at the average middle of Earth’s magnetosheath 12.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.primesh()
propagator.predict(start = '2020-01-01 00:00:00', stop = '2020-01-02 00:00:00', pos = [11.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.primesh(model=None, in_scaler=None, tar_scaler=None, loc_scaler=None, in_keys=None, tar_keys=None, out_keys=None, hps=[55, 18, 0.05])[source]

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

When instantiating a primesh object, one can specify a predefined model to be used instead of the automatically-loaded PRIME-SH 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 primesh is given below.

Parameters:

  • model – Keras model for predicitons. If None, PRIME-SH 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.

  • tar_scaler – Scikitlearn preprocessing scaler for target location 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.

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, loc_mask=False, 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]

Wrapper function to predict with a keras model. Differs from prime.predict_raw by the inclusion of separate location scaling. Not recommended for direct use, see prime.predict instead.