/*
 * 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 descriptors.dox
 *
 * Created on: Oct 28, 2011
 *    Author: heber
 */

/** \page descriptors Descriptors
 *
 * Descriptors help you to select a specific subset of a given array of
 * elements. For the moment these elements are either instances of atom
 * or molecule that the \ref world offers.
 *
 * They mostly work as an argument to either obtain a specific iterator
 * over the elements (that silently skips all non-matching ones) or
 * a subset.
 *
 * Note that the following boolean operators on descriptors work:
 * - or
 * - and
 * - not
 *
 * Hence, these descriptors are very mighty. A typical use would be as follows:
 * \code
 * World::getInstance().getAllAtoms(AtomByType(1) && AtomByShape(Sphere(Vector(0,0,0), 2.)));
 * \endcode
 * which would return an AtomComposite of all hydrogen (Z=1) atoms within a
 * sphere of radius 2. centered at (0,0,0).
 *
 * Or you may obtain iterators over a selection and use them in a loop as this:
 * \code
 * World::MoleculeIterator iter = World::getInstance().getMoleculeIter(MoleculeByFormula(Formula("H2O")));
 * World::MoleculeIterator enditer = World::getInstance().moleculeEnd();
 * std::cout << "List of all water molecules:" << std::endl;
 * for (; iter != enditer; ++iter)
 *  std:cout << (*iter)->getId() << std::endl;
 * \endcode
 *
 * \note There is difference between Selection and Descriptor. A
 * Descriptor is just a predicate() that selects among a given list. The current
 * Selection (of atoms/molecules) is a Descriptor \a applied to a the total
 * list of all atoms/molecules. Hence, a selection refers to a subset where
 * the Descriptor is just the condition that selects such a subset.
 *
 * \subsection descriptors-atom Atom Descriptors
 *
 *  The following descriptors are present for atoms:
 *  - by id: AtomById()
 *  - of currently selected molecule(s): AtomsByMoleculeSelection()
 *  - of molecule: AtomOfMolecule()
 *  - currently selected atoms: AtomsBySelection()
 *  - within a Shape: AtomByShape()
 *  - of specific element: AtomByType()
 *  - within distance to: AtomsWithinDistanceOf() (uses LinkedCell_View)
 *
 * \subsection descriptors-molecule Molecule Descriptors
 *
 *  The following descriptors are present for molecules:
 *  - by formula: MoleculeByFormula()
 *  - by id: MoleculeById()
 *  - by name: MoleculeByName()
 *  - of currently selected atoms: MoleculesByAtomSelection()
 *  - by order of creation: MoleculeByOrder() (i.e. -1 is the last one, 1 is the
 *    first ever created, ...)
 *  - by pointer: MoleculeByPtr MoleculeByPtr()
 *  - currently selected molecules: MoleculesBySelection()
 *
 * \subsection descriptors-world Descriptors and the World
 *
 *  In the World we make heavy use of descriptors. However, the World is also
 *  responsibly of informing connected Observers about removal or insertion of
 *  atoms or molecules.
 *  That's why its containers are protectedly constructed as ObservedContainers.
 *  Whenever you walk through them with a normal iterator, afterwards an update()
 *  is initiated. Only if you use a const_interator, this is prevented. But this
 *  at the natural disadvantage that the reference may only be used in constant
 *  environment.
 *  Descriptors however may return non-const reference. And we rely heavily on
 *  these to cheaply give us the correct reference for a given id, element type,
 *  and so on. So how do we do this?
 *
 *  Some of the descriptors are friends of the World and may use its internal
 *  containers directly, see AtomSelectionDescriptor_impl. Thus it can quickly
 *  walk through the atoms and find the correct one without causing huge delays
 *  by unnecessarily calling forth an update().
 *
 *
 * \date 2012-01-06
 *
 */