Boundary Models

Another option for providing boundaries are model specifications. Several empirically derived mathematical models are included in ocbpy.boundaries.models to allow access to these formulations. These models typically depend on magnetic local time (MLT) and a geomagnetic or solar wind index. OCBpy requires that these functions provide the boundary location in co-latitude (degrees of magnetic latitude away from the pole), have MLT as the first input argument, and that all other inputs be keyword arguments.

Starkov

The Starkov 1994 model (see Starkov Model) uses a mathematical formulation based on All-Sky Imager data and the Auroral Electrojet Lower envelope index. They specify three boundaries: the polar edge of the auroral oval, the equatorward edge of the auroral oval, and the equatorward edge of the diffuse aurora (usually more equatorward than the discrete edge). These may be accessed in the code here using the boundary keyworkds: ‘ocb’, ‘eab’, and ‘diffuse’, respectively.

Gussenhoven

The Gussenhoven 1983 model (see Gussenhoven Model) uses a mathematical formulation based on DMSP data and the Kp index. They specify a single boundary: the equatorward edge of the diffuse aurora. As this model defines the boundary using separate linear fits for different MLT bins, the results may be returned at the binned times (‘binned’), at the nearest binned time (‘closest’), or at the requested times using a circle fit to all of binned times (‘circle’).

CH-Aurora-2014

The CH-Aurora-2014 model (see CH-Aurora-2014 Model) uses a mathematical formulation based on CHAMP field-aligned current (FAC) data and a delayed time-history of the Newell Coupling Function. They specify both auroral boundaries in each hemisphere. Although this model may be driven entirely by the Newell Coupling Function, the authors recommend adjusting the model output with CHAMP measurements of the FAC boundaries.

Boundary Models Module

Functions that provide boundary locations through a mathematical model.

References

[8] (1,2)

Starkov, G. V. (1994) Mathematical model of the auroral boundaries, Geomagnetism and Aeronomy, English Translation, 34(3), 331-336.

[9] (1,2)

Gussenhoven, M. S. et al. (1983) Systematics of the Equatorward Diffuse Auroral Boundary, J. Geophys. Res, 88(A7), 5692-5708.

[10]

Umbach and Jones (2003) A Few Methods for Fitting Circles to Data, IEEE Transactions on Instruments and Measurements, 52(6), pp 1881-1885

[11] (1,2,3,4,5)

Xiong and Luhr (2014) An empirical model of the auroral oval derived from CHAMP field-aligned current signatures - Part 2, Ann. Geophys., 32, pp 623-631, doi:10.5194/angeo-32-623-2014

ocbpy.boundaries.models.ch_aurora_2014_boundary(mlt, em=0, bnd='ocb', hemi=1, obs_colat=None, obs_mlt=None)

Calculate the location of the CH-Aurora-2014 auroral boundaries.

Parameters:

• mlt (float or array-like) – Magnetic local time in hours

• em (float or int) – The time-integrated Newell Coupling Function, as described in Equation 2 of [11] (default=0)

• bnd (str) – Boundary to calculate, expects one of ‘ocb’ or ‘eab’ (default=’ocb’)

• hemi (int) – Sign denoting the hemisphere, 1 for North and -1 for South (default=1)

• obs_colat (array-like) – CHAMP, or other, boundary observation co-latitudes (default=None)

• obs_mlt (array-like) – MLT of the observed boundary locations (default=None)

Returns:

bnd_lat – Location of the boundary in degrees away from the pole in apex geomagnetic coordinates for the specified magnetic local times.

Return type:

float or array-like

References

[11]

ocbpy.boundaries.models.ch_aurora_2014_coefficient_values(em, bnd, hemi)

Retrive the CH-Aurora-2014 auroral boundary coefficients.

Parameters:

• em (float or int) – The time-integrated Newell Coupling Function, as described in Equation 2 of [11] (default=0)

• bnd (str) – Boundary to calculate, expects one of ‘ocb’ or ‘eab’

• hemi (int) – Sign denoting the hemisphere, 1 for North and -1 for South

Returns:

• semix (float) – Semi-axis along the x-plane

• semiy (float) – Semi-axis along the y-plane

• x0 (float) – x-coordinate of the ellipse center

• y0 (float) – y-coordinate of the ellipse center

• phi0 (float) – Orientation angle of the ellipse

References

Tables 2 and 3 in [11]

ocbpy.boundaries.models.ch_aurora_2014_radius(ang_lt, semix, semiy, x0, y0, phi0, del_rad=0.0)

Calculate the CH-Aurora-2014 ellipse radii at the desired times.

Parameters:

• ang_lt (float or array-like) – Angular measure of MLT in radians

• semix (float) – Semi-axis along the x-plane in degrees

• semiy (float) – Semi-axis along the y-plane in degrees

• x0 (float) – x-coordinate of the ellipse center in degrees

• y0 (float) – y-coordinate of the ellipse center in degrees

• phi0 (float) – Orientation angle of the ellipse in radians

• del_rad (float) – Assimilative adjustment to the radius in degrees

Returns:

rad – Radius of the ellipse at the desired MLT in degrees

Return type:

float or array-like

References

Equations 3 and 4 in [11]

ocbpy.boundaries.models.circle_fit(mlt, colat)

Fit a circle to boundary estimates.

Parameters:

• mlt (array-like) – Array of MLT values in hours for the boundary locations

• colat (array-like) – Array of magnetic co-latitude values in degrees denoting the boundary locations, paired to the mlt inputs

Returns:

• phi_cent (float) – MLT location of the circle centers in radians

• r_cent (float) – Co-latitude of the circle center in degrees

• radius (float) – Radius of the circle in degrees latitude

• r_err (float) – RMS error of the fit

Raises:

ValueError – If the inputs are the wrong shape

References

Section D in [10]

ocbpy.boundaries.models.gussenhoven_colatitudes(kp, mlt_inds=None, closest=False)

Calculate the Gussenhoven EAB model co-latitude values.

Parameters:

• kp (float or int) – Decimal Kp geomagnetic index, ranges from 0 to 9 with “+” translating to plus one third and “-” translating to minus one third

• mlt_inds (array-like or NoneType) – MLT hourly bins at which boundary locations will be returned or None to return all available values (default=None)

• closest (bool) – If False, will return NaN for the request for an MLT value that does not exist. If True, will find the closest binned value and return that instead (default=False)

Returns:

• colats (array-like) – Co-latitude values in degrees away from the pole for the requested MLT bins

• mlts (array-like) – MLT bin values for each co-latitude

References

[9]

ocbpy.boundaries.models.gussenhoven_equatorward_auroral_boundary(mlt, kp=0, model='circle')

Calculate the location of the diffuse EAB.

Parameters:

• mlt (float or array-like) – Magnetic local time in hours

• kp (float or int) – Decimal Kp geomagnetic index, ranges from 0 to 9 with “+” translating to plus one third and “-” translating to minus one third (default=0)

• model (str) – Model flavour, with ‘binned’ using the value from the available hourly solutions or NaN if that hour is absent, ‘closest’ to use the closest hourly bin, or ‘circle’ to use the value of the circle fit to the available hourly solutions (default=’circle’)

Returns:

bnd_lat – Location of the boundary in degrees away from the pole in corrected geomagnetic coordinates for the specified magnetic local times.

Return type:

float or array-like

Raises:

ValueError – If an unknown model method is requested.

References

[9]

ocbpy.boundaries.models.starkov_auroral_boundary(mlt, al=-1, bnd='ocb')

Calculate the location of the Starkov auroral boundaries.

Parameters:

• mlt (float or array-like) – Magnetic local time in hours

• al (float or int) – AL geomagnetic index, Auroral Electrojet Lower envelope in nT (default=-1)

• bnd (str) – Boundary to calculate, expects one of ‘ocb’, ‘eab’, or ‘diffuse’ (default=’ocb’)

Returns:

bnd_lat – Location of the boundary in degrees away from the pole in corrected geomagnetic coordinates for the specified magnetic local times.

Return type:

float or array-like

References

[8]

ocbpy.boundaries.models.starkov_coefficient_values(al, coeff_name, bnd)

Calculate the Starkov auroral model coefficient values.

Parameters:

• al (float or int) – AL geomagnetic index, Auroral Electrojet Lower envelope in nT

• coeff_name (str) – Coefficient name, expects one of ‘A0’, ‘A1’, ‘A2’, ‘A3’, ‘alpha1’, ‘alpha2’, or ‘alpha3’

• bnd (str) – Boundary to calculate, expects one of ‘ocb’, ‘eab’, or ‘diffuse’

Returns:

coeff – Coefficient value in hours (alpha) or degrees latitude (A)

Return type:

float

References

[8]