source: doc/userguide/userguide.xml@ d8ed62

Action_Thermostats Add_AtomRandomPerturbation Add_FitFragmentPartialChargesAction Add_RotateAroundBondAction Add_SelectAtomByNameAction Added_ParseSaveFragmentResults Adding_Graph_to_ChangeBondActions Adding_MD_integration_tests Adding_ParticleName_to_Atom Adding_StructOpt_integration_tests 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_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 FragmentMolecule_checks_bonddegrees GeometryObjects Gui_Fixes Gui_displays_atomic_force_velocity IndependentFragmentGrids IndependentFragmentGrids_IndividualZeroInstances IndependentFragmentGrids_IntegrationTest IndependentFragmentGrids_Sole_NN_Calculation JobMarket_RobustOnKillsSegFaults JobMarket_StableWorkerPool JobMarket_unresolvable_hostname_fix 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
Last change on this file since d8ed62 was d8ed62, checked in by Frederik Heber <heber@…>, 9 years ago

Rewrote FitPartialChargesAction to fit charges to currently selected atoms.

  • required AtomFragmentsMap in order to associate fragments to atoms.
  • updated documentation to match change in action.
  • Property mode set to 100644
File size: 151.0 KB
Line 
1<?xml version='1.0' encoding='UTF-8'?>
2<!-- This document was created with Syntext Serna Free. --><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3<!ENTITY molecuilder_logo SYSTEM "pictures/molecuilder_logo.png" NDATA PNG>
4<!ENTITY dialog_box SYSTEM "pictures/dialog_box.png" NDATA PNG>
5<!ENTITY dialog_add-atom_tooltip SYSTEM "pictures/dialog_add-atom_tooltip.png" NDATA PNG>
6<!ENTITY dialog_complex SYSTEM "pictures/dialog_complex.png" NDATA PNG>
7<!ENTITY dialog_exit SYSTEM "pictures/dialog_exit.png" NDATA PNG>
8<!ENTITY example_basic_view SYSTEM "pictures/example_basic_view.png" NDATA PNG>
9]>
10<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" version="5.0">
11 <info>
12 <title>MoleCuilder - a Molecule Builder</title>
13 <author>
14 <personname>
15 <firstname>Frederik</firstname>
16 <surname>Heber</surname>
17 </personname>
18 <affiliation>
19 <orgname>heber@ins.uni-bonn.de</orgname>
20 </affiliation>
21 </author>
22 <pubdate>07/03/14</pubdate>
23 </info>
24 <chapter>
25 <title>Introduction</title>
26 <figure>
27 <title>MoleCuilder logo depicting a tesselated buckyball and a benzene molecule</title>
28 <mediaobject>
29 <imageobject>
30 <imagedata width="100%" scalefit="1" entityref="molecuilder_logo"/>
31 </imageobject>
32 </mediaobject>
33 </figure>
34 <section xml:id="whatis">
35 <title xml:id="whatis.title">What is MoleCuilder?</title>
36 <para>In Short,<command> MoleCuilder</command> is a concatenation of
37 molecule and builder.</para>
38 <para>In more words, molecular dynamics simulations are frequently
39 employed to simulate material behavior under stress, chemical reactions
40 such as of cementitious materials, or folding pathways and docking
41 procedures of bio proteins. Even if the computational load, due to the
42 large number of atoms, is very demanding, nonetheless they may serve as
43 a starting point, e.g. extracting parameters for a coarser model.
44 However, what is on the other hand the starting point of molecular
45 dynamics simulations? It is the coordinate and element of each atom
46 combined with potential functions that model the interactions.</para>
47 <para>MoleCuilder allows to fully construct such a starting point:
48 letting the user construct atomic and molecular geometries by a simple
49 point&amp;click approach, a CAD-pendant on the nanoscale. Creating
50 suitable empirical potentials by fitting parameters to ab-initio
51 calculations within hours. Specific emphasis is placed on a
52 simple-to-use interface, allowing for the quick-and-dirty building of
53 molecular systems, and on scriptability. The last being important a eventually not a single, but
54 many, related molecular systems have to be created.</para>
55 <para>We hope you will enjoy using MoleCuilder as much as we had creating it and still continue extending it. It obtains its flexibility from the use of agile programming techniques and state-of-the-art libraries such as Boost. If you feel dissatiesfied with certain parts, please do not hesitate to give feedback (see below).</para>
56 <section xml:id="installation">
57 <title xml:id="installation.title">Installation requirements</title>
58 <para>For installations requirements and instructions we refer to the
59 internal documentation of MoleCuilder, created via <productname>doxygen</productname>. from the
60 source code.</para>
61 </section>
62 <section xml:id="license">
63 <title xml:id="license.title">License</title>
64 <para>As long as no other license statement is given, MoleCuilder is
65 free for user under the GNU Public License (GPL) Version 2 (see
66 <uri>www.gnu.de/documents/gpl-2.0.de.html</uri>).</para>
67 </section>
68 <section xml:id="disclaimer">
69 <title xml:id="disclaimer.title">Disclaimer</title>
70 <para>We quote section 11 from the GPLv2 license:</para>
71 <remark>Because the program is licensed free of charge, there is not warranty for the program, to the extent permitted by applicable law. Except when otherwise stated in writing in the copyright holders and/or other parties provide the program &quot;as is&quot; without warranty of any kind, either expressed or implied. Including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair, or correction.</remark>
72 </section>
73 <section xml:id="feedback">
74 <title xml:id="feedback.title">Feedback</title>
75 <para>If you encounter any bugs, errors, or would like to submit
76 feature request, please use the email address provided at the very
77 beginning of this user guide. The author is especially thankful for
78 any description of all related events prior to occurrence of the
79 error, saved &quot;session scripts&quot; (see below) and auxiliary files. Please
80 mind sensible space restrictions of email attachments.</para>
81 </section>
82 <section xml:id="notation">
83 <title xml:id="notation.title">Notation</title>
84 <para>We briefly explain a few specific wordings associated with the
85 program:</para>
86 <itemizedlist>
87 <listitem>
88 <para><emphasis>Action</emphasis> is a command that allows for
89 undoing and redoing, i.e. a single atomic procedure for
90 manipulating the molecular system. Here, atomic refers to indivisible and not to atoms. It is also referred to as a command.</para>
91 </listitem>
92 <listitem>
93 <para>Selection refers to a subsets from the set of instances of a
94 particular type, e.g. atoms, molecules, shapes, ...</para>
95 </listitem>
96 <listitem>
97 <para>Shape means a specific region of the domain that can be
98 described in the way of constructive geometry, i.e. as the
99 intersection, negation, and combination of primitives such as
100 spheres, cubes, or cylinders.</para>
101 </listitem>
102 <listitem>World refers to the whole of the molecular system, i.e. all atoms with coordinates and element type (over all time steps), all bonds between pairs of atoms, the size of the simulation domain. This state is also referred to as the state.</listitem>
103 <listitem>Time step is the current discrete position in time. Molecular dynamics simulations are executed in discrete (but very small) time steps. Each atom has a distinct position per time step. The discrete positions over the discrete time steps samples its trajectory during a simulation.</listitem>
104 </itemizedlist>
105 </section>
106 <section xml:id="completeness">
107 <title xml:id="completeness.title">Completeness</title>
108 <para>This documentation takes quite some effort to write. Hence, the
109 described features and especially the actions herein are settled with
110 respect to their functionality, while newer features or actions are
111 probably missing. This should be a clear sign to you that these are
112 probably not safe to use yet. If you nonetheless require them, you should acquire some familiarity with the code itself. This suggests
113 changing to the developer documentation which is maintained along with
114 the source code with <productname>doxygen</productname>.</para>
115 </section>
116 </section>
117 </chapter>
118 <chapter>
119 <title>Features</title>
120 <para>Basically, <command>MoleCuilder</command> parses geometries from
121 files, manipulates them, and stores them again in files. The manipulation
122 can be done either via a command-line interface or via the graphical user
123 interface.</para>
124 <section xml:id="concepts">
125 <title xml:id="concepts.title">Concepts</title>
126 <para>In general, we divide the molecular systems into three different
127 components or scales.</para>
128 <orderedlist>
129 <listitem>
130 <para>Atoms</para>
131 <para>Atoms are the undividable objects of the molecular systems.
132 They have at least an element <quote>Z</quote> and three coordinates
133 <quote>(x,y,z)</quote>.</para>
134 </listitem>
135 <listitem>
136 <para>Molecules</para>
137 <para>Molecules are bound conglomeration of atoms. They contain a
138 number of atoms, i.e. by beginning at an arbitrary atom of the molecule and traversing its bond graph eventually all of the molecule&apos;s atoms are visited. Currently, a bond refers to a covalent bonding between atoms. Also, molecules may have a
139 bounding box, i.e. a subdomain that contains all of the atoms in the
140 molecule.</para>
141 <para>Note that the molecular structure of the system, i.e. the
142 bonding graph, is determined by MoleCuilder and used to dissect the
143 system into distinct molecules on request.</para>
144 </listitem>
145 <listitem>
146 <para>Clusters</para>
147 <para>Clusters are unbound conglomeration of atoms. Clusters serves
148 as groups of atoms for specific operations that would be to
149 restricted if they worked on just molecules.</para>
150 </listitem>
151 <listitem>
152 <para>Domain</para>
153 <para>The domain refers to the simulation domain. It is the
154 parallelepiped in <inlineequation>
155 <m:math display="inline">
156 <m:mi>\mathbb{R}^3</m:mi>
157 </m:math>
158 </inlineequation>where either periodic, wrapped, or open boundary
159 conditions apply. The domain contains all atoms, i.e. the box
160 containing all atoms.</para>
161 </listitem>
162 </orderedlist>
163 </section>
164 <section xml:id="interfaces">
165 <title xml:id="interfaces.title">Interfaces</title>
166 <para>MoleCuilder has four different interfaces: Command-line, text
167 menu, graphical user interface, and python interface.</para>
168 <orderedlist>
169 <listitem>
170 <para>Command-Line</para>
171 <para>The command-line interface allows to use MoleCuilder
172 non-interactively via a terminal session. The program is executed by
173appending to the shell command a number of commands including all
174 required options that are then executed one after the other. After
175 execution of the last command, the program quits. The command-line
176 interface usually works on a specific file that is given as input,
177 manipulated, analysed, ... via the sequence of commands and
178 eventually all changes are stored in the this file. Hence, the input
179 file acts as the state of the starting configuration that is
180 modified via MoleCuilder.</para>
181 </listitem>
182 <listitem>
183 <para>Text menu</para>
184 <para>The text-menu is similar to the command-line interface with
185 the exception that it allows for interactive sessions. Commands are
186 chosen from a text menu and executed directly after selection by the
187 user.</para>
188 </listitem>
189 <listitem>
190 <para>Graphical interface</para>
191 <para>The graphical interface is based on Qt. It features a full graphical, three-dimensional
192representation of the simulation domain with atoms and
193 their bonds. It allows manipulation in point&amp;click fashion.
194 Commands are selected from pull-down menus and dialogs are used to
195 query the user for all required parameters to such a command.</para>
196 </listitem>
197 <listitem>
198 <para>Python interface</para>
199 <para>The last interface is accessible only within the python
200 programming language. MoleCuilder can be loaded as a module and its
201 commands can be executed with either the python interpreter
202 interactively or via python scripts non-interactively. Note that
203 this allows auxiliary calculations to be performed in pythons whose
204 results may be used as parameters in subsequent commands.</para>
205 </listitem>
206 </orderedlist>
207 </section>
208 <section xml:id="fileformats">
209 <title xml:id="fileformats.title">Known File formats</title>
210 <para>We briefly list the file formats MoleCuilder can parse and
211 store. We refer to external websites for more detailed information where appropriate.</para>
212 <itemizedlist>
213 <listitem>
214 <para>XYZ, <filename>.xyz</filename> (simplest of all formats,
215 line-wise element and three coordinates with two line header, number
216 of lines and a comment line)</para>
217 </listitem>
218 <listitem>
219 <para><link xlink:href="http://www.mpqc.org/">
220 <productname>MPQC </productname>
221 </link>, <filename>.in</filename></para>
222 </listitem>
223 <listitem>
224 <para><link xlink:href="http://www.pdb.org/">PDB</link>, <filename> .pdb</filename></para>
225 </listitem>
226 <listitem>
227 <para><productname>ESPACK</productname>, <filename>.conf</filename>
228 (electronic structure package by Institute for Numerical Simulation,
229 University of Bonn, code not in circulation)</para>
230 </listitem>
231 <listitem>
232 <para><link xlink:href="http://www.psicode.org/">
233 <productname>PSI4 </productname>
234 </link>, <filename>.psi</filename></para>
235 </listitem>
236 <listitem>
237 <para><link xlink:href="http://www.tremolo-x.org/">
238 <productname> TREMOLO</productname>
239 </link>, <filename>.data</filename></para>
240 </listitem>
241 <listitem>
242 <para>XML, <filename>.xml</filename> (XML as read by
243 <link xlink:href="http://www.scafacos.org/">ScaFaCoS</link>
244 project)</para>
245 </listitem>
246 </itemizedlist>
247 <para>These are identified via their suffixes and can be converted from
248 one into another (with possible loss of data outside of the intersection of
249 stored properties of the two involved file formats).</para>
250 </section>
251 </chapter>
252 <chapter>
253 <title>Interfaces</title>
254 <para>In this chapter, we explain the intention and use of the four
255 interfaces.</para>
256 <para>We will give the most extensive explanation of the command-line
257 interface, all subsequent interfaces are explained in highlighting their
258 differences with respect to the command-line interface. This is because
259 the command-line lends itself very well to representation in this textual
260 user guide. Although some images of the graphical interface are given
261 below, they would blow the size of the guide out of proportion.</para>
262 <para>In any case, you should make yourself familiar with at least one of
263 the interactive (text menu, GUI) and one of the non-interactive
264 (command-line, python) interfaces to use MoleCuilder to its full potential:
265 The interactive interface gives you the immediate feedback in constructing
266 &quot;synthesis&quot; (build) chains (of commands) for constructing your specific
267 molecular system in the computer. The non-interactive interface lends
268 itself to quick creation of related systems that differ only by specific
269 parameters you have modified in the script (command-line can be used in
270 shell scripts, python itself is a scripted language). Also, the
271 non-interactive interfaces are used for storing sessions which helps you
272 in documentation your experiments and later on understanding of what has
273 been actually created by the prescribed commands, i.e. debugging.</para>
274 <section xml:id="command-line-interface">
275 <title xml:id="command-line-interface.title">Command-line interface</title>
276 <para>The command-line interface reads options and commands from the
277 command line and executes them sequentially. This may be for example:
278 Open an empty file, add 2 hydrogen atoms and add 1 oxygen atom, recognize the bond graph, choose a
279 simulation box, fill the box with this given &quot;filler&quot; molecule, save the
280 file. This enables the use of MoleCuilder in simple script-files to
281 create a whole range of geometries that only differ in a few parameters
282 automatically.</para>
283 <para>Traditionally, <command>MoleCuilder</command> operates on a single
284 configuration file - the state - which may also store additional
285 information depending on the chosen file format such as parameters for
286 ab-initio computations. To some small extent <command>MoleCuilder</command> also allows manipulation of these paramters. An example for the above procedure is given
287 below:</para>
288 <programlisting>
289 ./molecuilder \
290 -i sample.xyz \
291 --add-atom H \
292 --domain-position &quot;0.,0.,0.&quot; \
293 ...
294 </programlisting>
295 <para>The first argument is the executable itself. Second, there is a
296 slew of arguments -- one per line split with a backslash telling the comman
297 shell that the line still continues -- consisting of the input action and
298 an arbitrarily named file <filename>sample.xyz</filename>, which may be
299 empty and whose file format is chosen by the given extension. The third
300 is the add-atom action following by an option that gives the position in
301 the domain where to add the &quot;H&quot;ydrogen atom. An action is always
302 introduced via a double hyphen and its full name (containing just
303 non-capital letters and hyphens) or a single hyphen and a single letter
304 for its shortform, such as <emphasis role="bold"> -a</emphasis> for adding an atom to the system. It is
305 followed by a fixed number of options. Most of these have default values
306 and in this do not have to be specified.</para>
307 <formalpara><title>Invalid values</title><para>Certain options accept only very specific input. For example, the option value associated with <emphasis role="bold">add-atom</emphasis></para>, i.e. the chemical element, can only be one of the chemical symbols that exist and not any arbitrary string. Each option value is checked on parsing the command-line. If any value is not valid, an error message is given and none of the actions is executed.</formalpara>
308 <formalpara>
309 <title>Shortforms of Actions</title>
310 <para>Note that not all action have shortforms and it is best practice
311 to have the full action name instead of its shortform to make the
312 command-line comprehendable to you in years to come.</para>
313 </formalpara>
314 <note>
315 <para>Note further that when placing a slew of commands in a script file it is generally recommended to use the above formatting: One command or option per line and each</para>
316 <para>option receives an extra tab for indentation.</para>
317 </note>
318 <section xml:id="preliminaries">
319 <title xml:id="preliminaries.title">Preliminaries</title>
320 <para>Some preliminary remarks are in order which we have gathered
321 here on how these actions work in general.</para>
322 <para>We first delve into some details about secondary structure
323 such as selections, shapes, and randomization required to specify
324 subsets of atoms and molecules you wish to manipulate. Then, we have
325give the details on the manipulation ordered by the
326 scale they act upon - single atoms, multiple atoms organized as
327 molecules, and all atoms organized by their containing domain.</para>
328 <para>In the following we will always give a command to illustrate the
329 procedure but just its necessary parts, i.e. &quot;...&quot; implies to prepend
330 it with the executable and input command for a specific configuration
331 file, for storing the manipulated state of the molecular system. </para>
332 <para>So if we write</para>
333 <programlisting>... --help</programlisting>
334 <para>Then we actually mean you to write</para>
335 <programlisting>./molecuilder --help</programlisting>
336 <para>Note that this specific exemplary command is very useful as it will always give you a list of all available actions and also a
337 brief explanation on how to properly enter values of a specific type,
338 e.g. an element, a vector, or a list of numbers. Details to a specific
339 action can be requested when its full name is known, e.g. for
340 &quot;add-atom&quot;,</para>
341 <programlisting>./molecuilder --help add-atom</programlisting>
342 <para>which fills you in on each option to the action: its full name,
343 its expected type, and a possibly present default value, and a brief
344 description of the option.</para>
345 <para>An Action can be undone and redone, e.g. undo adding an atom as
346 follows,</para>
347 <programlisting>... --add-atom H --domain-position &quot;0,0,0&quot; --undo</programlisting>
348 <para>and redo as follows</para>
349 <programlisting>... --add-atom H --domain-position &quot;0,0,0&quot; --undo --redo</programlisting>
350 <para>With the non-interactive interfaces this may seem rather
351 superfluous but it comes in very handy in the interactive ones. Also
352 this should tell you that actions are placed internally in a queue, i.e. a history,
353 that undo and redo manipulate.</para>
354 <para>Due to a current limitation of the implementation each command can be used on the command-line only once. Note that this <emphasis role="italic">only</emphasis> applies to the command-line interface. All other interfaces, especially all interactive ones, do not have such a restriction. For the command-line interface there are several ways to work around it. Either by splitting the whole chain of commands into several chunks, each using only unique commands and using the input file (the state) to contain and transport the intermediate stages as input for the next stage. Or to switch to other commands: often there are several possible ways of achieving a goal, especially when using selections.</para>
355 <para>Being done now with the preliminaries we now go through all available actions present in MoleCuilder.</para>
356 </section>
357 <section xml:id="fileparsers">
358 <title xml:id="fileparsers.title">File parsers</title>
359 <para>We have already given a list of all known file formats, see
360 <link linkend="fileformats">File formats</link>. Next, we explain how these
361 file formats are picked and manipulated.</para>
362 <section xml:id="fileparsers.parsing">
363 <title xml:id="fileparsers.parsing.title">Parsing files</title>
364 <para>We already discussed that the command-line interface works
365 state-based and hence you should supply it with a file to work
366 on.</para>
367 <programlisting>... --input water.data</programlisting>
368 <para>This will load all information, especially atoms with their
369 element and position, from the file <filename>water.data</filename>
370 into the state. Most importantly, all changes will eventually be stored to this file,
371 or to files with the prefix <filename>water</filename> and suffixes
372 of desired file formats, e.g. <filename>water.in</filename> if you
373 specified <productname>MPQC</productname>.</para>
374 <programlisting>... --load morewater.xyz</programlisting>
375 <para>This will load another file <filename>water.xyz</filename>,
376 however changes will still be written to files prefixed with
377 <filename>water</filename> as designated by the <emphasis role="bold">input</emphasis> command. Note that now already two state files
378 will stored, <filename>water.data</filename> and
379 <filename>water.xyz</filename> as these two different file formats
380 have been used. This is the default behavior: any additional file format used in loading is registered internally and the output file will then be written in all registered formats on exit.</para>
381 </section>
382 <section xml:id="fileparsers.set-output">
383 <title xml:id="fileparsers.set-output.tile">Adding output file formats</title>
384 <para>We already know that loading a file also picks a file format
385 by its suffix. We may add further file formats to which the state of
386 the molecular system is written to on program exit.</para>
387 <programlisting>... --set-output mpqc tremolo</programlisting>
388 <para>This will store the final state of the molecular systems as
389 <productname>MPQC</productname> and as
390 <productname>TREMOLO</productname> configuration file. See
391 <link linkend="fileformats">File formats</link> for the list of all file formats available.</para>
392 </section>
393 <section xml:id="fileparsers.output-as">
394 <title xml:id="fileparsers.output-as.title">Output the World</title>
395 <para>This will store the current World, i.e. all its atoms, to a
396 given file, where the output format is determined from the file
397 suffix.</para>
398 <programlisting>... --output-as world.xyz</programlisting>
399 <para>This will be automatically done on program exit, but in case an intermediate state is required (making sense for interactive and python interfaces), this command can be used.</para>
400 </section>
401 <section xml:id="fileparsers.save-selected-molecules">
402 <title xml:id="fileparsers.save-selected-molecules.title">Output the current molecular system</title>
403 <para>This will store all atoms contained in the currently selected
404 molecules to file. This is different to<emphasis role="bold">store-saturated-fragment</emphasis>
405 as it will not saturate dangling bonds because only whole molecules,
406 i.e. whose bond graph is connected, will be stored.</para>
407 <programlisting>... --save-selected-molecules waters.pdb
408 </programlisting>
409 </section>
410 </section>
411 <section xml:id="selections">
412 <title xml:id="selections.title">Selections and unselections</title>
413 <para>In order to tell MoleCuilder on what subset of atoms a specific
414 Action is to be performed, there are <emphasis>selection actions</emphasis>. Note that a selection per se does not change
415 anything in the state of the molecular system in any way. Essentially, it is just a filter.</para>
416 <para>Selections either work on atoms, on molecules, or on shapes
417 (this we explain later on). A given selection is maintained from the
418 execution of the selection action to the end of program or until
419 modified by another selection applied on the same type (atom,
420 molecule, shape). Selections are not stored to file (i.e. do not belong to the state).</para>
421 <para>We only give here a brief list on the available kind of selections for each of the three types they work on.
422Each action is executed either as follows, exemplified by selecting
423 all atoms.</para>
424 <programlisting>.... --select-all-atoms</programlisting>
425 <para>or, exemplified by unselecting the last molecule,</para>
426 <programlisting>... --unselect-molecule-by-order -1</programlisting>
427 <para>i.e. they are prepended by either <emphasis role="bold">select</emphasis> or <emphasis role="bold">unselect</emphasis>.</para>
428 <itemizedlist>
429 <listitem>
430 <para>Atoms</para>
431 <itemizedlist>
432 <listitem>
433 <para>All</para>
434 <programlisting>
435 ... --select-all-atoms
436 </programlisting>
437 </listitem>
438 <listitem>
439 <para>None</para>
440 <programlisting>
441 ... --unselect-all-atoms
442 </programlisting>
443 <programlisting>
444 ... --clear-atom-selection
445 </programlisting>
446 </listitem>
447 <listitem>
448 <para>Invert selection</para>
449 <programlisting>
450 ... --invert-atoms
451 </programlisting>
452 </listitem>
453 <listitem>
454 <para>By Element (all hydrogen atoms, all sulphur atoms,
455 ...)</para>
456 <programlisting>
457 ... --select-atom-by-element 1
458 </programlisting>
459 <programlisting>
460 ... --unselect-atom-by-element 1
461 </programlisting>
462 </listitem>
463 <listitem>
464 <para>By Id (atom with id 76)</para>
465 <programlisting>
466 ... --select-atom-by-id 76
467 </programlisting>
468 <programlisting>
469 ... --unselect-atom-by-id 76
470 </programlisting>
471 </listitem>
472 <listitem>
473 <para>By Order (the first (1), the second, ... the last
474 created(-1), the last but one)</para>
475 <programlisting>
476 ... --select-atom-by-order 1
477 </programlisting>
478 <programlisting>
479 ... --unselect-atom-by-order -2
480 </programlisting>
481 </listitem>
482 <listitem>
483 <para>By Shape (all atoms inside the volume specified by the currently selected shape)</para>
484 <programlisting>
485 ... --select-atom-inside-volume
486 </programlisting>
487 <programlisting>
488 ... --unselect-atoms-inside-volume
489 </programlisting>
490 </listitem>
491 <listitem>
492 <para>By Molecule (all atoms belonging to currently selected
493 molecules)</para>
494 <programlisting>
495 ... --select-molecules-atoms
496 </programlisting>
497 <programlisting>
498 ... --unselect-molecules-atoms
499 </programlisting>
500 </listitem>
501 <listitem>
502 <para>Push/Pop the current selection to/from a stack to store
503 it momentarily and allow modifications in MakroActions (this is very specific and used mostly internally).</para>
504 <programlisting>
505 ... --push-atom-selection
506 </programlisting>
507 <programlisting>
508 ... --pop-atom-selection
509 </programlisting>
510 </listitem>
511 </itemizedlist>
512 </listitem>
513 <listitem>
514 <para>Molecules</para>
515 <itemizedlist>
516 <listitem>
517 <para>All</para>
518 <programlisting>
519 ... --select-all-molecules
520 </programlisting>
521 </listitem>
522 <listitem>
523 <para>None</para>
524 <programlisting>
525 ... --unselect-all-molecules
526 </programlisting>
527 <programlisting>
528 ... --clear-molecule-selection
529 </programlisting>
530 </listitem>
531 <listitem>
532 <para>Invert selection</para>
533 <programlisting>
534 ... --invert-molecules
535 </programlisting>
536 </listitem>
537 <listitem>
538 <para>By Id (molecule with id 4)</para>
539 <programlisting>
540 ... --select-molecule-by-id 2
541 </programlisting>
542 <programlisting>
543 ... --unselect-molecule-by-id 2
544 </programlisting>
545 </listitem>
546 <listitem>
547 <para>By Order (first created molecule, second created
548 molecule, ...)</para>
549 <programlisting>
550 ... --select-molecule-by-order 2
551 </programlisting>
552 <programlisting>
553 ... --unselect-molecule-by-order -2
554 </programlisting>
555 </listitem>
556 <listitem>
557 <para>By Formula (molecule with H2O as formula)</para>
558 <programlisting>
559 ... --select-molecules-by-formula &quot;H2O&quot;
560 </programlisting>
561 <programlisting>
562 ... --unselect-molecules-by-formula &quot;H2O&quot;
563 </programlisting>
564 </listitem>
565 <listitem>
566 <para>By Name (all molecules named &quot;water4&quot;)</para>
567 <programlisting>
568 ... --select-molecules-by-name &quot;water4&quot;
569 </programlisting>
570 <programlisting>
571 ... --unselect-molecules-by-name &quot;water4&quot;
572 </programlisting>
573 </listitem>
574 <listitem>
575 <para>By Atom (all molecules for which at least one atom is
576 currently selected)</para>
577 <programlisting>
578 ... --select-atoms-molecules
579 </programlisting>
580 <programlisting>
581 ... --unselect-atoms-molecules
582 </programlisting>
583 </listitem>
584 <listitem>
585 <para>Push/Pop the current selection to/from a stack to store
586 it momentarily and allow modifications in MakroActions.</para>
587 <programlisting>
588 ... --push-molecule-selection
589 </programlisting>
590 <programlisting>
591 ... --pop-molecule-selection
592 </programlisting>
593 </listitem>
594 </itemizedlist>
595 </listitem>
596 <listitem>
597 <para>Shapes</para>
598 <itemizedlist>
599 <listitem>
600 <para>All</para>
601 <programlisting>
602 ... --select-all-shapes
603 </programlisting>
604 </listitem>
605 <listitem>
606 <para>None</para>
607 <programlisting>
608 ... --unselect-all-shapes
609 </programlisting>
610 </listitem>
611 <listitem>
612 <para>By Name (all shapes named &quot;sphere1&quot;)</para>
613 <programlisting>
614 ... --select-shape-by-name &quot;sphere1&quot;
615 </programlisting>
616 <programlisting>
617 ... --unselect-shape-by-name &quot;sphere1&quot;
618 </programlisting>
619 </listitem>
620 </itemizedlist>
621 </listitem>
622 </itemizedlist>
623 <remark>Note that an unselected instance (e.g. an atom) remains unselected upon further unselection and vice versa with selection.</remark>
624 <para>These above selections work then in conjunction with other
625 actions and make them very powerful, e.g. you can remove all atoms
626 inside a sphere by a selecting the spherical shape and subsequently
627 selecting all atoms inside the shape and then removing them.</para>
628 </section>
629 <section xml:id="shapes">
630 <title xml:id="shapes.title">Shapes</title>
631 <para>Shapes are specific regions of the domain. There are just a few
632 so-called <emphasis>primitive</emphasis> shapes such as cuboid,
633 sphere, cylinder, the whole domain, or none of it. However, these can be
634 combined via boolean operations such as and, or, and not. This
635 approach is called <emphasis>constructive geometry</emphasis>. E.g. by
636 combining a sphere with the negated (<emphasis role="italic">not</emphasis> operation) of a smaller sphere, we
637 obtain a spherical surface of specific thickness.</para>
638 <section xml:id="shapes.create-shape">
639 <title xml:id="shapes.create-shape.title">Creating shapes</title>
640 <para>Primitive shapes can be created as follows,</para>
641 <programlisting>
642 ... --create-shape \
643 --shape-type sphere \
644 --shape-name &quot;sphere1&quot; \
645 --stretch &quot;2,2,2&quot; \
646 --translation &quot;5,5,5&quot;
647 </programlisting>
648 <para>This will create a sphere of radius 2 (initial radius is 1)
649 with name &quot;sphere1&quot; that is centered at (5,5,5). Other primitives are
650 cuboid and cylinder, where a rotation can be specified as
651 follows.</para>
652 <programlisting><programlisting>
653 ... --create-shape \
654 --shape-type cuboid \
655 --shape-name &quot;box&quot; \
656 --stretch &quot;1,2,2&quot; \
657 --translation &quot;5,5,5&quot; \
658 --angle-x &quot;90&quot;
659 </programlisting>
660 ... --create-shape \
661 --shape-type cylinder \
662 --shape-name &quot;cylinder&quot; \
663 --stretch &quot;1,2,2&quot; \
664 --translation &quot;5,5,5&quot; \
665 --angle-y &quot;90&quot;
666 </programlisting>
667 </section>
668 <section xml:id="shapes.combine-shapes">
669 <title xml:id="shapes.combine-shapes.title">Combining shapes</title>
670 <para>Any two shapes can be combined by boolean operations as follows</para>
671 <programlisting>
672 ... --combine-shapes \
673 --shape-name &quot;combinedshape&quot; \
674 --shape-op &quot;AND&quot;
675 </programlisting>
676 <para>This will combine two currently selected shapes vis the &quot;AND&quot; operation
677 and create a new shape called &quot;combinedshape&quot;. Note that the two old shapes
678 are still present after this operation. We briefly explain each operation:
679 </para>
680 <itemizedlist>
681 <listitem>
682 <para><emphasis>AND</emphasis> combines two currently selected shapes
683 into a new shape that consists of only the volume where shapes overlap.</para>
684 </listitem>
685 <listitem>
686 <para><emphasis>OR</emphasis> combines two currently selected shapes
687 into a new shape that consists of all the volume that either shape
688 occupies.</para>
689 </listitem>
690 <listitem>
691 <para><emphasis>NOT</emphasis> creates the inverse to a currently selected
692 single shape that contains the volume with respect to the simulation domain
693 that the present one does not.</para>
694 </listitem>
695 </itemizedlist>
696 </section>
697 <section xml:id="shapes.remove-shape">
698 <title xml:id="shapes.remove-shape.title">Removing shapes</title>
699 <para>Removing a shape is as simple as removing an atom.</para>
700 <programlisting>... --remove-shape </programlisting>
701 <para>This removes all currently selected shapes.</para>
702 </section>
703 <section xml:id="shapes.manipulation">
704 <title xml:id="shapes.manipulation.title">Manipulating shapes</title>
705 <para>Shapes can be stretched, scaled, rotated, and translated to
706 modify primitives or combined primitive shapes. As you have seen
707 this manipulation could have occurred already at creation but we may also
708do it later on. As usual, we just list examples of the various manipulations
709 below, each of them works on the currently selected shapes.</para>
710 <programlisting>
711 ... --stretch-shapes &quot;1,1,2&quot; \
712 --stretch-center &quot;5,5,5&quot;
713 </programlisting>
714 <para>This stretches the shapes relative to the center at (5,5,5)
715 (default is origin) by a factor of 2 in the z direction.</para>
716 <programlisting>
717 ... --rotate-shapes \
718 --center &quot;10,2,2&quot; \
719 --angle-x 90 \
720 --angle-y 0 \
721 --angle-z 0
722 </programlisting>
723 <para>This way all selected shapes are rotated by 90 degrees around
724 the x axis with respect to the center at (10,2,2).</para>
725 <programlisting>... --translate-shapes &quot;5,0,0&quot; </programlisting>
726 <para>This translates all selected shapes by 5 along the x
727 axis.</para>
728 </section>
729 </section>
730 <section xml:id="randomization">
731 <title xml:id="randomization.title">Randomization</title>
732 <para>Some operations require randomness as input, e.g. when filling a
733 domain with molecules these may be randomly translated and rotated.
734 Random values are obtained by a random number generator that consists
735 of two parts: engine and distribution. The engine yields a <emphasis role="italic">uniform</emphasis> set
736 of random numbers in a specific interval, the distribution modifies
737 them, e.g. to become gaussian.</para>
738 <para>There are several Actions to modify the specific engine and
739 distribution and their parameters. One example usage is that with the
740 aforementioned filling of the domain (see below) molecules are rotated randomly.
741 If you specify a random number generator that randomly just spills out
742 values 0,1,2,3, then the randomness is just the orientation of the
743 molecule with respect to a specific axis: x,y,z. (rotation is at most
744 360 degrees and 0,1,2,3 act as divisor, hence rotation angle will then be always
745 a multiple of 90 degrees).</para>
746 <programlisting>
747 ... --set-random-number-distribution &quot;uniform_int&quot; \
748 --random-number-distribution-parameters &quot;p=1&quot;
749 </programlisting>
750 <para>This changes the distribution to &quot;uniform_int&quot;, i.e. integer
751 numbers that are distributed uniformly.</para>
752 <programlisting>
753 ... --set-random-number-engine &quot;mt19937&quot; \
754 --random-numner-engine-parameters &quot;seed=10&quot;
755 </programlisting>
756 <para>Specifying the seed allows you to obtain the same sequence of
757 random numbers for testing purposes.</para>
758 </section>
759 <section xml:id="atoms">
760 <title xml:id="atoms.title">Manipulate atoms</title>
761 <para>Here, we explain in detail how to add, remove atoms, change its
762 element type, scale the bond in between or measure the bond length or
763 angle.</para>
764 <section xml:id="atoms.add-atom">
765 <title xml:id="atoms.add-atom.title">Adding atoms</title>
766 <para>Adding an atom to the domain requires the element of the atom
767 and its coordinates as follows,</para>
768 <programlisting>
769 ... --add-atom O \
770 --domain-position &quot;2.,3.,2.35&quot;
771 </programlisting>
772 <para>where the element is given via its chemical symbol and the
773 vector gives the position within the domain</para>
774 </section>
775 <section xml:id="atoms.remove-atom">
776 <title xml:id="atoms.remove-atom.title">Removing atoms</title>
777 <para>Removing atom(s) does not need any option and operates on the
778 currently selected ones.</para>
779 <programlisting>... --remove-atom</programlisting>
780 </section>
781 <section xml:id="atoms.saturate-atom">
782 <title xml:id="atoms.saturate-atom.title">Saturating atoms</title>
783 <para>Newly instantiated atoms have no bonds to any other atom. If
784 you want to fill up their valence by a slew of hydrogen atoms
785 residing on a sphere around this atom, use this action.</para>
786 <programlisting>
787 ... --saturate-atoms
788 </programlisting>
789 <para>A number of hydrogen atoms is added around each selected atom corresponding to the valence of the chemical element. The hydrogen atoms are placed in the same
790 distance to this atom and approximately with same distance to their
791 nearest neighbors. Already present bonds (i.e. the position of neighboring atoms) is taken into account.</para>
792 </section>
793 <section xml:id="atoms.translate-atom">
794 <title xml:id="atoms.translate-atom.title">Translating atoms</title>
795 <para>In order to translate the current selected subset of atoms you
796have to specify a translation vector.</para>
797 <programlisting>
798 ... --translate-atoms &quot;-1,0,0&quot; \
799 --periodic 0
800 </programlisting>
801 <para>This translates all atoms by &quot;-1&quot; along the x axis and does not
802 mind the boundary conditions, i.e. it might shift atoms outside of the
803 domain.</para>
804 </section>
805 <section xml:id="atoms.mirror-atoms">
806 <title xml:id="atoms.mirror-atoms.title">Mirroring atoms</title>
807 <para>Present (and selected) atoms can be mirrored with respect to
808 a certain plane. You have to specify the normal vector of the plane
809 and the offset with respect to the origin as follows</para>
810 <programlisting>
811 ... --mirror-atoms &quot;1,0,0&quot; \
812 --plane-offset 10.1 \
813 --periodic 0
814 </programlisting>
815 </section>
816 <section xml:id="atoms.translate-to-origin">
817 <title xml:id="atoms.translate-to-origin.title">Translating atoms to origin</title>
818 <para>The following Action is convenient to place a subset of atoms
819 at a known position, the origin, and then translate them to some other
820 absolute coordinate. It calculates the average position of the set
821 of selected atoms and then translates all atoms by the negative of
822 this center, i.e. the center over all selected atoms is afterwards at the origin.</para>
823 <programlisting>... --translate-to-origin</programlisting>
824 <para>Note that this naturally does not heed the boundary conditions of the simulation domain.</para>
825 </section>
826 <section xml:id="atoms.change-element">
827 <title xml:id="atoms.change-element.title">Changing an atoms element </title>
828 <para>You can easily turn lead or silver into gold, by selecting the
829 silver atom and calling the change element action.</para>
830 <programlisting>... --change-element Au</programlisting>
831 </section>
832 </section>
833 <section xml:id="bond">
834 <title xml:id="bond.title">Bond-related manipulation</title>
835 <para>Atoms can also be manipulated with respect to the bonds.
836 <remark>Note that with bonds we always mean covalent bonds.</remark> First, we explain how to modify the bond structure itself, then we go
837 in the details of using the bond information to change bond distance
838 and angles.</para>
839 <section xml:id="bond.create-adjacency">
840 <title xml:id="bond.create-adjacency.title">Creating a bond graph </title>
841 <para>In case you have loaded a configuration file with no bond
842 information, e.g. XYZ, it is necessary to create the bond graph.
843 This is done by a heuristic distance criterion.</para>
844 <programlisting>... --create-adjacency</programlisting>
845 <para>This uses by default a criterion based on van-der-Waals radii,
846 i.e. if we look at two atoms indexed by &quot;a&quot; and &quot;b&quot;</para>
847 <equation>
848 <title>V(a) + V(b) - \tau &lt; R_{ab} &lt; V(a) + V(b) + \tau</title>
849 <m:math display="block">
850 <m:mi>where V(.) is the lookup table for the radii for a given element and \tau is a threshold value, set to 0.4.</m:mi>
851 </m:math>
852 </equation>
853 <para>As a second option, you may load a file containing bond table
854 information.</para>
855 <programlisting>... --bond-table table.dat</programlisting>
856 <para>which would parse a file <filename>table.dat</filename> for a
857 table giving typical bond distances between elements a and b. These
858 are used in the above criterion as <inlineequation>
859 <m:math display="inline">
860 <m:mi>V(a,b)</m:mi>
861 </m:math>
862 </inlineequation> in place of <inlineequation>
863 <m:math display="inline">
864 <m:mi>V(a)+V(b)</m:mi>
865 </m:math>
866 </inlineequation>.</para>
867 </section>
868 <section xml:id="bond.destroy-adjacency">
869 <title xml:id="bond.destroy-adjacency.title">Destroying the bond graph</title>
870 <para>The bond graph can be removed completely (and all bonds along
871 with it).</para>
872 <programlisting>... --destroy-adjacency</programlisting>
873 </section>
874 <section xml:id="bond.correct-bonddegree">
875 <title xml:id="bond.correct-bonddegree.title">Correcting bond degrees</title>
876 <para>Typically, after loading an input file with bond information, e.g.
877 a PDB file, the bond graph is complete but we lack the weights. That
878 is we do not know whether a bond is single, double, triple, ...
879 This action corrects the bond degree by enforcing charge neutrality
880 among the connected atoms.
881 </para>
882 <para>This action is in fact quadratically scaling in the number of
883 atoms. Hence, for large systems this may take longer than expected.
884 </para>
885 <programlisting>... --correct-bonddegree</programlisting>
886 <para>However, in normal use scenarios the action is fast and linear scaling.</para>
887 </section>
888 <section xml:id="bond.depth-first-search">
889 <title xml:id="bond.depth-first-search.title">Analysing a bond graph</title>
890 <para>You can perform a depth-first search analysis that reveals
891 cycles and other graph-related information.</para>
892 <programlisting>... --depth-first-search</programlisting>
893 <para>Note that this will only print some information and has no other impact on the state.</para>
894 </section>
895 <section xml:id="bond.subgraph-dissection">
896 <title xml:id="bond.subgraph-dissection.title">Dissecting the molecular system into molecules</title>
897 <para>The bond graph information can be used to recognize the
898 molecules within the system. Imagine you have just loaded a PDB file
899 containing bond information. However, initially all atoms are dumped
900 into the same molecule. Before you can start manipulating, you need
901 to dissect the system into individual molecules. Note that this is
902 just structural information and does not change the state of the
903 system.</para>
904 <programlisting>... --subgraph-dissection</programlisting>
905 <para>This analyses the bond graph, removes all currently present molecules and creates new molecules that each contain a single connected
906 subgraph, hence the naming of the Action.</para>
907 </section>
908 <section xml:id="bond.update-molecules">
909 <title xml:id="bond.update-molecules.title">Updating molecule structure</title>
910 <para>When the bond information has changed, new molecules might
911 have formed, this action updates all the molecules by scanning
912 the connectedness of the bond graph of the molecular system.
913 </para>
914 <programlisting>... --update-molecules</programlisting>
915 </section>
916 <section xml:id="bond.adds-bond">
917 <title xml:id="bond.adds-bond.title">Adding a bond manually</title>
918 <para>When the automatically created adjacency or bond graph
919 contains faulty bonds or lacks some, you can add them manually.
920 </para>
921 <programlisting>... --add-bonds</programlisting>
922 <para>If two atoms are selected, the single bond in between is added, if not
923already present. If more than two atoms are selected, than the
924 bond between any pair of these is added.</para>
925 <note>
926 <para>This is especially useful in conjunction with the
927 fragmentation scheme (explained later on). If you want to know the contribution from
928 certain fragments whose subgraph is not connected, you can simply
929 make the associated subset of atoms connected by selecting all
930 bonds and adding the bonds.</para>
931 </note>
932 </section>
933 <section xml:id="bond.remove-bonds">
934 <title xml:id="bond.remove-bonds.title">Removing a bond manually </title>
935 <para>In much the same way as adding a bond, you can also remove a
936 bond.</para>
937 <programlisting>... --remove-bonds</programlisting>
938 <para>Similarly, if more than two atoms are selected, then all bonds
939 found between any pair of these is removed.</para>
940 </section>
941 <section xml:id="bond.save-bonds">
942 <title xml:id="bond.save-bonds.title">Saving bond information </title>
943 <para>Bond information can be saved to a file in <link xlink:href="http://www.molecuilder.com/">
944 <productname>TREMOLO </productname>
945 </link>&apos;s dbond style.</para>
946 <programlisting>... --save-bonds system.dbonds</programlisting>
947 <para>Similarly is the following Action which saves the bond
948 information as a simple list of one atomic id per line and in
949 the same line, separated by spaces, the ids of all atoms connected
950 to it.</para>
951 <programlisting>... --save-adjacency system.adj</programlisting>
952 <para>This corresponds to the <emphasis role="bold">bond-file</emphasis> Action.</para>
953 </section>
954 <section xml:id="fileparsers.bond-file">
955 <title xml:id="fileparsers.bond-file.title">Load extra bond information</title>
956 <para>The reverse Action of <emphasis role="bold">save-bonds</emphasis> is the following which loads bond information from the file <emphasis role="bold">water.dbond</emphasis>.</para>
957 <programlisting>... --bond-file water.dbond</programlisting>
958 <para>Note that because of the use of ids the bond file is intimately connected to the associated input file containing the atomic coordinates and thus both should parsed right after another and to the very beginning of any sequence of Actions.</para>
959 </section>
960 <section xml:id="bond.stretch-bond">
961 <title xml:id="bond.stretch-bond.title">Stretching a bond</title>
962 <para>Stretching a bond actually refers to translation of the
963 associated pair of atoms. However, this action will keep the rest of
964 the molecule to which both atoms belong to invariant as well.</para>
965 <programlisting>... --stretch-bond 1.2</programlisting>
966 <para>This scales the original bond distance to the new bond
967 distance 1.2, shifting the right hand side and the left hand side of
968 the molecule accordingly.</para>
969 <warning>
970 <para>this fails with aromatic rings (but you can always
971 undo).</para>
972 </warning>
973 </section>
974 <section xml:id="bond.change-bond-angle">
975 <title xml:id="bond.change-bond-angle.title">Changing a bond angle </title>
976 <para>In the same way as stretching a bond, you can change the angle
977 in between two bonds. This works if exactly three atoms are selected
978 and two pairs are bonded.</para>
979 <programlisting>... --change-bond-angle 90</programlisting>
980 <para>This will change the angle from its value to 90 degrees by
981 translating the two outer atoms of this triangle (the atom connected
982 to both other atoms serves as rotation joint).</para>
983 </section>
984 </section>
985 <section xml:id="molecule">
986 <title xml:id="molecule.title">Manipulate molecules</title>
987 <para>Molecules are agglomerations of atoms that are (covalently) bonded. Hence,
988 the Actions working on molecules differ from those working on atoms.
989 Joining two molecules can only be accomplished by adding a bond in
990 between, and in the reverse fashion splitting a molecule by removing
991some or even all bonds in between. The Actions below mostly deal with copying
992 molecules. Removing of molecules is done via selecting the molecule&apos;s
993 atoms and removing them, which removes the atoms as well.</para>
994 <note>
995 <para>Initially when you load a file via the input action all atoms
996 are placed in a single molecule despite any present bond
997 information, see <link linkend="fragmentation">Dissecting the molecular system into molecules</link></para>
998 </note>
999 <section xml:id="molecule.copy">
1000 <title xml:id="molecule.copy.title">Copy molecules</title>
1001 <para>A basic operation is to duplicate a molecule. This works on a
1002 single, currently selected molecule. Afterwards, we elaborate on a
1003 more complex manner of copying, filling a specific shape with
1004 molecules.</para>
1005 <programlisting>
1006 ... --copy-molecule \
1007 --position &quot;10,10,10&quot;
1008 </programlisting>
1009 <para>This action copies the selected molecule and inserts it at the
1010 position (10,10,10) in the domain with respect to the molecule&apos;s
1011 center. In effect, it copies all the atoms of the original molecule
1012 and adds new bonds in between these copied atoms such that their
1013 bond subgraphs are identical.</para>
1014 </section>
1015 <section xml:id="molecule.change-molname">
1016 <title xml:id="molecule.change-molname.title">Change a molecules name</title>
1017 <para>You can change the name of a molecule which is important for
1018 selection.</para>
1019 <programlisting>... -change-molname &quot;test</programlisting>
1020 <para>This will change the name of the (only) selected molecule to
1021 &quot;test&quot;.</para>
1022 <para>Connected with this is the default name an unknown molecule
1023 gets.</para>
1024 <programlisting>... --default-molname test</programlisting>
1025 <para>This will change the default name of new molecules to
1026 &quot;test&quot;.</para>
1027 <note>
1028 <para>Note that a molecule loaded from file gets the filename
1029 (without suffix) as its name.</para>
1030 </note>
1031 </section>
1032 <section xml:id="molecule.remove-molecule">
1033 <title xml:id="molecule.remove-molecule.title">Remove molecules </title>
1034 <para>This removes one or multiple selected molecules.</para>
1035 <programlisting>... -remove-molecule</programlisting>
1036 <para>This essentially just removes all of the molecules&apos; atoms
1037 which in turn also causes the removal of the molecule.</para>
1038 </section>
1039 <section xml:id="molecule.translate-molecules">
1040 <title xml:id="molecule.translate-molecules.title">Translate molecules </title>
1041 <para>This translates one or multiple selected molecules by a
1042 specific offset..</para>
1043 <programlisting>... -translate-molecules</programlisting>
1044 <para>As before, this is actually just an operation on all of the molecule&apos;s atoms, namely translating them.</para>
1045 </section>
1046 <section xml:id="molecule.rotate-around-self">
1047 <title xml:id="molecule.rotate-around-self.title">Rotate around self </title>
1048 <para>You can rotate a molecule around its own axis.</para>
1049 <programlisting>
1050 ... --rotate-around-self &quot;90&quot; \
1051 --axis &quot;0,0,1&quot;
1052 </programlisting>
1053 <para>This rotates the molecule around the z axis by 90 degrees as
1054 if the origin were at its wn center of origin.</para>
1055 </section>
1056 <section xml:id="molecule.rotate-around-origin">
1057 <title xml:id="molecule.rotate-around-origin.title">Rotate around origin</title>
1058 <para>In the same manner the molecule can be rotated around an
1059 external origin.</para>
1060 <programlisting>
1061 ... --rotate-around-origin 90 \
1062 --position &quot;0,0,1&quot;\
1063 </programlisting>
1064 <para>This rotates the molecule around an axis from the origin to
1065 the position (0,0,1), i.e. around the z axis, by 90 degrees.</para>
1066 </section>
1067 <section xml:id="molecule.rotate-to-principal-axis-system">
1068 <title xml:id="molecule.rotate-to-principal-axis-system.title"> Rotate to principal axis system</title>
1069 <para>The principal axis system is given by an ellipsoid that mostly
1070 matches the molecules shape. The principal axis system can be
1071 simply determined by</para>
1072 <programlisting>... --principal-axis-system</programlisting>
1073 <para>To rotate the molecule around itself to align with this system
1074 do as follows</para>
1075 <programlisting>... --rotate-to-principal-axis-system &quot;0,0,1&quot;
1076 </programlisting>
1077 <para>This rotates the molecule in such a manner that the ellipsoids
1078 largest axis is aligned with the z axis. <remark>Note that &quot;0,0,-1&quot; would align anti-parallel.</remark></para>
1079 </section>
1080 <section xml:id="molecule.verlet-integration">
1081 <title xml:id="molecule.verlet-integration.title">Perform verlet integration</title>
1082 <para>Atoms not only have a position, but each instance also stores
1083 velocity and a force vector. These can be used in a velocity verlet
1084 integration step. Velocity verlet is an often employed time
1085 integration algorithm in molecular dynamics simulations.</para>
1086 <programlisting>
1087 ... --verlet-integration \
1088 --deltat 0.1 \
1089 --keep-fixed-CenterOfMass 0
1090 </programlisting>
1091 <para>This will integrate with a timestep of <inlineequation>
1092 <m:math display="inline">
1093 <m:mi>\Delta_t = 0.1</m:mi>
1094 </m:math>
1095 </inlineequation>and correcting forces and velocities such that
1096 the sum over all atoms is zero.</para>
1097 </section>
1098 <section xml:id="molecule.force-annealing">
1099 <title xml:id="molecule.force-annealing.title">Anneal the atomic forces</title>
1100 <para>This will shift the atoms in a such a way as to decrease (or
1101 anneal) the forces acting upon them.</para>
1102 <para>Forces may either be already present for the set of atoms by
1103 some other way (e.g. from a prior fragmentation calculation) or,
1104 as shown here, loaded from an external file. We anneal the forces for
1105 one step with a certain initial step width of 0.5 atomic time
1106 units and do not create a new timestep for each optimization
1107 step.</para>
1108 <programlisting>
1109 ... --force-annealing \
1110 --forces-file test.forces \
1111 --deltat 0.5 \
1112 --steps 1 \
1113 --output-every-step 0
1114 </programlisting>
1115 </section>
1116 <section xml:id="molecule.linear-interpolation-of-trajectories">
1117 <title xml:id="molecule.linear-interpolation-of-trajectories.title"> Linear interpolation between configurations</title>
1118 <para>This is similar to verlet integration, only that it performs
1119 a linear integration irrespective of the acting atomic forces.
1120 </para>
1121 <para>The following call will produce an interpolation between the
1122 configurations in time step 0 and time step 1 with 98 intermediate
1123 steps, i.e. current step 1 will end up in time step 99. In this
1124 case an identity mapping is used to associated atoms in start and
1125 end configuration.</para>
1126 <programlisting>
1127 ... --linear-interpolation-of-trajectories \
1128 --start-step 0 \
1129 --end-step 1 \
1130 --interpolation-steps 100 \
1131 --id-mapping 1
1132 </programlisting>
1133 </section>
1134 </section>
1135 <section xml:id="domain">
1136 <title xml:id="domain.title">Manipulate domain</title>
1137 <para>Here, we elaborate on how to duplicate all the atoms inside the
1138 domain, how to scale the coordinate system, how to center the atoms
1139 with respect to certain points, how to realign them by given
1140 constraints, how to mirror and most importantly how to specify the
1141 domain.</para>
1142 <section xml:id="domain.change-box">
1143 <title xml:id="domain.change-box.title">Changing the domain</title>
1144 <para>The domain is specified by a symmetric 3x3 matrix. The
1145 eigenvalues (diagonal entries in case of a diagonal matrix) give the
1146 length of the edges, additional entries specify transformations of
1147 the box such that it becomes a more general parallelepiped.</para>
1148 <programlisting>... change-box &quot;20,0,20,0,0,20&quot;</programlisting>
1149 <para>As the domain matrix is symmetric, six values suffice to fully
1150 specify it. We have to give the six components of the lower triangle matrix. Here, we change the box to a cuboid of equal edge length of
1151 20.<warning>
1152 <para>In case of the python interface an upper triangle matrix is given. Hence, the above would read &quot;20,0,0,20,0,20&quot;.</para>
1153 </warning></para>
1154 </section>
1155 <section xml:id="domain.bound-in-box">
1156 <title xml:id="domain.bound-in-box.title">Bound atoms inside box </title>
1157 <para>The following applies the current boundary conditions to the
1158 atoms. In case of periodic or wrapped boundary conditions the atoms
1159 will be periodically translated to be inside the domain
1160 again.</para>
1161 <programlisting>... --bound-in-box</programlisting>
1162 </section>
1163 <section xml:id="domain.center-in-box">
1164 <title xml:id="domain.center-in-box.title">Center atoms inside the domain</title>
1165 <para>This is a combination of changing the box and bounding the
1166 atoms inside it.</para>
1167 <programlisting>... --center-in-box &quot;20,0,20,0,0,20&quot;</programlisting>
1168 </section>
1169 <section xml:id="domain.center-edge">
1170 <title xml:id="domain.center-edge.title">Center the atoms at an edge</title>
1171 <para>MoleCuilder can calculate the minimum box (parallel to the
1172 cardinal axis) all atoms would fit in and translate all atoms in
1173 such a way that the lower, left, front edge of this minimum is at
1174 the origin (0,0,0).</para>
1175 <programlisting>... --center-edge</programlisting>
1176 </section>
1177 <section xml:id="domain.add-empty-boundary">
1178 <title xml:id="domain.add-empty-boundary.title">Extending the boundary by adding an empty boundary</title>
1179 <para>In the same manner as above a minimum box is determined that
1180 is subsequently expanded by a boundary of the given additional
1181 thickness. This applies to either side, i.e. left and right, top and bottom, front and back.</para>
1182 <programlisting>... --add-empty-boundary &quot;5,5,5&quot;</programlisting>
1183 <para>This will enlarge the box in such a way that every atom is at
1184 least by a distance of 5 away from the boundary of the domain (in
1185 the infinity norm).</para>
1186 </section>
1187 <section xml:id="domain.scale-box">
1188 <title xml:id="domain.scale-box.title">Scaling the box</title>
1189 <para>You can enlarge the domain by simple scaling factors.</para>
1190 <programlisting>... --scale-box &quot;1,1,2.5&quot;</programlisting>
1191 <para>Here, the domain is stretched in the z direction by a factor
1192 of 2.5.</para>
1193 </section>
1194 <section xml:id="domain.repeat-box">
1195 <title xml:id="domain.repeat-box.title">Repeating the box</title>
1196 <para>Under periodic boundary conditions often only the minimal
1197 periodic cell is stored. E.g. for a crystallic system this minimal cell is all that&apos;s needed to completely specify a larger body. If need be, multiple images can be easily
1198 added to the current state of the system by repeating the box, i.e.
1199 the box along with all contained atoms is copied and placed
1200 adjacently.</para>
1201 <programlisting>... --repeat-box &quot;1,2,2&quot;</programlisting>
1202 <para>This will create a 2x2 grid of the current domain, replicating
1203 it along the y and z direction along with all atoms. If the domain
1204 contained before a single water molecule, we will now have four of
1205 them.</para>
1206 </section>
1207 <section xml:id="domain.set-boundary-conditions">
1208 <title xml:id="domain.set-boundary-conditions.title">Change the boundary conditions</title>
1209 <para>Various boundary conditions can be applied that affect how
1210 certain Actions work, e.g. translate-atoms. We briefly give a list
1211 of all possible conditions:</para>
1212 <itemizedlist>
1213 <listitem>
1214 <para>Wrap</para>
1215 <para>Coordinates are wrapped to the other side of the domain,
1216 i.e. periodic boundary conditions.</para>
1217 </listitem>
1218 <listitem>
1219 <para>Bounce</para>
1220 <para>Coordinates are bounced back into the domain, i.e. they
1221 are reflected from the domain walls.</para>
1222 </listitem>
1223 <listitem>
1224 <para>Ignore</para>
1225 <para>No boundary conditions apply.</para>
1226 </listitem>
1227 </itemizedlist>
1228 <para>The following will set the boundary conditions to periodic.
1229 </para>
1230 <programlisting>... --set-boundary-conditions &quot;Wrap Wrap Wrap&quot;</programlisting>
1231 <para>Note that boundary conditions are not enforced unless explicitly requested, e.g. by the <emphasis role="bold">bound-in-box</emphasis> action</para>
1232 </section>
1233 </section>
1234 <section xml:id="filling">
1235 <title xml:id="filling.title">Filling</title>
1236 <para>Filling a specific part of the domain with one type of
1237 molecule, e.g. a water molecule, is the more advanced type of
1238 copying of a molecule (see <emphasis role="bold">copy-molecule</emphasis>) and for this we need several
1239 ingredients.</para>
1240 <para>First, we need to specify the part of the domain. This is done
1241 via a shape. We have already learned how to create and select
1242 shapes. The currently selected shape will serve as the fill-in
1243 region.</para>
1244 <para>Then, there are three types of filling: domain, volume, and
1245 surface. The domain is filled with a regular grid of fill-in points.
1246 A volume and a surface are filled by a set of equidistant points
1247 distributed within the volume or on the surface of a selected
1248 shape. The latter is closed connected to the respective shape selected. Molecules will then be copied and translated points when they
1249 &quot;fit&quot;. Note that not only primitive shape can be used for filling in molecules inside their volume or on their surface but also any kind of combined shape. </para>
1250 <remark>Note however that not all combinations may already be fully working.</remark>
1251 <para>The filler procedure checks each fill-in point whether there
1252 is enough space for the set of atoms. To this end, we require a cluster
1253 instead of a molecule. A cluster is more general than a molecule as it is not restricted to a connected subgraph with respect to the bond graph. A cluster is just a general agglomeration of atoms
1254 combined with a bounding box that contains all of them and serves as
1255 its minimal volume. I.e. we need such a cluster. For this a number of
1256 atoms have to be specified, the minimum bounding box is generated
1257 automatically by which it is checked whether sufficient space is available at the fill-in point.</para>
1258 <para>On top of that, molecules can be selected whose volume is
1259 additionally excluded from the filling region.</para>
1260 <section xml:id="filling.fill-regular-grid">
1261 <title xml:id="filling.fill-regular-grid.title">Fill the domain with molecules</title>
1262 <para>The call to fill the volume of the selected shape with the
1263 selected atoms is then as follows,</para>
1264 <programlisting>
1265 ... --fill-regular-grid \
1266 --mesh-size &quot;5,5,5&quot; \
1267 --mesh-offset &quot;.5,.5,.5&quot; \
1268 --DoRotate 1 \
1269 --min-distance 1. \
1270 --random-atom-displacement 0.05 \
1271 --random-molecule-displacement 0.4 \
1272 --tesselation-radius 2.5
1273 </programlisting>
1274 <para>This generates a cardinal grid of 5x5x5 fill-in points within the
1275 sphere that are offset such as to lie centered within the sphere, defined by a relative offset per axis in [0,1]. Hence, with an offset of &quot;0&quot; we have the points left-aligned, with &quot;0.5&quot; centered, and with &quot;1&quot; right-aligned. Additionally, each molecule is rotated
1276 by a random rotation matrix, each atom is translated randomly by at
1277 most 0.05, each molecule&apos;s center similarly but at most by 0.4. The selected
1278 molecules&apos; volume is obtained by tesselating their surface and
1279 excluding every fill-in point whose distance to this surface does
1280 not exceed 1. We refer to our comments in
1281 <link linkend="randomization">Randomization</link>for details on
1282 changing the randomness and obtaining some extra flexibility thereby.</para>
1283 </section>
1284 <section xml:id="filling.fill-volume">
1285 <title xml:id="filling.fill-volume.title">Fill a shape&apos;s volume with molecules</title>
1286 <para>More specifically than filling the whole domain with molecules,
1287 maybe except areas where other molecules already are, we also can
1288 fill only specific parts by selecting a shape and calling upon
1289 the following action:</para>
1290 <programlisting>
1291 ... --fill-volume \
1292 --counts 12 \
1293 --min-distance 1. \
1294 --DoRotate 1 \
1295 --random-atom-displacement 0.05 \
1296 --random-molecule-displacement 0.4 \
1297 --tesselation-radius 2.5
1298 </programlisting>
1299 <para>The specified option all have the same function as before. Here, we specified to generate 12 points inside the volume of the selected shape.</para>
1300 </section>
1301 <section xml:id="filling.fill-surface">
1302 <title xml:id="filling.fill-surface.title">Fill a shape&apos;s surface with molecules</title>
1303 <para>Filling a surface is very similar to filling its volume.
1304 Again the number of equidistant points has to be specified.
1305 However, randomness is constrained as the molecule has to be aligned
1306 with the surface in a specific manner. The idea is to have the molecules point away from the surface in a similar way. This is done by aligning an axis with the surface normal. The alignment axis refers
1307 to the largest principal axis of the filler molecule and will
1308 be aligned parallel to the surface normal at the fill-in point.
1309This is the same syntax as with <emphasis role="bold">rotate-around-self</emphasis>. </para>
1310 <para>The call below will fill in 12 points with a minimum distance
1311 between the instances of 1 angstroem. We allow for certain random
1312 displacements and use the z-axis for aligning the molecules on
1313 the surface.</para>
1314 <programlisting>
1315 ... --fill-surface \
1316 --counts 12 \
1317 --min-distance 1. \
1318 --DoRotate 1 \
1319 --random-atom-displacement 0.05 \
1320 --random-molecule-displacement 0.4 \
1321 --Alignment-Axis &quot;0,0,1&quot;
1322 </programlisting>
1323 </section>
1324 <section xml:id="filling.suspend-in-molecule">
1325 <title xml:id="filling.suspend-in-molecule.title">Suspend in molecule </title>
1326 <para>Add a given molecule in the simulation domain in such a way
1327 that the total density is as desired.</para>
1328 <programlisting>
1329 ... --suspend-in-molecule 1.
1330 </programlisting>
1331 </section>
1332 <section xml:id="filling.fill-molecule">
1333 <title xml:id="filling.fill-molecule.title">Fill in molecule</title>
1334 <para>This action will be soon be removed.</para>
1335 <programlisting>
1336 ... --fill-molecule
1337 </programlisting>
1338 </section>
1339 <section xml:id="filling.fill-void">
1340 <title xml:id="filling.fill-void.title">Fill void with molecule </title>
1341 <para>This action will be soon be removed.</para>
1342 <programlisting>
1343 ... --fill-void
1344 </programlisting>
1345 </section>
1346 </section>
1347 <section xml:id="analysis">
1348 <title xml:id="analysis.title">Analysis</title>
1349 <para>If atoms are manipulated and molecules are filled in, it is also a good idea to check on the manner of the filling. This can be done by for example looking at the pair correlation or angular correlation function. This may be useful in checking what is the mean distance between water molecules and how they are aligned with respect to each other.</para>
1350 <section xml:id="analysis.pair-correlation">
1351 <title xml:id="analysis.pair-correlation.title">Pair Correlation </title>
1352 <para>For two given elements Pair correlation checks on the typical
1353 distance in which they can be found with respect to one another. E.g. for
1354 water one might be interested what is the typical distance for
1355 hydrogen and oxygen atoms.</para>
1356 <programlisting>
1357 ... --pair-correlation \
1358 --elements 1 8 \
1359 --bin-start 0 \
1360 --bin-width 0.7 \
1361 --bin-end 10 \
1362 --output-file histogram.dat \
1363 --bin-output-file bins.dat \
1364 --periodic 0
1365 </programlisting>
1366 <para>This will compile a histogram for the interval [0,10] in steps
1367 of 0.7 and increment a specific bin if the distance of one such pair
1368 of a hydrogen and an oxygen atom can be found within its distance
1369 interval. These data files can be used for plotting the distribution right away in order to check on the correlation between the elements.</para>
1370 </section>
1371 <section xml:id="analysis.dipole-correlation">
1372 <title xml:id="analysis.dipole-correlation.title">Dipole Correlation </title>
1373 <para>The dipole correlation is similar to the pair correlation, only
1374 that it correlates the orientation of dipoles in the molecular
1375 system with one another.</para>
1376 <para>Note that the dipole correlation works on the currently
1377 selected molecules, e.g. all water molecules if so selected.</para>
1378 <programlisting>
1379 ... --dipole-correlation \
1380 --bin-start 0 \
1381 --bin-width 0.7 \
1382 --bin-end 10 \
1383 --output-file histogram.dat \
1384 --bin-output-file bins.dat \
1385 --periodic 0
1386 </programlisting>
1387 <para>Hence, instead of calculating a function of the distance in [0,infinity), it calculates the angular histogram in [0,2pi).</para>
1388 </section>
1389 <section xml:id="analysis.dipole-angular-correlation">
1390 <title xml:id="analysis.dipole-angular-correlation.title">Dipole Angular Correlation</title>
1391 <para>The dipole angular correlation looks at the angles of a
1392 dipole over time. It takes the orientation of a certain time step
1393 as the zero angle and bins all other orientations found in later
1394 time steps relative to it.
1395 </para>
1396 <para>Note that in contrast to the dipole correlation the dipole
1397 angular correlation works on the molecules determined by a formula.
1398 This is because selections do not work over time steps as molecules
1399 might change.
1400 </para>
1401 <programlisting>
1402 ... --dipole-angular-correlation H2O \
1403 --bin-start 0 \
1404 --bin-width 5 \
1405 --bin-end 360 \
1406 --output-file histogram.dat \
1407 --bin-output-file bins.dat \
1408 --periodic 0 \
1409 --time-step-zero 0
1410 </programlisting>
1411 </section>
1412 <section xml:id="analysis.point-correlation">
1413 <title xml:id="analysis.point-correlation.title">Point Correlation </title>
1414 <para>Point correlation is very similar to pair correlation, only
1415 that it correlates not positions of atoms among one another but
1416 against a fixed, given point.</para>
1417 <programlisting>
1418 ... --point-correlation \
1419 --elements 1 8 \
1420 --position &quot;0,0,0&quot; \
1421 --bin-start 0 \
1422 --bin-width 0.7 \
1423 --bin-end 10 \
1424 --output-file histogram.dat \
1425 --bin-output-file bins.dat \
1426 --periodic 0
1427 </programlisting>
1428 <para>This would calculate the correlation of all hydrogen and
1429 oxygen atoms with respect to the origin.</para>
1430 </section>
1431 <section xml:id="analysis.surface-correlation">
1432 <title xml:id="analysis.surface-correlation.title">Surface Correlation</title>
1433 <para>The surface correlation calculates the distance of a set
1434 of atoms with respect to a tesselated surface.</para>
1435 <programlisting>
1436 ... --surface-correlation \
1437 --elements 1 8 \
1438 --bin-start 0 \
1439 --bin-width 0.7 \
1440 --bin-end 10 \
1441 --output-file histogram.dat \
1442 --bin-output-file bins.dat \
1443 --periodic 0
1444 </programlisting>
1445 </section>
1446 <section xml:id="analysis.molecular-volume">
1447 <title xml:id="analysis.molecular-volume.title">Molecular Volume </title>
1448 <para>This simply calculates the volume that a selected molecule
1449 occupies. For this the molecular surface is determined via a
1450(convex) tesselation of its surface. Note that this surface is minimal is that aspect
1451 that each node of the tesselation consists of an atom of the
1452 molecule.</para>
1453 <programlisting>... --molecular-volume</programlisting>
1454 </section>
1455 <section xml:id="analysis.average-molecule-force">
1456 <title xml:id="analysis.average-molecule-forcetitle">Average force acting on a molecule</title>
1457 <para>This sums up all the forces of each atom of a currently
1458 selected molecule and returns the average force vector. This should
1459 give you the general direction of acceleration of the molecule.
1460 </para>
1461 <programlisting>... --molecular-volume</programlisting>
1462 </section>
1463 </section>
1464 <section xml:id="fragmentation">
1465 <title xml:id="fragmentation.title">Fragmentation</title>
1466 <para>Fragmentation refers to a so-called linear-scaling method called
1467 &quot;Bond-Order diSSection in an ANOVA-like fashion&quot; (BOSSANOVA),
1468 developed by <personname>Frederik Heber</personname>. In this section
1469 we briefly explain what the method does and how the associated actions
1470 work.</para>
1471 <para>The central idea behind the BOSSANOVA scheme is to fragment the
1472 graph of the molecular system into connected subgraphs of a certain
1473 number of vertices, namely a fixed number of atoms. To give an example, loading a ethane atom
1474 with the chemical formula C2H6, fragmenting the molecule up to order 1
1475 means creating two fragments, both methane-like from either carbon
1476 atom including surrounding hydrogen atoms. Fragmenting up to order 2
1477 would return both the methane fragments and additionally the full
1478 ethane molecule as it resembles a fragment of order 2, namely
1479 containing two (non-hydrogen) atoms.</para>
1480 <para>The reason for doing this is that usual ab-initio calculations
1481 of molecular systems via methods such as Density Functional Theory or
1482 Hartree-Fock scale at least as <inlineequation>
1483 <m:math display="inline">
1484 <m:mi>{\cal O}(M^3}</m:mi>
1485 </m:math>
1486 </inlineequation>with the number of atoms <inlineequation>
1487 <m:math display="inline">
1488 <m:mi>M</m:mi>
1489 </m:math>
1490 </inlineequation>. In general, this cost is prohibitive for calculating ground state energies and forces (required for molecular dynamics simulations) for larger molecules such as bio proteins. By fragmenting the molecular system and looking at fragments of fixed size, calculating the ground state energy of a
1491 number of fragment molecules becomes a linear scaling operation with the number of atoms. In the doctoral thesis of Frederik
1492 Heber, it is explained why this is a sensible ansatz mathematically
1493 and shown that it delivers a very good accuracy if electrons (and
1494 hence interactions) are in general localized.</para>
1495 <para>Long-range interactions (e.g. Coulomb or van-der-Waals interactions) are artificially truncated, however,
1496 with this fragmentation ansatz. It can be obtained in a perturbation manner
1497 by sampling the resulting electronic and nuclei charge density on a
1498 grid, summing over all fragments, and solving the associated Poisson
1499 equation. Such a calculation is implemented via the solver
1500 <productname>vmg</productname> by Julian Iseringhausen that is
1501 contained in the <link xlink:href="http://www.scafacos.org/">
1502 <productname>ScaFaCoS</productname>
1503 </link>. This enhancement is currently implemented via another program package named <productname>JobMarket</productname> that is at the moment not available publicly (contact the author Frederik Heber if interested).</para>
1504 <para>Note that we treat hydrogen special (but can be switched off) as
1505 fragments are calculated as closed shell (total spin equals zero).
1506 Also, we use hydrogen to saturate any dangling bonds that occur as
1507 bonds are cut when fragmenting a molecule (this, too, can be switched
1508 off).</para>
1509 <para>Eventually, the goal of fragmentation is to yield an energy and gradients with respect to nuclear positions per atom for each fragment. These forces can be used for molecular dynamics simulations, for structure optimization or for fitting empirical potential functions. The underlying operation consists of three parts. The first part is always the act of splitting up the selected atoms in the molecular system into fragments. The energies of the fragments are calculated in the second part via an external ab-initio solver, where the actual solver used is arbitrary and to some extent up to the user (<productname>MPQC </productname> is used by default). The second part of the fragmentation is to combine fragment results to energy and gradients for the total molecular system.</para>
1510 <para>Note that the molecular system itself is not touched in any way by this fragmentation. </para>
1511 <section xml:id="fragmentation.fragment-molecule">
1512 <title xml:id="fragmentation.fragment-molecule.title">Fragmenting a molecular system</title>
1513 <para>For the current selection of atoms, all fragments consisting
1514 of these (sub)set of atoms are created in the following
1515 manner.</para>
1516 <programlisting>
1517 ... --fragment-molecule &quot;BondFragment&quot; \
1518 --DoCyclesFull 1 \
1519 --distance 3. \
1520 --order 3 \
1521 --grid-level 5 \
1522 --output-types xyz mpqc
1523 </programlisting>
1524 <para>We go through each of the options one after the other. During
1525 fragmentation some files are created storing state information, i.e.
1526 the vertex/atom indices per fragment and so on. These files are used when re-performing the fragmentation on a slightly modified state (e.g. after a time integration step with essentially the same bond graph) for faster operation. These files all need
1527 a common prefix, here &quot;BondFragment&quot;. Then, we specify that cycles
1528 should be treated fully. This compensates for electrons in aromatic
1529 rings being delocalized over the ring. If cycles in the graph,
1530 originating from aromatic rings, are always calculated fully, i.e.
1531 the whole ring becomes a fragment, we partially overcome these
1532 issues. This does however not work indefinitely and accuracy of the
1533 approximation is limited (<inlineequation>
1534 <m:math display="inline">
1535 <m:mi>&gt;10^{-4}</m:mi>
1536 </m:math>
1537 </inlineequation>) in systems with many interconnected aromatic
1538 rings, such as graphene. Next, we give a distance cutoff of 3 angstroem used
1539 in bond graph creation. Then, we specify the maximum order, i.e. the
1540 maximum number of (non-hydrogen) atoms per fragment, here 3. The
1541 higher this number the more expensive the calculation becomes
1542 (because substantially more fragments are created) but also the more
1543 accurate. The grid level refers to the part where long-range Coulomb
1544 interactions are calculated. This is done via solving the associated
1545 Poisson equation with a multigrid solver -- however, this requires the <productname>JobMarket</productname> package. As input the solver
1546 requires the density which is sampled on a cartesian grid whose
1547 resolution these parameter defines (<inlineequation>
1548 <m:math display="inline">
1549 <m:mi>2^{\mathrm{level}}</m:mi>
1550 </m:math>
1551 </inlineequation>). And finally, we give the output file formats,
1552 i.e. which file formats are used for writing each fragment
1553 configuration (prefix is &quot;BondFragment&quot;, remember?). Here, we use
1554 XYZ (mainly for checking the configurations visually) and MPQC,
1555 which is a very robust Hartree-Fock solver. We refer to the
1556 discussion of the <link linkend="fileparsers">Parsers</link>
1557 on how to change the parameters of the ab-initio calculation. That is to the extent implemented in Molecuilder the created configuration files for the specific solver are manipulated with the options also manipulating the state file written on program exit.</para>
1558 <para>After having written all fragment configuration files, you
1559 need to calculate each fragment, grab the resulting energy (and
1560 force vectors) and place them into a result file manually. This at
1561 least is necessary if you have specified output-types above. If not,
1562 the fragments are not written to file but stored internally. Read
1563 on.</para>
1564 <para>All created fragments, i.e. their id sets, are stored in an
1565 internal structure that associates each atom with all fragments it
1566 is contained in. This AtomFragments container structure can be parsed
1567 and stored, see <link linkend="atomfragments">AtomFragments</link>.
1568 They are used e.g. for fitting partial charges. There, a selection of
1569 atoms is used to fit partial charges to all fragments (and the charge
1570 grids obtained from long-range calculations, see <link linkend="fragmentation.fragment-automation">FragmentAutomation</link>,
1571 and the container is needed to know all fragments.
1572 <note>This structure is cleared by this action and created fragment
1573 information is inserted afterwards, i.e. it contains only the
1574 associations from the current fragmentation.</note>
1575 </para>
1576 </section>
1577 <section xml:id="fragmentation.fragment-automation">
1578 <title xml:id="fragmentation.fragment-automation.title">Calculating fragment energies automatically</title>
1579 <para>Another way of doing this is enabled if you have
1580the <productname>JobMarket</productname> package. Initially, the package was required but now it is only recommended as then calculations can be performed in parallel or arbitrarily many cores (and also the long-range calculation are only available then). JobMarket implements a
1581 client/server ansatz, i.e. two (or more) independent programs are
1582 running (even on another computer but connected via an IP network),
1583 namely a server and at least one client. The server receives
1584 fragment configurations from MoleCuilder and assigns these to a
1585 client who is not busy. The client launches an executable that is
1586 specified in the work package he is assigned and gathers after
1587 calculation a number of values, likewise specified in the package.
1588 The results are gathered together by the server and can be requested
1589 from MoleCuilder once they are done. This essentially describes what
1590 is happening during the execution of this action.</para>
1591 <para>Stored fragment jobs can also be parsed again, i.e. reversing
1592 the effect of having output-types specified in <link linkend="fragmentation.fragment-molecule">Fragmenting a molecule </link>.</para>
1593 <programlisting>
1594 ... --parse-fragment-jobs \
1595 --fragment-jobs &quot;BondFragment00.in&quot; &quot;BondFragment01.in&quot; \
1596 --fragment-path &quot;./&quot; \
1597 --grid-level 5
1598 </programlisting>
1599 <para>Here, we have specified two files, namely
1600 <filename>BondFragment00.in</filename> and
1601 <filename>BondFragment01.in</filename>, to be parsed from the path
1602 &quot;./&quot;, i.e. the current directory. Also, we have specified to sample
1603 the electronic charge density obtained from the calculated ground
1604 state energy solution with a resolution of 5 (see fragment molecule
1605 and also below).</para>
1606 <para>This allows for automated and parallel calculation of all
1607 fragment energies and forces directly within MoleCuilder. The
1608 FragmentationAutomation action takes the fragment configurations
1609 from an internal storage wherein they are placed if in
1610 FragmentMolecule no output-types have been specified.</para>
1611 <programlisting>
1612 ... --fragment-automation \
1613 --fragment-executable mpqc \
1614 --fragment-resultfile BondFragment_results.dat \
1615 --DoLongrange 1 \
1616 --DoValenceOnly 1 \
1617 --grid-level 5 \
1618 --interpolation-degree 3 \
1619 --near-field-cells 4 \
1620 --server-address 127.0.0.1 \
1621 --server-port 1025
1622 </programlisting>
1623 <para>Again, we go through each of the action&apos;s options step by
1624 step.</para>
1625 <para>The executable is required if you do not have a patched
1626 version of <productname>MPQC</productname> that may directly act as
1627 a client to JobMarket&apos;s server. All calculated results are placed in
1628 the result file. If none is given, they are instead again placed in
1629 an internal storage for later access.</para>
1630 <note>
1631 <para>Long-calculations are only possible with a client that knows
1632 how to handle VMG jobs. If you encounter failures, then it is most
1633 likely that you do not have a suitable client.</para>
1634 </note>
1635 <para>In the next line, we have all options related to calculation
1636 of long-range interactions. We only sample valence charges on the
1637 grid, i.e. not core electrons and the nuclei charges are reduced
1638suitably. This avoids problems with sampling highly localized
1639 charges on the grid and is in general recommended. Next, there
1640 follow parameters for the multi grid solver, namely the resolution
1641 of the grid, see under fragmenting the molecule, the interpolation
1642 degree and the number of near field cells. A grid level of 6 is
1643 recommended but costly in terms of memory, the other values are at
1644 their recommend values.</para>
1645 <para>In the last line, parameters are given on how to access the
1646 JobMarket server, namely it address and its port. If the JobMarket package is not available, then these option values cannot be given. Instead the solver is called internally on the same machine and one fragment energy is calculated after the other.</para>
1647 </section>
1648 <section xml:id="fragmentation.analyse-fragment-results">
1649 <title xml:id="fragmentation.analyse-fragment-results.title"> Analyse fragment results</title>
1650 <para>After the energies and force vectors of each fragment have
1651 been calculated, they need to be summed up to an approximation for
1652 the energy and force vectors of the whole molecular system. This is
1653 done by calling this action.</para>
1654 <programlisting>
1655 ... --analyse-fragment-results \
1656 --fragment-prefix &quot;BondFragment&quot; \
1657 --fragment-resultfile BondFragment_results.dat \
1658 --store-grids 1
1659 </programlisting>
1660 <para>The purpose of the prefix should already be known to you, same
1661 with the result file that is the file parsed by MoleCuilder. The
1662 last option states that the sampled charge densities and the
1663 calculated potential from the long-range calculations should be
1664 stored with the summed up energies and forces. Note that this makes
1665 the resulting files substantially larger (Hundreds of megabyte or
1666 even gigabytes as currently the densities are stored on the full cartesian grid). Fragment energies and forces are stored in
1667 so-called internal homology containers. These are explained in the
1668 next section.</para>
1669 <para>Note that this action sets the force vector if these have been
1670 calculated for the fragment. Hence, a
1671 <link linkend="molecule.verlet-integration">verlet integration</link>
1672 is possible afterwards.</para>
1673 </section>
1674 <section xml:id="fragmentation.store-saturated-fragment">
1675 <title xml:id="fragmentation.store-saturated-fragment.title">Store a saturated fragment</title>
1676 <para>This will store the currently selected atoms as a fragment
1677 where all dangling bonds (by atoms that are connected in the bond
1678 graph but have not been selected as well) are saturated with
1679 additional hydrogen atoms. The output formats are set to just xyz.
1680 </para>
1681 <programlisting>
1682 ... --store-saturated-fragment \
1683 --DoSaturate 1 \
1684 --output-types xyz
1685 </programlisting>
1686 </section>
1687 </section>
1688 <section xml:id="homology">
1689 <title xml:id="homology.title">Homologies</title>
1690 <para>After a fragmentation procedure has been performed fully, what
1691 to do with the results? The forces can be used for time integration and structure optimization but what about
1692 the energies? The energy value is basically the function evaluation of
1693 the Born-Oppenheimer surface of the molecular system. For molecular dynamics simulations
1694 continuous ab-initio calculations to evaluate the Born-Oppenheimer
1695 surface, especially the gradient at the current position of the molecular system&apos;s configuration, is not feasible. Instead usually empirical potential functions
1696 are fitted as to resemble the Born-Oppenheimer surface to a sufficient
1697 degree.</para>
1698 <para>One frequently employed method is the many-body expansion of said surface
1699 which is basically nothing else than the fragmentation ansatz described
1700 above. Potential functions resemble a specific term in this many-body
1701 expansion. These are discussed in the next section.</para>
1702 <para>For each of these terms all homologous fragments (i.e. having
1703 the same atoms with respect to the present elements and bonded in the
1704 same way), differing only in the coordinate of each atom, are just a
1705 sampling or a function evaluation of this term of the many-body
1706 expansion with respect to varying nuclei coordinates. Hence, it is
1707 appropriate to use these function evaluations in a non-linear
1708 regression procedure. That is, we want to tune the parameters of the
1709 empirical potential function in such a way as to most closely obtain
1710 the same function evaluation as the ab-initio calculation did using the
1711 same nuclear coordinates. Usually, this is done in a least-square
1712 sense, minimising the euclidean norm.</para>
1713 <para>Homologies -- in the sense used here -- are then nothing else but containers for a specific
1714 type of fragment of all the different, calculated configurations (i.e.
1715 varying nuclear coordinates of the same fragment, i.e. same atoms with identical bonding).</para>
1716 <para>Now, we explain the actions that parse and store
1717 homologies.</para>
1718 <programlisting>... --parse-homologies homologies.dat</programlisting>
1719 <para>This parses the all homologies contained in the file
1720 <filename>homologies.dat</filename> and <emphasis role="italic">appends</emphasis> them to the homology
1721 container.</para>
1722 <programlisting>... --save-homologies homologies.dat</programlisting>
1723 <para>Complementary, this stores the current contents of the homology
1724 container, <emphasis role="italic">overwriting</emphasis> the file
1725 <filename>homologies.dat</filename>.</para>
1726 </section>
1727 <section xml:id="atomfragments">
1728 <title xml:id="atomfragments.title">AtomFragments</title>
1729 <para>Similarly, to <link linkend="homology">Homologies</link> also
1730 the associations between atoms and the respective fragments they take
1731 part in can be stored to a file and parse again at a later time.</para>
1732 <programlisting>... --parse-atom-fragments atomfragments.dat</programlisting>
1733 <para>This parses the all atom fragment associattions contained in the file
1734 <filename>atomfragments.dat</filename> and <emphasis role="italic">appends</emphasis>
1735 them to the atom fragments associations container.</para>
1736 <programlisting>... --save-atom-fragments atomfragments.dat</programlisting>
1737 <para>Complementary, this stores the current contents of the atom fragments
1738 associations container, <emphasis role="italic">overwriting</emphasis> the file
1739 <filename>atomfragments.dat</filename>.</para>
1740 </section>
1741 <section xml:id="potentials">
1742 <title xml:id="potentials.title">Potentials</title>
1743 <para>In much the same manner as we asked before: what are homology
1744 files or containers good for? However, taking into account what we have just explained, it
1745 should be clear: We fit potential function to these function
1746 evaluations of terms of the many-body expansion of the Born-Oppenheimer
1747 surface of the full system.</para>
1748 <section xml:id="potentials.fit-potential">
1749 <title xml:id="potentials.fit-potential.title">Fitting empirical potentials</title>
1750 <para>Let&apos;s take a look at an exemplary call to the fit potential
1751 action.</para>
1752 <programlisting>
1753 ... --fit-potential \
1754 --fragment-charges 8 1 1 \
1755 --potential-charges 8 1 \
1756 --potential-type morse \
1757 --take-best-of 5
1758 </programlisting>
1759 <para>Again, we look at each option in turn. The first is the
1760 charges or elements specifying the set of homologous fragments that
1761 we want to look at. Here, obviously we are interested in water
1762 molecules, consisting of a single oxygen (8) and two hydrogen atoms (1).
1763 Next, we specify the chemical element type of the potential, here a potential between oxygen (8) and hydrogen (1). We give
1764 the type of the potential as morse, which requires a single distance
1765 or two nuclear coordinates and the distance taken between the two. Finally, we state that the non-linear regression should be
1766 done with five random starting positions, i.e. five individual minimizations, and the set of parameters
1767 with the smallest L2 norm wins.</para>
1768 <note>
1769 <para>Due to translational and rotational degrees of freedom for
1770 fragments smaller than 7 atoms, it is appropriate to look at the
1771 pair-wise distances and not at the absolute coordinates. Hence,
1772 the two atomic positions, here for oxygen and hydrogen, are
1773 converted to a single distance. If we had given an harmonic
1774 angular potential and the then required three charges/elements, &quot;8 1 1&quot;, i.e. oxygen
1775 and two hydrogens, we would have obtained three distances.</para>
1776 <para>MoleCuilder always adds a so-called constant potential to
1777 the fit containing only a single parameter, the energy offset.
1778 This offset compensates for the interaction energy associated with
1779 a fragment of order 1, e.g. a single hydrogen atom. Essentially, this captures the atomic energy that is not associated to any bonding interactions.</para>
1780 <para>Note that by choosing "set-max-iterations" and "take-best-of"
1781 one can force the optimization to try either a single set of random
1782 initial parameters very thoroughly or many different sets just for
1783 a few iterations. Or any in between.</para>
1784 </note>
1785 </section>
1786 <section xml:id="potentials.fit-compound-potential">
1787 <title xml:id="potentials.fit-compound-potential.title">Fitting many empirical potentials simultaneously</title>
1788 <para>Another way is using a file containing a specific set of
1789 potential functions, possibly even with initial values.</para>
1790 <programlisting>
1791 ... --fit-compound-potential \
1792 --fragment-charges 8 1 1 \
1793 --potential-file water.potentials \
1794 --set-threshold 1e-3 \
1795 --training-file test.dat
1796 </programlisting>
1797 <para>Now, all empirical potential functions are summed up into a
1798 so-called compound potential over the combined set of parameters.
1799 These are now fitted simultaneously. For example, let&apos;s say the potential
1800 file <filename>water.potentials</filename> contains a harmonic bond
1801 potential between oxygen and hydrogen and another angular potential
1802 for the angle between hydrogen, oxygen, and hydrogen atom. Then, we would
1803 fit a function consisting of the sum of the two potentials functions in order to approximate the energy of a single
1804 water molecule (actually, it&apos;s the sum of three potentials. As mentioned before, a constant potential is always added to compensate non-bonding energies, i.e. not depending on interatomic distances). Here, the threshold criterion takes the place of the
1805<emphasis role="bold"> take-best-of</emphasis> option. Here, the minimization is reiterated so often on random (but to some extent chosen from a sensible range) starting parameters until the final L2 error is below 1e-3. Also, all data used
1806 for training, i.e. the tuples consisting of the fragments nuclei
1807 coordinates and the associated energy value are written to the file
1808 <filename>test.dat</filename>. This allows for graphical representation or other
1809way of analysis, e.g. for a Morse potential between oxygen and hydrogen the bonding energy can be plotted as a one-dimensional function and compared to the &quot;point cloud&quot; of sample points from the fragment term of Born-Oppenheimer surface. It is this point cloud, i.e. the training data, that is written to the file
1810 <filename>test.dat</filename>.</para>
1811 <para>Note that you can combine the two ways, i.e. start with a
1812 fit-potential call but give an empty potential file. The resulting
1813 parameters are stored in it. Fit other potentials and give different
1814 file names for each in turn. Eventually, you have to combine the file
1815 in a text editor at the moment. And perform a fit-compound-potential
1816 with this file.</para>
1817 <para>Here, also "set-max-iterations" and "take-best-of" can be used
1818 to mix thorough or shallow search from random initial parameter sets.
1819 </para>
1820 </section>
1821 <section xml:id="potentials.parse-potential">
1822 <title xml:id="potentials.parse-potential.title">Parsing an empirical potentials file</title>
1823 <para>Taking part in the compound potential is every potential
1824 function whose signature matches with the designated fragment-charges
1825 and who is currently known to MoleCuilder.</para>
1826 <para>More potentials can be registered (<emphasis role="bold">fit-potential</emphasis> will also
1827 register the potential it fits) by parsing them from a file.</para>
1828 <programlisting>
1829 ... --parse-potentials water.potentials
1830 </programlisting>
1831 <note>Currently, only <productname>TREMOLO</productname>potential files are understood and can be parsed.</note>
1832 </section>
1833 <section xml:id="potentials.save-potential">
1834 <title xml:id="potentials.save-potential.title">Saving an empirical potentials file</title>
1835 <para>The opposite to <emphasis role="bold">parse-potentials</emphasis> is to save all currently registered potential functions to the given
1836 file along with the currently fitted parameters</para>
1837 <programlisting>
1838 ... --save-potentials water.potentials
1839 </programlisting>
1840 <note>Again, only the <productname>TREMOLO</productname>potential format is understood currently and is written.</note>
1841 </section>
1842 <section xml:id="potentials.fit-partial-charges">
1843 <title xml:id="potentials.fit-partial-charges.title">Fitting partial particle charges</title>
1844 <para>The above empirical potential just model the short-range
1845 behavior in the molecular fragment, namely the (covalently) bonded interaction.
1846 In order to model the Coulomb long-range interaction as well without solving
1847 for the electronic ground state in each time step, partial charges
1848 are used that capture to some degree the created dipoles due to
1849 charge transfer from one atom to another when bonded. These are called
1850 partial charges because they combine both nuclei and electronic
1851 charges to yield an in general fractional charge.</para>
1852 <para>Note that so far the placement of partial charges is restricted
1853 to the position of nuclei in the molecular system. There are more
1854 complex ways of placing partial charges, e.g. as employed in higher
1855 TIP water molecules, that also use anti-bonding potentials. This is
1856 so far not implemented.</para>
1857 <para>To allow least-squares regression of these partial charges, we
1858 need the results of long-range calculations and the <emphasis role="bold">store-grids</emphasis>
1859 option (see above under <link linkend="fragmentation">Fragmentation </link>)
1860 must have been given.</para>
1861 <para>Furthermore, we require associations between selected atoms and
1862 the fragments, residing in the <link linkend="homology">Homology container</link>.
1863 These are contained in the <link linkend="atomfragments">AtomFragments association</link>
1864 container, that can also be parsed and stored.</para>
1865 <para>With these sampled charge density and Coulomb potential stored
1866 in the homology containers, we call this action as follows.</para>
1867 <programlisting>
1868 ... --fit-partial-charges \
1869 --potential-file water.particles \
1870 --radius 1.5
1871 </programlisting>
1872 <para>Assume that a water molecule has been selected previously. Then
1873 all homologous fragments that contain any of the water molecules are
1874 used as &quot;key&quot; to request all configurations of this type
1875 from the homologies container. For each of the atoms then an average
1876 partial charge is computed by fitting their respective Coulomb
1877 potential to the obtained from the fragment calculations. Resulting
1878 values are stored in <filename>water.particles</filename>. The
1879 radius is used to mask a certain region directly around the nuclei
1880 from the fit procedure. As here the charges of the core electrons and
1881 the nuclei itself dominate, we however are only interested in a good
1882 approximation to the long-range potential, this mask radius allows
1883 to give the range of the excluded zone.</para>
1884 </section>
1885 <section xml:id="potentials.parse-particle-parameters">
1886 <title xml:id="potentials.parse-particle-parameters.title">Parsing a particles file</title>
1887 <para>Empirical Potential contain parameters for function that model
1888 interactions between two or more specific particles. However,
1889 interactions can also be more general, such as a Coulomb
1890 potential, that interacts with any other particle with non-zero
1891 charge, or Lennard-Jones potential that interacts with any other
1892 particle close enough.
1893 Parameters for these particles are encoded in the internal Particle
1894 class and are parsed from and stored to a special particles file.
1895 This parse particle parameters function loads the parameters from
1896 a file, instantiates them in a new particle, and registers them
1897 such that they are known within molecuilder.</para>
1898 <para>More particles can be registered (<emphasis role="bold">fit-partial-charges</emphasis> will also
1899 register the particles it fits) by parsing them from a file.</para>
1900 <programlisting>
1901 ... --parse-particle-parameters water.particles
1902 </programlisting>
1903 <note>Currently, only <productname>TREMOLO</productname>particles files are understood and can be parsed.</note>
1904 </section>
1905 <section xml:id="potentials.save-particle-parameters">
1906 <title xml:id="potentials.save-particle-parameters.title">Saving a particles file</title>
1907 <para>The opposite to <emphasis role="bold">parse-particle-parameters</emphasis>
1908 is to save all currently registered particle and their parameters to
1909 the given file.</para>
1910 <programlisting>
1911 ... --save-particle-parameters water.particles
1912 </programlisting>
1913 <note>Again, only the <productname>TREMOLO</productname>particles format is understood currently and is written.</note>
1914 </section>
1915 </section>
1916 <section xml:id="dynamics">
1917 <title xml:id="dynamics.title">Dynamics</title>
1918 <para>For fitting potentials or charges we need many homologous but
1919 different fragments, i.e. atoms with slightly different positions.
1920 How can we generate these?</para>
1921 <para>One possibility is to use molecular dynamics. With the
1922 aforementioned fragmentation scheme we can quickly calculate not only
1923 energies but also forces if the chosen solver, such as
1924 <link xlink:href="http://www.mpqc.org/">
1925 <productname>MPQC </productname>
1926 </link>, supports it. Integrating these forces
1927 discretely over time gives insight into vibrational features of a
1928 molecular system close to the equilibrium and allows to generate those positions for fitting
1929 potentials that describe these vibrations.</para>
1930 <section xml:id="dynamics.molecular-dynamics">
1931 <title xml:id="dynamics.molecular-dynamics.title">Molecular dynamics </title>
1932 <para>The molecular dynamics action is a so-called macro Action,
1933 i.e. it combines several other Actions into one, namely:</para>
1934 <itemizedlist>
1935 <listitem>
1936 <para>--<emphasis role="bold">verlet-integration</emphasis></para>
1937 </listitem>
1938 <listitem>
1939 <para>--<emphasis role="bold">output</emphasis></para>
1940 </listitem>
1941 <listitem>
1942 <para>--<emphasis role="bold">clear-fragment-results</emphasis></para>
1943 </listitem>
1944 <listitem>
1945 <para>--<emphasis role="bold">destroy-adjacency</emphasis></para>
1946 </listitem>
1947 <listitem>
1948 <para>--<emphasis role="bold">create-adjacency</emphasis></para>
1949 </listitem>
1950 <listitem>
1951 <para>--<emphasis role="bold">update-molecules</emphasis></para>
1952 </listitem>
1953 <listitem>
1954 <para>--<emphasis role="bold">fragment-molecule</emphasis></para>
1955 </listitem>
1956 <listitem>
1957 <para>--<emphasis role="bold">fragment-automation</emphasis></para>
1958 </listitem>
1959 <listitem>
1960 <para>--<emphasis role="bold">analyse-fragment-results</emphasis></para>
1961 </listitem>
1962 </itemizedlist>
1963 <para>The following command will perform a molecular dynamics simulation
1964 for 100 time steps, each time step continuing over <emphasis role="bold">deltat</emphasis> equal to 0.5 atomic time units,
1965 i.e. 1.2e-17 s. Some of the other options listed below, such as <emphasis role="bold">order</emphasis>, <emphasis role="bold">distance</emphasis>, or <emphasis role="bold">fragment-executable</emphasis>, will seem familiar
1966 to you if you have read in this guide about the fragmentation actions. Look at the list above to see that they are a part of the makro action that performs molecular dynamics simulations. Below
1967 we will not keep the bond graph, i.e bonds and molecules may change
1968 over the simulation and hence also the created fragments per time
1969 step.
1970Furthermore, the forces are corrected such that the force add up to zero. </para>
1971 <programlisting>
1972 ... --molecular-dynamics \
1973 --steps 100 \
1974 --keep-bondgraph 0 \
1975 --order 3 \
1976 --distance 3. \
1977 --deltat 0.5 \
1978 --keep-fixed-CenterOfMass 1 \
1979 --fragment-executable mpqc \
1980 </programlisting>
1981 <para>Keeping the bond graph is useful when simulating close to the equilibrium and no bond breaking or forming should occur. Note that in general the BOSSANOVA fragmentation scheme is discontinuous with respect to the formation of bonds in the energy. This discontinuity arrises because of the threshold criterion used for detecting the bond graph. After each simulation step the bond graph is recreated (if <emphasis role="bold">keep-bondgraph</emphasis> is switched off) to accomodate for any structural changes. If bonds are added because two atoms are suddenly within the required distance which before was not the case, additional fragments are generated, calculated, and added to the approximation of the whole system. As the addition of these contributions is sudden -- in general, they will already be non-zero when the bonds are detected -- a slight jump in the total energy of the system can be expected.</para>
1982 <para>To sum it up, the use of the BOSSANOVA scheme in bond breaking/forming scenarios is in general not recommended. That&apos;s why keeping the bond graph is always sensible. However, if potential energies are too far away from equilibrium the simulation may still produce unphysical results.</para>
1983 </section>
1984 <section xml:id="dynamics.optimize-structure">
1985 <title xml:id="dynamics.optimize-structure.title">Structure optimization</title>
1986 <para>Structure optimization is also a macro Action, it basically
1987 combines the same Actions as <emphasis role="bold">molecular-dynamics</emphasis> does. However, it
1988 uses the <emphasis role="bold">force-annealing</emphasis> action instead of <emphasis role="bold">verlet-integration</emphasis>.</para>
1989 <para>The command below performs a structure optimization of the
1990 currently selected atoms (may also be a subset) for up to 100 time
1991 steps, where each time step is again 0.5 atomic time units. The time
1992 step here serves as the initial step width for annealing.
1993 </para>
1994 <programlisting>
1995 ... --optimize-structure \
1996 --keep-bondgraph 1 \
1997 --output-every-step 1 \
1998 --steps 100 \
1999 --order 3 \
2000 --distance 3. \
2001 --deltat 0.5 \
2002 --keep-fixed-CenterOfMass 1 \
2003 --fragment-executable mpqc \
2004 </programlisting>
2005 <para>Note that <emphasis role="bold">output-every-step</emphasis> will allow you to watch the
2006 optimization as each step is placed into a distinct time step.
2007 Otherwise only two time steps would be created: the initial and
2008 the final one containing the optimized structure.</para>
2009 </section>
2010 <section xml:id="dynamics.set-world-time">
2011 <title xml:id="dynamics.set-world-time.title">Set the world&apos;s time step</title>
2012 <para>In order to inspect or manipulate atoms and molecules at a
2013 certain time step, the World&apos;s time has to be set with the following
2014 Action.
2015 </para>
2016 <para>This will set the World&apos;s time to the fifth step (counting
2017 starts at zero).</para>
2018 <programlisting>... --set-world-time 4</programlisting>
2019 <para>Note that each atom has its own tracjectory storage and manages it in a clever way. That&apos;s why subsets of atoms may be time-integrated, while the other atoms will not get taken over on the time axis. They simply remain frozen during the integration.</para>
2020 </section>
2021 <section xml:id="dynamics.save-temperature">
2022 <title xml:id="dynamics.save-temperature.title">Save the temperature information</title>
2023 <para>For each present time step the temperature (i.e. the average velocity
2024 per atom multiplied with its mass) will be stored to a file.</para>
2025 <programlisting> ... --save-temperature temperature.dat</programlisting>
2026 <para>That is <emphasis role="italic">temperature.dat</emphasis> contains two columns: the first contains the time step and the second column contains the temperature of the system in atomic units.</para>
2027 </section>
2028 </section>
2029 <section xml:id="dynamics.tesselation">
2030 <title xml:id="dynamics.tesselation.title">Tesselations</title>
2031 <para>A tesselation is a set of triangles that form a closed surface. They are used to obtain molecular surfaces (and volumes) by rolling
2032 a virtual sphere of a certain radii on a molecule such that it always rests on at least three atoms. From such a resting position the sphere is rolled over all of its three sides until it rests again. This is continued until the closed
2033 surface of connected triangles is created.</para>
2034 <para>Note that tesselations are used internally by the graphical interface in order to show molecules by their surface. This is in general faster than displaying them as a ball-stick model consisting of spheres and cylinders.</para>
2035 <section xml:id="dynamics.tesselation.nonconvex-envelope">
2036 <title xml:id="dynamics.tesselation.nonconvex-envelope.title"> Non-convex envelope</title>
2037 <para>This will create a non-convex envelope for a molecule and store
2038 it to a file for viewing with external programs.</para>
2039 <programlisting>
2040 ... --nonconvex-envelope 6. \
2041 --nonconvex-file nonconvex.dat
2042 </programlisting>
2043 <para>This tesselation file can be conveniently viewed with
2044 <productname>TecPlot</productname> or with one of the Tcl script
2045 in the <emphasis role="italic">util</emphasis> folder with <productname>VMD</productname>. Also,
2046 still pictures can be produced with <productname>Raster3D </productname>.
2047 <note>The required file header.r3d can be found in a subfolder of the util folder.</note>
2048 </para>
2049 </section>
2050 <section xml:id="dynamics.tesselation.convex-envelope">
2051 <title xml:id="dynamics.tesselation.convex-envelope.title">Convex envelope</title>
2052 <para>This will create a convex envelope for a molecule and give the
2053 volumes of both the non-convex and the convex envelope. This is good
2054 for measuring the space a molecule takes up, e.g. when filling a
2055 domain and taking care of correct densities.</para>
2056 <programlisting>
2057 ... --convex-envelope 6. \
2058 --convex-file convex.dat
2059 </programlisting>
2060 <para>This tesselation file can be likewise viewed with
2061 <productname>TecPlot</productname> or with one of the Tcl script
2062 in the util folder with <productname>VMD</productname>.</para>
2063 </section>
2064 </section>
2065 <section xml:id="various">
2066 <title xml:id="various.title">Various commands</title>
2067 <para>Here, we gather all commands that do not fit into one of above
2068 categories for completeness.</para>
2069 <section xml:id="various.verbose">
2070 <title xml:id="various.verbose.title">Changing verbosity</title>
2071 <para>The verbosity level is the amount of stuff printed to screen.
2072 This information will in general help you to understand when
2073 something does not work. Mind the <emphasis>ERROR</emphasis> and
2074 <emphasis>WARNING</emphasis> messages in any case.</para>
2075 <para>This command below sets the verbosity from default of 2 to 4,</para>
2076 <programlisting>... --verbose 4</programlisting>
2077 <para>or shorter,</para>
2078 <programlisting>... -v 4</programlisting>
2079 </section>
2080 <section xml:id="various.dry-run">
2081 <title xml:id="various.dry-run.title">Dry runs</title>
2082 <para>A &quot;dry run&quot; refers to a test run where commands are not
2083 actually executed. You may bracket a certain set of actions by
2084 putting --<emphasis role="bold">dry-run</emphasis> before and --<emphasis role="bold">no-dry-run</emphasis> afterwards. Then, all
2085 actions in between will be looked at but not executed, i.e. they
2086 make it to the history but nothing is changed in the World.</para>
2087 <para>As an example, the following listing contains the adding of a
2088 hydrogen atom at position (5,5,5) inside the aforementioned dry run
2089 statements. Hence, no hydrogen atom is added but the <emphasis role="bold">add-atom</emphasis> action is
2090 stored in the history and will make it to a stored session.</para>
2091 <programlisting> ... --dry-run \
2092 --add-atom 1 --domain-position &quot;5,5,5&quot;
2093 --no-dry-run</programlisting>
2094 <para>This is useful for converting shell commands into python scripts. Commands are not executed but all are eventually found in the written pyrthon file.</para>
2095 </section>
2096 <section xml:id="various.element-db">
2097 <title xml:id="various.element-db.title">Loading an element database</title>
2098 <para>Element databases contain information on valency, van der
2099 Waals-radii and other information for each element.</para>
2100 <para>This loads all element database from the current folder (in a
2101 unix environment):</para>
2102 <programlisting>... --element-db ./</programlisting>
2103 </section>
2104 <section xml:id="various.fastparsing">
2105 <title xml:id="various.fastparsing.title">Fast parsing</title>
2106 <para>Parsing all time steps from a given input file can take a
2107 while, especially for larger systems. If fast parsing is activated,
2108 only the first time step is loaded, all other are ignored.</para>
2109 <programlisting>... --fastparsing 1</programlisting>
2110 </section>
2111 <section xml:id="various.version">
2112 <title xml:id="various.version.title">Giving the version of the program</title>
2113 <para>This prints the version information of the code, especially
2114 important when you request the fixing of bugs or implementation of
2115 features.</para>
2116 <programlisting>... --version</programlisting>
2117 </section>
2118 <section xml:id="various.warranty">
2119 <title xml:id="various.warranty.title">Giving warranty information</title>
2120 <para>As follows warranty information is given,</para>
2121 <programlisting>... --warranty</programlisting>
2122 </section>
2123 <section xml:id="various.help-redistribute">
2124 <title xml:id="various.help-redistribute.title">Giving redistribution information</title>
2125 <para>This gives information on the license and how to redistribute
2126 the program and its source code</para>
2127 <programlisting>... --help-redistribute</programlisting>
2128 </section>
2129 </section>
2130 <section xml:id="sessions">
2131 <title xml:id="sessions.title">Sessions</title>
2132 <para>A session refers to the queue of actions you have executed.
2133 Together with the initial configuration (and all files required for
2134 actions in the queue) this may be seen as a clever way of storing
2135 the state and history of a molecular system manipulation session. When proceeding in a try&amp;error
2136 fashion to construct a certain system, it is a good idea, to store the
2137 session at the point where your attempts start to deviate from one
2138 another.</para>
2139 <para>Note only that but stored session used in the graphical interface may safe a lot of repetitive pointing and clicking. On top of that if the python session file is called <emphasis role="italic">molecuilder.py</emphasis> and resides in the folder you start MoleCuilder from, then it will be executed automatically and even before creating the graphical interface (i.e. it is also faster).</para>
2140 <section xml:id="sessions.store-session">
2141 <title xml:id="sessions.store-session.title">Storing a session </title>
2142 <para>Storing sessions is simple,</para>
2143 <programlisting>
2144 ... --store-session &quot;session.py&quot; \
2145 --session-type python
2146 </programlisting>
2147 <para>Here, the session type is given as python (the other option is
2148&quot; cli&quot; for storing in the manner of the command-line interface, i.e. just as our example code snippets throughout this guide). The written
2149 python script <filename>session.py</filename> can even be used with
2150 the python interface described below, i.e. it is a full python script
2151 (that however requires the so-called <emphasis role="italic">pyMoleCuilder</emphasis> module).</para>
2152 </section>
2153 <section xml:id="sessions.load-session">
2154 <title xml:id="sessions.load-session.title">Loading a session</title>
2155 <para>Loading a session only works for python scripts, i.e. only for session type python and not for type cli. This actually
2156 blurs the line between the command-line interface and the python
2157 interface a bit. Again, MoleCuilder automatically executes a
2158 script called <filename>molecuilder.py</filename> if such a file is
2159 contained in the current directory.</para>
2160 <programlisting>... --load-session &quot;session.py&quot;</programlisting>
2161 <para>This will execute every action with its options contained in the
2162 script <filename>session.py</filename>.</para>
2163 </section>
2164 </section>
2165 <section xml:id="various-specific">
2166 <title xml:id="various-specific.title">Various specific commands </title>
2167 <para>In this (final) section of the action description we list a number
2168 Actions that are very specific to some purposes (or other programs).
2169 </para>
2170 <section xml:id="various-specific.save-selected-atoms-as-exttypes">
2171 <title xml:id="various-specific.save-selected-atoms-as-exttypes.title"> Saving exttypes of a set of atoms</title>
2172 <para>This saves the atomic ids of all currently selected atoms in a
2173 <link xlink:href="http://www.tremolo-x.com/">
2174 <productname>TREMOLO </productname>
2175 </link> exttypes file with the given name.</para>
2176 <programlisting>
2177 ... --save-selected-atoms-as-exttypes \
2178 --filename test.exttypes </programlisting>
2179 </section>
2180 <section xml:id="various-specific.set-parser-parameters">
2181 <title xml:id="various-specific.set-parser-parameters.title">Setting parser specific parameters</title>
2182 <para>You can tweak the parameters stored in files associated to specific ab initio programs to some extent.
2183 For example, <productname>MPQC</productname> stores various
2184 parameters modifying the specific ab-initio calculation performed, e.g. the basis set used, the level of theory, whether gradients are calculated.
2185 For <link xlink:href="http://www.mpqc.org/">
2186 <productname>MPQC </productname>
2187 </link> and
2188 <link xlink:href="http://www.psicode.org/">
2189 <productname>Psi4 </productname>
2190 </link> this can be modified as follows.</para>
2191 <programlisting>
2192 ... --set-parser-parameters mpqc \
2193 --parser-parameters &quot;theory=CLHF;basis=6-31*G;&quot;
2194 </programlisting>
2195 <para>This sets the ab-initio theory to closed-shell Hartree-Fock
2196 and the basis set to 6-31*G. Note the specific &quot;key=value;&quot; system. That is a key such as &quot;theory&quot; is followed by an equivalent sign and by a value, here &quot;CLHF&quot; for closed-shell Hartree-Fock, and finally a semicolon to separate the key-value pairs. Please avoid any unnecessary white spaces. Note that the implementation is probably not complete, hence do check the
2197 <productname>MPQC</productname> manual on further supported values that must be added by hand. We list below the currently implementd list of keys and their values.</para>
2198 <itemizedlist>
2199 <listitem>theory</listitem>
2200 <listitem>basis</listitem>
2201 </itemizedlist>
2202 </section>
2203 <section xml:id="various-specific.set-tremolo-atomdata">
2204 <title xml:id="various-specific.set-tremolo-atomdata.title">Tremolo specific options and potential files</title>
2205 <para><productname>TREMOLO</productname>&apos;s configuration files start
2206 with a specific line telling the amount of information that is contained in the
2207 file. This line can be modified, e.g. to enforce storing of
2208 velocities and forces as well as the atoms positions and
2209 element.</para>
2210 <programlisting>
2211 ... --set-tremolo-atomdata &quot;ATOM id element u=3 v=3 F=3&quot; \
2212 --reset 1
2213 </programlisting>
2214 <para>This will not append but reset the old line and fill it with
2215 the given string.</para>
2216 <para>One further specific action is required when loading certain
2217 <productname>TREMOLO</productname> configuration files. These
2218 contain element notations that refer to parameterized names used in
2219 empirical potentials and molecular dynamics simulations and not the
2220 usual chemical symbols, such as H or O. We may load an auxiliary
2221 file that gives the required conversion from OH1 to H, which is the
2222 so-called potentials file.</para>
2223 <programlisting>... --parse-tremolo-potentials water.potentials</programlisting>
2224 <para>This parses the lookup table from the file
2225 <filename>water.potentials</filename> and it can be used in
2226 following load actions.</para>
2227 <para>Note that this is the same format as written by the fitting actions. However, apart from this the Actions are not related, i.e. <emphasis role="bold">parse-potentials</emphasis> will not also load these element descriptions. If this is desired, the above Action has to be used.</para>
2228 </section>
2229 </section>
2230 </section>
2231 <section xml:id="textmenu-interface">
2232 <title xml:id="textmenu-interface.title">Text menu</title>
2233 <para>We now discuss how to use the text menu interface.</para>
2234 <para>The text menu is very much the interface counterpart to the
2235 command-line interface. However, both work in a terminal session.</para>
2236 <para>In the text menu, actions can be selected from hierarchical lists.
2237 Note that the menus for the graphical interface are organized in the
2238 exactly same way. After an action has been chosen, the option values
2239 have to be entered one after the other. After the last option value has
2240 been given, the action is executed and the result printed to the
2241 screen.</para>
2242 <para>With regards to the other functionality, it is very much the same
2243 as the command-line interface above. It differs by being interactive, i.e. when using an external viewer on the state file and saving it after an Action has been performed, output can be checked. However, you may work in this way also directly by using the graphical interface.</para>
2244 </section>
2245 <section xml:id="graphical-user-interface">
2246 <title xml:id="graphical-user-interface.title">Graphical user interface </title>
2247 <para>The main point of the GUI is that it renders the atoms and
2248 molecules visually. These are represented by the common
2249 stick-and-ball-model by default. For faster rendering, molecules can also be visualized by the a non-convex envelope, see Tesselations. Single or multiple atoms and molecules can easily
2250 be accessed, activated, and manipulated via tables. Changes made in the
2251 tables cause immediate update of the visual representation. Under the
2252 hood each of these manipulations is nothing but the call to an action,
2253 hence is fully undo- and redoable.</para>
2254 <para>This interface is most helpful in designing more advanced structures that are
2255 conceptually difficult to imagine without visual aid. Results can be inspected directly and, if unsuitable, can be undone and reperformed with tweaked parameters. At the end, a
2256file containing the session may be stored and this script can then be used to construct
2257 various derived or slightly modified structures.</para>
2258 <section xml:id="graphical-user-interface.basic-view">
2259 <title xml:id="graphical-user-interface.basic-view.title">Basic view </title>
2260 <para>Let us first give an impression of the basic view of the GUI after a molecule has been loaded.</para>
2261 <figure>
2262 <title>Screenshot of the basic view of the GUI after loading a file with eight water molecules.</title>
2263 <mediaobject>
2264 <imageobject>
2265 <imagedata width="100%" scalefit="1" entityref="example_basic_view"/>
2266 </imageobject>
2267 </mediaobject>
2268 </figure>
2269 <section xml:id="graphical-user-interface.3d-view">
2270 <title xml:id="graphical-user-interface.3d-view.title">3D view </title>
2271 <para>In the above figure, you see the stick-and-ball representation
2272 of the water molecules, the &quot;dreibein&quot; giving the positive axis
2273 directions and the slightly translucent cuboid of the domain on a black background.</para>
2274 </section>
2275 <section xml:id="graphical-user-interface.information-tabs">
2276 <title xml:id="graphical-user-interface.information-tabs.title"> Information Tabs</title>
2277 <para>Beneath this 3D view that you can rotate at will with your mouse
2278 and zoom in and out with your scroll wheel, you find to the right a
2279 part containing two tabs named Atom and Molecule. Look at where the
2280 mouse pointer is. It has colored the atom underneath in cyan
2281 (although it&apos;s also an oxygen atom and should be colored in rose
2282 as the rest). You can inspect its properties in the tab Atom: Name,
2283 element, mass, charge, position and number of bonds. If you switch
2284 to the Molecule tab, you would see the properties of the water
2285 molecule this specific atom belongs to.</para>
2286 </section>
2287 <section xml:id="graphical-user-interface.shape">
2288 <title xml:id="graphical-user-interface.shape.title">Shape section </title>
2289 <para>Beneath these information tabs you find the shape sections.
2290 There you find a list of all currently created shapes and you can
2291select them by clicking on them, which lets their surface appear in the 3D view, and manipulate them via the buttons beneath this list. Note that the calculation of the shape&apos;s surface may take up to a few seconds, so don&apos;t get itchy right away when nothing seems to happen for a moment.</para>
2292 </section>
2293 <section xml:id="graphical-user-interface.timeline">
2294 <title xml:id="graphical-user-interface.timeline.title">Timeline </title>
2295 <para>Directly below the 3D view there is a long slider. If a loaded
2296 file has multiple time step entries, this slider allows you to
2297 smoothly select one time frame after another. Sliding it with the
2298 mouse from left to right will reveal the animation that is hidden
2299 behind the distinct snapshots stored in the configuration
2300 file.</para>
2301 </section>
2302 <section xml:id="graphical-user-interface.tables">
2303 <title xml:id="graphical-user-interface.tables.title">Selection tables</title>
2304 <para>Underneath the time line there is another place for
2305 tabs.</para>
2306 <para>The first is on molecules, listing all present molecules of
2307 the molecular system in a tree view. If you click on a specific
2308 molecule, the one will get selected or unselected depending on its
2309 current selection state (see below for details on this with respect
2310 to the GUI). Also, if you tick the box the visibility of the specific molecules is changed: it switches between being displayed as either ball-and-stick, for manipulating its individual atoms, or as a molecular surface for (un)selecting it as a whole.</para>
2311 <para>The next tab enumerates all elements known to MoleCuilder
2312 where the ones are grayed out that are not present in the molecular
2313 system. Clicking on a present element will select all atoms of this
2314 specific element. A subsequent click unselects again.</para>
2315 <para>Subsequently follow tabs on enumerating the fragments and their
2316 fragment energies if calculated and the homologies along with
2317 graphical depiction (via QWT), again if present.</para>
2318 </section>
2319 </section>
2320 <section xml:id="graphical-user-interface.selections">
2321 <title xml:id="graphical-user-interface.selections.title">Selections </title>
2322 <para>Selections work generally always by calling a selection action from the pull-down menu and filling it with required parameters.</para>
2323 <para>With the GUI it may also be accessed directly: The row of icons
2324 above the 3D view has two icons depicting the selection of individual
2325 atoms or molecules. If either of them is selected, clicking with the
2326 left mouse button on an atom will either (un)select the atom or its
2327 associated molecule. Multiple atoms can be selected in this
2328 manner.</para>
2329 <para>Also, the selection tabs may be used by clicking on the name of a
2330 molecule as stated above or at an element.</para>
2331 <para>Similarly, if shapes are present in the shape section, clicking
2332 them will select them and also cause a translucent visualization to
2333 appear in the 3D view. Note that this visualization is quite costly
2334 right now and not suited to complex shapes. (This is in contrast to the molecular surfaces which are actually cheaper than the ball-and-stick presentation).</para>
2335 </section>
2336 <section xml:id="graphical-user-interface.dialogs">
2337 <title xml:id="graphical-user-interface.dialogs.title">Dialogs</title>
2338 <para>Most essential to the GUI are dialogs. Many action
2339 calls forth such a dialog. A dialog consists of a list of queries for a particular option value, one below the other. As each option
2340 value has a specific type, we briefly go into the details of how these
2341 queries look like.</para>
2342 <note>
2343 <para>Each dialog&apos;s okay button is grayed out until all entered option values
2344 are valid.</para>
2345 </note>
2346 <section xml:id="graphical-user-interface.dialogs.domain">
2347 <title xml:id="graphical-user-interface.dialogs.domain.title">Domain query</title>
2348 <figure>
2349 <title>Screenshot of a dialog showing a domain query</title>
2350 <mediaobject>
2351 <imageobject>
2352 <imagedata width="100%" scalefit="1" entityref="dialog_box"/>
2353 </imageobject>
2354 </mediaobject>
2355 <para>In the domain query a 3x3 symmetric matrix has to be
2356 entered. In the above screenshots you notice that the only
2357 non-zero entries are on the main diagonal. Here, we have simply
2358 specified a cube of edge length 8. The okay button will be grayed
2359 out if the matrix is either singular or not symmetric.</para>
2360 </figure>
2361 </section>
2362 <section xml:id="graphical-user-interface.dialogs.element">
2363 <title xml:id="graphical-user-interface.dialogs.element.title"> Element query</title>
2364 <figure>
2365 <title>Screenshot the add atom action containing an element query</title>
2366 <mediaobject>
2367 <imageobject>
2368 <imagedata width="100%" scalefit="1" entityref="dialog_add-atom_tooltip"/>
2369 </imageobject>
2370 </mediaobject>
2371 <para>Elements are picked from a pull-down box where all known
2372 elements are listed.</para>
2373 <para>In this dialog you also notice that a tooltip is given,
2374 briefly explaining what the action does.</para>
2375 </figure>
2376 </section>
2377 <section xml:id="graphical-user-interface.dialogs.action">
2378 <title xml:id="graphical-user-interface.dialogs.action.title"> Complex query</title>
2379 <figure>
2380 <title>Screenshot of a complex dialog consisting of multiple queries</title>
2381 <mediaobject>
2382 <imageobject>
2383 <imagedata width="100%" scalefit="1" entityref="dialog_complex"/>
2384 </imageobject>
2385 </mediaobject>
2386 <para>Here we show a more complex dialog. It queries for strings,
2387 for integer values (see the increase/decrease arrows), for
2388 booleans and for files (the &quot;choose&quot; buttons opens a file
2389 dialog).</para>
2390 </figure>
2391 </section>
2392 <section xml:id="graphical-user-interface.dialogs.exit">
2393 <title xml:id="graphical-user-interface.dialogs.exit.title">Exit query</title>
2394 <figure>
2395 <title>Screenshort showing the exit dialog</title>
2396 <mediaobject>
2397 <imageobject>
2398 <imagedata width="100%" scalefit="1" entityref="dialog_exit"/>
2399 </imageobject>
2400 </mediaobject>
2401 <para>Finally, we show the dialog that will pop up when exiting
2402 the graphical interface. It will ask whether it should store the
2403 current state of the system in the input file or not. You may
2404 cancel the exit, close without saving or save the current
2405 state.</para>
2406 </figure>
2407 </section>
2408 </section>
2409 </section>
2410 <section xml:id="python-interface">
2411 <title xml:id="python-interface.title">Python interface</title>
2412 <para>Last but not least we elaborate on the python interface. We have
2413 already discusses this interface to some extent. The current session,
2414 i.e. the queue of actions you have executed, can be stored as a python
2415 script and subsequently executed independently of the user interface it
2416 was created with. More generally, MoleCuilder&apos;s Actions can be executed within arbitrary python
2417 scripts where prior to its execution a specific module has to be loaded, enabling access to MoleCuilder&apos;s actions from inside the
2418 script.</para>
2419 <para>MoleCuilder&apos;s python module is called <emphasis role="italic">pyMoleCuilder</emphasis>. It is
2420 essentially a library that can be imported into python just as any other
2421 module. Let us assume you have started the python interpreter and you
2422 have added the containing folder of the <filename>pyMoleCuilder</filename>
2423 library to the <varname>PYTHONPATH</varname> variable.</para>
2424 <programlisting>import pyMoleCuilder as mol</programlisting>
2425 <para>Subsequently, you can access the help via</para>
2426 <programlisting>help(mol)</programlisting>
2427 <para>This will list all of MoleCuilder&apos;s actions with their function
2428 signatures within python as contained in the module <emphasis role="italic">pyMoleCuilder</emphasis> named
2429 as <emphasis role="bold">mol</emphasis> in the scope of the currently running interpreter. Note that the
2430 function names are not the names you know from the command-line
2431 interface, they might be called
2432 <computeroutput>WorldChangeBox(...)</computeroutput> or alike. However, they are related by a certain naming system. The first word is identical to the menu name it resides in the text or graphical interface. Then its followed by the actual name of the action that is similar to the command-line token.</para>
2433 <para>Let&apos;s try it out.</para>
2434 <programlisting>print mol.CommandVersion()</programlisting>
2435 <para>This will state the current version of the library.</para>
2436 <para>Go ahead and try out other commands. Refer to the documentation
2437 under the command-line interface and look up the function name via
2438 help.</para>
2439 </section>
2440 </chapter>
2441 <chapter>
2442 <title>Conclusions</title>
2443 <para>This ends this user guide.</para>
2444 <para>We have given you a brief introduction to the aim of the program and
2445 how each of the four interfaces are to be used. The rest is up to
2446 you.</para>
2447 <para>Tutorials and more information is available online, see <link xlink:href="http://www.molecuilder.com/">MoleCuilder&apos;s website</link>.
2448 </para>
2449 <para>Be aware that in general knowing how the code works allows you to
2450 understand what&apos;s going wrong if something&apos;s going wrong.</para>
2451 <section>
2452 <title>Thanks</title>
2453 <para>Huge thanks go out to Saskia Metzler who was patient enough to let
2454 me sit next to her while riding ten hours in a bus to Berlin as I was writing the very first version of this guide.</para>
2455 </section>
2456 </chapter>
2457</book>
Note: See TracBrowser for help on using the repository browser.