solarwindpy.core.ions.Ion

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