Changes between Initial Version and Version 1 of UseCaseFragmentingPropane

Timestamp:

Mar 26, 2014, 9:59:59 AM (11 years ago)

Author:

FrederikHeber

Comment:

--

UseCaseFragmentingPropane

@@ +1 @@
+= Fragmenting propane =
+
+In this use case we will fragment the molecule propane C,,3,,H,,8,,.
+
+To this end, fetch the XYZ configuration file '''C3H8.xyz''' attached to this page.
+
+Go to the folder where the file has been stored to. We will construct a chain of actions on the command-line. Therefore, we will add step by step further commands and see what is happening.
+
+== Loading a XYZ file ==
+
+First, we will load the file and see whether the formula is correctly recognized.
+{{{
+molecuilder --load C3H8.xyz
+}}}
+
+MoleCuilder should tell you that it scanned 11 atoms and that the formula of the parsed molecule is indeed C3H8, as expected.
+
+== Constructing the bond graph ==
+
+After we have checked that the loading of the file was successful, we need to a bond graph. The XYZ file format only contains two pieces information per atom, namely the element and the position in 3D space. Hence, we do not have any bonding information. In order to be able fragment the molecule, however, we need such a bond graph.
+
+Therefore, we tell MoleCuilder to construct the graph.
+
+{{{
+molecuilder --load C3H8.xyz --subgraph-dissection
+}}}
+
+The [doxygen:GraphSubgraphDissectionAction] does a little bit more than just create the bond graph. It also splits the loaded molecular system up into individual molecules by scanning all connected subgraphs and placing all associated nodes, i.e. the atoms, into a single molecule. 
+
+In our case, however, there is no additional change to the created bond graph as our molecular system consists of just a single molecule, namely C,,3,,H,,8,,.
+
+== Fragmenting the molecule ==
+
+Finally, we are going to fragment the system.
+
+What do we mean by that? We will store a number of configuration files where each contains one of the created fragments.
+
+What kind of information do we need to pass? Especially, we need to tell MoleCuilder what file format we want these fragment configuration files to be stored in. Furthermore, we need to tell to which size fragments should be created: The maximum size of the fragments, i.e. the maximum number of nodes of the cut-out graph, also called the bond order. 
+
+However, some additional information is required, too. Let's have a look at the added command.
+
+{{{
+molecuilder --load C3H8.xyz -I --fragment-molecule BondFragment --order 2 --distance 2 --output-types xyz
+}}}
+
+You notice ''output-types'' specifying the file format and ''order'' the maximum number of nodes/atoms, here 2. Additionally, we have ''distance'' and the action name ''fragment-molecule''. The latter gives the prefix of each stored file, especially of the fragment configurations. The former is just a maximum bond distance for the algorithm itself (2 is a safe value).
+
+Once you execute the above line, you will notice an error message.
+
+> ERROR: No atoms or molecules have been selected.
+
+We did not select the atoms that the fragment routine should work on.
+
+There are various ways of selecting atoms, by element, by id, by the associated molecule, by presence in certain region of the domain ... or simply all of them.
+
+{{{
+molecuilder --load C3H8.xyz -I --select-all-atoms --fragment-molecule BondFragment --order 2 --distance 2 --output-types xyz
+}}}
+
+Now, we are done. Five configuration files have been written, the first being '''BondFragment0.xyz''', and some other files storing information related to the fragmentation process, i.e. '''!BondFragmentKeySets.dat'''.
+
+Have a look at one of the files. You'll notice that the stored atoms have exactly the same positions in space as had the original atoms in the file '''C3H8.xyz''' ... with a few exceptions: As the fragmentation inherently has to cut through bonds, these so-called ''dangling'' bonds are saturated with hydrogen atoms. You can switch this behavior on and off. Similarly, you can switch on and off whether hydrogens for above reason of saturation are treated specially. By default, both are switched on.
+
+{{{
+molecuilder --load C3H8.xyz -I --fragment-molecule BondFragment --order 2 --distance 2 --output-types xyz --DoSaturate 0 --ExcludeHydrogen 0
+}}}
+
+With these additional options they are both switched off.
+
+And that was all for this use case. You have successfully fragmented a propane molecule up to bond order 2 and created five saturated fragments, stored as XYZ files.