Changeset 750cff for src/documentation/constructs

Timestamp:

Oct 31, 2011, 5:13:52 PM (14 years ago)

Author:

Frederik Heber <heber@…>

Branches:

Action_Thermostats, Add_AtomRandomPerturbation, Add_FitFragmentPartialChargesAction, Add_RotateAroundBondAction, Add_SelectAtomByNameAction, Added_ParseSaveFragmentResults, AddingActions_SaveParseParticleParameters, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_ParticleName_to_Atom, Adding_StructOpt_integration_tests, AtomFragments, Automaking_mpqc_open, AutomationFragmentation_failures, Candidate_v1.5.4, Candidate_v1.6.0, Candidate_v1.6.1, Candidate_v1.7.0, ChangeBugEmailaddress, ChangingTestPorts, ChemicalSpaceEvaluator, CombiningParticlePotentialParsing, Combining_Subpackages, Debian_Package_split, Debian_package_split_molecuildergui_only, Disabling_MemDebug, Docu_Python_wait, EmpiricalPotential_contain_HomologyGraph, EmpiricalPotential_contain_HomologyGraph_documentation, Enable_parallel_make_install, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, FitPartialCharges_GlobalError, Fix_BoundInBox_CenterInBox_MoleculeActions, Fix_ChargeSampling_PBC, Fix_ChronosMutex, Fix_FitPartialCharges, Fix_FitPotential_needs_atomicnumbers, Fix_ForceAnnealing, Fix_IndependentFragmentGrids, Fix_ParseParticles, Fix_ParseParticles_split_forward_backward_Actions, Fix_PopActions, Fix_QtFragmentList_sorted_selection, Fix_Restrictedkeyset_FragmentMolecule, Fix_StatusMsg, Fix_StepWorldTime_single_argument, Fix_Verbose_Codepatterns, Fix_fitting_potentials, Fixes, ForceAnnealing_goodresults, ForceAnnealing_oldresults, ForceAnnealing_tocheck, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, FragmentAction_writes_AtomFragments, FragmentMolecule_checks_bonddegrees, GeometryObjects, Gui_Fixes, Gui_displays_atomic_force_velocity, ImplicitCharges, IndependentFragmentGrids, IndependentFragmentGrids_IndividualZeroInstances, IndependentFragmentGrids_IntegrationTest, IndependentFragmentGrids_Sole_NN_Calculation, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, JobMarket_unresolvable_hostname_fix, MoreRobust_FragmentAutomation, ODR_violation_mpqc_open, PartialCharges_OrthogonalSummation, PdbParser_setsAtomName, PythonUI_with_named_parameters, QtGui_reactivate_TimeChanged_changes, Recreated_GuiChecks, Rewrite_FitPartialCharges, RotateToPrincipalAxisSystem_UndoRedo, SaturateAtoms_findBestMatching, SaturateAtoms_singleDegree, StoppableMakroAction, Subpackage_CodePatterns, Subpackage_JobMarket, Subpackage_LinearAlgebra, Subpackage_levmar, Subpackage_mpqc_open, Subpackage_vmg, Switchable_LogView, ThirdParty_MPQC_rebuilt_buildsystem, TrajectoryDependenant_MaxOrder, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps, TremoloParser_setsAtomName, Ubuntu_1604_changes, stable

Children:

5982c5

Parents:

19bc74

Message:

HUGE: Update on documenation.

• a general skeleton of the documentation is now in place with all the major components of MoleCuilder explained to some extent.
• some information has been transfered from TRAC (e.g. install procecure) into this doxygen documentation where it is general and not specific to the situation at our institute.

Location:

src/documentation/constructs

Files:

• actions.dox (modified) (1 diff)
• atoms.dox (added)
• bondgraph.dox (modified) (1 diff)
• constructs.dox (modified) (2 diffs)
• descriptors.dox (modified) (1 diff)
• fragmentation.dox (modified) (1 diff)
• linearalgebra.dox (added)
• logger.dox (added)
• molecules.dox (added)
• observers_observables.dox (modified) (1 diff)
• parsers.dox (modified) (1 diff)
• randomnumbers.dox (modified) (1 diff)
• serialization.dox (modified) (1 diff)
• shapes.dox (modified) (1 diff)
• tesselation.dox (modified) (1 diff)
• world.dox (added)

src/documentation/constructs/actions.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page actions Actions
+ *
+ *  Actions are Command patterns (http://en.wikipedia.org/wiki/Command_pattern)
+ *  to allow for undoing and redoing. Each specific Action derives from this
+ *  class to implement a certain functionality. There is a lot of preprocessor
+ *  magic implemented for making this as easy as possible. In effect you only
+ *  have to create three files of which only one actually contains more than a
+ *  few lines, namely the code of the Action itself.
+ *
+ *  Each Action has thus three types of functionalty: do, undo, and redo.
+ *
+ *  The ActionRegistry contains a prototype of each Action under its token
+ *  such that an instance can be retrieved by knowing this token.
+ *
+ *  Each Action obtains its parameter from a central ValueStorage such that
+ *  they are independent of where the parameter originated from: a command line
+ *  parameter, a value entered in a graphical dialog or given via the keyboard
+ *  in a terminal. That's why each begins with a function call to
+ *  getParametersfromValueStorage() to fill its internal Action::params
+ *  structure.
+ *
+ *  Also there is a regression test (\ref regression-test) for each Action to
+ *  check that it always behaves the same no matter how much the code
+ *  implementing actually has changed.
+ *
+ * \section actions-add To add a new action ...
+ *
+ *  The following steps have to be done for adding a new action:
+ *  -# Create three new files .cpp, .def, and .hpp
+ *  -# Add the files to \b src/Actions/Makefile.am.
+ *  -# Add the name of the Action to \b src/Actions/GlobalListOfActions.hpp
+ *    such that the ActionRegistry knows about it and can instantiate a
+ *    prototype.
+ *
+ *
+ *  \date 2011-10-31
+ *
+ */

src/documentation/constructs/bondgraph.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page bondgraph BondGraph
+ *
+ * The BondGraph class contains the knowledge of when two atoms are bonded and
+ * when not. At this moment it either uses a sum of covalent bond radii or an
+ * externally given bond table that gives typical bond lengths per element.
+ *
+ * The BondGraph's main working horse is the BondGraph::CreateAdjacency()
+ * function. It is strongly connected to the following graph actions:
+ * - GraphCreateAdjacencyAction
+ * - GraphSubgraphDissectionAction
+ *
+ * Therein, the bond structure is recognized again from scratch or/and the
+ * molecules afterwards represent disconnected subgraphs.
+ *
+ * In terms of graph theory the bond graph is an undirected graph with the
+ * bond degree as its weight. Bonds are respresented by edges, the atoms
+ * represent nodes.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/constructs/constructs.dox

@@ -7 +7 @@
 
 /**
- * \file constructs
+ * \file constructs.dox
  *
  * Created on: Oct 11, 2011
@@ -14 +14 @@
 
 
-/*
- * \page constructs "List of various rigid constructs"
+/**
+ * \page constructs List of various rigid constructs
  *
  * The following constructs are present and should be known to you as an alphabetical list:
  *
- *  \li \subpage actions
- *  \li \subpage linearalgebra
- *  \li \subpage bondgraph
- *  \li \subpage descriptors
- *  \li \subpage fragmentation
- *  \li \subpage observers
- *  \li \subpage parsers
- *  \li \subpage randomnumbers
- *  \li \subpage serialization
- *  \li \subpage shapes
- *  \li \subpage tesselation
- *  \li \subpage world
+ *  \li \ref actions
+ *  \li \ref atom
+ *  \li \ref linearalgebra
+ *  \li \ref bondgraph
+ *  \li \ref descriptors
+ *  \li \ref fragmentation
+ *  \li \ref molecule
+ *  \li \ref observers
+ *  \li \ref parsers
+ *  \li \ref randomnumbers
+ *  \li \ref serialization
+ *  \li \ref shapes
+ *  \li \ref tesselation
+ *  \li \ref world
  *
  *  Note that the most important construct is the \subpage world "World" whose functions
  *  should absolutely be known.
  *
+ *
+ * \date 2011-10-31
+ *
  */

src/documentation/constructs/descriptors.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page descriptors Descriptors
+ *
+ * Descriptors help you to select a specific subset of a given array of
+ * elements. For the moment these elements are either instances of atom
+ * or molecule that the \ref world offers.
+ *
+ * They mostly work as an argument to either obtain a specific iterator
+ * over the elements (that silently skips all non-matching ones) or
+ * a subset.
+ *
+ * Note that the following boolean operators on descriptors work:
+ * - or
+ * - and
+ * - not
+ *
+ * Hence, these descriptors are very mighty. A typical use would be as follows:
+ * \code
+ * World::getInstance().getAllAtoms(AtomByType(1) && AtomByShape(Sphere(Vector(0,0,0), 2.)));
+ * \endcode
+ * which would return an AtomComposite of all hydrogen (Z=1) atoms within a
+ * sphere of radius 2. centered at (0,0,0).
+ *
+ * Or you may obtain iterators over a selection and use them in a loop as this:
+ * \code
+ * World::MoleculeIterator iter = World::getInstance().getMoleculeIter(MoleculeByFormula(Formula("H2O")));
+ * World::MoleculeIterator enditer = World::getInstance().moleculeEnd();
+ * std::cout << "List of all water molecules:" << std::endl;
+ * for (; iter != enditer; ++iter)
+ *  std:cout << (*iter)->getId() << std::endl;
+ * \endcode
+ *
+ * \note There is difference between Selection and Descriptor. A
+ * Descriptor is just a predicate() that selects among a given list. The current
+ * Selection (of atoms/molecules) is a Descriptor \a applied to a the total
+ * list of all atoms/molecules. Hence, a selection refers to a subset where
+ * the Descriptor is just the condition that selects such a subset.
+ *
+ * \subsection descriptors-atom Atom Descriptors
+ *
+ *  The following descriptors are present for atoms:
+ *  - by id: AtomById()
+ *  - of currently selected molecule(s): AtomsByMoleculeSelection()
+ *  - currently selected atoms: AtomsBySelection()
+ *  - within a Shape: AtomByShape()
+ *  - of specific element: AtomByType()
+ *
+ * \subsection descriptors-molecule Molecule Descriptors
+ *
+ *  The following descriptors are present for molecules:
+ *  - by formula: MoleculeByFormula()
+ *  - by id: MoleculeById()
+ *  - by name: MoleculeByName()
+ *  - of currently selected atoms: MoleculesByAtomSelection()
+ *  - by order of creation: MoleculeByOrder() (i.e. -1 is the last one, 1 is the
+ *    first ever created, ...)
+ *  - by pointer: MoleculeByPtr MoleculeByPtr()
+ *  - currently selected molecules: MoleculesBySelection()
+ *
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/constructs/fragmentation.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page fragmentation Fragmentation
+ *
+ * Fragmentation contains all routines that are required to split a given
+ * molecular system into fragments. This is part of the so-called BOSSANOVA
+ * (Bond Order diSSection in an ANOVA-like fashion) approach to get linear
+ * scaling complexity for ab-initio quantum chemistry methods.
+ *
+ * The class Fragmentation contains with Fragmentation::FragmentMolecule()
+ * the main routine that dissect a given system and stores the fragments
+ * as configuration files.
+ *
+ * After these have been treated with a supported ab-initio solver, the
+ * energies and forces can be put together via \b joiner to approximation
+ * to the total energy and forces of the whole molecular system. Later,
+ * \b analyzer additionally gives data on how good this approximation has
+ * worked out in plotable format.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/constructs/observers_observables.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page observers Observers and Observables
+ *
+ * The Observer/Observerable mechanism is crucial to let different and
+ * independent components know about changes among one another. E.g. when an
+ * the element of an atom changes, the GUI (\ref graphical) needs to know
+ * about this change to plot the atom with a different color or shape.
+ *
+ * The Observer/Observerable mechanism is basically just a call-back: A
+ * class announces itself as Observable with having a specific interface
+ * of functions. Observer may signOn() to this class and have a specific
+ * function (update()) be called whenever a change occurs in the Observable
+ * class.
+ *
+ * Note that additionally an Observable may have various \a channels and
+ * Observers may signOn() to just such a channel to get a very specific
+ * update. E.g. a LinkedCell class needs to know when the position of an
+ * atom changes but it does not need to know about changes of element or
+ * velocity, ... These updates are called \a Notifications.
+ *
+ * As an example:
+ * \code
+ * World::getInstance().signOn(this, World::getInstance().getChannel(World::AtomInserted));
+ * \endcode
+ * Here, in the constructor of GLWorldView the class signs on to atoms
+ * being inserted into the World such that it can add these onto the display
+ * as well. Notifications are received via recieveNotifications(), e.g.
+ * which you have to implement for an Observer class
+ * \code
+ *   switch (notification->getChannelNo()) {
+ *   case World::AtomInserted:
+ *   {
+ *     const atom *_atom = World::getInstance().lastChanged<atom>();
+ *     emit atomInserted(_atom);
+ *     break;
+ *   }
+ * \endcode
+ * Here, we just switch over all events that we process and care about (note
+ * that we only get called for those for which we have subscribed) and proceed.
+ *
+ * \note There is a complete logging mechanism available for this. However,
+ * it has to be compiled via a specific switch (\ref install). So, when
+ * you need to know why your function isn't notified, that's the way to
+ * find out.
+ *
+ * Be wary of where the update occurs: while the World tells you about new
+ * or destroyed atoms, only the atom itself tells you when its position has
+ * changed!
+ *
+ * \section observers-world Observers and the World
+ *
+ * The World, containing the arrays of all atoms and molecules, is a bit
+ * special with these observers. E.g. when you request a non-const array
+ * of atoms you receive an ObservedIterator. That is one where automatically
+ * it is assumed that you changed something and hence update() is called
+ * after you stepped over one of its elements.
+ *
+ * Thus, use const-iterators and arrays whenever possible, first to avoid
+ * this overhead, but second to avoid making pain-in-the-ass, hard-to-find
+ * mistakes.
+ *
+ * Also, the world stores specific information about what changed in the
+ * template function World::lastChanged() where it might contain reference
+ * to an atom that is about to be destroyed or just added.
+ *
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/constructs/parsers.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page parsers Format Parsers
+ *
+ *  Format Parsers load or save information about the World (i.e. all atoms,
+ *  contained bonds, ...) in a specific file format.
+ *
+ *  All parsers derive from FormatParser and all available instances of
+ *  FormatParser's are stored in a FormatParserStorage such that they can be
+ *  retrieved with simply knowing the associated token.
+ *
+ *  We have this storage as the FormatParser may also contain extra information
+ *  per atom (...AtomDataContainer or alikes) which should be copied when an
+ *  atom is copied. Hence, as soon as a FormatParser is accessed once it sits
+ *  in the Storage and accumulates all information. Therefore, every parser
+ *  instance is unique per type throughout the run of the program.
+ *
+ *  A specific parser can be obtained from the FormatParserStorage just by
+ *  knowing the correct keyword such as this:
+ *  \code
+ *  ParserTypes type = FormatParserStorage::getInstance().getTypeFromName("xyz");
+ *  FormatParserInterface &parser = FormatParserStorage::getInstance().get(type);
+ *  \endcode
+ *
+ *  Associated to the FormatParser's is also the ChangeTracker (\ref observers)
+ *  that observers the World and tells all parsers on program exit whether
+ *  to save or not (i.e. whether any changes occurred). FormatParser_common
+ *  makes sure that each FormatParser signUp()s to this ChangeTracker.
+ *
+ *  Important is also the concept of a Parameter here. A Parameter is a value
+ *  of a certain type with a given valid range or set of valid values. There
+ *  ContinuousValue and DiscreteValue template classes that are subsequently
+ *  joined with a name to give a ContinuousParameter and DiscreteParameter to
+ *  be stored via a unifying ParameterInterface into a ParameterStorage. Such
+ *  an instance each of the FormatParser's contains. Therein extra information
+ *  such as a basis set, unit length, energy cutoff or other parser-specific
+ *  parameters are stored.
+ *
+ *  Various actions (WorldInputAction, WorldOuputAction, AtomSaveSelectedAtomsAction,
+ *  MoleculeSaveSelectedAction) use the parser to load or store atoms or to
+ *  control the behavior of storage (ParserSetOutputFormatAction, ...)
+ *
+ * \section parsers-add To add a new parser ...
+ *
+ *  The following tasks are necessary:
+ *  -# think of unique brief name for your parser, e.g. "xyz" and add to
+ *  \b ParserTypes.def. This will inform FormatParserStorage of your new parser.
+ *  (Again there is some preprocessor magic for instanting all ...)
+ *  -# Implement a FormatParserTraits specialization with some common stuff to
+ *    your parsers
+ *  \code
+ *  template<>
+ *  struct FormatParserTrait<name>
+ *  {
+ *    //!> Name of the parser
+ *    static const std::string name;
+ *    //!> suffix of the files the parser understands to read and write
+ *    static const std::string suffix;
+ *    //!> ParserTypes enumeration for the parser
+ *    static const enum ParserTypes type;
+ *  };
+ *  \endcode
+ *  where \a name is the name unique name of your parser, e.g. \a xyz.
+ *  -# Create all these static variables with matching contents.
+ *  -# Implement a FormatParser specialization
+ *  \code
+ *  template <>
+ *  class FormatParser< name >  : virtual public FormatParserInterface, public FormatParser_common
+ *  {
+ *  ...
+ *  };
+ *  \endcode
+ *  where \a name is again the name of your parser. FormatParser_common
+ *  contains some functionality common to all Parsers where FormatParserInterface
+ *  is the interface where load() and save() are defined. This allows for storage
+ *  in FormatParserRegistry.
+ *  -# implement FormatParserInterface::load() and FormatParserInterface::save().
+ *  -# implement FormatParser_common::AtomInserted() and
+ *    FormatParser_common::AtomRemoved()
+ *
+ *
+ * \date 2011-10-31
+ */

src/documentation/constructs/randomnumbers.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page randomnumbers Random Number Generation
+ *
+ * There is a factory for random number generators present. This implementation
+ * has been necessary due to lack of a common interface on the side of the
+ * boost::random programmer. Hence, we added a RandomNumberInterface for both
+ * engine and distribution and a factory for both and finally the conglomerate
+ * for combining both into a single RandomNumberGenerator.
+ *
+ * Whereever random numbers should be picked with a varying distribution or
+ * even better a user-controlled one, this RandomNumberGenerator should be
+ * used, e.g. as this
+ * \code
+ * RandomNumberGenerator &random = RandomNumberGeneratorFactory::getInstance().makeRandomNumberGenerator();
+ * const double rng_min = random.min();
+ * const double rng_max = random.max();
+ * \endcode
+ * This returns a reference to a random number generator instance. And also we obtain
+ * its RandomNumberGenerator::min() and RandomNumberGenerator::max() values.
+ * Then, we may create random values as simple as this:
+ * \code
+ * double random_value = (random()/((rng_max-rng_min)/2.) - 1.);
+ * \endcode
+ * which creates a random value within [-1,1]. Note that random() here is
+ * RandomNumberGenerator::operator() and not some global function.
+ *
+ * \note Do not necessarily use the random number generation when just a uniform
+ * distribution is required. The implementation is especially designed to allow
+ * the user control over the random number distribution. E.g. when filling the void
+ * space in a simulation box with molecules he may choose a discrete distribution
+ * with a small number of values to have a few, but random orientations of the
+ * molecules (MoleculeFillVoidWithMoleculeAction()).
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/constructs/serialization.dox

@@ -14 +14 @@
  *    Author: heber
  */
+
+/** \page serialization Serialization
+ *
+ *  Serialization is a mighty concept. The is only possible within an object-
+ *  oriented framework. The member variables of a class make up its internal
+ *  state. By storing this state, creating another instance and restoring
+ *  the variables to this state, we may in essence clone the instance. However,
+ *  we obtain additional control as to the moment of restoration because the
+ *  internal state is stored temporarily. To allow for this storage all of
+ *  these variables have to be \e serialized.
+ *
+ *  Serialization refers to putting one after another into a writable form
+ *  (e.g. convert to string and write into a stringstream) and eventually
+ *  in reverse order to read them one by one from this writable form and
+ *  cast them back into their original type.
+ *
+ *  Here, this is done via boost::serialization.
+ *
+ *  \attention The serialization headers do not mingle well with \b MemDebug.hpp.
+ *  Hence, place them before MemDebug.hpp as they do funny stuff with the
+ *  new() operator.
+ *
+ *  Serialization is so powerful because the stored state can be stored to
+ *  disk, transfered to another thread or even to another computer. If received
+ *  by a compatible code, the instance is recreated and computation can be
+ *  continued elsewhere.
+ *
+ *  For the moment we use it for creating an undo state within the Action's.
+ *  I.e. we store the state of all instances that are modified by an Action's
+ *  doings and may in Action::performUndo() just re-create the unmodified
+ *  instance by loading them from the serializing archive.
+ *
+ *  \section serialization-add How to make your class serializable.
+ *
+ *  \subsection serialization-add-simple The simple case
+ *
+ *  All you need to do with your newly created class foo is this:
+ *  \code
+ *  class foo {
+ *  ...
+ *  private:
+ *    friend class boost::serialization::access;
+ *    template<class Archive>
+ *    void serialize(Archive & ar, const unsigned int version) const
+ *    {
+ *      ar & content;
+ *    }
+ *    ...
+ *    double content;
+ *  };
+ *  \endcode
+ *  This will implement a serialization function for both directions for the
+ *  member variable content. I.e. we may now store a class instance as this:
+ *  \code
+ *  #include <boost/archive/text_oarchive.hpp>
+ *  std::stringstream stream;
+ *  boost::archive::text_oarchive oa(stream);
+ *  oa << diagonal;
+ *  \endcode
+ *  This will store the state of the class in the stringstream \a stream.
+ *  Getting the instance back is then as easy as
+ *  \code
+ *  #include <boost/archive/text_iarchive.hpp>
+ *  boost::archive::text_iarchive ia(stream);
+ *  RealSpaceMatrix *newm;
+ *  ia >> newm;
+ *  \endcode
+ *
+ *  \subsection serialization-add-complicated The more complicated case
+ *
+ *  It gets trickier when load and store need to be done differently, e.h.
+ *  \code
+ *  class foo {
+ *  ...
+ *  private:
+ *    friend class boost::serialization::access;
+ *    // serialization
+ *    template<class Archive>
+ *    void save(Archive & ar, const unsigned int version) const
+ *    {
+ *      ar & content;
+ *    }
+ *    template<class Archive>
+ *    void load(Archive & ar, const unsigned int version)
+ *    {
+ *      ar & content;
+ *      createViews();
+ *    }
+ *    BOOST_SERIALIZATION_SPLIT_MEMBER()
+ *    ...
+ *  }
+ *  \endcode
+ *  Here, we split serialize() function into distinct load() and save() because
+ *  we have to call an additional function to fully re-store the instance, i.e.
+ *  it creates some internal reference arrays (Views) in a specific manner.
+ *
+ *  The serialize functions can also be added externally, i.e. outside of the
+ *  scope of the class, but can then access only public members (except we
+ *  again make it a friend).
+ *
+ *
+ * \date 2011-10-31
+ */

src/documentation/constructs/shapes.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page shapes Shapes
+ *
+ * Shapes are present for denoting a specific region of the simulation domain.
+ * There are three types present:
+ *  - Sphere
+ *  - Ellipsoid
+ *  - Cuboid
+ *
+ * Note that both may be modified (shrink/grow, rotate, morph) via an arbitrary
+ * matrix.
+ *
+ * The shapes are for the moment only used within \ref descriptors to specify
+ * a specific subset of atoms, here that reside in a certain region of the
+ * simulation domain.
+ *
+ * \todo There is a certain relation between Tesselation and Shape. Hence, later
+ * Tesselation shall itself be a Shape, i.e. that describes a certain region in
+ * space, here via a tesselated mesh.
+ *
+ * Again, Shapes can be joined via boolean operators:
+ * - add
+ * - or
+ * - not
+ *
+ * And thus are a very powerful concept.
+ *
+ * E.g. a shape can be used like this
+ * \code
+ * Cuboid(Vector(0,0,0), Vector(2,2,2)) && !Sphere(Vector(1,1,1), 1.)
+ * \endcode
+ * which would be match any object within the cuboid from (0,0,0) to (2,2,2)
+ * that is not in the unit sphere at (1,1,1).
+ *
+ *
+ * \date 2011-10-31
+ *
+ */

src/documentation/constructs/tesselation.dox

@@ -12 +12 @@
  *    Author: heber
  */
+
+/** \page tesselation Tesselation
+ *
+ * Tesselation is a first step towards recognizing molecular surfaces.
+ *
+ * Within the code it is used for calculating correlation functions with regard
+ * to such a surface.
+ *
+ * \section tesselation-procedure
+ *
+ * In the tesselation all atoms act as possible hindrance to a rolling sphere
+ * that moves in from infinity. whenever it rests uniquely on three distinct
+ * points (atoms) a triangle is created. The algorithm continues by flipping the
+ * sphere over one of the triangle's edges to eventually obtain a closed,
+ * tesselated surface of the molecule.
+ *
+ * \note This mesh is different to the usual sense of a molecular surface as
+ * atoms are directly located on it. Normally, one considers a so-called
+ * Van-der-Waals sphere around the atoms and tesselates over these. However,
+ * the mesh can easily be modified and even expanded to match the other
+ * (although the code for that is not yet fully implemented).
+ *
+ * \section tesselation-extension
+ *
+ * The main problem for extending the mesh to match with the normal sense is
+ * that triangles may suddenly intersect others when we have the case of a non-
+ * convex mesh (which is rather the normal case). And this has to be
+ * specifically treated. Also, it is not sure whether the procedure of
+ * expanding our current surface is optimal and one should not start on a
+ * different set of nodes created from virtual points resting on the
+ * van-der-Waals spheres.
+ *
+ * \date 2011-10-31
+ *
+ */