source: src/documentation/constructs/world.dox@ 936a02

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

/**
 * \page world World
 *
 * The World is a singleton instance that can be obtained from everywhere.
 * It stores information that globally need to be accessible but in a controlled
 * manner. Therefore, the World is also an Observable that gives specific
 * information when atoms or molecules have changed.
 *
 * The World is the one most important class of molecule. It contains the
 * following important structures:
 * - list of all atoms in the World, accessible via various functions
 * - list of all molecules, likewise accessible via various functions
 * - access to the Domain instance
 * - access to the BondGraph instance
 * - access to the config instance
 * - access to the periodentafel instance
 * - access to Thermostat instances
 * - setting and getting of the ExitFlag (number returned on program exit)
 * - access to WorldTime to setting the active time step
 *
 * I.e. whenever you need to do something with atoms, the World instance is
 * involved.
 *
 * \section world-usage Howto use the World?
 *
 * Usage is a simple as:
 * -# include the header \b World.hpp
 * -# get an instance via
 * \code
 * World::getInstance()
 * \endcode
 *
 * \section world-standard-procedures Standard Procedures
 *
 * In this section we explain various standard procedures wherein the World is
 * involved.
 *
 * \note Accesssing molecules is very similar to accessing atoms, hence we only
 * give the details for atoms here.
 *
 * \subsection world-standard-procedures-atom-const_iteration Iterating over all atoms
 *
 * When you want to iterate over all atoms, but only need const access, do this:
 * \code
 * for(World::internal_AtomIterator iter = World::getInstance().getAtomIter_internal();
 *    iter != World::getInstance().atomEnd_internal();
 *    ++iter) {
 *   ...access *iter ...
 * }
 * \endcode
 * However, these internal routines are protected. Hence, not every class may access
 * them. Another variant is therefor to obtain a copy array:
 * \code
 * const World::AtomComposite atoms = World::getInstance().getAllAtoms();
 * for(World::AtomComposite::const_iterator iter = atoms.begin();
 *     iter != atoms.end();
 *     ++iter) {
 *   ...access *iter ...
 * }
 * \endcode
 *
 * \subsection world-standard-procedures-atom-iteration Iterating over all atoms
 *
 * When you want to iterate over all atoms, but only need const access, do this:
 * \code
 * for(World::AtomIterator iter = World::getInstance().getAtomIter();
 *    iter != World::getInstance().atomEnd();
 *    ++iter) {
 *   ...access *iter ...
 * }
 * \endcode
 * However, there we obtain an observed iterator. I.e. accessing *iter always
 * calls forth an OBSERVE mechanism. Another variant is therefore to obtain a copy
 * array:
 * \code
 * World::AtomComposite atoms = World::getInstance().getAllAtoms();
 * for(World::AtomComposite::iterator iter = atoms.begin();
 *     iter != atoms.end();
 *     ++iter) {
 *   ...access *iter ...
 * }
 * \endcode
 *
 * \subsection world-standard-procedures-atom-subset-iteration Iterating over subset of atoms
 *
 * Iterating over a subset involves giving a specific descriptor to either
 * World::getAtomIter() or World::getAllAtoms() such as this:
 * \code
 * World::AtomIterator iter = World::getInstance().getAtomIter(AtomsBySelection());
 * \endcode
 * \code
 * World::AtomComposite atoms = World::getInstance().getAllAtoms(AtomByType(1));
 * \endcode
 * respectively.
 *
 *
 * \date 2011-10-31
 *
 */