/*
 * 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()
 *  - currently selected atoms: AtomsBySelection()
 *  - within a Shape: AtomByShape()
 *  - of specific element: AtomByType()
 *
 * \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()
 *
 *
 * \date 2011-10-31
 *
 */