[750cff] | 1 | /*
|
---|
| 2 | * Project: MoleCuilder
|
---|
| 3 | * Description: creates and alters molecular systems
|
---|
| 4 | * Copyright (C) 2010 University of Bonn. All rights reserved.
|
---|
| 5 | * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
|
---|
| 6 | */
|
---|
| 7 |
|
---|
| 8 | /**
|
---|
| 9 | * \file world.dox
|
---|
| 10 | *
|
---|
| 11 | * Created on: Oct 31, 2011
|
---|
| 12 | * Author: heber
|
---|
| 13 | */
|
---|
| 14 |
|
---|
| 15 | /**
|
---|
| 16 | * \page world World
|
---|
| 17 | *
|
---|
| 18 | * The World is a singleton instance that can be obtained from everywhere.
|
---|
| 19 | * It stores information that globally need to be accessible but in a controlled
|
---|
| 20 | * manner. Therefore, the World is also an Observable that gives specific
|
---|
| 21 | * information when atoms or molecules have changed.
|
---|
| 22 | *
|
---|
| 23 | * The World is the one most important class of molecule. It contains the
|
---|
| 24 | * following important structures:
|
---|
| 25 | * - list of all atoms in the World, accessible via various functions
|
---|
| 26 | * - list of all molecules, likewise accessible via various functions
|
---|
| 27 | * - access to the Domain instance
|
---|
| 28 | * - access to the BondGraph instance
|
---|
| 29 | * - access to the config instance
|
---|
| 30 | * - access to the periodentafel instance
|
---|
| 31 | * - access to Thermostat instances
|
---|
| 32 | * - setting and getting of the ExitFlag (number returned on program exit)
|
---|
| 33 | * - access to WorldTime to setting the active time step
|
---|
| 34 | *
|
---|
| 35 | * I.e. whenever you need to do something with atoms, the World instance is
|
---|
| 36 | * involved.
|
---|
| 37 | *
|
---|
| 38 | * \section world-usage Howto use the World?
|
---|
| 39 | *
|
---|
| 40 | * Usage is a simple as:
|
---|
| 41 | * -# include the header \b World.hpp
|
---|
| 42 | * -# get an instance via
|
---|
| 43 | * \code
|
---|
| 44 | * World::getInstance()
|
---|
| 45 | * \endcode
|
---|
| 46 | *
|
---|
| 47 | * \section world-standard-procedures Standard Procedures
|
---|
| 48 | *
|
---|
| 49 | * In this section we explain various standard procedures wherein the World is
|
---|
| 50 | * involved.
|
---|
| 51 | *
|
---|
| 52 | * \note Accesssing molecules is very similar to accessing atoms, hence we only
|
---|
| 53 | * give the details for atoms here.
|
---|
| 54 | *
|
---|
| 55 | * \subsection world-standard-procedures-atom-const_iteration Iterating over all atoms
|
---|
| 56 | *
|
---|
| 57 | * When you want to iterate over all atoms, but only need const access, do this:
|
---|
| 58 | * \code
|
---|
| 59 | * for(World::internal_AtomIterator iter = World::getInstance().getAtomIter_internal();
|
---|
| 60 | * iter != World::getInstance().atomEnd_internal();
|
---|
| 61 | * ++iter) {
|
---|
| 62 | * ...access *iter ...
|
---|
| 63 | * }
|
---|
| 64 | * \endcode
|
---|
| 65 | * However, these internal routines are protected. Hence, not every class may access
|
---|
| 66 | * them. Another variant is therefor to obtain a copy array:
|
---|
| 67 | * \code
|
---|
| 68 | * const World::AtomComposite atoms = World::getInstance().getAllAtoms();
|
---|
| 69 | * for(World::AtomComposite::const_iterator iter = atoms.begin();
|
---|
| 70 | * iter != atoms.end();
|
---|
| 71 | * ++iter) {
|
---|
| 72 | * ...access *iter ...
|
---|
| 73 | * }
|
---|
| 74 | * \endcode
|
---|
| 75 | *
|
---|
| 76 | * \subsection world-standard-procedures-atom-iteration Iterating over all atoms
|
---|
| 77 | *
|
---|
| 78 | * When you want to iterate over all atoms, but only need const access, do this:
|
---|
| 79 | * \code
|
---|
| 80 | * for(World::AtomIterator iter = World::getInstance().getAtomIter();
|
---|
| 81 | * iter != World::getInstance().atomEnd();
|
---|
| 82 | * ++iter) {
|
---|
| 83 | * ...access *iter ...
|
---|
| 84 | * }
|
---|
| 85 | * \endcode
|
---|
| 86 | * However, there we obtain an observed iterator. I.e. accessing *iter always
|
---|
| 87 | * calls forth an OBSERVE mechanism. Another variant is therefore to obtain a copy
|
---|
| 88 | * array:
|
---|
| 89 | * \code
|
---|
| 90 | * World::AtomComposite atoms = World::getInstance().getAllAtoms();
|
---|
| 91 | * for(World::AtomComposite::iterator iter = atoms.begin();
|
---|
| 92 | * iter != atoms.end();
|
---|
| 93 | * ++iter) {
|
---|
| 94 | * ...access *iter ...
|
---|
| 95 | * }
|
---|
| 96 | * \endcode
|
---|
| 97 | *
|
---|
| 98 | * \subsection world-standard-procedures-atom-subset-iteration Iterating over subset of atoms
|
---|
| 99 | *
|
---|
| 100 | * Iterating over a subset involves giving a specific descriptor to either
|
---|
| 101 | * World::getAtomIter() or World::getAllAtoms() such as this:
|
---|
| 102 | * \code
|
---|
| 103 | * World::AtomIterator iter = World::getInstance().getAtomIter(AtomsBySelection());
|
---|
| 104 | * \endcode
|
---|
| 105 | * \code
|
---|
| 106 | * World::AtomComposite atoms = World::getInstance().getAllAtoms(AtomByType(1));
|
---|
| 107 | * \endcode
|
---|
| 108 | * respectively.
|
---|
| 109 | *
|
---|
| 110 | *
|
---|
| 111 | * \date 2011-10-31
|
---|
| 112 | *
|
---|
| 113 | */
|
---|