Merge pull request #162 from ReactionMechanismGenerator/docs2

 Docs: Added `Writing an ARC input file using the API` to advanced

docs/source/advanced.rst

@@ -3,6 +3,8 @@
 Advanced Features
 =================
 
+.. _flexXYZ:
+
 Flexible coordinates (xyz) input
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -47,7 +49,7 @@ ARC will perform 1D rotor scans to all possible unique hindered rotors in the sp
 
 The rotor scan resolution is 8 degrees by default (scanning 360 degrees overall).
 Rotors are invalidated (not used for thermo / rate calculations) if at least one barrier
-is above a maximum threshold (40 kJ/mol by defaut), if the scan is inconsistent by more than 30%
+is above a maximum threshold (40 kJ/mol by default), if the scan is inconsistent by more than 30%
 between two consecutive points, or if the scan is inconsistent by more than 5 kJ/mol
 between the initial anf final points.
 All of the above settings can be modified in the settings.py file.
@@ -91,7 +93,7 @@ Troubleshooting
 
 ARC is has fairly good auto-troubleshooting methods.
 
-However, at times a user might know in advance that a particular additional keywork
+However, at times a user might know in advance that a particular additional keyword
 is required for the calculation. In such cases, simply pass the relevant keyword
 in the ``initial_trsh`` (`trsh` stands for `troubleshooting`) dictionary passed to ARC::
 
@@ -243,7 +245,7 @@ pass their labels to ARC in the ``dont_gen_confs`` list, e.g.::
         H   1.5267840  -2.0696580   0.0000000
 
 In the above example, ARC will only generate conformers for propane, but not for propanol.
-For propane, it will compare the selected conformers agains the user-given xyz guess using the
+For propane, it will compare the selected conformers against the user-given xyz guess using the
 conformer level DFT method, and will take the most stable structure for the rest of the calculations,
 regardless of its source (ARC's conformers or the user guess). For propanol, on the other hand,
 ARC will not attempt to generate conformers, and will simply use the user guess.
@@ -252,4 +254,148 @@ Note: If a species label is added to the ``dont_gen_confs`` list, but the specie
 coordinates, ARC **will** generate conformers for it.
 
 
+Writing an ARC input file using the API
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Writing in YAML isn't very intuitive for many, especially without a good editor.
+You could use ARC's API to define your objects, and then dump it all in a YAML file
+which could be read as an input in ARC::
+
+    from arc.species.species import ARCSpecies
+    from arc.common import save_yaml_file
+
+    input_dict = dict()
+
+    input_dict['project'] = 'Demo_project_input_file_from_API'
+
+    input_dict['job_types'] = {'conformers': True,
+                               'opt': True,
+                               'fine_grid': True,
+                               'freq': True,
+                               'sp': True,
+                               '1d_rotors': True,
+                               'orbitals': False,
+                               'lennard_jones': False,
+                              }
+
+    spc1 = ARCSpecies(label='NO', smiles='[N]=O')
+
+    adj1 = """multiplicity 2
+    1 C u0 p0 c0 {2,D} {4,S} {5,S}
+    2 C u0 p0 c0 {1,D} {3,S} {6,S}
+    3 O u1 p2 c0 {2,S}
+    4 H u0 p0 c0 {1,S}
+    5 H u0 p0 c0 {1,S}
+    6 H u0 p0 c0 {2,S}"""
+
+    xyz2 = [
+        """O       1.35170118   -1.00275231   -0.48283333
+           C      -0.67437022    0.01989281    0.16029161
+           C       0.62797113   -0.03193934   -0.15151370
+           H      -1.14812497    0.95492850    0.42742905
+           H      -1.27300665   -0.88397696    0.14797321
+           H       1.11582953    0.94384729   -0.10134685""",
+        """O       1.49847909   -0.87864716    0.21971764
+           C      -0.69134542   -0.01812252    0.05076812
+           C       0.64534929    0.00412787   -0.04279617
+           H      -1.19713983   -0.90988817    0.40350584
+           H      -1.28488154    0.84437992   -0.22108130
+           H       1.02953840    0.95815005   -0.41011413"""]
+
+    spc2 = ARCSpecies(label='vinoxy', xyz=xyz2, adjlist=adj1)
+
+    spc_list = [spc1, spc2]
+
+    input_dict['species'] = [spc.as_dict() for spc in spc_list]
+
+    save_yaml_file(path='some/path/to/desired/folder/input.yml', content=input_dict)
+
+
+The above code generated the following input file::
+
+    project: Demo_project_input_file_from_API
+
+    job_types:
+      1d_rotors: true
+      conformers: true
+      fine_grid: true
+      freq: true
+      lennard_jones: false
+      opt: true
+      orbitals: false
+      sp: true
+
+    species:
+    - E0: null
+      arkane_file: null
+      bond_corrections:
+        N=O: 1
+      charge: 0
+      external_symmetry: null
+      force_field: MMFF94
+      generate_thermo: true
+      is_ts: false
+      label: 'NO'
+      long_thermo_description: 'Bond corrections: {''N=O'': 1}
+
+        '
+      mol: |
+        multiplicity 2
+        1 N u1 p1 c0 {2,D}
+        2 O u0 p2 c0 {1,D}
+      multiplicity: 2
+      neg_freqs_trshed: []
+      number_of_rotors: 0
+      optical_isomers: null
+      rotors_dict: {}
+      t1: null
+    - E0: null
+      arkane_file: null
+      bond_corrections:
+        C-H: 3
+        C-O: 1
+        C=C: 1
+      charge: 0
+      conformer_energies:
+      - null
+      - null
+      conformers:
+      - |-
+        O       1.35170118   -1.00275231   -0.48283333
+        C      -0.67437022    0.01989281    0.16029161
+        C       0.62797113   -0.03193934   -0.15151370
+        H      -1.14812497    0.95492850    0.42742905
+        H      -1.27300665   -0.88397696    0.14797321
+        H       1.11582953    0.94384729   -0.10134685
+      - |-
+        O       1.49847909   -0.87864716    0.21971764
+        C      -0.69134542   -0.01812252    0.05076812
+        C       0.64534929    0.00412787   -0.04279617
+        H      -1.19713983   -0.90988817    0.40350584
+        H      -1.28488154    0.84437992   -0.22108130
+        H       1.02953840    0.95815005   -0.41011413
+      external_symmetry: null
+      force_field: MMFF94
+      generate_thermo: true
+      is_ts: false
+      label: vinoxy
+      long_thermo_description: 'Bond corrections: {''C-O'': 1, ''C=C'': 1, ''C-H'': 3}
+
+        '
+      mol: |
+        multiplicity 2
+        1 O u1 p2 c0 {3,S}
+        2 C u0 p0 c0 {3,D} {4,S} {5,S}
+        3 C u0 p0 c0 {1,S} {2,D} {6,S}
+        4 H u0 p0 c0 {2,S}
+        5 H u0 p0 c0 {2,S}
+        6 H u0 p0 c0 {3,S}
+      multiplicity: 2
+      neg_freqs_trshed: []
+      number_of_rotors: 0
+      optical_isomers: null
+      rotors_dict: {}
+      t1: null
+
+
 .. include:: links.txt

docs/source/conf.py

@@ -14,14 +14,14 @@
 
 import os
 import sys
+import datetime
+from arc.common import VERSION
+
 sys.path.insert(0, os.path.abspath('.'))
 
 
 # -- Project information -----------------------------------------------------
 
-import datetime
-from arc.common import VERSION
-
 year = datetime.datetime.now().year
 project = u'ARC'
 copyright = u'2018-{0}, Alon Grinberg Dana'.format(year)
@@ -97,7 +97,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # stylesheet to use
 # html_style = 'custom.css'
@@ -121,7 +121,7 @@
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-#latex_logo = '../logo/ARC-logo-small.jpg'
+# latex_logo = '../logo/ARC-logo-small.jpg'
 
 
 # -- Options for HTMLHelp output ---------------------------------------------

docs/source/contribute.rst

@@ -9,7 +9,7 @@ as a benefit to the community in the hopes that others may find it useful as wel
 We welcome contributions from the community. Please see the `contributor guidelines`__
 on ARC's GitHub page, as well as the Code of Conduct.
 
-__ contributorGuidlines_
+__ contributorGuidelines_
 
 It is recommended to open an issue on GitHub, notifying the developers on a bug
 you are trying to fix or a feature you plan to implement (see our `roadmap`_) to avoid duplicate work.

docs/source/examples.rst

@@ -83,7 +83,7 @@ To specify a composite method, simply define something like::
 
 Note that for composite methods the default ``freq_level`` and ``scan_level`` may have different
 default values than for non-composite methods (defined in settings.py). Yes, an independent
-frequencies calculation job is executed afte a composite job just so that the Hamiltonian will
+frequencies calculation job is executed after a composite job just so that the Hamiltonian will
 be outputted.
 
 The same example as above ran via the API (e.g., in `Jupyter notebooks`__) would look like the following::
@@ -161,6 +161,11 @@ Here's an example for optimizing a transition state (TS) after generating severa
           - TS3/3.gjf
           - TS3/4.gjf
 
+In the above example we're using `.gjf` files (Gaussian job files) that contain the coordinate guesses.
+You could define ``xyz`` using various forms, see `Flexible coordinates (xyz) input`__.
+
+__ flexXYZ_
+
 Note that the main difference is the ``is_ts`` flag which is set to `True` (it is `False` by default).
 
 .. include:: links.txt

docs/source/links.txt

@@ -12,6 +12,6 @@
 .. _semantic: https://semver.org/
 .. _autotst: https://github.com/ReactionMechanismGenerator/AutoTST
 .. _greengp: http://greengroup.mit.edu/
-.. _contributorGuidlines: https://github.com/ReactionMechanismGenerator/ARC/wiki/ARC-Contributor-Guidelines
+.. _contributorGuidelines: https://github.com/ReactionMechanismGenerator/ARC/wiki/ARC-Contributor-Guidelines
 .. _roadmap: https://github.com/ReactionMechanismGenerator/ARC/wiki/Roadmap
 .. _gaussian: http://gaussian.com/

docs/source/output.rst

@@ -72,9 +72,9 @@ After running a Project, the local Project folder will contain the following dir
     - *species_dictionary.txt*: The adjacency list for the species.
     - **geometry**
 
-        - *<species_name>.gjf*: A Gaussian job file for visuallizing the species' coordinates in GaussView.
-        - *<species_name>.xyz*: An XYZ format file for visuallizing the species' coordinates, e.g., in Avogadro.
-        - *freq.out*: The frequency job output file for visuallizing vibrational modes.
+        - *<species_name>.gjf*: A Gaussian job file for visualizing the species' coordinates in GaussView.
+        - *<species_name>.xyz*: An XYZ format file for visualizing the species' coordinates, e.g., in Avogadro.
+        - *freq.out*: The frequency job output file for visualizing vibrational modes.
         - *geometry.png*: An image of the species in an arbitrary orientation for quick viewing.
         - **conformers**
 

docs/source/release.rst

@@ -101,7 +101,7 @@ ARC 1.1.0
     - Improved error message if rxn energetics are problematic
     - Added min_list() to Scheduler
     - Improve converter xyz functions
-    - Improved xyz handeling in Species (`xyz` can now be a list)
+    - Improved xyz handling in Species (`xyz` can now be a list)
 
   - #133:
 

docs/source/running.rst

@@ -107,7 +107,7 @@ __ jupyter_
 
 Example iPython notebooks are available in the ``ipython/Demo`` folder.
 Various :ref:`standalone tools <tools>` in an iPython format are also available,
-demonstraiting different utilizations of the API.
+demonstrating different utilizations of the API.
 Users are of course directed to read :ref:`ARC's API <api>`.
 
 .. include:: links.txt