solarwindpy.core.ions

Contains Ion class.

This module defines the Ion class, which inherits from the Base class and contains Vector and Tensor objects.

Classes

Ion(data, species)

Container for a single ion species.

class Ion(data: DataFrame, species: str)[source]

Bases: Base

Container for a single ion species.

Parameters:

data (pandas.DataFrame) – Data for the ion in the form ("M", "C") where M is the measurement type (n, v, w) and C is the component.
species (str) – Species identifier, e.g. "p" for protons or "a" for alpha particles.

species

The ion’s species name.

Type:: str

__init__(data: DataFrame, species: str)[source]

Initialize an Ion instance with plasma measurement data.

Parameters:

data (pandas.DataFrame) – Ion measurement data with MultiIndex columns formatted as (“M”, “C”) where M is measurement type (n, v, w, T) and C is component (x, y, z, par, per, etc.).
species (str) – Ion species identifier following standard conventions: - ‘p1’ or ‘p’ for protons - ‘a’ for alpha particles (He2+) - ‘o6’ for O6+ ions - Other species as needed

Notes

The Ion class provides access to fundamental plasma measurements:

n: Number density [cm^-3]
v: Velocity vector [km/s]
w: Thermal speed [km/s] (assumes mw² = 2kT)
T: Temperature [K] (derived from thermal speed)

Physical constants and mass values are automatically assigned based on the species identifier using standard atomic masses.

Examples

Create a proton ion from measurement data:

>>> import pandas as pd
>>> import numpy as np
>>> columns = pd.MultiIndex.from_tuples([
...     ('n', '', 'p1'),
...     ('v', 'x', 'p1'), ('v', 'y', 'p1'), ('v', 'z', 'p1'),
...     ('w', 'par', 'p1'), ('w', 'per', 'p1')
... ], names=['M', 'C', 'S'])
>>> df = pd.DataFrame(np.random.rand(2, 6), columns=columns)
>>> proton_data = df.xs('p1', level='S', axis=1)
>>> proton = Ion(proton_data, 'p1')
>>> proton.species
'p1'

set_species(species: str) → None[source]

Set the species of the ion.

Parameters:: species (str) – The species of the ion.
Raises:: ValueError – If the species contains a ‘+’ character.

set_data(data: DataFrame) → None[source]

Set the data for the ion.

Parameters:: data (pd.DataFrame) – The data to set for the ion.
Raises:: ValueError – If the data column names are unrecognized.

property species: str: Get the ion species.

property velocity: Vector: Get the ion’s velocity as a Vector.

property v: Vector: Alias for velocity property.

property thermal_speed: Tensor: Get the ion’s thermal speed as a Tensor.

property w: Tensor: Alias for thermal_speed property.

property number_density: Series: Get the number density of the ion.

property n: Series: Alias for number_density property.

property mass_density: Series: Calculate the ion’s mass density.

property rho: Series: Alias for mass_density property.

property anisotropy: Series

Calculate temperature anisotropy R_T = p_⟂/p_∥.

Returns:: Temperature anisotropy.
Return type:: pd.Series

property temperature: DataFrame

Calculate temperature T = (m / (2 * k_B)) * w^2.

Returns:: Temperature of the ion.
Return type:: pd.DataFrame

property pth: DataFrame

Calculate thermal pressure p_th = 0.5 * ρ * w^2.

Returns:: Thermal pressure.
Return type:: pd.DataFrame

property cs: DataFrame

Calculate the species’ sound speed.

Returns:: Sound speed of the ion species.
Return type:: pd.DataFrame

property specific_entropy: Series

Calculate the specific entropy S = p_th * ρ^(-γ).

Returns:: Specific entropy of the ion.
Return type:: pd.Series

References

Siscoe, G. L. (1983). Solar System Magnetohydrodynamics (pp. 11-100). https://doi.org/10.1007/978-94-009-7194-3_2

property S: Series: Alias for specific_entropy property.

property kinetic_energy_flux

Calculate the kinetic energy flux.

The kinetic energy flux is calculated as:

\[W_k = \frac{1}{2} \rho v^3\]

Returns:: Kinetic energy flux.
Return type:: pd.Series

property Wk: Shortcut to kinetic_energy_flux.

property constants: Constants

Physical constants.

Returns:: Physical constants instance.
Return type:: uc.Constants

property data: DataFrame

Underlying DataFrame containing the data.

Returns:: Data with MultiIndex columns.
Return type:: pd.DataFrame

head()

Return the first few rows of the data.

Returns:: First few rows of the data.
Return type:: pd.DataFrame

property logger: Logger

Logger instance for this object.

Returns:: Logger instance.
Return type:: logging.Logger

static mi_tuples(x: Tuple[Tuple[str, ...], ...]) → MultiIndex

Create a MultiIndex from tuples with appropriate names.

Parameters:: x (Tuple[Tuple[str, ...], ...]) – Tuples to create MultiIndex from.
Returns:: MultiIndex created from tuples.
Return type:: MI

tail()

Return the last few rows of the data.

Returns:: Last few rows of the data.
Return type:: pd.DataFrame

property units: Units

Units conversion factors.

Returns:: Units conversion instance.
Return type:: uc.Units