diffusion¶
- piran.diffusion.get_DnX_single_root(
- cpdr: Cpdr,
- resonant_root: ResonantRoot,
- normalised_intensity: Annotated[Quantity, Unit('m3 T2 / rad')],
- phi_squared: Annotated[Quantity, Unit(dimensionless)],
- singular_term: Annotated[Quantity, Unit('m / s')],
Calculates the diffusion coefficients in pitch angle DnXaa, mixed pitch angle-momentum DnXap and momentum DnXpp, for a given resonant root, as defined in equations 11, 12 and 13 in Glauert & Horne 2005.
- Parameters:
- cpdrpiran.cpdr.Cpdr
Cold plasma dispersion relation object.
- resonant_rootpiran.cpdr.ResonantRoot object
NamedTuple object containing a resonant root, i.e., root to both dispersion relation and resonance condition.
- normalised_intensityastropy.units.quantity.Quantity[UNIT_BKN]
Normalised intensity \(|B_{k}^{norm}|^2\)
- phi_squaredastropy.units.quantity.Quantity[u.dimensionless_unscaled]
Phi_{n,k}^2.
- singular_termastropy.units.quantity.Quantity[u.m / u.s]
v_par - d(omega) / d(k_par)
- Returns:
- DnXaa, DnXap, DnXpptuple
Pitch angle, mixed pitch angle-momentum and momentum diffusion coefficients for a given resonant root. Note that since these are wrapped in a tuple, it appears that the @u.quantity_input decorator does not actually check these! There is an appropriate test in place in test_diffusion.py to check the validity of these outputs.
- piran.diffusion.get_diffusion_coefficients(
- X_range: Annotated[Quantity, Unit(dimensionless)],
- DnX_single_res: Annotated[Quantity, Unit('kg2 m2 / s3')],
Given an array of wave normal angles and an an identically-sized array of outputs from Equation 11, 12, or 13, calculate $int_{X_min}^{X_max} X D_{alpha alpha}^{nX} dX$, i.e. the integral part from equations 8, 9 or 10 in Glauert & Horne 2005. No summation over different resonances happens in this function. Note: For the integration we use Simpson’s rule.
- Parameters:
- X_rangeastropy.units.quantity.Quantity[u.dimensionless_unscaled]
Array of wave normal angles.
- DnX_single_resastropy.units.quantity.Quantity[UNIT_DIFF]
Array of diffusion coefficients for a specific resonance, one per X (i.e. calculated values from equations 11, 12 or 13 in Glauert & Horne 2005).
- Returns:
- integralastropy.units.quantity.Quantity[UNIT_DIFF[]]
Either $D_{alpha alpha}$ or $D_{alpha p}$ ($D_{p alpha}$) or $D_{pp}$, i.e. equations 8, 9 and 10 from Glauert 2005) for a single resonance.
- piran.diffusion.get_energy_diffusion_coefficient(
- rel_kin_energy: Annotated[Quantity, Unit('J')],
- rest_mass_energy: Annotated[Quantity, Unit('J')],
- momentum_diff_coef: Annotated[Quantity, Unit('kg2 m2 / s3')],
Given relativistic kinetic energy, rest mass energy and relativistic momentum diffusion coefficient calculate the energy diffusion coefficient from equation 29 in Glauert & Horne 2005.
- Parameters:
- rel_kin_energyastropy.units.quantity.Quantity.Quantity[Joule],
Relativistic kinetic energy.
- rest_mass_energyastropy.units.quantity.Quantity.Quantity[Joule],
Rest mass energy.
- momentum_diff_coefastropy.units.quantity.Quantity[UNIT_DIFF]
Momentum diffusion coefficient $D_{pp}$.
- Returns:
- energy_diff_coefastropy.units.quantity.Quantity[u.J**2 / u.s]
Energy diffusion coefficient $D_{EE}$.
- piran.diffusion.get_mixed_aE_diffusion_coefficient(
- rel_kin_energy: Annotated[Quantity, Unit('J')],
- rest_mass_energy: Annotated[Quantity, Unit('J')],
- mixed_ap_diff_coef: Annotated[Quantity, Unit('kg2 m2 / s3')],
Given relativistic kinetic energy, rest mass energy and mixed pitch angle-momentum diffusion coefficient calculate the mixed pitch angle-energy diffusion coefficient from equation 30 in Glauert & Horne 2005.
- Parameters:
- rel_kin_energyastropy.units.quantity.Quantity.Quantity[Joule],
Relativistic kinetic energy.
- rest_mass_energyastropy.units.quantity.Quantity.Quantity[Joule],
Rest mass energy.
- mixed_ap_diff_coefastropy.units.quantity.Quantity[UNIT_DIFF]
Mixed pitch angle-momentum diffusion coefficient $D_{pp}$.
- Returns:
- mixed_aE_diff_coefastropy.units.quantity.Quantity[u.J**2 / u.s]
Mixed pitch angle-energy diffusion coefficient $D_{aE}$.
- piran.diffusion.get_normalised_intensity(
- power_spectral_density: Annotated[Quantity, Unit('T2 s / rad')],
- wave_norm_angle_dist_eval,
- norm_factor: Annotated[Quantity, Unit('s / m3')],
Calculates the normalised intensity \(|B_{k}^{norm}|^2\).
Depending on the input parameters, this is either equation 4b or 5b from Cunningham 2023. Equation 5b is used in Glauert & Horne 2005, while equation 4b is the proposed method by Cunningham. If we are calculating equation 5b, then norm_factor is computed by the compute_glauert_norm_factor() function in the piran package, which returns the N(omega) term in the denominator of 5b, while if we are calculating equation 4b, then norm_factor shall be computed by piran’s compute_cunningham_norm_factor() function which returns the denominator in 4b. Note that wave_norm_angle_dist_eval must be normalised if we are calculating equation 4b (Cunningham’s proposed method).
- Parameters:
- power_spectral_densityastropy.units.quantity.Quantity[UNIT_PSD]
Power spectral density B^2(omega).
- wave_norm_angle_dist_eval
Wave normal angle distribution evaluated at X.
- norm_factorastropy.units.quantity.Quantity[UNIT_NF]
Normalisation factor.
- Returns:
- normalised_intensityastropy.units.quantity.Quantity[UNIT_BKN]
Normalised intensity \(|B_{k}^{norm}|^2\)
- piran.diffusion.get_phi_squared(
- cpdr: Cpdr,
- resonant_root: ResonantRoot,
Calculate Phi_{n,k}^2 from equation A13 in Glauert & Horne 2005.
- Parameters:
- cpdrpiran.cpdr.Cpdr
Cold plasma dispersion relation object.
- resonant_rootpiran.cpdr.ResonantRoot object
NamedTuple object containing a resonant root, i.e., root to both dispersion relation and resonance condition.
- Returns:
- phi_squaredastropy.units.quantity.Quantity[u.dimensionless_unscaled]
Phi_{n,k}^2.
- piran.diffusion.get_power_spectral_density(
- cpdr: Cpdr,
- wave_amplitude: Annotated[Quantity, Unit('T')],
- omega: Annotated[Quantity, Unit('rad / s')],
Calculate the power spectral density B_squared(omega) term from equation 5 in Glauert & Horne 2005, in units T^2 * s / rad.
- Parameters:
- cpdrpiran.cpdr.Cpdr
Cold plasma dispersion relation object.
- wave_amplitudeastropy.units.quantity.Quantity[u.T]
Wave ampltitude.
- omegaastropy.units.quantity.Quantity[u.rad / u.s]
Wave frequency.
- Returns:
- power_spectral_densityastropy.units.quantity.Quantity[UNIT_PSD]
Power spectral density.
- piran.diffusion.get_singular_term(
- cpdr: Cpdr,
- resonant_root: ResonantRoot,
Calculate the denominator from the last term in equation 11 in Glauert & Horne 2005. The term is v_par - d(omega) / d(k_par) evaluated at signed k_par and is returned without taking its absolute value. More specifically, the term is v_par - (- (dD/dk) / (dD/domega) ) * (1 / cos(psi)), with cos(psi) = ± 1 / sqrt(1 + X^2). cos(psi) = + 1 / sqrt(1 + X^2) if psi in [0, 90] (or equivalently, k_par pos) cos(psi) = - 1 / sqrt(1 + X^2) if psi in (90, 180] (or equivalently, k_par neg).
- Parameters:
- cpdrpiran.cpdr.Cpdr
Cold plasma dispersion relation object.
- resonant_rootpiran.cpdr.ResonantRoot object
NamedTuple object containing a resonant root, i.e., root to both dispersion relation and resonance condition.
- Returns:
- singular_termastropy.units.quantity.Quantity[u.m / u.s]