oasislmf.pytools.gul.random
===========================

.. py:module:: oasislmf.pytools.gul.random

.. autoapi-nested-parse::

   This file contains the utilities for generating random numbers in gulpy.



Attributes
----------

.. autoapisummary::

   oasislmf.pytools.gul.random.logger
   oasislmf.pytools.gul.random.GROUP_ID_HASH_CODE
   oasislmf.pytools.gul.random.EVENT_ID_HASH_CODE
   oasislmf.pytools.gul.random.HASH_MOD_CODE
   oasislmf.pytools.gul.random.HAZARD_GROUP_ID_HASH_CODE
   oasislmf.pytools.gul.random.HAZARD_EVENT_ID_HASH_CODE
   oasislmf.pytools.gul.random.HAZARD_HASH_MOD_CODE
   oasislmf.pytools.gul.random.EVENT_ID_HASH_CODE
   oasislmf.pytools.gul.random.PERIL_CORRELATION_GROUP_HASH
   oasislmf.pytools.gul.random.HASH_MOD_CODE


Functions
---------

.. autoapisummary::

   oasislmf.pytools.gul.random.generate_hash
   oasislmf.pytools.gul.random.generate_hash_hazard
   oasislmf.pytools.gul.random.get_random_generator
   oasislmf.pytools.gul.random.generate_correlated_hash_vector
   oasislmf.pytools.gul.random.compute_norm_inv_cdf_lookup
   oasislmf.pytools.gul.random.compute_norm_cdf_lookup
   oasislmf.pytools.gul.random.get_norm_cdf_cell_nb
   oasislmf.pytools.gul.random.get_corr_rval
   oasislmf.pytools.gul.random.random_MersenneTwister
   oasislmf.pytools.gul.random.random_LatinHypercube


Module Contents
---------------

.. py:data:: logger

.. py:data:: GROUP_ID_HASH_CODE

.. py:data:: EVENT_ID_HASH_CODE

.. py:data:: HASH_MOD_CODE

.. py:data:: HAZARD_GROUP_ID_HASH_CODE

.. py:data:: HAZARD_EVENT_ID_HASH_CODE

.. py:data:: HAZARD_HASH_MOD_CODE

.. py:function:: generate_hash(group_id, event_id, base_seed=0)

   Generate hash for a given `group_id`, `event_id` pair for the vulnerability pdf.

   Args:
       group_id (int): group id.
       event_id (int]): event id.
       base_seed (int, optional): base random seed. Defaults to 0.

   Returns:
       int64: hash


.. py:function:: generate_hash_hazard(hazard_group_id, event_id, base_seed=0)

   Generate hash for a given `hazard_group_id`, `event_id` pair for the hazard pdf.

   Args:
       hazard_group_id (int): group id.
       event_id (int]): event id.
       base_seed (int, optional): base random seed. Defaults to 0.

   Returns:
       int64: hash


.. py:function:: get_random_generator(random_generator)

   Get the random generator function.

   Args:
       random_generator (int): random generator function id.

   Returns:
       The random generator function.



.. py:data:: EVENT_ID_HASH_CODE

.. py:data:: PERIL_CORRELATION_GROUP_HASH

.. py:data:: HASH_MOD_CODE

.. py:function:: generate_correlated_hash_vector(unique_peril_correlation_groups, event_id, base_seed=0)

   Generate hashes for all peril correlation groups for a given `event_id`.

   Args:
       unique_peril_correlation_groups (List[int]): list of the unique peril correlation groups.
       event_id (int): event id.
       base_seed (int, optional): base random seed. Defaults to 0.

   Returns:
       List[int64]: hashes


.. py:function:: compute_norm_inv_cdf_lookup(cdf_min, cdf_max, N)

.. py:function:: compute_norm_cdf_lookup(x_min, x_max, N)

.. py:function:: get_norm_cdf_cell_nb(x, x_min, x_max, N)

.. py:function:: get_corr_rval(x_unif, y_unif, rho, x_min, x_max, N, norm_inv_cdf, cdf_min, cdf_max, norm_cdf, Nsamples, z_unif)

.. py:function:: random_MersenneTwister(seeds, n, skip_seeds=0)

   Generate random numbers using the default Mersenne Twister algorithm.

   Args:
       seeds (List[int64]): List of seeds.
       n (int): number of random samples to generate for each seed.
       skip_seeds (int): number of seeds to skip starting from the beginning
         of the `seeds` array. For skipped seeds no random numbers are generated
         and the output rndms will contain zeros at their corresponding row.
         Default is 0, i.e. no seeds are skipped.

   Returns:
       rndms (array[float]): 2-d array of shape (number of seeds, n) 
         containing the random values generated for each seed.
       rndms_idx (Dict[int64, int]): mapping between `seed` and the 
         row in rndms that stores the corresponding random values.


.. py:function:: random_LatinHypercube(seeds, n, skip_seeds=0)

   Generate random numbers using the Latin Hypercube algorithm.

   Args:
       seeds (List[int64]): List of seeds.
       n (int): number of random samples to generate for each seed.

   Returns:
       rndms (array[float]): 2-d array of shape (number of seeds, n) 
         containing the random values generated for each seed.
       rndms_idx (Dict[int64, int]): mapping between `seed` and the 
         row in rndms that stores the corresponding random values.
       skip_seeds (int): number of seeds to skip starting from the beginning
         of the `seeds` array. For skipped seeds no random numbers are generated
         and the output rndms will contain zeros at their corresponding row.
         Default is 0, i.e. no seeds are skipped.

   Notes:
       Implementation follows scipy.stats.qmc.LatinHypercube v1.8.0.
       Following scipy notation, here we assume `centered=False` all the times:
       instead of taking `samples=0.5*np.ones(n)`, here we always
       draw uniform random samples in order to initialise `samples`.