more docs

Author: nkanazawa1989

qiskit_experiments/curve_analysis/fit_models.py

@@ -12,15 +12,15 @@
 """Fit models that are used for curve fitting."""
 
 from abc import ABC, abstractmethod
-from typing import Callable, List, Optional
+from typing import Callable, List, Optional, Union
 
 import numpy as np
 
 from qiskit_experiments.exceptions import AnalysisError
 
 
 class FitModel(ABC):
-    """Base class of fit models.
+    r"""Base class of fit models.
 
     This is a function-like object that implements a fit model as a ``__call__`` magic method,
     thus it behaves like a Python function that the SciPy curve_fit solver accepts.
@@ -29,22 +29,74 @@ class FitModel(ABC):
     This class ties together the fit function and associated parameter names to
     perform correct parameter mapping among multiple objective functions with different signatures,
     in which some parameters may be excluded from the fitting when they are fixed.
+
+    Examples:
+
+        Given we have two functions :math:`F_1(x_1, p_0, p_1, p_2)` and :math:`F_2(x_2, p_0, p_3)`.
+        During the fit, we assign :math:`p_1=2` and exclude it from the fitting.
+        This is formulated with set operation as follows:
+
+        .. math::
+
+            \Theta_1 = \{ p_0, p_1, p_2 \}, \Theta_2 = \{p_0, p_3\}, \Theta_{\rm fix} = \{p_1\}
+
+        Note that :class:`FitModel` subclass is instantiated with a list of
+        :math:`F_1` and :math:`F_2` (``fit_functions``) together with
+        a list of :math:`\Theta_1` and :math:`\Theta_2` (``signatures``) and
+        :math:`\Theta_{\rm fix}` (``fixed_parameters``).
+        The signature of new fit model instance will be
+        :math:`\Theta = (\Theta_1 \cup \Theta_2) - \Theta_{\rm fix} = \{ p_0, p_2, p_3\}`.
+        The fit function that this model provides is accordingly
+
+        .. math::
+
+            F(x, \Theta) = F(x_0 \oplus x_1, p_0, p_2, p_3).
+
+        This function might be called from the scipy curve fit algorithm
+        which only takes variadic arguments (i.e. agnostic to parameter names).
+
+        .. math::
+
+            F(x, {\rm *args}) = F(x,\bar{p}_0, \bar{p}_1, \bar{p}_2)
+
+        The fit model internally maps :math:`\bar{p}_0 \rightarrow p_0`,
+        :math:`\bar{p}_1 \rightarrow p_2`, and :math:`\bar{p}_2 \rightarrow p_3`
+        while assigning :math:`p_1=2` when its called from the curve fitting algorithm.
+        Note that this mapping is performed in the ``__call__`` method.
+        The function signature :math:`\Theta` is provided with the property :attr:`signature`.
+
+    Notes:
+
+        This class is usually instantiated with the :class:`SeriesDef` in the
+        ``__init_subclass__`` method of :class:`CurveAnalysis` subclasses.
+        User doesn't need to take care of input values to the constructor
+        unless one manually instantiates the class for debugging purpose.
     """
 
     def __init__(
         self,
         fit_functions: List[Callable],
         signatures: List[List[str]],
-        fit_models: Optional[List[str]] = None,
+        fit_models: Optional[Union[List[str], str]] = None,
         fixed_parameters: Optional[List[str]] = None,
     ):
         """Create new fit model.
 
         Args:
-            fit_functions: List of callables that defines fit function of a single series.
-            signatures: List of parameter names of a single series.
-            fit_models: List of string representation of fit functions.
-            fixed_parameters: List of parameter names that are fixed in the fit.
+            fit_functions: List of callables that forms the fit model for a
+                particular curve analysis class. It may consists of multiple curves.
+            signatures: List of argument names that each fit function callable takes.
+                The length of the list should be identical to the ``fit_functions``.
+            fit_models: String representation of fit functions.
+                Because this is just a metadata, the format of input value doesn't matter.
+                It may be a single string description for the entire fit model, or
+                list of descriptions for each fit functions. If not provided,
+                "not defined" is stored in the experiment result metadata.
+            fixed_parameters: List of parameter names that are not considered to be fit parameter.
+                The value of parameter is provided by analysis default setting or users,
+                which is fixed during the curve fitting. Arbitrary number of parameters
+                in the fit model can be fixed, however, every parameter should be
+                defined in the model.
 
         Raises:
             AnalysisError: When ``fit_functions`` and ``signatures`` don't match.
@@ -54,8 +106,14 @@ def __init__(
 
         self._fit_functions = fit_functions
         self._signatures = signatures
-        self._fit_models = fit_models or [None for _ in range(len(fit_functions))]
 
+        # String representation of the fit model. This is stored as a list of string.
+        if not fit_models or isinstance(fit_models, str):
+            fit_models = [fit_models]
+        self._fit_models = fit_models
+
+        # No validation is performed since this class is always instantiated from the
+        # curve analysis class itself. The validation is performed there.
         if not fixed_parameters:
             fixed_parameters = []
         self._fixed_params = {p: None for p in fixed_parameters}
@@ -121,13 +179,17 @@ class SingleFitFunction(FitModel):
     the fit parameters and the fixed parameters :math:`\Theta_{\rm fix}`.
     The function :math:`f` is usually set by :attr:`SeriesDef.fit_func` which is
     a standard python function.
+
+    .. seealso::
+
+        Class :class:`FitModel`.
     """
 
     def __call__(self, x: np.ndarray, *params) -> np.ndarray:
         """Compute values of fit functions.
 
         Args:
-            x: Composite X values array.
+            x: Input X values array.
             *params: Variadic argument provided from the fitter.
 
         Returns:
@@ -166,6 +228,10 @@ class CompositeFitFunction(FitModel):
     This data represents the location where the function with index ``i``
     is returned and where the x values :math:`x_i` comes from.
     One must set this data indices before calling the composite fit function.
+
+    .. seealso::
+
+        Class :class:`FitModel`.
     """
 
     def __init__(
@@ -182,7 +248,7 @@ def __call__(self, x: np.ndarray, *params) -> np.ndarray:
         """Compute values of fit functions.
 
         Args:
-            x: Composite X values array.
+            x: Input X values array.
             *params: Variadic argument provided from the fitter.
 
         Returns: