hHf SrSSKJr SSKrSSKJrJrJr SSKJ r SSK J r SSKJ r SSK rSSKJr SS KJrJrJrJrJrJrJrJrJrJrJrJr SS KJr /S Qr \ S0S1S jj5r!\!RE\5S0S2Sjj5r#\!RE\5S0S3Sjj5r$\!RE\5S0S4Sjj5r%\!RE\5S0S5Sjj5r&\!RE\5S0S6Sjj5r'\!RE\5S0S7Sjj5r(\!RE\5\!RE\5\!RE\5\!RE\5\!RE\5S0S8Sjj55555r)\ S9Sj5r*\*RE\5S:Sj5r+\*RE\5S;Sj5r,\*RE\5SSj5r/\*RE\5S?Sj5r0\*RE\5\*RE\5\*RE\5\*RE\5S@Sj5555r1\ SASj5r2\2RE\5SBSj5r3\2RE\5\2RE\5\2RE\5SCSj555r4\2RE\5SDS j5r5\2RE\5SES!j5r6\ SFS"j5r7\7RE\5\7RE\5\7RE\5\7RE\5SGS#j5555r8\7RE\5SHS$j5r9\7RE\5SIS%j5r:\7RE\5\7RE\5\7RE\5\7RE\5\7RE\5SJS&j55555r;\ S \Rx4SKS'jj5r=\=RE\5\=RE\5\=RE\5\=RE\5S \Rx4SLS(jj5555r>\=RE\5S \Rx4SMS)jj5r?\=RE\5S \Rx4SNS*jj5r@\=RE\5S \Rx4SOS+jj5rA\=RE\5S \Rx4SPS,jj5rB\=RE\5S \Rx4SQS-jj5rC\=RE\5S \Rx4SRS.jj5rD\=RE\5S \Rx4S/j5rEg)SaTSpace-based utility functions for vector environments. - ``batch_space``: Create a (batched) space containing multiple copies of a single space. - ``batch_differing_spaces``: Create a (batched) space containing copies of different compatible spaces (share a common dtype and shape) - ``concatenate``: Concatenate multiple samples from (unbatched) space into a single object. - ``Iterate``: Iterate over the elements of a (batched) space and items. - ``create_empty_array``: Create an empty (possibly nested) (normally numpy-based) array, used in conjunction with ``concatenate(..., out=array)`` ) annotationsN)CallableIterableIteratordeepcopy)singledispatch)Any)CustomSpaceError) BoxDictDiscreteGraph GraphInstance MultiBinary MultiDiscreteOneOfSequenceSpaceTextTuple)T_cov) batch_spacebatch_differing_spacesiterate concatenatecreate_empty_arrayc6[S[U5SU35e)aBatch spaces of size `n` optimized for neural networks. Args: space: Space (e.g. the observation space for a single environment in the vectorized environment). n: Number of spaces to batch by (e.g. the number of environments in a vectorized environment). Returns: Batched space of size `n`. Raises: ValueError: Cannot batch spaces that does not have a registered function. Example: >>> from gymnasium.spaces import Box, Dict >>> import numpy as np >>> space = Dict({ ... 'position': Box(low=0, high=1, shape=(3,), dtype=np.float32), ... 'velocity': Box(low=0, high=1, shape=(2,), dtype=np.float32) ... }) >>> batch_space(space, n=5) Dict('position': Box(0.0, 1.0, (5, 3), float32), 'velocity': Box(0.0, 1.0, (5, 2), float32)) zMThe space provided to `batch_space` is not a gymnasium Space instance, type: ,  TypeErrortypespacens \/home/james-whalen/.local/lib/python3.13/site-packages/gymnasium/vector/utils/space_utils.pyrr/s,2  WX\]bXcWddfglfmn c"[U/S/URR--5n[R"URU5[R"UR U5pC[ X4UR[UR5S9$Nrlowhighdtypeseed) tupler,ndimnptiler-r r.r np_randomr%r&repeatsr,r-s r'_batch_space_boxr7MscQC1# ../G 7+RWWUZZ-I 38EOO;T UUr(c [[R"U4URURS9UR[ UR 5[R"U4URURS9S9$)Nr.)r.r/start)rr2fullr&r.rr4r:r$s r'_batch_space_discreter<TsV  eggU[[1kk eoo &ggqdEKKu{{;  r(c2[U/S/URR--5n[R"UR U5nU[R"URU5-S- n[ UUUR[UR5S9$r*) r0nvecr1r2r3r:r r.rr4r5s r'_batch_space_multidiscreter?^szQC1# //0G ''%++w 'C W- - 1D   kk eoo &  r(c r[SSU4UR-UR[UR5S9$)Nrrr,r-shaper.r/)r rBr.rr4r$s r'_batch_space_multibinaryrCks6  dU[[ kk eoo &  r(cx^[[U4SjUR55[UR5S9$)Nc38># UHn[UTS9v M g7f)r&N)r).0subspacer&s r' %_batch_space_tuple..ys FXk(a(sr/)rr0spacesrr4r$s `r'_batch_space_tuplerMvs.  F FF eoo & r(c [UR5VVs0sHup#U[X1S9_M snn[UR5S9$s snnf)NrFrK)r itemsrrr4)r%r&keyrHs r'_batch_space_dictrQ~sB >CkkmLm]Sk(( (mL eoo & LsA c ^[[U4Sj[U555[TR5S9n[TR5n[ [ [URSSU555nURU5 U$)Nc3:># UHn[T5v M g7fNrrG_r%s r'rI&_batch_space_custom..s 0x!huooxrKrgחA) rr0rangerr4listmapintintegersr/)r%r& batched_space space_rng new_seedss` r'_batch_space_customrasp 0uQx 00x7PM)ISi00C;<=Iy! r(ct^[T5S:dS5e[U4SjT55(d$STVs/sHn[U5PM sn35e[TS5[R;dS[R35e[R [TS55"T5$s snf)aBatch a Sequence of spaces where subspaces to contain minor differences. Args: spaces: A sequence of Spaces with minor differences (the same space type but different parameters). Returns: A batched space Example: >>> from gymnasium.spaces import Discrete >>> spaces = [Discrete(3), Discrete(5), Discrete(4), Discrete(8)] >>> batch_differing_spaces(spaces) MultiDiscrete([3 5 4 8]) rz"Expects a non-empty list of spacesc3T># UHn[U[TS55v M g7frN) isinstancer#rGr%rLs r'rI)batch_differing_spaces..s&8>u 5$vay/**s%(z7Expects all spaces to be the same shape, actual types: zTRequires the Space type to have a registered `batch_differing_space`, current list: )lenallr#rregistrydispatchrLr%s` r'rrs v;?@@@? 8>  e @[aAb[aRW$u+[aAb@cde  VAY1:::@ ]^t^}^}]~@: " * *4q ? ;F CC BcsB5c ^[U4SjT55(d$STVs/sHoRPM sn35e[U4SjT55(d.STVs/sHoRRPM sn35e[U4SjT55(d.STVs/sHoRRPM sn35e[ [ R"TVs/sHoRPM sn5[ R"TVs/sHoRPM sn5TSR[TSR5S9$s snfs snfs snfs snfs snf) Nc3\># UH!nTSRUR:Hv M# g7frdr9rfs r'rI._batch_differing_spaces_box..%4:5q 5;;&F),*Expected all dtypes to be equal, actually c3># UH5nTSRRURR:Hv M7 g7frd)r,rBrfs r'rIros/# UH5nTSRRURR:Hv M7 g7frd)r-rBrfs r'rIro1>DUq  0 00frtz2Expected all Box.high shape to be equal, actually rr+) rir.r,rBr-r r2arrayrr4rls` r'_batch_differing_spaces_boxrxsn 4:  X 3f4UfU[[f4U3VWX  D  e ;[ar:r/)rr2rwr&r:rr4rls r' _batch_differing_spaces_discreterzsa  XXF3F5wwF3 4hh8 89 fQi)) * 38s A> Bc ^[U4SjT55(d$STVs/sHoRPM sn35e[U4SjT55(d.STVs/sHoRRPM sn35e[U4SjT55(d.STVs/sHoRRPM sn35e[ [ R"TVs/sHoRPM sn5[ R"TVs/sHoRUR-PM sn5S- TSR[TSR5S 9$s snfs snfs snfs snfs snf) Nc3\># UH!nTSRUR:Hv M# g7frdr9rfs r'rI9_batch_differing_spaces_multi_discrete..rprqrrc3># UH5nTSRRURR:Hv M7 g7frd)r>rBrfs r'rIr}rvrtz/Expects all MultiDiscrete.nvec shape, actually c3># UH5nTSRRURR:Hv M7 g7frd)r:rBrfs r'rIr}s1@Fuq !2!22rtz0Expects all MultiDiscrete.start shape, actually rrr+) rir.r>rBr:r r2rwrr4rls` r'&_batch_differing_spaces_multi_discreters} 4:  X 3f4UfU[[f4U3VWX  >D  b 8X^9_X^u**:J:JX^9_8`ab  @F  d 9Z`:aZ`QV;;;L;LZ`:a9bcd   HHv6vekkv6 7 XXVDVE{{UZZ/VD E IQioo fQi)) *  5V:`;b7DsE+ E0(E5)E: "E?c ^[U4SjT55(de[SS[T54TSR-TSR[ TSR 5S9$)Nc3\># UH!nTSRUR:Hv M# g7frd)rBrfs r'rI7_batch_differing_spaces_multi_binary..s"B6%vay%++-6rqrrrA)rir rhrBr.rr4)rLs`r'$_batch_differing_spaces_multi_binaryrs` B6B B BB B  6{nvay.Qioo fQi)) *  r(c [[S[UVs/sHoRPM sn655[ USR 5S9$s snf)Nc38# UHn[U5v M g7frT)r)rG subspacess r'rI0_batch_differing_spaces_tuple..s E  #9 - -EsrrK)rr0ziprLrr4rls r'_batch_differing_spaces_tuplersT    V"DVE<# UH)nTSR5UR5:Hv M+ g7frd)keysrfs r'rI/_batch_differing_spaces_dict..s'DVEvay~~5::</Vs14rrK)rir rrrr4)rLrPr%s` r'_batch_differing_spaces_dictrs DVD D DD D ay~~' ' '(Hs(HI I' fQi)) *  (H sB A? B ?B c[UVs/sHn[U5PM sn[USR5S9$s snf)NrrK)rrr4rls r'_batch_spaces_undefinedrs; &,-fU%f-HVAY=P=P4Q -s;c[U[5(a$[S[U5S[U5S35e[ S[U5SU35e)aIterate over the elements of a (batched) space. Args: space: (batched) space (e.g. `action_space` or `observation_space` from vectorized environment). items: Batched samples to be iterated over (e.g. sample from the space). Example: >>> from gymnasium.spaces import Box, Dict >>> import numpy as np >>> space = Dict({ ... 'position': Box(low=0, high=1, shape=(2, 3), seed=42, dtype=np.float32), ... 'velocity': Box(low=0, high=1, shape=(2, 2), seed=42, dtype=np.float32)}) >>> items = space.sample() >>> it = iterate(space, items) >>> next(it) {'position': array([0.77395606, 0.43887845, 0.85859793], dtype=float32), 'velocity': array([0.77395606, 0.43887845], dtype=float32)} >>> next(it) {'position': array([0.697368 , 0.09417735, 0.97562236], dtype=float32), 'velocity': array([0.85859793, 0.697368 ], dtype=float32)} >>> next(it) Traceback (most recent call last): ... StopIteration zSpace of type `z;` doesn't have an registered `iterate` function. Register `z` for `iterate` to support it.zIThe space provided to `iterate` is not a gymnasium Space instance, type: r )rerr r#r"r%rOs r'rrso2%d5k]*efjkpfqersQ R  WX\]bXcWddfglfm n  r(c[S5e)Nz2Unable to iterate over a space of type `Discrete`.)r"rs r'_iterate_discreter5s H IIr(c\[U5$![an[SU35UeSnAff=f)Nz/Unable to iterate over the following elements: )iterr")r%rOes r' _iterate_baser:s;E{ =eW E  s +&+c [SU55(a2[[U5VVs/sHup#[X1U5PM snn6$[ U5$s snnf![ a[nUVs/sH-n[ U5[R;dM"[ U5PM/ Os snfnn[SUSUSUS35UeSnAff=f)Nc3Z# UH!n[U5[R;v M# g7frT)r#rrj)rGrHs r'rI!_iterate_tuple..Is De(4>W-- -es)+zCould not iterate through z1 as no custom iterate function is registered for z/ and `iter(items)` raised the following error: .) rir enumeraterr Exceptionr#rjr )r%rOirHrunregistered_spacess r'_iterate_tuplerFs De DDDIeDTUDT[QWXQx0DTUVV E{V " !H~W%5%55 DN!  (/`at`uvefgehhi j   s/A A C&B<*!BBB<<Cc ## [URR5VVs/sHup#U[X1U54PM snn6upE[U6H%n[XF5VVs0sHup'X'_M snnv M' gs snnfs snnf7frT)rrLrOr)r%rOrPrHrvaluesitemvalues r' _iterate_dictrYs"'!3!3!5 !5 '(#J/ 0!5 LD V ,/O>> from gymnasium.spaces import Box >>> import numpy as np >>> space = Box(low=0, high=1, shape=(3,), seed=42, dtype=np.float32) >>> out = np.zeros((2, 3), dtype=np.float32) >>> items = [space.sample() for _ in range(2)] >>> concatenate(space, items, out) array([[0.77395606, 0.43887845, 0.85859793], [0.697368 , 0.09417735, 0.97562236]], dtype=float32) zMThe space provided to `concatenate` is not a gymnasium Space instance, type: r r!r%rOouts r'rres,6  WX\]bXcWddfglfmn r(c.[R"USUS9$)Nr)axisr)r2stackrs r'_concatenate_basers 88Es ++r(cX^^[UU4Sj[UR555$)Nc 3x># UH*up[UTVs/sHo3UPM snTU5v M, gs snf7frT)r)rGrrHrrOrs r'rI%_concatenate_tuple..s@4MQ H5954Aw593q6BB4:s :5 :)r0rrLrs ``r'_concatenate_tuplers( &u||4 r(cUR5VVVs0sH'up4U[XAVs/sHoUUPM snX#5_M) snnn$s snfs snnnfrT)rOr)r%rOrrPrHrs r'_concatenate_dictrsU #[[] *MC [%#@%$I%#@#( KK* #@ sA AA A c[U5$rTr0rs r'_concatenate_customrs <r(c6[S[U5SU35e)aCreate an empty (possibly nested and normally numpy-based) array, used in conjunction with ``concatenate(..., out=array)``. In most cases, the array will be contained within the batched space, however, this is not guaranteed. Args: space: Observation space of a single environment in the vectorized environment. n: Number of environments in the vectorized environment. If ``None``, creates an empty sample from ``space``. fn: Function to apply when creating the empty numpy array. Examples of such functions are ``np.empty`` or ``np.zeros``. Returns: The output object. This object is a (possibly nested) numpy array. Raises: ValueError: Space is not a valid :class:`gymnasium.Space` instance Example: >>> from gymnasium.spaces import Box, Dict >>> import numpy as np >>> space = Dict({ ... 'position': Box(low=0, high=1, shape=(3,), dtype=np.float32), ... 'velocity': Box(low=0, high=1, shape=(2,), dtype=np.float32)}) >>> create_empty_array(space, n=2, fn=np.zeros) {'position': array([[0., 0., 0.], [0., 0., 0.]], dtype=float32), 'velocity': array([[0., 0.], [0., 0.]], dtype=float32)} zTThe space provided to `create_empty_array` is not a gymnasium Space instance, type: r r!r%r&fns r'rrs,<  ^_cdi_j^kkmnsmtu r(c@U"U4UR-URS9$)Nr9)rBr.rs r'_create_empty_array_multirs qdU[[  44r(cF^^[UU4SjUR55$)Nc3:># UHn[UTTS9v M g7f)r&rN)r)rGrHrr&s r'rI,_create_empty_array_tuple..sW,h#Hb9,rX)r0rLrs ``r'_create_empty_array_tuplers W%,,W WWr(c jUR5VVs0sHup4U[XAUS9_M snn$s snnf)Nr)rOr)r%r&rrPrHs r'_create_empty_array_dictrs<LQ;;= KX-# " 55=  s/c^^TRb[UU4Sj[U555$[UU4Sj[U555$)Nc 3 ># UHn[T"STRR-TRRS9T"STRR-TRRS9T"S[ R S9S9v M g7f)rr9)rnodesedges edge_linksN)r node_spacerBr. edge_spacer2int64rGrVrr%s r'rI,_create_empty_array_graph..s}   0 0 6 66e>N>N>T>TU 0 0 6 66e>N>N>T>TUfBHH5  sB Bc3># UH@n[T"STRR-TRRS9SSS9v MB g7f)rr9Nr)rrrBr.rs r'rIrsN   0 0 6 66e>N>N>T>TU  sAA )rr0rYrs` `r'_create_empty_array_graphrsS # 1X     1X    r(c@^[U4Sj[U555$)Nc3\># UH!nTRSTR-v M# g7frd) characters min_lengthrUs r'rI+_create_empty_array_text..s'JA!!!$u'7'77rqr0rYrs` r'_create_empty_array_textrs JqJ JJr(c^^TR(a[UU4Sj[U555$[S[U555$)Nc3N># UHn[TRSTS9v M g7f)rrN)r feature_spacers r'rI/_create_empty_array_sequence.. s$ IQA u22aB ?s"%c36# UHn[5v M g7frTrrGrVs r'rIr s/hUWWh)rr0rYrs` `r'_create_empty_array_sequencersA {{ INq   /eAh///r(c8[S[U555$)Nc36# UHn[5v M g7frTrrs r'rI,_create_empty_array_oneof..s+(Q(rrrs r'_create_empty_array_oneofrs +%(+ ++r(cgrTrs r'_create_empty_array_customrs r(r)r% Space[Any]r&r\returnr)r%r r&r\)r%rr&r\)r%rr&r\)r%rr&r\)r%rr&r\)r%r r&r\)r%zGraph | Text | Sequence | OneOfr&r\)rLztyping.Sequence[Space]rr)rLz list[Box])rLzlist[Discrete])rLzlist[MultiDiscrete])rLzlist[MultiBinary])rLz list[Tuple])rLz list[Dict])rLz%list[Graph | Text | Sequence | OneOf])r%z Space[T_cov]rOrrr)r%rrOr)r%z!Box | MultiDiscrete | MultiBinaryrO np.ndarray)r%rrOtuple[Any, ...])r%r rOdict[str, Any])r%rrOrr-tuple[Any, ...] | dict[str, Any] | np.ndarrayrr)r%z,Box | Discrete | MultiDiscrete | MultiBinaryrOrrrrr)r%rrOrrrrr)r%r rOrrrrr)r%rrOrrNonerr)r%rr&r\rrrr)r%r r&r\rr)r%rr&r\rr)r%r r&r\rr)r%rr&r\rztuple[GraphInstance, ...])r%rr&r\rztuple[str, ...])r%rr&r\rr)r%rr&r\)F__doc__ __future__rtypingcollections.abcrrrcopyr functoolsr r numpyr2gymnasium.errorr gymnasium.spacesr r rrrrrrrrrrgymnasium.spaces.spacer__all__rregisterr7r<r?rCrMrQrarrxrzrrrrrrrrrrrrrrrzerosrrrrrrrrrrr(r'rs# 88$,    ) : cVV  h  m$ %  k"# e d e d h e e   DD4  %&&  *+  /0&  - .   '(  & '   '  &  *  '(+'(   D (JJ #- +! %$ $== !(U2> c h m$ k", 7, , , ,#% , e !(7 d  '5 e d h e e  RXX "*2FS!X&]+[)345*,'" 5U#56288X$XT"34# U#    $ .T"34K#KX&BHH0 000'0U#56288,$,U#()bhh$r(