# Copyright © 2024-2025 HQS Quantum Simulations GmbH. All Rights Reserved.
# LICENSE PLACEHOLDER
"""Collection of functions and constants for conversion between units."""
from __future__ import annotations
import numpy as np
from typing import Any
from hqs_nmr.datatypes import Isotope, GYROMAGNETIC_RATIOS, NMRCalculationParameters
DEFAULT_REFERENCE_ISOTOPE = Isotope(1, "H")
# Collection of useful constants and units
k_boltzmann_J_per_K = 1.380649e-23
h_planck_J_s = 6.62607015e-34
[docs]
def field_T_to_frequency_MHz(
field_T: float,
reference_isotope: Isotope = DEFAULT_REFERENCE_ISOTOPE,
gyromagnetic_ratios: dict[Isotope, float] = GYROMAGNETIC_RATIOS,
) -> float:
"""Convert field in Tesla to a reference frequency in MHz with respect to specified isotope.
Args:
field_T: Magnetic field in Tesla.
reference_isotope: Reference isotope for the conversion.
gyromagnetic_ratios: Dictionary of gyromagnetic ratios in rad / (T s).
Returns:
Reference frequency.
"""
return (field_T * gyromagnetic_ratios[reference_isotope]) / (1e6 * 2 * np.pi)
[docs]
def frequency_MHz_to_field_T(
frequency_MHz: float,
reference_isotope: Isotope = DEFAULT_REFERENCE_ISOTOPE,
gyromagnetic_ratios: dict[Isotope, float] = GYROMAGNETIC_RATIOS,
) -> float:
"""Convert reference frequency in MHz with respect to specified isotope to field in Tesla.
Args:
frequency_MHz: Reference energy in MHz.
reference_isotope: Reference isotope for the conversion.
gyromagnetic_ratios: Dictionary of gyromagnetic ratios in rad / (T s).
Returns:
Reference frequency.
"""
return (frequency_MHz * 1e6 * 2 * np.pi) / gyromagnetic_ratios[reference_isotope]
[docs]
def rad_per_s_to_ppm(variable: Any, calculation_parameters: NMRCalculationParameters) -> Any:
"""Convert variable from rad / s to ppm.
Args:
variable: Variable to be converted.
calculation_parameters: Calculation parameters used for the calculation. Contains the
reference isotope and gyromagnetic ratios as well as the magnetic field.
Returns:
Converted variable.
"""
reference_frequency_rad_per_s = calculation_parameters.reference_frequency_rad_per_s
return variable / (reference_frequency_rad_per_s * 1e-6)
[docs]
def ppm_to_rad_per_s(variable: Any, calculation_parameters: NMRCalculationParameters) -> Any:
"""Convert variable from ppm to rad / s.
Args:
variable: Variable to be converted.
calculation_parameters: Calculation parameters used for the calculation. Contains the
reference isotope and gyromagnetic ratios as well as the magnetic field.
Returns:
Converted variable.
"""
reference_frequency_rad_per_s = calculation_parameters.reference_frequency_rad_per_s
return variable * (reference_frequency_rad_per_s * 1e-6)
[docs]
def Hz_to_ppm(variable: Any, calculation_parameters: NMRCalculationParameters) -> Any:
"""Convert variable from Hz to ppm.
Args:
variable: Variable to be converted.
calculation_parameters: Calculation parameters used for the calculation. Contains the
reference isotope and gyromagnetic ratios as well as the magnetic field.
Returns:
Converted variable.
"""
reference_frequency_rad_per_s = calculation_parameters.reference_frequency_rad_per_s
return variable * 2 * np.pi / (reference_frequency_rad_per_s * 1e-6)
[docs]
def ppm_to_Hz(variable: Any, calculation_parameters: NMRCalculationParameters) -> Any:
"""Convert variable from ppm to Hz.
Args:
variable: Variable to be converted.
calculation_parameters: Calculation parameters used for the calculation. Contains the
reference isotope and gyromagnetic ratios as well as the magnetic field.
Returns:
Converted variable.
"""
reference_frequency_rad_per_s = calculation_parameters.reference_frequency_rad_per_s
return variable * (reference_frequency_rad_per_s * 1e-6) / (2 * np.pi)
[docs]
def rad_per_s_to_Hz(variable: Any) -> Any:
"""Convert variable from rad / s to Hz.
Args:
variable: Variable to be converted.
Returns:
Converted variable.
"""
return variable / (2 * np.pi)
[docs]
def Hz_to_rad_per_s(variable: Any) -> Any:
"""Convert variable from Hz to rad / s.
Args:
variable: Variable to be converted.
Returns:
Converted variable.
"""
return variable * 2 * np.pi