Merge pull request #351 from tovrstra/split-getting-started

Split the getting started docs

docs/getting_started/dumping.rst

@@ -0,0 +1,61 @@
+..
+    : IODATA is an input and output module for quantum chemistry.
+    :
+    : Copyright (C) 2011-2019 The IODATA Development Team
+    :
+    : This file is part of IODATA.
+    :
+    : IODATA is free software; you can redistribute it and/or
+    : modify it under the terms of the GNU General Public License
+    : as published by the Free Software Foundation; either version 3
+    : of the License, or (at your option) any later version.
+    :
+    : IODATA is distributed in the hope that it will be useful,
+    : but WITHOUT ANY WARRANTY; without even the implied warranty of
+    : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    : GNU General Public License for more details.
+    :
+    : You should have received a copy of the GNU General Public License
+    : along with this program; if not, see <http://www.gnu.org/licenses/>
+    :
+    : --
+
+Dumping Files
+=============
+
+IOData can also be used to write different file formats:
+
+.. literalinclude:: ../example_scripts/convert_fchk_molden.py
+    :language: python
+    :linenos:
+    :lines: 3-
+
+One could also convert (and manipulate) an entire trajectory. The following
+example converts a geometry optimization trajectory from a Gaussian FCHK file
+to an XYZ file:
+
+.. literalinclude:: ../example_scripts/convert_fchk_xyz_traj.py
+    :language: python
+    :linenos:
+    :lines: 3-
+
+If you wish to perform some manipulations before writing the trajectory, the
+simplest way is to load the entire trajectory in a list of IOData objects and
+dump it later:
+
+.. literalinclude:: ../example_scripts/convert_fchk_xyz_traj_mod1.py
+    :language: python
+    :linenos:
+    :lines: 3-
+
+For very large trajectories, you may want to avoid loading it as a whole in
+memory. For this, one should avoid making the ``list`` object in the above
+example. The following approach would be more memory efficient.
+
+.. literalinclude:: ../example_scripts/convert_fchk_xyz_traj_mod2.py
+    :language: python
+    :linenos:
+    :lines: 3-
+
+More details can be found in the API documentation of
+:py:func:`iodata.api.dump_one` and :py:func:`iodata.api.dump_many`.

docs/getting_started/index.rst

@@ -0,0 +1,42 @@
+..
+    : IODATA is an input and output module for quantum chemistry.
+    :
+    : Copyright (C) 2011-2019 The IODATA Development Team
+    :
+    : This file is part of IODATA.
+    :
+    : IODATA is free software; you can redistribute it and/or
+    : modify it under the terms of the GNU General Public License
+    : as published by the Free Software Foundation; either version 3
+    : of the License, or (at your option) any later version.
+    :
+    : IODATA is distributed in the hope that it will be useful,
+    : but WITHOUT ANY WARRANTY; without even the implied warranty of
+    : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    : GNU General Public License for more details.
+    :
+    : You should have received a copy of the GNU General Public License
+    : along with this program; if not, see <http://www.gnu.org/licenses/>
+    :
+    : --
+
+Getting Started
+===============
+
+IOData can be used to read and write various quantum chemistry file formats.
+
+The ``iodata-convert`` script can be used for simple conversions.
+More complex use cases can be implemented in Python,
+allowing you to access all loaded data as Python objects
+that can be modified or updated before writing to a new file.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   script
+   loading
+   dumping
+   inputs
+   representation
+   units

docs/getting_started/inputs.rst

@@ -0,0 +1,74 @@
+..
+    : IODATA is an input and output module for quantum chemistry.
+    :
+    : Copyright (C) 2011-2019 The IODATA Development Team
+    :
+    : This file is part of IODATA.
+    :
+    : IODATA is free software; you can redistribute it and/or
+    : modify it under the terms of the GNU General Public License
+    : as published by the Free Software Foundation; either version 3
+    : of the License, or (at your option) any later version.
+    :
+    : IODATA is distributed in the hope that it will be useful,
+    : but WITHOUT ANY WARRANTY; without even the implied warranty of
+    : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    : GNU General Public License for more details.
+    :
+    : You should have received a copy of the GNU General Public License
+    : along with this program; if not, see <http://www.gnu.org/licenses/>
+    :
+    : --
+
+Writing Input Files
+===================
+
+IOData can be used to write input files for quantum-chemistry software. By
+default minimal settings are used, which can be changed if needed. For example,
+the following will prepare a Gaussian input for a HF/STO-3G calculation from
+a PDB file:
+
+.. literalinclude:: ../example_scripts/write_gaussian_com.py
+    :language: python
+    :linenos:
+    :lines: 3-
+
+The level of theory and other settings can be modified by setting corresponding
+attributes in the IOData object:
+
+.. literalinclude:: ../example_scripts/write_gaussian_com_lot.py
+    :language: python
+    :linenos:
+    :lines: 3-
+
+The run types can be any of the following: ``energy``, ``energy_force``,
+``opt``, ``scan`` or ``freq``. These are translated into program-specific
+keywords when the file is written.
+
+It is possible to define a custom input file template to allow for specialized
+commands. This is done by passing a template string using the optional ``template`` keyword,
+placing each IOData attribute (or additional keyword, as shown below) in curly brackets:
+
+.. literalinclude:: ../example_scripts/write_gaussian_com_template.py
+    :language: python
+    :linenos:
+    :lines: 3-
+
+The input file template may also include keywords that are not part of the IOData
+object:
+
+.. literalinclude:: ../example_scripts/write_gaussian_com_custom.py
+    :language: python
+    :linenos:
+    :lines: 3-
+
+In some cases, it may be preferable to load the template from file, instead of
+defining it in the script:
+
+.. literalinclude:: ../example_scripts/write_gaussian_com_file.py
+    :language: python
+    :linenos:
+    :lines: 3-
+
+More details can be found in the API documentation of
+:py:func:`iodata.api.write_input`.