# Miscellaneous operations

## Saving, loading, and copying objects

MMTK provides an easy way to store (almost) arbitrary objects in files and retrieve them later. All objects of interest to users can be stored, including chemical objects, collections, universes, normal modes, configurations, etc. It is also possible to store standard Python objects such as numbers, lists, dictionaries etc., as well as practically any user-defined objects. Storage is based on the standard Python module `pickle`.

Objects are saved with MMTK.save and restored with MMTK.load. If several objects are to be stored in a single file, use tuples: `save((object1, object2), filename)` and `object1, object2 = load(filename)` to retrieve the objects.

Note that storing an object in a file implies storing all objects referenced by it as well, such that the size of the file can become larger than expected. For example, a configuration object contains a reference to the universe for which it is defined. Therefore storing a configuration object means storing the whole universe as well. However, nothing is ever written twice to the same file. If you store a list or a tuple containing a universe and a configuration for it, the universe is written only once.

It should be noted that when saving an object, all objects that this object refers to are also saved in the same file (otherwise the restored object would be missing some references). In practice this means that saving any chemical object, even a single atom, involves saving the whole universe that this object is part of. However, when saving several objects in one file, objects referenced several times are saved only once.

Frequently it is also useful to copy an object, such as a molecule or a configuration. There are two functions (which are actually taken from the Python standard library module `copy`) for this purpose, which have a somewhat different behaviour for container-type objects (lists, dictionaries, collections etc.). `MMTK.copy(object)` returns a copy of the given object. For a container object, it returns a new container object which contains the same objects as the original one. If the intention is to get a container object which contains copies of the original contents, then `MMTK.deepcopy(object)` should be used. For objects that are not container-type objects, there is no difference between the two functions.

## Exporting to specific file formats and visualization

MMTK can write objects in specific file formats that can be used by other programs. Three file formats are supported: the PDB format, widely used in computational chemistry, the DCD format for trajectories, written by the programs CHARMM and X-Plor and read by many visualization programs, and the VRML format, understood by VRML browsers as a representation of a three-dimensional scene for visualization. MMTK also provides a more general interface that can generate graphics objects in any representation if a special module for that representation exists. In addition to facilitating the implementation of new graphics file formats, this approach also permits the addition of custom graphics elements (lines, arrows, spheres, etc.) to molecular representations.

### PDB, VRML, and DCD files

Any chemical object, collection, or universe can be written to a PDB or VRML file by calling the method `writeToFile`, defined in class MMTK.Collection.GroupOfAtoms. PDB files are read via the class MMTK.PDB.PDBConfiguration. DCD files can be read by a MMTK.DCD.DCDReader object. For writing DCD files, there is the function MMTK.DCD.writeDCDPDB, which also creates a compatible PDB file without which the DCD file could not be interpreted.

Special care must be taken to ensure a correct mapping of atom numbers when reading from a DCD file. In MMTK, each atom object has a unique identity and atom numbers, also used internally for efficiency, are not strictly necessary and are not used anywhere in MMTK's application programming interface. DCD file, however, simply list coordinates sorted by atom number. For interpreting DCD files, another file must be available which allows the identification of atoms from their number and vice versa; this can for example be a PDB file.

When reading DCD files, MMTK assumes that the atom order in the DCD file is identical to the internal atom numbering of the universe for which the DCD file is read. This assumption is in general valid only if the universe has been created from a PDB file that is compatible with the DCD file, without any additions or removals.

### Visualization and animation

The most common need for file export is visualization. All objects that can be visualized (chemical systems and subsets thereof, normal mode objects, trajectories) provide a method `view` which creates temporary export files, starts a visualization program, and deletes the temporary files. Depending on the object type there are various optional parameters.

MMTK also allows visualization of normal modes and trajectories using animation. Since not all visualization programs permit animation, and since there is no standard way to ask for it, animation is implemented only for the programs XMol and VMD. Animation is available for normal modes, trajectories, and arbitrary sequences of configurations (see function MMTK.Visualization.viewSequence).

For more specialized needs, MMTK permits the creation of graphical representations of most of its objects via general graphics modules that have to be provided externally. Suitable modules are provided in the package Scientific.Visualization and cover VRML (version 1), VRML2 (aka VRML97), and the molecular visualization program VMD. Modules for other representations (e.g. rendering programs) can be written easily; it is recommended to use the existing modules as an example. The generation of graphics objects is handled by the method `graphicsObjects`, defined in the class MMTK.Visualization.Viewable, which is a mix-in class that makes graphics objects generation available for all objects that define chemical systems or parts thereof, as well as for certain other objects that are viewable.

The explicit generation of graphics objects permits the mixture of different graphical representations for various parts of a system, as well as the combination of MMTK-generated graphics objects with arbitrary other graphics objects, such as lines, arrows, or spheres. All graphics objects are finally combined into a scene object (also defined in the various graphics modules) in order to be displayed. See also the visualization examples.

## Fields

For analyzing or visualizing atomic properties that change little over short distances, it is often convenient to represent these properties as functions of position instead of one value per atom. Functions of position are also known as fields, and mathematical techniques for the analysis of fields have proven useful in many branches of physics. Such a field can be obtained by averaging over the values corresponding to the atoms in a small region of space. MMTK provides classes for scalar and vector field in module MMTK.Field. See also the example Miscellaneous/vector_field.py.

## Charge fitting

A frequent problem in determining force field parameters is the determination of partial charges for the atoms of a molecule by fitting to the electrostatic potential around the molecule, which is obtained from quantum chemistry programs. Although this is essentially a straightforward linear least-squares problem, many procedures that are in common use do not use state-of-the-art techniques and may yield erroneous results. MMTK provides a charge fitting method that is numerically stable and allows the imposition of constraints on the charges. It is implemented in module MMTK.ChargeFit. See also the example Miscellaneous/charge_fit.py.