gmxapi-79 Safe management of session working directories

.travis.yml

@@ -29,39 +29,54 @@ matrix:
       - GMX_THREAD_MPI=ON
       - gmxapi_DIR=$HOME/gromacs
       - GROMACS_DIR=$HOME/gromacs
+      - GROMACS_TAG=devel
+# Todo: GROMACS_TAG=devel needs to be fixed before merging to a release branch.
+# What makes me uncomfortable is that this is not automatic, but maybe that is for the best. We should check the
+# version dependencies before issuing a release or merging to master. This is described in RELEASE.txt
 
-# It is clearly a bad idea to have the development branch of a project requiring the development branch
-# of another project in the primary build recipe. We either need to build and test development and master
-# branches distinctly in a build matrix, only build off of tagged releases or the master branch of the
-# dependency, or otherwise find a better solution that allows the master branch to be entirely included in
-# the develop branch.
 before_install:
   - uname -a
   - apt list --installed
   - test -n $CC  && unset CC
   - test -n $CXX && unset CXX
-  - wget https://github.com/kassonlab/gromacs-gmxapi/archive/master.zip
-  - unzip master.zip
+  - wget https://github.com/kassonlab/gromacs-gmxapi/archive/$GROMACS_TAG.zip
+  - unzip $GROMACS_TAG.zip
 
 install:
-  - pushd gromacs-gmxapi-master
+  - pushd gromacs-gmxapi-$GROMACS_TAG
   - mkdir build
   - pushd build
   - cmake -DCMAKE_INSTALL_PREFIX=$HOME/gromacs -DGMX_FFT_LIBRARY=fftpack -DGMX_GPU=OFF -DGMX_OPENMP=OFF -DGMX_SIMD=None -DGMX_USE_RDTSCP=OFF -DGMX_MPI=$GMX_MPI -DGMX_THREAD_MPI=$GMX_THREAD_MPI ..
   - make -j4 install
   - popd
   - popd
-  # pip 10.0.0 appears to be broken
-  - python -m pip install --upgrade pip==9 --user
+  - python -m pip install --upgrade pip --user
   - python -m pip install --upgrade setuptools --user
   - python -m pip install virtualenv --user
   - python -m pip install pytest --user
-  - python -m pip install cmake --user
   - python -m pip install numpy --user
   - python -m pip install mpi4py --user
   - python -m pip install networkx --user
 
 script:
-  - GROMACS_DIR=$HOME/gromacs python -m pip install . --verbose --user
-  - mpiexec -n 2 python -m mpi4py -m pytest --log-cli-level=DEBUG --pyargs gmx -s --verbose 
+  - mkdir build
+  - pushd build
+  # install in user site-packages directory
+  - GROMACS_DIR=$HOME/gromacs cmake .. -DPYTHON_EXECUTABLE=`which python` -DGMXAPI_USER_INSTALL=ON
+  - make -j4 install
+  - popd
+  - mpiexec -n 2 python -m mpi4py -m pytest --log-cli-level=DEBUG --pyargs gmx -s --verbose
+  - pip uninstall -y gmx
+  # install in virtualenv
+  - virtualenv venv
+  - source venv/bin/activate
+  - pip install numpy mpi4py networkx pytest
+  - pushd build
+  # Do an intentionally non-thorough job of removing previous build: test unclean build directory.
+  - rm CMakeCache.txt
+  - GROMACS_DIR=$HOME/gromacs cmake .. -DPYTHON_EXECUTABLE=`which python`
+  - make -j4 install
+  - popd
+  - mpiexec -n 2 python -m mpi4py -m pytest --log-cli-level=DEBUG --pyargs gmx -s --verbose
+
 

CMakeLists.txt

@@ -5,8 +5,53 @@ cmake_minimum_required(VERSION 3.4.3)
 #list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
 
 # Sets the PROJECT_VERSION variable, as well...
-project(gmxpy VERSION 0.0.5)
+project(gmxpy VERSION 0.0.6)
+
+# If the user is not in a virtual environment and is not a privileged user and has not specified an install location
+# for the Python module (GMXAPI_INSTALL_PATH), this option causes the automatic install location to query the user
+# site-packages directory instead of using the default site-packages directory for the interpreter.
+option(GMXAPI_USER_INSTALL "Override the default site-packages directory with the user-specific Python packages directory. \
+       (Do not use with virtual environments.) \
+       Has no effect if GMXAPI_INSTALL_PATH is defined or cached. \
+       Use -UGMXAPI_INSTALL_PATH to force recalculation." OFF)
+
+# Since a user may have multiple virtual environments with different Python interpreters, it is generally confusing to
+# have a package for a virtual environment installed in the user's default user site-packages directory.
+
+unset(PYTHONINTERP_FOUND)
+unset(PYTHONLIBS_FOUND)
+find_package(PythonInterp)
+if (PYTHONINTERP_FOUND)
+    message(STATUS "Found Python interpreter: ${PYTHON_EXECUTABLE}")
+    find_package(PythonLibs)
+    if (PYTHONLIBS_FOUND)
+        if (GMXAPI_USER_INSTALL)
+            execute_process(COMMAND ${PYTHON_EXECUTABLE} "-m" "site" "--user-site" OUTPUT_VARIABLE GMXAPI_DEFAULT_SITE_PACKAGES OUTPUT_STRIP_TRAILING_WHITESPACE)
+            message(STATUS "Python user site-packages directory is ${GMXAPI_DEFAULT_SITE_PACKAGES}")
+        else()
+            execute_process(COMMAND ${PYTHON_EXECUTABLE} -c "import sys; import os; print(os.path.abspath(os.path.join(sys.prefix, 'lib', 'python${PYTHON_VERSION_MAJOR}.${PYTHON_VERSION_MINOR}', 'site-packages')))" OUTPUT_VARIABLE GMXAPI_DEFAULT_SITE_PACKAGES OUTPUT_STRIP_TRAILING_WHITESPACE)
+            message(STATUS "Python site-packages directory is ${GMXAPI_DEFAULT_SITE_PACKAGES}")
+        endif()
+    else()
+        message(FATAL "Found Python interpreter ${PYTHON_EXECUTABLE} but this Python installation does not have developer tools."
+                "Set PYTHON_EXECUTABLE to the Python interpreter that was installed with a working Python.h header file.")
+    endif()
+else()
+    message(FATAL "Could not find Python interpreter. Set CMake flag -DPYTHON_EXECUTABLE=/path/to/python to hint.")
+endif()
+
+# At some point this may be part of a CMake package with several components for which a single CMAKE_INSTALL_PREFIX does
+# not make sense, so let's manage the install path separately.
+set(GMXAPI_INSTALL_PATH ${GMXAPI_DEFAULT_SITE_PACKAGES}/gmx CACHE PATH
+    "Path to Python module install location (site-packages). For an automatically determined install location based on \
+    the Python installation, leave undefined or explicitly undefined with -UGMXAPI_INSTALL_PATH and, optionally, set \
+    GMXAPI_USER_INSTALL on or off to specify the installation's site-packages directory or the 'user' site-packages \
+    directory.")
+
+message(STATUS "Python module will be installed to GMXAPI_INSTALL_PATH cache value ${GMXAPI_INSTALL_PATH}")
 
 add_subdirectory(pybind11)
 
-add_subdirectory(src/gmx/core)
+add_subdirectory(src/gmx)
+
+add_subdirectory(docs)

README.md

@@ -1,6 +1,3 @@
-[![Build Status](https://travis-ci.org/kassonlab/gmxapi.svg?branch=master)](https://travis-ci.org/kassonlab/gmxapi)
-[![Documentation Status](https://readthedocs.org/projects/gmxapi/badge/?version=latest)](http://gmxapi.readthedocs.io/en/latest/?badge=latest)
-
 The gmxapi project provides interfaces for managing and extending molecular dynamics simulation workflows.
 In this repository, a Python package provides the `gmx` module for high-level interaction with GROMACS.
 `gmx.core` provides Python bindings to the `gmxapi` C++ GROMACS external API.
@@ -17,6 +14,16 @@ The whole thing is driven at the highest level by a simple Python interface.
 
 See the latest gmxapi documentation at [http://gmxapi.readthedocs.io/en/latest/](http://gmxapi.readthedocs.io/en/latest/)
 
+## Current master branch
+[![Build Status](https://travis-ci.org/kassonlab/gmxapi.svg?branch=master)](https://travis-ci.org/kassonlab/gmxapi)
+[![Documentation Status](https://readthedocs.org/projects/gmxapi/badge/?version=latest)](http://gmxapi.readthedocs.io/en/latest/?badge=latest)
+
+## Development branch
+[![Build Status](https://travis-ci.org/kassonlab/gmxapi.svg?branch=devel)](https://travis-ci.org/kassonlab/devel)
+[![Documentation Status](https://readthedocs.org/projects/gmxapi/badge/?version=devel)](http://gmxapi.readthedocs.io/en/devel/?badge=latest)
+
+Note: automated documentation generation may not be up to date for development branch.
+
 # Running simulations from Python
 
 To run a simulation as you would with the `gmx` command-line tool, a gmxapi

docker/Dockerfile

@@ -22,6 +22,7 @@ RUN pip install --upgrade setuptools --user
 
 RUN wget https://github.com/kassonlab/gmxapi/archive/$BRANCH.zip && \
     unzip $BRANCH.zip && \
+    rm -rf /home/jovyan/gmxpy && \
     mv gmxapi-$BRANCH /home/jovyan/gmxpy && \
     rm $BRANCH.zip
 

docs/CMakeLists.txt

@@ -0,0 +1,23 @@
+# Dummy output which is never actually produced. Anything that depends on
+# this will always be rebuilt. Ref: https://stackoverflow.com/a/32062884/5351807
+add_custom_command(
+    OUTPUT always_rebuild
+    COMMAND cmake -E echo
+)
+
+add_custom_command(
+    OUTPUT
+    objects.inv
+    DEPENDS
+    always_rebuild
+    COMMAND
+    ${PYTHON_EXECUTABLE} -m sphinx -b html ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT
+    "Generating documentation with Sphinx"
+    VERBATIM
+)
+
+add_custom_target(
+    docs
+    DEPENDS objects.inv
+)