python_packaging/README.md

   1 # Python package sources
   2
   3 This directory exists as a staging area supporting GROMACS enhancement
   4 [#2045](https://gitlab.com/gromacs/gromacs/-/issues/2045),
   5 which attempts to update the gmxapi efforts from GROMACS 2019,
   6 merge external repositories from
   7 https://github.com/kassonlab/gmxapi
   8 and
   9 https://github.com/kassonlab/sample_restraint,
  10 and build the new functionality proposed at
  11 https://github.com/kassonlab/gmxapi-scripts
  12
  13 ## Repository organization
  14
  15 **TODO: testing infrastructure and project management conventions to allow fully integrated development**
  16 **TODO: Consider long term homes of these directory contents.**
  17
  18 ## gmxapi
  19
  20 Python framework for gmxapi high-level interface.
  21
  22 The `src` directory provides the files that will be copied to the GROMACS installation location from which users may
  23 install Python packages.
  24 This allows C++ extension modules to be built against a user-chosen GROMACS installation,
  25 but for a Python interpreter that is very likely different from that used
  26 by the system administrator who installed GROMACS.
  27
  28 To build and install the Python package,
  29 first install GROMACS to `/path/to/gromacs`.
  30 Then, install the package in a Python virtualenv.
  31
  32     source /path/to/gromacs/bin/GMXRC
  33     python3 -m venv $HOME/somevirtualenv
  34     source $HOME/somevirtualenv/bin/activate
  35     (cd src && pip install -r requirements.txt && pip install .)
  36     python -c 'import gmxapi as gmx'
  37
  38 Use `pytest` to run unit tests and integration tests.
  39
  40     pip install -r requirements-test.txt
  41     pytest src/test
  42     pytest test
  43
  44 For additional discussion on packaging and distribution, see
  45 https://gitlab.com/gromacs/gromacs/-/issues/2896
  46
  47 ## Sample MD extension code
  48
  49 `sample_restraint` is a subtree containing a complete CMake project for building
  50 pluggable GROMACS MD extensions for execution through gmxapi. Up to and
  51 including version 0.0.7 of the sample code, the sub-project lived at
  52 https://github.com/kassonlab/sample_restraint/ and was supported by GROMACS 2019.
  53
  54 The GROMACS repository becomes the upstream source for the sample code for
  55 GROMACS releases 2020 and higher. Refer to [README.md](sample_restraint/README.md)
  56 in `python_packaging/sample_restraint` for more information.
  57
  58 To use a plugin based on the sample restraint, you will need to build and install
  59 the gmxapi Python package (above).
  60
  61 **todo** CookieCutter repo for easy forking.
  62
  63 ## Docker and Travis-CI testing
  64
  65 **TODO: Migrate to Jenkins-based CI as Docker infrastructure becomes available.**
  66 Infastructure described here is transitional and reflects our need to be able to see code work
  67 in order to review it satisfactorily in the period before GROMACS CI infrastructure
  68 is ready for the load. At some point the Docker aspects will change,
  69 or be removed as appropriate.
  70
  71 The Python packaging will be tested on Jenkins with Docker-based CI, but this
  72 infrastructure is a little way off. In the mean time, we are trying to submit
  73 changes that do not affect main line GROMACS development or building and to
  74 perform testing with Docker externally. Users may build and run Docker images
  75 from the `python_packaging/docker` directory. The `kassonlab` Travis-CI account
  76 will automatically build and run Docker-based tests for each outstanding
  77 feature branch.
  78
  79 The Dockerfiles
  80 * direct a few different Linux, Python, and GROMACS configurations,
  81 * build and install the `gmxapi` and `sample_restraint` packages, and
  82 * provide a few styles of testing through the `scripts` accessible through `entrypoint.sh`.
  83
  84 In successive build stages, Travis-CI is directed to use a series of Docker images,
  85 referred to here with their dockerhub repository, an explanation of tags,
  86 and the Dockerfiles from which they are built.
  87 The image naming scheme encodes a build matrix element in the repository name and
  88 a git branch or reference in the image tag (described below).
  89 Additional information in `python_packaging/docker/README.md`.
  90
  91 1. `gmxapi/gromacs-dependencies-<matrix>:<tag>` Ubuntu distribution with dependencies for
  92    various GROMACS build configurations. `<matrix>` encodes the build matrix dimensions
  93    for things like compiler and MPI flavor. Travis-CI will rebuild this for commits to
  94    `kassonLabFork`, but if the `<matrix>` string changes, a more privileged dockerhub
  95    account will have to push the new repository the first time and then grant access
  96    to the service account used by the Travis-CI configuration.
  97    `<tag>` is the (short) git revision hash
  98    of the `master` branch commit corresponding to the current state of the `kassonLabFork`
  99    branch.
 100 2. `gmxapi/gromacs-<matrix>:<tag>` Builds on `gromacs-dependencies-<matrix>`, where
 101    `<matrix>` has the same meaning as above. `<tag>` is the (short) git revision hash
 102    of the `master` branch commit corresponding to the current state of the `kassonLabFork`
 103    branch.
 104    This is recorded in the `kassonLabFork` `.travis.yml`.
 105 3. `gmxapi/ci-<matrix>:<tag>` starts with `gromacs-<matrix>` and merges in the
 106     `python_packaging` changes associated with the feature branch indicated by `<tag>`
 107
 108 Hint: the fork point from `master` and the current git ref can be set as environment variables:
 109
 110     FORKPOINT=$(git show -s --pretty=format:"%h" `git merge-base master HEAD`)
 111     REF=`git show -s --pretty=format:"%h"`
 112
 113 ## External project code
 114
 115 Refer to `./src/external/README.md` for current details on the copied external
 116 sources.
 117
 118 # pybind11
 119
 120 Python bindings are expressed in C++ using the
 121 [pybind11](https://pybind11.readthedocs.io/en/stable/)
 122 template library.
 123 The pybind11 repository is mirrored in GROMACS project sources and
 124 installed with GROMACS for convenience and reproducibility.
 125
 126 # Build and install
 127
 128 ## Cross compiling
 129
 130 On some systems, GROMACS will have been built and installed for a different
 131 architecture than the system on which the Python package will be compiled.
 132 We need to use CMake Tool-chains to support cross-compiling for the target architecture.
 133
 134 ## Offline installation
 135
 136 The `pip install` options `--no-index` and `--find-links` allow for an offline stash of package archives so that
 137 satisfying dependencies for a new virtualenv does not require network access or lengthy build times.
 138
 139 # Dependencies
 140
 141 ## OS X
 142 Some dependencies (notably, a Python installation itself) may require some fiddling
 143 with the XCode SDK.
 144 https://developer.apple.com/documentation/xcode_release_notes/xcode_10_release_notes#3035624
 145
 146 # Tests for gmxapi Python packages distributed with GROMACS
 147
 148 ## Requirements
 149
 150 Python tests use the `unittest` standard library module and the `unittest.mock`
 151 submodule, included in Python 3.3+.
 152
 153 The additional `pytest` package allows tests to be written more easily and
 154 concisely, with easier test fixtures (through decorators), log handling, and
 155 other output handling.
 156
 157 ## Files
 158
 159 Python files beginning with `test_` are collected by the Python testing
 160 framework during automatic test discovery.
 161
 162 `conftest.py` and `pytest.ini` provide configuration for `pytest`.
 163
 164 ## Usage
 165
 166 For basic tests, install the Python package(s) (presumably into a virtualenv),
 167 then use the `pytest` executable to run these tests against the installed
 168 package(s).
 169
 170 `pytest $LOCAL_REPO_DIR/python_packaging/src/test`
 171
 172 where `$LOCAL_REPO_DIR` is the path to the local copy of the GROMACS source repository.
 173
 174 For multi-process tests, run with an MPI execution wrapper and the `mpi4py` module.
 175
 176 `mpiexec -n 2 python -m mpi4py -m pytest $LOCAL_REPO_DIR/python_packaging/test`
 177
 178 ## Controlling output
 179
 180 Refer to pytest documentation for command line options to control the type and detail of output.
 181 Some high level overview and basic tasks are online at https://docs.pytest.org/en/3.9.3/usage.html
 182 but you should run `pytest -h` in a terminal to get the complete set of available options
 183 (in particular, note *log_cli* and *log_level*).