Changeset bbff92


Ignore:
Timestamp:
Nov 3, 2011, 10:38:31 AM (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:
004ae7
Parents:
7ba268 (diff), f11c23 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Merge branch 'Doxygen_Documentation_Enhancement' into mergeMaster

Files:
39 added
18 edited

Legend:

Unmodified
Added
Removed

  • LinearAlgebra/configure.ac

    r7ba268 rbbff92  
    33
    44AC_PREREQ(2.59)
    5 AC_INIT(LinearAlgebra, 1.0.3, [heber@ins.uni-bonn.de], [molecuilder], [http://trac.ins.uni-bonn.de/projects/molecuilder/])
     5AC_INIT(LinearAlgebra, 1.0.3, [heber@ins.uni-bonn.de], [linearalgebra], [http://trac.ins.uni-bonn.de/projects/molecuilder/])
    66AC_CONFIG_AUX_DIR([build-aux])
    77AC_CONFIG_SRCDIR([src/LinearAlgebra/Vector.cpp])
    … …  
    2323DX_PS_FEATURE(OFF)
    2424DX_PDF_FEATURE(OFF)
    25 DX_INIT_DOXYGEN(LinearAlgebra, Doxyfile, $(docdir))
     25DX_INIT_DOXYGEN(LinearAlgebra, Doxyfile, ${docdir})
    2626
    2727LT_INIT([static])

  • LinearAlgebra/doc/Doxyfile

    r7ba268 rbbff92  
    9090                         *.c++ \
    9191                         *.d \
     92                         *.dox \
    9293                         *.java \
    9394                         *.ii \

  • LinearAlgebra/tests/CodeChecks/Makefile.am

    r7ba268 rbbff92  
    55        testsuite.at \
    66        testsuite-config_h.at \
     7        testsuite-date_in_dox.at \
    78        testsuite-memdebug.at \
    89        $(TESTSUITE)
    … …  
    1213
    1314TESTSCRIPTS = \
    14         testsuite-memdebug.at \
    15         testsuite-config_h.at
     15        testsuite-config_h.at \
     16        testsuite-date_in_dox.at \
     17        testsuite-memdebug.at
    1618
    1719max_jobs = 4
    … …  
    2527                esac; \
    2628        done; \
    27         $(SHELL) '$(TESTSUITE)' $$nrjobs $(TESTSUITEFLAGS)
     29        $(SHELL) '$(TESTSUITE)' $$nrjobs AUTOTEST_PATH='$(abs_top_builddir)/src' $(TESTSUITEFLAGS)
    2830
    2931installcheck-local: atconfig atlocal $(TESTSUITE)
    30         $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
    31         $(TESTSUITEFLAGS)
     32        nrjobs=; \
     33        for flag in $$MAKEFLAGS; do \
     34                case $$flag in \
     35                --* | =*=) ;; \
     36                *j*) nrjobs="-j$(max_jobs)" ;; \
     37                esac; \
     38        done; \
     39        $(SHELL) '$(TESTSUITE)' $$nrjobs AUTOTEST_PATH='$(bindir)' $(TESTSUITEFLAGS)
    3240
    3341clean-local:

  • LinearAlgebra/tests/CodeChecks/testsuite-config_h.at

    r7ba268 rbbff92  
    11AT_SETUP([Checking for present config.h include])
    2 AT_KEYWORDS([CodeCheck,MemDebug])
     2AT_KEYWORDS([CodeCheck config_h])
    33m4_include(atlocal)
    44ok=""

  • LinearAlgebra/tests/CodeChecks/testsuite-memdebug.at

    r7ba268 rbbff92  
    11AT_SETUP([Checking for present MemDebug.hpp include])
    2 AT_KEYWORDS([CodeCheck,MemDebug])
     2AT_KEYWORDS([CodeCheck MemDebug])
    33m4_include(atlocal)
    44ok="builder.cpp MemDebug.cpp SubspaceFactorizer.cpp TestRunner.cpp"

  • LinearAlgebra/tests/CodeChecks/testsuite.at

    r7ba268 rbbff92  
    44# In pre initial files are placed, in post results can be found to be checked by diff in this testsuite.
    55
    6 AT_INIT([Molecular Builder])
     6AT_INIT([Linear Algebra])
    77AT_TESTED(egrep find grep)
    88
    … …  
    1010m4_ifdef([AT_COLOR_TESTS], [AT_COLOR_TESTS])
    1111
    12 AT_BANNER([MoleCuilder - Code Checks])
     12AT_BANNER([LinearAlgebra - Code Checks])
     13m4_include(atlocal)
     14
    1315m4_include(testsuite-memdebug.at)
    1416
    1517m4_include(testsuite-config_h.at)
     18
     19m4_include(testsuite-date_in_dox.at)

  • Makefile.am

    r7ba268 rbbff92  
    2020.PHONY: doc
    2121doc:
     22        mkdir -p ${DX_DOCDIR}
    2223        cd doc && make doxygen-doc
    2324

  • configure.ac

    r7ba268 rbbff92  
    2525DX_PS_FEATURE(OFF)
    2626DX_PDF_FEATURE(OFF)
    27 DX_INIT_DOXYGEN(MoleCuilder, Doxyfile, $(docdir))
     27DX_INIT_DOXYGEN(MoleCuilder, Doxyfile, ${docdir})
    2828
    2929# use libtool

  • doc/Doxyfile

    r7ba268 rbbff92  
    9090                         *.c++ \
    9191                         *.d \
     92                         *.dox \
    9293                         *.java \
    9394                         *.ii \

  • doc/userguide.xml

    r7ba268 rbbff92  
    3232      CAD-pendant on the nanoscale. Specific emphasis is placed on a
    3333      simple-to-use interface, allowing for the quick-and-dirty building of
    34       molecular systems. </para>
     34      molecular systems.</para>
    3535
    3636      <para>Geometries should henceforth be simulated with molecular dynamics
    … …  
    5454
    5555        <para><simplelist>
    56             <member>Qt3 (<uri>http://www.trolltech.com/</uri>)</member>
     56            <member>Qt4 (<uri>http://qt.nokia.com/</uri>)</member>
    5757          </simplelist>The code has been tested develeoped on Linux/GNU. It
    5858        was also tested with Win/Cygwin.</para>
    … …  
    149149      commands. A command is always introduced via a hyphen and a single
    150150      letter, e.g. -a for adding an atom to the system. It is followed by a
    151       fixed number of options. </para>
     151      fixed number of options.</para>
    152152
    153153      <para><emphasis>Note that these first three arguments are always

  • src/Actions/Action.hpp

    r7ba268 rbbff92  
    3333#include "Actions/ActionTraits.hpp"
    3434
    35 /**
    36  * @file
    37  * <H1> Action Howto </H1>
    38  *
    39  * <H2> Introduction </H2>
    40  *
    41  * Actions are used in object oriented design as a replacement for callback functions.
    42  * In most ways Actions can be used in the same way that callbacks were used in non
    43  * OO-Systems, but can contain support for several extra mechanism such as undo/redo
    44  * or progress indicators.
    45  *
    46  * The main purpose of an action class is to contain small procedures, that can be repeatedly
    47  * called. These procedures can also be stored, passed around, so that the execution of an
    48  * action can happen quite far away from the place of creation. For a detailed description of
    49  * the Action pattern see GOF:1996.
    50  *
    51  * <H3> How to use an action </H3>
    52  *
    53  * The process of using an action is as easy as calling the call() method of the action. The
    54  * action will then do whatever it is supposed to do. If it is an action that can be undone, it
    55  * will also register itself in the history to make itself available for undo. To undo the last
    56  * action, you can either use the undoLast() method inside the ActionHistory class or call the
    57  * UndoAction also provided by the ActionHistory. If an action was undone it will be available for
    58  * redo, using the redoLast() method of the ActionHistory or the RedoAction also provided by this
    59  * class. To check whether undo/redo is available at any moment you can use the hasUndo() or
    60  * hasRedo() method respectively.
    61  *
    62  * Note that an Action always has two functions createDialog() and performCall(). The former
    63  * returns a Dialog filled with query...() functions for all information that we need from the
    64  * user. The latter must not contain any interaction but just uses these values (which are
    65  * temporarily stored by class ValueStorage) to perform the Action.
    66  *
    67  * Furthermore, there is a global action function that makes the action callable with already
    68  * present parameters (i.e. without user interaction and for internal use within the code only).
    69  * This function is basically just a macro, that puts the parameters into the ValueStorage and
    70  * calls Action::call(Action::NonInteractive).
    71  *
    72  * Actions can be set to be active or inactive. If an action is set to inactive it is signaling, that
    73  * some condition necessary for this action to be executed is not currently met. For example the
    74  * UndoAction will set itself to inactive, when there is no action at that time that can be undone.
    75  * Using call() on an inactive Action results in a no-op. You can query the state of an action using
    76  * the isActive() method.
    77  *
    78  * The undo capabilities of actions come in three types as signaled by two boolean flags (one
    79  * combination of these flags is left empty as can be seen later).
    80  * <ul>
    81  * <li/> The first flag indicates if the undo mechanism for this action should be considered at all, i.e.
    82  *   if the state of the application changes in a way that needs to be reverted. Actions that should
    83  *   consider the undo mechanism are for example adding a molecule, moving atoms, changing
    84  *   the name of a molecule etc. Changing the View-Area on the other hand should be an action that
    85  *   does not consider the undo mechanism. This flag can be queried using the shouldUndo() method.
    86  *
    87  * <li/> The second flag indicates whether the changes can be undo for this action. If this flag is true
    88  *   the action will be made available for undo using the ActionHistory class and the actions of this
    89  *   class. If this flag is false while the shoudlUndo() flag is true this means that this action
    90  *   changes the state of the application changes in a way that cannot be undone, but might cause
    91  *   the undo of previous actions to fail. In this case the whole History is cleared, as to keep
    92  *   the state of the application intact by avoiding dangerous undos. This flag can be queried
    93  *   using the canUndo() method.
    94  *</ul>
    95  *
    96  * Each action has a name, that can be used to identify it throughout the run of the application.
    97  * This name can be retrieved using the getName() method. Most actions also register themselves with
    98  * a global structure, called the ActionRegistry. Actions that register themselves need to have a
    99  * unique name for the whole application. If the name is known these actions can be retrieved from
    100  * the registry by their name and then be used as normal.
    101  *
    102  * <H2> Building your own actions </H2>
    103  *
    104  * Building actions is easy. Each specific ...Action is derived from the base class Action.
    105  * In order to create all the reoccuring stuff, macros have been created which you can simply
    106  * include and then don't need to worry about it.
    107  * There are three major virtual functions: performCall(), performUndo(), performRedo() which
    108  * you have to write, to equip your action with some actual capabilities.
    109  * Each Action definition and implementation consists of of three files:
    110  * -# cpp: contains performX() which you have to write, also some boilerplate functions which are
    111  *         constructed automatically when including your def and "Actions/action_impl_pre.hpp"
    112  * -# hpp: boilerplate definitions created simply by including your def and
    113  *         "Actions/action_impl_header.hpp"
    114  * -# def: macro definitions of all your parameters and additional variables needed for the state,
    115  *         also name and category and token of your action.
    116  *
    117  * Best thing to do is look at one of the already present triples and you should soon understand
    118  * what you have to add:
    119  * -# pick the right category, i.e. the right folder in src/Actions
    120  * -# pick the right name
    121  * -# decide which parameters your actions need and what the type, the variable name and the token
    122  *    to reference it from the command-line should be. Check whether already present and fitting
    123  *    tokens exists, e.g. "position" as token for a Vector representing a position.
    124  * -# consider which additional information you need to undo your action
    125  * -# don't forget to include your .def file followed by "action_impl_pre.hpp" in .cpp or
    126  *    "action_impl_header.hpp" in the .hpp
    127  * -# continue to write the functionality of your action in performCall(), undo and redo in performUndo()
    128  *    and performRedo().
    129  * -# You should indicate whether the action supports undo by implementing the shouldUndo() and
    130  *    canUndo() methods to return the appropriate flags.
    131  *
    132  * <H3> Specific notes on the macros </H3>
    133  *
    134  * The following functions are created by the macros, i.e. you don't need to worry about it:
    135  *
    136  * Any user interaction should be placed into the dialog returned by fillDialog().
    137  *
    138  * Also, create the global function to allow for easy calling of your function internally (i.e.
    139  * without user interaction). It should have the name of the Action class without the suffix Action.
    140  *
    141  * The constructor of your derived class also needs to call the Base constructor, passing it the
    142  * name of the Action and a flag indicating whether this action should be made available in the
    143  * registry. WARNING: Do not use the virtual getName() method of the derived action to provide the
    144  * constructor with the name, even if you overloaded this method to return a constant. Doing this
    145  * will most likely not do what you think it does (see: http://www.parashift.com/c++-faq-lite/strange-inheritance.html#faq-23.5
    146  * if you want to know why this wont work)
    147  *
    148  * <H3> Interfacing your Action with the Undo mechanism </H3>
    149  *
    150  * The performX() methods need to comply to a simple standard to allow for undo and redo. The first
    151  * convention in this standard concerns the return type. All methods that handle calling, undoing
    152  * or redoing return an object of Action::state_ptr. This is a smart pointer to a State object, that
    153  * can be used to store state information that is needed by your action for later redo. A rename
    154  * Action for example would need to store which object has been renamed and what the old name was.
    155  * A move Action on the other hand would need to store the object that has been moved as well as the
    156  * old position. If your Action does not need to store any kind of information for redo you can
    157  * simply return Action::success and skip the rest of this paragraph. If your action has been
    158  * abborted you can return Action::failure, which indicates to the history mechanism that this
    159  * action should not be stored.
    160  *
    161  * If your Action needs any kind of information to undo its execution, you need to store this
    162  * information in the state that is returned by the performCall() method. Since no assumptions
    163  * can be made on the type or amount of information the ActionState base class is left empty.
    164  * To use this class you need to derive a YourActionState class from the ActionState base class
    165  * adding your data fields and accessor functions. Upon undo the ActionState object produced
    166  * by the corresponding performCall() is then passed to the performUndo() method which should
    167  * typecast the ActionState to the appropriate sub class, undo all the changes and produce
    168  * a State object that can be used to redo the action if neccessary. This new state object is
    169  * then used if the redo mechanism is invoked and passed to the performRedo() function, which
    170  * again produces a State that can be used for performUndo().
    171  *
    172  * <H3> Outline of the implementation of Actions </H3>
    173  *
    174  * To sum up the actions necessary to build actions here is a brief outline of things methioned
    175  * in the last paragraphs:
    176  *
    177  * <H4> Basics </H4>
    178  *
    179  * <ul>
    180  *  <li/> create parameter tupels (type, token, reference), put into def. Access them later in
    181  *        the performX() via the structure params.###.
    182  *  <li/> think of name, category and token for your action, put into def
    183  *  <li/> create additional state variables tupels (type, reference) for storing extra information
    184  *        that you need for undo/redo in the ActionState. You can always access the parameters
    185  *        of your Action by state.params.### (i.e. they are copied to the state by default).
    186  *  <li/> implement performCall(), first line should be calling of getParametersfromValueStorage().
    187  *  <li/> performUndo(), performRedo()
    188  *  <li/> implement the functions that return the flags for the undo mechanism, i.e. true/false.
    189  * </ul>
    190  *
    191  * <H4> Implementing performX() methods </H4>
    192  *
    193  * <ul>
    194  *  <li/> performCall():
    195  *  <ul>
    196  *   <li/> first line should be calling of getParametersfromValueStorage().
    197  *   <li/> Access your parameters by the structure params.### (where ### stands for the reference/
    198  *         variable name chosen in the tupel).
    199  *   <li/> do whatever is needed to make the action work
    200  *   <li/> if the action was abborted return Action::failure
    201  *   <li/> if the action needs to save a state return a custom state object
    202  *   <li/> otherwise return Action::success
    203  *  </ul>
    204  *  <li/> performUndo():
    205  *  <ul>
    206  *   <li/> typecast the ActionState pointer to a Pointer to YourActionState if necessary
    207  *   <li/> undo the action using the extra information and the Action's parameters in the state
    208  *   <li/> produce a new state that can be used for redoing and return it
    209  *  </ul>
    210  *  <li/> performRedo():
    211  *  <ul>
    212  *   <li/> take the ActionState produced by performUndo and typecast it to a pointer to YourActionState if necessary
    213  *   <li/> redo the undone action using the extra information and the Action's parameters in the state
    214  *   <li/> produce a new state that can be used by performUndo() and return it
    215  *  </ul>
    216  * </ul>
    217  *
    218  * <H2> Advanced techniques </H2>
    219  *
    220  * <H3> Predefined Actions </H3>
    221  *
    222  * To make construction of actions easy there are some predefined actions. Namely these are
    223  * the MethodAction and the ErrorAction.
    224  *
    225  * The method action can be used to turn any function with empty arguments and return type void
    226  * into an action (also works for functors with those types). Simply pass the constructor for the
    227  * MethodAction a name to use for this action, the function to call inside the performCall()
    228  * method and a flag indicating if this action should be made retrievable inside the registry
    229  * (default is true). MethodActions always report themselves as changing the state of the
    230  * application but cannot be undone. i.e. calling MethodActions will always cause the ActionHistory
    231  * to be cleared.
    232  *
    233  * ErrorActions can be used to produce a short message using the Log() << Verbose() mechanism of
    234  * the molecuilder. Simply pass the constructor a name for the action, the message to show upon
    235  * calling this action and the flag for the registry (default is again true). Error action
    236  * report that they do not change the state of the application and are therefore not considered
    237  * for undo.
    238  *
    239  * <H3> Sequences of Actions and MakroActions </H3>
    240  *
    241  * <H4> Building sequences of Actions </H4>
    242  *
    243  * Actions can be chained to sequences using the ActionSequence class. Once an ActionSequence is
    244  * constructed it will be initially empty. Any Actions can then be added to the sequence using the
    245  * addAction() method of the ActionSequence class. The last added action can be removed using the
    246  * removeLastAction() method. If the construction of the sequence is done, you can use the
    247  * callAll() method. Each action called this way will register itself with the History to allow
    248  * separate undo of all actions in the sequence.
    249  *
    250  * <H4> Building larger Actions from simple ones </H4>
    251  *
    252  * Using the pre-defined class MakroAction it is possible to construct bigger actions from a sequence
    253  * of smaller ones. For this you first have to build a sequence of the actions using the ActionSequence
    254  * as described above. Then you can construct a MakroAction passing it a name, the sequence to use
    255  * and as usual a flag for the registry. You can then simply call the complete action-sequence through
    256  * this makro action using the normal interface. Other than with the direct use of the action sequence
    257  * only the complete MakroAction is registered inside the history, i.e. the complete sequence can be
    258  * undone at once. Also there are a few caveats you have to take care of when using the MakroAction:
    259  * <ul>
    260  *  <li/> All Actions as well as the sequence should exclusively belong to the MakroAction. This
    261  *        especially means, that the destruction of these objects should be handled by the MakroAction.
    262  *  <li/> none of the Actions inside the MakroAction should be registered with the registry, since the
    263  *        registry also assumes sole ownership of the actions.
    264  *  <li/> Do not remove or add actions from the sequence once the MakroAction has been constructed, since this
    265  *        might brake important assumptions for the undo/redo mechanism
    266  * </ul>
    267  *
    268  * <H3> Special kinds of Actions </H3>
    269  *
    270  * To make the usage of Actions more versatile there are two special kinds of actions defined,
    271  * that contain special mechanisms. These are defined inside the class Process, for actions that
    272  * take some time and indicate their own progress, and in the class Calculations for actions that
    273  * have a retrievable result.
    274  *
    275  * <H4> Processes </H4>
    276  *
    277  * Processes are Actions that might take some time and therefore contain special mechanisms
    278  * to indicate their progress to the user. If you want to implement a process you can follow the
    279  * guidelines for implementing actions. In addition to the normal Action constructor parameters,
    280  * you also need to define the number of steps the process takes to finish (use 0 if that number is
    281  * not known upon construction). At the beginning of your process you then simply call start() to
    282  * indicate that the process is taking up its work. You might also want to set the number of steps it
    283  * needs to finish, if it has changed since the last invocation/construction. You can use the
    284  * setMaxSteps() method for this. Then after each finished step of calulation simply call step(),
    285  * to let the indicators know that it should update itself. If the number of steps is not known
    286  * at the time of calculation, you should make sure the maxSteps field is set to 0, either through
    287  * the constructor or by using setMaxSteps(0). Indicators are required to handle both processes that
    288  * know the number of steps needed as well as processes that cannot predict when they will be finished.
    289  * Once your calculation is done call stop() to let every indicator know that the process is done with
    290  * the work and to let the user know.
    291  *
    292  * Indicators that want to know about processes need to implement the Observer class with all the
    293  * methods defined there. They can then globally sign on to all processes using the static
    294  * Process::AddObserver() method and remove themselves using the Process::RemoveObserver()
    295  * methods. When a process starts it will take care that the notification for this process
    296  * is invoked at the right time. Indicators should not try to observe a single process, but rather
    297  * be ready to observe the status of any kind of process using the methods described here.
    298  *
    299  * <H4> Calculations </H4>
    300  *
    301  * Calculations are special Actions that also return a result when called. Calculations are
    302  * always derived from Process, so that the progress of a calculation can be shown. Also
    303  * Calculations should not contain side-effects and not consider the undo mechanism.
    304  * When a Calculation is called using the Action mechanism this will cause it to calculate
    305  * the result and make it available using the getResult() method. Another way to have a Calculation
    306  * produce a result is by using the function-call operator. When this operator is used, the Calculation
    307  * will try to return a previously calculated and cached result and only do any actuall calculations
    308  * when no such result is available. You can delete the cached result using the reset() method.
    309  */
    31035
    31136namespace MoleCuilder {

  • src/Actions/ValueStorage.hpp

    r7ba268 rbbff92  
    8989 * to store&retrieve/exchange values.
    9090 *
    91  * \section <ValueStorage> (ValueStorage howto)
     91 * \section ValueStorage ValueStorage howto
    9292 *
    9393 * If you ever need to add a particular class to the ValueStorage, do as follows:

  • src/UIElements/CommandLineUI/CommandLineParser.hpp

    r7ba268 rbbff92  
    3131
    3232/** This class is a wrapper for boost::program_options.
    33  *
    34  * <h1> CommandLine Howto </h1>
    35  * <h2> Introduction </h2>
    36  *
    37  * The UIFactory is a base class for the User Interaction. There are three UI specializations:
    38  * Text, GUI and CommandLine. Accessing functionality via the CommandLine UI is explained here.
    39  *
    40  * First, an Action has to be written for the specific functionality. This Action should
    41  * be added in Actions/...Action in the respective subdirectory of the following types:
    42  *  -# Analysis: Analysis actions like evaluating pair correlation, bonds, ...
    43  *  -# Atom: adding, removing, manipulating atoms
    44  *  -# Cmd: specifying data bases, verbosity, ...
    45  *  -# Fragmentation: fragmenting a system, performing graph analysis, ...
    46  *  -# Molecule: adding, removing, manipulating molecules
    47  *  -# Parser: Parsing files (loading, saving)
    48  *  -# Tesselation: obtaining (non)convex surface of a molecule, embedding, ...
    49  *  -# World: Setting Box dimensions, default name of new molecules, ...
    50  *
    51  *  The CommandLineUIFactory is a specialization of the UIFactory for parsing command
    52  *  line parameters, generating and executing actions there from.
    53  *
    54  *  The idea of the CommandLineFactory is explained elsewhere, here we would like to give a
    55  *  receipe for creating new actions.
    56  *
    57  * <h3>Introducing new actions</h3>
    58  *
    59  * Let us now introduce what to do if a new action is to be implemented. Here, we use the
    60  * CommandLineVersionAction as an example.
    61  * This consists if basically three parts:
    62  * 1. Create the files, write the classes and make them compilable
    63  *   - Create new source and header files in one of the above subfolders in the Actions folder,
    64  *     e.g. create VersionAction.cpp and VersionAction.hpp in Actions/Cmd/
    65  *   - Give it a sensible class name, the convention is <type><what it does>Action,
    66  *     where <type> is basically the naming (written out) of the subdirectory,
    67  *     e.g. class CommandLineVersionAction.
    68  *   - Add the source and header file to the respective variables in molecuilder/src/Makefile.am,
    69  *     e.g. if you add a Cmd action the variables are CMDACTIONSOURCE and CMDACTIONHEADER,
    70  *     such that they get compiled.
    71  * 2. Add an instance to the CommandLineUIFactory, such that they are known to the UI.
    72  *   - Add the header file as an include to UIElements/CommandLineWindow.cpp, e.g.
    73  *     #include "Actions/Cmd/VersionAction.hpp"
    74  *   - Add an instance of your class to the specific populater-function in
    75  *     UIElements/CommandLineWindow.cpp, e.g. for the above Cmd action, add to populateCommandActions()
    76  *     add new CommandLineVersionAction().
    77  *     This will automatically register in the ActionRegistry.
    78  * 3. Give them an option name, short hand an description, such that they can be referenced from
    79  *    the command line.
    80  *   - think of a new key name, e.g. "version", which is the long form of the command parameter,
    81  *     i.e. --version).
    82  *   - add this key to every map of MapofActions, i.e. to
    83  *     - MapofActions::DescriptionMap: the description which appears as help and tooltip
    84  *     - MapofActions::ShortFormMap: the short form of the command parameter (e.g. -v)
    85  *     - MapofActions::ValueMap: the value the command parameter has (do not create if it does not need one)
    86  *   - If your action requires additional parameters, these need to be added in the same manner as in
    87  *     the list item above.
    88  *
    89  *  Don't forget to write the actual code. :)
    90  *
    91  * <h3>Writing an action</h3>
    92  *
    93  *  As you write a new action you may think in terms of the command line, i.e. you want to use this
    94  *  new functionality you add by calling molecuilder as: ./molecuilder --super-action foobar.txt, where
    95  *  the key of your new action would be "super-action". While this is fine, keep in mind, that your action
    96  *  should be useable for the other UI specializations as well, i.e. from the menu and the GUI. Therefore,
    97  *  -# Don't use cin to ask the user for input: Use Query...()!
    98  *  -# Rather don't use cout/cerrs, but either give Log() or eLog() or use QueryEmpty() if you want to give
    99  *     the user specific information what you ask of him.
    10033 *
    10134 */

  • src/builder.cpp

    r7ba268 rbbff92  
    1313 */
    1414
    15 /*! \page Copyright notice
    16  *
    17  *  MoleCuilder - to create and alter molecular systems
    18  *  Copyright (C) 2010  University Bonn. All rights reserved.
    19  *
    20  */
    21 
    22 /*! \mainpage MoleCuilder - a molecular set builder
    23  *
    24  * This introductory shall briefly make acquainted with the program, helping in installing and a first run.
    25  *
    26  * \section about About the Program
    27  *
    28  *  MoleCuilder is a program, written entirely in C++, that enables the construction of a coordinate set for the
    29  *  atoms making up an molecule. It allows for both building of simple molecules by adding atom-wise giving bond
    30  *  angles and distances or absolute coordinates, but also using them as templates. Regions can be specified and
    31  *  ordered to be filled with a molecule in a certain manner. Greater conglomerations of molecules can be tesselated
    32  *  and recognized as a region themselves to be subsequently surrounded by other (surface solvated) molecules.
    33  *  In the end, MoleCuilder allows the construction of arbitrary nano structures, whether they be crystalline or
    34  *  amorphic in nature.
    35  *
    36  *
    37  * \section install Installation
    38  *
    39  *  Installation should without problems succeed as follows:
    40  *  -# ./configure (or: mkdir build;mkdir run;cd build; ../configure --bindir=../run)
    41  *  -# make
    42  *  -# make install
    43  *
    44  *  Further useful commands are
    45  *  -# make clean uninstall: deletes .o-files and removes executable from the given binary directory\n
    46  *  -# make doxygen-doc: Creates these html pages out of the documented source
    47  *  -# make check: Runs an extensive set of unit tests and a testsuite which also gives a good overview on the set of
    48  *                 functions.
    49  *
    50  * \section run Running
    51  *
    52  *  The program can be executed by running: ./molecuilder
    53  *
    54  *  MoleCuilder has three interfaces at your disposal:
    55  *  -# Textmenu: A simple interactive console-based menu, where awaits your choices and inputs in order to set atoms
    56  *               as you like
    57  *  -# CommandLineUI: Every command can also be chained up as a sequence of actions on the command line to be executed
    58  *               with any user interaction.
    59  *  -# GraphicalUI: A graphical user interface that also display the molecular structure being built and lots of other
    60  *               informations to ease the construction of bigger geometries.
    61  *
    62  *  The supported output formats right now are:
    63  *  -# mpqc: Configuration files of the Massively Parallel Quantum Chemistry package (Sandia labs)
    64  *  -# pcp: Configuration files of the Parallel Car-Parrinello program (Institute for Numerical Simulation)
    65  *  -# tremolo: Configuration files of TREMOLO (Institute for Numerical Simulation)
    66  *  -# xyz: the most basic format for the 3d arrangement of atoms consisting of a list of element and 3 coordinates.
    67  *
    68  */
    6915
    7016// include config.h

  • tests/CodeChecks/Makefile.am

    r7ba268 rbbff92  
    55        testsuite.at \
    66        testsuite-config_h.at \
     7        testsuite-date_in_dox.at \
    78        testsuite-memdebug.at \
    89        $(TESTSUITE)
    … …  
    1213
    1314TESTSCRIPTS = \
    14         testsuite-memdebug.at \
    15         testsuite-config_h.at
     15        testsuite-config_h.at \
     16        testsuite-date_in_dox.at \
     17        testsuite-memdebug.at
    1618
    1719max_jobs = 4
    … …  
    2527                esac; \
    2628        done; \
    27         $(SHELL) '$(TESTSUITE)' $$nrjobs $(TESTSUITEFLAGS)
     29        $(SHELL) '$(TESTSUITE)' $$nrjobs AUTOTEST_PATH='$(abs_top_builddir)/src' $(TESTSUITEFLAGS)
    2830
    2931installcheck-local: atconfig atlocal $(TESTSUITE)
    30         $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
    31         $(TESTSUITEFLAGS)
     32        nrjobs=; \
     33        for flag in $$MAKEFLAGS; do \
     34                case $$flag in \
     35                --* | =*=) ;; \
     36                *j*) nrjobs="-j$(max_jobs)" ;; \
     37                esac; \
     38        done; \
     39        $(SHELL) '$(TESTSUITE)' $$nrjobs AUTOTEST_PATH='$(bindir)' $(TESTSUITEFLAGS)
    3240
    3341clean-local:

  • tests/CodeChecks/testsuite-config_h.at

    r7ba268 rbbff92  
    11AT_SETUP([Checking for present config.h include])
    2 AT_KEYWORDS([CodeCheck,MemDebug])
    3 m4_include(atlocal)
     2AT_KEYWORDS([CodeCheck config_h])
    43ok=""
    54echo `pwd`

  • tests/CodeChecks/testsuite-memdebug.at

    r7ba268 rbbff92  
    11AT_SETUP([Checking for present MemDebug.hpp include])
    2 AT_KEYWORDS([CodeCheck,MemDebug])
    3 m4_include(atlocal)
     2AT_KEYWORDS([CodeCheck MemDebug])
    43ok="builder.cpp MemDebug.cpp SubspaceFactorizer.cpp TestRunner.cpp"
    54echo `pwd`

  • tests/CodeChecks/testsuite.at

    r7ba268 rbbff92  
    1111
    1212AT_BANNER([MoleCuilder - Code Checks])
     13m4_include(atlocal)
     14
    1315m4_include(testsuite-memdebug.at)
    1416
    1517m4_include(testsuite-config_h.at)
     18
     19m4_include(testsuite-date_in_dox.at)
Note: See TracChangeset for help on using the changeset viewer.