quimb.gen.rand ============== .. py:module:: quimb.gen.rand .. autoapi-nested-parse:: Functions for generating random quantum objects and states. Attributes ---------- .. autoapisummary:: quimb.gen.rand._RG_HANDLER quimb.gen.rand.choice quimb.gen.rand.rand_mps Classes ------- .. autoapisummary:: quimb.gen.rand._RGenHandler Functions --------- .. autoapisummary:: quimb.gen.rand.seed_rand quimb.gen.rand.set_rand_bitgen quimb.gen.rand._get_rgens quimb.gen.rand.randn quimb.gen.rand.rand quimb.gen.rand.random_seed_fn quimb.gen.rand._randint quimb.gen.rand._choice quimb.gen.rand.rand_rademacher quimb.gen.rand.rand_phase quimb.gen.rand.get_rand_fill_fn quimb.gen.rand.rand_matrix quimb.gen.rand.rand_herm quimb.gen.rand.rand_pos quimb.gen.rand.rand_rho quimb.gen.rand.rand_uni quimb.gen.rand.rand_ket quimb.gen.rand.rand_haar_state quimb.gen.rand.gen_rand_haar_states quimb.gen.rand.rand_mix quimb.gen.rand.rand_product_state quimb.gen.rand.rand_matrix_product_state quimb.gen.rand.rand_seperable quimb.gen.rand.rand_iso quimb.gen.rand.rand_mera Module Contents --------------- .. py:class:: _RGenHandler(initial_seed=None, initial_bitgen=None) Private object that handles pool of random number generators for parallel number generation - seeding them & changing the underlying bit generators. .. py:attribute:: rgs :value: [] .. py:method:: set_bitgen(bitgen) Set the core underlying bit-generator. :param bitgen: Which bit generator to use, either from numpy or `randomgen` - https://bashtage.github.io/randomgen/bit_generators/index.html. :type bitgen: {None, str} .. py:method:: set_seed(seed=None) Set the seed for the bit generators. :param seed: Seed supplied to `numpy.random.SeedSequence`. None will randomly the generators (default). :type seed: {None, int}, optional .. py:method:: get_rgens(num_threads) Get a list of the :class:`numpy.random.Generator` instances, having made sure there are at least ``num_threads``. :param num_threads: The number of generators to return. :type num_threads: int :rtype: list[numpy.random.Generator] .. py:data:: _RG_HANDLER .. py:function:: seed_rand(seed) See the random number generators, by instantiating a new set of bit generators with a 'seed sequence'. .. py:function:: set_rand_bitgen(bitgen) Set the core bit generator type to use, from either ``numpy`` or ``randomgen``. :param bitgen: Which bit generator to use. :type bitgen: {'PCG64', 'SFC64', 'MT19937', 'Philox', str} .. py:function:: _get_rgens(num_threads) .. py:function:: randn(shape=(), dtype=float, scale=1.0, loc=0.0, num_threads=None, seed=None, dist='normal') Fast multithreaded generation of random normally distributed data. :param shape: The shape of the output random array. :type shape: tuple[int] :param dtype: The data-type of the output array. :type dtype: {'complex128', 'float64', 'complex64' 'float32'}, optional :param scale: A multiplicative scale for the random numbers. :type scale: float, optional :param loc: An additive location for the random numbers. :type loc: float, optional :param num_threads: How many threads to use. If ``None``, decide automatically. :type num_threads: int, optional :param dist: Type of random number to generate. :type dist: {'normal', 'uniform', 'rademacher', 'exp'}, optional .. py:function:: rand(*args, **kwargs) .. py:function:: random_seed_fn(fn) Modify ``fn`` to take a ``seed`` argument (so as to seed the random generators once-only at beginning of function not every ``randn`` call). .. py:function:: _randint(*args, **kwargs) .. py:function:: _choice(*args, **kwargs) .. py:data:: choice .. py:function:: rand_rademacher(shape, scale=1, loc=0.0, dtype=float) .. py:function:: rand_phase(shape, scale=1, dtype=complex) Generate random complex numbers distributed on the unit sphere. .. py:function:: get_rand_fill_fn(dist='normal', loc=0.0, scale=1.0, seed=None, dtype='float64') Get a callable with the given random distribution and parameters, that has signature ``fill_fn(shape) -> array``. :param dist: Type of random number to generate, defaults to 'normal'. :type dist: {'normal', 'uniform', 'rademacher', 'exp'}, optional :param loc: An additive offset to add to the random numbers. :type loc: float, optional :param scale: A multiplicative factor to scale the random numbers by. :type scale: float, optional :param seed: A random seed. :type seed: int, optional :param dtype: The underlying data type. :type dtype: {'float64', 'complex128', 'float32', 'complex64'}, optional :rtype: callable .. py:function:: rand_matrix(d, scaled=True, sparse=False, stype='csr', density=None, dtype=complex, seed=None) Generate a random matrix of order `d` with normally distributed entries. If `scaled` is `True`, then in the limit of large `d` the eigenvalues will be distributed on the unit complex disk. :param d: Matrix dimension. :type d: int :param scaled: Whether to scale the matrices values such that its spectrum approximately lies on the unit disk (for dense matrices). :type scaled: bool, optional :param sparse: Whether to produce a sparse matrix. :type sparse: bool, optional :param stype: The type of sparse matrix if ``sparse=True``. :type stype: {'csr', 'csc', 'coo', ...}, optional :param density: Target density of non-zero elements for the sparse matrix. By default aims for about 10 entries per row. :type density: float, optional :param dtype: The data type of the matrix elements. :type dtype: {complex, float}, optional :returns: **mat** -- Random matrix. :rtype: qarray or sparse matrix .. py:function:: rand_herm(d, sparse=False, density=None, dtype=complex) Generate a random hermitian operator of order `d` with normally distributed entries. In the limit of large `d` the spectrum will be a semi-circular distribution between [-1, 1]. .. seealso:: :obj:`rand_matrix`, :obj:`rand_pos`, :obj:`rand_rho`, :obj:`rand_uni` .. py:function:: rand_pos(d, sparse=False, density=None, dtype=complex) Generate a random positive operator of size `d`, with normally distributed entries. In the limit of large `d` the spectrum will lie between [0, 1]. .. seealso:: :obj:`rand_matrix`, :obj:`rand_herm`, :obj:`rand_rho`, :obj:`rand_uni` .. py:function:: rand_rho(d, sparse=False, density=None, dtype=complex) Generate a random positive operator of size `d` with normally distributed entries and unit trace. .. seealso:: :obj:`rand_matrix`, :obj:`rand_herm`, :obj:`rand_pos`, :obj:`rand_uni` .. py:function:: rand_uni(d, dtype=complex) Generate a random unitary operator of size `d`, distributed according to the Haar measure. .. seealso:: :obj:`rand_matrix`, :obj:`rand_herm`, :obj:`rand_pos`, :obj:`rand_rho` .. py:function:: rand_ket(d, sparse=False, stype='csr', density=0.01, dtype=complex) Generates a ket of length `d` with normally distributed entries. .. py:function:: rand_haar_state(d, dtype=complex) Generate a random state of dimension `d` according to the Haar distribution. .. py:function:: gen_rand_haar_states(d, reps, dtype=complex) Generate many random Haar states, recycling a random unitary operator by using all of its columns (not a good idea?). .. py:function:: rand_mix(d, tr_d_min=None, tr_d_max=None, mode='rand', dtype=complex) Constructs a random mixed state by tracing out a random ket where the composite system varies in size between 2 and d. This produces a spread of states including more purity but has no real meaning. .. py:function:: rand_product_state(n, qtype=None, dtype=complex) Generates a ket of `n` many random pure qubits. .. py:function:: rand_matrix_product_state(n, bond_dim, phys_dim=2, dtype=complex, cyclic=False, trans_invar=False) Generate a random matrix product state (in dense form, see :func:`~quimb.tensor.MPS_rand_state` for tensor network form). :param n: Number of sites. :type n: int :param bond_dim: Dimension of the bond (virtual) indices. :type bond_dim: int :param phys_dim: Physical dimension of each local site, defaults to 2 (qubits). :type phys_dim: int, optional :param cyclic: Whether to impose cyclic boundary conditions on the entanglement structure. :type cyclic: bool (optional) :param trans_invar: Whether to generate a translationally invariant state, requires cyclic=True. :type trans_invar: bool (optional) :returns: **ket** -- The random state, with shape (phys_dim**n, 1) :rtype: qarray .. py:data:: rand_mps .. py:function:: rand_seperable(dims, num_mix=10, dtype=complex) Generate a random, mixed, seperable state. E.g rand_seperable([2, 2]) for a mixed two qubit state with no entanglement. :param dims: The local dimensions across which to be seperable. :type dims: tuple of int :param num_mix: How many individual product states to sum together, each with random weight. :type num_mix: int, optional :returns: Mixed seperable state. :rtype: qarray .. py:function:: rand_iso(n, m, dtype=complex) Generate a random isometry of shape ``(n, m)``. .. py:function:: rand_mera(n, invariant=False, dtype=complex) Generate a random mera state of ``n`` qubits, which must be a power of 2. This uses ``quimb.tensor``.