7 Reading and writing dump records

Orbitals, density matrices, fock matrices, orbital energies, occupation numbers, and redundancy information for a given wavefunction are stored in a dump record. Reading and writing quantities from or to a dump record can be performed by the subroutines in file writedump.f. Before being able to access a dump record using these routines, it must either be created using subroutine reserve_dump or, if already existent, using subroutine read_info. Only a single dump record can be active (open) for writing at one time. The information for the open dump record is stored in common/dumpinfow. It is written back to the record by calling flush_dump. flush_dump should always be called as soon as a record has been written and is not needed any more.

It is often necessary, however, to read from a second dump record while a first one is already opened for read/write. Therefore, a second set of routines is provided in file readdump.f. These have similar functionality, but allow only reading. The information used by these routines is stored in common/dumpinfor. It is not required to open a dump record before performing these read-only operations. However, since the information from the dump record must be recovered each time a read-only routine is called, these are less efficient than the read/write routines in file writedump.f. Therefore, in cases where the same information is repeatedly read or written to the same dump record, as for instance during the scf iterations, the latter routines should be used. On the other hand, if one is interested just to read a particular quantity from a dump record, the routines in readdump.f are easier to use.

Each dump record contains a header containing information about the quantities stored in the record. This information is read into commons dumpinfow or dumpinfor when a record is opened. Each dump record is associated with a particular wavefunction type, which is stored in variable dump_method. The program version and creating date are also stored (variables dump_version and dump_date, respectively). The different quantities like orbitals, density matrices, orbital energies etc, are distinguished internally by keywords like ORBITALS, DENSITY, FOCK, EIG, OCC, GRP. These names are stored in array dump_name. A single record may contain several orbital or density matrices, for instance for different states in a state-averaged mcscf calculation, or canonical and localized orbitals in the scf case. Therefore, different types like NATORB, CANONICAL, or LOCAL can be associated with the name ORBITAL (array dump_type). The types are provided by the user via the calling routines, while the names cannot be modified. Furthermore, since there can be different sets of orbitals for a given type type, also the number of electrons, as well as the state, symmetry, and spin are stored for each quantity (dump_nelec, dump_state, dump_sym, dump_ms2). Instead of using these specifications, it is often more convenient to use a set number iset, which is associated to each quantity.