swarmpal.toolboxes.dsecs.dsecs_algorithms

Contents

swarmpal.toolboxes.dsecs.dsecs_algorithms#

Algorithms for low latitude spherical elementary current system analysis.

Adapted from MatLab code by Heikki Vanhamäki.

Attributes#

logger

Classes#

grid2D

Class for 2D DSECS grids

grid1D

Simple class to hold a 1D lat grid

dsecsgrid

Class for all the grids needed in DSECS analysis

dsecsdata

Class for DSECS variables and fitting procedures

Functions#

_DSECS_steps(SwAin, SwCin)

DSECS analysis for Vires xarray input.

_legPol_n1(n, x[, ind])

Evaluate associated Legendre polynomials (l, m=1).

_legPol(n, x[, ind])

Evaluate Legendre polynomials.

SECS_1D_DivFree_vector(latV, latSECS, ri)

Calculates the matrix for 1D divergence free current density.

SECS_1D_DivFree_magnetic(latB, latSECS, rb, rsecs, M)

Calculates the matrix for magnetic field from 1D divergence free current.

SECS_1D_CurlFree_vector(latV, latSECS, ri)

Calculates the array relating SECS amplitudes to curl free current.

SECS_1D_CurlFree_magnetic(latB, latSECS, rb, rsecs, ...)

Calculates the array that maps the CF SECS amplitudes to magnetic field.

SECS_2D_DivFree_vector(thetaV, phiV, thetaSECS, ...)

Calculates 2D DF SECS matrices for currents densities.

SECS_2D_DivFree_magnetic(thetaB, phiB, thetaSECS, ...)

Calculates the array that maps the SECS amplitudes to magnetic field.

SECS_2D_CurlFree_antisym_vector(thetaV, phiV, ...)

Calculates the mapping from antisymmetric dipolar CF SECS to current density.

SECS_2D_CurlFree_antisym_magnetic(thetaB, phiB, ...)

Calculates the mapping from antisymmetric dipolar CF SECS to magnetic field.

secs_2d_curlFree_antisym_lineintegral(thetaB, phiB, ...)

Line integral for DSECS 2d curl free.

_calc_root(x, y, z)

_summary_

getUnitVectors(SwA, SwC)

Calculates the magnetic unit vectors.

getLocalDipoleFPtrack1D(latB, rB, Ri)

Finds the local dipole footpoints for the 1D curl-free grid creation.

getLocalDipoleFPtrack2D(latB, lonB, rB, Ri)

Finds the local dipole footpoints for the 2D curl-free grid creation.

mag_transform_dsecs(SwA, SwC, pole_lat, pole_lon)

Rotates the data to a magnetic coordinate systems.

trim_data(SwA, SwC)

Finds a period with suitable spaceraft velocity for analysis.

get_exclusion_zone(SwA, SwC)

Module Contents#

swarmpal.toolboxes.dsecs.dsecs_algorithms.logger#
swarmpal.toolboxes.dsecs.dsecs_algorithms._DSECS_steps(SwAin, SwCin)[source]#

DSECS analysis for Vires xarray input.

Parameters:

  • SwAin (xarray from SecsInput) – Input data for Swarm Alpha

  • SwCin (xarray from SecsInput) – Input data for Swarm Charlie

Returns:

Each entry contains the original data (“original_data), the resulting current densities (“current_densities”), the magnetic fit for Swarm A and C (“magnetic_Fit_Alpha”, “magnetic_Fit_Charlie”) and the dsecsdata object (“case”).

Return type:

List of dicts

swarmpal.toolboxes.dsecs.dsecs_algorithms._legPol_n1(n, x, ind=False)[source]#

Evaluate associated Legendre polynomials (l, m=1).

Parameters:

  • n (int) – max degree of the polynomials

  • x (ndarray) – points at which to evaluate the polynomials, -1 <= x >= 1

  • ind (bool, optional) – Return only the nth degree polynomial, by default False

Returns:

(len(x),n) shaped array of the polynomial values.

Return type:

ndarray

swarmpal.toolboxes.dsecs.dsecs_algorithms._legPol(n, x, ind=False)[source]#

Evaluate Legendre polynomials.

Parameters:

  • n (int) – max degree of the polynomials

  • x (ndarray) – 1D array of points at which to evaluate the polynomials, -1 <= x >= 1

  • ind (bool, optional) – Return only the nth degree polynomial, by default False

Returns:

(len(x),n+1) shaped array of the polynomial values.

Return type:

ndarray

swarmpal.toolboxes.dsecs.dsecs_algorithms.SECS_1D_DivFree_vector(latV, latSECS, ri)[source]#

Calculates the matrix for 1D divergence free current density.

Parameters:

  • latV (ndarray) – Latitudes of locations where vectors is calculated, in degrees

  • latSECS (ndarray) – Latitudes of the 1D SECS poles, in degrees

  • ri (int) – Assumed radius of the spherical shell where the currents flow (km).

Returns:

2D array that maps the 1D elementary current amplitudes to currents.

Return type:

ndarray

swarmpal.toolboxes.dsecs.dsecs_algorithms.SECS_1D_DivFree_magnetic(latB, latSECS, rb, rsecs, M)[source]#

Calculates the matrix for magnetic field from 1D divergence free current.

Parameters:

  • latB (ndarray) – Array of latitudes where the magnetic field is calculated [degree]

  • latSECS (ndarray) – Array of latitudes where 1D CF SECS are located [degree]

  • rb (ndarray) – Array of radial distances of the points where the magnetic field is calculated, scalar or vector, [km]

  • rsecs (float) – Radius of the sphere where the 1D CF SECS are located, scalar, [km]

  • M (int) – argest order of the Legendre polynomials

Returns:

  • ndarray – 2D array to map the elementary current system amplitudes to radial magnetic field

  • ndarray – 2D array to map the elementary current system amplitudes to meridional magnetic field

swarmpal.toolboxes.dsecs.dsecs_algorithms.SECS_1D_CurlFree_vector(latV, latSECS, ri)[source]#

Calculates the array relating SECS amplitudes to curl free current.

Parameters:

  • latV (ndarray) – Array of latitudes where the current is calculated.

  • latSECS (ndarray) – Array of latitudes of the SECS poles.

  • ri (float) – Assumed radius of the spherical shell where the currents flow (km).

Returns:

2D array to map the elementary current amplitudes to div free current.

Return type:

ndarray

swarmpal.toolboxes.dsecs.dsecs_algorithms.SECS_1D_CurlFree_magnetic(latB, latSECS, rb, rsecs, geometry)[source]#

Calculates the array that maps the CF SECS amplitudes to magnetic field.

Parameters:

  • latB (ndarray) – Latitudes where the magnetic field is calculated.

  • latSECS (ndarray) – Latitudes of the SECS poles

  • rb (ndarray) – Array of radial distances of the points where the magnetic field is calculated, scalar or vector, [km]

  • rsecs (float) – Radius of the sphere where the calculation takes place, [km], scalar

  • geometry (string) – If ‘radial’, assume radial field lines. Else, assume dipolar field.

Returns:

2D array that maps the SECS amplitudes to magnetic field measurements.

Return type:

ndarray

swarmpal.toolboxes.dsecs.dsecs_algorithms.SECS_2D_DivFree_vector(thetaV, phiV, thetaSECS, phiSECS, radius, limitangle)[source]#

Calculates 2D DF SECS matrices for currents densities.

Function for calculating matrices matVtheta and matVphi which give the theta- and phi-components of a vector field from the scaling factors of div-free spherical elementary surrent systems (DF SECS).

Parameters:

  • thetaV (ndarray) – theta coordinate of points where the vector is calculated

  • phiV (ndarray) – phi coordinate of points where the vector is calculated

  • thetaSECS (ndarray) – theta coordinates od SECS poles

  • phiSECS (ndarray) – phi coordinates of points where the vector is calculated

  • radius (ndarray) – Radius of the sphere where the calculation takes place, [km], scalar

  • limitangle (ndarray) – Half-width of the uniformly distributed SECS, [radian], scalar or Nsecs-dimensional vector.

Returns:

  • ndarray – 2D array to map the elementary current system amplitudes to theta component of current density.

  • ndarray – 2D array to map the elementary current system amplitudes to phi component of current density.

swarmpal.toolboxes.dsecs.dsecs_algorithms.SECS_2D_DivFree_magnetic(thetaB, phiB, thetaSECS, phiSECS, rb, rsecs)[source]#

Calculates the array that maps the SECS amplitudes to magnetic field.

Parameters:

  • thetaB (ndarray) – Theta coordinate of the points where magnetic field is calculated.

  • phiB (ndarray) – Phi coordinate of the points where magnetic field is calculated.

  • thetaSECS (ndarray) – Theta coordinate of the SECS poles.

  • phiSECS (ndarray) – Phi coordinate of the SECS poles.

  • rb (ndarray) – Geocentric radius of the points where the magnetic field is calculated.

  • rsecs (float) – Assumed radius of the spherical shell where the currents flow (km).

Returns:

  • ndarray – 2D array to map the elementary current system amplitudes to radial component of magnetic field.

  • ndarray – 2D array to map the elementary current system amplitudes to theta component of magnetic field.

  • ndarray – 2D array to map the elementary current system amplitudes to phi component of magnetic field.

swarmpal.toolboxes.dsecs.dsecs_algorithms.SECS_2D_CurlFree_antisym_vector(thetaV, phiV, thetaSECS, phiSECS, radius, limitangle)[source]#

Calculates the mapping from antisymmetric dipolar CF SECS to current density.

Parameters:

  • thetaV (ndarray) – theta coordinate of points where the vector is calculated

  • phiV (ndarray) – phi coordinate of points where the vector is calculated

  • thetaSECS (ndarray) – theta coordinates od SECS poles

  • phiSECS (ndarray) – phi coordinates of points where the vector is calculated

  • radius (ndarray) – Radius of the sphere where the calculation takes place, [km], scalar

  • limitangle (ndarray) – Half-width of the uniformly distributed SECS, [radian], scalar or Nsecs-dimensional vector.

Returns:

  • ndarray – 2D array that maps the SECS amplitudes to the theta component of the current density.

  • ndarray – 2D array that maps the SECS amplitudes to the phi component of the current density.

swarmpal.toolboxes.dsecs.dsecs_algorithms.SECS_2D_CurlFree_antisym_magnetic(thetaB, phiB, thetaSECS, phiSECS, rb, rsecs, limitangle)[source]#

Calculates the mapping from antisymmetric dipolar CF SECS to magnetic field.

Parameters:

  • thetaB (ndarray) – Theta coordinate of the points where magnetic field is calculated.

  • phiB (ndarray) – Phi coordinate of the points where magnetic field is calculated.

  • thetaSECS (ndarray) – Theta coordinate of the SECS poles.

  • phiSECS (ndarray) – Phi coordinate of the SECS poles.

  • rb (ndarray) – Geocentric radius of the points where the magnetic field is calculated.

  • rsecs (float) – Assumed radius of the spherical shell where the currents flow (km).

  • limitangle (ndarray) – Half-width of the uniformly distributed SECS, [radian], scalar or Nsecs-dimensional vector.

Returns:

  • ndarray – 2D array that maps the SECS amplitudes to the theta component of the current density.

  • ndarray – 2D array that maps the SECS amplitudes to the phi component of the current density.

swarmpal.toolboxes.dsecs.dsecs_algorithms.secs_2d_curlFree_antisym_lineintegral(thetaB, phiB, thetaSECS, phiSECS, rb, rsecs, smallr)[source]#

Line integral for DSECS 2d curl free.

Parameters:

  • thetaB (ndarray) – Theta coordinate of the points where magnetic field is calculated.

  • phiB (ndarray) – Phi coordinate of the points where magnetic field is calculated.

  • thetaSECS (float) – Theta coordinate of the SECS pole in radian.

  • phiSECS (float) – Phi coordinate of the SECS pole in radian.

  • rb (ndarray) – Geocentric radius of the points where the magnetic field is calculated.

  • rsecs (float) – Assumed radius of the spherical shell where the currents flow (km).

  • smallr (ndarray) – Limit of “small” radius [km]

Returns:

bx, by, bz – Cartesian components of the magnetic field at the magnetometer locations [nT]

Return type:

ndarray

swarmpal.toolboxes.dsecs.dsecs_algorithms._calc_root(x, y, z)[source]#

_summary_

Parameters:

  • x (ndarray) – _description_

  • y (ndarray) – _description_

  • z (ndarray) – _description_

Returns:

_description_

Return type:

ndarray

swarmpal.toolboxes.dsecs.dsecs_algorithms.getUnitVectors(SwA, SwC)[source]#

Calculates the magnetic unit vectors.

Parameters:

  • SwA (xarray) – Swarm A and C datasets.

  • SwC (xarray) – Swarm A and C datasets.

Returns:

SwA, SwC – Swarm A and C datasets including magnetic unit vectors ‘ggUvT’, ‘ggUvP’ and ‘UvR’.

Return type:

xarray

class swarmpal.toolboxes.dsecs.dsecs_algorithms.grid2D(origin='geo')[source]#

Class for 2D DSECS grids

ggLat#
ggLon#
magLat#
magLon#
angle2D#
diff2lon2D#
diff2lat2D#
origin = 'geo'#
create(lat1, lon1, lat2, lon2, dlat, lonRat, extLat, extLon, poleLat, poleLon)[source]#

Initializes the 2D grid from Swarm data.

Parameters:

  • lat1 (ndarray) – Swarm A and C latitudes, [degree].

  • lat2 (ndarray) – Swarm A and C latitudes, [degree].

  • lon1 (ndarray) – Swarm A and C longitudes, [degree].

  • lon2 (ndarray) – Swarm A and C longitudes, [degree].

  • dlat (float) – 2D grid spacing in latitudinal direction, [degree].

  • lonRat (int or float) – Ratio between the satellite separation and longitudinal spacing of the 2D grid.

  • extLat (int) – Number of points to extend the 2D grid outside data area in latitudinal and longitudinal directions.

  • extLon (int) – Number of points to extend the 2D grid outside data area in latitudinal and longitudinal directions.

class swarmpal.toolboxes.dsecs.dsecs_algorithms.grid1D[source]#

Simple class to hold a 1D lat grid

lat#
diff2#
create(lat1, lat2, dlat, extLat)[source]#

Initializes the 1D grid from Swarm data.

Parameters:

  • lat1 (ndarray) – Swarm A and C latitudes ,[degree].

  • lat2 (ndarray) – Swarm A and C latitudes ,[degree].

  • dlat (int or float) – 1D grid spacing in latitudinal direction, [degree].

  • extLat (int) – Number of points to extend the 1D grid outside data area in latitudinal direction.

class swarmpal.toolboxes.dsecs.dsecs_algorithms.dsecsgrid[source]#

Class for all the grids needed in DSECS analysis

out#
secs2Ddf#
secs1Ddf#
secs1DcfNorth#
secs1DcfSouth#
secs2DcfNorth#
secs2DcfSouth#
secs2DcfRemoteNorth#
secs2DcfRemoteSouth#
outputlimitlat = 40#
Re = 6371#
Ri = 6501#
poleLat = 90.0#
poleLon = 0.0#
dlatOut = 0.5#
lonRatioOut = 2#
extLatOut = 0#
extLonOut = 3#
extLat1D = 5#
indsN#
insdS#
extLat2D = 5#
extLon2D = 7#
cfremoteN = 3#
flag = 0#
test#
FindPole(SwA)[source]#

Finds the best location for a local magnetic dipole pole based on Swarm measurements.

Parameters:

SwA (xarray) – Swarm A dataset.

create(SwA, SwC)[source]#

Initializes the 1D and 2D grids from Swarm data.

Parameters:

  • SwA (xarray) – Swarm A and C datasets.

  • SwC (xarray) – Swarm A and C datasets.

swarmpal.toolboxes.dsecs.dsecs_algorithms.getLocalDipoleFPtrack1D(latB, rB, Ri)[source]#

Finds the local dipole footpoints for the 1D curl-free grid creation.

Parameters:

  • latB (ndarrar) – Magnetic latitude of the satellite, [degree].

  • rB (ndarray) – Geocentric radius of the satellite, [km].

  • Ri (int or float) – Assumed radius of the spherical shell where the currents flow, [km].

Returns:

track – Latitude of the local dipole footpoints of the satellite, [degree].

Return type:

ndarray

swarmpal.toolboxes.dsecs.dsecs_algorithms.getLocalDipoleFPtrack2D(latB, lonB, rB, Ri)[source]#

Finds the local dipole footpoints for the 2D curl-free grid creation.

Parameters:

  • latB (ndarray) – Magnetic latitude of the satellite, [degree].

  • lonB (ndarray) – Magnetic longitude of the satellite, [degree].

  • rB (ndarray) – Geocentric radius of the satellite, [km].

  • Ri (int or float) – Assumed radius of the spherical shell where the currents flow, [km].

Returns:

latFP, lonFP – Latidue and longitude of the local dipole footpoints of the satellite, [degree].

Return type:

ndarray

swarmpal.toolboxes.dsecs.dsecs_algorithms.mag_transform_dsecs(SwA, SwC, pole_lat, pole_lon)[source]#

Rotates the data to a magnetic coordinate systems.

Parameters:

  • SwA (xarray) – Swarm A and C datasets.

  • SwC (xarray) – Swarm A and C datasets.

  • pole_lat (float) – Latitude and longitude of the new pole in the old coordinates, [degree].

  • pole_lon (float) – Latitude and longitude of the new pole in the old coordinates, [degree].

Returns:

SwA, SwC – Swarm A and C datasets including data rotated to the magnetic coordinate system.

Return type:

xarray

swarmpal.toolboxes.dsecs.dsecs_algorithms.trim_data(SwA, SwC)[source]#

Finds a period with suitable spaceraft velocity for analysis.

Parameters:

  • SwA (xarray) – Swarm A and C datasets.

  • SwC (xarray) – Swarm A and C datasets.

Returns:

SwA, SwC – Swarm A and C datasets trimmed to the suitable period.

Return type:

xarray

swarmpal.toolboxes.dsecs.dsecs_algorithms.get_exclusion_zone(SwA, SwC)[source]#
class swarmpal.toolboxes.dsecs.dsecs_algorithms.dsecsdata[source]#

Class for DSECS variables and fitting procedures

lonB#
latB#
rB#
Bt#
Bp#
Br#
Bpara#
uvR#
uvT#
uvP#
grid: dsecsgrid#
alpha1Ddf: float = 1e-05#
epsSVD1Ddf: float = 0.0004#
alpha1Dcf: float = 0.0002#
epsSVD1Dcf: float = 0.01#
alpha2D: float = 0.0005#
epsSVD2D: float = 0.001#
epsSVD2dcf: float = 0.002#
alpha2Dcf: float = 1.0#
df1D#
df2D#
cf1D#
cf2D#
df2dBr#
df2dBp#
df2dBt#
df1dBt#
df1dBr#
matBr1Ddf#
matBt1Ddf#
df1DJp#
matBpara1D#
matBpara2D#
apexlats#
cf1dDipMagJp#
cf1dDipMagJt#
cf1dDipJr#
cf1dDipBr#
cf1dDipMagBt#
cf1dDipMagBp#
cf2dDipMagJp#
cf2dDipMagJt#
cf2dDipJr#
cf2dDipBr#
cf2dDipMagBt#
cf2dDipMagBp#
matBp2Ddf#
matBt2Ddf#
matBr2Ddf#
df2dMagJt#
df2dMagJp#
remoteCf2dDipMagBr#
remoteCf2dDipMagBt#
remoteCf2dDipMagBp#
remoteCf2dDipMagJp#
remoteCf2dDipMagJt#
remoteCf2dDipMagJr#
test#
flag = 0#
QDlats#
apexcrossingA: float = 0#
apexcrossingC: float = 0#
exclusionmax = 0#
exclusionmin = 0#
SwA = None#
SwC = None#
populate(SwA, SwC)[source]#

Initializes a DSECS analaysis case from Swarm data.

Parameters:

  • SwA (xarray) – Swarm A and C datasets.

  • SwC (xarray) – Swarm A and C datasets.

fit1D_df()[source]#

1D divergence-free fitting.

fit2D_df()[source]#

2D divergence-free fitting.

analyze()[source]#

Perform the DSECS analysis steps.

fit1D_cf()[source]#

1D curl-free fitting.

fit2D_cf()[source]#

2D curl-free fitting.

dump()[source]#

Dump the currents to xarrays.

Returns:

  • dsmag – xarray of the results in the magnetic coordinate system.

  • dsgeo – xarray of the results in geographic coordinate system.

  • fitA – xarray with fitted magnetic field for Swarm A

  • fitC – xarray with fitted magnetic field for Swarm C

Contents