Changeset 750cff for src/documentation


Ignore:
Timestamp:
Oct 31, 2011, 5:13:52 PM (13 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, 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
Files:
13 added
20 edited

Legend:

Unmodified
Added
Removed

  • src/documentation/code.dox

    r19bc74 r750cff  
    1414
    1515/**
    16  * \page code "How to use the code"
     16 * \page code How to use the code
    1717 *
    18  * \li \subpage faq "Frequently Asked Questions"
    19  * \li \subpage constructs "List of various rigid constructs"
    20  * \li \subpage howto "Howtos for specific code constructs"
     18 * \li \ref faq
     19 * \li \ref constructs
     20 * \li \ref howto
     21 *
     22 *
     23 * \date 2011-10-31
    2124 *
    2225 */

  • src/documentation/constructs/actions.dox

    r19bc74 r750cff  
    1212 *    Author: heber
    1313 */
     14
     15/** \page actions Actions
     16 *
     17 *  Actions are Command patterns (http://en.wikipedia.org/wiki/Command_pattern)
     18 *  to allow for undoing and redoing. Each specific Action derives from this
     19 *  class to implement a certain functionality. There is a lot of preprocessor
     20 *  magic implemented for making this as easy as possible. In effect you only
     21 *  have to create three files of which only one actually contains more than a
     22 *  few lines, namely the code of the Action itself.
     23 *
     24 *  Each Action has thus three types of functionalty: do, undo, and redo.
     25 *
     26 *  The ActionRegistry contains a prototype of each Action under its token
     27 *  such that an instance can be retrieved by knowing this token.
     28 *
     29 *  Each Action obtains its parameter from a central ValueStorage such that
     30 *  they are independent of where the parameter originated from: a command line
     31 *  parameter, a value entered in a graphical dialog or given via the keyboard
     32 *  in a terminal. That's why each begins with a function call to
     33 *  getParametersfromValueStorage() to fill its internal Action::params
     34 *  structure.
     35 *
     36 *  Also there is a regression test (\ref regression-test) for each Action to
     37 *  check that it always behaves the same no matter how much the code
     38 *  implementing actually has changed.
     39 *
     40 * \section actions-add To add a new action ...
     41 *
     42 *  The following steps have to be done for adding a new action:
     43 *  -# Create three new files .cpp, .def, and .hpp
     44 *  -# Add the files to \b src/Actions/Makefile.am.
     45 *  -# Add the name of the Action to \b src/Actions/GlobalListOfActions.hpp
     46 *    such that the ActionRegistry knows about it and can instantiate a
     47 *    prototype.
     48 *
     49 *
     50 *  \date 2011-10-31
     51 *
     52 */

  • src/documentation/constructs/bondgraph.dox

    r19bc74 r750cff  
    1212 *    Author: heber
    1313 */
     14
     15/** \page bondgraph BondGraph
     16 *
     17 * The BondGraph class contains the knowledge of when two atoms are bonded and
     18 * when not. At this moment it either uses a sum of covalent bond radii or an
     19 * externally given bond table that gives typical bond lengths per element.
     20 *
     21 * The BondGraph's main working horse is the BondGraph::CreateAdjacency()
     22 * function. It is strongly connected to the following graph actions:
     23 * - GraphCreateAdjacencyAction
     24 * - GraphSubgraphDissectionAction
     25 *
     26 * Therein, the bond structure is recognized again from scratch or/and the
     27 * molecules afterwards represent disconnected subgraphs.
     28 *
     29 * In terms of graph theory the bond graph is an undirected graph with the
     30 * bond degree as its weight. Bonds are respresented by edges, the atoms
     31 * represent nodes.
     32 *
     33 *
     34 * \date 2011-10-31
     35 *
     36 */

  • src/documentation/constructs/constructs.dox

    r19bc74 r750cff  
    77
    88/**
    9  * \file constructs
     9 * \file constructs.dox
    1010 *
    1111 * Created on: Oct 11, 2011
    … …  
    1414
    1515
    16 /*
    17  * \page constructs "List of various rigid constructs"
     16/**
     17 * \page constructs List of various rigid constructs
    1818 *
    1919 * The following constructs are present and should be known to you as an alphabetical list:
    2020 *
    21  *  \li \subpage actions
    22  *  \li \subpage linearalgebra
    23  *  \li \subpage bondgraph
    24  *  \li \subpage descriptors
    25  *  \li \subpage fragmentation
    26  *  \li \subpage observers
    27  *  \li \subpage parsers
    28  *  \li \subpage randomnumbers
    29  *  \li \subpage serialization
    30  *  \li \subpage shapes
    31  *  \li \subpage tesselation
    32  *  \li \subpage world
     21 *  \li \ref actions
     22 *  \li \ref atom
     23 *  \li \ref linearalgebra
     24 *  \li \ref bondgraph
     25 *  \li \ref descriptors
     26 *  \li \ref fragmentation
     27 *  \li \ref molecule
     28 *  \li \ref observers
     29 *  \li \ref parsers
     30 *  \li \ref randomnumbers
     31 *  \li \ref serialization
     32 *  \li \ref shapes
     33 *  \li \ref tesselation
     34 *  \li \ref world
    3335 *
    3436 *  Note that the most important construct is the \subpage world "World" whose functions
    3537 *  should absolutely be known.
    3638 *
     39 *
     40 * \date 2011-10-31
     41 *
    3742 */

  • src/documentation/constructs/descriptors.dox

    r19bc74 r750cff  
    1212 *    Author: heber
    1313 */
     14
     15/** \page descriptors Descriptors
     16 *
     17 * Descriptors help you to select a specific subset of a given array of
     18 * elements. For the moment these elements are either instances of atom
     19 * or molecule that the \ref world offers.
     20 *
     21 * They mostly work as an argument to either obtain a specific iterator
     22 * over the elements (that silently skips all non-matching ones) or
     23 * a subset.
     24 *
     25 * Note that the following boolean operators on descriptors work:
     26 * - or
     27 * - and
     28 * - not
     29 *
     30 * Hence, these descriptors are very mighty. A typical use would be as follows:
     31 * \code
     32 * World::getInstance().getAllAtoms(AtomByType(1) && AtomByShape(Sphere(Vector(0,0,0), 2.)));
     33 * \endcode
     34 * which would return an AtomComposite of all hydrogen (Z=1) atoms within a
     35 * sphere of radius 2. centered at (0,0,0).
     36 *
     37 * Or you may obtain iterators over a selection and use them in a loop as this:
     38 * \code
     39 * World::MoleculeIterator iter = World::getInstance().getMoleculeIter(MoleculeByFormula(Formula("H2O")));
     40 * World::MoleculeIterator enditer = World::getInstance().moleculeEnd();
     41 * std::cout << "List of all water molecules:" << std::endl;
     42 * for (; iter != enditer; ++iter)
     43 *  std:cout << (*iter)->getId() << std::endl;
     44 * \endcode
     45 *
     46 * \note There is difference between Selection and Descriptor. A
     47 * Descriptor is just a predicate() that selects among a given list. The current
     48 * Selection (of atoms/molecules) is a Descriptor \a applied to a the total
     49 * list of all atoms/molecules. Hence, a selection refers to a subset where
     50 * the Descriptor is just the condition that selects such a subset.
     51 *
     52 * \subsection descriptors-atom Atom Descriptors
     53 *
     54 *  The following descriptors are present for atoms:
     55 *  - by id: AtomById()
     56 *  - of currently selected molecule(s): AtomsByMoleculeSelection()
     57 *  - currently selected atoms: AtomsBySelection()
     58 *  - within a Shape: AtomByShape()
     59 *  - of specific element: AtomByType()
     60 *
     61 * \subsection descriptors-molecule Molecule Descriptors
     62 *
     63 *  The following descriptors are present for molecules:
     64 *  - by formula: MoleculeByFormula()
     65 *  - by id: MoleculeById()
     66 *  - by name: MoleculeByName()
     67 *  - of currently selected atoms: MoleculesByAtomSelection()
     68 *  - by order of creation: MoleculeByOrder() (i.e. -1 is the last one, 1 is the
     69 *    first ever created, ...)
     70 *  - by pointer: MoleculeByPtr MoleculeByPtr()
     71 *  - currently selected molecules: MoleculesBySelection()
     72 *
     73 *
     74 * \date 2011-10-31
     75 *
     76 */

  • src/documentation/constructs/fragmentation.dox

    r19bc74 r750cff  
    1212 *    Author: heber
    1313 */
     14
     15/** \page fragmentation Fragmentation
     16 *
     17 * Fragmentation contains all routines that are required to split a given
     18 * molecular system into fragments. This is part of the so-called BOSSANOVA
     19 * (Bond Order diSSection in an ANOVA-like fashion) approach to get linear
     20 * scaling complexity for ab-initio quantum chemistry methods.
     21 *
     22 * The class Fragmentation contains with Fragmentation::FragmentMolecule()
     23 * the main routine that dissect a given system and stores the fragments
     24 * as configuration files.
     25 *
     26 * After these have been treated with a supported ab-initio solver, the
     27 * energies and forces can be put together via \b joiner to approximation
     28 * to the total energy and forces of the whole molecular system. Later,
     29 * \b analyzer additionally gives data on how good this approximation has
     30 * worked out in plotable format.
     31 *
     32 *
     33 * \date 2011-10-31
     34 *
     35 */

  • src/documentation/constructs/observers_observables.dox

    r19bc74 r750cff  
    1212 *    Author: heber
    1313 */
     14
     15/** \page observers Observers and Observables
     16 *
     17 * The Observer/Observerable mechanism is crucial to let different and
     18 * independent components know about changes among one another. E.g. when an
     19 * the element of an atom changes, the GUI (\ref graphical) needs to know
     20 * about this change to plot the atom with a different color or shape.
     21 *
     22 * The Observer/Observerable mechanism is basically just a call-back: A
     23 * class announces itself as Observable with having a specific interface
     24 * of functions. Observer may signOn() to this class and have a specific
     25 * function (update()) be called whenever a change occurs in the Observable
     26 * class.
     27 *
     28 * Note that additionally an Observable may have various \a channels and
     29 * Observers may signOn() to just such a channel to get a very specific
     30 * update. E.g. a LinkedCell class needs to know when the position of an
     31 * atom changes but it does not need to know about changes of element or
     32 * velocity, ... These updates are called \a Notifications.
     33 *
     34 * As an example:
     35 * \code
     36 * World::getInstance().signOn(this, World::getInstance().getChannel(World::AtomInserted));
     37 * \endcode
     38 * Here, in the constructor of GLWorldView the class signs on to atoms
     39 * being inserted into the World such that it can add these onto the display
     40 * as well. Notifications are received via recieveNotifications(), e.g.
     41 * which you have to implement for an Observer class
     42 * \code
     43 *   switch (notification->getChannelNo()) {
     44 *   case World::AtomInserted:
     45 *   {
     46 *     const atom *_atom = World::getInstance().lastChanged<atom>();
     47 *     emit atomInserted(_atom);
     48 *     break;
     49 *   }
     50 * \endcode
     51 * Here, we just switch over all events that we process and care about (note
     52 * that we only get called for those for which we have subscribed) and proceed.
     53 *
     54 * \note There is a complete logging mechanism available for this. However,
     55 * it has to be compiled via a specific switch (\ref install). So, when
     56 * you need to know why your function isn't notified, that's the way to
     57 * find out.
     58 *
     59 * Be wary of where the update occurs: while the World tells you about new
     60 * or destroyed atoms, only the atom itself tells you when its position has
     61 * changed!
     62 *
     63 * \section observers-world Observers and the World
     64 *
     65 * The World, containing the arrays of all atoms and molecules, is a bit
     66 * special with these observers. E.g. when you request a non-const array
     67 * of atoms you receive an ObservedIterator. That is one where automatically
     68 * it is assumed that you changed something and hence update() is called
     69 * after you stepped over one of its elements.
     70 *
     71 * Thus, use const-iterators and arrays whenever possible, first to avoid
     72 * this overhead, but second to avoid making pain-in-the-ass, hard-to-find
     73 * mistakes.
     74 *
     75 * Also, the world stores specific information about what changed in the
     76 * template function World::lastChanged() where it might contain reference
     77 * to an atom that is about to be destroyed or just added.
     78 *
     79 *
     80 * \date 2011-10-31
     81 *
     82 */

  • src/documentation/constructs/parsers.dox

    r19bc74 r750cff  
    1212 *    Author: heber
    1313 */
     14
     15/** \page parsers Format Parsers
     16 *
     17 *  Format Parsers load or save information about the World (i.e. all atoms,
     18 *  contained bonds, ...) in a specific file format.
     19 *
     20 *  All parsers derive from FormatParser and all available instances of
     21 *  FormatParser's are stored in a FormatParserStorage such that they can be
     22 *  retrieved with simply knowing the associated token.
     23 *
     24 *  We have this storage as the FormatParser may also contain extra information
     25 *  per atom (...AtomDataContainer or alikes) which should be copied when an
     26 *  atom is copied. Hence, as soon as a FormatParser is accessed once it sits
     27 *  in the Storage and accumulates all information. Therefore, every parser
     28 *  instance is unique per type throughout the run of the program.
     29 *
     30 *  A specific parser can be obtained from the FormatParserStorage just by
     31 *  knowing the correct keyword such as this:
     32 *  \code
     33 *  ParserTypes type = FormatParserStorage::getInstance().getTypeFromName("xyz");
     34 *  FormatParserInterface &parser = FormatParserStorage::getInstance().get(type);
     35 *  \endcode
     36 *
     37 *  Associated to the FormatParser's is also the ChangeTracker (\ref observers)
     38 *  that observers the World and tells all parsers on program exit whether
     39 *  to save or not (i.e. whether any changes occurred). FormatParser_common
     40 *  makes sure that each FormatParser signUp()s to this ChangeTracker.
     41 *
     42 *  Important is also the concept of a Parameter here. A Parameter is a value
     43 *  of a certain type with a given valid range or set of valid values. There
     44 *  ContinuousValue and DiscreteValue template classes that are subsequently
     45 *  joined with a name to give a ContinuousParameter and DiscreteParameter to
     46 *  be stored via a unifying ParameterInterface into a ParameterStorage. Such
     47 *  an instance each of the FormatParser's contains. Therein extra information
     48 *  such as a basis set, unit length, energy cutoff or other parser-specific
     49 *  parameters are stored.
     50 *
     51 *  Various actions (WorldInputAction, WorldOuputAction, AtomSaveSelectedAtomsAction,
     52 *  MoleculeSaveSelectedAction) use the parser to load or store atoms or to
     53 *  control the behavior of storage (ParserSetOutputFormatAction, ...)
     54 *
     55 * \section parsers-add To add a new parser ...
     56 *
     57 *  The following tasks are necessary:
     58 *  -# think of unique brief name for your parser, e.g. "xyz" and add to
     59 *  \b ParserTypes.def. This will inform FormatParserStorage of your new parser.
     60 *  (Again there is some preprocessor magic for instanting all ...)
     61 *  -# Implement a FormatParserTraits specialization with some common stuff to
     62 *    your parsers
     63 *  \code
     64 *  template<>
     65 *  struct FormatParserTrait<name>
     66 *  {
     67 *    //!> Name of the parser
     68 *    static const std::string name;
     69 *    //!> suffix of the files the parser understands to read and write
     70 *    static const std::string suffix;
     71 *    //!> ParserTypes enumeration for the parser
     72 *    static const enum ParserTypes type;
     73 *  };
     74 *  \endcode
     75 *  where \a name is the name unique name of your parser, e.g. \a xyz.
     76 *  -# Create all these static variables with matching contents.
     77 *  -# Implement a FormatParser specialization
     78 *  \code
     79 *  template <>
     80 *  class FormatParser< name >  : virtual public FormatParserInterface, public FormatParser_common
     81 *  {
     82 *  ...
     83 *  };
     84 *  \endcode
     85 *  where \a name is again the name of your parser. FormatParser_common
     86 *  contains some functionality common to all Parsers where FormatParserInterface
     87 *  is the interface where load() and save() are defined. This allows for storage
     88 *  in FormatParserRegistry.
     89 *  -# implement FormatParserInterface::load() and FormatParserInterface::save().
     90 *  -# implement FormatParser_common::AtomInserted() and
     91 *    FormatParser_common::AtomRemoved()
     92 *
     93 *
     94 * \date 2011-10-31
     95 */

  • src/documentation/constructs/randomnumbers.dox

    r19bc74 r750cff  
    1212 *    Author: heber
    1313 */
     14
     15/** \page randomnumbers Random Number Generation
     16 *
     17 * There is a factory for random number generators present. This implementation
     18 * has been necessary due to lack of a common interface on the side of the
     19 * boost::random programmer. Hence, we added a RandomNumberInterface for both
     20 * engine and distribution and a factory for both and finally the conglomerate
     21 * for combining both into a single RandomNumberGenerator.
     22 *
     23 * Whereever random numbers should be picked with a varying distribution or
     24 * even better a user-controlled one, this RandomNumberGenerator should be
     25 * used, e.g. as this
     26 * \code
     27 * RandomNumberGenerator &random = RandomNumberGeneratorFactory::getInstance().makeRandomNumberGenerator();
     28 * const double rng_min = random.min();
     29 * const double rng_max = random.max();
     30 * \endcode
     31 * This returns a reference to a random number generator instance. And also we obtain
     32 * its RandomNumberGenerator::min() and RandomNumberGenerator::max() values.
     33 * Then, we may create random values as simple as this:
     34 * \code
     35 * double random_value = (random()/((rng_max-rng_min)/2.) - 1.);
     36 * \endcode
     37 * which creates a random value within [-1,1]. Note that random() here is
     38 * RandomNumberGenerator::operator() and not some global function.
     39 *
     40 * \note Do not necessarily use the random number generation when just a uniform
     41 * distribution is required. The implementation is especially designed to allow
     42 * the user control over the random number distribution. E.g. when filling the void
     43 * space in a simulation box with molecules he may choose a discrete distribution
     44 * with a small number of values to have a few, but random orientations of the
     45 * molecules (MoleculeFillVoidWithMoleculeAction()).
     46 *
     47 * \date 2011-10-31
     48 *
     49 */

  • src/documentation/constructs/serialization.dox

    r19bc74 r750cff  
    1414 *    Author: heber
    1515 */
     16
     17/** \page serialization Serialization
     18 *
     19 *  Serialization is a mighty concept. The is only possible within an object-
     20 *  oriented framework. The member variables of a class make up its internal
     21 *  state. By storing this state, creating another instance and restoring
     22 *  the variables to this state, we may in essence clone the instance. However,
     23 *  we obtain additional control as to the moment of restoration because the
     24 *  internal state is stored temporarily. To allow for this storage all of
     25 *  these variables have to be \e serialized.
     26 *
     27 *  Serialization refers to putting one after another into a writable form
     28 *  (e.g. convert to string and write into a stringstream) and eventually
     29 *  in reverse order to read them one by one from this writable form and
     30 *  cast them back into their original type.
     31 *
     32 *  Here, this is done via boost::serialization.
     33 *
     34 *  \attention The serialization headers do not mingle well with \b MemDebug.hpp.
     35 *  Hence, place them before MemDebug.hpp as they do funny stuff with the
     36 *  new() operator.
     37 *
     38 *  Serialization is so powerful because the stored state can be stored to
     39 *  disk, transfered to another thread or even to another computer. If received
     40 *  by a compatible code, the instance is recreated and computation can be
     41 *  continued elsewhere.
     42 *
     43 *  For the moment we use it for creating an undo state within the Action's.
     44 *  I.e. we store the state of all instances that are modified by an Action's
     45 *  doings and may in Action::performUndo() just re-create the unmodified
     46 *  instance by loading them from the serializing archive.
     47 *
     48 *  \section serialization-add How to make your class serializable.
     49 *
     50 *  \subsection serialization-add-simple The simple case
     51 *
     52 *  All you need to do with your newly created class foo is this:
     53 *  \code
     54 *  class foo {
     55 *  ...
     56 *  private:
     57 *    friend class boost::serialization::access;
     58 *    template<class Archive>
     59 *    void serialize(Archive & ar, const unsigned int version) const
     60 *    {
     61 *      ar & content;
     62 *    }
     63 *    ...
     64 *    double content;
     65 *  };
     66 *  \endcode
     67 *  This will implement a serialization function for both directions for the
     68 *  member variable content. I.e. we may now store a class instance as this:
     69 *  \code
     70 *  #include <boost/archive/text_oarchive.hpp>
     71 *  std::stringstream stream;
     72 *  boost::archive::text_oarchive oa(stream);
     73 *  oa << diagonal;
     74 *  \endcode
     75 *  This will store the state of the class in the stringstream \a stream.
     76 *  Getting the instance back is then as easy as
     77 *  \code
     78 *  #include <boost/archive/text_iarchive.hpp>
     79 *  boost::archive::text_iarchive ia(stream);
     80 *  RealSpaceMatrix *newm;
     81 *  ia >> newm;
     82 *  \endcode
     83 *
     84 *  \subsection serialization-add-complicated The more complicated case
     85 *
     86 *  It gets trickier when load and store need to be done differently, e.h.
     87 *  \code
     88 *  class foo {
     89 *  ...
     90 *  private:
     91 *    friend class boost::serialization::access;
     92 *    // serialization
     93 *    template<class Archive>
     94 *    void save(Archive & ar, const unsigned int version) const
     95 *    {
     96 *      ar & content;
     97 *    }
     98 *    template<class Archive>
     99 *    void load(Archive & ar, const unsigned int version)
     100 *    {
     101 *      ar & content;
     102 *      createViews();
     103 *    }
     104 *    BOOST_SERIALIZATION_SPLIT_MEMBER()
     105 *    ...
     106 *  }
     107 *  \endcode
     108 *  Here, we split serialize() function into distinct load() and save() because
     109 *  we have to call an additional function to fully re-store the instance, i.e.
     110 *  it creates some internal reference arrays (Views) in a specific manner.
     111 *
     112 *  The serialize functions can also be added externally, i.e. outside of the
     113 *  scope of the class, but can then access only public members (except we
     114 *  again make it a friend).
     115 *
     116 *
     117 * \date 2011-10-31
     118 */

  • src/documentation/constructs/shapes.dox

    r19bc74 r750cff  
    1212 *    Author: heber
    1313 */
     14
     15/** \page shapes Shapes
     16 *
     17 * Shapes are present for denoting a specific region of the simulation domain.
     18 * There are three types present:
     19 *  - Sphere
     20 *  - Ellipsoid
     21 *  - Cuboid
     22 *
     23 * Note that both may be modified (shrink/grow, rotate, morph) via an arbitrary
     24 * matrix.
     25 *
     26 * The shapes are for the moment only used within \ref descriptors to specify
     27 * a specific subset of atoms, here that reside in a certain region of the
     28 * simulation domain.
     29 *
     30 * \todo There is a certain relation between Tesselation and Shape. Hence, later
     31 * Tesselation shall itself be a Shape, i.e. that describes a certain region in
     32 * space, here via a tesselated mesh.
     33 *
     34 * Again, Shapes can be joined via boolean operators:
     35 * - add
     36 * - or
     37 * - not
     38 *
     39 * And thus are a very powerful concept.
     40 *
     41 * E.g. a shape can be used like this
     42 * \code
     43 * Cuboid(Vector(0,0,0), Vector(2,2,2)) && !Sphere(Vector(1,1,1), 1.)
     44 * \endcode
     45 * which would be match any object within the cuboid from (0,0,0) to (2,2,2)
     46 * that is not in the unit sphere at (1,1,1).
     47 *
     48 *
     49 * \date 2011-10-31
     50 *
     51 */

  • src/documentation/constructs/tesselation.dox

    r19bc74 r750cff  
    1212 *    Author: heber
    1313 */
     14
     15/** \page tesselation Tesselation
     16 *
     17 * Tesselation is a first step towards recognizing molecular surfaces.
     18 *
     19 * Within the code it is used for calculating correlation functions with regard
     20 * to such a surface.
     21 *
     22 * \section tesselation-procedure
     23 *
     24 * In the tesselation all atoms act as possible hindrance to a rolling sphere
     25 * that moves in from infinity. whenever it rests uniquely on three distinct
     26 * points (atoms) a triangle is created. The algorithm continues by flipping the
     27 * sphere over one of the triangle's edges to eventually obtain a closed,
     28 * tesselated surface of the molecule.
     29 *
     30 * \note This mesh is different to the usual sense of a molecular surface as
     31 * atoms are directly located on it. Normally, one considers a so-called
     32 * Van-der-Waals sphere around the atoms and tesselates over these. However,
     33 * the mesh can easily be modified and even expanded to match the other
     34 * (although the code for that is not yet fully implemented).
     35 *
     36 * \section tesselation-extension
     37 *
     38 * The main problem for extending the mesh to match with the normal sense is
     39 * that triangles may suddenly intersect others when we have the case of a non-
     40 * convex mesh (which is rather the normal case). And this has to be
     41 * specifically treated. Also, it is not sure whether the procedure of
     42 * expanding our current surface is optimal and one should not start on a
     43 * different set of nodes created from virtual points resting on the
     44 * van-der-Waals spheres.
     45 *
     46 * \date 2011-10-31
     47 *
     48 */

  • src/documentation/faq.dox

    r19bc74 r750cff  
    1616
    1717/**
    18  * \page faq "Frequently Asked Questions"
     18 * \page faq Frequently Asked Questions
    1919 *
    2020 *  TODO: Documentation - add FAQ
    2121 *
     22 *
     23 * \date 2011-10-31
     24 *
    2225 */

  • src/documentation/install.dox

    r19bc74 r750cff  
    1313 */
    1414
    15 /* \page install Installation
     15/**
     16 *  \page install Installation
    1617 *
    17  *  Installation should without problems succeed as follows:
    18  *  -# ./configure (or: mkdir build;mkdir run;cd build; ../configure --bindir=../run)
    19  *  -# make
    20  *  -# make install
     18 * \section install-compiling Compiling the Code
     19 *
     20 * After you obtained the code, you do the following:
     21 *
     22 * \code
     23 * ./bootstrap
     24 * \endcode
     25 *
     26 * This creates the necessary autoconf and automake files.
     27 *
     28 * After this,
     29 *
     30 * \code
     31 * mkdir build
     32 * cd build
     33 * ../configure --prefix=`pwd`
     34 * \endcode
     35 *
     36 * which will run the configure script that checks whether you have a current
     37 * version of the following required packages
     38 *
     39 * -# GNU Scientific Library (specify via LDFLAGS, ...)
     40 * -# Qt4 framework (--with-Qt=<dir> or --with-Qt-include-dir, --with-Qt-bin-dir,
     41 *  --with-Qt-lib-dir and --with-Qt-lib)
     42 * -# Boost library 1.40 or newer with program_options and threads (--with-boost=<dir>)
     43 * -# CPPUnit framework (--with-cppunit-prefix=<dir>)
     44 * -# CodePatterns (--with-codepatterns=<dir>)
     45 *
     46 * \a --prefix is the argument to tell configure where all program code should go
     47 * to (pwd is the unix command for the current working directory). There are
     48 * others, see
     49 *
     50 * \code
     51 * ../configure --help
     52 * \endcode
     53 *
     54 * and some enable/disable switches you should check out:
     55 *
     56 * - \a --enable-ecut - says that the TestRunner, comprising all unit tests in one
     57 *  exectuable, shall make use of the Eclipse CppUnitTest (ECUT). If this is
     58 *  started within eclipse with this plugin installed, a shiny interface will tell
     59 *  you what failed and what not.
     60 * - \a --enable-debug - activates many internal asserts, memory debugger and more
     61 *  (makes code a lot slower but gives information in case something fails)
     62 *
     63 * \note A note about configure: If one library is found only under some specific path, you
     64 * can add CFLAGS, CPPFLAGS, LDFLAGS, ... to the configure call, like this
     65 * \code
     66 * ../configure --prefix=`pwd` --enable-hydrogen CFLAGS="-Wall -g3" CXXFLAGS="-Wall -g3"
     67 * \endcode
     68 * which enables all compiler warnings and full debugging of the code without any
     69 * optimization. configure saves these variables, too, such that when it is called
     70 * to re-configure it will still make use of them from its cache file.
     71 *
     72 * There are several flags that change the way molecuilder is compiled and probably
     73 * make it run faster, more unsafe, ...
     74 * -# \a -DLOG_OBSERVER,  What the Observers do is logged, the log is printed on exit
     75 * -# \a -DNO_MEMDEBUG,   MemDebug (memory debugger) is disabled
     76 * -# \a -DNO_CACHING,  Cachable are short-wired, i.e. always recalculate, this slows
     77 *  down the code a lot
     78 * -# \a -DNDEBUG,  include NO_MEMDEBUG, also ASSERTs are not checked, this speeds up
     79 *  the code by a factor of 5
     80 *
     81 * \section install-install Installing
     82 *
     83 * Now, we are ready to compile and install.
     84 *
     85 * \code
     86 * make
     87 * make install
     88 * \endcode
     89 *
     90 * \attention If you have a multi-core system, it is highly recommended to use the
     91 * \a -j option of make to allow for multiple threads to work on compiling or
     92 * checking the codfe simultaneously.
     93 *
     94 * And if everything went well, you should launch the unit tests and the testsuite
     95 * by (see section \ref tests on how to launch the tests individually)
     96 *
     97 * \code
     98 * make check
     99 * \endcode
     100 *
     101 * If everything is OK, you have a working version of MoleCuilder in form of the
     102 * executables \b bin/molecuilder and \b bin/molecuildergui.
     103 *
     104 * If you have to delete all compiled stuff, enter
     105 *
     106 * \code
     107 * make clean
     108 * \endcode
     109 *
     110 * or
     111 *
     112 * \code
     113 * make distclean
     114 * \endcode
     115 *
     116 * which will also delete all autoconf stuff for configure.
     117 *
     118 * distclean is at times necessary when stuff does not compile and there's
     119 * seemingly no logic behind it, i.e. especially when paths of modules have
     120 * changed. To recover your configure options, either look at \b config.log in
     121 * the build directory or enter
     122 *
     123 * \code
     124 * ./config.status --version
     125 * \endcode
    21126 *
    22127 *  Further useful commands are
    23  *  -# make clean uninstall: deletes .o-files and removes executable from the given binary directory\n
    24  *  -# make doxygen-doc: Creates these html pages out of the documented source
    25  *  -# make check: Runs an extensive set of unit tests and a testsuite which also gives a good overview on the set of
    26  *                 functions.
     128 *  -# make clean uninstall: deletes .o-files and removes executable from the given
     129 *    binary directory
     130 *  -# make doc: Creates these html pages out of the documented source
     131 *  -# make check: Runs an extensive set of unit tests and a testsuite which also gives
     132 *    a good overview on the set of functions.
     133 *
     134 * \date 2011-10-31
    27135 */

  • src/documentation/launch.dox

    r19bc74 r750cff  
    1313 */
    1414
    15 /*
    16  * \subpage launch Running the code
     15/**
     16 * \page launch Running the code
    1717 *
    18  *  The program can be executed by running: ./molecuilder
     18 *  Before you have done
     19 *  \code
     20 *  make install
     21 *  \endcode
     22 *  The executables are in the \b src folder of your build directory. There are
     23 *  two variants:
     24 *  - molecuilder (contains command line and text interface)
     25 *  - molecuildergui (contains graphical user interface)
    1926 *
    20  *  MoleCuilder has three interfaces at your disposal:
    21  *  -# Textmenu: A simple interactive console-based menu, where awaits your choices and inputs in order to set atoms
    22  *               as you like
    23  *  -# CommandLineUI: Every command can also be chained up as a sequence of actions on the command line to be executed
    24  *               with any user interaction.
    25  *  -# GraphicalUI: A graphical user interface that also display the molecular structure being built and lots of other
    26  *               informations to ease the construction of bigger geometries.
     27 *  The programs can be executed by running:
     28 *  - Text menu: Launching molecuilder with no options always gives the text menu.
     29 *    \code ./molecuilder \endcode
     30 *  - Command line menu: Depends on what you want, but an exemplary call is
     31 *    \code ./molecuilder -i test.xyz -o tremolo xyz -v 3 --add-atom H --position "0,0,0"\endcode
     32 *  - Graphical menu
     33 *    \code ./molecuildergui \endcode
    2734 *
    28  *  The supported output formats right now are:
    29  *  -# mpqc: Configuration files of the Massively Parallel Quantum Chemistry package (Sandia labs)
    30  *  -# pcp: Configuration files of the Parallel Car-Parrinello program (Institute for Numerical Simulation)
    31  *  -# tremolo: Configuration files of TREMOLO (Institute for Numerical Simulation)
    32  *  -# xyz: the most basic format for the 3d arrangement of atoms consisting of a list of element and 3 coordinates.
     35 * The user interface are explained in greater detail in \ref userinterfaces.
    3336 *
    34  *  \section
     37 *
     38 * \date 2011-10-31
    3539 *
    3640 */

  • src/documentation/mainpage.dox

    r19bc74 r750cff  
    2222 */
    2323
    24 /*! \mainpage MoleCuilder - a molecular set builder
     24/** \mainpage MoleCuilder - a molecular set builder
    2525 *
    26  * This introductory shall briefly make acquainted with the program, helping in installing and a first run.
     26 * This is the main page of the Doxygen documentation of \e MoleCuilder. We give
     27 * a brief description what the program is intended to do and then branch via
     28 * the contents of this documentation into various topics.
    2729 *
    2830 * \section about About the Program
    2931 *
    30  *  MoleCuilder is a program, written entirely in C++, that enables the construction of a coordinate set for the
    31  *  atoms making up an molecule. It allows for both building of simple molecules by adding atom-wise giving bond
    32  *  angles and distances or absolute coordinates, but also using them as templates. Regions can be specified and
    33  *  ordered to be filled with a molecule in a certain manner. Greater conglomerations of molecules can be tesselated
    34  *  and recognized as a region themselves to be subsequently surrounded by other (surface solvated) molecules.
    35  *  In the end, MoleCuilder allows the construction of arbitrary nano structures, whether they be crystalline or
    36  *  amorphic in nature.
     32 *  MoleCuilder is a program, written entirely in C++, that enables the
     33 *  construction of a coordinate set for the atoms making up an molecule. It
     34 *  allows for both building of simple molecules by adding atom-wise giving bond
     35 *  angles and distances or absolute coordinates, but also using them as
     36 *  templates. Regions can be specified and ordered to be filled with a molecule
     37 *  in a certain manner. Greater conglomerations of molecules can be tesselated
     38 *  and recognized as a region themselves to be subsequently surrounded by other
     39 *  (surface solvated) molecules. In the end, MoleCuilder allows the construction
     40 *  of arbitrary nano structures, whether they be crystalline or amorphic in
     41 *  nature.
    3742 *
    38  *  For copyright see \subpage copyright.
     43 *  For copyright see \ref copyright.
    3944 *
    40  * \section Contents
     45 * \section idea The central idea behind the program
     46 *
     47 * What are the central ideas?
     48 *
     49 * - Testedness: See \ref tests-policy which is meant \e seriously. Nothing is
     50 *   worse than one version behaving different to the next with respect to
     51 *   output.
     52 * - Re-usability: Every piece of functionality should be easy to re-use at
     53 *   someplace else. Say no to specialized one-purpose scripts, say yes to
     54 *   a LEGO-like system of building your world.
     55 * - Extendability: It's easy to add a new piece to the code. And it is even
     56 *   more so, if you have read this documentation and know what's all already
     57 *   in place.
     58 * - Userfriendliness: Every Action can be undone, every Action gives lots
     59 *   of output (if desired) to tell you what's going on. It's easy to save
     60 *   files in between. There are also three kinds of GUIs, each of which
     61 *   have the same functionality.
     62 *
     63 * \section contents Contents
    4164 *
    4265 * This manual is divided into the following sections:
    43  * \li \subpage install "Installation Instructions"
    44  * \li \subpage test "Automated testing"
    45  * \li \subpage launch "Launching the Code"
    46  * \li \subpage code "How to the use and extend the code"
     66 * \li \ref install
     67 * \li \ref tests
     68 * \li \ref launch
     69 * \li \ref debug
     70 * \li \ref code
     71 * \li \ref fileformats
     72 *
     73 * \date 2011-10-31
    4774 *
    4875 */

  • src/documentation/tests/code-tests.dox

    r19bc74 r750cff  
    2222 * -# Every .cpp files must include \b config.h and \b CodePatterns/MemDebug.hpp
    2323 * -# Every .hpp files must include \b config.h
     24 * -# Every .dox file contains a (correctly formatted: YYYY-MM-DD) date stamp.
    2425 *
    2526 * These make sure that the memory debugger is catching every movement on the
    26  * heap and that every module knows about the behavior controling defines that
    27  * are checked by autoconf and written to \b config.h in the build directory.
     27 * heap and that every module knows about the behavior controling \e #define's that
     28 * are checked by autoconf and written to \b config.h in the build directory. And
     29 * also that for every documentation file it is known when it was current.
    2830 *
    29  * \section Directory structure
     31 * \section codetest-structure Directory structure
    3032 *
    3133 * The code tests are contained in \b tests/CodeChecks. Therein are all test
    … …  
    3335 * Mostly, these look through files
    3436 *
    35  * \section Launching all tests
     37 * \section codetest-launch-all Launching all tests
    3638 *
    37  *  TODO: Documentation - explain how to launch all code tests.
     39 *  In order to launch all tests, simply do:
     40 *  -# Enter \b tests/CodeChecks in your build directory
     41 *  -# Run
     42 *    \code make check \endcode
     43 *    there
    3844 *
    39  * \section Launching some tests
     45 * \section codetest-launch-some Launching some tests
    4046 *
    41  *  TODO: Documentation - explain how to launch some code tests
     47 *  Launching a single or just some of the tests is only a little bit more
     48 *  complicated. Proceed as follows:
     49 *  -# Enter \b tests/CodeChecks in your build directory
     50 *  -# Run
     51 *  \code ../../../tests/CodeChecks/testsuite <option> AUTOTEST_PATH="<buildpath>/src" \endcode,
     52 *  where \a <option> is explained in the subsections below and \a <buildpath> is
     53 *  the build path (i.e. the variable \a AUTOTEST_PATH should contain the path to
     54 *  the executable).
    4255 *
    43  * \section Inspecting results
     56 *  \subsection regressiontest-launch-by-number ... by number
    4457 *
    45  *  TODO: Documentation - explain how to inspect code test results.
     58 *    Tests can be launched by specifying their test number, e.g. then \a <option>
     59 *    might be \a 1 or \a 1-2 or just nothing for all of them.
     60 *
     61 *  \subsection regressiontest-launch-by-keyword .. by keyword
     62 *
     63 *    Tests may as well be launched by some keywords, e.g. each code check has
     64 *    a specific keyword which is given via \b AT_KEYWORD directive of Autotest.
     65 *    I.e. we may launch the test on \b config.h presence via the \a <option>
     66 *    \a -k \a config_h. Also multiple keywords may be given.
     67 *
     68 * \section codetest-results Inspecting results
     69 *
     70 *  The testsuite can be launched with the additional option of \a -d which leaves the
     71 *  directory of the test present even though the test has passed for inspection.
     72 *
     73 *  If a test fails, in whatever way it was launched, will leave in the build directory
     74 *  a folder \b tests/CodeChecks/testsuite.dir/<nr> where \a <nr> is the number of the
     75 *  test (padded maybe with some zeros).
     76 *
     77 *  In the current state tests will fail because one file does not include \b
     78 *  config.h or \b MemDebug.hpp. Hence, check the testsuite's log to get the file
     79 *  name of the culprit at its very bottom.
     80 *
     81 * \section unittest-add Adding new tests
     82 *
     83 *  \attention Name convention of files, (no spaces, use underscore) e.g.
     84 *  \b testsuite-config_h.at
     85 *  - the test script file should be called as follows:
     86 *    -# testsuite-...
     87 *    -# followed by the construct that is tested.
     88 *
     89 *  In order to add a new test, you have to do the following:
     90 *  -# Add a new \b testsuite-....at script to the folder \b tests/CodeChecks
     91 *    (have a look at the present ones and see above for help on the commands
     92 *    recognized by Autotest. \e Mind \e giving it a suitable \e keyword!).
     93 *  -# Add the file to Makefile.am such that the testsuite is re-created when
     94 *    you change the test script.
     95 *  -# Add the file as an \e m4_include directive to testsuite.at.
     96 *
     97 *
     98 * \date 2011-10-31
    4699 *
    47100 */

  • src/documentation/tests/regression-tests.dox

    r19bc74 r750cff  
    2525 * regression tests.
    2626 *
    27  * \section Directory structure
     27 * \section regressiontest-structure Directory structure
    2828 *
    2929 * They are contained in the source folder \b tests/regression. There are
    … …  
    3636 *  named test script one directory level higher.
    3737 *
    38  *  \section Adding a new test
     38 *  \section regressiontest-launch-all Launching all tests
     39 *
     40 *  Launching all regression tests is as simple as:
     41 *  -# Enter the build directory
     42 *  -# There, enter \b tests/regression
     43 *  -# Run
     44 *  \code make check \endcode
     45 *  (at you liberty with option \a -j8 or similar for running the tests in
     46 *  parallel.
     47 *
     48 *  \section regressiontest-launch-some Launching a specific tests
     49 *
     50 *  Launching a single or just some of the tests is only a little bit more
     51 *  complicated. There are two options: either by the test number which however
     52 *  changes when new tests are added, and by keywords.
     53 *
     54 *  Then proceed as follows:
     55 *  -# Enter the build directory
     56 *  -# There, enter \b tests/regression
     57 *  -# Run
     58 *  \code ../../../tests/regression/testsuite <option> AUTOTEST_PATH="<buildpath>/src" \endcode,
     59 *  where \a <option> is explained in the subsections below and \a <buildpath>
     60 *  is the build path (i.e. the variable \a AUTOTEST_PATH should contain the
     61 *  path to the executable).
     62 *
     63 *  \subsection regressiontest-launch-by-number ... by number
     64 *
     65 *    Tests can be launched by specifying their test number, e.g. then \a <option>
     66 *    might be \a 283 or \a 283-284 or \a 283,285-286 or alike
     67 *
     68 *  \subsection regressiontest-launch-by-keyword .. by keyword
     69 *
     70 *    Tests may as well be launched by some keywords, e.g. each Action has a
     71 *    specific token which is also one of its keyword (see above for the
     72 *    policy). I.e. we may launch the test on fill-void via the \a <option>
     73 *    \a -k \a fill-void. Also multiple keywords may be given.
     74 *
     75 * \section regressiontest-results Inspecting test results
     76 *
     77 *  The testsuite can be launched with the additional option of \a -d which
     78 *  leaves the directory of the test present even though the test has passed
     79 *  for inspection.
     80 *
     81 *  If a test fails, in whatever way it was launched, will leave in the build
     82 *  directory a folder \b tests/regression/testsuite.dir/<nr> where \a <nr> is
     83 *  the number of the test (padded maybe with some zeros).
     84 *
     85 * \section regressiontest-add Adding a new test
     86 *
     87 *  \attention Name convention of files and directories, e.g.
     88 *  \b tests/regression/Parser/Pdb with \b testsuite-parser-pdb-save.at
     89 *  - the test directory should either be called as the token of the Action it
     90 *    tests or a unique and brief description but with no spaces, no dashes,
     91 *    but CamelCase (i.e. Capitalize each new word)
     92 *  - the test script file should be called as follows:
     93 *    -# testsuite-...
     94 *    -# ...each directory (non-capital letters) with a dash...
     95 *    -# ..the name of the test directory...
     96 *    -# a further description of there are multiple test scripts in the
     97 *      test directory.
    3998 *
    4099 *  Adding a new regression tests consists of the following items:
    … …  
    51110 *  testsuite is automatically re-compiled when one of the test files has changed.
    52111 *
    53  *  \section Launching all tests
    54112 *
    55  *  Launching all regression tests is as simple as:
    56  *  -# Enter the build directory
    57  *  -# There, enter \b tests/regression
    58  *  -# Run
    59  *  \code make check \endcode
    60  *  (at you liberty with option \a -j8 or similar for running the tests in parallel.
    61  *
    62  *  \section Launching a specific tests
    63  *
    64  *  Launching a single or just some of the tests is only a little bit more complicated.
    65  *  There are two options: either by the test number which however changes when new
    66  *  tests are added, and by keywords.
    67  *
    68  *  Then proceed as follows:
    69  *  -# Enter the build directory
    70  *  -# There, enter \b tests/regression
    71  *  -# Run
    72  *  \code ../../../tests/regression/testsuite <option> AUTOTEST_PATH="<buildpath>/src" \endcode,
    73  *  where \a <option> is explained in the subsections below and \a <buildpath> is the build
    74  *  path (i.e. the variable \a AUTOTEST_PATH should contain the path to the executable).
    75  *
    76  *  \subsection ... by number
    77  *
    78  *    Tests can be launched by specifying their test number, e.g. then \a <option>
    79  *    might be \a 283 or \a 283-284 or \a 283,285-286 or alike
    80  *
    81  *  \subsection .. by keyword
    82  *
    83  *    Tests may as well be launched by some keywords, e.g. each Action has a specific
    84  *    token which is also one of its keyword (see above for the policy). I.e. we may
    85  *    launch the test on fill-void via the \a <option> \a -k \a fill-void. Also
    86  *    multiple keywords may be given.
    87  *
    88  * \section Inspecting test results
    89  *
    90  *  The testsuite can be launched with the additional option of \a -d which leaves the
    91  *  directory of the test present even though the test has passed for inspection.
    92  *
    93  *  If a test fails, in whatever way it was launched, will leave in the build directory
    94  *  a folder \b tests/regression/testsuite.dir/<nr> where \a <nr> is the number of the
    95  *  test (padded maybe with some zeros).
     113 * \date 2011-10-31
    96114 *
    97115 */

  • src/documentation/tests/tests.dox

    r19bc74 r750cff  
    2525 * testing. Tests are regarded here as a kind of contract. The code itself is
    2626 * just one hand in two hands shaking, the other hand is resembled by the tests
    27  * that checks whether the code does exactly what it's supposed to do. Without
    28  * testing a larger project is impossible because it cannot evolve. With
    29  * increasing size, a project must be refactored
    30  * (http://en.wikipedia.org/wiki/Code_refactoring) such that new code does not
    31  * have to wiggle itself around the same old issues that are present from the
    32  * start. Before one starts refactoring, it must be assured by some means that
    33  * the code before and after behaves the same with respect to its intended
    34  * functionality. These means are the tests.
     27 * that check whether the code does exactly what it's supposed to do. Without
     28 * testing a larger project is impossible because it cannot evolve: The old
     29 * addage and compromises grow and grow. With increasing size, a project must be
     30 * refactored (http://en.wikipedia.org/wiki/Code_refactoring) such that new code
     31 * does not have to wiggle itself around the same old issues that are
     32 * inadvertently and unavoidably present from the start. Before one starts
     33 * refactoring, it must be assured by some means that the code before and after
     34 * behaves the same with respect to its intended functionality. These means are
     35 * the tests.
    3536 *
    36  * Unit tests (http://en.wikipedia.org/wiki/Unit_testing) tests single
    37  * components (e.g. classes), dependencies on other classes are often just
    38  * mimicked via so-called stubs. These test whether a component always behaves
    39  * as desired.
     37 * Unit tests (http://en.wikipedia.org/wiki/Unit_testing) check on single
     38 * components (e.g. classes), dependencies of the components on other classes
     39 * with the test frame are often just mimicked via so-called stubs (sort of
     40 * dummy components that don't calculate or do anything but return an expected
     41 * result suitable for this test only, see http://en.wikipedia.org/wiki/Test_stubs).
     42 * These test whether a component always behaves as desired.
    4043 *
    4144 * Regression test (http://en.wikipedia.org/wiki/Regression_testing) on the other
    … …  
    4548 * has not changed the outcome of older functions.
    4649 *
     50 * \section tests-launch-all Launching all tests
     51 *
    4752 * Note that all tests can be launched via
    4853 * \code make check \endcode
    4954 * in the top build directory.
    5055 *
    51  * \section Policy on launching tests
     56 * \section tests-policy Policy on launching tests
    5257 *
    5358 * Note that the above run of \e all \e tests \e should \e pass for each and
    … …  
    6065 * runs fine and produces a distributable archive.
    6166 *
     67 * \date 2011-10-31
     68 *
    6269 */

  • src/documentation/tests/unit-tests.dox

    r19bc74 r750cff  
    1818 * Unit tests are done via the CppUnit framework (http://cppunit.sourceforge.net/doc/1.8.0/).
    1919 *
    20  * \section Directory structure
     20 * \section unittest-structure Directory structure
    2121 *
    2222 *  Unit tests are always located in a subfolder \b unittests of the component
    … …  
    2424 *  resides in \b src/Parser/unittests.
    2525 *
    26  * \section Adding new tests
    27  *
    28  *  TODO: Documentation - explain how to add tests.
    29  *
    30  * \section Launching all tests
     26 * \section unittest-launch-all Launching all tests
    3127 *
    3228 *  All unit tests can be launched as follows:
    … …  
    3935 * This will run all present unit tests one after the other.
    4036 *
    41  * \section Launching some tests
     37 * \section unittest-launch-some Launching some tests
    4238 *
    4339 *  If only some of the tests should be checked, then they have to be launched by
    … …  
    5652 *  libraries, which have not been installed so far, are found.
    5753 *
    58  * \section Inspecting results
     54 * \section unittest-results Inspecting results
    5955 *
    6056 *  Results of the test are shown during run. An \a Ok(2) indicates that
    6157 *  two tests for the single launched testsuite passed.
    6258 *
     59 * \section unittest-add Adding new tests
     60 *
     61 *  \attention Name convention of files, (no spaces, use CamelCase) e.g.
     62 *  \b AnalysisBondsUnitTest
     63 *  - the unit test module should be called as follows:
     64 *    -# either the name of the component or the module
     65 *    -# followed by UnitTest.
     66 *  - the test class should be called as follows:
     67 *    -# the name of the class it tests
     68 *    -# followed by Test.
     69 *
     70 *  Adding a new test is as easy as this:
     71 *  -# Create a new module for declaration and definition of the unit test
     72 *    in a suitable \b unittests subfolder (see above on policy and naming).
     73 *    Check out one of the present unit tests and rename, but beware of
     74 *    copy&paste errors!
     75 *  -# Add the test to the \b Makefile.am contained in \b unittests.
     76 *
     77 *  If there is not yet a \b unittests folder:
     78 *  -# Create a new \b Makefile.am, check out one of the present ones to get
     79 *    an idea, below is a small list of contained elements. Note that the
     80 *    variable must begin with a unique name as all Makefile.am on unit tests
     81 *    are included into one big Makefile.am in \b src/unittests.
     82 *  -# Add your ...SOURCES and ...HEADERS to TESTSOURCES and TESTHEADERS.
     83 *  -# Add an include directive to \b src/unittests/Makefile.am of this
     84 *    newly created \b Makefile.am.
     85 *
     86 *  What's contained in the \b Makefile.am:
     87 *  -# ...SOURCES and ...HEADERS gathering all source and header files in this
     88 *    \b unittests folder (this is needed for the test program that contains
     89 *    all unit test in one executable).
     90 *  -# ...TESTS gathering all test programs in this \b unittests folder.
     91 *  -# ...TESTS is added to TESTS, check_PROGRAMS, noinst_PROGRAMS such that
     92 *    it is known that they are just tests, programs for \a make \a check and
     93 *    are not to be installed.
     94 *  -# ...LIBS gathers general libs that all of the tests in this \b unittests
     95 *    folder share.
     96 *  -# for each unit test:
     97 *    -# ...SOURCES gathers all source files that are required for the test.
     98 *    -# ...LDADD gathers all libs that are required for compilation.
     99 *
     100 *
     101 * \date 2011-10-31
     102 *
    63103 */
Note: See TracChangeset for help on using the changeset viewer.