3.2 Namespaces (Prev) 3.4 Simp namespace (Next)

The Util namespace contains a varity of general utility classes for scientific computation. Here we list only a few of the most important classes.

Space (Vectors and Tensors)

The dimensionality of space is defined by the int const Dimension = 3.

Cartesian vectors, such as atomic positions, are represented throughout Simpatico by Vector objects. The elements of a Vector can be manipulated exactly as if they were elements of a normal C array: If v is a three-dimensional Vector, v[0], v[1], and v[2] are its Cartesian components, which are all double precision floating point. A variety of standard mathematical operations (vector addition, dot products, etc.) are provided as methods or overloaded operators.

An IntVector is a Vector with integer (rather than floating point) elements. Most of the operations that are defined for a Vector are also defined for an IntVector.

A Tensor is an object with two Cartesian indices. The components of a Tensor T are accessed using the notation T(i, j), by overloading the () parentheses operator, where i and j are indices between 0 and Dimension - 1 (i.e., between 0 and 2).

Container templates

The src/util/containers directory provides a set of container class templates that are used throughout Simpatico. These containers are used in preference to either bare C arrays or to standard library containers, with few exceptions.

The most common containers (DArray, FArray, FSArray, DPArray, and FPArray) are one-dimensional array containers. All of these array containers overload the [] operator to return a specific element as a reference to an object, using the same syntax as a C array or the standard library std::vector container. The names of these array class templates include a set of prefixes. The prefixes D or F in the name an array container template indicate whether the underlying C-array is dynamically allocated (D) or fixed size (F). The prefix P indicates that array implementation merely stores pointers to objects, rather than actual objects. A prefix S, for arrays with no P prefix, indicates that an array has a logical size that is distinct from its capacity, and can grow by appending elements to its end.

More specialized containers include ArrayStack, ArraySet, and RingBuffer.

All array containers provide optional checking of array index bounds. This feature is activated at compile time (for debugging purposes or safety) if the preprocessor macro UTIL_DEBUG is defined, or may be turned off (for speed in production code) by not defining this macro.

The decision to use this set of "home made" containers in preference to heavy use of std::vector was based in part on a desire for two "safety" features that std::vector lacks. The first is ability to conveniently turn index bounds checking on or off for debugging, as described above. The second is a guarantee that the underlying C-array will not be resized and reallocated during use, which invalidates any pointers to elements of an array. Because a std::vector is designed to grow as needed as elements are added, the C-array underlying a std::vector can be automatically reallocated and copied to a new location in response to addition of new elements. This makes std::vector containers unsuitable for designs in which objects are allocated in arrays, but are accessed via pointers, which is a common pattern in Simpatico.

Parameter File IO

The src/util/containers directory contains a set of classes that are used to read and write parameter file blocks. Every class that needs to read data from the parameter file during initialization must be derived from the ParamComposite base class. This class defines a pure virtual method ParamComposite::readParam() method. Every subclass of ParamComposite must implement this method, which should read a parameter file block that contains the data required to initialize of that subclass. The ParamComposite class also provides a set of methods and method templates that are used to read and write individual parameters.

Random

A Random object represents a random number generator (RNG). The implementation uses a Mersenne-Twister RNG.