README.md

   1 GROMACS Python API project
   2 ==========================
   3
   4 This project provides Python wrappers for Gromacs trajectory analysis [framework][trjan].
   5
   6 You can find an example tool written with this framework in `examples/example_pyapi.py`.
   7
   8 We would be very grateful for any feedback at this very alpha stage of the project.
   9
  10 Building and installing
  11 -----------------------
  12
  13 gromacs-pyapi has following dependencies:
  14
  15 * Gromacs (tested with 2016.x branch)
  16 * CMake
  17 * [SIP][sip] (confirmed to work with 4.19)
  18
  19 These should be present in repositories of any modern Linux distro.
  20
  21 To build do the following:
  22
  23 ```console
  24 $ mkdir build
  25 $ cd build
  26 $ cmake .. -DCMAKE_INSTALL_PREFIX=~/.local
  27 $ make
  28 $ make install
  29 ```
  30
  31 Of course, you can choose any install location you like.
  32
  33 By default, the bindings will be built with currently active Python version. Both Python 2 and Python 3 are supported.
  34
  35 Usage
  36 --------
  37
  38 To use analysis framework, you need to subclass `gromacs.TrajectoryAnalysis.TrajectoryAnalysisModule` and override all virtual methods as stated in Gromacs documentation. To run the tool, provide an instance of your module to `TrajectoryAnalysis.TrajectoryAnalysisCommandLineRunner.runAsMain` function. All this boilerplate code can be copied from the example.
  39
  40 When run, the script will behave exactly like any other `gmx` tool, accepting the same set of command-line options. Module specific options can be provided in `initOptions` method with use of `gromacs.Options.PyOptionsHolder` class. This class is needed to overcome impossibilities to directly wrap gromacs `Options` framework in Python.
  41
  42 `PyOptionHolder` class has several static methods:
  43
  44 * `doubleOption`
  45 * `integerOption`
  46 * `stringOption`
  47 * `booleanOption`
  48 * `selectionOption`
  49 * `fileNameOption`
  50
  51 All of these methods accept three arguments: `name`, `count` and `default`. Only name is mandatory, `count` is 1 by default.
  52 If `count` is zero, the option will accept an unlimited number of values. If `count` is greater than zero, the option will accept exactly `count` values.
  53
  54 You should store an instance of `PyOptionsHolder` class in your module's instance field and later access options values by name with `[]` operator. In other words, this class will behave as a dictionary.
  55
  56 This option framework may change in the future.
  57
  58 NumPy
  59 ----------
  60
  61 All data sent from C++ side is not copied into Python memory. Instead, a memory view of some sort is returned. For topology, frames and selections all coordinate, velocity, etc. vectors are provided as NumPy arrays directly on top of C++ arrays allocated by Gromacs. This means that actual references to these arrays are only valid during current fuction call, e.g. `analyzeFrame`. If you try to store an array and use it later, you may get a segmentation fault or you may access not the array you were expecting, because of memory re-writing. If you need to store this data for later use, allocate your own array and make a copy.
  62
  63 [trjan]: http://manual.gromacs.org/documentation/2016.3/doxygen/html-user/page_analysisframework.xhtml
  64 [sip]: https://www.riverbankcomputing.com/software/sip/intro