symmray.utils

Utility functions, mostly for generating random symmray indices and arrays

Attributes

DEBUG
rand_z2_index

Classes

RandomStateTranslated

Simple wrapper to make numpy.random.RandomState have the same

Functions

set_debug(debug)
lazyabstractmethod(method)	Mark a method as one that must be implemented in a subclass, but only
hasher(k)
get_rng([seed])
get_random_fill_fn([seed, dist, dtype, scale, loc])	Get a function that produces numpy arrays of random numbers with the
rand_partition(d, n[, seed])	Randomly partition d into n sizes each of size at least 1.
get_zn_charges(ncharge, order)	Get a list of ncharge distinct ZN charges that are as close to
rand_zn_index(d, order[, dual, subsizes, seed])	Generate a random ZN index with the given dimension and order.
rand_z2z2_index(d[, dual, subsizes, seed])
get_u1_charges(ncharge)	Get a list of ncharge distinct U1 charges that are as close to the
rand_u1_index(d[, dual, subsizes, seed])	Generate a random U1 index with the given dimension.
get_u1u1_charges(ncharge)	Get a list of ncharge distinct U1U1 charges that are as close to
rand_u1u1_index(d[, dual, subsizes, seed])
rand_index(symmetry, d[, dual, subsizes, seed])	Get a random index with the given symmetry.
get_array_cls(→ type)	Get the array class for the given symmetry, fermionic flag, and flat
choose_duals(duals, ndim)
get_rand(symmetry, shape[, duals, charge, seed, dist, ...])	Get a random symmray array, with the given symmetry and shape. The
get_rand_blockvector(size[, block_size, seed, dist])
from_dense(array, symmetry, index_maps[, duals, ...])

Module Contents

symmray.utils.DEBUG

symmray.utils.set_debug(debug)

symmray.utils.lazyabstractmethod(method)

Mark a method as one that must be implemented in a subclass, but only enforce this when the method is called. This can be used as a decorator (if you want to demonstrate the call signature) or by directly assigning the result to a method name.

symmray.utils.hasher(k)

class symmray.utils.RandomStateTranslated(rng)

Simple wrapper to make numpy.random.RandomState have the same interface as numpy.random.Generator.

rng

integers(*args, **kwargs)

__getattribute__(name)

symmray.utils.get_rng(seed=None)

symmray.utils.get_random_fill_fn(seed=None, dist='normal', dtype='float64', scale=1.0, loc=0.0)

Get a function that produces numpy arrays of random numbers with the specified distribution, dtype, loc, and scale.

Parameters:

• seed (None, int, or numpy.random.Generator, optional) – The seed for the random number generator.

• dist (str, optional) – The distribution of the random numbers. Can be “normal” or “uniform” or any other distribution supported by numpy.

• dtype (str, optional) – The data type of the random numbers. If “complex”, the real and imaginary parts are generated separately and added.

• scale (float, optional) – A multiplicative factor to the distribution.

• loc (float, optional) – An additive offset to the distribution.

Returns:

A function with signature fill_fn(shape) -> numpy.ndarray.

Return type:

callable

symmray.utils.rand_partition(d, n, seed=None)

Randomly partition d into n sizes each of size at least 1.

symmray.utils.get_zn_charges(ncharge, order)

Get a list of ncharge distinct ZN charges that are as close to 0 or |G| as possible, with a slight bias towards positive charges.

Parameters:

• ncharge (int) – The number of distinct charges to get.

• order (int) – The order (i.e. size, N) of the cyclic group ZN.

Returns:

charges – A list of ncharge <= order distinct ZN charges.

Return type:

list[int]

symmray.utils.rand_zn_index(d, order, dual='random', subsizes='random', seed=None)

Generate a random ZN index with the given dimension and order.

Parameters:

• d (int, dict[hashable, int] or sequence[(hashable, int), ...]) – The total size of the index. If a dict, an explicit chargemap. If a sequence, a linearmap.

• order (int) – The order (i.e. size, N) of the cyclic group ZN.

• dual (bool or "random", optional) – The dualness of the index. If “random”, it is randomly chosen.

• subsizes ("random", "equal", "maximal", "minimal", or tuple[int], optional) –

  The sizes of the charge sectors. The choices are as follows:

  • ”random”: the charges and sizes are randomly determined.

  • ”equal”: a fixed number of charges ‘close to’ zero charge are chosen, all with equal size (up to remainders).

  • ”maximal”: as many charges as possible are chosen, each with size 1 (or more if the total number of charges is less than the total size).

  • ”minimal”: only the zero charge sector is chosen, with full size.

  • tuple: the sizes of the charge sectors, a matching number of charges are chosen automatically, in sequence ‘closest to zero’.

• seed (None, int, or numpy.random.Generator, optional) – The seed for the random number generator.

Return type:

BlockIndex

symmray.utils.rand_z2_index

symmray.utils.rand_z2z2_index(d, dual='random', subsizes='random', seed=None)

symmray.utils.get_u1_charges(ncharge)

Get a list of ncharge distinct U1 charges that are as close to the origin as possible, with a slight bias towards positive charges.

symmray.utils.rand_u1_index(d, dual='random', subsizes='random', seed=None)

Generate a random U1 index with the given dimension.

Parameters:

• d (int) – The total size of the index.

• dual (bool or "random", optional) – The dualness of the index. If “random”, it is randomly chosen.

• subsizes ("random", "equal", "maximal", "minimal", or tuple[int], optional) –

  The sizes of the charge sectors. The choices are as follows:

  • ”random”: the charges and sizes are randomly determined.

  • ”equal”: a fixed number of charges ‘close to’ zero charge are chosen, all with equal size (up to remainders).

  • ”maximal”: as many charges as possible are chosen, each with size 1 (or more if the total number of charges is less than the total size).

  • ”minimal”: only the zero charge sector is chosen, with full size.

  • tuple: the sizes of the charge sectors, a matching number of charges are chosen automatically, in sequence ‘closest to zero’.

• seed (None, int, or numpy.random.Generator, optional) – The seed for the random number generator.

Return type:

BlockIndex

symmray.utils.get_u1u1_charges(ncharge)

Get a list of ncharge distinct U1U1 charges that are as close to the origin as possible.

symmray.utils.rand_u1u1_index(d, dual='random', subsizes='random', seed=None)

symmray.utils.rand_index(symmetry, d, dual='random', subsizes='random', seed=None)

Get a random index with the given symmetry.

Parameters:

• symmetry (str or Symmetry) – The symmetry of the index.

• d (int, dict, sequence, or BlockIndex) – The total size of the index. If a dict, an explicit chargemap. If a sequence an explicit linearmap. If a BlockIndex, it is returned unchanged.

• dual (bool or "random", optional) – The dualness of the index. If “random”, it is randomly chosen.

• subsizes ("random", "equal", "maximal", "minimal", or tuple[int], optional) –

  The sizes of the charge sectors. The choices are as follows:

  • ”random”: the charges and sizes are randomly determined.

  • ”equal”: a fixed number of charges ‘close to’ zero charge are chosen, all with equal size (up to remainders).

  • ”maximal”: as many charges as possible are chosen, each with size 1 (or more if the total number of charges is less than the total size).

  • ”minimal”: only the zero charge sector is chosen, with full size.

  • tuple: the sizes of the charge sectors, a matching number of charges are chosen automatically, in sequence ‘closest to zero’.

• seed (None, int, or numpy.random.Generator, optional) – The seed for the random number generator.

Return type:

BlockIndex

symmray.utils.get_array_cls(symmetry, fermionic=False, flat=False) → type

Get the array class for the given symmetry, fermionic flag, and flat flag.

symmray.utils.choose_duals(duals, ndim)

symmray.utils.get_rand(symmetry, shape, duals='random', charge=None, seed=None, dist='normal', fermionic=False, label=None, flat=False, subsizes='random', **kwargs)

Get a random symmray array, with the given symmetry and shape. The duals, charge, and sub charge sizes can be specified or automatically or randomly generated.

Parameters:

• symmetry (str) – The symmetry of the array.

• shape (tuple[int | dict | sequence | BlockIndex, ...]) – The desired overall effective shape of the array. Each element can be an int, in which case the charge sizes will be generated automatically according to subsizes, or an explicit dict of charge sizes, or an explicit linearmap, or a BlockIndex.

• duals ("random", "equals", or Sequence[bool], optional) – The dualness of each index. If “random”, the dualnesses are chosen randomly. If “equal”, they are chosen so the first half of the indices have dual=False and the second half have dual=True. If shape contains BlockIndex objects, the dualness of that index takes precedence over any specification here.

• charge (int or tuple[int], optional) – The total charge of the array. If not given the ‘zero’ charge is used, which depends on the symmetry.

• seed (None, int, or numpy.random.Generator, optional) – The seed for the random number generator.

• dist (str, optional) – The distribution of the random numbers. Can be “normal” or “uniform”.

• fermionic (bool, optional) – Whether to generate a fermionic array.

• label (hashable, optional) – An optional label for the array, potentially needed for ordering dummy odd fermionic modes.

• flat (bool, optional) – Whether to generate a ‘flat’ backend array (True) or the default block-sparse backend array (False). If flat, then subsizes should be set to “equal” or equivalent.

• subsizes ("random", "equal", "maximal", "minimal", or tuple[int], optional) –

  The sizes of the charge sectors. The choices are as follows:

  • ”random”: the charges and sizes are randomly determined.

  • ”equal”: a fixed number of charges ‘close to’ zero charge are chosen, all with equal size (up to remainders).

  • ”maximal”: as many charges as possible are chosen, each with size 1 (or more if the total number of charges is less than the total size).

  • ”minimal”: only the zero charge sector is chosen, with full size.

  • tuple: the sizes of the charge sectors, a matching number of charges are chosen automatically, in sequence ‘closest to zero’.

  If shape contains dict or BlockIndex objects, the subsizes of those indices take precedence over any specification here.

• kwargs – Additional keyword arguments are passed to the random array generation function.

Return type:

AbelianArray or FermionicArray

symmray.utils.get_rand_blockvector(size, block_size=0.25, seed=None, dist='normal')

symmray.utils.from_dense(array, symmetry, index_maps, duals=None, fermionic=False, charge=None, flat=False, **kwargs)