26297372401

Committed 22 May 2026 03:41PM UTC coverage: 59.902% (-2.9%) from 62.79%

Build # 26297372401

Build Type

Pull #53

github

Committed by

web-flow

Commit Message

Merge f3fb329e0 into 23c1195a2

Pull Request Pull Request #53: Major refactor

Coverage Stats

1186 of 2005 new or added lines in 59 files covered. (59.15%)

14 existing lines in 5 files now uncovered.

2804 of 4681 relevant lines covered (59.9%)

0.6 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

41.38

/el_paso/processing/compute_equatorial_plasmaspheric_density.py

# SPDX-FileCopyrightText: 2025 GFZ Helmholtz Centre for Geosciences
# SPDX-FileContributor: Bernhard Haas
#
# SPDX-License-Identifier: Apache-2.0

import logging
import typing
from typing import Literal

import astropy.units as u
import numpy as np

import el_paso as ep
from el_paso.utils import timed_function

if typing.TYPE_CHECKING:
    from numpy.typing import NDArray

logger = logging.getLogger(__name__)

DENTON_DENSITY_UPPER_LIMIT = 1500
MAX_ALPHA = 5


@timed_function("Density mapping")
def compute_equatorial_plasmaspheric_density(
    density_var: ep.Variable,
    xgeo_local_var: ep.Variable,
    xgeo_equatorial_var: ep.Variable,
    method: Literal["Denton_average"] = "Denton_average",
) -> ep.Variable:
    r"""Maps the plasma density from a local measurement point to the magnetic equator.

    This function uses a simple empirical model to map plasma density measured
    at a specific local position to the magnetic equator. The mapping is based
    on a power-law density profile, $n(r) = n_{eq} (r / r_{eq})^{-\alpha}$,
    where the exponent $\alpha$ is determined by the chosen method.

    Args:
        density_var (ep.Variable): The input variable containing the local
            plasma density data, expected in units convertible to $cm^{-3}$.
        xgeo_local_var (ep.Variable): The variable containing the GEO coordinates
            corresponding to the density measurements.
        xgeo_equatorial_var (ep.Variable): The variable containing the GEO
            coordinates of the corresponding magnetic field line foot-point
            at the magnetic equator.
        method (Literal["Denton_average"], optional): The method used
            to calculate the power-law exponent $\alpha$.
            - "Denton_average" (default): Uses a fixed average $\\alpha$: $2.5$ inside the
              plasmasphere (density $\ge 10 \cdot (6.6 / r_{eq})^4$) and $0.5$
              outside the plasmasphere. This is an approximation based on Sheeley et al. (2001).

    Returns:
        ep.Variable: A new variable containing the plasma density mapped to the
            magnetic equator, with units of $cm^{-3}$.
    """
    logger.info("Computing equatorial plasmaspheric density...")

    r_local = np.linalg.norm(xgeo_local_var.get_data(ep.units.RE).astype(np.float64), ord=2, axis=1)
    r_eq = np.linalg.norm(xgeo_equatorial_var.get_data(ep.units.RE).astype(np.float64), ord=2, axis=1)
    r_local = typing.cast("NDArray[np.float32]", r_local)
    r_eq = typing.cast("NDArray[np.float32]", r_eq)

    density_data = density_var.get_data(u.cm ** (-3)).astype(np.float64)

    mapped_density_var = ep.Variable(original_unit=u.cm ** (-3))
    mapped_density_var.metadata.source_files = density_var.metadata.source_files

    match method:
        case "Denton_average":
            inside_pp = density_data >= 10 * (6.6 / r_eq) ** 4

            alpha = np.full_like(density_data, 0.5)
            alpha[inside_pp] = 2.5

            density_eq_data = density_data / (r_eq / r_local) ** alpha

            mapped_density_var.metadata.add_processing_note(
                "Mapped to the equator using 'compute_equatorial_plasmaspheric_density' assuming the Denton average "
                "approximation with alpha=2.5 inside the plasmasphere (according to the criterion used in "
                "Sheeley et al. 2001) and alpha=1 outside the plasmasphere."
            )

    mapped_density_var.set_data(density_eq_data, u.cm ** (-3))

    return mapped_density_var

1	# SPDX-FileCopyrightText: 2025 GFZ Helmholtz Centre for Geosciences
2	# SPDX-FileContributor: Bernhard Haas
3	#
4	# SPDX-License-Identifier: Apache-2.0
5
6	import logging	1✔
7	import typing	1✔
8	from typing import Literal	1✔
9
10	import astropy.units as u	1✔
11	import numpy as np	1✔
12
13	import el_paso as ep	1✔
14	from el_paso.utils import timed_function	1✔
15
16	if typing.TYPE_CHECKING:
17	from numpy.typing import NDArray
18
19	logger = logging.getLogger(__name__)	1✔
20
21	DENTON_DENSITY_UPPER_LIMIT = 1500	1✔
22	MAX_ALPHA = 5	1✔
23
24
25	@timed_function("Density mapping")	1✔
26	def compute_equatorial_plasmaspheric_density(	1✔
27	density_var: ep.Variable,
28	xgeo_local_var: ep.Variable,
29	xgeo_equatorial_var: ep.Variable,
30	method: Literal["Denton_average"] = "Denton_average",
31	) -> ep.Variable:
32	r"""Maps the plasma density from a local measurement point to the magnetic equator.
33
34	This function uses a simple empirical model to map plasma density measured
35	at a specific local position to the magnetic equator. The mapping is based
36	on a power-law density profile, $n(r) = n_{eq} (r / r_{eq})^{-\alpha}$,
37	where the exponent $\alpha$ is determined by the chosen method.
38
39	Args:
40	density_var (ep.Variable): The input variable containing the local
41	plasma density data, expected in units convertible to $cm^{-3}$.
42	xgeo_local_var (ep.Variable): The variable containing the GEO coordinates
43	corresponding to the density measurements.
44	xgeo_equatorial_var (ep.Variable): The variable containing the GEO
45	coordinates of the corresponding magnetic field line foot-point
46	at the magnetic equator.
47	method (Literal["Denton_average"], optional): The method used
48	to calculate the power-law exponent $\alpha$.
49	- "Denton_average" (default): Uses a fixed average $\\alpha$: $2.5$ inside the
50	plasmasphere (density $\ge 10 \cdot (6.6 / r_{eq})^4$) and $0.5$
51	outside the plasmasphere. This is an approximation based on Sheeley et al. (2001).
52
53	Returns:
54	ep.Variable: A new variable containing the plasma density mapped to the
55	magnetic equator, with units of $cm^{-3}$.
56	"""
57	logger.info("Computing equatorial plasmaspheric density...")	×
58
59	r_local = np.linalg.norm(xgeo_local_var.get_data(ep.units.RE).astype(np.float64), ord=2, axis=1)	×
60	r_eq = np.linalg.norm(xgeo_equatorial_var.get_data(ep.units.RE).astype(np.float64), ord=2, axis=1)	×
61	r_local = typing.cast("NDArray[np.float32]", r_local)	×
62	r_eq = typing.cast("NDArray[np.float32]", r_eq)	×
63
NEW 64	density_data = density_var.get_data(u.cm ** (-3)).astype(np.float64)	×
65
NEW 66	mapped_density_var = ep.Variable(original_unit=u.cm ** (-3))	×
67	mapped_density_var.metadata.source_files = density_var.metadata.source_files	×
68
69	match method:	×
70	case "Denton_average":	×
71	inside_pp = density_data >= 10 * (6.6 / r_eq) ** 4	×
72
73	alpha = np.full_like(density_data, 0.5)	×
74	alpha[inside_pp] = 2.5	×
75
76	density_eq_data = density_data / (r_eq / r_local) ** alpha	×
77
78	mapped_density_var.metadata.add_processing_note(	×
79	"Mapped to the equator using 'compute_equatorial_plasmaspheric_density' assuming the Denton average "
80	"approximation with alpha=2.5 inside the plasmasphere (according to the criterion used in "
81	"Sheeley et al. 2001) and alpha=1 outside the plasmasphere."
82	)
83
NEW 84	mapped_density_var.set_data(density_eq_data, u.cm ** (-3))	×
85
86	return mapped_density_var	×

GFZ / EL_PASO / 26297372401

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous