Improve parameter-related types and documentation (#3330)

This is part of the suggestion in #3256 (review).

cirq/__init__.py

@@ -410,6 +410,7 @@
     PeriodicValue,
     RANDOM_STATE_OR_SEED_LIKE,
     Timestamp,
+    TParamKey,
     TParamVal,
     validate_probability,
     value_equality,

cirq/protocols/json_serialization_test.py

@@ -190,6 +190,7 @@ def test_fail_to_resolve():
     'RANDOM_STATE_OR_SEED_LIKE',
     'STATE_VECTOR_LIKE',
     'Sweepable',
+    'TParamKey',
     'TParamVal',
     'ParamDictType',
 

cirq/study/resolver.py

@@ -24,7 +24,7 @@
     import cirq
 
 
-ParamDictType = Dict[Union[str, sympy.Symbol], Union[float, str, sympy.Basic]]
+ParamDictType = Dict['cirq.TParamKey', 'cirq.TParamVal']
 document(
     ParamDictType,  # type: ignore
     """Dictionary from symbols to values.""")
@@ -36,10 +36,11 @@
 
 
 class ParamResolver:
-    """Resolves sympy.Symbols to actual values.
+    """Resolves parameters to actual values.
 
-    A Symbol is a wrapped parameter name (str). A ParamResolver is an object
-    that can be used to assign values for these keys.
+    A parameter is a variable whose value has not been determined.
+    A ParamResolver is an object that can be used to assign values for these
+    variables.
 
     ParamResolvers are hashable.
 
@@ -63,15 +64,17 @@ def __init__(self,
                                {} if param_dict is None else param_dict)
 
     def value_of(self,
-                 value: Union[sympy.Basic, float, str]) -> 'cirq.TParamVal':
-        """Attempt to resolve a Symbol, string, or float to its assigned value.
+                 value: Union['cirq.TParamKey', float]) -> 'cirq.TParamVal':
+        """Attempt to resolve a parameter to its assigned value.
 
         Floats are returned without modification.  Strings are resolved via
         the parameter dictionary with exact match only.  Otherwise, strings
         are considered to be sympy.Symbols with the name as the input string.
 
-        sympy.Symbols are first checked for exact match in the parameter
-        dictionary.  Otherwise, the symbol is resolved using sympy substitution.
+        A sympy.Symbol is first checked for exact match in the parameter
+        dictionary. Otherwise, it is treated as a sympy.Basic.
+
+        A sympy.Basic is resolved using sympy substitution.
 
         Note that passing a formula to this resolver can be slow due to the
         underlying sympy library.  For circuits relying on quick performance,
@@ -81,8 +84,7 @@ def value_of(self,
         If unable to resolve a name, returns a sympy.Symbol with that name.
 
         Args:
-            value: The sympy.Symbol or name or float to try to resolve into just
-                a float.
+            value: The parameter to try to resolve.
 
         Returns:
             The value of the parameter as resolved by this resolver.

cirq/study/sweepable.py

@@ -21,9 +21,12 @@
 from cirq.study.resolver import ParamResolver, ParamResolverOrSimilarType
 from cirq.study.sweeps import ListSweep, Points, Sweep, UnitSweep, Zip
 
+SweepLike = Union[ParamResolverOrSimilarType, Sweep]
+document(
+    SweepLike,  # type: ignore
+    """An object similar to an iterable of parameter resolvers.""")
 
-Sweepable = Union[Dict[str, float], ParamResolver, Sweep, Iterable[
-    Union[Dict[str, float], ParamResolver, Sweep]], None]
+Sweepable = Union[SweepLike, Iterable[SweepLike]]
 document(
     Sweepable,  # type: ignore
     """An object or collection of objects representing a parameter sweep.""")

cirq/study/sweeps.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 from typing import (Any, cast, Dict, Iterable, Iterator, List, overload,
-                    Sequence, Tuple, Union)
+                    Sequence, TYPE_CHECKING, Tuple, Union)
 
 import abc
 import collections
@@ -22,8 +22,10 @@
 from cirq._doc import document
 from cirq.study import resolver
 
+if TYPE_CHECKING:
+    import cirq
 
-Params = Iterable[Tuple[str, float]]
+Params = Iterable[Tuple['cirq.TParamKey', 'cirq.TParamVal']]
 
 
 def _check_duplicate_keys(sweeps):

cirq/value/__init__.py

@@ -66,7 +66,9 @@
     Timestamp,)
 
 from cirq.value.type_alias import (
-    TParamVal,)
+    TParamKey,
+    TParamVal,
+)
 
 from cirq.value.value_equality_attr import (
     value_equality,)

cirq/value/type_alias.py

@@ -19,7 +19,12 @@
 """Supply aliases for commonly used types.
 """
 
+TParamKey = Union[str, sympy.Basic]
+document(
+    TParamKey,  # type: ignore
+    """A parameter that a parameter resolver may map to a value.""")
+
 TParamVal = Union[float, sympy.Basic]
 document(
     TParamVal,  # type: ignore
-    """A value that a parameter resolver may return for a symbol.""")
+    """A value that a parameter resolver may return for a parameter.""")

rtd_docs/api.rst

@@ -724,6 +724,7 @@ important roles in the internal machinery of the library.
     cirq.LinearCombinationOfGates
     cirq.LinearCombinationOfOperations
     cirq.SingleQubitPauliStringGateOperation
+    cirq.TParamKey
     cirq.TParamVal