docs: improved documentation

.gitignore

@@ -8,3 +8,8 @@ dist/
 **/__pycache__
 *_precalculated.db
 *.so
+/doc/alkali_atom_data
+/doc/divalent_atom_functions
+/doc/divalent_atom_data
+/doc/generated
+/doc/_static

arc/alkali_atom_functions.py

@@ -44,11 +44,7 @@
 if sys.version_info > (2,):
     xrange = range
 
-try:
-    import cPickle as pickle   # fast, C implementation of the pickle
-except Exception:
-    # Python 3 already has efficient pickle (instead of cPickle)
-    import pickle
+import pickle
 sqlite3.register_adapter(np.float64, float)
 sqlite3.register_adapter(np.float32, float)
 sqlite3.register_adapter(np.int64, int)
@@ -117,15 +113,6 @@ class AlkaliAtom(object):
 
     """
 
-    #: Hyperfine Splitting Coefficients (SI Units)
-    Ahfs = 0.0        #: Ground-state Hyperfine Magnetic Dipole Constant (Hz)
-    AhfsD1 = 0.0      #: ngP1/2 Hyperfine Magnetic Dipole Constant (Hz)
-    AhfsD2 = 0.0      #: ngP3/2 Hyperfine Magnetic Dipole Constant (Hz)
-    BhfsD2 = 0.0      #: ngP3/2 Hyperfine Magnetic Quadrupole Constant (Hz)
-    AhfsiP12 = 0.0    #: (ng+1)P1/2 Hyperfine Magnetic Dipole Constant (Hz)
-    AhfsiP32 = 0.0    #: (ng+1)P3/2 Hyperfine Magnetic Dipole Constant (Hz)
-    BhfsiP32 = 0.0    #: (ng+1)P3/2 Hyperfine Magnetic Quadrupole Constant (Hz)
-
     gS = 2.0023193043737  # : Electron Spin g-factor [Steck]
     gL = 0.0          #: Electron Orbital g-factor
     gI = 0.0          #: Nuclear g-factor
@@ -2664,7 +2651,7 @@ def breitRabi(self, n, l, j, B):
                 float: State energy :math:`E_z` in SI units (Hz), state f, state mf
         """
 
-        [Ahfs, Bhfs] = self.getHFSCoefficients(n, l, j)
+        Ahfs, Bhfs = self.getHFSCoefficients(n, l, j)
 
         # Bohr Magneton
         uB = physical_constants["Bohr magneton in Hz/T"][0]

arc/calculations_atom_pairstate.py

@@ -95,12 +95,11 @@ class PairStateInteractions:
         .. _`interactions example snippet`:
             ./Rydberg_atoms_a_primer.html#Short-range-interactions
 
-       .. _`inter-species interaction calculation snippet`:
+        .. _`inter-species interaction calculation snippet`:
            ./ARC_3_0_introduction.html#Inter-species-pair-state-calculations
 
-        Parameers:
-            atom (:obj:`arc.alkali_atom_functions.AlkaliAtom`
-                or :obj:`arc.divalent_atom_functions.DivalentAtom`):
+        Parameters:
+            atom (:obj:`arc.alkali_atom_functions.AlkaliAtom` or :obj:`arc.divalent_atom_functions.DivalentAtom`):
                 = {
                 :obj:`arc.alkali_atom_data.Lithium6`,
                 :obj:`arc.alkali_atom_data.Lithium7`,
@@ -116,7 +115,7 @@ class PairStateInteractions:
                 :obj:`arc.divalent_atom_data.Ytterbium174` }
                 Select the alkali metal for energy level
                 diagram calculation
-            n (int):
+            n (int): 
                 principal quantum number for the *first* atom
             l (int):
                 orbital angular momentum for the *first* atom
@@ -140,17 +139,17 @@ class PairStateInteractions:
                 up to quadrupole-quadrupole. Default value is 1.
             s (float):
                 optional, spin state of the first atom. Default value
-                of 0.5 is correct for :obj:`AlkaliAtom` but for
-                :obj:`DivalentAtom` it has to be explicitly set to 0 or 1 for
+                of 0.5 is correct for :obj:`arc.alkali_atom_functions.AlkaliAtom`
+                but for :obj:`arc.divalent_atom_functions.DivalentAtom`
+                it has to be explicitly set to 0 or 1 for
                 singlet and triplet states respectively.
                 **If `s2` is not specified, it is assumed that the second
                 atom is in the same spin state.**
             s2 (float):
                 optinal, spin state of the second atom. If not
                 specified (left to default value None) it will assume spin
                 state of the first atom.
-            atom2 (:obj:`arc.alkali_atom_functions.AlkaliAtom`
-                or :obj:`arc.divalent_atom_functions.DivalentAtom`):
+            atom2 (:obj:`arc.alkali_atom_functions.AlkaliAtom` or :obj:`arc.divalent_atom_functions.DivalentAtom`):
                 optional,
                 specifies atomic species for the second atom, enabeling
                 calculation of **inter-species pair-state interactions**.
@@ -203,11 +202,11 @@ def __init__(self, atom, n, l, j, nn, ll, jj, m1, m2,
                  s2=None, atom2=None):
         # alkali atom type, principal quantum number, orbital angular momentum,
         #  total angular momentum projections of the angular momentum on z axis
-        self.atom1 = atom  #: atom type
+        self.atom1 = atom  #: the first atom type (isotope)
         if atom2 is None:
-            self.atom2 = atom
+            self.atom2 = atom  #: the second atom type (isotope)
         else:
-            self.atom2 = atom2
+            self.atom2 = atom2  #: thge second atom type (isotope)
         self.n = n  # : pair-state definition: principal quantum number of the first atom
         self.l = l  # : pair-state definition: orbital angular momentum of the first atom
         self.j = j  # : pair-state definition: total angular momentum of the first atom
@@ -217,8 +216,7 @@ def __init__(self, atom, n, l, j, nn, ll, jj, m1, m2,
         self.m1 = m1  # : pair-state definition: projection of the total ang. momentum for the *first* atom
         self.m2 = m2  # : pair-state definition: projection of the total angular momentum for the *second* atom
         self.interactionsUpTo = interactionsUpTo
-        """"
-            Specifies up to which approximation we include in pair-state interactions.
+        """ Specifies up to which approximation we include in pair-state interactions.
             By default value is 1, corresponding to pair-state interactions up to
             dipole-dipole coupling. Value of 2 is also supported, corresponding
             to pair-state interactions up to quadrupole-quadrupole coupling.
@@ -266,15 +264,16 @@ def __init__(self, atom, n, l, j, nn, ll, jj, m1, m2,
         self.coupling = []
         """
             List of matrices defineing coupling strengths between the states in
-             J basis (not resolving :math:`m_j` ). Basis is given by
-             :obj:`channel`. Used as intermediary for full interaction matrix
-             calculation by :obj:`defineBasis`.
+            J basis (not resolving :math:`m_j` ). Basis is given by
+            :obj:`PairStateInteractions.channel`. Used as intermediary for full
+            interaction matrix calculation by
+            :obj:`PairStateInteractions.defineBasis`.
         """
         self.channel = []
         """
             states relevant for calculation, defined in J basis (not resolving
             :math:`m_j`. Used as intermediary for full interaction matrix
-            calculation by :obj:`defineBasis`.
+            calculation by :obj:`PairStateInteractions.defineBasis`.
         """
 
         # ======================= Full basis (resolving mj) ===================
@@ -285,13 +284,15 @@ def __init__(self, atom, n, l, j, nn, ll, jj, m1, m2,
             [[n1,l1,j1,mj1,n2,l2,j2,mj2], ...].
             Each state is an array [n1,l1,j1,mj1,n2,l2,j2,mj2] corresponding to
             :math:`|n_1,l_1,j_1,m_{j1},n_2,l_2,j_2,m_{j2}\\rangle` state.
-            Calculated by :obj:`defineBasis`.
+            Calculated by :obj:`PairStateInteractions.defineBasis`.
         """
         self.matrixElement = []
         """
-            `matrixElement[i]` gives index of state in :obj:`channel` basis
-            (that doesn't resolve :obj:`m_j` states), for the given index `i`
-            of the state in :obj:`basisStates`  ( :math:`m_j` resolving) basis.
+            `matrixElement[i]` gives index of state in
+            :obj:`PairStateInteractions.channel` basis
+            (that doesn't resolve :math:`m_j` states), for the given index `i`
+            of the state in :obj:`PairStateInteractions.basisStates` 
+            ( :math:`m_j` resolving) basis.
         """
 
         # variuos parts of interaction matrix in pair-state basis
@@ -301,7 +302,8 @@ def __init__(self, atom, n, l, j, nn, ll, jj, m1, m2,
             on inter-atomic distance. E.g. diagonal elements of the interaction
             matrix, that describe energies of the pair states in unperturbed
             basis, will be stored here. Basis states are stored in
-            :obj:`basisStates`. Calculated by :obj:`defineBasis`.
+            :obj:`PairStateInteractions.basisStates`. Calculated by
+            :obj:`PairStateInteractions.defineBasis`.
         """
         self.matR = []
         """
@@ -311,13 +313,14 @@ def __init__(self, atom, n, l, j, nn, ll, jj, m1, m2,
             respectively. These matrices correspond to dipole-dipole
             ( :math:`C_3`), dipole-quadrupole ( :math:`C_4`) and
             quadrupole-quadrupole ( :math:`C_5`) interactions
-            coefficients. Basis states are stored in :obj:`basisStates`.
-            Calculated by :obj:`defineBasis`.
+            coefficients. Basis states are stored in
+            :obj:`PairStateInteractions.basisStates`.
+            Calculated by :obj:`PairStateInteractions.defineBasis`.
         """
         self.originalPairStateIndex = 0
         """
             index of the original n,l,j,m1,nn,ll,jj,m2 pair-state in the
-            :obj:`basisStates` basis.
+            :obj:`PairStateInteractions.basisStates` basis.
         """
 
         self.matE = []
@@ -1185,9 +1188,12 @@ def defineBasis(self, theta, phi, nRange, lrange, energyDelta,
             on distance as :math:`R^{-3}, R^{-4}` or :math:`R^{-5}`,
             corresponding to dipole-dipole (:math:`C_3` ), dipole-qudrupole
             (:math:`C_4` ) and quadrupole-quadrupole coupling (:math:`C_5` )
-            respectively. These parts of the matrix are stored in :obj:`matR`
-            in that order. I.e. :obj:`matR[0]` stores dipole-dipole coupling
-            (:math:`\propto R^{-3}`), :obj:`matR[0]` stores dipole-quadrupole
+            respectively. These parts of the matrix are stored in
+            :obj:`PairStateInteractions.matR`
+            in that order. I.e. :obj:`matR[0]`
+            stores dipole-dipole coupling
+            (:math:`\propto R^{-3}`),
+            :obj:`matR[1]` stores dipole-quadrupole
             couplings etc.
 
             Parameters:
@@ -1215,8 +1221,8 @@ def defineBasis(self, theta, phi, nRange, lrange, energyDelta,
                     more verbose output.
 
             See also:
-                :obj:`alkali_atom_functions.saveCalculation` and
-                :obj:`alkali_atom_functions.loadSavedCalculation` for
+                :obj:`arc.alkali_atom_functions.saveCalculation` and
+                :obj:`arc.alkali_atom_functions.loadSavedCalculation` for
                 information on saving intermediate results of calculation for
                 later use.
         """
@@ -1952,7 +1958,7 @@ def plotLevelDiagram(self,  highlightColor='red',
 
     def savePlot(self, filename="PairStateInteractions.pdf"):
         """
-            Saves plot made by :obj:`plotLevelDiagram`
+            Saves plot made by :obj:`PairStateInteractions.plotLevelDiagram`
 
             Args:
                 filename (:obj:`str`, optional): file location where the plot

arc/calculations_atom_single.py

@@ -394,7 +394,7 @@ def plot3D(self,
                 of the plot should be shown. Default value is `True`.
 
         Returns:
-            :obj:`matplotlib.figure` object with a requested plot. Use `show()`
+            :obj:`matplotlib.pyplot.figure` object with a requested plot. Use `show()`
             method to see figure.
 
         """

arc/custom-module-template.rst

@@ -0,0 +1,25 @@
+{{ fullname | escape | underline}}
+.. currentmodule:: {{ module }}
+.. autoclass:: {{ objname }}
+   :members:                                   
+   :show-inheritance:                           
+   :inherited-members:                     
+   {% block methods %}
+   .. automethod:: __init__
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}