symmray.utils ============= .. py:module:: symmray.utils .. autoapi-nested-parse:: Utility functions, mostly for generating random symmray indices and arrays Attributes ---------- .. autoapisummary:: symmray.utils.DEBUG symmray.utils.rand_z2_index Classes ------- .. autoapisummary:: symmray.utils.RandomStateTranslated Functions --------- .. autoapisummary:: symmray.utils.set_debug symmray.utils.lazyabstractmethod symmray.utils.hasher symmray.utils.get_rng symmray.utils.get_random_fill_fn symmray.utils.rand_partition symmray.utils.get_zn_charges symmray.utils.rand_zn_index symmray.utils.rand_z2z2_index symmray.utils.get_u1_charges symmray.utils.rand_u1_index symmray.utils.get_u1u1_charges symmray.utils.rand_u1u1_index symmray.utils.rand_index symmray.utils.get_array_cls symmray.utils.choose_duals symmray.utils.get_rand symmray.utils.get_rand_blockvector symmray.utils.from_dense Module Contents --------------- .. py:data:: DEBUG .. py:function:: set_debug(debug) .. py:function:: 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. .. py:function:: hasher(k) .. py:class:: RandomStateTranslated(rng) Simple wrapper to make `numpy.random.RandomState` have the same interface as `numpy.random.Generator`. .. py:attribute:: rng .. py:method:: integers(*args, **kwargs) .. py:method:: __getattribute__(name) .. py:function:: get_rng(seed=None) .. py:function:: 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. :param seed: The seed for the random number generator. :type seed: None, int, or numpy.random.Generator, optional :param dist: The distribution of the random numbers. Can be "normal" or "uniform" or any other distribution supported by numpy. :type dist: str, optional :param dtype: The data type of the random numbers. If "complex", the real and imaginary parts are generated separately and added. :type dtype: str, optional :param scale: A multiplicative factor to the distribution. :type scale: float, optional :param loc: An additive offset to the distribution. :type loc: float, optional :returns: A function with signature `fill_fn(shape) -> numpy.ndarray`. :rtype: callable .. py:function:: rand_partition(d, n, seed=None) Randomly partition `d` into `n` sizes each of size at least 1. .. py:function:: 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. :param ncharge: The number of distinct charges to get. :type ncharge: int :param order: The order (i.e. size, N) of the cyclic group ZN. :type order: int :returns: **charges** -- A list of `ncharge <= order` distinct ZN charges. :rtype: list[int] .. py:function:: rand_zn_index(d, order, dual='random', subsizes='random', seed=None) Generate a random ZN index with the given dimension and order. :param d: The total size of the index. If a dict, an explicit chargemap. If a sequence, a linearmap. :type d: int, dict[hashable, int] or sequence[(hashable, int), ...] :param order: The order (i.e. size, N) of the cyclic group ZN. :type order: int :param dual: The dualness of the index. If "random", it is randomly chosen. :type dual: bool or "random", optional :param subsizes: 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'. :type subsizes: "random", "equal", "maximal", "minimal", or tuple[int], optional :param seed: The seed for the random number generator. :type seed: None, int, or numpy.random.Generator, optional :rtype: BlockIndex .. py:data:: rand_z2_index .. py:function:: rand_z2z2_index(d, dual='random', subsizes='random', seed=None) .. py:function:: 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. .. py:function:: rand_u1_index(d, dual='random', subsizes='random', seed=None) Generate a random U1 index with the given dimension. :param d: The total size of the index. :type d: int :param dual: The dualness of the index. If "random", it is randomly chosen. :type dual: bool or "random", optional :param subsizes: 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'. :type subsizes: "random", "equal", "maximal", "minimal", or tuple[int], optional :param seed: The seed for the random number generator. :type seed: None, int, or numpy.random.Generator, optional :rtype: BlockIndex .. py:function:: get_u1u1_charges(ncharge) Get a list of ``ncharge`` distinct U1U1 charges that are as close to the origin as possible. .. py:function:: rand_u1u1_index(d, dual='random', subsizes='random', seed=None) .. py:function:: rand_index(symmetry, d, dual='random', subsizes='random', seed=None) Get a random index with the given symmetry. :param symmetry: The symmetry of the index. :type symmetry: str or Symmetry :param d: 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. :type d: int, dict, sequence, or BlockIndex :param dual: The dualness of the index. If "random", it is randomly chosen. :type dual: bool or "random", optional :param subsizes: 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'. :type subsizes: "random", "equal", "maximal", "minimal", or tuple[int], optional :param seed: The seed for the random number generator. :type seed: None, int, or numpy.random.Generator, optional :rtype: BlockIndex .. py:function:: get_array_cls(symmetry, fermionic=False, flat=False) -> type Get the array class for the given symmetry, fermionic flag, and flat flag. .. py:function:: choose_duals(duals, ndim) .. py:function:: 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. :param symmetry: The symmetry of the array. :type symmetry: str :param shape: 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`. :type shape: tuple[int | dict | sequence | BlockIndex, ...] :param duals: 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. :type duals: "random", "equals", or Sequence[bool], optional :param charge: The total charge of the array. If not given the 'zero' charge is used, which depends on the symmetry. :type charge: int or tuple[int], optional :param seed: The seed for the random number generator. :type seed: None, int, or numpy.random.Generator, optional :param dist: The distribution of the random numbers. Can be "normal" or "uniform". :type dist: str, optional :param fermionic: Whether to generate a fermionic array. :type fermionic: bool, optional :param label: An optional label for the array, potentially needed for ordering dummy odd fermionic modes. :type label: hashable, optional :param flat: 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. :type flat: bool, optional :param subsizes: 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. :type subsizes: "random", "equal", "maximal", "minimal", or tuple[int], optional :param kwargs: Additional keyword arguments are passed to the random array generation function. :rtype: AbelianArray or FermionicArray .. py:function:: get_rand_blockvector(size, block_size=0.25, seed=None, dist='normal') .. py:function:: from_dense(array, symmetry, index_maps, duals=None, fermionic=False, charge=None, flat=False, **kwargs)