Merge pull request #36 from dgasmith/docs

v0.6 release tweaks

.gitignore

@@ -56,6 +56,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/source/api/
 
 # PyBuilder
 target/

README.md

@@ -1,5 +1,5 @@
 QCEngine
-==============================
+========
 [![Travis Build Status](https://travis-ci.org/MolSSI/QCEngine.png)](https://travis-ci.org/MolSSI/QCEngine)
 [![codecov](https://codecov.io/gh/MolSSI/QCEngine/branch/master/graph/badge.svg)](https://codecov.io/gh/MolSSI/QCEngine/branch/master)
 [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/MolSSI/QCEngine.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/MolSSI/QCEngine/context:python)
@@ -19,6 +19,48 @@ Available Procedures:
  - [Geometric](https://github.com/leeping/geomeTRIC)
 
 
+# Example
+
+A simple example of QCEngine's capabilities is as follows:
+
+```python
+>>> import qcengine as qcng
+>>> import qcelemental as qcel
+
+>>> mol = qcel.models.Molecule.from_data("""
+O  0.0  0.000  -0.129
+H  0.0 -1.494  1.027
+H  0.0  1.494  1.027
+""")
+
+>>> inp = qcel.models.ResultInput(
+    molecule=mol,
+    driver="energy",
+    model={"method": "SCF", "basis": "sto-3g"},
+    keywords={"scf_type": "df"}
+    )
+```
+
+These input specifications can be executed with the ``compute`` function along with a program specifier:
+
+```python
+>>> ret = qcng.compute(inp, "psi4", return_dict=False)
+```
+
+The results contain a complete record of the computation:
+
+
+```python
+>>> ret.return_result
+-74.45994963230625
+
+>>> ret.properties.scf_dipole_moment
+[0.0, 0.0, 0.6635967188869244]
+
+>>> ret.provenance.cpu
+Intel(R) Core(TM) i7-7820HQ CPU @ 2.90GHz
+```
+
 See the [documentation](https://qcengine.readthedocs.io/en/latest/) for more information.
 
 # License

docs/source/api.rst

@@ -0,0 +1,13 @@
+============
+QCEngine API
+============
+
+.. automodapi:: qcengine
+
+.. automodapi:: qcengine.compute
+
+.. automodapi:: qcengine.config
+
+.. automodapi:: qcengine.util
+
+.. automodapi:: qcengine.programs

docs/source/changelog.rst

@@ -13,6 +13,31 @@ Changelog
 .. Bug Fixes
 .. +++++++++
 
+v0.6.0 / 2019-02-28
+-------------------
+
+Breaking Changes
+++++++++++++++++
+
+- (:pr:`36`) **breaking change** Model objects are returned by default rather than a dictionary.
+
+New Features
+++++++++++++
+
+- (:pr:`18`) Add the ``dftd3`` program to available computers.
+- (:pr:`29`) Adds preliminary support for the ``Molpro`` compute engine.
+- (:pr:`31`) Moves all computation to ``ProgramExecutor`` to allow for a more flexible input generation, execution, output parsing interface.
+- (:pr:`32`) Adds a general ``execute`` process which safely runs subprocess jobs.
+
+Enhancements
+++++++++++++
+
+- (:pr:`33`) Moves the ``dftd3`` executor to the new ``ProgramExecutor`` interface.
+- (:pr:`34`) Updates models to the more strict QCElemental v0.3.0 model classes.
+- (:pr:`35`) Updates CI to avoid pulling CUDA libraries for ``torchani``.
+- (:pr:`36`) First pass at documentation.
+
+
 v0.5.2 / 2019-02-13
 -------------------
 

docs/source/community.rst

@@ -12,7 +12,8 @@ Discussion
 - QCArchive Slack is a great place to get feedback and advice from the community. Click `here <https://join.slack.com/t/qcdb/shared_invite/enQtNDIzNTQ2OTExODk0LWM3OTgxN2ExYTlkMTlkZjA0OTExZDlmNGRlY2M4NWJlNDlkZGQyYWUxOTJmMzc3M2VlYzZjMjgxMDRkYzFmOTE>`_ to get started.
 - The QCArchive GitHub repositories contain future roadmaps, current code updates, and a list of issues that are being worked and provide an excellent overview of the development status of the project. See the following links:
 
-   - `QCSchema <https://github.com/MolSSI/QC_JSON_Schema>`_
+   - `QCSchema <https://github.com/MolSSI/QCSchema>`_
+   - `QCElemental <https://github.com/MolSSI/QCElemental>`_
    - `QCEngine <https://github.com/MolSSI/QCEngine>`_
    - `QCFractal <https://github.com/MolSSI/QCFractal>`_
 
@@ -21,11 +22,11 @@ Work with us!
 -------------
 
 The QCArchive project is actively looking for early collaborations to use our
-tools, help us shake out the bugs, and be evangelist within the computational
+tools, help us shake out the bugs, and be evangelists within the computational
 molecular science community for this code ecosystem. In return you will receive
 the following benefits:
 
-- Work directly with MolSSI Software Scientist who will discuss your problem and provide ideas.
+- Work directly with a MolSSI Software Scientist who will discuss your problem and provide ideas.
 - Develop the requirements and potential solutions for your use case within the QCArchive ecosystem.
 - Setup monthly meetings to ensure your project stays on track.
 - Highlight your project within the QCArchive ecosystem.

docs/source/conf.py

@@ -55,6 +55,8 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
+    'sphinx_automodapi.automodapi',
+    'sphinx_automodapi.automodsumm',
 ]
 
 napoleon_google_docstring = False
@@ -185,7 +187,12 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/3.7', None),
+                       'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+                       'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+                       'matplotlib': ('https://matplotlib.org/', None),
+                       'qcelemental': ('https://qcelemental.readthedocs.io/en/latest/', None)
+                      }
 
 # -- Options for todo extension ----------------------------------------------
 

docs/source/environment.rst

@@ -0,0 +1,54 @@
+Environment Detection
+======================
+
+QCEngine can inspect the current compute environment to determine the resources available to it.
+
+Node Description
+----------------
+
+QCEngine can detect node descriptions to obtain general information about the current node.
+
+.. code:: python
+
+    >>> qcng.config.get_node_descriptor()
+    <NodeDescriptor hostname_pattern='*' name='default' scratch_directory=None
+                    memory=5.568 memory_safety_factor=10 ncores=4 jobs_per_node=2>
+
+Config
+------
+
+The configuration file operated based on the current node descriptor and can be overridden:
+
+.. code:: python
+
+    >>> qcng.get_config()
+    <JobConfig ncores=2 memory=2.506 scratch_directory=None>
+
+    >>> qcng.get_config(local_options={"scratch_directory": "/tmp"})
+    <JobConfig ncores=2 memory=2.506 scratch_directory='/tmp'>
+
+    >>> os.environ["SCRATCH"] = "/my_scratch"
+    >>> qcng.get_config(local_options={"scratch_directory": "$SCRATCH"})
+    <JobConfig ncores=2 memory=2.506 scratch_directory='/my_scratch'>
+
+Global Environment
+-------------------
+
+The global environment can also be inspected directly.
+
+.. code:: python
+
+    >>> qcng.config.get_global()
+    {
+        'hostname': 'qcarchive.molssi.org',
+        'memory': 5.568,
+        'username': 'user',
+        'ncores': 4,
+        'cpuinfo': {
+            'python_version': '3.6.7.final.0 (64 bit)',
+            'brand': 'Intel(R) Core(TM) i7-7820HQ CPU @ 2.90GHz',
+            'hz_advertised': '2.9000 GHz',
+            ...
+        },
+        'cpu_brand': 'Intel(R) Core(TM) i7-7820HQ CPU @ 2.90GHz'
+    }