flopscope.

flopscope.numpy.random.symmetric

flopscope.numpy.random.symmetric(shape, symmetry, distribution='randn', **distribution_kwargs)[flopscope source]

Sample random data and project it to a symmetry group.

Parameters

shape:int or tuple of int

Shape of the sampled array.

symmetry:SymmetryGroup

Symmetry group used for Reynolds averaging.

distribution:str or callable, default ``"randn"``

Name of a flops.random distribution function (for example "randn" or "normal"), or a callable that accepts either:

  • (*shape, **kwargs)

  • size=shape

and returns an array.

**distribution_kwargs

Extra keyword arguments forwarded to the distribution function.

Returns

:SymmetricTensor

The symmetrized sample wrapped with flops.as_symmetric.

Raises

:ValueError

If shape is not an integer or a tuple/list of integers.

:TypeError

If distribution is neither a NumPy random distribution name nor a callable.

:AttributeError

If distribution is a string that is not present in NumPy random.

:SymmetryError

If projected output does not satisfy the requested symmetry constraints.

Notes

This is equivalent to flops.symmetrize(sampled_data, symmetry=symmetry) where sampled_data is drawn from distribution.

The implementation currently:

  1. Samples raw values from the selected distribution.

  2. Applies flops.symmetrize to project into the symmetry-invariant subspace.

Estimated FLOP cost is approximately:

C_dist(n_elem) + |G| * n_elem + n_elem (+ validation),

where n_elem is the sampled array size, |G| is the group order, and C_dist(n_elem) is the cost of the chosen sampling distribution. The default distribution='randn' corresponds to C_dist(n_elem)≈n_elem.

For existing data, use flops.symmetrize directly.

Examples

>>> import flopscope as flops
>>> import flopscope.numpy as fnp
>>> S = fnp.random.symmetric((4, 4), flops.SymmetryGroup.symmetric(axes=(0, 1)))
>>> S.is_symmetric((0, 1))
True
>>> S = fnp.random.symmetric(
... (3, 3, 3),
... flops.SymmetryGroup.cyclic(axes=(0, 1, 2)),
... distribution="normal",
... loc=0.0,
... scale=1.0,
... )
>>> S.is_symmetric((0, 1, 2))
True
>>> import flopscope.numpy as fnp
>>> import flopscope as flops
>>> import flopscope.numpy as fnp
>>> def shifted_uniform(shape, **kwargs):
... return flops.random.uniform(*shape, **kwargs)
>>> S = fnp.random.symmetric(
... (2, 2),
... flops.SymmetryGroup.symmetric(axes=(0, 1)),
... distribution=shifted_uniform,
... )
>>> S.is_symmetric((0, 1))
True