| 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 | * \subsection world-internals-notes Notes on internals of the World
|
|---|
| 111 | *
|
|---|
| 112 | * \paragraph world-internals-notes-idpool
|
|---|
| 113 | *
|
|---|
| 114 | * The World has an idpool to manage the ids of atoms and molecules, i.e. such
|
|---|
| 115 | * that they are:
|
|---|
| 116 | * -# unique
|
|---|
| 117 | * -# not loosely spread over the whole range of possible, but tightly packed
|
|---|
| 118 | *
|
|---|
| 119 | * For the latter to work we have a class IdPool that manages the ids and
|
|---|
| 120 | * defragments the pool from time to time by combining ranges of released ids.
|
|---|
| 121 | *
|
|---|
| 122 | * \date 2011-10-31
|
|---|
| 123 | *
|
|---|
| 124 | */
|
|---|
