
    h                    |    S r SSKJr  SSKJrJrJr  SSKJr  SSK	r
SSKJrJr   " S S\\
R                     5      rg)	z?Implementation of a space consisting of finitely many elements.    )annotations)IterableMappingSequence)AnyN)MaskNDArraySpacec                     ^  \ rS rSrSr  S     SU 4S jjjr\S 5       r S     SS jjrSS jr	SS jr
SS jrSU 4S	 jjrSS
 jrSS jrSrU =r$ )Discrete   a  A space consisting of finitely many elements.

This class represents a finite subset of integers, more specifically a set of the form :math:`\{ a, a+1, \dots, a+n-1 \}`.

Example:
    >>> from gymnasium.spaces import Discrete
    >>> observation_space = Discrete(2, seed=42) # {0, 1}
    >>> observation_space.sample()
    np.int64(0)
    >>> observation_space = Discrete(3, start=-1, seed=42)  # {-1, 0, 1}
    >>> observation_space.sample()
    np.int64(-1)
    >>> observation_space.sample(mask=np.array([0,0,1], dtype=np.int8))
    np.int64(1)
    >>> observation_space.sample(probability=np.array([0,0,1], dtype=np.float64))
    np.int64(1)
    >>> observation_space.sample(probability=np.array([0,0.3,0.7], dtype=np.float64))
    np.int64(1)
c                  > [         R                  " [        U5      [         R                  5      (       d   S[        U5       35       eUS:  d   S5       e[         R                  " [        U5      [         R                  5      (       d   S[        U5       35       e[         R                  " U5      U l        [         R                  " U5      U l        [        TU ]!  S[         R                  U5        g)a[  Constructor of :class:`Discrete` space.

This will construct the space :math:`\{\text{start}, ..., \text{start} + n - 1\}`.

Args:
    n (int): The number of elements of this space.
    seed: Optionally, you can use this argument to seed the RNG that is used to sample from the ``Dict`` space.
    start (int): The smallest element of this space.
z,Expects `n` to be an integer, actual dtype: r   zn (counts) have to be positivez/Expects `start` to be an integer, actual type:  N)	np
issubdtypetypeintegerint64nstartsuper__init__)selfr   seedr   	__class__s       S/home/james-whalen/.local/lib/python3.13/site-packages/gymnasium/spaces/discrete.pyr   Discrete.__init__"   s     }}GRZZ
 
 	D9$q'C	D 
 1u666u}}K
 
 	K<T%[MJ	K 
 !XXe_
RXXt,    c                    g)zDChecks whether this space can be flattened to a :class:`spaces.Box`.Tr   r   s    r   is_np_flattenableDiscrete.is_np_flattenable=   s     r   c                B   Ub  Ub  [        SU SU 35      eUGbR  [        U[        R                  5      (       d   S[	        U5       35       eUR
                  [        R                  :X  d   SUR
                   35       eUR                  U R                  4:X  d+   S[        U R                  5      4 SUR                   35       eUS:H  n[        R                  " [        R                  " US:H  U5      5      (       d
   S	U 35       e[        R                  " U5      (       a?  U R                  U R                  R                  [        R                   " U5      S   5      -   $ U R                  $ UGb}  [        U[        R                  5      (       d   S
[	        U5       35       eUR
                  [        R"                  :X  d   SUR
                   35       eUR                  U R                  4:X  d+   S[        U R                  5      4 SUR                   35       e[        R                  " [        R$                  " US:  US:*  5      5      (       d
   SU 35       e[        R&                  " [        R(                  " U5      S5      (       d   S[        R(                  " U5       35       eU R                  U R                  R                  [        R*                  " U R                  5      US9-   $ U R                  U R                  R-                  U R                  5      -   $ )a  Generates a single random sample from this space.

A sample will be chosen uniformly at random with the mask if provided, or it will be chosen according to a specified probability distribution if the probability mask is provided.

Args:
    mask: An optional mask for if an action can be selected.
        Expected `np.ndarray` of shape ``(n,)`` and dtype ``np.int8`` where ``1`` represents valid actions and ``0`` invalid / infeasible actions.
        If there are no possible actions (i.e. ``np.all(mask == 0)``) then ``space.start`` will be returned.
    probability: An optional probability mask describing the probability of each action being selected.
        Expected `np.ndarray` of shape ``(n,)`` and dtype ``np.float64`` where each value is in the range ``[0, 1]`` and the sum of all values is 1.
        If the values do not sum to 1, an exception will be thrown.

Returns:
    A sampled integer from the space
zIOnly one of `mask` or `probability` can be provided, actual values: mask=z, probability=zAThe expected type of the sample mask is np.ndarray, actual type: z@The expected dtype of the sample mask is np.int8, actual dtype: z)The expected shape of the sample mask is z, actual shape:    r   z?All values of the sample mask should be 0 or 1, actual values: zHThe expected type of the sample probability is np.ndarray, actual type: zJThe expected dtype of the sample probability is np.float64, actual dtype: z0The expected shape of the sample probability is zOAll values of the sample probability should be between 0 and 1, actual values: zDThe sum of the sample probability should be equal to 1, actual sum: )p)
ValueError
isinstancer   ndarrayr   dtypeint8shaper   intall
logical_oranyr   	np_randomchoicewherefloat64logical_andisclosesumarangeintegers)r   maskprobabilityvalid_action_masks       r   sampleDiscrete.sampleB   s<   $  7[\`[aaop{o|}  bjj  `RSWX\S]R^_`  

bgg%_QRVR\R\Q]^_%::"  h:CK>:JJZ[_[e[eZfgh  !%	66dai):;  XPQUPVWX  vv'((zzDNN$9$9HH./2%   zz!$RZZ  nYZ^_jZkYlmn  !!RZZ/p[\g\m\m[nop/$$)  vA3tvv;.AQQabmbsbsatuv  66{a/1AB  o`al`mno  ::{#Q  lUVXV\V\]hViUjkl  :: 5 5bii6G; 5 WWW :: 7 7 ???r   c                   [        U[        5      (       a  [        R                  " U5      nO[        U[        R                  [        R
                  45      (       a[  [        R                  " UR                  [        R                  5      (       a'  UR                  S:X  a  [        R                  " U5      nOg[        U R                  Us=:*  =(       a     U R                  U R                  -   :  5      $ s  5      $ )z?Return boolean specifying if x is a valid member of this space.r   F)r&   r+   r   r   genericr'   r   r(   r   r*   boolr   r   )r   xas_int64s      r   containsDiscrete.contains   s    axx{HBJJ

344MM!''2::..177b=xx{HDJJ(@@TZZ$&&-@@AA@AAr   c                |    U R                   S:w  a  SU R                   SU R                    S3$ SU R                   S3$ )z,Gives a string representation of this space.r   z	Discrete(z, start=))r   r   r   s    r   __repr__Discrete.__repr__   s=    ::?tvvhhtzzl!<<466(!$$r   c                    [        U[        5      =(       a9    U R                  UR                  :H  =(       a    U R                  UR                  :H  $ )z7Check whether ``other`` is equivalent to this instance.)r&   r   r   r   )r   others     r   __eq__Discrete.__eq__   s=     uh' *%''!*

ekk)	
r   c                x   > [        U5      nSU;  a  [        R                  " S5      US'   [        TU ]  U5        g)zUsed when loading a pickled space.

This method has to be implemented explicitly to allow for loading of legacy states.

Args:
    state: The new state
r   r   N)dictr   r   r   __setstate__)r   stater   s     r   rN   Discrete.__setstate__   s6     U %XXa[E'NU#r   c                D    U Vs/ s H  n[        U5      PM     sn$ s  snf )z-Converts a list of samples to a list of ints.)r+   r   sample_nr@   s      r   to_jsonableDiscrete.to_jsonable   s     ()1A)))s   c                Z    U Vs/ s H  n[         R                  " U5      PM     sn$ s  snf )z6Converts a list of json samples to a list of np.int64.)r   r   rR   s      r   from_jsonableDiscrete.from_jsonable   s"    %-.XX...s    ()r   r   )Nr   )r   int | np.integer[Any]r   z int | np.random.Generator | Noner   rY   )NN)r8   MaskNDArray | Noner9   rZ   returnznp.int64)r@   r   r[   r?   )r[   str)rI   r   r[   r?   )rO   z-Iterable[tuple[str, Any]] | Mapping[str, Any])rS   zSequence[np.int64]r[   	list[int])rS   r]   r[   zlist[np.int64])__name__
__module____qualname____firstlineno____doc__r   propertyr    r;   rB   rF   rJ   rN   rT   rW   __static_attributes____classcell__)r   s   @r   r   r      s    . 26'(	- - /- %	- -6  
 RVC@&C@<NC@	C@JB%
$$*/ /r   r   )rb   
__future__r   collections.abcr   r   r   typingr   numpyr   gymnasium.spaces.spacer   r	   r   r   r   r   r   <module>rk      s0    E " 7 7   5m/uRXX m/r   