Atom Vectors (AV) can be saved to files and their contents can be restored from files. An AV file (AVF) may contain multiple records of any kind of AV but each file can only hold records of the same shape (number of atoms and dimensions). There are two methods and one function for file I/O. The writeavf() method operates in two modes: to create a new AVF or to append to an existing AVF. Method Name Argument Keywords Return Value writeavf "filename", "type", "note" None Keyword Argument Value Preset Value filename required name of the file the AV is to be written or appended to - type optional the type number that is to be written for this record 0 note optional a character string to be stored with the record - The file named in the filename argument is checked to see if it already exists. If it does, the file is opened and the header read to confirm it is a proper AVF. The number of atoms and the number of dimensions are read from the file and compared with the corresponding values for the target AV. They must match. There is no attempt to match Atom Maps. If there is no mismatch so far, the contents of the target is appended to the AVF. If the named file does not exist a new AVF is created. If the target AV is mapped, the atom map is encoded and saved to the new AVF. The contents of the target AV is then written to the new AVF. The value specified for type is recorded in the file. When the file is read, the type value can be used to ensure that the target is receiving content that is appropriate. The preset value of 0 forever marks the record that is written as untyped. The file can be annotated with a string specified with the note keyword. This string can be of any length but only the first 79 characters will be written to file. The following example makes use of an Atom Map which you can see here (will open in a new window). Top is the root of the map and Gd3 is a node in the map. We write out the "Gd3" slice of A to the file twice. In the first write, the file is created and the slice containing only zeroes is written. In the second write, the same slice, now containing numbers from the Uniform distribution is appended to the file. >>> from Yup.Taro.AtomVect import * >>> A = AtomVector( Top ) >>> A[Gd3].writeavf( 'gd3.av', note='First Record: all zeroes' ) >>> A.fill(sample='UNIFORM') >>> A[Gd3].writeavf( 'gd3.av', note='Second Record: samples from the Uniform distribution' ) >>> A.writeavf( 'gd3.av' ) Traceback (most recent call last): File "<stdin>", line 1, in ? AtomVect.error: (writeavf) incompatible numatom >>> Since filename is the keyword to the first argument, we can leave it out as we have done in the example. The third attempt at writing to the file fails because we try to write the entire AV to an AVF which is designed for a smaller number of atoms. The readavf() method fills the target AV with the contents of the specified record of the named file, provided the file has content that is compatible with the target AV and the specified record is of the required type. Method Name Argument Keywords Return Value readavf "filename", "type", "shownote", "record" None Keyword Argument Value Preset Value filename required name of the file to be read - type optional if not zero: the record to be read must be of this type 0 shownote optional if not zero: show the annotation for the record 1 record optional the record to be read, 0 for the last record 0 The file named as value to the filename keyword is opened for reading. It must exist, must be readable and must have a proper header that identifies it as an AVF. If the target is a mapped AV, and if the file has an encoded atom map, the two maps must be identical. Otherwise the file is not read any further. The record specified by this keyword is located. 0 (the preset value) is taken to be the last record in the AVF. If the record does not exist, the error is flagged. The requested record is read if the type specified matches the value recorded for the requested record. A type value of 0 either in the request or as recorded in the file will always result in a match. Thus, the preset value of 0 turns off the type matching requirement. The annotation for the requested record, see the AVF format, is printed on the standard error output if shownote is not set to 0. The preset value turns on this feature. The annotation is prefixed by the name of the file, the record number and the record type. The following example is a follow-on to the earlier example. In the first read, we do not specify a record number and so the last record is read. We know it is the last record because the annotation constains the note we entered earlier for the second (and last) record and we can see the content by printing the target AV. Note that the content was written from an Extract AV but we read it into a newly created Entire AV. In this case the target AV is anonymous and so there is no matching of Atom Maps. The only requirement is that the target AV has the same shape as that in the file. >>> B = AtomVector( numatom=Gd3.numatoms ) >>> B.readavf( 'gd3.av' ) gd3.av[0;0]: Second Record: samples from the Uniform distribution >>> B AtomVector[4:3] { -0.534288 -0.560472 -0.645924 0.696158 -0.250954 0.370647 0.306192 -0.834407 -0.0395215 0.197668 -0.213538 -0.570849 } >>> A AtomVector[16:3] { -0.0277413 0.648549 0.382733 -0.0690634 -0.89526 0.656545 -0.404462 0.547166 0.0104678 0.750603 0.832209 0.22074 0.44554 0.263894 -0.966918 -0.0707724 -0.531358 -0.292947 -0.534288 -0.560472 -0.645924 0.696158 -0.250954 0.370647 0.306192 -0.834407 -0.0395215 0.197668 -0.213538 -0.570849 -0.863094 -0.73986 -0.733085 -0.34904 -0.516831 -0.163793 0.221534 0.288736 0.599536 -0.653859 0.168188 0.0729698 -0.958373 0.747124 0.574755 -0.916929 -0.47496 0.181921 } >>> A[Gd3].readavf( 'gd3.av', record=1 ) gd3.av[1;0]: First Record: all zeroes >>> A AtomVector[16:3] { -0.0277413 0.648549 0.382733 -0.0690634 -0.89526 0.656545 -0.404462 0.547166 0.0104678 0.750603 0.832209 0.22074 0.44554 0.263894 -0.966918 -0.0707724 -0.531358 -0.292947 0 0 0 0 0 0 0 0 0 0 0 0 -0.863094 -0.73986 -0.733085 -0.34904 -0.516831 -0.163793 0.221534 0.288736 0.599536 -0.653859 0.168188 0.0729698 -0.958373 0.747124 0.574755 -0.916929 -0.47496 0.181921 } >>> >>> A[Gb2].readavf( 'gd3.av' ) Traceback (most recent call last): File "<stdin>", line 1, in ? AtomVect.error: (readavf) numatom mismatch >>> In the second part of the example, we asked for the first record to be read into the original slice. Again we see the annotation that we entered when we created that record. We print A before and after the read to show that readavf() affects only the target slice. Finally, we try to read a record written for the "Gd3" slice into another slice. This fails because the new target has a different shape. The MapAndVector() function (not a method!) reads the named file and if it is a good AVF, returns two objects: a new Atom Map and a new Atom Vector. Function Name Argument Keywords Return Values MapAndVector "filename", "libdir", "record", "type", "shownote" (Atom Map, Atom Vector) Keyword Argument Value Preset Value filename required name of the AVF - libdir required location of a constants directory - record optional the record to be read, 0 for the last 0 type optional the expected record type 0 shownote optional whether to show the annotation for the record 1 The file named in the filename argument must exist, must be readable and must be an AVF. If the AVF has an encoded atom map, a new atom map is created. It is OK for the AVF not to have an AVF. A new AV is then created. The AV is mapped if there had been an atom map or Anonymous if not. The specified record is then read into the AV provided the record exists and is of the requested type. The annotation is printed on the standard error output if shownote is non-zero. The value assigned to the libdir keyword specifies the location of a library of constants. This must contain the files created by the fpf program. The Atom Map that is created is associated with this library; atom classes and chemical states can be assigned only to the values defined in this library. The function returns a Python tuple containing the Atom Map (which may be None) and the Atom Vector. Intro New Print Compare Operators Data Methods Functions Subscript Files