Changes between Initial Version and Version 1 of StartersTutorial


Ignore:
Timestamp:
Jul 6, 2010, 1:54:07 PM (14 years ago)
Author:
FrederikHeber
Comment:

first version of tutorial

Legend:

Unmodified
Added
Removed
Modified
  • StartersTutorial

    v1 v1  
     1= A Starter's tutorial =
     2
     3In this tutorial we will build a hydrogen molecule atom by atom, load another hydrogen molecule from file. We will recognize the bond structure and dissect the system into two separate molecules. We will tesselate one molecule. And eventually, we will do a correlation analysis. Note that this tutorial will not go into the details of the code, it will just explain what to do and what happens using molecuilder on the command line.
     4
     5We assume throughout this tutorial that your main folder is ''molecuilder'', that you have created a subfolder called ''build'' wherein the compilation took place and the executable's path is then ''molecuilder/build/src/molecuilder''. We assume that you have entered the ''build'' directory before starting this tutorial, hence molecuilder can be launched by entering ''./src/molecuilder''.
     6
     7It is helpful to visually inspect the outputs of molecuilder at each step, [[http://jmol.sourceforge.net/ Jmol]] or [[http://www.ks.uiuc.edu/Research/vmd/ vmd]] may be helpful for this purpose.
     8
     9== Building hydrogen ==
     10
     11Execute:
     12{{{
     13./src/molecuilder -i test.conf -o pcp xyz -a 6 --position 0 0 0
     14}}}
     15
     16This will add an "oxygen" atom (atomic number is actually 8 but we correct the error further below) at (0,0,0). Note that we have called the input file ''test'', which will also be the root of all output files (besides the suffix). We create pcp and xyz output files. The former can store information about the domain, too, the latter is a very common format with many molecule viewers such as listed exemplarily above. Furtheron, we don't have to specify ''pcp'' anymore, as ''test.conf'' that we parse and add stuff on top is of ''pcp'' format and will get updated automatically.
     17
     18Note that two files have been created: ''test.conf'' and ''test.conf.xyz''. Both contain information about the added atom, the former a lot of other information, too.
     19
     20Instead of ''-a'' we could have written ''--add-atom'' as well. Almost all actions have this kind of short-form, options such as ''--position'' however never have a short-form. This makes them distinguishable from the actions.
     21
     22Let's continue and define the simulation box:
     23{{{
     24./src/molecuilder -i test.conf -o xyz -B 10 0 10 0 0 10
     25}}}
     26
     27Note that the '''!BoxLength''' entry in ''test.conf'' has changed, while the file ''test.conf.xyz'' has not changed at all.
     28
     29We add the two remaining hydrogen atoms:
     30{{{
     31./src/molecuilder -i test.conf -o xyz -a 1 --position 0.758602 0. 0.504284
     32./src/molecuilder -i test.conf -o xyz -a 1 --position 0.758602 0. -0.504284
     33}}}
     34
     35As of now, "equal" actions cannot be stacked but this will come very soon. Different actions can however be sequenced on the command line. This is also the reason, why ''-o'' has to be placed in front of ''-a'' as otherwise the output files will be present but empty.
     36
     37Let's briefly fix atom 0's element, i.e. convert it from carbon to oxygen.
     38{{{
     39./src/molecuilder -i test.conf -o xyz -e 8 --atom-by-id 0
     40}}}
     41
     42This will change the element of atom with index 0 to 8, i.e. make it an oxygen.
     43
     44Regarding the positions and our domain box, we have set the water molecule a bit right on the corner. Let's shift the molecule a bit
     45
     46{{{
     47./src/molecuilder -i test.conf -o xyz -t -5 0 0 --molecule-by-id 0 --periodic 1
     48}}}
     49
     50Note that we explicitely stated here to have periodic boundary conditions active. Hence, the coordinates get wrapped around. If we parse in a config file, all atoms are automatically put into a single moleculde, here referenced by its index 0.
     51
     52Tedious of entering ''-i test.conf -o xyz'' all the time? If you don't want to check the xyz file, you may also just say ''test.conf'' in its place, which will store information to this pcp config file only.
     53
     54A better approach for making sure all atoms are inside the domain is to use the bound-in-box action:
     55{{{
     56./src/molecuilder -i test.conf -o xyz --bound-in-box
     57}}}
     58
     59Note that this action has no parameter. It has used the box size specified above. As we have already translated the water molecule, nothing should have happened.
     60
     61== Parsing in another water molecule ==
     62
     63Adding atoms singly is now very tedious. Often one already has an xyz description of the molecule. Let's parse in another water molecule from the file [file:water.xyz].
     64{{{
     65./src/molecuilder -i test.conf -o xyz -p water.xyz
     66}}}
     67
     68If we would like to place it right-away somewhere else, we would use this call:
     69{{{
     70./src/molecuilder -i test.conf -o xyz -p water.xyz -t 5 0 0 --molecule-by-id 1 --periodic 1
     71}}}
     72which would translate the newly parsed-in molecule, getting index 1, bey (5,0,0), adhering to periodic boundary conditions.
     73
     74== Use the bond structure ==
     75
     76If we parse in the config files again, we will not have two separate molecules, addressable by indices 0 and 1, but a single one. This is bad. Let's do a graph analysis of the system
     77{{{
     78./src/molecuilder -i test.conf -v 3 -D 2.
     79}}}
     80
     81Note that we have specified here a verbosity level (''-v'') of 3 such that one sees a bit of what's going on.
     82
     83Now lets fix it by
     84{{{
     85./src/molecuilder -i test.conf -I
     86}}}
     87
     88== Tesselate the second molecule ==
     89
     90The last step is especially needed for the following tesselation of the second molecule only:
     91{{{
     92./src/molecuilder -i test.conf -I -N 3. --nonconvex-file NonConvexEnvelope --molecule-by-id 2
     93}}}
     94
     95This will write a [[http://www.tecplot.com/ TecPlot]] conforming file ''!NonConvexEnvelope.dat'' that contains two triangles right on top of each other. Simply because the water molecule is quite flat and has exactly three atoms, i.e. nodes for the boundary graph.
     96
     97== Pair correlation analysis ==
     98
     99We will end this tutorial by doing some analysis on these two water molecules, namely a pair correlation
     100{{{
     101./src/molecuilder -i test.conf -v 3 -C E --elements 1 8 --output-file output-point.csv --bin-output-file bin_output-point.csv --bin-start 0 --bin-end 20
     102}}}
     103
     104and a surface correlation analysis.
     105{{{
     106./src/molecuilder -i test.conf -v 3 -I -C S --elements 1 --output-file output-surface.csv --bin-output-file bin_output-surface.csv --bin-start 0 --bin-width 1. --bin-end 20 --molecule-by-id 2
     107}}}
     108
     109In the respective ''bin_output...csv'' files you find the binned distances between elements hydrogen and oxygen on the one hand and between all hydrogen atoms and the surface of the second water molecule on the other hand.
     110
     111
     112This ends this tutorial. I hope you have got an idea of how molecuilder is put into action and what can be done.