source: src/documentation/constructs/world.dox@ 732507

/*
 * 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.
 *
 * \subsection world-internals-notes Notes on internals of the World
 *
 * \paragraph world-internals-notes-idpool
 *
 * The World has an idpool to manage the ids of atoms and molecules. The IdPool
 * inherits policies, such that ids are given in a unique (uniqueId) or
 * continuous (continousId) fashion.
 * The id of an atom is the sole identifier for which we can guarantee
 * uniqueness. Due to undo and redo actions the memory address is not a good
 * identifier. This is however required for FormatParser's that need
 * to store their additionalAtomData at program exit and have to safely identify
 * the data with its atoms. This can only be accomplished via the id. Hence,
 * we use the unique policy there.
 * The id of a molecule however is more of a convenience, to distinguish it from
 * the currently present others. A molecule may change very often and it is also
 * a compound structure that may change slightly (when a new bond to another atom
 * occurs). Thus, the concept of the id as a unique identifier does not make
 * sense. Hence, we use the continuous policy here.
 *
 * Note that IdPool::reserveId() has to ascertain that we may sweep through ids
 * available to (undone) AtomRemoveAction or (redone) AtomAddAction in sublinear
 * time. For this to work we have a class IdPool that manages the ids and
 * defragments the pool from time to time by combining ranges of released ids.
 *
 * \date 2012-01-06
 *
 */