pairinteraction · johannes-moegerle · Mar 10, 2026 · Mar 10, 2026 · Mar 10, 2026 · Mar 10, 2026
diff --git a/README.md b/README.md
@@ -86,6 +86,22 @@ Then, similarly to `rydstate.species.sqdt.rubidium.py` you can define the quantu
 Finally, you can use the custom species by simply calling `rydstate.RydbergStateSQDTAlkali("Custom_Rb", n=50, l=0, j=1/2, m=1/2)` (the code will look for all subclasses of `SpeciesObjectSQDT` until it finds one with the species name "Custom_Rb").
 
 
+## Contributors
+
+The software is currently maintained by:
+* [Johannes Mögerle]
+
+In addition, the following people contributed significantly to this software:
+* [Frederic Hummel] - Author of the MQDT.jl julia package, which the python implementation of the MQDT calculations in this package are based on, and from where the FModel parameters where taken.
+* [Sebastian Weber] - Input about the code structure and the Numerov implementation.
+
+We warmly welcome new contributions!
+
+[Johannes Mögerle]: https://github.com/johannes-moegerle
+[Frederic Hummel]: https://github.com/frederic-atom
+[Sebastian Weber]: https://github.com/seweber
+
+
 ## License
 
 The rydstate software is licensed under [LGPL v3][license-lgpl-link]. For more information, see [LICENSE.txt](https://github.com/pairinteraction/rydstate/blob/main/LICENSE.txt).
diff --git a/docs/api/angular.rst b/docs/api/angular.rst
@@ -0,0 +1,13 @@
+Angular module
+==============
+
+.. currentmodule:: rydstate
+
+.. autosummary::
+    :toctree: ../_autosummary/
+
+    angular.AngularKetLS
+    angular.AngularKetJJ
+    angular.AngularKetFJ
+    angular.AngularState
+    angular.utils
diff --git a/docs/api/basis.rst b/docs/api/basis.rst
@@ -0,0 +1,13 @@
+Rydberg Basis
+=============
+
+.. currentmodule:: rydstate
+
+.. autosummary::
+    :toctree: ../_autosummary/
+
+    BasisSQDTAlkali
+    BasisSQDTAlkalineLS
+    BasisSQDTAlkalineJJ
+    BasisSQDTAlkalineFJ
+    BasisMQDT
diff --git a/docs/api/mqdt/sr87.rst b/docs/api/mqdt/sr87.rst
@@ -0,0 +1,6 @@
+Strontium 87
+============
+
+.. automodule:: rydstate.species.mqdt.sr87
+    :members:
+    :member-order: bysource
diff --git a/docs/api/mqdt/sr88.rst b/docs/api/mqdt/sr88.rst
@@ -0,0 +1,6 @@
+Strontium 88
+============
+
+.. automodule:: rydstate.species.mqdt.sr88
+    :members:
+    :member-order: bysource
diff --git a/docs/api/mqdt/yb171.rst b/docs/api/mqdt/yb171.rst
@@ -0,0 +1,6 @@
+Ytterbium 171
+=============
+
+.. automodule:: rydstate.species.mqdt.yb171
+    :members:
+    :member-order: bysource
diff --git a/docs/api/mqdt/yb173.rst b/docs/api/mqdt/yb173.rst
@@ -0,0 +1,6 @@
+Ytterbium 173
+=============
+
+.. automodule:: rydstate.species.mqdt.yb173
+    :members:
+    :member-order: bysource
diff --git a/docs/api/mqdt/yb174.rst b/docs/api/mqdt/yb174.rst
@@ -0,0 +1,6 @@
+Ytterbium 174
+=============
+
+.. automodule:: rydstate.species.mqdt.yb174
+    :members:
+    :member-order: bysource
diff --git a/docs/api/radial.rst b/docs/api/radial.rst
@@ -0,0 +1,12 @@
+Radial module
+=============
+
+.. currentmodule:: rydstate
+
+.. autosummary::
+    :toctree: ../_autosummary/
+
+    radial.RadialKet
+    radial.Wavefunction
+    radial.Model
+    radial.numerov
diff --git a/docs/api/rydberg_states.rst b/docs/api/rydberg_states.rst
@@ -0,0 +1,14 @@
+Rydberg States
+==============
+
+.. currentmodule:: rydstate
+
+.. autosummary::
+    :toctree: ../_autosummary/
+
+    RydbergStateSQDT
+    RydbergStateSQDTAlkali
+    RydbergStateSQDTAlkalineLS
+    RydbergStateSQDTAlkalineJJ
+    RydbergStateSQDTAlkalineFJ
+    RydbergStateMQDT
diff --git a/docs/api/species_mqdt.rst b/docs/api/species_mqdt.rst
@@ -0,0 +1,20 @@
+MQDT Parameters
+===============
+
+.. currentmodule:: rydstate
+
+.. autosummary::
+    :toctree: ../_autosummary/
+
+    species.SpeciesObjectMQDT
+    species.FModel
+    species.FModelSQDT
+
+.. toctree::
+    :maxdepth: 1
+
+    mqdt/sr87
+    mqdt/sr88
+    mqdt/yb171
+    mqdt/yb173
+    mqdt/yb174
diff --git a/docs/api/species_sqdt.rst b/docs/api/species_sqdt.rst
@@ -0,0 +1,21 @@
+SQDT Parameters
+===============
+
+.. currentmodule:: rydstate
+
+.. autosummary::
+    :toctree: ../_autosummary/
+
+    species.SpeciesObjectSQDT
+    species.HydrogenTextBook
+    species.Hydrogen
+    species.Lithium
+    species.Sodium
+    species.Potassium
+    species.Rubidium
+    species.Cesium
+    species.Strontium87
+    species.Strontium88
+    species.Ytterbium171
+    species.Ytterbium173
+    species.Ytterbium174
diff --git a/docs/api_reference.rst b/docs/api_reference.rst
@@ -11,66 +11,12 @@ The RydState python API can be accessed via the ``rydstate`` module by
 
 All the available classes, methods and functions are documented below:
 
-.. currentmodule:: rydstate
-
-**Rydberg States**
-
-.. autosummary::
-    :toctree: _autosummary/
-
-       RydbergStateSQDT
-       RydbergStateSQDTAlkali
-       RydbergStateSQDTAlkalineLS
-       RydbergStateSQDTAlkalineJJ
-       RydbergStateSQDTAlkalineFJ
-
-**Rydberg Basis**
-
-.. autosummary::
-    :toctree: _autosummary/
-
-       BasisSQDTAlkali
-       BasisSQDTAlkalineLS
-       BasisSQDTAlkalineJJ
-       BasisSQDTAlkalineFJ
-
-**Angular module**
-
-.. autosummary::
-    :toctree: _autosummary/
-
-       angular.AngularKetLS
-       angular.AngularKetJJ
-       angular.AngularKetFJ
-       angular.AngularState
-       angular.utils
-
-
-**Radial module**
-
-.. autosummary::
-    :toctree: _autosummary/
-
-       radial.RadialKet
-       radial.Wavefunction
-       radial.Model
-       radial.numerov
-
-**Species module and parameters**
-
-.. autosummary::
-    :toctree: _autosummary/
-
-       species.SpeciesObjectSQDT
-       species.HydrogenTextBook
-       species.Hydrogen
-       species.Lithium
-       species.Sodium
-       species.Potassium
-       species.Rubidium
-       species.Cesium
-       species.Strontium87
-       species.Strontium88
-       species.Ytterbium171
-       species.Ytterbium173
-       species.Ytterbium174
+.. toctree::
+    :maxdepth: 2
+
+    api/rydberg_states
+    api/basis
+    api/angular
+    api/radial
+    api/species_sqdt
+    api/species_mqdt
diff --git a/docs/conf.py b/docs/conf.py
@@ -36,6 +36,10 @@
 
 # -- Options for HTML output -------------------------------------------------
 html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "collapse_navigation": False,
+    "navigation_depth": 3,
+}
 html_static_path = ["_static"]
 
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -137,6 +137,7 @@ mccabe.max-complexity = 10
 
 [tool.ruff.lint.per-file-ignores]
 "docs/examples/*.ipynb" = ["T201"]
+"src/rydstate/species/mqdt/*.py" = ["RUF012", "N801"]
 
 [tool.ruff.lint.isort]
 combine-as-imports = true

diff --git a/src/rydstate/__init__.py b/src/rydstate/__init__.py
@@ -1,11 +1,7 @@
 from rydstate import angular, basis, radial, rydberg, species
-from rydstate.basis import (
-    BasisSQDTAlkali,
-    BasisSQDTAlkalineFJ,
-    BasisSQDTAlkalineJJ,
-    BasisSQDTAlkalineLS,
-)
+from rydstate.basis import BasisMQDT, BasisSQDTAlkali, BasisSQDTAlkalineFJ, BasisSQDTAlkalineJJ, BasisSQDTAlkalineLS
 from rydstate.rydberg import (
+    RydbergStateMQDT,
     RydbergStateSQDT,
     RydbergStateSQDTAlkali,
     RydbergStateSQDTAlkalineFJ,
@@ -15,10 +11,12 @@
 from rydstate.units import ureg
 
 __all__ = [
+    "BasisMQDT",
     "BasisSQDTAlkali",
     "BasisSQDTAlkalineFJ",
     "BasisSQDTAlkalineJJ",
     "BasisSQDTAlkalineLS",
+    "RydbergStateMQDT",
     "RydbergStateSQDT",
     "RydbergStateSQDTAlkali",
     "RydbergStateSQDTAlkalineFJ",

diff --git a/src/rydstate/angular/angular_ket.py b/src/rydstate/angular/angular_ket.py
@@ -12,12 +12,15 @@
     is_angular_momentum_quantum_number,
     is_angular_operator_type,
 )
+from rydstate.angular.core_ket_base import CoreKet
 from rydstate.angular.utils import (
     InvalidQuantumNumbersError,
     NotSet,
     check_spin_addition_rule,
     get_possible_quantum_number_values,
+    is_dummy_ket,
     is_not_set,
+    is_unknown,
     minus_one_pow,
     try_trivial_spin_addition,
 )
@@ -92,9 +95,9 @@ def __init__(
         """
         if species is not None:
             if isinstance(species, str):
-                from rydstate.species import SpeciesObjectSQDT  # noqa: PLC0415
+                from rydstate.species.sqdt import SpeciesObjectSQDT  # noqa: PLC0415
 
-                species = SpeciesObjectSQDT.from_name(species)
+                species = SpeciesObjectSQDT.from_name(species.replace("_mqdt", ""))
             # use i_c = 0 for species without defined nuclear spin (-> ignore hyperfine)
             if i_c is not None and i_c != species.i_c_number:
                 raise ValueError(f"Nuclear spin i_c={i_c} does not match the species {species} with i_c={species.i_c}.")
@@ -232,6 +235,11 @@ def to_state(self, coupling_scheme: CouplingScheme | None = None) -> AngularStat
             The angular state in the specified coupling scheme.
 
         """
+        if any(is_unknown(qn) for qn in self.quantum_numbers):
+            from rydstate.angular.angular_ket_dummy import AngularKetDummy  # noqa: PLC0415
+
+            return AngularKetDummy(str(self), f_tot=self.f_tot, m=self.m).to_state(coupling_scheme)
+
         if coupling_scheme is None or coupling_scheme == self.coupling_scheme:
             return self._create_angular_state([1], [self])
         if coupling_scheme == "LS":
@@ -355,6 +363,9 @@ def calc_reduced_overlap(self, other: AngularKetBase) -> float:
         If the kets are of different types, the overlap is calculated using the corresponding
         Clebsch-Gordan coefficients (/ Wigner-j symbols).
         """
+        if any(is_dummy_ket(s) for s in [self, other]):
+            return 1.0 if self == other else 0.0
+
         for q in set(self.quantum_number_names) & set(other.quantum_number_names):
             if self.get_qn(q) != other.get_qn(q):
                 return 0
@@ -730,3 +741,7 @@ def sanity_check(self, msgs: list[str] | None = None) -> None:
             msgs.append(f"{self.f_c=}, {self.j_r=}, {self.f_tot=} don't satisfy spin addition rule.")
 
         super().sanity_check(msgs)
+
+    def get_core_ket(self) -> CoreKet:
+        """Get the core ket corresponding to this FJ ket."""
+        return CoreKet(i_c=self.i_c, s_c=self.s_c, l_c=self.l_c, j_c=self.j_c, f_c=self.f_c)