Commit a2ca9fd9 authored by Gordian Edenhofer's avatar Gordian Edenhofer
Browse files

Highlight that keys in a multi-domain are sorted

As the ordering of the random numbers within a multi-field are dependent
on the ordering of the keys, it is highly relevant even for the average
nifty user that keys are sorted. Hence, state so in the docstrings of
MultiDomain, MultiField and in the `from_random` method in sugar.py.
parent 83cc5351
Pipeline #75040 passed with stages
in 35 minutes and 4 seconds
......@@ -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 number are distributed sequentially
over a multi-domain. In this example, ordering keys differently will change
the resulting :class:`MultiField`.
"""
_domainCache = {}
......
......@@ -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 ordering of the keys within a multi-domain WILL change the resulting
:class:`MultiField`. Note, since keys in a :class:`MultiDomain` are sorted,
renaming keys may also impacts the ordering of the generated random numbers
within the returned :class:`MultiField`.
"""
domain = MultiDomain.make(domain)
if isinstance(dtype, dict):
dtype = {kk: np.dtype(dt) for kk, dt in dtype.items()}
......
......@@ -274,6 +274,13 @@ def from_random(random_type, domain, dtype=np.float64, **kwargs):
-------
Field or MultiField
The newly created random field
Notes
-----
The ordering of the keys within a multi-domain WILL change the resulting
:class:`MultiField`. Note, since keys in a :class:`MultiDomain` are sorted,
renaming keys may also impacts the ordering of the generated random numbers
within the returned :class:`MultiField`.
"""
if isinstance(domain, (dict, MultiDomain)):
return MultiField.from_random(random_type, domain, dtype, **kwargs)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment