Minor changes to documentation [ci skip]

qmix/circuit.py

@@ -8,16 +8,16 @@
  all of the components in these embedding circuits are **linear**, the 
  embedding circuit can be reduced to a **Thevenin equivalent circuit**, with
  one for **each tone and harmonic.**
- 
+
  To fully describe the embedding circuit, 3 bits of information are needed
  for each signal that is applied to the junction:
- 
+
  1. the frequency of the applied signal,
  2. the Thevenin voltage of the embedding circuit at this freq., and
  3. the Thevenin impedance of the embedding circuit at this freq.
 
- The main class in this module (``EmbeddingCircuit``) allows the user to 
- build an embedding circuit in the proper format.
+The main class in this module (``EmbeddingCircuit``) allows the user to 
+build an embedding circuit in the proper format.
  
 """
 
@@ -114,15 +114,15 @@ class EmbeddingCircuit(object):
  (tones) applied to the junction.
  num_p (int, optional, default is 1): Number of harmonics included for
  each tone.
- vb_min (float, optional, default is 0): Minimum bias voltage for array.
- vb_max (float, optional, default is 2): Maximum bias voltage for array.
+ vb_min (float, optional, default is 0): Minimum bias voltage.
+ vb_max (float, optional, default is 2): Maximum bias voltage.
  vb_npts (int, optional, default is 201): Number of points in bias
  voltage sweep.
  fgap (float, optional): Gap frequency of the junction in units [Hz].
  This is equal to ``e*Vgap/h``, where ``e`` is the charge of an
  electron, ``Vgap`` is the gap voltage, and ``h`` is the Planck
  constant. ``fgap`` is used to normalize and de-normalize frequency
- values (that't it).
+ values (that't it!).
  vgap (float, optional): Gap voltage of the junction in units [V]. This is the
  voltage where the sharp non-linearity in the DC I-V curve occurs 
  (a.k.a., the transition voltage).
@@ -135,11 +135,11 @@ class EmbeddingCircuit(object):
  Attributes:
  vph (numpy.ndarray): An array for the photon voltage normalized to the
  gap voltage. This is a 1-dimensional array of real numbers. It
- contains all of the photon voltages for the fundamental tones that
+ contains photon voltages for all of the fundamental tones that
  are applied to the junction. The photon voltage is defined as
  ``hf/e``, where ``h`` is the Planck constant, ``f`` is the
  frequency of the fundamental tone, and ``e`` is the charge of an
- electron. However, since this value is normalized to the gap
+ electron. Since this value is normalized to the gap
  voltage, the photon voltage is also equal to the normalized
  frequency, ``f/fgap``, where ``fgap`` is the gap frequency. Note
  that this array is 1-based, meaning that the photon voltage of the
@@ -188,10 +188,12 @@ class EmbeddingCircuit(object):
  vb (numpy.ndarray): Array for the DC bias voltage sweep. This value is
  normalized to the gap voltage.
  vb_npts (int): Number of points in the bias voltage sweep.
+ name (str): A name to describe this instance of the embedding circuit
+ class.
  comment (list): A list of comments to describe the different signals.
  For example, to describe tone 1/harmonic 1 as the local-oscillator
  signal, you might use ``cct.comment[1][1] = "LO"``. This has to be
- done after the initialization of the EmbeddingCircuit class.
+ set after the initialization of the EmbeddingCircuit class.
 
  """
 

qmix/exp/parameters.py

@@ -1,34 +1,34 @@
 """ This module contains a dictionary of parameters (``params``) that is
-used by the ``qmix.exp.RawData`` and ``qmix.exp.RawData0`` classes to control
+used by ``qmix.exp.RawData`` and ``qmix.exp.RawData0`` to control
 how experimental data is loaded and analyzed.
 
 Note:
 
  This dictionary just contains the default values. You can overwrite these 
  values by passing keyword arguments to ``RawData`` or ``RawData0``. For 
- example, the default value for voltage units is ``"mV"``.
- You can change this parameter to be ``"uV"`` by passing 
- ``v_fmt="uV"`` to the ``RawData`` or ``RawData0`` class.
+ example, the default value for voltage units is millivolts (``"mV"``).
+ You can change this parameter to be microvolts (``"uV"``) by passing 
+ ``v_fmt="uV"`` to ``RawData`` or ``RawData0``.
+
+ Also note that experimental data can be passed to ``RawData0`` and 
+ ``RawData`` either as CSV data files or as Numpy arrays. In both
+ cases, the data should have two columns: one for voltage and one 
+ for current or IF power, depending on the file. See Example #3 on the 
+ QMix website for more information.
 
 All of the different parameters are described below along with their default 
 values.
 
 **Parameters:**
 
- - Experimental data data:
- - **Note:** Experimental data can be passed to ``RawData0`` and 
- ``RawData`` either as CSV data files or as Numpy arrays. The CSV
- files should have two columns: one for voltage and one for current
- or IF power. The Numpy arrays should also have two columns.
  - CSV files:
- - **Note:** All of the experimental data is expected to be stored in
- CSV data files. These parameters control how the data is read in 
- from these files.
+ - **Note:** If you are using CSV files, these parameters control how 
+ the data is loaded from the CSV files.
  - ``delimiter = ","`` : The delimiter used by the CSV data files.
  - ``usecols = (0,1)`` : Which columns to import from the CSV data 
  files.
  - ``skip_header = 1`` : Number of rows to skip at the beginning CSV 
- data files. Used to skip the header.
+ data files. (Used to skip the header.)
  - Units:
  - ``v_fmt = "mV"`` : Units for imported voltage data. The options 
  are: ``"uV"``, ``"mV"`` and ``"V"``.
@@ -41,7 +41,8 @@
  interpolation.
  - ``debug = False`` : If set to ``True``, this will plot each step of
  the I-V data loading and analysis procedure. Note: This will 
- display 4 individual plots for each I-V curve that is loaded.
+ display 4 individual plots for each I-V curve that is loaded, so do
+ not use this if you are looping through multiple files.
  - Correcting voltage/current offsets:
  - **Note:** Sometimes there is an offset in the I-V data. The 
  parameters below can be used to correct this. If you know the 
@@ -50,9 +51,10 @@
  find the offset on its own. This is done by taking the derivative
  of the DC I-V curve, and then finding the maximum derivative value 
  between ``-voffset_range`` and ``+voffset_range``.
- - ``ioffset = None`` : Offset in DC tunneling current data in units 
- [A].
- - ``voffset = None`` : Offset in DC bias voltage data in units [V].
+ - ``ioffset = None`` : Offset of the DC tunneling current data in 
+ units [A].
+ - ``voffset = None`` : Offset of the DC bias voltage data in units 
+ [V].
  - ``voffset_range = 3e-4`` : Voltage range over which to look for the 
  voltage offset in units [V]. The ``RawData0`` class will look from 
  ``-voffset_range`` to ``+voffset_range`` for the voltage offset.
@@ -84,8 +86,8 @@
  - ``filter_nwind = 21`` : Width of the Savitzky-Golay filter.
  - ``filter_npoly = 3`` : Order of the Savitzky-Golay filter.
  - Analyzing the DC I-V curve:
- - ``vgap_threshold = 105e-6`` : Threshold current at which to measure
- the gap voltage, in units [A]. (Note: the gap voltage is defined 
+ - ``vgap_threshold = 105e-6`` : Threshold current, in units [A], at 
+ which to measure the gap voltage. (Note: the gap voltage is defined
  here as the voltage at which the DC I-V curve crosses this current 
  value.)
  - ``rn_vmin = 3.5e-3`` : Lower range over which to calculate normal 
@@ -100,17 +102,17 @@
  - ``analyze_iv = True`` : Analyze the pumped I-V data? This involves 
  a procedure to recover the embedding circuit.
  - ``cut_low = 0.25`` : Fit interval for impedance recovery, lower end,
- normalized to photon step width.
+ normalized to the photon voltage.
  - ``cut_high = 0.2`` : Fit interval for impedance recovery, upper end,
- normalized to photon step width.
+ normalized to the photon voltage.
  - ``remb_range = (0, 1)`` : Range of embedding resistances to test, 
- normalized to normal resistance.
+ normalized to the normal resistance.
  - ``xemb_range = (-1, 1)`` : Range of embedding reactances to test, 
- normalized to normal resistance.
- - ``alpha_max = 1.5`` : Maximum drive level (alpha) for initial guess 
+ normalized to the normal resistance.
+ - ``alpha_max = 1.5`` : Initial guess for the drive level (alpha)
  during impedance recovery.
  - ``num_b = 20`` : Maximum number of Bessel functions to include when 
- calculating tunneling currents.
+ calculating the tunneling currents.
  - Importing IF data:
  - ``ifdata_vmax = 2.25`` : Maximum IF voltage to import (normalized to
  vgap). Used in case the IF data is saturated beyond a certain bias 
@@ -122,6 +124,10 @@
  convolving it with a Gaussian distribution. This is the standard 
  deviation, in number of data points.
  - Analyzing the DC IF data:
+ - **Note:** DC IF data (IF power with no LO injection) is used to 
+ measure the IF noise contribution and convert the power units into
+ units of temperature [K]. This is done by fitting a linear trend
+ to the shot noise present in the DC IF data.
  - ``vshot = None`` : Range of voltages over which to fit a linear 
  trend line to the shot noise. This is a list of lists, in units [V].
  For example, to fit the shot noise slope from 4-5 mV and from 
@@ -141,8 +147,8 @@ class will determine the best bias voltage automatically.
  - Response function:
  - **Note:** The ``RawData0`` class generates a response function
  based on the imported DC I-V data (using ``qmix.respfn.RespFn``).
- It also generates a second response function that is smeared 
- slightly. This smeared response function is useful for simulations
+ It also generates a second response function that is slightly 
+ smeared. This smeared response function is useful for simulations
  because it simulates a small amount of heating.
  - ``v_smear = 0.020`` : Voltage smear of the "smeared" response 
  function.
@@ -155,7 +161,7 @@ class will determine the best bias voltage automatically.
  [GHz].
  - Miscellaneous:
  - ``comment = ""`` : Add a comment to describe this instance.
- - ``verbose = True`` : Print information to the terminal?
+ - ``verbose = True`` : Print information to the terminal.
 
 """
 

qmix/respfn.py

@@ -33,14 +33,14 @@
 
  - ``RespFnPolynomial``: This class will generate a response function 
  based on the polynomial model from Kennedy (1999). The order of the
- polynomial controls how sharp the transition is, so this class can be
- used to simulate the effect of the transition's sharpness (i.e., how 
- do the results change when the gap is more or less sharp).
+ polynomial controls the sharpness of the transition, so this class can
+ be used to simulate the effect of the transition's sharpness (e.g., 
+ how does the gain change when the gap is more or less sharp?).
  
  - ``RespFnExponential``: This class will generate a response function 
- based on the exponential model from Rashid et al. (2016). This model is
- very similar to ``RespFnPolynomial``, except that you can include a 
- constant subgap resistance.
+ based on the exponential model from Rashid *et al.* (2016). This model
+ is very similar to ``RespFnPolynomial``, except that you can include a
+ leakage current (i.e., a finite subgap resistance).
 
 Upon initialization, these classes will:
 
@@ -118,7 +118,13 @@
 class RespFn(object):
  """Generate the response function from pre-processed I-V data.
 
- This is a class to contain, interpolate and plot the response function.
+ This class expects "pre-processed" I-V data, meaning that there are more
+ data points around the curvier regions of the I-V curve and fewer points
+ in the linear regions. Sampling in this way helps the interpolation run
+ as quick as possible.
+
+ If you have not "pre-processed" your data, please use 
+ ``RespFnFromIVData``.
 
  Args:
  voltage (ndarray): normalized DC bias voltage
@@ -192,6 +198,9 @@ def __init__(self, voltage, current, **params):
  def plot_interpolation(self, fig_name=None, ax=None): # pragma: no cover
  """Plot the interpolation of the response function.
 
+ This can be used to check the interpolation of the response function.
+ (Mostly just a sanity check.)
+ 
  Note: If ``fig_name`` is provided, this method will save the plot 
  to the specified folder and then close the plot. This means
  that the Matplotlib axis object will not be returned in this
@@ -246,6 +255,9 @@ def plot_interpolation(self, fig_name=None, ax=None): # pragma: no cover
  def show_current(self, fig_name=None, ax=None): # pragma: no cover
  """Plot the interpolation of the response function.
 
+ This can be used to check the interpolation of the response function.
+ (Mostly just a sanity check.)
+
  Note: If ``fig_name`` is provided, this method will save the plot 
  to the specified folder and then close the plot. This means
  that the Matplotlib axis object will not be returned in this
@@ -312,7 +324,7 @@ def didc(self, vbias):
 
  This method is not used directly by QMix, but it can be useful if
  you are calculating the tunneling currents using Tucker theory
- (Tucker and Feldman, 1985).
+ (see: Tucker and Feldman, 1985).
 
  Args:
  vbias (ndarray): Bias voltage (normalized)
@@ -335,7 +347,7 @@ def dikk(self, vbias):
 
  This method is not used directly by QMix, but it can be useful if
  you are calculating the tunneling currents using Tucker theory
- (Tucker and Feldman, 1985).
+ (see: Tucker and Feldman, 1985).
 
  Args:
  vbias (ndarray): Bias voltage (normalized)
@@ -361,14 +373,13 @@ def resp(self, vbias):
  return self._f_ikk(vbias) + 1j * self._f_idc(vbias)
 
  def resp_conj(self, vbias):
- """Interpolate the complex conjugate of the response function
- .
+ """Interpolate the complex conjugate of the response function.
 
  Note:
 
  This method is not used directly by QMix, but it can be useful if
  you are calculating the tunneling currents using Tucker theory
- (Tucker and Feldman, 1985).
+ (see: Tucker and Feldman, 1985).
 
  This method is included because it might be *slightly* faster than
  ``np.conj(resp.resp(vb))`` where ``resp`` is an instance of this
@@ -386,18 +397,18 @@ def resp_conj(self, vbias):
 
  def resp_swap(self, vbias):
  """Interpolate the response function, with the real and imaginary 
- components swapped,.
+ components swapped.
  
  Note:
 
  This method is not used directly by QMix, but it can be useful if
  you are calculating the tunneling currents using Tucker theory
- (Tucker and Feldman, 1985).
+ (see: Tucker and Feldman, 1985).
 
  This method is included because it might be *slightly* faster than
- ``1j * np.conj(resp.resp(vb))`` where ``resp`` is an instance of
- this class (which is the normal way that you would swap the real
- and imaginary components).
+ ``1j*np.conj(resp.resp(vb))`` where ``resp`` is an instance of
+ this class. This is the normal way that you would swap the real
+ and imaginary components.
 
  Args:
  vbias (ndarray): Bias voltage (normalized)
@@ -416,8 +427,6 @@ def resp_swap(self, vbias):
 class RespFnFromIVData(RespFn):
  """Generate the response function from I-V data.
 
- This is a class to contain, interpolate and plot the response function.
-
  Unlike ``RespFn``, this class will resample the I-V data to optimize the
  interpolation.
 
@@ -476,7 +485,10 @@ def __init__(self, voltage, current, **kwargs):
 class RespFnPolynomial(RespFn):
  """Response function based on the polynomial I-V curve model.
 
- Class to contain, interpolate and plot the response function.
+ This model is from Kennedy (1999). The order of the polynomial 
+ (``p_order``) controls the sharpness of the non-linearity.
+
+ See ``qmix.mathfn.ivcurve_models.polynomial`` for the model.
 
  Args:
  p_order (int): Order of the polynomial
@@ -511,13 +523,10 @@ def __init__(self, p_order=50, **kwargs):
 class RespFnExponential(RespFn):
  """Response function based on the exponential I-V curve model.
 
- Class to contain, interpolate and plot the response function.
-
- Reference:
+ This model is from Rashid *et al.* (2016). Through this model you can 
+ set the sharpness of the non-linearity *and* the subgap resistance.
 
- H. Rashid, et al., "Harmonic and reactive behavior of the
- quasiparticle tunnel current in SIS junctions," AIP Advances,
- vol. 6, 2016.
+ See ``qmix.mathfn.ivcurve_models.exponential`` for the model.
 
  Args:
  vgap (float): Gap voltage (un-normalized)
@@ -555,7 +564,11 @@ def __init__(self, vgap=2.8e-3, rn=14, rsg=1000, agap=4e4, **kwargs):
 class RespFnPerfect(RespFn):
  """Response function based on the perfect I-V curve model.
 
- Class to contain, interpolate and plot the response function.
+ The perfect I-V curve has zero subgap current below the transition, and 
+ a current exactly equal to ``vb * Rn``, where ``vb`` is the bias voltage
+ and ``Rn`` is the normal resistance, above the transition.
+
+ See ``qmix.mathfn.ivcurve_models.perfect`` for the model.
 
  Keyword Args:
  verbose (bool, default is True): print info to terminal?