Add variation labels to plots in hfss_report_full_convergence (#119)

* Improve assorted docstrings

* Add variation labels to HFSS convergence report

pyEPR/core_distributed_analysis.py

@@ -236,7 +236,7 @@ def setup_data(self):
     def calc_p_junction_single(self, mode, variation, U_E=None, U_H=None):
         '''
         This function is used in the case of a single junction only.
-        For multiple junctions, see `calc_p_junction`.
+        For multiple junctions, see :func:`~pyEPR.DistributedAnalysis.calc_p_junction`.
 
         Assumes no lumped capacitive elements.
         '''
@@ -389,6 +389,7 @@ def get_variations(self):
 
         Returns:
             Returns a list of strings that give the variation labels for HFSS.
+
             .. code-block:: python
 
                 OrderedDict([
@@ -941,13 +942,14 @@ def calc_Q_external(self, variation, freq_GHz, U_E = None):
     def calc_p_junction(self, variation, U_H, U_E, Ljs, Cjs):
         '''
         For a single specific mode.
-        Expected that you have specified the mode before calling this, `self.set_mode(num)`
+        Expected that you have specified the mode before calling this, :func:`~pyEPR.DistributedAnalysis.set_mode`.
+
+        Expected to precalc U_H and U_E for mode, will return pandas pd.Series object:
 
-        Expected to precalc U_H and U_E for mode, will return pandas pd.Series object
-            junc_rect = ['junc_rect1', 'junc_rect2'] name of junc rectangles to integrate H over
-            junc_len  = [0.0001]   specify in SI units; i.e., meters
-            LJs       = [8e-09, 8e-09] SI units
-            calc_sign = ['junc_line1', 'junc_line2']
+            * junc_rect = ['junc_rect1', 'junc_rect2'] name of junc rectangles to integrate H over
+            * junc_len  = [0.0001]   specify in SI units; i.e., meters
+            * LJs       = [8e-09, 8e-09] SI units
+            * calc_sign = ['junc_line1', 'junc_line2']
 
         WARNING: Cjs is experimental.
 
@@ -1520,8 +1522,8 @@ def has_fields(self, variation: str = None):
         Determine if fields exist for a particular solution.
         Just calls `self.solutions.has_fields(variation_string)`
 
-        variation (str | None) : String of variation label, such as '0' or '1'
-            If None, gets the nominal variation
+        Args:
+            variation (str): String of variation label, such as '0' or '1'. If None, gets the nominal variation
         '''
         if self.solutions:
             #print('variation=', variation)
@@ -1607,7 +1609,7 @@ def hfss_report_full_convergence(self, fig=None, _display=True):
         if fig is None:
             fig = plt.figure(figsize=(11, 3.))
 
-        for variation in self.variations:
+        for variation, variation_labels in self.get_variations().items():
             fig.clf()
 
             # Grid spec and axes;    height_ratios=[4, 1], wspace=0.5
@@ -1618,6 +1620,8 @@ def hfss_report_full_convergence(self, fig=None, _display=True):
             convergence_t = self.get_convergence(variation=variation)
             convergence_f = self.hfss_report_f_convergence(variation=variation)
 
+            axs[0].set_ylabel(variation_labels, fontsize='large')  # add variation labels to y-axis of first plot
+
             ax0t = axs[1].twinx()
             plot_convergence_f_vspass(axs[0], convergence_f)
             plot_convergence_max_df(axs[1], convergence_t.iloc[:, 1])

pyEPR/core_quantum_analysis.py

@@ -443,11 +443,10 @@ def analyze_all_variations(self,
         '''
         See analyze_variation for full documentation
 
-        Specific params:
-        --------------------
-            variations : None returns all_variations otherwise this is a list with number
-                         as strings ['0', '1']
-            analyze_previous :set to true if you wish to overwrite previous analysis
+        Args:
+            variations: None returns all_variations otherwise this is a list with number as strings ['0', '1']
+            analyze_previous: set to true if you wish to overwrite previous analysis
+            **kwargs: Keyword arguments passed to :func:`~pyEPR.QuantumAnalysis.analyze_variation`.
         '''
 
         result = OrderedDict()
@@ -611,24 +610,22 @@ def analyze_variation(self,
         Core analysis function to call!
 
         Args:
-        ---------------
             junctions: list or slice of junctions to include in the analysis.
                 None defaults to analysing all junctions
             modes: list or slice of modes to include in the analysis.
                 None defaults to analysing all modes
 
         Returns:
-        ----------------
-            f_0 [MHz]    : Eigenmode frequencies computed by HFSS; i.e., linear freq returned in GHz
-            f_1 [MHz]    : Dressed mode frequencies (by the non-linearity; e.g., Lamb shift, etc. ).
-                           Result based on 1st order perturbation theory on the 4th order
-                           expansion of the cosine.
-            f_ND [MHz]   : Numerical diagonalization result of dressed mode frequencies.
-                           only available if `cos_trunc` and  `fock_trunc` are set (non None).
-            chi_O1 [MHz] : Analytic expression for the chis based on a cos trunc to 4th order, and using 1st
-                           order perturbation theory. Diag is anharmonicity, off diag is full cross-Kerr.
-            chi_ND [MHz] : Numerically diagonalized chi matrix. Diag is anharmonicity, off diag is full
-                           cross-Kerr.
+            dict: Dictionary containing at least the following:
+                * f_0 [MHz]: Eigenmode frequencies computed by HFSS; i.e., linear freq returned in GHz
+                * f_1 [MHz]: Dressed mode frequencies (by the non-linearity; e.g., Lamb shift, etc. ).
+                  Result based on 1st order perturbation theory on the 4th order expansion of the cosine.
+                * f_ND [MHz]: Numerical diagonalization result of dressed mode frequencies.
+                  only available if `cos_trunc` and  `fock_trunc` are set (non None).
+                * chi_O1 [MHz]: Analytic expression for the chis based on a cos trunc to 4th order, and using 1st
+                  order perturbation theory. Diag is anharmonicity, off diag is full cross-Kerr.
+                * chi_ND [MHz]: Numerically diagonalized chi matrix. Diag is anharmonicity, off diag is full
+                  cross-Kerr.
         '''
 
         # ensuring proper matrix dimensionality when slicing