/*
 * Project: MoleCuilder
 * Description: creates and alters molecular systems
 * Copyright (C)  2010 University of Bonn. All rights reserved.
 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
 */

/**
 * \file molecules.dox
 *
 * Created on: Oct 31, 2011
 *    Author: heber
 */

/**
 * \page molecules Molecules
 *
 * Molecule is the next important structure to atom.
 *
 * Molecule are especially important for \ref fragmentation and lots of
 * their (old) code comes from this theme.
 *
 * Basically, a molecule is just a conglomerate of atoms whose nodes form a
 * connected subgraph of the entire molecular system.
 *
 * A molecule has its own internal array of atoms that may be traversed.
 * Similar concepts as with the World with regards to const and non-const
 * traversal, the former involving an Observer mechanism, come into play here
 * as well.
 *
 * \section molecules-atoms Atoms
 *
 * Atoms are added to the molecule via molecule::AddAtom() and removed via
 * molecule::RemoveAtom(). Therein, the atom receives a unique ParticleInfo::Nr
 * that is useful only within the molecule and is displayed in the atoms name,
 * i.e. atom names only vary within the molecule.
 *
 * The molecule only stores the atoms global id and uses a boost::transform_iterator
 * to map the ids to the true refs obtained from the World.
 *
 * \section molecules-formula Formula
 *
 * One important concept of molecules is the associated Formula. It, as well
 * as the AtomCount, are implemented as Cachables, i.e. they are aware of
 * changes to the contained atoms via the Observer mechanism but update
 * themselves only when requested.
 *
 * Formulas are very powerful because they can also be used as a Descriptor
 * (\ref descriptors) to access only a certain subsets of molecules, e.g.
 * "H2O" selects all water molecules.
 *
 * \section molecules-bondgraph Notes on the BondGraph
 *
 * Note that molecules are very volatile: Changing the bond graph also changes
 * most of the present molecules at this time as so far there is no update
 * mechanism. Hence, be aware of it.
 *
 *
 * \date 2011-10-31
 *
 */