Line data    Source code

       1             : # SPDX-FileCopyrightText: 2025 PairInteraction Developers
       2             : # SPDX-License-Identifier: LGPL-3.0-or-later
       3           1 : from __future__ import annotations
       4             : 
       5           1 : from typing import TYPE_CHECKING, overload
       6             : 
       7           1 : from pairinteraction.perturbative.effective_system_pair import EffectiveSystemPair, EffectiveSystemPairReal
       8           1 : from pairinteraction.units import QuantityScalar
       9             : 
      10             : if TYPE_CHECKING:
      11             :     from pairinteraction.ket import KetAtom
      12             :     from pairinteraction.units import PintFloat
      13             : 
      14             : 
      15           1 : class C3(EffectiveSystemPair):
      16             :     """Class for calculating the C3 coefficient between two states.
      17             : 
      18             :     Given two `KetAtom` objects ket1 and ket2,
      19             :     this class computes the C3 coefficient between ``|ket1, ket2>`` and ``|ket2, ket1>``.
      20             :     This class also allows to set magnetic and electric fields similar to the `SystemAtom` class,
      21             :     as well as the angle between the two atoms like in the `SystemPair` class.
      22             : 
      23             :     Examples:
      24             :         >>> import pairinteraction as pi
      25             :         >>> ket1 = pi.KetAtom("Rb", n=60, l=0, j=0.5, m=0.5)
      26             :         >>> ket2 = pi.KetAtom("Rb", n=61, l=1, j=1.5, m=0.5)
      27             :         >>> c3_obj = pi.C3(ket1, ket2)
      28             :         >>> c3 = c3_obj.get(unit="planck_constant * MHz * micrometer^3")
      29             :         >>> print(f"{c3:.2f}")
      30             :         -93.29
      31             : 
      32             :     """
      33             : 
      34           1 :     def __init__(self, ket1: KetAtom, ket2: KetAtom) -> None:
      35           1 :         super().__init__([(ket1, ket2), (ket2, ket1)])
      36           1 :         self.set_perturbation_order(1)
      37             : 
      38             :         # Set some default distance. The exact value does not matter for the C3 value
      39           1 :         self.set_distance(100, unit="micrometer")
      40             : 
      41             :     @overload
      42             :     def get(self, unit: None = None) -> PintFloat: ...
      43             : 
      44             :     @overload
      45             :     def get(self, unit: str) -> float: ...
      46             : 
      47           1 :     def get(self, unit: str | None = None) -> float | PintFloat:
      48             :         """Get the C3 coefficient of the pair interaction between the specified ket1 and ket2.
      49             : 
      50             :         Args:
      51             :             unit: The unit in which to return the C3 coefficient.
      52             :                 If None, returns a pint object.
      53             : 
      54             :         """
      55           1 :         h_eff_pint = self.get_effective_hamiltonian(return_order=1)
      56           1 :         distance = self.system_pair.get_distance()
      57           1 :         c3_pint = h_eff_pint[1, 0] * distance**3  # type: ignore [index]  # pint does not know it can be indexed
      58           1 :         return QuantityScalar.convert_pint_to_user(c3_pint, "c3", unit)
      59             : 
      60             : 
      61           1 : class C3Real(C3, EffectiveSystemPairReal):
      62           1 :     pass