swarmpal.toolboxes.fac.fac_algorithms
=====================================

.. py:module:: swarmpal.toolboxes.fac.fac_algorithms

.. autoapi-nested-parse::

   Tools to evaluate FACs using the single-satellite method

   Given input containing magnetic field measurements and model predictions, compute the FACs

   Adapted from code by Ask Neve Gamby (https://github.com/Swarm-DISC/SwarmPyFAC).
   For information about the algorithm, see https://doi.org/10.5047/eps.2013.09.006



Attributes
----------

.. autoapisummary::

   swarmpal.toolboxes.fac.fac_algorithms.logger
   swarmpal.toolboxes.fac.fac_algorithms.MU_0


Functions
---------

.. autoapisummary::

   swarmpal.toolboxes.fac.fac_algorithms._means
   swarmpal.toolboxes.fac.fac_algorithms._spherical_delta
   swarmpal.toolboxes.fac.fac_algorithms._NEC_to_VSC
   swarmpal.toolboxes.fac.fac_algorithms._radial_current
   swarmpal.toolboxes.fac.fac_algorithms._interpolate_data
   swarmpal.toolboxes.fac.fac_algorithms._inclination
   swarmpal.toolboxes.fac.fac_algorithms.fac_single_sat_algo


Module Contents
---------------

.. py:data:: logger

.. py:data:: MU_0

.. py:function:: _means(x)

.. py:function:: _spherical_delta(p)

   Compute the change of spherical positions as an NEC vector


.. py:function:: _NEC_to_VSC(v)

   Construct a function which transforms vectors from NEC to VSC frame


.. py:function:: _radial_current(dB, v, dt)

   Calculate radial currents from magnetic residuals and spacecraft velocity


.. py:function:: _interpolate_data(t_source, t_target)

   Interpolate data from original sampling on t_source to new sampling on t_target


.. py:function:: _inclination(v)

.. py:function:: fac_single_sat_algo(time=None, positions=None, B_res=None, B_model=None, inclination_limit=30.0, time_jump_limit=1)

   Compute field-aligned current (FAC) from numpy arrays

   :param time: Array of datetime64[ns]
   :type time: array_like
   :param positions: Nx3 array of positions (Latitude, Longitude, Radius) in units of (degrees, degrees, metres)
   :type positions: array_like
   :param B_res: Nx3 array of magnetic field residuals in nanoTesla
   :type B_res: array_like
   :param B_model: Nx3 array of magnetic field model predictions in nanoTesla
   :type B_model: array_like
   :param inclination_limit: Limit of inclination for FAC validity
   :type inclination_limit: float, optional
   :param time_jump_limit: Maximum allowable time step in data for FAC validity
   :type time_jump_limit: int, optional

   :returns: {"time": array_like, "fac": array_like, "irc": array_like}
             FAC (field-aligned current) and IRC (radial current) estimates
   :rtype: dict