Changes between Initial Version and Version 1 of ExampleSpatialTranslation

Timestamp:

Jul 6, 2010, 10:29:32 AM (14 years ago)

Author:

FrederikHeber

Comment:

first version

ExampleSpatialTranslation

@@ +1 @@
+= Spatial translation of a molecule =
+
+Note that we will here explain in full detail how actions are called, this will be omitted on other examples.
+
+You can call this action [source:src/Actions/MoleculeAction/TranslateAction.cpp] via any of the three interface, here we explain it via the !CommandLineUI.
+
+The following will start molecuilder with the !CommandLineUI [source:src/UIElements/CommandLineUIUIFactory.hpp] as the UIFactory [source:src/UIElements/UIFactory.hpp]
+{{{
+molecuilder -i test.conf -t 2 0 0 --molecule-by-id 0
+}}}
+It will parse the molecular system found in the pcp config file ''test.conf'' and translate it by (2,0,0), i.e. by 2 angstroem in the x direction, and save the file on exit.
+
+But what happens behind inside molecuilder?
+
+== Code explained ==
+
+   1 First of all, there is an action class called !MoleculeTranslateAction defined in [source:src/Actions/MoleculeAction/TranslateAction.cpp]. It has a unique(!) '''NAME'''.
+ 
+   1 Furthermore, all actions are instantiated in the so-called !MapOfActions::populateActions() [source:src/Actions/MapOfActions.cpp], also the !MoleculeTranslateAction(). Thereby, its '''NAME''' and the pointer to its instance is placed in an !ActionRegistry [source:src/Actions/ActionRegistry.cpp], which is a singleton, can be called from anywhere and asked for the instance of a specific action when knowing its name. In this registry the instantiated actions are simply sitting there and waiting to be called forth to do something.
+
+   1 Moreover, the !MapOfActions has lists about which Action belongs to which menu, what the short form for the command-option is (the long form is always --NAME), what type its parameter has (if any) and also default values (also if any). This information is used by the !CommandLineParser [source:src/CommandLineParser.cpp] to fill in the [[http://www.boost.org/doc/libs/1_43_0/doc/html/program_options.html|boost::program_options]] with the necessary details to parse all command line arguments into a map for later retrieval.
+
+   1 See the main() function in [source:src/builder.cpp] for an overview what has happened so far and happens now: The !CommandLineParser was set, it has parsed all command line arguments and has also noted down their specific ordering on the command line in !CommandLineParser::!SequenceOfActions. Now, the !MainWindow is called. This is the central instance of any user interface (whether textmenu, commandline or graphical) to wait for user interaction.
+
+   1 In the !CommandLineUI variant of the !MainWindow [source:src/UIElements/CommandLineUI/CommandLineWindow.cpp] in the function display(), we go through this !SequenceOfActions. All actions are asked from the repository. If not present, we assume that is not an action but an additonal argument (such as --input or -i above). If it is present, the action is called.
+
+   1 In MoleculeTranslateAction::performCall() [source:src/Actions/MoleculeAction/TranslateAction.cpp] you notice that first a dialog is constructed and then its display() function is called. This will wait for user interaction and return with a success-or-not statement. If the user input has been complete (success), we proceed and translate the molecule. For this translation action the following information is necessary: The molecule to translate, the vector to translate by and a statement whether periodic boundary conditions shall be adhered.
+
+   1 These dialogs and their queries are bit more difficult. Each !UIFactory variant has its own queries. In case of the text menu, the user is asked on the console for the specific set of values, in the graphical interface a window pops up with boxes to enter the values. However, on the commandline these values have to be fed in already by the knowledgable user: In our case the parameter to our (-t) command line argument, i.e. to our action is the vector. Hence, the dialog receives the action's '''NAME''' as reference, whereas for the molecule and the periodicity statement we give the names of options that are defined in !MapOfActions. Note that periodicity has a default value of ''0'' and thus may be omitted.
+
+   1 These references are necessary for the queries as in our command line case the queries will turn to !CommandLineParser and ask its parsed map of command line arguments for the value belonging to this reference. I.e. for "molecule-by-id" !CommandLineParser::vm [source:src/CommandLineParser.hpp] contains ''0''
+
+   1 With the complete information we call upon molecule::Translate() or molecule::!TranslatePeriodically() [source:src/molecule_geometry.cpp] for the molecule instance obtained via the query.
+
+   1 At the end of the main function, a !FormatParserStorage [source:src/Parser/FormatParseStorage.cpp] is called which will create the output streams for all desired formats and !ChangeTracker will tell the specific !FormatParsers to write the updated information from the World [source:src/World.hpp] to file.