h^\ SrSSKJr SSKrSSKJrJr SSKJ r J r J r SSK r SSKJr SSKrSSKJrJrJrJrJrJrJrJrJrJrJrJr \S8Sj5r\RA\5\RA\5S9S j55r!\RA\5S:S j5r"\RA\5S;S j5r#\RA\5SSj5r&\RA\5S?Sj5r'\RA\5S@Sj5r(\ "S5r)\ \\ \*\+\ 4\,\ S4\4r-\SASj5r.\.RA\5\.RA\5SBSj55r/\.RA\5SCSj5r0\.RA\5SDSj5r1\.RA\5SESj5r2\.RA\5SFSj5r3\.RA\5SGSj5r4\.RA\5SHSj5r5\.RA\5SISj5r6\.RA\5SJSj5r7\SKSj5r8\8RA\5\8RA\5SBSj55r9\8RA\5SLSj5r:\8RA\5SMS j5r;\8RA\5SNS!j5r<\8RA\5SOS"j5r=\8RA\5SGS#j5r>\8RA\5SPS$j5r?\8RA\5SQS%j5r@\8RA\5SRS&j5rA\SSS'j5rB\BRA\5STS(j5rC\BRA\5\BRA\5\BRA\5SUS)j555rD\BRA\5SVS*j5rE\BRA\5SWS+j5rF\BRA\5SXS,j5rG\BRA\5SYS-j5rH\BRA\5SZS.j5rI\BRA\5S[S/j5rJ\S\S0j5rK\KRA\5\KRA\5\KRA\5\KRA\5S15555rL\KRA\5S]S2j5rM\KRA\5S^S3j5rN\KRA\5S45rO\KRA\5S_S5j5rP\KRA\5S`S6j5rQ\KRA\5SaS7j5rRg)bzImplementation of utility functions that can be applied to spaces. These functions mostly take care of flattening and unflattening elements of spaces to facilitate their usage in learning code. ) annotationsN)reducesingledispatch)AnyTypeVarUnion)NDArray) BoxDictDiscreteGraph GraphInstance MultiBinary MultiDiscreteOneOfSequenceSpaceTextTuplecZURSLa[US35e[SUS35e)a8Return the number of dimensions a flattened equivalent of this space would have. Args: space: The space to return the number of dimensions of the flattened spaces Returns: The number of dimensions for the flattened spaces Raises: NotImplementedError: if the space is not defined in :mod:`gym.spaces`. ValueError: if the space cannot be flattened into a :class:`gymnasium.spaces.Box` Example: >>> from gymnasium.spaces import Dict, Discrete >>> space = Dict({"position": Discrete(2), "velocity": Discrete(3)}) >>> flatdim(space) 5 Fd cannot be flattened to a numpy array, probably because it contains a `Graph` or `Sequence` subspaceUnknown space: ``)is_np_flattenable ValueErrorNotImplementedErrorspaces P/home/james-whalen/.local/lib/python3.13/site-packages/gymnasium/spaces/utils.pyflatdimr !sA( %'gy z    0q9 ::cL[[RURS5$)N)ropmulshapers r_flatdim_box_multibinaryr'=s "&&%++q ))r!c,[UR5$N)intnrs r_flatdim_discreter,Cs uww<r!cT[[R"UR55$r))r*npsumnvecrs r_flatdim_multidiscreter1Hs rvvejj! ""r!cxUR(a[SUR55$[US35e)Nc38# UHn[U5v M g7fr)r .0ss r !_flatdim_tuple..P4|!71::|r)rr/spacesrrs r_flatdim_tupler=Ms8 4u||444  'uv r!cUR(a*[SURR555$[ US35e)Nc38# UHn[U5v M g7fr)r4r5s rr8 _flatdim_dict..Ys='.mr:r;)maxr<rs r_flatdim_oneofrLks s4u||44 44r!T.c [SUS35e)a>Flatten a data point from a space. This is useful when e.g. points from spaces must be passed to a neural network, which only understands flat arrays of floats. Args: space: The space that ``x`` is flattened by x: The value to flatten Returns: The flattened datapoint - For :class:`gymnasium.spaces.Box` and :class:`gymnasium.spaces.MultiBinary`, this is a flattened array - For :class:`gymnasium.spaces.Discrete` and :class:`gymnasium.spaces.MultiDiscrete`, this is a flattened one-hot array of the sample - For :class:`gymnasium.spaces.Tuple` and :class:`gymnasium.spaces.Dict`, this is a concatenated array the subspaces (does not support graph subspaces) - For graph spaces, returns :class:`GraphInstance` where: - :attr:`GraphInstance.nodes` are n x k arrays - :attr:`GraphInstance.edges` are either: - m x k arrays - None - :attr:`GraphInstance.edge_links` are either: - m x 2 arrays - None Raises: NotImplementedError: If the space is not defined in :mod:`gymnasium.spaces`. Example: >>> from gymnasium.spaces import Box, Discrete, Tuple >>> space = Box(0, 1, shape=(3, 5)) >>> flatten(space, space.sample()).shape (15,) >>> space = Discrete(4) >>> flatten(space, 2) array([0, 0, 1, 0]) >>> space = Tuple((Box(0, 1, shape=(2,)), Box(0, 1, shape=(3,)), Discrete(3))) >>> example = ((.5, .25), (1., 0., .2), 1) >>> flatten(space, example) array([0.5 , 0.25, 1. , 0. , 0.2 , 0. , 1. , 0. ]) rrrrxs rflattenrRtsT  0q9 ::r!cZ[R"XRS9R5$Ndtype)r.asarrayrVrRrPs r_flatten_box_multibinaryrXs  ::a{{ + 3 3 55r!cz[R"URURS9nSX!UR- 'U$)NrUr#)r.zerosr+rVstart)rrQonehots r_flatten_discreter]s/ XXeggU[[ 1FFu{{? Mr!cl[R"URRS-4[RS9n[R "URR 55USS&[R"US4URS9nSX2SSXR- R 5-'U$)Nr#rU) r.rZr0sizeint32cumsumrRrVr[)rrQoffsetsr\s r_flatten_multidiscreterdshh !+-RXX>G))EJJ..01GABK XXwr{nEKK 8F9:F3B<1{{?335 56 Mr!c 0UR(a[[R"[XR5VVs/sH$up#[R "[ X255PM& snn5$[S[XR555$s snnf)Nc3<# UHup[X!5v M g7fr))rR)r6x_partr7s rr8!_flatten_tuple..sJ5I ##5I)rr. concatenatezipr<arrayrRtuple)rrQrgr7s r_flatten_tuplernsk ~~;>q,,;O P;OifRXXga( );O P   JSLL5IJ JJ Qs+B c zUR(ac[R"URR 5VVs/sH'up#[R "[ X1U55PM) snn5$URR 5VVs0sHup#U[ X1U5_M snn$s snnfs snnfr))rr.rjr<itemsrlrR)rrQkeyr7s r _flatten_dictrrs ~~8= 8J8J8L M8LfcRXXga3( )8L M  38,,2D2D2F G2FCcF# #2F GG N Gs .B1 B7cSSjnU"URUR5nUceU"URUR5n[ X4UR 5$)zWe're not using ``.unflatten()`` for :class:`Box` and :class:`Discrete` because a graph is not a homogeneous space, see `.flatten` docstring.cSnUbUb[U[5(a!URURSS5nU$[U[5(de[ R "URSURUR- 4URS9nSU[ R"URS5XR- 4'U$)Nrr_rUr#) isinstancer reshaper&r r.rZr+r[rVarange)unflatten_space unflatten_xrets r_graph_unflatten(_flatten_graph.._graph_unflattens  &;+B/3//!))+*;*;A*>C "/8<<<<hh &&q)?+<+<?T?T+TU)// IIk//23[CXCX5XX r!)rxzDiscrete | Box | NoneryNDArray[Any] | Nonereturnr} node_spacenodes edge_spaceedgesr edge_linksrrQr{rrs r_flatten_graphrsl.( & U--qww 7E    U--qww 7E q|| 44r!c[R"UR4[UR5[R S9n[ U5Hup4URU5X#'M U$)N)r& fill_valuerV)r.fullrFlen character_setra enumeratecharacter_index)rrQarrivals r _flatten_textrsX ''!c%2E2E.Fbhh CA,&&s+ Jr!c^TR(a[RRR TR U5nUVs/sHn[ TRU5PM nn[TR5n[RRRU[U5S9n[RRRXTU5$[U4SjU55$s snf)N)r+c3P># UHn[TRU5v M g7fr))rR feature_spacer6itemrs rr8$_flatten_sequence..s!FADWU00$77A#&) stackgymvectorutilsiteratestacked_feature_spacerRr flatten_spacecreate_empty_arrayrrjrm)rrQ samples_iterssampleflattened_samplesflattened_spaceouts` r_flatten_sequencers {{ ((001L1LaP ?L ?LVGE'' 0}  ((;(;<jj11 s#452 zz++OPSTTFAFFF s C2c8Uup#URUn[XC5n[U5S- nURU:aF[R "XeR- USUR S9n[R"XW/5n[R"U/U/5$)Nr#rrU)r<rRr r`r.rrVrj)rrQidxr sub_space flat_sample max_flatdimpaddings r_flatten_oneofrsKC S!I),K%.1$K+%'' ** *KN+BSBS nnk%;< >>C5+. //r!c [SUS35e)aUnflatten a data point from a space. This reverses the transformation applied by :func:`flatten`. You must ensure that the ``space`` argument is the same as for the :func:`flatten` call. Args: space: The space used to unflatten ``x`` x: The array to unflatten Returns: A point with a structure that matches the space. Raises: NotImplementedError: if the space is not defined in :mod:`gymnasium.spaces`. rrrOrPs r unflattenrs"  0q9 ::r!cp[R"XRS9RUR5$rT)r.rWrVrvr&rPs r_unflatten_box_multibinaryr*s& ::a{{ + 3 3EKK @@r!c[R"U5n[US5S:Xa[USUS35eURUSS-$)NrzK is not a valid one-hot encoded vector and can not be unflattened to space @. Not all valid samples in a flattened space can be unflattened.)r.nonzerorrr[)rrQrs r_unflatten_discreter2s`jjmG 71:!c\]b\cdM M   ;;A &&r!c[R"URRS-4URS9n[R "URR 55USS&[R"U5un[U5S:Xa[USUS35e[R"X2SS- URS9RUR5UR-$)Nr#rUrzW is not a concatenation of one-hot encoded vectors and can not be unflattened to space rr_)r.rZr0r`rVrbrRrrrrWrvr&r[)rrQrcindicess r_unflatten_multidiscreter=shh !+-U[[AG))EJJ..01GABKAJW 7|qchinhopM M  7Sb\)=EEekkR ++ r!chUR(a[U[R5(dUS[ U535e[R "UR Vs/sHn[U5PM sn[RS9n[R"U[R"USS55n[S[X@R 555$[U[5(dUS[ U535e[S[XR 555$s snf)NzZ is numpy-flattenable. Thus, you should only unflatten numpy arrays for this space. Got a rUr_c3<# UHup[X!5v M g7fr)rr6 flattenedr7s rr8#_unflatten_tuple..Ys! A  a # # ArizX is not numpy-flattenable. Thus, you should only unflatten tuples for this space. Got a c3<# UHup[X!5v M g7fr)rrs rr8r`sR=Q\Y1((=Qri) rrur.ndarraytyperWr<r int_splitrbrmrk)rrQr7dimslist_flatteneds r_unflatten_tuplerOs  rzz   yWnostuovnw x y zzu||<|!71:|<<;M;M;O'P 'P# 8C 1( ('P   4  w lmqrsmtluvw 5:LL4F4F4H I4H&#C1f% %4H IIF  JsE<E#EcSnU"URUR5nU"URUR5n[ X4UR 5$)zWe're not using `.unflatten() for :class:`Box` and :class:`Discrete` because a graph is not a homogeneous space. The size of the outcome is actually not fixed, but determined based on the number of nodes and edges in the graph. c SnUb}Ubz[U[5(aUR"S/URQ76nU$[U[5(a1[ R "[ R"U55SSS24nU$)Nr_)rur rvr&r r.rWr)rxryresults rr{*_unflatten_graph.._graph_unflatten{su  &;+B/3//$,,RH/2G2GH OX66BJJ{$;# UHn[TRU5v M g7fr))rrrs rr8&_unflatten_sequence..s!HadYu22D99ar) rrrrrrrrrrrjrm)rrQr flatten_itersrunflattened_samplesrs` r_unflatten_sequencers {{'(;(;< ((00D AN ANvIe))6 2  jj11   %8!9 zz++   !4  HaHHH s C=c[R"US5nURUn[U5nUSSU-nU[ X554$)Nrr#)r.int64r<r r)rrQrr original_sizetrimmed_samples r_unflatten_oneofrsL ((1Q4.C S!II&Mq1},-N  )4 44r!c [SUS35e)a' Flatten a space into a space that is as flat as possible. This function will attempt to flatten ``space`` into a single :class:`gymnasium.spaces.Box` space. However, this might not be possible when ``space`` is an instance of :class:`gymnasium.spaces.Graph`, :class:`gymnasium.spaces.Sequence` or a compound space that contains a :class:`gymnasium.spaces.Graph` or :class:`gymnasium.spaces.Sequence` space. This is equivalent to :func:`flatten`, but operates on the space itself. The result for non-graph spaces is always a :class:`gymnasium.spaces.Box` with flat boundaries. While the result for graph spaces is always a :class:`gymnasium.spaces.Graph` with :attr:`Graph.node_space` being a ``Box`` with flat boundaries and :attr:`Graph.edge_space` being a ``Box`` with flat boundaries or ``None``. The box has exactly :func:`flatdim` dimensions. Flattening a sample of the original space has the same effect as taking a sample of the flattened space. However, sampling from the flattened space is not necessarily reversible. For example, sampling from a flattened Discrete space is the same as sampling from a Box, and the results may not be integers or one-hot encodings. This may result in errors or non-uniform sampling. Args: space: The space to flatten Returns: A flattened Box Raises: NotImplementedError: if the space is not defined in :mod:`gymnasium.spaces`. Example - Flatten spaces.Box: >>> from gymnasium.spaces import Box >>> box = Box(0.0, 1.0, shape=(3, 4, 5)) >>> box Box(0.0, 1.0, (3, 4, 5), float32) >>> flatten_space(box) Box(0.0, 1.0, (60,), float32) >>> flatten(box, box.sample()) in flatten_space(box) True Example - Flatten spaces.Discrete: >>> from gymnasium.spaces import Discrete >>> discrete = Discrete(5) >>> flatten_space(discrete) Box(0, 1, (5,), int64) >>> flatten(discrete, discrete.sample()) in flatten_space(discrete) True Example - Flatten spaces.Dict: >>> from gymnasium.spaces import Dict, Discrete, Box >>> space = Dict({"position": Discrete(2), "velocity": Box(0, 1, shape=(2, 2))}) >>> flatten_space(space) Box(0.0, 1.0, (6,), float64) >>> flatten(space, space.sample()) in flatten_space(space) True Example - Flatten spaces.Graph: >>> from gymnasium.spaces import Graph, Discrete, Box >>> space = Graph(node_space=Box(low=-100, high=100, shape=(3, 4)), edge_space=Discrete(5)) >>> flatten_space(space) Graph(Box(-100.0, 100.0, (12,), float32), Box(0, 1, (5,), int64)) >>> flatten(space, space.sample()) in flatten_space(space) True rrrOrs rrrs~  0q9 ::r!c[URR5URR5URS9$rT)r lowrRhighrVrs r_flatten_space_boxrs/ uyy  "EJJ$6$6$8 LLr!cB[SS[U54URS9$)Nrr#rrr&rV)r r rVrs r_flatten_space_binaryrs  11WU^$5U[[ IIr!c UR(aURVs/sHn[U5PM nn[[R "UVs/sHoR PM sn5[R "UVs/sHoRPM sn5[R"UVs/sHoRPM sn6S9$[URVs/sHn[U5PM snS9$s snfs snfs snfs snfs snfN)rrrV)r<) rr<rr r.rjrr result_typerVr)rr7 space_lists r_flatten_space_tuplers 05 = 1mA& =z:z!z:; <A <=..J"?Jq77J"?@  5<<@: <"?@sC6C; ?D.DD c bUR(aURR5Vs/sHn[U5PM nn[ [ R "UVs/sHoRPM sn5[ R "UVs/sHoRPM sn5[ R"UVs/sHoRPM sn6S9$[URR5VVs0sHup0U[U5_M snnS9$s snfs snfs snfs snfs snnfr) rr<rArr r.rjrrrrVr rp)rr7rrqs r_flatten_space_dictrs 05 0C0C0EF0E1mA&0E Fz:z!z:; <A <=..J"?Jq77J"?@  ./s7,Qgajj,r;r#rrVr)rr<rKr.rlminrrrrjrrhasattrrVr ) r num_subspacesrr7lowshighs overall_low overall_highrrrVs r_flatten_space_oneofr,sK %M7%,,77!;K 885<<H>MA-. a0VW XD NNellRlga>QWQWWlR SE 3+u EEIJSs3G +3GG-Gc[U[5(a [U[5(a [S5e[5e)a`Returns if two spaces share a common dtype and shape (plus any critical variables). This function is primarily used to check for compatibility of different spaces in a vector environment. Args: space_1: A Gymnasium space space_2: A Gymnasium space Returns: If the two spaces share a common dtype and shape (plus any critical variables). zJ`check_dtype_shape_equivalence` doesn't support Generic Gymnasium Spaces, )rurr TypeErrorspace_1space_2s ris_space_dtype_shape_equivr>s7'5!!j%&@&@! X  kr!c[U5[U5L=(a9 URUR:H=(a URUR:H$r))rr&rVrs r'_is_space_fundamental_dtype_shape_equivrSsC W g& + MMW]] * + MMW]] * r!c[U[5=(a9 URUR:H=(a URUR:H$r))rurrFrrs r _is_space_text_dtype_shape_equivr`sE 7D! ;   '"4"4 4 ;  ! !W%:%: :r!c^^[T[5=(aL TR5TR5:H=(a$ [UU4SjTR555$)Nc3H># UHn[TUTU5v M g7fr)r)r6rqrrs rr83_is_space_dict_dtype_shape_equiv..ns* % 'ws|WS\ B B%")rur keysallrs``r _is_space_dict_dtype_shape_equivrisM 7D! LLNglln ,  ||~  r!c^^[T[5=(a( [UU4Sj[[ T5555$)Nc3H># UHn[TUTU5v M g7fr)r r6rrrs rr84_is_space_tuple_dtype_shape_equiv..ws(.DWq"71:wqz::DWr )rurrrangerrs``r!_is_space_tuple_dtype_shape_equivrus4 gu % #.DI#g,DW.+r!cf[U[5=(a [URUR5=(at URSL=(a URSL=(dJ URSL=(a5 URSL=(a [URUR5$r))rur rrrrs r!_is_space_graph_dtype_shape_equivr|s 7E" &w'9'97;M;M N   4 ' FG,>,>$,F ""$.W&&d2W.w/A/A7CUCUV r!c^^[T[5=(aF [T5[T5:H=(a( [UU4Sj[ [T5555$)Nc3H># UHn[TUTU5v M g7fr)r rs rr84_is_space_oneof_dtype_shape_equiv..s* ( 'wqz71: > >(r )rurrrrrs``r!_is_space_oneof_dtype_shape_equivrsL 7E" LCL (  3w<(  r!c[U[5=(a? URURL=(a [URUR5$r))rurrrrrs r$_is_space_sequence_dtype_shape_equivrsE 7H% U MMW]] * U &w'<'S>S Tr!)r Space[Any]r~r*)rBox | MultiBinaryr~r*)rr r~r*)rrr~r*)rrr~r*)rr r~r*)rr )rrr~r*)rrr~r*)rSpace[T]rQrMr~FlatType)rr rQ NDArray[Any]r~r#)rr rQnp.int64r~NDArray[np.int64])rrrQr%r~r%)rrrQtuple[Any, ...]r~ztuple[Any, ...] | NDArray[Any])rr rQdict[str, Any]r~zdict[str, Any] | NDArray[Any])rr rQrr~r)rrrQstrr~NDArray[np.int32])rrrQtuple[Any, ...] | Anyr~r*)rrrQtuple[int, Any]r~r#)rr!rQr"r~rM)rr rQr%r~r$)rrrQNDArray[np.integer[Any]]r~r,)rrrQzNDArray[Any] | tuple[Any, ...]r~r&)rr rQzNDArray[Any] | dict[str, Any]r~r')rrrQr)r~r()rrrQr&r~r*)rrrQr#r~r+)rrr~z%Box | Dict | Sequence | Tuple | Graph)rr r~r )rz&Discrete | MultiBinary | MultiDiscreter~r )rrr~z Box | Tuple)rr r~z Box | Dict)rr r~r )rrr~r )rrr~r)rrr~r )rrrrr~bool)rr)rr )rr )rr)rr)S__doc__ __future__roperatorr$ functoolsrrtypingrrrnumpyr. numpy.typingr gymnasiumrgymnasium.spacesr r r r rrrrrrrrr registerr'r,r1r=rBrDrGrLrMrr(rmr"rRrXr]rdrnrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr!rr9s #,&&      ;;6 #+** ( - #!# % $ %  $ %55 CL tCH~uS#X M N););X #+66 (  -  .! %KK $HH %55: $ (G G-GGG" % 0 0;;& C K A A!-AA!A  H'' M" 5#" ES S3SSS& D J J E55, D  HII" E55>;>;BMM! $ &J'%"JBB   !K"KFF"($$S)$$X.$$]3$$[124/*$$T*+$$T*+$$U+, $$U+ , $$U+,$$X./r!