scml.common
===========

.. py:module:: scml.common

.. autoapi-nested-parse::

   Common functions used in all modules



Attributes
----------

.. autoapisummary::

   scml.common.IterableOrInt
   scml.common.IterableOrFloat
   scml.common.IterableOrClass
   scml.common.IterableOrObject
   scml.common.EPSILON


Functions
---------

.. autoapisummary::

   scml.common.isinobject
   scml.common.isinclass
   scml.common.isin
   scml.common.isinfloat
   scml.common.fraction_cut
   scml.common.integer_cut
   scml.common.realin
   scml.common.strin
   scml.common.intin
   scml.common.make_array
   scml.common.distribute_quantities
   scml.common.distribute


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

.. py:data:: IterableOrInt

.. py:data:: IterableOrFloat

.. py:data:: IterableOrClass

.. py:data:: IterableOrObject

.. py:data:: EPSILON
   :value: 1e-05


.. py:function:: isinobject(x: IterableOrObject, y: IterableOrClass)

.. py:function:: isinclass(x: IterableOrClass, y: IterableOrClass)

   Checks that x is within the range specified by y. Ugly but works


.. py:function:: isin(x: IterableOrInt, y: IterableOrInt)

   Checks that x is within the range specified by y. Ugly but works


.. py:function:: isinfloat(x: IterableOrFloat, y: IterableOrFloat)

   Checks that x is within the range specified by y. Ugly but works


.. py:function:: fraction_cut(n: int, p: numpy.ndarray) -> numpy.ndarray

   Distributes n items on boxes with probabilities relative to p


.. py:function:: integer_cut(total: int, n: int, mx: int | list[int], mn: int | list[int] | None = None, randomize: bool = True) -> list[int]

   Generates l random integers that sum to n where each of them is at least l_m
   :param n: total
   :param l: number of levels
   :param l_m: minimum per level
   :param l_x: maximum per level
   :param randomize: If true, the integers resulting are randomized otherwise they will always be in the same order

   Returns:



.. py:function:: realin(rng: tuple[float, float] | float | list[float] | numpy.ndarray) -> float

   Selects a random number within a range if given or the input if it was a float

   :param rng: Range or single value

   :returns: the real within the given range


.. py:function:: strin(lst: list[str] | str) -> str

   Selects a random string from a list (or just returns the string if no list
   is given)

   :param lst: list of value

   :returns: the real within the given range


.. py:function:: intin(rng: tuple[int, int] | int | list[int] | numpy.ndarray) -> int

   Selects a random number within a range if given or the input if it was an int

   :param rng: Range or single value

   :returns: the int within the given range


.. py:function:: make_array(x: numpy.ndarray | list[int] | tuple[int | float, int | float] | int | float, n: int, dtype: type[float] | type[int] = int, min_total: int = 0) -> numpy.ndarray

   Creates an array with the given choices


.. py:function:: distribute_quantities(equal: bool, predictability: float, q: list[int] | numpy.typing.NDArray, a: int, n_steps: int, limit: list[int] | None = None)

   Used internally by generate() methods to distribute exogenous contracts

   :param equal: whether the quantities are to be distributed equally
   :param predictability: how much are quantities for the same agent at different
                          times are similar
   :param q: The quantity per step to be distributed
   :param a: The number of agents to distribute over.
   :param limit: The maximum quantity per step for each agent (len(limit) == a). Only used if `equal==False`

   :returns: an n_steps * a list of lists giving the distributed quantities where
             sum[s, :] ~= q[s]. The error can be up to 2*a per step


.. py:function:: distribute(q: int, n: int, *, mx: int | None = None, equal=False, concentrated=False, allow_zero=False) -> list[int]

   Distributes q values over n bins.

   :param q: Quantity to distribute
   :param n: number of bins to distribute q over
   :param mx: Maximum allowed per bin. `None` for no limit
   :param equal: Try to make the values in each bins as equal as possible
   :param concentrated: If true, will try to concentrate offers in few bins. `mx` must be passed in this case
   :param allow_zero: Allow some bins to be zero even if that is not necessary