ib3dZddlZddlZddlZddlZddlmZmZm Z m Z m Z ddl m Z ddlmZddlmZmZmZmZmZdd lmZdd lmZdd lmZdd lmZdd lmZddlmZmZm Z ddlm!Z!Gdde"Z#Gdde#Z$Gdde#Z%Gdde#Z&Gdde"Z'Gddej(Z)Gdde'e)Z*Gdd e*Z+Gd!d"e,Z-Gd#d$e'e-Z.Gd%d&e*Z/d'Z0Gd(d)e,Z1Gd*d+e'e1Z2Gd,d-e+Z3Gd.d/e#Z4dS)0a Base classes --- :mod:`MDAnalysis.coordinates.base` =================================================== Derive, FrameIterator, Reader and Writer classes from the classes in this module. The derived classes must follow the :ref:`Trajectory API`. .. _FrameIterators: FrameIterators -------------- FrameIterators are "sliced trajectories" (a trajectory is a :ref:`Reader `) that can be iterated over. They are typically created by slicing a trajectory or by fancy-indexing of a trajectory with an array of frame numbers or a boolean mask of all frames. Iterator classes used by the by the :class:`ProtoReader`: .. autoclass:: FrameIteratorBase .. autoclass:: FrameIteratorSliced .. autoclass:: FrameIteratorAll .. autoclass:: FrameIteratorIndices .. autoclass:: StreamFrameIteratorSliced .. _ReadersBase: Readers ------- Readers know how to take trajectory data in a given format and present it in a common API to the user in MDAnalysis. There are two types of readers: 1. Readers for *multi frame trajectories*, i.e., file formats that typically contain many frames. These readers are typically derived from :class:`ReaderBase`. 2. Readers for *single frame formats*: These file formats only contain a single coordinate set. These readers are derived from :class:`SingleFrameReaderBase`. The underlying low-level readers handle closing of files in different ways. Typically, the MDAnalysis readers try to ensure that files are always closed when a reader instance is garbage collected, which relies on implementing a :meth:`~ReaderBase.__del__` method. However, in some cases, this is not necessary (for instance, for the single frame formats) and then such a method can lead to undesirable side effects (such as memory leaks). In this case, :class:`ProtoReader` should be used. .. autoclass:: ReaderBase :members: :inherited-members: .. autoclass:: SingleFrameReaderBase :members: :inherited-members: .. autoclass:: ProtoReader :members: .. autoclass:: StreamReaderBase :members: .. _WritersBase: Writers ------- Writers know how to write information in a :class:`Timestep` to a trajectory file. .. autoclass:: WriterBase :members: :inherited-members: Converters ---------- Converters output information to other libraries. .. deprecated:: 2.7.0 All converter code has been moved to :mod:`MDAnalysis.converters` and will be removed from the :mod:`MDAnalysis.coordinates.base` module in 3.0.0. .. autoclass:: ConverterBase :members: :inherited-members: Helper classes -------------- The following classes contain basic functionality that all readers and writers share. .. autoclass:: IOBase :members: N)AnyUnionOptionalListDict)Timestep)core)_READERS _READER_HINTS_SINGLEFRAME_WRITERS_MULTIFRAME_WRITERS _CONVERTERS)units) AuxReader) auxreader)get_auxreader_for) _AUXREADERS) asiterable Namespacestore_init_arguments) NamedStreamcJeZdZdZdZdZedZedZ dS)FrameIteratorBaseaM Base iterable over the frames of a trajectory. A frame iterable has a length that can be accessed with the :func:`len` function, and can be indexed similarly to a full trajectory. When indexed, indices are resolved relative to the iterable and not relative to the trajectory. .. versionadded:: 0.19.0 c||_dSN _trajectory)self trajectorys e/srv/www/vhosts/g4struct/public_html/venv/lib/python3.11/site-packages/MDAnalysis/coordinates/base.py__init__zFrameIteratorBase.__init__s%ctrNotImplementedErrorr s r"__len__zFrameIteratorBase.__len__s!###r$ct|tr8|r6t|dtrtj|tS|S)Nrdtype) isinstancelistboolnparray)framess r"_avoid_bool_listz"FrameIteratorBase._avoid_bool_listsJ fd # # 0 0:fQi3N3N 08F$/// / r$c|jSrrr(s r"r!zFrameIteratorBase.trajectorys r$N) __name__ __module__ __qualname____doc__r#r) staticmethodr3propertyr!r$r"rrsr  &&&$$$\   X   r$rcveZdZdZfdZdZdZdZedZ edZ edZ xZ S) FrameIteratorSlicedaH Iterable over the frames of a trajectory on the basis of a slice. Parameters ---------- trajectory: ProtoReader The trajectory over which to iterate. frames: slice A slice to select the frames of interest. See Also -------- FrameIteratorBase .. versionadded:: 0.19.0 ctt||||j|j|j\|_|_|_ dSr) superr=r#check_slice_indicesstartstopstep_start_stop_step)r r!r2 __class__s r"r#zFrameIteratorSliced.__init__sW !4((11*===.8.L.L L&+v{/ / + TZr$cBt|j|j|jSr) range_lengthrArBrCr(s r"r)zFrameIteratorSliced.__len__sDJ 49===r$c#Kt|j|j|jD]}|j|V|jdSr)rangerArBrCr!rewind)r is r"__iter__zFrameIteratorSliced.__iter__sWtz49di88 % %A/!$ $ $ $ $      r$c t|tjrt|}| |cxkr|ks%nt d|||dkrt||z}|j||jzz}|j |St|tr|jpd|jz}|j=|j |jdkr|j}n<|jt|dz |jzz}n|j|jpd|jzz}|j Q|j |jdkr |t||j |dz |zz}n|j}|tj|z}n|j|j pd|jzz}t|||}t|j|}||_||_||_|S||}tjt+t-|j|j |j|} t/|j| S)Nz3Index {} is out of range of the range of length {}.rr)r-numbersIntegrallen IndexErrorformatrArCr!_read_frame_with_auxslicerBrIr0signr=rDrErFr3r1r.rKFrameIteratorIndices) r framelengthrCrAlastrB new_sliceframe_iteratorr2s r" __getitem__zFrameIteratorSliced.__getitem__s5 eW- . .* AYYF7U++++V++++ !V"(&"7"7999qyyD E)J!22E?77>> > u % %! AJO!ty0D{":%a JEE J#d))a-49)DDEE ek&6Q$)%CCz!:%a L 4$H$H1$LPT#TTDD:Dbgdmm+zUZ_1 $AAeT400I0)LLN %*N !#'N #'N ! !))%00EXd5TY #J#JKKLLUSF'@@ @r$c|jSr)rDr(s r"rAzFrameIteratorSliced.starts {r$c|jSr)rEr(s r"rBzFrameIteratorSliced.stop  zr$c|jSrrFr(s r"rCzFrameIteratorSliced.step rar$) r5r6r7r8r#r)rNr^r:rArBrC __classcell__rGs@r"r=r=s"     >>>!!! +A+A+AZXXXr$r=c4eZdZdZfdZdZdZdZxZS)FrameIteratorAllz Iterable over all the frames of a trajectory. Parameters ---------- trajectory: ProtoReader The trajectory over which to iterate. See Also -------- FrameIteratorBase .. versionadded:: 0.19.0 cXtt||dSr)r?rgr#)r r!rGs r"r#zFrameIteratorAll.__init__"s( %%..z:::::r$c|jjSr)r!n_framesr(s r"r)zFrameIteratorAll.__len__%s ''r$c*t|jSr)iterr!r(s r"rNzFrameIteratorAll.__iter__(sDO$$$r$c|j|Sr)r!r rYs r"r^zFrameIteratorAll.__getitem__+su%%r$) r5r6r7r8r#r)rNr^rdres@r"rgrgso;;;;;(((%%%&&&&&&&r$rgcJeZdZdZfdZdZdZdZedZ xZ S)rXa! Iterable over the frames of a trajectory listed in a sequence of indices. Parameters ---------- trajectory: ProtoReader The trajectory over which to iterate. frames: sequence A sequence of indices. See Also -------- FrameIteratorBase cRtt||g|_|D]Z}t |t jstd||}|j |[t|j|_dS)Nz Frames indices must be integers.) r?rXr#_framesr-rPrQ TypeError _apply_limitsappendtuple)r r!r2rYrGs r"r#zFrameIteratorIndices.__init__>s "D))22:>>>  ' 'EeW%566 D BCCC,,U33E L   & & & &T\** r$c*t|jSr)rRr2r(s r"r)zFrameIteratorIndices.__len__Hs4;r$c#K|jD]}|j|V|jdSr)r2r!rUrLrns r"rNzFrameIteratorIndices.__iter__KsP[ > >E/66u== = = = =      r$ct|tjr'|j|}|j|S||}tj|j|}t|j|Sr) r-rPrQr2r!rUr3r0r1rX)r rYr2s r"r^z FrameIteratorIndices.__getitem__Psu eW- . . AK&E?77>> >))%00EXdk**51F'@@ @r$c|jSr)rqr(s r"r2zFrameIteratorIndices.framesYs |r$) r5r6r7r8r#r)rNr^r:r2rdres@r"rXrX/s  +++++   !!! AAAXr$rXcpeZdZdZddddZddZddZddZddZdd Z dd Z dd Z dd Z d Z dZdZdS)IOBasezBase class bundling common functionality for trajectory I/O. .. versionchanged:: 0.8 Added context manager protocol. N)timerZvelocityTcptjd|jdd}|dkr|S|s||zS||z}|S)aConversion of coordinate array x from native units to base units. Parameters ---------- x : array_like Positions to transform inplace : bool (optional) Whether to modify the array inplace, overwriting previous data Note ---- By default, the input `x` is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided. .. versionchanged:: 0.7.5 Keyword `inplace` can be set to ``False`` so that a modified copy is returned *unless* no conversion takes place, in which case the reference to the unmodified `x` is returned. rZAngstrom?rget_conversion_factorr xinplacefs r"convert_pos_from_nativezIOBase.convert_pos_from_nativeisS0  '(, 8(>++%("!Y...7.G.PM(+  Q Q    DD sA77 BBN)r5r6r7r8r#r;r$r"rrks2 Q Q Q Q Qr$rceZdZUdZeZeed<eed<e ed<e ed<dZ de fdZ e d Zdefd Zdefd Zdefd Zedefd ZedefdZede fdZedZedZdZdZejd;dZdZejdZdZ dZ!dZ"dZ#dZ$dZ%dZ& dd2Z5d3Z6d4Z7d5Z8d;d6Z9ed7Z:e:j;d8Z:d9Z?? ?r$c |j|d<|d|j |d|jn#t$rYnwxYwt j|fi|S)aReturns a writer appropriate for *filename*. Sets the default keywords *start*, *step* and *dt* (if available). *n_atoms* is always set from :attr:`Reader.n_atoms`. See Also -------- :meth:`Reader.Writer` and :func:`MDAnalysis.Writer` n_atomsrAr)r setdefaultrYrrr writerrs r" OtherWriterzProtoReader.OtherWriters!Ly'4:...    dDG , , , ,    D {8..v...sA AANcdSrr;r rs r"rzProtoReader._read_next_timesteps  r$c.||S)z! Iterate over trajectory frames. )rr(s r"rNzProtoReader.__iter__"s  r$cdS)zyShould position Reader to just before first frame Calling next after this should return the first frame Nr;r(s r"rzProtoReader._reopen's r$c|dkr|t|z }|dks|t|kr0td|t||S)Nrz+Index {} exceeds length of trajectory ({}).)rRrSrTrns r"rszProtoReader._apply_limits/se 199 SYY E 199T** &uc$ii 8 8:: : r$ct|tjr*||}||St|t t jfrt|dkrit|dtt j frBt j |t}t j t||}t||St|trh||j|j|j\}}}|dkr(|t|kr|dkrt'|St)||St+d)a|Return the Timestep corresponding to *frame*. If `frame` is a integer then the corresponding frame is returned. Negative numbers are counted from the end. If frame is a :class:`slice` then an iterator is returned that allows iteration over that part of the trajectory. Note ---- *frame* is a 0-based frame index. rr+rzJTrajectories must be an indexed using an integer, slice or list of indices)r-rPrQrsrUr.r0ndarrayrRr/bool_asarrayarangerXrVr@rArBrCrgr=rr)r rYrArBrCs r"r^zProtoReader.__getitem__7sP eW- . . 9&&u--E,,U33 3 bj1 2 2 95zzQ:eAhrx8H#I#I 5555 #d)),,U3'e44 4 u % % 9 $ 8 8 UZ!5!5 E4zzdc$ii//DAII'---*4777899 9r$cZtd|jj)z,Move to *frame* and fill timestep with data.z+{0} does not support direct frame indexing.)rrrTrGr5rns r" _read_framezProtoReader._read_frameYs+!6$."9::<< >w G GHHH7#&!&! 199011 1d))yq =AAw{EE QYY W E 199E !88((aKE <"Qhh77BDD AXX GOD !88wDdD  r$cfd|jj|j|j|jS)Nz7<{cls} {fname} with {nframes} frames of {natoms} atoms>)rfnamernatoms)rTrGr5rrjrr(s r"__repr__zProtoReader.__repr__s76'-M<    r$facasel AtomGroup atomgroup AtomgrouprArBrCorderc|.tjdt|rtd|}||||\}}}t t |||}|9t |dkrtd|j}t |} n|j} tj | }tj || dftj } t||||D]\} } | j|| | ddf<d |krn fd |D} n!#t$rtd |d wxYw tj| | gd } n##t$rd|d}t|wxYw| S)aReturn a subset of coordinate data for an AtomGroup Parameters ---------- asel : AtomGroup (optional) The :class:`~MDAnalysis.core.groups.AtomGroup` to read the coordinates from. Defaults to ``None``, in which case the full set of coordinate data is returned. .. deprecated:: 2.7.0 asel argument will be renamed to atomgroup in 3.0.0 atomgroup: AtomGroup (optional) Same as `asel`, will replace `asel` in 3.0.0 start : int (optional) Begin reading the trajectory at frame index `start` (where 0 is the index of the first frame in the trajectory); the default ``None`` starts at the beginning. stop : int (optional) End reading the trajectory at frame index `stop`-1, i.e, `stop` is excluded. The trajectory is read to the end with the default ``None``. step : int (optional) Step size for reading; the default ``None`` is equivalent to 1 and means to read every frame. order : str (optional) the order/shape of the return data array, corresponding to (a)tom, (f)rame, (c)oordinates all six combinations of 'a', 'f', 'c' are allowed ie "fac" - return array where the shape is (frame, number of atoms, coordinates) See Also -------- :class:`MDAnalysis.coordinates.memory` .. versionadded:: 2.4.0 NzKasel argument to timeseries will be renamed to'atomgroup' in 3.0, see #3911)categoryz-Cannot provide both asel and atomgroup kwargsrz0Timeseries requires at least one atom to analyzer+rc:g|]}|Sr;)index).0rM default_orders r" z*ProtoReader.timeseries..,s'@@@Q---a00@@@r$zUnrecognized order key in z, must be permutation of 'fac')rrr z5Repeated or missing keys passed to argument `order`: z, each key must be used once)warningswarnDeprecationWarningrr@rRrKindicesrr0remptyfloat32 enumerate positionsmoveaxis)r rrrArBrCr r atom_numbersr coordinatesrMrnewidxrrs @r" timeserieszProtoReader.timeseriess-X   M0+ - - - - R !PQQQI 44UD$GGtTeE4..//  9~~"" FHHH$,L&&FF\F9V,,Lh32:FFF tE$tO455 ; ;EAr " \ :K111   M ! ! A@@@@%@@@ A A A "@e"@"@"@AAA A ) k+vyyyII  ) ) )J&+JJJ ((( )sD..E E)) F aux_specauxdatarTc |tdt|ttjvrt |}||}n|}|j|||fi|dS)a\ Add auxiliary data to be read alongside trajectory. Auxiliary data may be any data timeseries from the trajectory additional to that read in by the trajectory reader. *auxdata* can be an :class:`~MDAnalysis.auxiliary.base.AuxReader` instance, or the data itself as e.g. a filename; in the latter case an appropriate :class:`~MDAnalysis.auxiliary.base.AuxReader` is guessed from the data/file format. An appropriate `format` may also be directly provided as a key word argument. On adding, the AuxReader is initially matched to the current timestep of the trajectory, and will be updated when the trajectory timestep changes (through a call to :meth:`next()` or jumping timesteps with ``trajectory[i]``). The representative value(s) of the auxiliary data for each timestep (as calculated by the :class:`~MDAnalysis.auxiliary.base.AuxReader`) are stored in the current timestep in the ``ts.aux`` namespace under *aux_spec*; e.g. to add additional pull force data stored in pull-force.xvg:: u = MDAnalysis.Universe(PDB, XTC) u.trajectory.add_auxiliary('pull', 'pull-force.xvg') The representative value for the current timestep may then be accessed as ``u.trajectory.ts.aux.pull`` or ``u.trajectory.ts.aux['pull']``. The following applies to energy readers like the :class:`~MDAnalysis.auxiliary.EDR.EDRReader`. All data that is present in the (energy) file can be added by omitting `aux_spec` like so:: u.trajectory.add_auxiliary(auxdata="ener.edr") *aux_spec* is expected to be a dictionary that maps the desired attribute name in the ``ts.aux`` namespace to the precise data to be added as identified by a :attr:`data_selector`:: term_dict = {"temp": "Temperature", "epot": "Potential"} u.trajectory.add_auxiliary(term_dict, "ener.edr") Adding this data can be useful, for example, to filter trajectory frames based on non-coordinate data like the potential energy of each time step. Trajectory slicing allows working on a subset of frames:: selected_frames = np.array([ts.frame for ts in u.trajectory if ts.aux.epot < some_threshold]) subset = u.trajectory[selected_frames] See Also -------- :meth:`remove_auxiliary` Note ---- Auxiliary data is assumed to be time-ordered, with no duplicates. See the :ref:`Auxiliary API`. Nz:No input `auxdata` specified, but it needs to be provided.)rrr.rvaluesrattach_auxiliary)r r r!rTr reader_typers r" add_auxiliaryzProtoReader.add_auxiliary:sD ?/00 0 ==[%7%9%9 : : : :+G44K# G,,III" "46DDVDDDDDr$c||}|~t|jj|dS)zClear data and close the :class:`~MDAnalysis.auxiliary.base.AuxReader` for the auxiliary *auxname*. See Also -------- :meth:`add_auxiliary` N)_check_for_auxrdelattrrrr rrs r"remove_auxiliaryzProtoReader.remove_auxiliarysA!!'**  W%%%%%r$c4|jS)z* Lists the names of added auxiliary data. )rkeysr(s r"rzProtoReader.aux_listsz   r$ct||jvr |j|Std|)z Check for the existance of an auxiliary *auxname*. If present, return the AuxReader; if not, raise ValueError zNo auxiliary named {name}r)rrrrT)r rs r"r(zProtoReader._check_for_auxs> dm # #:g& &8??W?MMNN Nr$c||}|j}||jdz|-t |||jdz|-||}|t |j|kst|dddkr4|}|j|kt|dddk4|S)a Move to the next timestep for which there is at least one step from the auxiliary *auxname* within the cutoff specified in *auxname*. This allows progression through the trajectory without encountering ``NaN`` representative values (unless these are specifically part of the auxiliary data). If the auxiliary cutoff is not set, where auxiliary steps are less frequent (``auxiliary.dt > trajectory.dt``), this allows progression at the auxiliary pace (rounded to nearest timestep); while if the auxiliary steps are more frequent, this will work the same as calling :meth:`next()`. See the :ref:`Auxiliary API`. See Also -------- :meth:`iter_as_aux` rN_framerr) r(r step_to_framerCrnext_nonempty_framerrYgetattr)r rrr next_frames r" next_as_auxzProtoReader.next_as_auxs*!!'** W1 b119 III1 b119,,R00   jJ&&'$!*D*D*J*JBjJ&&'$!*D*D*J*J r$c#K||}|| ||Vn#t$rYdSwxYw+)zIterate through timesteps for which there is at least one assigned step from the auxiliary *auxname* within the cutoff specified in *auxname*. See Also -------- :meth:`next_as_aux` :meth:`iter_auxiliary` TN)r(r_restartr6rr*s r" iter_as_auxzProtoReader.iter_as_auxs!!'**    &&w//////      sA A('A(c#K||}||}nt|||}||D]}|V||jdS)az Iterate through the auxiliary *auxname* independently of the trajectory. Will iterate over the specified steps of the auxiliary (defaults to all steps). Allows to access all values in an auxiliary, including those out of the time range of the trajectory, without having to also iterate through the trajectory. After interation, the auxiliary will be repositioned at the current step. Parameters ---------- auxname : str Name of the auxiliary to iterate over. (start, stop, step) : optional Options for iterating over a slice of the auxiliary. selected : lst | ndarray, optional List of steps to iterate over. Yields ------ :class:`~MDAnalysis.auxiliary.base.AuxStep` object See Also -------- :meth:`iter_as_aux` N)r(rVread_tsr) r rrArBrCselectedr selectionrMs r"iter_auxiliaryzProtoReader.iter_auxiliarysq8!!'**   IIeT400IY  AGGGG DGr$cL||}t||S)aLGet the value of *attrname* from the auxiliary *auxname* Parameters ---------- auxname : str Name of the auxiliary to get value for attrname : str Name of gettable attribute in the auxiliary reader See Also -------- :meth:`set_aux_attribute` )r(r4)r rattrnamers r"get_aux_attributezProtoReader.get_aux_attributes'!!'**sH%%%r$c||}|dkr|||dSt|||dS)a Set the value of *attrname* in the auxiliary *auxname*. Parameters ---------- auxname : str Name of the auxiliary to alter attrname : str Name of settable attribute in the auxiliary reader new New value to try set *attrname* to See Also -------- :meth:`get_aux_attribute` :meth:`rename_aux` - to change the *auxname* attribute rN)r( rename_auxsetattr)r rr@newrs r"set_aux_attributezProtoReader.set_aux_attributesT"!!'** y OOGS ) ) ) ) ) C3 ' ' ' ' 'r$cd||}||jvr#td|||_|j||j|<t|jj ||jj |t|jj |dS)a1 Change the name of the auxiliary *auxname* to *new*. Provided there is not already an auxiliary named *new*, the auxiliary name will be changed in ts.aux namespace, the trajectory's list of added auxiliaries, and in the auxiliary reader itself. Parameters ---------- auxname : str Name of the auxiliary to rename new : str New name to try set Raises ------ ValueError If the name *new* is already in use by an existing auxiliary. z.Auxiliary data with name {name} already existsr/N) r(rrrTrrpoprDrrr))r rrErs r"rCzProtoReader.rename_aux's&!!'** $-  &&,f#f&6&688 8 *..11 3 S$'+g"6777 W%%%%%r$c6|sj}fd|D}|S)aGet descriptions to allow reloading the specified auxiliaries. If no auxnames are provided, defaults to the full list of added auxiliaries. Passing the resultant description to ``add_auxiliary()`` will allow recreation of the auxiliary. e.g., to duplicate all auxiliaries into a second trajectory:: descriptions = trajectory_1.get_aux_descriptions() for aux in descriptions: trajectory_2.add_auxiliary(**aux) Returns ------- list List of dictionaries of the args/kwargs describing each auxiliary. See Also -------- :meth:`MDAnalysis.auxiliary.base.AuxReader.get_description` cNg|]!}j|"Sr;)rget_description)rrr s r"rz4ProtoReader.get_aux_descriptions..]s+NNNc 37799NNNr$)r)r auxnames descriptionss` r"get_aux_descriptionsz ProtoReader.get_aux_descriptionsCs30 %}HNNNNXNNN r$c|jS)z$ Returns the list of transformations)rr(s r"transformationszProtoReader.transformations`s $$r$c@|js ||_dStd)NzTransformations are already set)rr)r rPs r"rPzProtoReader.transformationses+$ @$3D ! ! !>?? ?r$c ||_||j|_dS#t$rd}t|dwxYw)aAdd all transformations to be applied to the trajectory. This function take as list of transformations as an argument. These transformations are functions that will be called by the Reader and given a :class:`Timestep` object as argument, which will be transformed and returned to the Reader. The transformations can be part of the :mod:`~MDAnalysis.transformations` module, or created by the user, and are stored as a list `transformations`. This list can only be modified once, and further calls of this function will raise an exception. .. code-block:: python u = MDAnalysis.Universe(topology, coordinates) workflow = [some_transform, another_transform, this_transform] u.trajectory.add_transformations(*workflow) The transformations are applied in the order given in the list `transformations`, i.e., the first transformation is the first or innermost one to be applied to the :class:`Timestep`. The example above would be equivalent to .. code-block:: python for ts in u.trajectory: ts = this_transform(another_transform(some_transform(ts))) Parameters ---------- transform_list : list list of all the transformations that will be applied to the coordinates in the order given in the list See Also -------- :mod:`MDAnalysis.transformations` zDCan't add transformations again. Please create a new Universe objectN)rPrrr)r rPrs r"add_transformationszProtoReader.add_transformationslsaR ;#2D 11$'::DGGG  / / /(FV$$$ . /s *Ac0|jD] }||}|S)z2Applies all the transformations given by the user )rP)r r transforms r"rz"ProtoReader._apply_transformationss*-  I2BB r$r)NNNNNr)NNN)NNNN)>r5r6r7r8r _Timestepr.__annotations__dictrrr#r) classmethodrrrrLr:floatrrrYr|r!rrabcabstractmethodrrNrrsr^rrUrr@rrstrr0rrrrrr&r+rr(r6r9r>rArFrCrNrPsetterrSrr;r$r"rrs8I KKKNNNMMM!!! ;;[; h    ( EX -5 - - -X -sXXX???///(           9 9 9D<<<...&V!V!V!p   6:48BF'+(- UUx 4U&{3U"3-U4B7;$(KEKE %c4S>&9 :KE$S)^4KE"KE$( KEKEKEKEZ & & &!!X!OOO$$$L$CG $####J&&&"(((.&&&8:%%X%@@@ 0;0;0;lr$r) metaclassc@eZdZdZedfd ZdZdZxZS) ReaderBaseaKBase class for trajectory readers that extends :class:`ProtoReader` with a :meth:`__del__` method. New Readers should subclass :class:`ReaderBase` and properly implement a :meth:`close` method, to ensure proper release of resources (mainly file handles). Readers that are inherently safe in this regard should subclass :class:`ProtoReader` instead. See the :ref:`Trajectory API` definition in for the required attributes and methods. See Also -------- :class:`ProtoReader` .. versionchanged:: 0.11.0 Most of the base Reader class definitions were offloaded to :class:`ProtoReader` so as to allow the subclassing of ReaderBases without a :meth:`__del__` method. Created init method to create common functionality, all ReaderBase subclasses must now :func:`super` through this class. Added attribute :attr:`_ts_kwargs`, which is created in init. Provides kwargs to be passed to :class:`Timestep` .. versionchanged:: 1.0 Removed deprecated flags functionality, use convert_units kwarg instead Tc tt|t|tr||_nt ||_||_i}dD] } ||}|||<#t$rYwxYw||_ dS)Nr time_offset) r?rar#r-rrr] convert_unitsr _ts_kwargs)r rrer ts_kwargsattvalrGs r"r#zReaderBase.__init__s j$((*** h , , *$DMMMMDM* ( % %C %Sk"% #     $s(A66 BBcD|jdi|j}|jr|j|j||jj|j|_|jD]-\}}| ||.|SaQReturn independent copy of this Reader. New Reader will have its own file handle and can seek/iterate independently of the original. Will also copy the current state of the Timestep held in the original Reader. .. versionchanged:: 2.2.0 Arguments used to construct the reader are correctly captured and passed to the creation of the new class. Previously the only ``n_atoms`` was passed to class copies, leading to a class created with default parameters which may differ from the original class. r;) rG_kwargsrPrSrrYcopyrrr&r rErauxreads r"rmzReaderBase.copys"dn,,t|,,   ; #C #T%9 : : DGM $ 0 0 2 2 7 7 GW   gw||~~ 6 6 6 6 r$c|jD]!}|j|"|dSr)rrr)r rs r"__del__zReaderBase.__del__s?= $ $C JsO ! ! # # # # r$r) r5r6r7r8rr#rmrqrdres@r"rarasr6$$$$$$(<r$raceZdZdZdS) _Writermetactt||| t|d}|dd}|dd}|r#|D] }|}|t |<!|r#|D]"}|}|t |<!dSdS#t$rYdSwxYw)NrT singleframeT multiframeF)rr#rgetrrrr)rrrrrsinglemultirs r"r#z_Writermeta.__init__s dD%333 1Yx011C ]]=$77FMM,66E 222A A.1(++ 111A A-0'** 1 111    DD sB33 CCNr5r6r7r#r;r$r"rsrss#11111r$rsc2eZdZdZd dZdZdZdZdZdS) WriterBaseaBase class for trajectory writers. See :ref:`Trajectory API` definition in for the required attributes and methods. .. versionchanged:: 2.0.0 Deprecated :func:`write_next_timestep` has now been removed, please use :func:`write` instead. Tc |j)tjdtjd}}n|jdd|jdd}}|s|}||}tj||gS)zRead dimensions from timestep *ts* and return appropriate unitcell. The default is to return ``[A,B,C,alpha,beta,gamma]``; if this is not appropriate then this method has to be overriden. Nr ) dimensionsr0zerosrmr concatenate)r rrlengthsangless r"convert_dimensions_to_unitcellz)WriterBase.convert_dimensions_to_unitcell's =  hqkk28A;;VGG mBQB/qrr1BVG %llnnG,,W55~w/000r$c,||S)aJWrite current timestep, using the supplied `obj`. Parameters ---------- obj : :class:`~MDAnalysis.core.groups.AtomGroup` or :class:`~MDAnalysis.core.universe.Universe` write coordinate information associate with `obj` Note ---- The size of the `obj` must be the same as the number of atoms provided when setting up the trajectory. .. versionchanged:: 2.0.0 Deprecated support for Timestep argument to write has now been removed. Use AtomGroup or Universe as an input instead. )_write_next_framer objs r"writezWriterBase.write8s$%%c***r$c.|dSrrr(s r"rqzWriterBase.__del__Ls r$c d|jj|j|jS#t t f$r(d|jj|jcYSwxYw)Nz< {0!s} {1!r} for {2:d} atoms >z< {0!s} {1!r} >)rTrGr5rrrrAttributeErrorr(s r"rzWriterBase.__repr__Osv T4;;DN* T T T%++DN,CT]SS S S S Ts*-6A&%A&ctj|}tj|d|kotj||dkS)aReturns ``True`` if all values are within limit values of their formats. Due to rounding, the test is asymmetric (and *min* is supposed to be negative):: min < x <= max Parameters ---------- criteria : dict dictionary containing the *max* and *min* values in native units x : numpy.ndarray ``(x, y, z)`` coordinates of atoms selected to be written out Returns ------- bool minmax)r0ravelall)r criteriars r"has_valid_coordinatesz WriterBase.has_valid_coordinatesWsB$ HQKKvhuo)**Krva8E?6J/K/KKr$Nr) r5r6r7r8rrrqrrr;r$r"r|r|sv  1111"+++(TTTLLLLLr$r|ceZdZdZdZedfd ZdZdZfdZ d Z d Z dd Z d Z d ZdZfdZdZxZS)SingleFrameReaderBaseu Base class for Readers that only have one frame. To use this base class, define the method :meth:`_read_first_frame` to read from file `self.filename`. This should populate the attribute `self.ts` with a :class:`Timestep` object. .. versionadded:: 0.10.0 .. versionchanged:: 0.11.0 Added attribute "_ts_kwargs" for subclasses Keywords "dt" and "time_offset" read into _ts_kwargs .. versionchanged:: 2.2.0 Calling `__iter__` now rewinds the reader before yielding a :class:`Timestep` object (fixing behavior that was not well defined previously). .. versionchanged:: 2.10.0 Fixed a typo in the attribute assignment (`self.atom` → `self.atoms`), which may affect subclasses relying on this value. z {0} only contains a single frameTNc tt|||_||_d|_||_i}dD] } ||}|||<#t$rYwxYw||_| dS)Nrrc) r?rr#rrerjrrrf_read_first_frame) r rrerrrgrhrirGs r"r#zSingleFrameReaderBase.__init__s #T**33555  *   ( % %C %Sk"% #     $      s A A'&A'c |jdi|j}|j|_|jD]-\}}|||.|j|_|Srk)rGrlrrmrrr&rPrns r"rmzSingleFrameReaderBase.copys dn,,t|,, $ 0 0 2 2 7 7 GW   gw||~~ 6 6 6 6#2 r$cdSrr;r(s r"rz'SingleFrameReaderBase._read_first_framerr$c||jD]$\}}||j|_%t t ||jdSr)rrrrrr?rr)r rrorGs r"rLzSingleFrameReaderBase.rewindsw    $ 0 0 2 2 1 1 GW''00DGG #T**AA$'JJJJJr$cdSrr;r(s r"rzSingleFrameReaderBase._reopens r$cdt|j|jjr)r_errrTrGr5r(s r"rzSingleFrameReaderBase.nexts%DI,,T^-DEEFFFr$cdt|j|jjr)r'rrTrGr5rs r"rz)SingleFrameReaderBase._read_next_timesteps%!$)"2"24>3J"K"KLLLr$c#DK||jVdSr)rLrr(s r"rNzSingleFrameReaderBase.__iter__s# g r$c~|dkr1t|j|jj|jS)Nr)rSrrTrGr5rrns r"rz!SingleFrameReaderBase._read_frames5 A::TY--dn.EFFGG Gwr$cdSrr;r(s r"rzSingleFrameReaderBase.closes  r$ctt|j||jD]}||j|_dS)a% Add all transformations to be applied to the trajectory. This function take as list of transformations as an argument. These transformations are functions that will be called by the Reader and given a :class:`Timestep` object as argument, which will be transformed and returned to the Reader. The transformations can be part of the :mod:`~MDAnalysis.transformations` module, or created by the user, and are stored as a list `transformations`. This list can only be modified once, and further calls of this function will raise an exception. .. code-block:: python u = MDAnalysis.Universe(topology, coordinates) workflow = [some_transform, another_transform, this_transform] u.trajectory.add_transformations(*workflow) Parameters ---------- transform_list : list list of all the transformations that will be applied to the coordinates See Also -------- :mod:`MDAnalysis.transformations` N)r?rrSrPr)r rPrUrGs r"rSz)SingleFrameReaderBase.add_transformationssR@ ?#T**>PP- ) )Ii((DGG ) )r$c|S)z- Applies the transformations to the timestep.r;rs r"rz,SingleFrameReaderBase._apply_transformationss  r$)TNr)r5r6r7r8rrr#rmrrLrrrrNrrrSrrdres@r"rrms$$ .D!!!!!!*6   KKKKK    GGGMMMM     ")")")")")Hr$rc|dkr!||krtd|dz |z |zzS|dkr"||krtd|dz |z | zzSdS)Nrr)rrs r"rIrIso qUT\\1q5(T11222 ((ut||1 D(te44555qr$ceZdZdZdS)_Convertermetactt||| t|d}|D] }|}|t|<!dS#t $rYdSwxYw)Nlib)rr#rrrr)rrrrrrs r"r#z_Convertermeta.__init__s dD%333 %Yu-..C % %GGII!$ A % %    DD sA A,+A,Nrzr;r$r"rrs# % % % % %r$rc$eZdZdZdZdZdZdS) ConverterBasezBase class for converting to other libraries. .. deprecated:: 2.7.0 This class has been moved to :class:`MDAnalysis.converters.base.ConverterBase` and will be removed from :mod:`MDAnalysis.coordinates.base` in 3.0.0. cBd}tj|tddS)NzConverterBase moved from coordinates.base.ConverterBase to converters.base.ConverterBase and will be removed from coordinates.base in MDAnalysis release 3.0.0r ) stacklevel)rrr)rwmsgs r"__init_subclass__zConverterBase.__init_subclass__-s).  d.1======r$cBd|jjS)Nz<{cls}>)r)rTrGr5r(s r"rzConverterBase.__repr__4sDN$;<<>>==="""""r$rceZdZdZdfd ZdZedZdZdZ dZ d Z d Z d Z d Zd ZdZdZdZdefdZdZxZS)StreamReaderBasea Base class for readers that read a continuous stream of data. This class is designed for readers that process continuous data streams, such as live feeds from simulations. Unlike traditional trajectory readers that can randomly access frames, streaming readers have fundamental constraints: - **No random access**: Cannot seek to arbitrary frames (no ``traj[5]``) - **Forward-only**: Can only iterate sequentially through frames - **No length**: Total number of frames is unknown until stream ends - **No rewinding**: Cannot restart or rewind the stream - **No copying**: Cannot create independent copies of the reader - **No reopening**: Cannot restart iteration once stream is consumed - **No timeseries**: Cannot use ``timeseries()`` or bulk data extraction - **No writers**: Cannot create ``Writer()`` or ``OtherWriter()`` instances - **No pickling**: Cannot serialize reader instances (limits multiprocessing) - **No StreamWriterBase**: No complementary Writer class available for streaming data The reader raises :exc:`RuntimeError` for operations that require random access or rewinding, including ``rewind()``, ``copy()``, ``timeseries()``, ``Writer()``, ``OtherWriter()``, and ``len()``. Only slice notation is supported for iteration. Parameters ---------- filename : str or file-like Source of the streaming data convert_units : bool, optional Whether to convert units from native to MDAnalysis units (default: True) **kwargs Additional keyword arguments passed to the parent ReaderBase See Also -------- StreamFrameIteratorSliced : Iterator for stepped streaming access ReaderBase : Base class for standard trajectory readers .. versionadded:: 2.10.0 Tc tt|j|fd|i|d|_d|_d|_d|_dS)NreTFr)r?rr# _init_scope_reopen_called _first_tsr1)r rrerrGs r"r#zStreamReaderBase.__init__csa.%%.   $1 5;    # r$c|js"|jdkr|xjdz c_|jS||jdz}|jr%|j|_d|_|S)NrrF)rr1rrrrmrs r"rz$StreamReaderBase._read_next_timesteplsw "DK2$5$5 KK1 KK> !   dkAo . .   %!W\\^^DN$D  r$cZtd|jj)z3Changes as stream is processed unlike other readersz{}: n_frames is unknown RuntimeErrorrTrGr5r(s r"rjzStreamReaderBase.n_frames}s, % , ,T^-D E E   r$cZtd|jjNz{} has unknown lengthrr(s r"r)zStreamReaderBase.__len__* # * *4>+B C C   r$c |}|jD]%\}}|j||}&||}n#t t f$r tdwxYw|S)aAdvance to the next timestep in the streaming trajectory. Streaming readers process frames sequentially and cannot rewind once iteration completes. Use ``for ts in trajectory`` for iteration. Returns ------- Timestep The next timestep in the stream Raises ------ StopIteration When the stream ends or no more frames are available N)rrrrrrrrrs r"rzStreamReaderBase.nexts 1))++B $(:#3#3#5#5 7 7Z(22266,,R00BB'" * * *T ) * s A++BcZtd|jj)aXRewinding is not supported for streaming trajectories. Streaming readers process data continuously from streams and cannot restart or go backward in the stream once consumed. Raises ------ RuntimeError Always raised, as rewinding is not supported for streaming trajectories z){}: Stream-based readers can't be rewoundrr(s r"rLzStreamReaderBase.rewinds1 7 > >'     r$cZtd|jj)aReader copying is not supported for streaming trajectories. Streaming readers maintain internal state and connection resources that cannot be duplicated. Each stream connection is unique and cannot be copied. Raises ------ RuntimeError Always raised, as copying is not supported for streaming trajectories z{} does not support copyingrr(s r"rmzStreamReaderBase.copys, ) 0 01H I I   r$c|jr,td|jjd|_d|_dS)aPrepare stream for iteration - can only be called once. Streaming readers cannot be reopened once iteration begins. This method is called internally during iteration setup and will raise an error if called multiple times. Raises ------ RuntimeError If the stream has already been opened for iteration z{}: Cannot reopen streamrTN)rrrTrGr5r1r(s r"rzStreamReaderBase._reopensN   *11$.2IJJ  "r$c Ztd|jj)aOTimeseries extraction is not supported for streaming trajectories. Streaming readers cannot randomly access frames or store bulk coordinate data in memory, which ``timeseries()`` requires. Use sequential frame iteration instead. Parameters ---------- **kwargs Any keyword arguments (ignored, as method is not supported) Raises ------ RuntimeError Always raised, as timeseries extraction is not supported for streaming trajectories z6{}: cannot access timeseries for streamed trajectoriesr)r rs r"rzStreamReaderBase.timeseriess,$ D K KDNLc d d   r$ct|trK||j|j|j\}}}|t |St||Std)aReturn an iterator for slicing a streaming trajectory. Parameters ---------- frame : slice Slice object. Only the step parameter is meaningful for streams. Returns ------- FrameIteratorAll or StreamFrameIteratorSliced Iterator for the requested slice. Raises ------ TypeError If frame is not a slice object. ValueError If slice contains start or stop values. Examples -------- >>> for ts in traj[:]: # All frames sequentially ... process(ts) >>> for ts in traj[::5]: # Every 5th frame ... process(ts) See Also -------- StreamFrameIteratorSliced Nz6Streamed trajectories must be an indexed using a slice) r-rVr@rArBrCrgStreamFrameIteratorSlicedrr)r rY_rCs r"r^zStreamReaderBase.__getitem__sx> eU # # 11 UZJAq$|'---0t<<<H r$c|,td|jj|,td|jj|yt |t jr3|dkr,td|jjn,td|jj|||fS)aCheck and validate slice indices for streaming trajectories. Streaming trajectories have fundamental constraints that differ from traditional trajectory files: * **No start/stop indices**: Since streams process data continuously without knowing the total length, ``start`` and ``stop`` must be ``None`` * **Step-only slicing**: Only the ``step`` parameter is meaningful, controlling how many frames to skip during iteration * **Forward-only**: ``step`` must be positive (> 0) as streams cannot be processed backward in time Parameters ---------- start : int or None Starting frame index. Must be ``None`` for streaming readers. stop : int or None Ending frame index. Must be ``None`` for streaming readers. step : int or None Step size for iteration. Must be positive integer or ``None`` (equivalent to 1). Returns ------- tuple (start, stop, step) with validated values Raises ------ ValueError If ``start`` or ``stop`` are not ``None``, or if ``step`` is not a positive integer. Examples -------- Valid streaming slices:: traj[:] # All frames (step=None, equivalent to step=1) traj[::2] # Every 2nd frame traj[::10] # Every 10th frame Invalid streaming slices:: traj[5:] # Cannot specify start index traj[:100] # Cannot specify stop index traj[5:100:2] # Cannot specify start or stop indices traj[::-1] # Cannot go backwards (negative step) See Also -------- __getitem__ StreamFrameIteratorSliced .. versionadded:: 2.10.0 NzC{}: Cannot expect a start index from a stream, 'start' must be NonezA{}: Cannot expect a stop index from a stream, 'stop' must be Nonerz7{}: Cannot go backwards in a stream, 'step' must be > 0z{}: 'step' must be an integer)rrTrGr5r-rPrQ)r rArBrCs r"r@z$StreamReaderBase.check_slice_indicessr  U\\N+   SZZN+   $ 011 !88$QXX N3!3::/ dD  r$c Ztd|jj)aVWriter creation is not supported for streaming trajectories. Writer creation requires trajectory metadata that streaming readers cannot provide due to their sequential processing nature. Parameters ---------- filename : str Output filename (ignored, as method is not supported) **kwargs Additional keyword arguments (ignored, as method is not supported) Raises ------ RuntimeError Always raised, as writer creation is not supported for streaming trajectories z2{}: cannot create Writer for streamed trajectoriesrrs r"rzStreamReaderBase.Writerss1$ @ G G'     r$c Ztd|jj)aWriter creation is not supported for streaming trajectories. OtherWriter initialization requires frame-based parameters and trajectory indexing information. Streaming readers process data sequentially without meaningful frame indexing, making writer setup impossible. Parameters ---------- filename : str Output filename (ignored, as method is not supported) **kwargs Additional keyword arguments (ignored, as method is not supported) Raises ------ RuntimeError Always raised, as writer creation is not supported for streaming trajectories z7{}: cannot create OtherWriter for streamed trajectoriesrrs r"rzStreamReaderBase.OtherWriters1& E L L'     r$cZtd|jjNz{} does not support picklingr'rTrGr5r(s r" __getstate__zStreamReaderBase.__getstate__*! * 1 1$.2I J J   r$statecZtd|jjrr)r rs r" __setstate__zStreamReaderBase.__setstate__rr$cZd|jj|j|jS)Nz8<{cls} {fname} with continuous stream of {natoms} atoms>)rrr)rTrGr5rrr(s r"rzStreamReaderBase.__repr__s2 vN+m| r$r)r5r6r7r8r#rr:rjr)rrLrmrrr^r@rrrobjectrrrdres@r"rr:sF&&P"  X    :   $   ###&   ,***XT!T!T!l   0   2    &           r$rcPeZdZdZfdZdZdZdZdZe dZ xZ S)raIterator for sliced frames in a streamed trajectory. Created when slicing a streaming trajectory with a step parameter (e.g., ``trajectory[::n]``). Reads every nth frame from the continuous stream, discarding intermediate frames for performance. This differs from iterating over all frames (``trajectory[:]``) which uses :class:`FrameIteratorAll` and processes every frame sequentially without skipping. Streaming constraints apply to the sliced iterator: - Frames cannot be accessed randomly (no indexing support) - The total number of frames is unknown until streaming ends - Rewinding or restarting iteration is not possible - Only forward iteration with a fixed step size is supported Parameters ---------- trajectory : StreamReaderBase The streaming trajectory reader to iterate over. Must be a stream-based reader that supports continuous data reading. step : int Step size for iteration. Must be a positive integer. A step of 1 reads every frame, step of 2 reads every other frame, etc. See Also -------- StreamReaderBase FrameIteratorBase .. versionadded:: 2.10.0 cXt|||_dSr)r?r#rF)r r!rCrGs r"r#z"StreamFrameIteratorSliced.__init__s& $$$ r$c8|j|Sr)r!rr(s r"rNz"StreamFrameIteratorSliced.__iter__s !!! r$c |jjdz|jzdkr4|j|jjdz|jzdk4n#tt f$r t dwxYw|jS)Nrr)r!r1rFrrrrrr(s r"rz"StreamFrameIteratorSliced.__next__s *?)A-;q@@33555?)A-;q@@'" * * *T ) *##%%%s AAA,cZtd|jjrrr(s r"r)z!StreamFrameIteratorSliced.__len__rr$c td)Nz)Sliced iterator does not support indexing)rrns r"r^z%StreamFrameIteratorSliced.__getitem__sFGGGr$c|jS)aThe step size for sliced frame iteration. Returns the step interval used when iterating through frames in a streaming trajectory. For example, a step of 2 means every second frame is processed, while a step of 1 processes every frame. Returns ------- int Step size for iteration. Always a positive integer greater than 0. rcr(s r"rCzStreamFrameIteratorSliced.steps zr$) r5r6r7r8r#rNrr)r^r:rCrdres@r"rrs!!F & & &   HHH  X     r$r)5r8r[numpyr0rPrtypingrrrrrtimestepr r r r rrrrauxiliary.baserauxiliary.corerr auxiliaryrlib.utilrrrrrrr=rgrXr{ABCMetarrrarrsr|rrIrrrrr;r$r"rsb2ffN 33333333333333 &&&&&&&&&&&&......######BBBBBBBBBB""""""        :[[[[[+[[[|&&&&&(&&&:,,,,,,,,,^JJJJJVJJJZQQQQQ#+QQQ.f f f f f &Kf f f f RRRRRRRRRj11111$1114PLPLPLPLPL;PLPLPLPLfSSSSSKSSSl    % % % % %T % % %$"""""Fn"""",| | | | | z| | | ~ PPPPP 1PPPPPr$