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