.. DOCUMENTATION BUILT FROM RELEASE: 2.1.0b3 (Jun 30, 2017) .. : HORTON: Helpful Open-source Research TOol for N-fermion systems. : Copyright (C) 2011-2017 The HORTON Development Team : : This file is part of HORTON. : : HORTON 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. : : HORTON 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 : : -- .. _user_getting_started: Getting Started ############### How to use HORTON? ================== HORTON is essentially a Python library that can be used for performing electronic structure calculations as well as interpreting these calculations (i.e. post-processing). There are two different ways to use HORTON. The most versatile approach is to write Python scripts that use HORTON as a Python library. This gives you full access to all the features available in HORTON; however, this requires some knowledge of the Python programming language. Alternatively, part of HORTON's functionality is accessible through built-in python scripts whose performance can be controlled through command line arguments. Obviously, this requires less programming knowledge. Running HORTON as a Python library ---------------------------------- There will be many examples in the following sections demonstrating how HORTON can be used when writing your own Python scripts. These scripts should all start with the following lines: .. code-block:: python #!/usr/bin/env python # Import the HORTON library from horton import * # Import some other stuff (optional) import numpy as np, h5py as h5, matplotlib.pyplot as pt # Actual Python script This header is then followed by some Python code that does the actual computation of interest. In such a script, you basically write the `main` program to do your calculations, exploiting the components that HORTON offers. The HORTON library is designed such that all its features are as modular as possible, allowing you to combine them in various ways. Before running your script, say ``run.py``, we recommend that you to make it executable (this needs to be done only once for every script): .. code-block:: bash chmod +x run.py Now, when your script has completed, you can run it as follows: .. code-block:: bash ./run.py Do not use ``horton.py`` as your script name; this will cause trouble when loading the ``horton`` library (due to a namespace collision). .. _using_horton_as_a_script: Running HORTON as ``horton-*.py`` scripts ----------------------------------------- The built-in HORTON scripts all have the ``horton-*.py`` filename pattern. Through command line arguments, one can control the actual calculations performed by these scripts. Basic information on how to use each built-in script can be obtained by using the ``--help`` flag. For example, .. code-block:: bash horton-convert.py --help Writing a basic HORTON Python script ==================================== HORTON scripts just run with a regular Python interpreter (like `ASE `_ and unlike `PSI4 `_, which uses a modified Python interpreter). This means that you need to have a basic knowledge of Python. In addition, it will be helpful to be familiar with popular Python packages for scientific computing. The links below provide some resources to broaden your Python knowledge: * `Python `_, `Python documentation `_, `Getting started with Python `_ * `NumPy `_ (array manipulation), `Getting started with NumPy `_ * `SciPy `_ (scientific computing library), `The SciPy tutorial `_ * `Matplotlib `_ (plotting) * `H5Py `_ (load/dump arrays from/to binary files) * `Programming Q&A `_ * `Python code snippets `_ The following sections go through some basic features that will appear in many other examples in the documentation. Atomic Units ------------ Internally, HORTON works exclusively in atomic units. If you want to convert a value from a different unit to atomic units, multiply it with the appropriate unit constant, e.g. the following snippet sets ``length`` to 5 Angstrom and prints it in atomic units: .. code-block:: python length = 5*angstrom # recording 5 angstrom in atomic units print length Conversely, if you want to print a value in a different unit than atomic units, divide it by the appropriate constant. For example, the following prints an energy of 0.001 Hartree in kJ/mol: .. code-block:: python energy = 0.001 # recording energy in Hartree print energy/kjmol # printing energy in kJ/mol An overview of all units can be found in :py:mod:`horton.units`. There are two special cases: 1. Angles are in radians, but you can use the ``deg`` unit to work with degrees, for example, ``90*deg`` and ``np.pi/2`` are equivalent. 2. Temperatures are in Kelvin. Array Indexing -------------- All arrays and list-like objects in Python use zero-based indexing. This means that the first element of a vector is accessed as follows: .. code-block:: python vector = np.array([1, 2, 3]) print vector[0] This convention also applies to all array-like (and list-like) objects in HORTON, e.g. the first orbital in a Slater determinant has index 0. Loading/Dumping Data from/to a File ----------------------------------- All input and output of data in HORTON is managed through the :py:class:`~horton.io.iodata.IOData` class. To load data, call the :py:meth:`~horton.io.iodata.IOData.from_file` method of the :py:class:`~horton.io.iodata.IOData` class, e.g.: .. code-block:: python mol = IOData.from_file('water.xyz') The information read from the file is accessible through attributes of the ``mol`` object. For example, the following prints the coordinates of the nuclei in Angstrom: .. code-block:: python print mol.coordinates/angstrom To write data into a file, first create an instance of the :py:class:`~horton.io.iodata.IOData` class, then set the appropriate attributes, and write the content into a file by calling the :py:meth:`~horton.io.iodata.IOData.to_file` method of the :py:class:`~horton.io.iodata.IOData` class. For example, the following snippet creates a ``.xyz`` file for a Neon atom: .. code-block:: python mol = IOData(title='Neon') mol.coordinates = np.array([[0.0, 0.0, 0.0]]) mol.numbers = np.array([10]) mol.to_file('neon.xyz') For a complete list of supported input/output file formats please refer to :ref:`ref_file_formats`; this includes a list of :py:class:`~horton.io.iodata.IOData` attributes supported by each file format. A definition of all possible :py:class:`~horton.io.iodata.IOData` attributes can be found in :py:class:`horton.io.iodata.IOData`. Periodic Table -------------- HORTON has a periodic table of elements alongside several atomic properties that may come in handy in computations. For more details please refer to :py:mod:`horton.periodic`. The following example prints some information for Carbon atom: .. code-block:: python print periodic[6].mass/amu # The mass in atomic mass units print periodic['C'].cov_radius/angstrom # The covalent radius in angstrom print periodic['c '].c6 # The C6 coefficient in atomic units As demonstrated above, you can be relatively sloppy with the index when referring to elements of the periodic table. A Complete Example ------------------ This first example is kept very simple in order to illustrate the basics of a HORTON Python script. (It neither performs an electronic calculation nor does post-processing.) This example loads a ``.xyz`` file and computes the molecular mass. Finally, it writes the data read from the ``.xyz`` file and the calculated mass into a ``.h5`` file, using HORTON's internal data format. .. literalinclude:: ../data/examples/getting_started/first.py :caption: data/examples/getting_started/first.py :lines: 1-23 Note that the ``context.get_fn('test/water.xyz')`` expression is used to look up a data file from the HORTON data directory. If you want to use your own file, load the molecule as follows: .. code-block:: python mol = IOData.from_file('your_file.xyz')