Release v.3.2-beta2

- Add several tests to check accuracy of library - Add "make test" functionality with cmake - Add automated travis-ci testing (https://travis-ci.org/wesbarnett/libgmxcpp) - Add readthedocs documentation and update README (http://libgmxcpp.readthedocs.org), integrated with doxygen - Some bug fixes with overloading coordinates operators - Bug fix with reading in max number of frames with Trajectory - Uncrustify all code - Add bond vector calculation - Add bond angle calculation - Add dihedral angle calculation - Add Clusters doxygen documentation - Add center of mass calculations, tests, and docs - Add geometric center calculation, and docs. Is tested with center of mass. - Add routine to center group of atoms around a point, removing pbc; and docs. Is tested with center of mass
wesbarnett · Apr 9, 2015 · 84bba62 · 84bba62
1 parent eba8b64
commit 84bba62
Show file tree

Hide file tree

Showing 29 changed files with 384 additions and 121 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1 +1,3 @@
 *~
+build
+doxyxml
diff --git a/.travis.yml b/.travis.yml
@@ -1,8 +1,15 @@
 language: cpp
 compiler: gcc
+install: 
+    - sudo apt-get update -qq
+    - sudo apt-get install doxygen 
+    - sudo pip install --upgrade pip
+    - sudo pip install sphinx 
+    - sudo pip install breathe
 script: 
     - mkdir build 
     - cd build
     - cmake .. 
     - make
     - make test
+    - make docs
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,11 +1,13 @@
 cmake_minimum_required(VERSION 2.8)
 project(gmxcpp)
+set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
 set (gmxcpp_VERSION_MAJOR 1)
 set (gmxcpp_VERSION_MINOR 0)
 set(CMAKE_CXX_FLAGS "-std=c++0x -Wall -fopenmp")
 add_subdirectory(include)
 include_directories(include)
 add_subdirectory(src)
+add_subdirectory(docs)
 
 project(tests)
 add_subdirectory(tests)

diff --git a/README.md b/README.md
@@ -1,7 +1,6 @@
+[![Build Status](https://travis-ci.org/wesbarnett/libgmxcpp.svg?branch=v3.2-beta2)](https://travis-ci.org/wesbarnett/libgmxcpp)
+[![Documentation Status](https://readthedocs.org/projects/libgmxcpp/badge/?version=v3.2-beta2)](https://readthedocs.org/projects/libgmxcpp/?badge=v3.2-beta2)
 
-!["Build status"](https://travis-ci.org/wesbarnett/libgmxcpp.svg?branch=master)
-[![Documentation
-Status](https://readthedocs.org/projects/libgmxcpp/badge/?version=latest)](https://readthedocs.org/projects/libgmxcpp/?badge=latest)
 
 This is a C++ toolkit used for reading in Gromacs files (.xtc and .ndx) for
 use in analyzing simulation results. This interfaces with libxdrfile and

diff --git a/cmake/FindSphinx.cmake b/cmake/FindSphinx.cmake
@@ -0,0 +1,14 @@
+find_program(SPHINX_EXECUTABLE NAMES sphinx-build
+    HINTS
+    $ENV{SPHINX_DIR}
+    PATH_SUFFIXES bin
+    DOC "Sphinx documentation generator"
+)
+
+include(FindPackageHandleStandardArgs)
+
+find_package_handle_standard_args(Sphinx DEFAULT_MSG
+    SPHINX_EXECUTABLE
+)
+
+mark_as_advanced(SPHINX_EXECUTABLE)
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
@@ -0,0 +1,26 @@
+find_package(Sphinx)
+
+if(NOT DEFINED SPHINX_THEME)
+    set(SPHINX_THEME default)
+endif()
+
+if(NOT DEFINED SPHINX_THEME_DIR)
+    set(SPHINX_THEME_DIR)
+endif()
+
+configure_file(Doxyfile ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile COPYONLY)
+
+# HTML output directory
+set(SPHINX_MAN_DIR "${CMAKE_CURRENT_BINARY_DIR}/html")
+
+add_custom_target(docs COMMAND
+    ${SPHINX_EXECUTABLE}
+        -b html
+        -c ${CMAKE_CURRENT_SOURCE_DIR}
+        "${CMAKE_CURRENT_SOURCE_DIR}"
+        "${SPHINX_MAN_DIR}"
+    COMMENT "Building HTML documentation with Sphinx.")
+
+add_custom_command(TARGET docs POST_BUILD
+        COMMENT "HTML documentation is in docs/html."
+        )
diff --git a/Doxyfile → docs/Doxyfile b/Doxyfile → docs/Doxyfile
@@ -758,7 +758,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  =
+INPUT                  = ..
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -793,7 +793,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = src/xdrfile.c,include/gmxcpp/xdrfile.h
+EXCLUDE                = 
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -809,7 +809,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = xdrfile*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -1006,7 +1006,7 @@ COLS_IN_ALPHA_INDEX    = 5
 # while generating the index headers.
 # This tag requires that the tag ALPHABETICAL_INDEX is set to YES.
 
-IGNORE_PREFIX          = xdr,XDR
+IGNORE_PREFIX          = 
 
 #---------------------------------------------------------------------------
 # Configuration options related to the HTML output
@@ -1835,7 +1835,7 @@ GENERATE_XML           = YES
 # The default directory is: xml.
 # This tag requires that the tag GENERATE_XML is set to YES.
 
-XML_OUTPUT             = docs/doxyxml
+XML_OUTPUT             = doxyxml
 
 # If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program
 # listings (including syntax highlighting and cross-referencing information) to

diff --git a/docs/about.rst b/docs/about.rst
diff --git a/docs/analysis.rst b/docs/analysis.rst
@@ -5,8 +5,8 @@ In addition to being able to read in trajectories and index files, some basic
 analysis functions are included in the API. These are not intended to be
 exhaustive of all possible analytical tools. Instead, this is a simple framework
 the analyst can use in writing his own programs. All of these are currently
-found in "gmxcpp/Utils.h", except for the clustering routines, which are found
-in "gmxcpp/Clusters.h".
+found in ``gmxcpp/Utils.h``, except for the clustering routines, which are found
+in ``gmxcpp/Clusters.h``.
 
 Bond vector
 -----------
@@ -16,6 +16,14 @@ Bond angle
 ----------
 .. doxygenfunction:: bond_angle
 
+Center a group of atoms around a point
+-------------------------------------
+.. doxygenfunction:: do_center_group
+
+Center of mass
+--------------
+.. doxygengroup:: center_of_mass
+
 Clustering
 ----------
 .. doxygenclass:: Clusters
@@ -41,13 +49,17 @@ Dot product
 -----------
 .. doxygenfunction:: dot
 
+Geometric center
+----------------
+.. doxygenfunction:: center_of_geometry
+
 Periodic boundary condition
 ---------------------------
 .. doxygenfunction:: pbc
 
 Random point on sphere
 ----------------------
-.. doxygenfunction:: gen_sphere_point
+.. doxygengroup:: gen_sphere_point
 
 Surface area
 ------------

diff --git a/docs/api.rst b/docs/api.rst
@@ -2,10 +2,13 @@
 API
 ===
 
+Most of the important functions / classes have already been covered in the
+previous two sections and so may not be repeated here.
+
 .. toctree::
    :maxdepth: 2
 
    classes/coordinates
    classes/Trajectory
    classes/triclinicbox
-   files/Utils.h
+
diff --git a/docs/cite.rst b/docs/cite.rst
diff --git a/docs/classes/Frame.rst b/docs/classes/Frame.rst
diff --git a/docs/classes/Index.rst b/docs/classes/Index.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -16,6 +16,7 @@
 import sys
 import os
 import shlex
+import subprocess
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -138,7 +139,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']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -284,16 +285,19 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
 
-#sys.path.append( "/var/build/user_builds/libgmxcpp/checkouts/latest/ext/breathe" )
+# Needed for breathe, which links doxygen xml file to sphinx
 extensions = ['breathe' ]
 breathe_projects = { "libgmxcpp":"./doxyxml" }
 breathe_default_project = "libgmxcpp"
 
-import subprocess, os
+# Runs doxygen on code
+subprocess.call('doxygen', shell=True)
 
-read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
+# Are we on readthedocs?
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
-if read_the_docs_build:
-
-        subprocess.call('cd ..; doxygen; cd docs', shell=True)
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
diff --git a/docs/example.rst b/docs/example.rst
@@ -1,8 +1,8 @@
 
 Example Programs
-===============
+================
 
-There is an example program in the "example" directory. Use "make" to compile it
+There is an example program in the ``example`` directory. Use ``make`` to compile it
 and test it out on an .xtc and .ndx file from a recent simulation.
 
 Additionally `there is an example program which calculates the radial

diff --git a/docs/files/Index.cpp.rst b/docs/files/Index.cpp.rst
diff --git a/docs/files/Trajectory.cpp.rst b/docs/files/Trajectory.cpp.rst
diff --git a/docs/files/Trajectory.h.rst b/docs/files/Trajectory.h.rst
diff --git a/docs/files/Utils.h.rst b/docs/files/Utils.h.rst
diff --git a/img/screenshot.png → docs/images/screenshot.png b/img/screenshot.png → docs/images/screenshot.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,16 +6,45 @@
 libgmxcpp
 =========
 
-a C++ toolkit used for reading in Gromacs files (.xtc and .ndx) for
-use in analyzing simulation results
+http://github.com/wesbarnett/libgmxcpp
+
+This is a C++ toolkit used for reading in Gromacs files (.xtc and .ndx) for
+use in analyzing simulation results. This interfaces with libxdrfile and
+implements an object-oriented style. The main usage of the library is to be able
+to create a Trajectory object which reads in an XTC file along with an optional
+GROMACS index file such that the user only has to worry with implementing the
+actual analysis. Several functions which are repeatedly used in Molecular
+Dynamics analysis (periodic boundary condition calculations, distances, etc.)
+are also included. 
+
+Development
+-----------
+
+The development branch is ``master``. Releases are merged into the ``release``
+branch.
+
+Advantages
+----------
+
+* Only one object construction needs to be called to read in both .xtc and .ndx
+  files.
+* Index groups can be used by name within the program to get a desired atom's
+  coordinates.
+* Custom classes for atomic coordinates and simulation box allow overloading of
+  operators to simplify coding.
+* Common functions such as distance, magnitude, and cross product are built-in.
+* Analysis loops can easily be parallelized with class getter functions, since
+  all data frames are initially read in and can be accessed simultaneously.
+* No other libraries needed (the relevant parts of libxdrfile are included with
+  this project).
+
+.. image:: images/screenshot.png
 
 .. toctree::
 
-   about
    installation
-   example
    usage
    analysis
+   example
    api
    license
-   cite