Changeset caece4


Ignore:
Timestamp:
May 20, 2014, 9:14:56 AM (11 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:
6029a6
Parents:
74459a
git-author:
Frederik Heber <heber@…> (03/20/14 17:23:35)
git-committer:
Frederik Heber <heber@…> (05/20/14 09:14:56)
Message:

Enhanced documentation significantly.

  • went through all of the constructs and updated each.
  • enhanced documentation ofr Fragmentation::FragmentMolecule().
Location:
src
Files:
25 edited

Legend:

Unmodified
Added
Removed

  • src/Fragmentation/Fragmentation.cpp

    r74459a rcaece4  
    6666/** Constructor of class Fragmentation.
    6767 *
    68  * \param _mol molecule for internal use (looking up atoms)
     68 * \param _mol molecule which we currently fragment
    6969 * \param _FileChecker instance contains adjacency parsed from elsewhere
    7070 * \param _treatment whether to treat hydrogen special and saturate dangling bonds or not
    … …  
    8484
    8585/** Performs a many-body bond order analysis for a given bond order.
    86  * -# parses adjacency, keysets and orderatsite files
    87  * -# RootStack is created for every subgraph (here, later we implement the "update 10 sites with highest energ
    88 y contribution", and that's why this consciously not done in the following loop)
    89  * -# in a loop over all subgraphs
    90  *  -# calls FragmentBOSSANOVA with this RootStack and within the subgraph molecule structure
    91  *  -# creates molecule (fragment)s from the returned keysets (StoreFragmentFromKeySet)
    92  * -# combines the generated molecule lists from all subgraphs
    93  * -# saves to disk: fragment configs, adjacency, orderatsite, keyset files
    94  * Note that as we split "this" molecule up into a list of subgraphs, i.e. a MoleculeListClass, we have two sets
    95  * of vertex indices: Global always means the index in "this" molecule, whereas local refers to the molecule or
    96  * subgraph in the MoleculeListClass.
     86 *
     87 * \note during fragmentation we switch to so-called local ids, atomic ids
     88 * that are valid only for the specific molecule (representing a connected
     89 * subgraph of the molecular system).
     90 *
     91 * -# create the local id to global id mapping
     92 * -# parse the adjacency file and require the above mapping for translation
     93 * -# initialize a mask for the molecule's atoms, telling which atoms are
     94 *    treated and which atoms neglected during fragmentation
     95 * -# parse and orderatsite file and check whether there's something to do. This
     96      allows for iterative calls to fragmentation
     97 * -# fragments from the last fragmentation stored to file are converted into
     98 *    keysets (sets of atomic indices that describe one fragment)
     99 * -# in a loop as long as order at site is not correct yet
     100 *   -# prepare a stack containing the initial ids where the fragmentation or
     101 *      rather the graph algorithms start from
     102 *   -# call fragmentBOSSANOVA()
     103 * -# afterwards in case we don't saturate we remove single-atom fragments
     104 * -# translate the local ids of the keysets into global ids.
     105 * -# updated order at site file is written
     106 *
     107 * note that all created fragments or rather their describing key sets are
     108 * contained in the Graph Fragmentation::FragmentList.
     109 *
    97110 * \param atomids atomic ids (local to Fragmentation::mol) to fragment, used in AtomMask
    98111 * \param Order up to how many neighbouring bonds a fragment contains in BondOrderScheme::BottumUp scheme
    99112 * \param prefix prefix string for every fragment file name (may include path)
     113 * \param ParsedFragmentList all already created key sets
    100114 * \return 1 - continue, 2 - stop (no fragmentation occured)
    101115 */

  • src/documentation/code.dox

    r74459a rcaece4  
    3434 * Not everything is always documented, not everything is always up-to-date.
    3535 * Search the code or try to look at Actions that are similar to what you
    36  * intent. Try to understand how they do and whever your ideas really can't
    37  * be realized with the current capabilities of the code.
     36 * intent. Try to understand what they do, how they achieve it and whever your
     37 * ideas really can't be realized with the current capabilities of the code
     38 * already.
    3839 *
    3940 * If not, it gets more complicated because if one extends the code, one can
    … …  
    6667 * \code World::getInstance().getBondGraph() \endcode, because it's a unique
    6768 * instance) and how to use them because that's exactly what's being tested
    68  * there. Just browse through the various(?) test functions implemented in
     69 * there. Just browse through the various test functions implemented in
    6970 * each of the unit tests or rather the unit tests to the constructs you need.
    7071 *
    … …  
    107108 *
    108109 *
    109  * \date 2011-11-03
     110 * \date 2014-03-10
    110111 *
    111112 */

  • src/documentation/constructs/actions.dox

    r74459a rcaece4  
    33 * Description: creates and alters molecular systems
    44 * Copyright (C)  2010 University of Bonn. All rights reserved.
     5 * Copyright (C)  2014 Frederik Heber. All rights reserved.
    56 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
    67 */
    … …  
    2627 *  the Action does.
    2728 *
    28  *  Each Action has thus three types of functionality: do, undo, and redo.
     29 *  Each Action has thus three types of functionality: do, undo, and redo. And
     30 *  each action has a unique \a token: a name without white space that is
     31 *  descriptive.
    2932 *
    30  *  The ActionRegistry contains a prototype of each Action under its token
    31  *  such that an instance can be retrieved by knowing this token.
     33 *  The ActionRegistry contains a prototype of each Action under its token.
     34 *  If an Action is requested via its known token from the ActionQueue
     35 *  (that contains the ActionRegistry), this prototype is cloned and added to the
     36 *  queue.
    3237 *
    33  *  Each Action can contain multiple \ref parameters in its specific ActionParameters
    34  *  structure that represent the options. Executing call() first fills a dialog
    35  *  with \ref queries, one for each option. The UI then tries to obtain the
    36  *  values from the user. Depending on the type of the UI in use that could mean
    37  *  parsing stored command line parameters or displaying a real dialog box with widgets.
     38 *  Each Action can contain multiple \ref parameters in its specific
     39 *  ActionParameters structure that represent the options. Executing call() first
     40 *  fills a dialog with \ref queries, one for each option. The UI then tries to
     41 *  obtain the values from the user. Depending on the type of the UI in use that
     42 *  could mean parsing stored command line parameters or displaying a real dialog
     43 *  box with widgets.
    3844 *
    3945 *  Also there is a regression test (\ref regression-test) for each Action to
    4046 *  check that it always behaves the same no matter how much the code
    41  *  implementing actually has changed.
     47 *  implementing actually has changed. In most cases also for testing undo and
     48 *  redo.
    4249 *
    4350 * \section actions-add To add a new action ...
    … …  
    5360 *
    5461 * The central points of Actions is that they can be undone and redone. This
    55  * has to be implemented in two more functions beside the "do".
     62 * has to be implemented in two more functions beside the "do" in performCall().
    5663 *
    5764 * Note that undoing means to get everything back to its original state and by whatever
    … …  
    6168 * E.g. if your Action creates some new atoms, store their info as \ref AtomicInfo.
    6269 * Then, undo can simply delete the newly created atoms and redo can quickly re-
    63  * create them in the state they have been before.
     70 * create them in the state they have been before. Types required for storage are
     71 * contained in the Action's state and are filled during performCall(). Undo and
     72 * redo both get access to this state and may use the information as described.
    6473 *
    6574 * Have a look at \ref UndoRedoHelpers.hpp for some helper functions on this.
    … …  
    7281 *
    7382 *
    74  *  \date 2013-02-07
     83 *  \date 2014-03-10
    7584 *
    7685 */

  • src/documentation/constructs/atoms.dox

    r74459a rcaece4  
    33 * Description: creates and alters molecular systems
    44 * Copyright (C)  2010 University of Bonn. All rights reserved.
     5 * Copyright (C)  2014 Frederik Heber. All rights reserved.
    56 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
    67 */
    … …  
    6566 * -# CopyAtoms_Simple: Fills the internal set with true copies.
    6667 * -# CopyAtoms_withBonds: Additionally also adds bonds in between the copies
    67  *    as they exist in between the original atoms.
     68 *    when they exist in between the original atoms.
    6869 * -# CopyAtoms_SaturateDanglingBonds: additionally checks for cut bond that
    6970 *    would now become dangling bonds and inserts additional hydrogens for

  • src/documentation/constructs/bondgraph.dox

    r74459a rcaece4  
    1919 * externally given bond table that gives typical bond lengths per element.
    2020 *
    21  * The BondGraph's main working horse is the BondGraph::CreateAdjacency()
     21 * The BondGraph's main work horse is the BondGraph::CreateAdjacency()
    2222 * function. It is strongly connected to the following graph actions:
    2323 * - GraphCreateAdjacencyAction
    2424 * - GraphSubgraphDissectionAction
    2525 *
    26  * Therein, the bond structure is recognized again from scratch or/and the
     26 * Therein, the bond structure is recognized from scratch or/and the
    2727 * molecules afterwards represent disconnected subgraphs.
    2828 *

  • src/documentation/constructs/filling.dox

    r74459a rcaece4  
    1515/** \page filling Filling a domain
    1616 *
    17  * The idea behind filling a domain is to cluster it with a set of nodes,
    18  * i.e. a position in space in such a way that e.g. around node is sufficient
     17 * The idea behind filling a domain is to cluster it with a set of \b nodes,
     18 * i.e. a position in space in such a way that e.g. around a node is sufficient
    1919 * space to fill in the desired molecule. The logic of generating the nodes
    2020 * is responsible to create them in such a way as to allow for dense (or
    … …  
    2323 * filling the specific domain (sphere, ellipsoid, cuboid, pyramid, ...)
    2424 * in the best possible way.
    25  * Whether each node can be filled is then to be decided by a predicate.
     25 * Whether each node can be filled is then to be decided by a \b predicate.
    2626 *
    2727 * The filling routine uses then both to traverse the given nodes and
    … …  
    4040 *
    4141 * The node generation is basically just a point or mesh generator that fills
    42  * a specified region (best would be based on the class Shape) with a mesh in
    43  * such a way as to fulfill certain criteria:
     42 * a specified region based on the class Shape with a mesh in such a way as to
     43 * fulfill certain criteria:
    4444 *
    4545 *    -# equidistant
    … …  
    5555 * be composable via logic operators such as || (or), && (and), ! (not), ...
    5656 *
    57  * Note that each predicate receives on construction all the required
     57 * \note each predicate receives on construction all the required
    5858 * information, e.g. LinkedCell_View or Tesselation references or objects, ...
    5959 *
    … …  
    6565 *
    6666 * It rejects all nodes that evaluate to false, the list of valid points is
    67  * then traversed again and at each node a Cluster is created.
     67 * then traversed again and at each node a Cluster is created by the copy method.
    6868 *
    6969 * Note that we rely on \ref Cluster's, objects containing a set of atomicId_t
    70  * and that are inside a contained \ref Shape, to fill at each node. We use
     70 * and a \ref Shape, containing all of these atoms, to fill at each node. We use
    7171 * Cluster::clone() to create a copy that is subsequently placed at the desired
    7272 * node via an \ref Inserter functor. This allows to either simply shift the
    … …  
    7575 *
    7676 *
    77  * \date 2012-01-16
     77 * \date 2014-03-10
    7878 */

  • src/documentation/constructs/fragmentation.dox

    r74459a rcaece4  
    1818 * molecular system into fragments. This is part of the so-called BOSSANOVA
    1919 * (Bond Order diSSection in an ANOVA-like fashion) approach to get linear
    20  * scaling complexity for ab-initio quantum chemistry methods.
     20 * scaling complexity for ab-initio quantum chemistry methods. This method is
     21 * explained in the doctoral thesis of Frederik Heber.
    2122 *
     23 * \secton fragmentation-fragmentation Fragmenting molecules
     24 *
     25 * Everything starts in the Action FragmentationFragmentationAction. We require
     26 * a list of selected atoms. These are browsed and we note down all the associated
     27 * molecules (fragmentation is molecule-based). Subsequently, we make sure that
     28 * the bond degree has correct bond degress with respect to the selected set.
     29 * Then, Fragmentation is created for each molecule in the list.
    2230 * The class Fragmentation contains with Fragmentation::FragmentMolecule()
    23  * the main routine that dissect a given system and stores the fragments
    24  * as configuration files.
     31 * the main routine that dissect a given molecule
     32 * Afterwards, all KeySet's are obtained as a Graph from the Fragmentation
     33 * instance and combined into a single graph.
     34 * Via a depth first search analysis cycles are detected and added as
     35 * cycle fragments to this sets of KeySet.
     36 * Finally, all fragments are placed in the FragmentationResultContainer.
    2537 *
    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
     38 * If desired, \b inter-fragments, that fragments are combined if they are only
     39 * a certain distance apart from another and their summed fragmentation orders
     40 * do not exceed the specified value. This is required for local correlation
     41 * calculation. Otherwise correlation is only calculated (if supported by the
     42 * solver) within covalently connected fragments, i.e. we do not get any van
     43 * der Waals interactions.
     44 *
     45 * These fragments may be exported to file if output file types \sa fileformats
     46 * are given. There, the current FormatParserParameters are used. If none are
     47 * given, fragments remain in the FragmentationResultContainer.
     48 *
     49 * \secton fragmentation-automation Calculating fragments
     50 *
     51 * If then FragmentationFragmentationAutomationAction is used, these are converted
     52 * into MPQCJobs (and VMGJobs) that are passed on via a network connection to a
     53 * JobMarket's server as a FragmentJob.
     54 * Any idling connected clients will then process each one of the jobs until the
     55 * whole bundle is completed. The Action checks on the current tatus of the jobs
     56 * and requests any finished jobs (FragmentResult).
     57 * After all jobs' results have been received, they are stored in
     58 * FragmentationShortRangeResults and FragmentationLongrangeResults.
     59 * FragmentationAnalyseFragmentResultsAction will process both these results and
     60 * sum up the approximate energy and forces (where these are set as the atoms'
     61 * forces for the current time step).
     62 *
     63 * Alternatively to automation, where everything is done inside MoleCuilder, one
     64 * may also use the exported files to calculate an approximation. To this end,
     65 * the energies and forces are put together via \b joiner to approximation
    2866 * to the total energy and forces of the whole molecular system. Later,
    2967 * \b analyzer additionally gives data on how good this approximation has
    … …  
    3169 *
    3270 *
    33  * \date 2011-10-31
     71 * \date 2014-03-10
    3472 *
    3573 */

  • src/documentation/constructs/potentials.dox

    r74459a rcaece4  
    2020 * bond structure into connected subgraphs, calculating the energies of the
    2121 * fragments (ab-initio) and summing up to a good approximation of the total
    22  * energy of the whole system.
     22 * energy of the whole system, \sa fragmentation.
    2323 * Second, having calculated these energies, there quickly comes up the thought
    2424 * that one actually calculates quite similar systems all time and if one could
    … …  
    2929 * distances within a molecular fragment (i.e. the bond lengths) in order to
    3030 * give a value for the total energy without the need to solve a complex
    31  * ab-initio model.
     31 * ab-initio model (essentially, not solving the electronic Schrödinger equation
     32 * anymore).
    3233 *
    3334 * Empirical potentials have been thought of by fellows such as Lennard-Jones,
    … …  
    8586 *  h2o += 8,1,1;
    8687 *  // TrainingData needs so called Extractors to get the required distances
    87  *  // from the stored fragment. These are functions are bound.
     88 *  // from the stored fragment. These functions are bound via boost::bind.
    8889 *  TrainingData AngleData(
    8990 *      boost::bind(&Extractors::gatherDistancesFromFragment,

  • src/documentation/constructs/serialization.dox

    r74459a rcaece4  
    1717/** \page serialization Serialization
    1818 *
    19  *  Serialization is a mighty concept. The is only possible within an object-
     19 *  Serialization is a mighty concept. This is only possible within an object-
    2020 *  oriented framework. The member variables of a class make up its internal
    2121 *  state. By storing this state, creating another instance and restoring
    … …  
    2323 *  we obtain additional control as to the moment of restoration because the
    2424 *  internal state is stored temporarily. To allow for this storage all of
    25  *  these variables have to be \e serialized.
     25 *  these variables have to be \e serializable.
    2626 *
    2727 *  Serialization refers to putting one after another into a writable form
    … …  
    114114 *  again make it a friend).
    115115 *
     116 *  \subsection serialization-add-complicated The more complicated case
     117 *
     118 *  Noted the additional \a version parameter up there in the serialize functions'
     119 *  signature? When classes change, we might still want to be able to parse in
     120 *  older states. As as state is always written to a default constructed object.
     121 *  this is possible. You can check the version variable like this to make your
     122 *  function compatible with older functions.
     123 *
     124 *  \code
     125 *    void serialize(Archive & ar, const unsigned int version) const
     126 *    {
     127 *      ar & content;
     128 *      if (version > 0)
     129 *        are & newcontent;
     130 *    }
     131 *    ...
     132 *    double newcontent;
     133 *  };
     134 *  \endcode
     135 *
     136 *  The version itself is set as follows,
     137 *  \code
     138 *    BOOST_CLASS_VERSION(foo, 1)
     139 *  \endcode
     140 *  where you give the name of your class and the version.
     141 *
    116142 *  \subsection serialization-important notes Some important notes
    117143 *
    … …  
    119145 *  a stupid mistake is introduced that is trivial once understand but hard
    120146 *  to find otherwise. This is especially so because compiler errors with
    121  *  respect to the serialization part are always length (whole page) and
     147 *  respect to the serialization part are always lengthy (whole page) and
    122148 *  very hard to read:
    123149 *  \li Always obtain the same type from an archive that you put into it!
    … …  
    151177 *    boost::serialization::base_object<base type>(*this);
    152178 *    \endcode
     179 *  \li When you have code in header and implementation module, boost might get
     180      confused, use \code BOOST_CLASS_EXPORT_KEY(foo) \endcode and
     181          \code BOOST_CLASS_EXPORT_IMPLEMENT(foo) \encode for this.
     182 *  \li The only other issues encountered so far is that a class needs to get
     183 *    instantiated. Otherwise its (templated) serialization code is not present.
     184 *    There are ..._EXPORT keywords in boost::serialization for this. Similarly
     185 *    required when just the base class is created/instantiated but you also need
     186 *    derived classes.
     187 *  \li The boost::serialization documentation is in general quite helpful. Use
     188 *    above mentioned keywords to look for more information.
    153189 *
    154190 *
    155  * \date 2011-11-01
     191 * \date 2014-03-10
    156192 */

  • src/documentation/constructs/shaperegistry.dox

    r74459a rcaece4  
    22 * Project: MoleCuilder
    33 * Description: creates and alters molecular systems
    4  * Copyright (C)  2010 University of Bonn. All rights reserved.
     4 * Copyright (C)  2013 University of Bonn. All rights reserved.
    55 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
    66 */
    … …  
    4040 * registry.
    4141 *
    42  * It is planned to create a more specialized ShapeTesselation class. Basic
    43  * shapes (sphere, cube, etc.) would have predefined meshes. For combined
     42 * \todo It is planned to create a more specialized ShapeTesselation class.
     43 * Basic shapes (sphere, cube, etc.) would have predefined meshes. For combined
    4444 * shaped these basic meshes could then be intersected. That would be faster
    4545 * and allow correct rendering of topologically nontrivial shapes.

  • src/documentation/constructs/shapes.dox

    r74459a rcaece4  
    3333 * space, here via a tesselated mesh.
    3434 *
     35 * \section shapes-constructive-geometry Constructive Geometry
     36 *
    3537 * Again, Shapes can be joined via boolean operators:
    3638 * - add
    … …  
    3840 * - not
    3941 *
    40  * And thus are a very powerful concept.
     42 * And thus are a very powerful concept called constructive geometry.
    4143 *
    4244 * E.g. a shape can be used like this
    … …  
    4850 *
    4951 *
    50  * \date 2013-02-07
     52 * \date 2014-03-10
    5153 *
    5254 */

  • src/documentation/constructs/tesselation.dox

    r74459a rcaece4  
    2323 *
    2424 * 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
     25 * that moves in from infinity. Whenever it rests uniquely on three distinct
     26 * points (atoms) a triangle is created. The algorithm continues by pushing the
    2727 * sphere over one of the triangle's edges to eventually obtain a closed,
    28  * tesselated surface of the molecule.
     28 * tesselated surface of the whole molecule.
    2929 *
    3030 * \note This mesh is different to the usual sense of a molecular surface as
    3131 * 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).
     32 * Van-der-Waals sphere around the atoms and tesselates over these.
     33 * \todo However, the mesh can easily be modified and even expanded to match the
     34 * other (although the code for that is not yet fully implemented).
    3535 *
    3636 * \section tesselation-extension
    … …  
    4444 * van-der-Waals spheres.
    4545 *
    46  * \date 2011-10-31
     46 * Note that it is possible to select a number of atoms and create a bounding box
     47 * from a combination of spheres with van der Waals radii.
     48 *
     49 * \date 2014-03-10
    4750 *
    4851 */

  • src/documentation/constructs/validators.dox

    r74459a rcaece4  
    1717 *
    1818 * Validators define constraints for variables. A given variable can be
    19  * testet whether or not it fulfills the constraints by executing the
    20  * validator's isValid() function. Equivalently the operator::() can be used.
     19 * tested whether or not it fulfills the constraints by executing the
     20 * validator's isValid() function. Equivalently the Validator::operator()
     21 * can be used.
    2122 *
    2223 * Their main purpose is to constrain user input for \ref parameters in \ref actions.
    … …  
    3334 * \endcode
    3435 *
    35  * The type of the variale is static. The base class Validator has a template parameter
    36  * to define the type. Some derived validators don't have template parameters because
    37  * they are derived from a Validator<SomeFixedType>.
     36 * The type of the variable is static. The base class Validator has a template
     37 * parameter to define the type. Some derived validators don't have template
     38 * parameters because they are derived from a Validator<SomeFixedType>.
    3839 *
    3940 * \date 2013-01-28

  • src/documentation/copyright.dox

    r74459a rcaece4  
    3232 *
    3333 *
    34  *  Copyright (C) 2007-2011  University Bonn. All rights reserved.
     34 *  Copyright (C) 2007-2012  University Bonn. All rights reserved.
     35 *  Copyright (C) 2013-14  Frederik Heber. All rights reserved.
    3536 *
    36  * \date 2011-10-31
     37 * \date 2014-03-10
    3738 *
    3839 */

  • src/documentation/fileformats.dox

    r74459a rcaece4  
    2323 *  -# tremolo: Configuration files of TREMOLO (Institute for Numerical Simulation)
    2424 *  -# xyz: the most basic format for the 3d arrangement of atoms consisting of a list of element and 3 coordinates.
     25 *  -# xml: XML is the general format of the ScaFaCoS library containing particle
     26 *     positions and charges for long-range calculations.
    2527 *
    2628 *
    27  * \date 2011-10-31
     29 * \date 2014-03-10
    2830 *
    2931 */

  • src/documentation/future.dox

    r74459a rcaece4  
    2020 * Here is a list of what pieces of the code should be refactored to make them
    2121 * easier to use:
    22  * - Fragmentation and related classes: Just generate the keysets and have a
    23  *  pool of hydrogen atoms that are re-used when creating and writing
    24  *  fragments. Add and re-add messes up the Id's of the Atom's.
    2522 * - Tesselation and related classes: Especially, the removing and adding of
    2623 *  nodes is not fully (and correctly) implemented, see the regression tests
    … …  
    3330 * Here the list of what should be implemented to make the code more powerful
    3431 * and just makes sense given the current constructs.
    35  * - LinkedCell should be owned by the World and internally, such that one
    36  *  simply may access nearest neighbors (e.g. via Selection of a sphere) but in
    37  * \f$ {\cal O}(N) \f$ and not naively \f${\cal} (N^2)\f$.
    38  * - LinkedCell should be updateable. Thus it could listen to World's
    39  *  notifications when World::AtomInserted or World::AtomRemoved and update.
    40  *  Hence, it would always be up-to-date. Combined with the Cachable pattern in
    41  *  CodePatterns realizing lazy evaluation (http://en.wikipedia.org/wiki/Lazy_evaluation),
    42  *  i.e. when many updates have gathered, we rather re-create the linked cell
    43  *  structure, this can easily be made very convenient, fast, and powerful.
    4432 * - BondGraph should be updataeable. As above it should listen the Worlds'
    4533 *  notifications and so on (also Cachable ...)
    … …  
    5543 *  new Action but a token that just tells how to fill and a factory pattern
    5644 *  behind it that spits out the algorithm how to do it.
     45 * - molecule's should also contain the bounding box. This would allow to use
     46 *  them as crystallic unit cells.
    5747 *
    5848 *
    59  * \date 2011-11-03
     49 * \date 2014-03-10
    6050 *
    6151 */

  • src/documentation/install.dox

    r74459a rcaece4  
    191191 *  Massively Parallel Quantum Chemistry (http://www.mpqc.org/) is a Hartree-Fock
    192192 *  solver with emphasis on concurrency. We, however, require only the solver part.
    193  *  The code base has been adapted a bit to allow use within JobMarket.
    194  *  Also, it uses the ScaFaCoS package to calculate long-range forces.
     193 *  The code base has been adapted a bit to allow use as a JobMarket-compatible
     194 *  client. Also, it uses the ScaFaCoS package to calculate long-range forces.
    195195 *
    196196 * \section install-compiling Compiling the Code
    … …  
    333333 *  from a distributed archive. This is checked for each release version.
    334334 *
    335  * \date 2013-04-09
     335 * \date 2014-03-10
    336336 */

  • src/documentation/launch.dox

    r74459a rcaece4  
    2424 *  - molecuilder (contains command line and text interface)
    2525 *  - molecuildergui (contains graphical user interface)
     26 *  There is one more variant, a python module, residing in the libs folder:
     27 *  - pyMoleCuilder
    2628 *
    2729 *  The programs can be executed by running:
    … …  
    3234 *  - Graphical menu
    3335 *    \code ./molecuildergui \endcode
     36 *  - Python interface
     37 *    \code PYTHONPATH="<installpath>/libs" /usr/bin/python \endcode
     38 *    Then try,
     39 *    \code
     40 *      import pyMoleCuilder as mol
     41 *      help(mol)
     42 *    \endcode
    3443 *
    3544 * The user interface are explained in greater detail in \ref userinterfaces.
    3645 *
    3746 *
    38  * \date 2011-10-31
     47 * \date 2014-03-10
    3948 *
    4049 */

  • src/documentation/mainpage.dox

    r74459a rcaece4  
    3131 *
    3232 *  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
     33 *  construction of a coordinate set for the atoms making up a molecular system. It
    3434 *  allows for both building of simple molecules by adding atom-wise giving bond
    3535 *  angles and distances or absolute coordinates, but also using them as
    … …  
    3737 *  in a certain manner. Greater conglomerations of molecules can be tesselated
    3838 *  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.
     39 *  (surface solvated) molecules.
     40 *  Once initial configurations have been created, empirical potential functions
     41 *  can be fitted to ab-initio calculations -- calculated quickly via the BOSSANOVA
     42 *  scheme -- to enable subsequent (classical) molecular dynamics simulations.
    4243 *
    4344 *  For copyright see \ref copyright.
    … …  
    6061 *   files in between. There are also three kinds of GUIs, each of which
    6162 *   have the same functionality.
     63 * - Scriptability: Eventually, you want to create lots of configurations with
     64 *   only small differences. A session can be stored as either command-line or
     65 *   python script and extended to create all of the configurations in a straight-
     66 *   forward manner.
    6267 *
    6368 * \section contents Contents
    … …  
    7277 * \li \ref fileformats
    7378 *
    74  * \date 2011-10-31
     79 * \date 2014-03-10
    7580 *
    7681 */

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

    r74459a rcaece4  
    2323 * -# Every .hpp files must include \b config.h
    2424 * -# Every .dox file contains a (correctly formatted: YYYY-MM-DD) date stamp.
     25 * -# Every .cpp file must contain a correct copyright header
     26 * -# Every .hpp file must be present in a Makefile.am (for distributable archive)
    2527 *
    2628 * These make sure that the memory debugger is catching every movement on the
    … …  
    9597 *  -# Add the file as an \e m4_include directive to testsuite.at.
    9698 *
     99 *  These files may also contain exceptions which are stored as a simple list of
     100 *  files for which one of the above rules does not apply.
    97101 *
    98  * \date 2011-10-31
     102 * \date 2014-03-10
    99103 *
    100104 */

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

    r74459a rcaece4  
    2020 *
    2121 * Regression test with this project are used to check on the functionality of
    22  * all Actions. The launch the MoleCuilder from the command line with a given
     22 * all Actions. They launch MoleCuilder from the command line with a given
    2323 * action and option and basically diff the output against a stored file with
    2424 * the desired result. This should be the behavior of more than 90% of all
    25  * regression tests.
     25 * regression tests.
     26 * For some we additionally catch the output from stdout and stderr and diff against
     27 * it, but this is actually not a recommended way of testing as output depends very
     28 * much on the logging level.
    2629 *
    2730 * \section regressiontest-structure Directory structure

  • src/documentation/userinterfaces/commandline.dox

    r74459a rcaece4  
    2020 * forward way.
    2121 *
    22  * Commands are parsed via the CommandLineParser with uses boost::program_options
     22 * Commands are parsed via the CommandLineParser which uses boost::program_options
    2323 * to recognize the given options. ActionRegistry and OptionRegistry are used
    24  * to distinguish Option's from Action's. A specific type per option is expected
    25  * and the ValueStorage assures that only the correct type is parsed.
     24 * to distinguish Option's from Action's. Each option has a specific type and a
     25 * Validator ascertains that the value associated with this option and of this
     26 * specific type matches certain criteria.
    2627 *
    2728 * So far the sequence of the Option's is not really important but for the
    2829 * Action's the ordering counts: first come, first serve.
    2930 *
    30  * Undoing is possible as well. But is so far only used in the regression test
    31  * to test its functionality. This will become more usefull when the
    32  * ActionHistory is stored to file and past session can be re-enacted by loading
    33  * simply it. Their undo would allow for traversing back in this history.
     31 * Undoing is possible from the command-line as well. But is so far only used in
     32 * the regression test to test its functionality. However, as the ActionHistory,
     33 * or rather ActionQueue, can be saved as a session, this is useful as in a restored
     34 * ActionHistory undo would allow for traversing back in this history.
    3435 *
    3536 *
    36  * \date 2011-10-31
     37 * \date 2014-03-10
    3738 *
    3839 */

  • src/documentation/userinterfaces/graphical.dox

    r74459a rcaece4  
    1616 * \page userinterfaces-graphical Graphical User Interface
    1717 *
    18  * The GUI is based on Qt4. It used Qt3D for displaying the GlWorldView and
     18 * The GUI is based on Qt4. It uses Qt3D for displaying the GlWorldView and
    1919 * allowing for easy selecting of atoms and molecules.
    2020 *
    … …  
    2323 * - a world view, implemented in GLWorldView, displaying atoms and bonds
    2424 *   and allowing for selecting them.
    25  * - A list of all currently selected molecules.
    26  * - A list of all currently present molecules.
     25 * - a tab widget on the right with hover info and a list of shapes.
     26 * - a tab widget below the world view enlisting molecules, elements, fragments,
     27 *   and homologies.
     28 *
    2729 *
    2830 * \section userinterfaces-graphical-query Queries in the graphical interface.
    2931 *
    30  * As all Action always instantiate a Dialog which behaves differently for
     32 * As all Action's always instantiate a Dialog which behaves differently for
    3133 * each of the three user interface, we give a brief description of what it
    3234 * does here.
    … …  
    3638 * Eventually, this concatenated dialog is presented to the user -- it might
    3739 * be empty though as well -- he enters all values and clicks accept (even
    38  * in case of an empty dialog). These values are passed via a Pipe mechanism
    39  * (this is a workaround as Qt's moc does not liked nested classes) to the
    40  * ValueStorage.
     40 * in case of an empty dialog). These values are inspected with each Option's
     41 * validator and only if all are true, accept is actually clickable. If not, at
     42 * least one option is still invalid.
     43 *
    4144 *
    4245 * \section userinterfaces-graphical-world_view How the World view works ...
    4346 *
    44  * GLWorldView handles the Observer translation to Qt's own mechanism. Also, it
    45  * contains an instance of the GLWorldScene. This instance knows about all
     47 * GLWorldView handles the Observer translation to Qt's own signal/slot mechanism.
     48 * Also, it contains an instance of the GLWorldScene. This instance knows all about
    4649 * atoms and bonds present in this scene, i.e. it has lists on them and handles
    4750 * adding and removing. Objects in this scene are GLMoleculeObject's which
    … …  
    5356 *
    5457 *
    55  * \date 2012-01-05
     58 * \date 2014-03-10
    5659 *
    5760 */

  • src/documentation/userinterfaces/python.dox

    r74459a rcaece4  
    22 * Project: MoleCuilder
    33 * Description: creates and alters molecular systems
    4  * Copyright (C)  2010 University of Bonn. All rights reserved.
     4 * Copyright (C)  2013 Frederik Heber. All rights reserved.
    55 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
    66 */
    … …  
    2222 *  This is done in \b src/Python/PythonScripting.cpp.
    2323 *
    24  *  There again some preprocessor magic is happening. One the one hand we
    25  *  need GlobalListOfActions.hpp to have a list of all actions available.
    26  *  Second, in AllActionPython.hpp we define export functions for every
    27  *  Action (in essence we use the COMMAND function, see Action_impl_pre.hpp,
    28  *  which makes an Action usable internally as a normal function).
     24 *  There again some preprocessor magic is happening, very similar to constructs
     25 *  we used for the Action's. One the one hand we need GlobalListOfActions.hpp to
     26 *  have a list of all actions available. Second, in AllActionPython.hpp we define
     27 *  export functions for every Action (in essence we use the COMMAND function, see
     28 *  Action_impl_pre.hpp, which makes an Action usable internally as a normal
     29 *  function).
    2930 *
    3031 *  Then, at the beginning of the BOOST_PYTHON_MODULE declaration we initialize
    … …  
    4849 *  \endcode
    4950 *  which loads a file \b test.xyz into the (internal) World, selects the first
    50  *  atom and removes it. Notice \b mol.wait() at the end. This might be necessary
    51  *  as actions are executed in a different thread than the python script itself.
     51 *  atom and removes it.
     52 *
     53 *  \subsection userinterfaces-python-first-test-wait Wait may be important ...
     54 *
     55 *  \note Notice \b mol.wait() at the end. This might be necessary as actions are
     56 *  executed in a different thread than the python script itself. This is only
     57 *  enabled when configure is called with \b enable-action-thread.
     58 *
    5259 *  Hence, if you require values from molecuilder you have to make sure that
    5360 *  all your actions have been processed by this second thread. That's what
    … …  
    8289 *
    8390 *  If in the current directory a file \b molecuilder.py is found, the contents
    84  *  is executed as a regular python script.
     91 *  is executed as a regular python script prior to any other Action's.
    8592 *
    8693 *  \note Each commands needs to be taken from a molecule called \a pyMoleCuilder.
    … …  
    141148 *  gives you the docu string on WorldInputAction.
    142149 *
    143  * \subsection userinterfaces-python-notes-wait Waiting for the action queue
    144  *
    145  * Note again that actions are executed in a different thread as the python
    146  * script. Hence, we require synchronization at certain intervals where you
    147  * require molecuilder to be up to speed. All commands you executed such
    148  * as
    149  * \code
    150  * import pyMoleCuilder as mol
    151  * mol.WorldInput("foo.xyz")
    152  * mol.wait()
    153  * \endcode
    154  * just queue this specific input action but not execute it right away. That's
    155  * left to the other thread. Hence, you need to wait() before:
    156  * -# you access mol.get...() functions as these are not actions themselves.
    157  * -# you need to have files written by molecuilder to be parsed in the python
    158  *    script.
    159150 *
    160151 *
    161  * \date 2013-09-28
     152 * \date 2014-03-10
    162153 *
    163154 */

  • src/documentation/userinterfaces/textmenu.dox

    r74459a rcaece4  
    33 * Description: creates and alters molecular systems
    44 * Copyright (C)  2010 University of Bonn. All rights reserved.
     5 * Copyright (C)  2014 Frederik Heber. All rights reserved.
    56 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
    67 */
    … …  
    1617 * \page userinterfaces-textmenu Text Menu Interface
    1718 *
    18  *  The textmenu mimicks the graphical interface in having the very same menu
    19  *  with actions at the same positions. Only visual output can only be obtained
    20  *  by saving the world at intervals and inspecting the outcome. This is a sort
    21  *  of lowman's way to a graphical interface but can be done via a remote
    22  * machine if its filesystem is mountable.
     19 * The textmenu mimicks the graphical interface in having the very same menu
     20 * with actions at the same positions. Only visual output can only be obtained
     21 * by saving the world at intervals and inspecting the outcome via another program.
     22 * This is a sort of layman's way to a graphical interface but can be done via a
     23 * remote machine if its filesystem is mountable.
    2324 *
    24  *  \note The textmenu interface is the least maintained part of the user
    25  *  interfaces, so be cautious in using it. However, it also has the smallest
    26  *  impact in terms of code lines. In effect it may work just as well as the
    27  *  others.
     25 * \note The textmenu interface is the least maintained part of the user
     26 * interfaces, so be cautious in using it. However, it also has the smallest
     27 * impact in terms of code lines. In effect it may work just as well as the
     28 * others.
    2829 *
    2930 *
    30  *  \date 2011-10-31
     31 * \date 2014-03-10
    3132 *
    3233 */
Note: See TracChangeset for help on using the changeset viewer.