pysecs

pysecs is an open-source library for calculating Spherical Elementary Current Systems (SECS).

Features

• Based upon the scikit-learn framework with fit() and predict() methods.
• The only dependency is NumPy. It is built using fast broadcasting techniques to provide highly scalable calculations.
• Divergence-free and curl-free systems, including the curl-free magnetic field for observations above the current shell (satellite altitudes).
• Uncertainty propagation: amplitude variances and prediction variance maps (predict(..., return_var=True)).
• Robust fitting (fit(..., robust='huber'|'bisquare')) that automatically downweights localized single-station disturbances.
• Temporal estimation with KalmanSECS: a Kalman filter / smoother over the SEC amplitudes with innovation gating for impulsive outliers.
• Automatic SECS grid generation from an observation network (SECS.from_observations(obs_loc, r_shell)), with sensible defaults for spacing and padding and a guard against poles landing on a station.

Examples

Examples can be found in examples/

Install

The easiest method to install pysecs is with pip.

> pip install pysecs

For a source install you can follow these instructions:

1. Clone the git repository

   > git clone https://github.com/greglucas/pysecs

2. Build and install the package

   > pip install .

3. Testing The package has a test suite that can be run with pytest

   > pytest

License

The code is released under an MIT license License described in LICENSE.md

References

This package has been developed from different publications. Please consider citing the papers that are relevant to the work you are doing if you are utilizing this code.

Software

Lucas, G., Rigler, E. J., Murphy, B. (2024). greglucas/pysecs: REL: v0.3.0 (v0.3.0).
Zenodo. https://doi.org/10.5281/zenodo.14511596

Original Paper

Amm, O. "Ionospheric Elementary Current Systems in Spherical Coordinates and Their Application."
Journal of geomagnestism and geoelectricity 49.7 (1997): 947-955. doi:10.5636/jgg.49.947

Applications Paper

Amm, O., and A. Viljanen. "Ionospheric disturbance magnetic field continuation
from the ground to the ionosphere using spherical elementary current systems."
Earth, Planets and Space 51.6 (1999): 431-440. doi:10.1186/BF03352247

Review Chapter (curl-free magnetic field)

The magnetic field of the curl-free system (Equation 2.15) implemented in this package is given in this review chapter.

Vanhamäki, H., and L. Juusola. "Introduction to Spherical Elementary Current Systems."
Ionospheric Multi-Spacecraft Analysis Tools, ISSI Scientific Report Series 17 (2020): 5-33.
doi:10.1007/978-3-030-26732-2_2

Problems or Questions

• Report an issue using the GitHub issue tracker