Ignore:
Timestamp:
Sep 17, 2014, 9:29:44 PM (10 years ago)
Author:
Frederik Heber <heber@…>
Branches:
Action_Thermostats, Add_AtomRandomPerturbation, Add_FitFragmentPartialChargesAction, Add_RotateAroundBondAction, Add_SelectAtomByNameAction, Added_ParseSaveFragmentResults, AddingActions_SaveParseParticleParameters, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_ParticleName_to_Atom, Adding_StructOpt_integration_tests, AtomFragments, Automaking_mpqc_open, AutomationFragmentation_failures, Candidate_v1.5.4, Candidate_v1.6.0, Candidate_v1.6.1, ChangeBugEmailaddress, ChangingTestPorts, ChemicalSpaceEvaluator, CombiningParticlePotentialParsing, Combining_Subpackages, Debian_Package_split, Debian_package_split_molecuildergui_only, Disabling_MemDebug, Docu_Python_wait, EmpiricalPotential_contain_HomologyGraph, EmpiricalPotential_contain_HomologyGraph_documentation, Enable_parallel_make_install, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, FitPartialCharges_GlobalError, Fix_BoundInBox_CenterInBox_MoleculeActions, Fix_ChargeSampling_PBC, Fix_ChronosMutex, Fix_FitPartialCharges, Fix_FitPotential_needs_atomicnumbers, Fix_ForceAnnealing, Fix_IndependentFragmentGrids, Fix_ParseParticles, Fix_ParseParticles_split_forward_backward_Actions, Fix_PopActions, Fix_QtFragmentList_sorted_selection, Fix_Restrictedkeyset_FragmentMolecule, Fix_StatusMsg, Fix_StepWorldTime_single_argument, Fix_Verbose_Codepatterns, Fix_fitting_potentials, Fixes, ForceAnnealing_goodresults, ForceAnnealing_oldresults, ForceAnnealing_tocheck, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, FragmentAction_writes_AtomFragments, FragmentMolecule_checks_bonddegrees, GeometryObjects, Gui_Fixes, Gui_displays_atomic_force_velocity, ImplicitCharges, IndependentFragmentGrids, IndependentFragmentGrids_IndividualZeroInstances, IndependentFragmentGrids_IntegrationTest, IndependentFragmentGrids_Sole_NN_Calculation, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, JobMarket_unresolvable_hostname_fix, MoreRobust_FragmentAutomation, ODR_violation_mpqc_open, PartialCharges_OrthogonalSummation, PdbParser_setsAtomName, PythonUI_with_named_parameters, QtGui_reactivate_TimeChanged_changes, Recreated_GuiChecks, Rewrite_FitPartialCharges, RotateToPrincipalAxisSystem_UndoRedo, SaturateAtoms_findBestMatching, SaturateAtoms_singleDegree, StoppableMakroAction, Subpackage_CodePatterns, Subpackage_JobMarket, Subpackage_LinearAlgebra, Subpackage_levmar, Subpackage_mpqc_open, Subpackage_vmg, Switchable_LogView, ThirdParty_MPQC_rebuilt_buildsystem, TrajectoryDependenant_MaxOrder, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps, TremoloParser_setsAtomName, Ubuntu_1604_changes, stable
Children:
9bce96
Parents:
c62e27
git-author:
Frederik Heber <heber@…> (09/14/14 18:25:06)
git-committer:
Frederik Heber <heber@…> (09/17/14 21:29:44)
Message:

DOCU: Added all missing Actions to userguide.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/userguide/userguide.xml

    rc62e27 rf73e06  
    488488
    489489        <section>
    490           <title>Setting parser specific parameters</title>
    491 
    492           <para>You can also tweak the parameters stored in this file easily.
    493           For example, <productname>MPQC</productname> stores various
    494           parameters modifying the specific ab-initio calculation performed.
    495           For <productname>MPQC</productname> and
    496           <productname>Psi4</productname> this can be modified as
    497           follows.</para>
    498 
    499           <programlisting>
    500                 ... --set-parser-parameters mpqc \
    501                     --parser-parameters "theory=CLHF;basis=6-31*G;"
     490          <title>Output the current molecular system</title>
     491
     492          <para>This will store the current World, i.e. all its atoms, to a
     493          given file, where the output format is determined from the file
     494          suffix.</para>
     495
     496          <programlisting>... --output-as world.xyz</programlisting>
     497        </section>
     498
     499        <section>
     500          <title>Output the current molecular system</title>
     501
     502          <para>This will store all atoms contained in the currently selected
     503          molecules to file. This is different to "store-saturated-fragment"
     504          as it will not saturate dangling bonds because only whole molecules,
     505          i.e. whose bond graph is connected, will be stored.</para>
     506
     507          <programlisting>... --save-selected-molecules waters.pdb
    502508          </programlisting>
    503 
    504           <para>This sets the ab-initio theory to closed-shell Hartree-Fock
    505           and the basis set to 6-31*G. Please check the
    506           <productname>MPQC</productname> manual on specific
    507           parameters.</para>
    508         </section>
    509 
    510         <section>
    511           <title>Tremolo specific options and potential files</title>
    512 
    513           <para><productname>TREMOLO</productname>'s configuration files start
    514           with a specific line telling the amount of information stored in the
    515           file. This file can be modified, e.g. to enforce storing of
    516           velocities and forces as well as the atoms positions and
    517           element.</para>
    518 
    519           <programlisting>
    520                 ... --set-tremolo-atomdata "ATOM id element u=3 v=3 F=3" \
    521                     --reset 1
    522           </programlisting>
    523 
    524           <para>This will not append but reset the old line and fill it with
    525           the given string.</para>
    526 
    527           <para>One specific action is required when loading certain
    528           <productname>TREMOLO</productname> configuration files. These
    529           contain element notations that refer to parameterized names used in
    530           empirical potentials and molecular dynamics simulations and not the
    531           usual chemical symbols, such as H or O. We may load an auxiliary
    532           file that gives the required conversion from OH1 to H, which is the
    533           so-called potential file.</para>
    534 
    535           <programlisting>... --parse-tremolo-potentials water.potentials</programlisting>
    536 
    537           <para>This parses the lookup table from the file
    538           <filename>water.potentials</filename> and it can be used in
    539           following load actions.</para>
     509        </section>
     510
     511        <section>
     512          <title>Load extra bond information</title>
     513
     514          <para>For some parsers bond information is stored not with the atoms
     515          coordinates but in an extra file. This action parses such a file.</para>
     516
     517          <programlisting>... --bond-file water.dbond
     518          </programlisting>
    540519        </section>
    541520      </section>
    … …  
    571550            <itemizedlist>
    572551              <listitem>
     552                <para>All</para>
     553                <programlisting>
     554                ... --select-all-atoms
     555                </programlisting>
     556              </listitem>
     557
     558              <listitem>
     559                <para>None</para>
     560                <programlisting>
     561                ... --unselect-all-atoms
     562                </programlisting>
     563                <programlisting>
     564                ... --clear-atom-selection
     565                </programlisting>
     566              </listitem>
     567
     568              <listitem>
     569                <para>Invert selection</para>
     570                <programlisting>
     571                ... --invert-atoms
     572                </programlisting>
     573              </listitem>
     574
     575              <listitem>
    573576                <para>By Element (all hydrogen atoms, all sulphur atoms,
    574577                ...)</para>
     578                <programlisting>
     579                ... --select-atom-by-element 1
     580                </programlisting>
     581                <programlisting>
     582                ... --unselect-atom-by-element 1
     583                </programlisting>
    575584              </listitem>
    576585
    577586              <listitem>
    578587                <para>By Id (atom with id 76)</para>
     588                <programlisting>
     589                ... --select-atom-by-id 76
     590                </programlisting>
     591                <programlisting>
     592                ... --unselect-atom-by-id 76
     593                </programlisting>
    579594              </listitem>
    580595
    581596              <listitem>
    582                 <para>By Order (the first (1), the second, ... the last, the
    583                 last but one)</para>
     597                <para>By Order (the first (1), the second, ... the last
     598                created(-1), the last but one)</para>
     599                <programlisting>
     600                ... --select-atom-by-order 1
     601                </programlisting>
     602                <programlisting>
     603                ... --unselect-atom-by-order -2
     604                </programlisting>
    584605              </listitem>
    585606
    586607              <listitem>
    587608                <para>By Shape (specific region of the domain)</para>
     609                <programlisting>
     610                ... --select-atom-inside-volume
     611                </programlisting>
     612                <programlisting>
     613                ... --unselect-atoms-inside-volume
     614                </programlisting>
    588615              </listitem>
    589616
    … …  
    591618                <para>By Molecule (all atoms belonging to currently selected
    592619                molecules)</para>
     620                <programlisting>
     621                ... --select-molecules-atoms
     622                </programlisting>
     623                <programlisting>
     624                ... --unselect-molecules-atoms
     625                </programlisting>
    593626              </listitem>
    594627            </itemizedlist>
    … …  
    600633            <itemizedlist>
    601634              <listitem>
     635                <para>All</para>
     636                <programlisting>
     637                ... --select-all-molecules
     638                </programlisting>
     639              </listitem>
     640
     641              <listitem>
     642                <para>None</para>
     643                <programlisting>
     644                ... --unselect-all-molecules
     645                </programlisting>
     646                <programlisting>
     647                ... --clear-molecule-selection
     648                </programlisting>
     649              </listitem>
     650
     651              <listitem>
     652                <para>Invert selection</para>
     653                <programlisting>
     654                ... --invert-molecules
     655                </programlisting>
     656              </listitem>
     657
     658              <listitem>
    602659                <para>By Id (molecule with id 4)</para>
     660                <programlisting>
     661                ... --select-molecule-by-id 2
     662                </programlisting>
     663                <programlisting>
     664                ... --unselect-molecule-by-id 2
     665                </programlisting>
    603666              </listitem>
    604667
    605668              <listitem>
    606                 <para>By Order (first molecule, second molecule, ...)</para>
     669                <para>By Order (first created molecule, second created
     670                molecule, ...)</para>
     671                <programlisting>
     672                ... --select-molecule-by-order 2
     673                </programlisting>
     674                <programlisting>
     675                ... --unselect-molecule-by-order -2
     676                </programlisting>
    607677              </listitem>
    608678
    609679              <listitem>
    610                 <para>By Name (molecule named "water4"</para>
     680                <para>By Formula (molecule with H2O as formula)</para>
     681                <programlisting>
     682                ... --select-molecules-by-formula "H2O"
     683                </programlisting>
     684                <programlisting>
     685                ... --unselect-molecules-by-formula "H2O"
     686                </programlisting>
     687              </listitem>
     688
     689              <listitem>
     690                <para>By Name (molecule named "water4")</para>
     691                <programlisting>
     692                ... --select-molecules-by-name "water4"
     693                </programlisting>
     694                <programlisting>
     695                ... --unselect-molecules-by-name "water4"
     696                </programlisting>
    611697              </listitem>
    612698
    … …  
    614700                <para>By Atom (all molecules for which at least one atom is
    615701                currently selected)</para>
     702                <programlisting>
     703                ... --select-atoms-molecules
     704                </programlisting>
     705                <programlisting>
     706                ... --unselect-atoms-molecules
     707                </programlisting>
    616708              </listitem>
    617709            </itemizedlist>
    618710          </listitem>
    619         </itemizedlist>
    620 
    621         <itemizedlist>
     711
    622712          <listitem>
    623713            <para>Shapes</para>
    … …  
    625715            <itemizedlist>
    626716              <listitem>
     717                <para>All</para>
     718                <programlisting>
     719                ... --select-all-shapes
     720                </programlisting>
     721              </listitem>
     722
     723              <listitem>
     724                <para>None</para>
     725                <programlisting>
     726                ... --unselect-all-shapes
     727                </programlisting>
     728              </listitem>
     729
     730              <listitem>
    627731                <para>By Name (shape name "sphere1")</para>
     732                <programlisting>
     733                ... --select-shape-by-name "sphere1"
     734                </programlisting>
     735                <programlisting>
     736                ... --unselect-shape-by-name "sphere1"
     737                </programlisting>
    628738              </listitem>
    629739            </itemizedlist>
    630740          </listitem>
    631741
    632           <listitem>
    633             <para>All</para>
    634 
    635             <itemizedlist>
    636               <listitem>
    637                 <para>All (selects or unselects all instances of the
    638                 type)</para>
    639               </listitem>
    640 
    641               <listitem>
    642                 <para>Clear (clears the current selection)</para>
    643               </listitem>
    644             </itemizedlist>
    645           </listitem>
    646742        </itemizedlist>
    647 
    648         <para>Furthermore, a selection can be imverted, e.g. inverting the
    649         current selection of atoms.</para>
    650 
    651         <programlisting>... --invert-atoms</programlisting>
    652743
    653744        <remark>Note that an unselected instance (e.g. an atom) remains
    … …  
    701792
    702793        <section>
     794          <title>Combining shapes</title>
     795
     796          <para>Any two shapes can be combined by boolean operations as follows</para>
     797
     798          <programlisting>
     799                ... --combine-shapes \
     800                    --shape-name "combinedshape" \
     801                    --shape-op "AND" \
     802          </programlisting>
     803
     804          <para>This will combine two currently selected shapes vis the "AND" operation
     805          and create a new shape called "combinedshape". Note that the two old shapes
     806          are still present after this operation. We briefly explain each operation:
     807          </para>
     808          <itemizedlist>
     809            <listitem>
     810              <para><emphasis>AND</emphasis> combines two currently selected shapes
     811              into a new shape that only consists of the volume where shapes overlap.</para>
     812            </listitem>
     813            <listitem>
     814              <para><emphasis>OR</emphasis> combines two currently selected shapes
     815              into a new shape that consists of all the volume where that either shape
     816              occupies.</para>
     817            </listitem>
     818            <listitem>
     819              <para><emphasis>NOT</emphasis> creates the inverse to a currently selected
     820              single shape that contains the volume with respect to the simulation domain
     821              that the present one does not.</para>
     822            </listitem>
     823          </itemizedlist>
     824        </section>
     825
     826        <section>
    703827          <title>Removing shapes</title>
    704828
    … …  
    728852
    729853          <programlisting>
    730                 ... --rotate-shape \
     854                ... --rotate-shapes \
    731855                    --center "10,2,2" \
    732856                    --angle-x 90 \
    … …  
    8971021
    8981022        <section>
     1023          <title>Correcting bond degrees</title>
     1024
     1025          <para>Typically, after loading an input file bond information, e.g.
     1026          a PDB file, the bond graph is complete but we lack the weights. That
     1027          is we do not know whether a bond is single, double, triple, ...
     1028          This action corrects the bond degree by enforcing charge neutrality
     1029          among the connected atoms.
     1030          </para>
     1031          <para>This action is in fact quadratically scaling in the number of
     1032          atoms. Hence, for large systems this may take longer than expected.
     1033          </para>
     1034
     1035          <programlisting>... --correct-bonddegree</programlisting>
     1036        </section>
     1037
     1038        <section>
    8991039          <title>Analysing a bond graph</title>
    9001040
    … …  
    9241064
    9251065        <section>
     1066          <title>Updating molecule structure</title>
     1067
     1068          <para>When the bond information has changed, new molecules might
     1069          have formed, this action updates all the molecules by scanning
     1070          the connectedness of the bond grapf of the molecular system.
     1071          </para>
     1072
     1073          <programlisting>... --update-molecules</programlisting>
     1074        </section>
     1075
     1076        <section>
    9261077          <title>Adding a bond manually</title>
    9271078
    … …  
    9401091
    9411092          <programlisting>... --remove-bond</programlisting>
     1093        </section>
     1094
     1095        <section>
     1096          <title>Saving bond information</title>
     1097
     1098          <para>Bond information can be saved to a file in <link
     1099          xlink:href="http://www.molecuilder.com/"><programname>TREMOLO
     1100          </programname></link>'s dbond style.</para>
     1101
     1102          <programlisting>... --save-bonds system.dbonds</programlisting>
     1103         
     1104          <para>Similarly is the following Action which saves the bond
     1105          information as a simple list of one atomic id per line and in
     1106          the same line, separated by spaces, the ids of all atoms connected
     1107          to it.</para>
     1108         
     1109          <programlisting>... --save-adjacency system.adj</programlisting>
     1110         
    9421111        </section>
    9431112
    … …  
    10151184
    10161185        <section>
    1017           <title>Fill a domain section with molecules</title>
    1018 
     1186          <title>Change a molecules name</title>
     1187
     1188          <para>You can change the name of a molecule which is important for
     1189          selection.</para>
     1190
     1191          <programlisting>... -change-molname "test</programlisting>
     1192
     1193          <para>This will change the name of the (only) selected molecule to
     1194          "test".</para>
     1195
     1196          <para>Connected with this is the default name an unknown molecule
     1197          gets.</para>
     1198
     1199          <programlisting>... --default-molname test</programlisting>
     1200
     1201          <para>This will change the default name of a molecule to
     1202          "test".</para>
     1203
     1204          <note>
     1205            <para>Note that a molecule loaded from file gets the filename
     1206            (without suffix) as its name.</para>
     1207          </note>
     1208        </section>
     1209
     1210        <section>
     1211          <title>Rotate around self</title>
     1212
     1213          <para>You can rotate a molecule around its own axis.</para>
     1214
     1215          <programlisting>
     1216                ... --rotate-around-self "90" \
     1217                    --axis "0,0,1"
     1218          </programlisting>
     1219
     1220          <para>This rotates the molecule around the z axis by 90 degrees as
     1221          if the origin were at its center of origin.</para>
     1222        </section>
     1223
     1224        <section>
     1225          <title>Rotate around origin</title>
     1226
     1227          <para>In the same manner the molecule can be rotated around an
     1228          external origin.</para>
     1229
     1230          <programlisting>
     1231                ... --rotate-around-origin 90 \
     1232                    --position "0,0,1"\
     1233          </programlisting>
     1234
     1235          <para>This rotates the molecule around an axis from the origin to
     1236          the position (0,0,1), i.e. around the z axis, by 90 degrees.</para>
     1237        </section>
     1238
     1239        <section>
     1240          <title>Rotate to principal axis system</title>
     1241
     1242          <para>The principal axis system is given by an ellipsoid that mostly
     1243          matches the molecules shape. The principal axis system can be just
     1244          simply determined by</para>
     1245
     1246          <programlisting>... --principal-axis-system</programlisting>
     1247
     1248          <para>To rotate the molecule around itself to align with this system
     1249          do as follows.</para>
     1250
     1251          <programlisting>... --rotate-to-principal-axis-system "0,0,1"</programlisting>
     1252
     1253          <para>This rotates the molecule in such a manner that the ellipsoids
     1254          largest axis is aligned with the z axis. <remark>Note that "0,0,-1"
     1255          would align anti-parallel.</remark></para>
     1256        </section>
     1257
     1258        <section>
     1259          <title>Perform verlet integration</title>
     1260
     1261          <para>Atoms not only have a position, but each instance also stores
     1262          velocity and a force vector. These can be used in a velocity verlet
     1263          integration step. Velocity verlet is a often employed time
     1264          integration algorithm in molecular dynamics simulations.</para>
     1265
     1266          <programlisting>
     1267                ... --verlet-integration \
     1268                    --deltat 0.1 \
     1269                    --keep-fixed-CenterOfMass 0
     1270          </programlisting>
     1271
     1272          <para>This will integrate with a timestep of <inlineequation>
     1273              <m:math display="inline">
     1274                <m:mi>\Delta_t = 0.1</m:mi>
     1275              </m:math>
     1276            </inlineequation>and correcting forces and velocities such that
     1277          the sum over all atoms is zero.</para>
     1278        </section>
     1279
     1280        <section>
     1281          <title>Anneal the atomic forces</title>
     1282
     1283          <para>This will shift the atoms in a such a way as to decrease (or
     1284          anneal) the forces acting upon them.</para>
     1285
     1286          <para>Forces may either be already present for the set of atoms by
     1287          some other way (e.g. from a prior fragmentation calculation) or,
     1288          as shown here, from an external file. We anneal the forces for
     1289          one step with a certain initial step width of 0.5 atomic time
     1290          units and do not create a new timestep for each optimization
     1291          step.</para>
     1292
     1293          <programlisting>
     1294          ... --force-annealing \
     1295          --forces-file test.forces \
     1296          --deltat 0.5 \
     1297          --steps 1 \
     1298          --output-every-step 0
     1299          </programlisting>
     1300        </section>
     1301
     1302        <section>
     1303          <title>Linear interpolation between configurations</title>
     1304
     1305          <para>This is similar to verlet-integration, only that it performs
     1306          a linear integration irrespective of the acting atomic forces.
     1307          </para>
     1308
     1309          <para>The following call will produce an interpolation between the
     1310          configurations in time step 0 and time step 1 with 98 intermediate
     1311          steps, i.e. current step 1 will end up in time step 99. In this
     1312          case an idential mapping is used to associated atoms in start and
     1313          end configuration.</para>
     1314
     1315          <programlisting>
     1316          ... --linear-interpolation-of-trajectories \
     1317          --start-step 0 \
     1318          --end-step 1 \
     1319          --interpolation-steps 100 \
     1320          --id-mapping 1
     1321          </programlisting>
     1322        </section>
     1323      </section>
     1324
     1325      <section>
     1326        <title>Manipulate domain</title>
     1327
     1328        <para>Here, we elaborate on how to duplicate all the atoms inside the
     1329        domain, how the scale the coordinate system, how to center the atoms
     1330        with respect to certain points, how to realign them by given
     1331        constraints, how to mirror and most importantly how to specify the
     1332        domain.</para>
     1333
     1334        <section>
     1335          <title>Changing the domain</title>
     1336
     1337          <para>The domain is specified by a symmetric 3x3 matrix. The
     1338          eigenvalues (diagonal entries in case of a diagonal matrix) give the
     1339          length of the edges, additional entries specify transformations of
     1340          the box such that it becomes a more general parallelepiped.</para>
     1341
     1342          <programlisting>... change-box "20,0,20,0,0,20"</programlisting>
     1343
     1344          <para>As the domain matrix is symmetric, six values suffice to fully
     1345          specify it. We have to give the six components of the lower diagonal
     1346          matrix. Here, we change the box to a cuboid of equal edge length of
     1347          20.</para>
     1348        </section>
     1349
     1350        <section>
     1351          <title>Bound atoms inside box</title>
     1352
     1353          <para>The following applies the current boundary conditions to the
     1354          atoms. In case of periodic or wrapped boundary conditions the atoms
     1355          will be periodically translated to be inside the domain
     1356          again.</para>
     1357
     1358          <programlisting>... --bound-in-box</programlisting>
     1359        </section>
     1360
     1361        <section>
     1362          <title>Center atoms inside the domain</title>
     1363
     1364          <para>This is a combination of changing the box and bounding the
     1365          atoms inside it.</para>
     1366
     1367          <programlisting>... --center-in-box "20,0,20,0,0,"</programlisting>
     1368        </section>
     1369
     1370        <section>
     1371          <title>Center the atoms at an edge</title>
     1372
     1373          <para>MoleCuilder can calculate the minimum box (parallel to the
     1374          cardinal axis) all atoms would fit in and translate all atoms in
     1375          such a way that the lower, left, front edge of this minimum is at
     1376          the origin (0,0,0).</para>
     1377
     1378          <programlisting>... --center-edge</programlisting>
     1379        </section>
     1380
     1381        <section>
     1382          <title>Extending the boundary by adding an empty boundary</title>
     1383
     1384          <para>In the same manner as above a minimum box is determined that
     1385          is subsequently expanded by a boundary of the given additional
     1386          thickness. This applies to either side.</para>
     1387
     1388          <programlisting>... --add-empty-boundary "5,5,5"</programlisting>
     1389
     1390          <para>This will enlarge the box in such a way that every atom is at
     1391          least by a distance of 5 away from the boundary of the domain (in
     1392          the infinity norm).</para>
     1393        </section>
     1394
     1395        <section>
     1396          <title>Scaling the box</title>
     1397
     1398          <para>You can enlarge the domain by simple scaling factors.</para>
     1399
     1400          <programlisting>... --scale-box "1,1,2.5"</programlisting>
     1401
     1402          <para>Here, the domain is stretched in the z direction by a factor
     1403          of 2.5.</para>
     1404        </section>
     1405
     1406        <section>
     1407          <title>Repeating the box</title>
     1408
     1409          <para>Under periodic boundary conditions often only the minimal
     1410          periodic cell is stored. If need be, multiple images can be easily
     1411          added to the current state of the system by repeating the box, i.e.
     1412          the box along with all contained atoms is copied and placed
     1413          adjacently.</para>
     1414
     1415          <programlisting>... --repeat-box "1,2,2"</programlisting>
     1416
     1417          <para>This will create a 2x2 grid of the current domain, replicating
     1418          it along the y and z direction along with all atoms. If the domain
     1419          contained before a single water molecule, we will now have four of
     1420          them.</para>
     1421        </section>
     1422       
     1423        <section>
     1424          <title>Change the boundary conditions</title>
     1425
     1426          <para>Various boundary conditions can be applied that affect how
     1427          certain Actions work, e.g. translate-atoms. We briefly give a list
     1428          of all possible conditions:</para>
     1429          <itemizedlist>
     1430            <listitem>
     1431              <para>Wrap</para>
     1432              <para>Coordinates are wrapped to the other side of the domain,
     1433              i.e. periodic boundary conditions.</para>
     1434            </listitem>
     1435            <listitem>
     1436              <para>Bounce</para>
     1437              <para>Coordinates are bounced back into the domain, i.e. they
     1438              are reflected from the domain walls.</para>
     1439            </listitem>
     1440            <listitem>
     1441              <para>Ignore</para>
     1442              <para>No boundary conditions apply.</para>
     1443            </listitem>
     1444          </itemizedlist>
     1445         
     1446          <para>The following will set the boundary conditions to periodic.
     1447          </para>
     1448
     1449          <programlisting>... --set-boundary-conditions "Wrap Wrap Wrap"
     1450          </programlisting>
     1451        </section>
     1452      </section>
     1453
     1454      <section>
     1455        <title>Filling</title>
     1456       
    10191457          <para>Filling a specific part of the domain with one type of
    10201458          molecule, e.g. a water molecule, is the more advanced type of
    1021           copying and we need several ingredients.</para>
     1459          copying of a molecule (see copy-molecule) and we need several
     1460          ingredients.</para>
    10221461
    10231462          <para>First, we need to specify the part of the domain. This is done
    … …  
    10261465          region.</para>
    10271466
    1028           <para>Then, they are two types of filling, volume and surface. The
    1029           volume is filled with a regular grid of fill-in points, and in the
    1030           same manner is the surface filled with a regular grid of points.
    1031           Molecules will be copied and translated points when they
     1467          <para>Then, they are three types of filling, domain, volume, and
     1468          surface. The domain is filled with a regular grid of fill-in points.
     1469          A volume and a surface are filled by a set of equidistant points
     1470          distributed within the volume or on the surface of a selected
     1471          shape. Molecules will then be copied and translated points when they
    10321472          "fit".</para>
    10331473
    … …  
    10431483          additionally excluded from the filling region.</para>
    10441484
     1485        <section>
     1486          <title>Fill the domain with molecules</title>
     1487
    10451488          <para>The call to fill the volume of the selected shape with the
    10461489          selected atoms is then as follows,</para>
    … …  
    10501493                    --mesh-size "5,5,5" \
    10511494                    --mesh-offset ".5,.5,.5" \
    1052                     --DoRotate 1 --min-distance 1. \
     1495                    --DoRotate 1 \
     1496                    --min-distance 1. \
    10531497                    --random-atom-displacement 0.05 \
    10541498                    --random-molecule-displacement 0.4 \
    … …  
    10681512
    10691513        <section>
    1070           <title>Change a molecules name</title>
    1071 
    1072           <para>You can change the name of a molecule which is important for
    1073           selection.</para>
    1074 
    1075           <programlisting>... -change-molname "test</programlisting>
    1076 
    1077           <para>This will change the name of the (only) selected molecule to
    1078           "test".</para>
    1079 
    1080           <para>Connected with this is the default name an unknown molecule
    1081           gets.</para>
    1082 
    1083           <programlisting>... --default-molname test</programlisting>
    1084 
    1085           <para>This will change the default name of a molecule to
    1086           "test".</para>
    1087 
    1088           <note>
    1089             <para>Note that a molecule loaded from file gets the filename
    1090             (without suffix) as its name.</para>
    1091           </note>
    1092         </section>
    1093 
    1094         <section>
    1095           <title>Rotate around self</title>
    1096 
    1097           <para>You can rotate a molecule around its own axis.</para>
    1098 
    1099           <programlisting>
    1100                 ... --rotate-around-self "90" \
    1101                     --axis "0,0,1"
     1514          <title>Fill a shape's volume with molecules</title>
     1515         
     1516          <para>More specifically than filling the whole domain with molecules,
     1517          maybe except areas where other molecules already are, we also can
     1518          fill only specific parts by selecting a shape and calling upon
     1519          the following action:</para>
     1520
     1521          <programlisting>
     1522                ... --fill-volume \
     1523                    --counts 12 \
     1524                    --min-distance 1. \
     1525                    --DoRotate 1 \
     1526                    --random-atom-displacement 0.05 \
     1527                    --random-molecule-displacement 0.4 \
     1528                    --tesselation-radius 2.5
    11021529          </programlisting>
    1103 
    1104           <para>This rotates the molecule around the z axis by 90 degrees as
    1105           if the origin were at its center of origin.</para>
    1106         </section>
    1107 
    1108         <section>
    1109           <title>Rotate around origin</title>
    1110 
    1111           <para>In the same manner the molecule can be rotated around an
    1112           external origin.</para>
    1113 
    1114           <programlisting>
    1115                 ... --rotate-around-origin 90 \
    1116                     --position "0,0,1"\
     1530        </section>
     1531         
     1532        <section>
     1533          <title>Fill a shape's surface with molecules</title>
     1534
     1535                  <para>Filling a surface is very similar to filling its volume.
     1536                  Again the number of equidistant points has to be specified.
     1537                  However, randomness is constrained as the molecule is be aligned
     1538                  with the surface in a specific manner. The alignment axis refers
     1539                  to the largest principal axis of the filler molecule and will
     1540                  be aligned parallel to the surface normal at the fill-in point.
     1541                  </para>
     1542
     1543                  <para>The call below fill in 12 points with a minimum distance
     1544                  between the instances of 1 angstroem. We allow for certain random
     1545                  displacements and use the z-axis for aligning the molecules on
     1546                  the surface.</para>
     1547
     1548          <programlisting>
     1549                ... --fill-surface \
     1550                    --counts 12 \
     1551                    --min-distance 1. \
     1552                    --DoRotate 1 \
     1553                    --random-atom-displacement 0.05 \
     1554                    --random-molecule-displacement 0.4 \
     1555                    --Alignment-Axis "0,0,1"
    11171556          </programlisting>
    1118 
    1119           <para>This rotates the molecule around an axis from the origin to
    1120           the position (0,0,1), i.e. around the z axis, by 90 degrees.</para>
    1121         </section>
    1122 
    1123         <section>
    1124           <title>Rotate to principal axis system</title>
    1125 
    1126           <para>The principal axis system is given by an ellipsoid that mostly
    1127           matches the molecules shape. The principal axis system can be just
    1128           simply determined by</para>
    1129 
    1130           <programlisting>... --principal-axis-system</programlisting>
    1131 
    1132           <para>To rotate the molecule around itself to align with this system
    1133           do as follows.</para>
    1134 
    1135           <programlisting>... --rotate-to-principal-axis-system "0,0,1"</programlisting>
    1136 
    1137           <para>This rotates the molecule in such a manner that the ellipsoids
    1138           largest axis is aligned with the z axis. <remark>Note that "0,0,-1"
    1139           would align anti-parallel.</remark></para>
    1140         </section>
    1141 
    1142         <section>
    1143           <title>Perform verlet integration</title>
    1144 
    1145           <para>Atoms not only have a position, but each instance also stores
    1146           velocity and a force vector. These can be used in a velocity verlet
    1147           integration step. Velocity verlet is a often employed time
    1148           integration algorithm in molecular dynamics simulations.</para>
    1149 
    1150           <programlisting>
    1151                 ... --verlet-integration \
    1152                     --deltat 0.1 \
    1153                     --keep-fixed-CenterOfMass 0
    1154           </programlisting>
    1155 
    1156           <para>This will integrate with a timestep of <inlineequation>
    1157               <m:math display="inline">
    1158                 <m:mi>\Delta_t = 0.1</m:mi>
    1159               </m:math>
    1160             </inlineequation>and correcting forces and velocities such that
    1161           the sum over all atoms is zero.</para>
     1557        </section>
     1558
     1559        <section>
     1560          <title>Suspend in molecule</title>
     1561
     1562          <para>Add a given molecule in the simulation domain in such a way
     1563          that the total density is as desired.</para>
     1564
     1565          <programlisting>
     1566                ... --suspend-in-molecule 1.
     1567              </programlisting>
     1568        </section>
     1569
     1570        <section>
     1571          <title>Fill in molecule</title>
     1572
     1573          <para>This action will be soon be removed.</para>
     1574
     1575          <programlisting>
     1576                ... --fill-molecule
     1577              </programlisting>
     1578        </section>
     1579
     1580        <section>
     1581          <title>Fill void with molecule</title>
     1582
     1583          <para>This action will be soon be removed.</para>
     1584
     1585          <programlisting>
     1586                ... --fill-void
     1587              </programlisting>
    11621588        </section>
    11631589      </section>
    11641590
    11651591      <section>
    1166         <title>Manipulate domain</title>
    1167 
    1168         <para>Here, we elaborate on how to duplicate all the atoms inside the
    1169         domain, how the scale the coordinate system, how to center the atoms
    1170         with respect to certain points, how to realign them by given
    1171         constraints, how to mirror and most importantly how to specify the
    1172         domain.</para>
    1173 
    1174         <section>
    1175           <title>Changing the domain</title>
    1176 
    1177           <para>The domain is specified by a symmetric 3x3 matrix. The
    1178           eigenvalues (diagonal entries in case of a diagonal matrix) give the
    1179           length of the edges, additional entries specify transformations of
    1180           the box such that it becomes a more general parallelepiped.</para>
    1181 
    1182           <programlisting>... change-box "20,0,20,0,0,20"</programlisting>
    1183 
    1184           <para>As the domain matrix is symmetric, six values suffice to fully
    1185           specify it. We have to give the six components of the lower diagonal
    1186           matrix. Here, we change the box to a cuboid of equal edge length of
    1187           20.</para>
    1188         </section>
    1189 
    1190         <section>
    1191           <title>Bound atoms inside box</title>
    1192 
    1193           <para>The following applies the current boundary conditions to the
    1194           atoms. In case of periodic or wrapped boundary conditions the atoms
    1195           will be periodically translated to be inside the domain
    1196           again.</para>
    1197 
    1198           <programlisting>... --bound-in-box</programlisting>
    1199         </section>
    1200 
    1201         <section>
    1202           <title>Center atoms inside the domain</title>
    1203 
    1204           <para>This is a combination of changing the box and bounding the
    1205           atoms inside it.</para>
    1206 
    1207           <programlisting>... --center-in-box "20,0,20,0,0,"</programlisting>
    1208         </section>
    1209 
    1210         <section>
    1211           <title>Center the atoms at an edge</title>
    1212 
    1213           <para>MoleCuilder can calculate the minimum box (parallel to the
    1214           cardinal axis) all atoms would fit in and translate all atoms in
    1215           such a way that the lower, left, front edge of this minimum is at
    1216           the origin (0,0,0).</para>
    1217 
    1218           <programlisting>... --center-edge</programlisting>
    1219         </section>
    1220 
    1221         <section>
    1222           <title>Extending the boundary by adding an empty boundary</title>
    1223 
    1224           <para>In the same manner as above a minimum box is determined that
    1225           is subsequently expanded by a boundary of the given additional
    1226           thickness. This applies to either side.</para>
    1227 
    1228           <programlisting>... --add-empty-boundary "5,5,5"</programlisting>
    1229 
    1230           <para>This will enlarge the box in such a way that every atom is at
    1231           least by a distance of 5 away from the boundary of the domain (in
    1232           the infinity norm).</para>
    1233         </section>
    1234 
    1235         <section>
    1236           <title>Scaling the box</title>
    1237 
    1238           <para>You can enlarge the domain by simple scaling factors.</para>
    1239 
    1240           <programlisting>... --scale-box "1,1,2.5"</programlisting>
    1241 
    1242           <para>Here, the domain is stretched in the z direction by a factor
    1243           of 2.5.</para>
    1244         </section>
    1245 
    1246         <section>
    1247           <title>Repeating the box</title>
    1248 
    1249           <para>Under periodic boundary conditions often only the minimal
    1250           periodic cell is stored. If need be, multiple images can be easily
    1251           added to the current state of the system by repeating the box, i.e.
    1252           the box along with all contained atoms is copied and placed
    1253           adjacently.</para>
    1254 
    1255           <programlisting>... --repeat-box "1,2,2"</programlisting>
    1256 
    1257           <para>This will create a 2x2 grid of the current domain, replicating
    1258           it along the y and z direction along with all atoms. If the domain
    1259           contained before a single water molecule, we will now have four of
    1260           them.</para>
    1261         </section>
     1592        <title>Analysis</title>
     1593
     1594                <para></para>
     1595
     1596        <section>
     1597          <title>Pair Correlation</title>
     1598         
     1599          <para>Pair correlation checks for two given elements on the typical
     1600          distance they can be found with respect to one another. E.g. for
     1601          water one might be interested what is the typical distance for
     1602          hydrogen and oxygen atoms.</para>
     1603
     1604          <programlisting>
     1605          ... --pair-correlation \
     1606              --elements 1 8 \
     1607              --bin-start 0 \
     1608              --bin-width 0.7 \
     1609              --bin-end 10 \
     1610              --output-file histogram.dat \
     1611              --bin-output-file bins.dat \
     1612              --periodic 0
     1613          </programlisting>
     1614         
     1615          <para>This will compile a histogram for the interval [0,10] in steps
     1616          of 0.7 and increment a specific bin if the distance of one such pair
     1617          of a hydrogen and an oxygen atom can be found within its distance
     1618          interval.</para>
     1619        </section>
     1620
     1621        <section>
     1622          <title>Dipole Correlation</title>
     1623         
     1624          <para>The dipole correlation is similar to the pair correlation, only
     1625          that it correlates the orientation of dipoles in the molecular
     1626          system with one another.</para>
     1627          <para>Note that the dipole correlation works on the currently
     1628          selected molecules, e.g. all water molecules if so selected.</para>
     1629
     1630          <programlisting>
     1631          ... --dipole-correlation \
     1632              --bin-start 0 \
     1633              --bin-width 0.7 \
     1634              --bin-end 10 \
     1635              --output-file histogram.dat \
     1636              --bin-output-file bins.dat \
     1637              --periodic 0
     1638          </programlisting>
     1639        </section>
     1640
     1641        <section>
     1642          <title>Dipole Angular Correlation</title>
     1643         
     1644          <para>The dipole angular correlation looks at the angles of a
     1645          dipole over time. It takes the orientation of a certain time step
     1646          as the zero angle and bins all other orientations found in later
     1647          time steps relative to it.
     1648          </para>
     1649          <para>Note that in contrast to the dipole correlation the dipole
     1650          angular correlation works on the molecules determined by a formula.
     1651          This is because selections do not work over time steps as molecules
     1652          might change.
     1653          </para>
     1654
     1655          <programlisting>
     1656          ... --dipole-angular-correlation H2O \
     1657              --bin-start 0 \
     1658              --bin-width 5 \
     1659              --bin-end 360 \
     1660              --output-file histogram.dat \
     1661              --bin-output-file bins.dat \
     1662              --periodic 0 \
     1663              --time-step-zero 0
     1664          </programlisting>
     1665        </section>
     1666
     1667        <section>
     1668          <title>Point Correlation</title>
     1669         
     1670          <para>Point correlation is very similar to pair correlation, only
     1671          that it correlates not positions of atoms among one another but
     1672          against a fixed, given point.</para>
     1673
     1674          <programlisting>
     1675          ... --point-correlation \
     1676              --elements 1 8 \
     1677              --position "0,0,0" \
     1678              --bin-start 0 \
     1679              --bin-width 0.7 \
     1680              --bin-end 10 \
     1681              --output-file histogram.dat \
     1682              --bin-output-file bins.dat \
     1683              --periodic 0
     1684          </programlisting>
     1685         
     1686          <para>This would calculate the correlation of all hydrogen and
     1687          oxygen atoms with respect to the origin.</para>
     1688        </section>
     1689
     1690        <section>
     1691          <title>Surface Correlation</title>
     1692         
     1693          <para>The surface correlation calculates the distance of a set
     1694          of atoms with respect to a tesselated surface.</para>
     1695
     1696          <programlisting>
     1697          ... --surface-correlation \
     1698              --elements 1 8 \
     1699              --bin-start 0 \
     1700              --bin-width 0.7 \
     1701              --bin-end 10 \
     1702              --output-file histogram.dat \
     1703              --bin-output-file bins.dat \
     1704              --periodic 0
     1705          </programlisting>
     1706        </section>
     1707
     1708        <section>
     1709          <title>Molecular Volume</title>
     1710         
     1711          <para>This simply calculates the volume that a selected molecule
     1712          occupies. For this the molecular surface is determined via a
     1713          tesselation. Note that this surface is minimal is that aspect
     1714          that each node of the tesselation consists of an atom of the
     1715          molecule.</para>
     1716
     1717          <programlisting>... --molecular-volume</programlisting>
     1718        </section>
     1719
    12621720      </section>
    12631721
    … …  
    13041762        equation. Such a calculation is implemented via the solver
    13051763        <productname>vmg</productname> by Julian Iseringhausen that is
    1306         contained in the <productname>ScaFaCoS</productname> package (<link
    1307         xlink:href="???">http://www.scafacos.org/</link>).</para>
     1764        contained in the <link xlink:href="http://www.scafacos.org/">
     1765        <productname>ScaFaCoS</productname></link>.</para>
    13081766
    13091767        <para>Note that we treat hydrogen special (but can be switched off) as
    … …  
    14851943          integration</link> is possible afterwards.</para>
    14861944        </section>
     1945       
     1946        <section>
     1947          <title>Store a saturated fragment</title>
     1948
     1949          <para>After the energies and force vectors of each fragment have
     1950          been calculated, they need to be summed up to an approximation for
     1951          the energy and force vectors of the whole molecular system. This is
     1952          done by calling this action.</para>
     1953
     1954          <para>This will store the currently selected atoms as a fragment
     1955          where all dangling bonds (by atoms that are connected in the bond
     1956          graph but have not been selected as well) are saturated with
     1957          additional hydrogen atoms. The output formats are set to just xyz.
     1958          </para>
     1959
     1960          <programlisting>
     1961                ... --store-saturated-fragment \
     1962                    --DoSaturate 1 \
     1963                    --output-types xyz
     1964              </programlisting>
     1965        </section>
    14871966      </section>
    14881967
    … …  
    15292008        container.</para>
    15302009
    1531         <programlisting>... --store-homologies homologies.dat</programlisting>
     2010        <programlisting>... --save-homologies homologies.dat</programlisting>
    15322011
    15332012        <para>Complementary, this stores the current contents of the homology
    … …  
    16192098
    16202099        <section>
    1621           <title>Fitting partial charges</title>
     2100          <title>Fitting particle charges</title>
    16222101
    16232102          <para>The above empirical potential just model the short-range
    16242103          behavior in the molecular fragment, namely the bonded interaction.
    16252104          In order to model the long-range interaction as well without solving
    1626           for the electronic ground state in each time step, partial charges
     2105          for the electronic ground state in each time step, particle charges
    16272106          are used that capture to some degree the created dipoles due to
    16282107          charge transfer from one atom to another when bonded.</para>
    … …  
    16362115
    16372116          <programlisting>
    1638                 ... --fit-partial-charges \
     2117                ... --fit-particle-charges \
    16392118                    --fragment-charges 8 1 1 \
    16402119                    --potential-file water.potentials \
    … …  
    16542133
    16552134      <section>
     2135        <title>Dynamics</title>
     2136
     2137        <para>For fitting potentials or charges we need many homologuous but
     2138        different fragments, i.e. atoms with slightly different positions.
     2139        How can we generate these?</para>
     2140
     2141        <para>One possibility is to use molecular dynamics. With the
     2142        aforementioned fragmentation scheme we can quickly calculate not only
     2143        energies but also forces if the chosen solver, such as
     2144        <link xlink:href="http://www.mpqc.org/"><productname>MPQC
     2145        </productname></link>, supports it. Integrating these forces discretely over time
     2146        gives insight into vibrational features of a molecular system and
     2147        allows to generate those positions for fitting potentials that
     2148        describe these vibrations.</para>
     2149
     2150        <section>
     2151          <title>Molecular dynamics</title>
     2152
     2153          <para>The molecular dynamics action is a so-called macro Action,
     2154          i.e. it combines several other Actions into one, namely:</para>
     2155                  <itemizedlist>
     2156            <listitem>
     2157              <para>--verlet-integration</para>
     2158            </listitem>
     2159            <listitem>
     2160              <para>--output</para>
     2161            </listitem>
     2162            <listitem>
     2163              <para>--clear-fragment-results</para>
     2164            </listitem>
     2165            <listitem>
     2166              <para>--destroy-adjacency</para>
     2167            </listitem>
     2168            <listitem>
     2169              <para>--create-adjacency</para>
     2170            </listitem>
     2171            <listitem>
     2172              <para>--update-molecules</para>
     2173            </listitem>
     2174            <listitem>
     2175              <para>--fragment-molecule</para>
     2176            </listitem>
     2177            <listitem>
     2178              <para>--fragment-automation</para>
     2179            </listitem>
     2180            <listitem>
     2181              <para>--analyse-fragment-results</para>
     2182            </listitem>
     2183                  </itemizedlist>
     2184                 
     2185                  <para>The following will perform a molecular dynamics simulation
     2186                  for 100 time steps, each time step combining 0.5 atomic time units,
     2187                  i.e. 1.2 1e-17 s. The other options listed below will seem familiar
     2188                  to you if you have read about the other Actions listed above. Below
     2189                  we will not keep the bondgraph, i.e bonds and molecules may change
     2190                  over the simulation and hence also the created fragments per time
     2191                  step.
     2192                  </para>
     2193
     2194          <programlisting>
     2195          ... --molecular-dynamics \
     2196          --steps 100 \
     2197          --keep-bondgraph 0 \
     2198          --order 3 \
     2199          --distance 3. \
     2200          --deltat 0.5 \
     2201          --keep-fixed-CenterOfMass 1 \
     2202          --fragment-executable mpqc \
     2203          </programlisting>
     2204        </section>
     2205
     2206        <section>
     2207          <title>Structure optimization</title>
     2208
     2209                  <para>Structure optimization is also a macro Action, it basically
     2210                  combines the same Actions as molecular-dynamics does. However, it
     2211                  uses force-annealing instead of verlet-integration.</para>
     2212
     2213                  <para>The following performs a structure optimization of the
     2214                  currently selected atoms (may also be a subset) for up to 100 time
     2215                  steps, where each time step ist 0.5 atomic time units. The time
     2216                  step here is the initial step with for annealing.
     2217                  </para>
     2218
     2219          <programlisting>
     2220          ... --optimize-structure \
     2221          --keep-bondgraph 1 \
     2222          --output-every-step 1 \
     2223          --steps 100 \
     2224          --order 3 \
     2225          --distance 3. \
     2226          --deltat 0.5 \
     2227          --keep-fixed-CenterOfMass 1 \
     2228          --fragment-executable mpqc \
     2229          </programlisting>
     2230
     2231                  <para>Note that output-every-step will allow you to watch the
     2232                  optimization as each step is placed into a distinct time step.
     2233                  Otherwise only two time steps would be created: the initial and
     2234                  the final one containing the optimized structure.</para>
     2235        </section>
     2236
     2237        <section>
     2238          <title>Set the world's time step</title>
     2239
     2240                  <para>In order to inspect or manipulate atoms and molecules at a
     2241                  certain time step, the World's time has to be set with the following
     2242                  Action.
     2243                  </para>
     2244                 
     2245                  <para>This will set the World's time to the fifth step (counting
     2246                  starts at zero).</para>
     2247
     2248          <programlisting>... --set-world-time 4</programlisting>
     2249        </section>
     2250
     2251        <section>
     2252          <title>Save the temperature information</title>
     2253
     2254                  <para>For each time step the temperature (i.e. the average velocity
     2255                  per atom times its mass) will be stored to a file.</para>
     2256
     2257          <programlisting>
     2258          ... --save-temperature temperature.dat \
     2259          </programlisting>
     2260        </section>
     2261      </section>
     2262   
     2263      <section>
     2264        <title>Tesselations</title>
     2265
     2266        <para>Tesselations obtain molecular surfaces (and volumes) by rolling
     2267        a virtual sphere of a certain radii on a molecule until a closed
     2268        surface of connected triangles is created.</para>
     2269
     2270        <section>
     2271          <title>Non-convex envelope</title>
     2272         
     2273          <para>This will create a non-convex envelope for a molecule.</para>
     2274
     2275          <programlisting>
     2276          ... --nonconvex-envelope 6. \
     2277          --nonconvex-file nonconvex.dat
     2278          </programlisting>
     2279
     2280          <para>This tesselation file can be conveniently viewed with
     2281          <programname>TecPlot</programname> or with one of the Tcl script
     2282          in the util folder with <programname>VMD</programname>.</para>
     2283        </section>
     2284
     2285        <section>
     2286          <title>Convex envelope</title>
     2287         
     2288          <para>This will create a convex envelope for a molecule.</para>
     2289
     2290          <programlisting>
     2291          ... --convex-envelope 6. \
     2292          --convex-file convex.dat
     2293          </programlisting>
     2294
     2295          <para>This tesselation file can be conveniently viewed with
     2296          <programname>TecPlot</programname> or with one of the Tcl script
     2297          in the util folder with <programname>VMD</programname>.</para>
     2298        </section>
     2299      </section>
     2300
     2301      <section>
    16562302        <title>Various commands</title>
    16572303
    … …  
    16772323
    16782324        <section>
     2325          <title>Loading an element database</title>
     2326
     2327          <para>Element databases contain information on valency, van der
     2328          Waals-radii and other information for each element.</para>
     2329
     2330          <para>This loads all element database from the current folder (in a
     2331          unix environment):</para>
     2332
     2333          <programlisting>... --element-db ./</programlisting>
     2334
     2335        </section>
     2336
     2337        <section>
     2338          <title>Fast parsing</title>
     2339
     2340          <para>Parsing all time steps from a given input file can take a
     2341          while, especially for larger systems. If fast parsing is activated,
     2342          only the first time step is loaded, all other are ignored.</para>
     2343
     2344          <programlisting>... --fastparsing 1</programlisting>
     2345        </section>
     2346
     2347        <section>
    16792348          <title>Giving the version of the program</title>
    16802349
    … …  
    16922361
    16932362          <programlisting>... --warranty</programlisting>
     2363        </section>
     2364
     2365        <section>
     2366          <title>Giving redistribution information</title>
     2367
     2368          <para>This gives information on the license and how to redistribute
     2369          the program and its source code</para>
     2370
     2371          <programlisting>... --help-redistribute</programlisting>
    16942372        </section>
    16952373      </section>
    … …  
    17052383        session at the point where your attempts start to deviate from one
    17062384        another.</para>
     2385
     2386        <section>
     2387          <title>Storing a session</title>
     2388
     2389          <para>Storing sessions is simple,</para>
     2390
     2391          <programlisting>
     2392                  ... --store-session "session.py" \
     2393                      --session-type python
     2394              </programlisting>
     2395
     2396          <para>Here, the session type is given as python (the other option is
     2397          cli for in the manner of the command-line interface) and the written
     2398          python script <filename>session.py</filename> can even be used with
     2399          the python interface described below, i.e. it is a full python script
     2400          (that however requires the so-called pyMoleCuilder module).</para>
     2401        </section>
     2402
     2403        <section>
     2404          <title>Loading a session</title>
     2405
     2406          <para>Loading a session only works for python scripts. This actually
     2407          blurs the line between the command-line interface and the python
     2408          interface a bit. But even more, MoleCuilder automatically executes a
     2409          script called <filename>molecuilder.py</filename> if such a file is
     2410          contained in the current directory.</para>
     2411
     2412          <programlisting>... --load-session "session.py"</programlisting>
     2413
     2414          <para>This will execute every action with its options contained in the
     2415          script <filename>session.py</filename>.</para>
     2416        </section>
    17072417      </section>
    17082418
    17092419      <section>
    1710         <title>Storing a session</title>
    1711 
    1712         <para>Storing sessions is simple,</para>
    1713 
    1714         <programlisting>
    1715                 ... --store-session "session.py" \
    1716                     --session-type python
    1717         </programlisting>
    1718 
    1719         <para>Here, the session type is given as python (the other option is
    1720         cli for in the manner of the command-line interface) and the written
    1721         python script <filename>session.py</filename> can even be used with
    1722         the python interface described below, i.e. it is a full python script
    1723         (that however requires the so-called pyMoleCuilder module).</para>
    1724       </section>
    1725 
    1726       <section>
    1727         <title>Loading a session</title>
    1728 
    1729         <para>Loading a session only works for python scripts. This actually
    1730         blurs the line between the command-line interface and the python
    1731         interface a bit. But even more, MoleCuilder automatically executes a
    1732         script called <filename>molecuilder.py</filename> if such a file is
    1733         contained in the current directory.</para>
    1734 
    1735         <programlisting>... --load-session "session.py"</programlisting>
    1736 
    1737         <para>This will execute every action with its options contained in the
    1738         script <filename>session.py</filename>.</para>
     2420        <title>Various specific commands</title>
     2421       
     2422        <para>In this (final) section of the action description we list a number
     2423        Actions that are very specific to some purposes (or other programs).
     2424        </para>
     2425       
     2426        <section>
     2427          <title>Saving exttypes of a set of atoms</title>
     2428         
     2429          <para>This saves the atomic ids of all currently selected atoms in a
     2430           <link xlink:href="http://www.tremolo-x.com/"><programname>TREMOLO
     2431           </programname></link> exttypes file with the given name.</para>
     2432
     2433          <programlisting>
     2434          ... --save-selected-atoms-as-exttypes \
     2435          --filename test.exttypes </programlisting>
     2436        </section>
     2437       
     2438        <section>
     2439          <title>Setting parser specific parameters</title>
     2440
     2441          <para>You can also tweak the parameters stored in this file easily.
     2442          For example, <productname>MPQC</productname> stores various
     2443          parameters modifying the specific ab-initio calculation performed.
     2444          For <link xlink:href="http://www.mpqc.org/"><productname>MPQC
     2445          </productname></link> and
     2446          <link xlink:href="http://www.psicode.org/"><productname>Psi4
     2447          </productname></link> this can be modified as follows.</para>
     2448
     2449          <programlisting>
     2450                ... --set-parser-parameters mpqc \
     2451                    --parser-parameters "theory=CLHF;basis=6-31*G;"
     2452          </programlisting>
     2453
     2454          <para>This sets the ab-initio theory to closed-shell Hartree-Fock
     2455          and the basis set to 6-31*G. Please check the
     2456          <productname>MPQC</productname> manual on specific
     2457          parameters.</para>
     2458        </section>
     2459
     2460        <section>
     2461          <title>Tremolo specific options and potential files</title>
     2462
     2463          <para><productname>TREMOLO</productname>'s configuration files start
     2464          with a specific line telling the amount of information stored in the
     2465          file. This file can be modified, e.g. to enforce storing of
     2466          velocities and forces as well as the atoms positions and
     2467          element.</para>
     2468
     2469          <programlisting>
     2470                ... --set-tremolo-atomdata "ATOM id element u=3 v=3 F=3" \
     2471                    --reset 1
     2472          </programlisting>
     2473
     2474          <para>This will not append but reset the old line and fill it with
     2475          the given string.</para>
     2476
     2477          <para>One specific action is required when loading certain
     2478          <productname>TREMOLO</productname> configuration files. These
     2479          contain element notations that refer to parameterized names used in
     2480          empirical potentials and molecular dynamics simulations and not the
     2481          usual chemical symbols, such as H or O. We may load an auxiliary
     2482          file that gives the required conversion from OH1 to H, which is the
     2483          so-called potential file.</para>
     2484
     2485          <programlisting>... --parse-tremolo-potentials water.potentials</programlisting>
     2486
     2487          <para>This parses the lookup table from the file
     2488          <filename>water.potentials</filename> and it can be used in
     2489          following load actions.</para>
     2490        </section>
    17392491      </section>
    17402492    </section>
    … …  
    20292781
    20302782    <para>Tutorials and more information is available online, see <link
    2031     xlink:href="???">http://www.molecuilder.com/</link>.</para>
     2783    xlink:href="http://www.molecuilder.com/">MoleCuilder's website</link>.
     2784    </para>
    20322785
    20332786    <para>Be aware that in general knowing how the code works allows you to
Note: See TracChangeset for help on using the changeset viewer.