Merge branch 'nifty6_multi_domain_keys' into 'NIFTy_6'

Highlight that keys in a multi-domain are sorted

See merge request !465

nifty6/multi_domain.py

@@ -22,9 +22,18 @@ from .utilities import frozendict, indent
 class MultiDomain(object):
     """A tuple of domains corresponding to a direct sum.
 
-    This class is the domain of the direct sum of fields defined
-    on (possibly different) domains. To make an instance
-    of this class, call `MultiDomain.make(inp)`.
+    This class is the domain of the direct sum of fields defined on (possibly
+    different) domains. To make an instance of this class, call
+    `MultiDomain.make(inp)`.
+
+    Notes
+    -----
+    For consistency and to be independent of the order of insertion, the keys
+    within a multi-domain are sorted. Hence, renaming a domain may result in it
+    being placed at a different index within a multi-domain. This is especially
+    important if a sequence of, e.g., random numbers is distributed sequentially
+    over a multi-domain. In this example, ordering keys differently will change
+    the resulting :class:`MultiField`.
     """
     _domainCache = {}
 

nifty6/multi_field.py

@@ -102,6 +102,29 @@ class MultiField(Operator):
 
     @staticmethod
     def from_random(random_type, domain, dtype=np.float64, **kwargs):
+        """Draws a random multi-field with the given parameters.
+
+        Parameters
+        ----------
+        random_type : 'pm1', 'normal', or 'uniform'
+            The random distribution to use.
+        domain : DomainTuple
+            The domain of the output random Field.
+        dtype : type
+            The datatype of the output random Field.
+
+        Returns
+        -------
+        MultiField
+            The newly created :class:`MultiField`.
+
+        Notes
+        -----
+        The individual fields within this multi-field will be drawn in alphabetical
+        order of the multi-field's domain keys. As a consequence, renaming these
+        keys may cause the multi-field to be filled with different random numbers,
+        even for the same initial RNG state.
+        """
         domain = MultiDomain.make(domain)
         if isinstance(dtype, dict):
             dtype = {kk: np.dtype(dt) for kk, dt in dtype.items()}

nifty6/sugar.py

@@ -274,6 +274,13 @@ def from_random(random_type, domain, dtype=np.float64, **kwargs):
     -------
     Field or MultiField
         The newly created random field
+
+    Notes
+    -----
+    When called with a multi-domain, the individual fields will be drawn in
+    alphabetical order of the multi-domain's domain keys. As a consequence,
+    renaming these keys may cause the multi-field to be filled with different
+    random numbers, even for the same initial RNG state.
     """
     if isinstance(domain, (dict, MultiDomain)):
         return MultiField.from_random(random_type, domain, dtype, **kwargs)