README

This is an unofficial version of GROMACS. Please do not use it for
production simulation work. It exists to show a working prototype from
which the GROMACS team expects to extract code useful for implementing
functionality in future major releases of GROMACS.

This code is contained in a git branch available from the main GROMACS
code review server. The latest version can be obtained via

  git clone https://gerrit.gromacs.org/gromacs.git -b sandbox-gmxapi --single-branch

For more information, refer to python_packaging/README.md, docs/install-guide,
and Redmine issue https://redmine.gromacs.org/issues/2045
or email info@gmxapi.org. Developers may also consider the git commit history
and Gerrit issues tagged with the topic "gmxapi".

When the functionality is integrated, then this branch will no longer
be useful and will be removed from the gerrit server.  If there is no
activity in twelve months, then the core GROMACS team will deem it
inactive and remove it.

The team interested in this branch includes
* Eric Irrgang, Peter Kasson (UVA/MolSSI)
* Mark Abraham, Paul Bauer, Joe Jordan, Christian Blau (KTH/BioExcel)

Current branch policy is that any of the members of the gerrit
"gmxapi" or "gmxcore" groups may push either normal or merge
commits to it. The history of this branch is of no real interest.
Commits to it will not be reviewed per se. As with all shared
branches, it will never be rebased. Periodically, master branch will
be merged into it, so that it stays up to date. The GROMACS Jenkins CI
server currently does not do any verification on this branch, so it
will not be as stable or widely useful as GROMACS master branch. This
branch will not be mirrored on the GROMACS github.

To push to this branch, use

  git push ssh://USER@gerrit.gromacs.org HEAD:refs/heads/sandbox-gmxapi

The gerrit server will not require that a ChangeId exists, so you do
not need the usual GROMACS git post-commit hook installed to work with
this branch. Do not push to refs/for/sandbox-gmxapi, because that is
the invocation that opens a patch set for review for this branch,
which we do not intend to do.

Code will be extracted from this branch in manageable chunks and
proposed for integration in master branch in the usual way for
GROMACS. This branch merely provides convenient context for reviewers
about the context into which that chunk will later fit. For example,
they could see that functionality works suitably, or test performance.

As such code is integrated into master branch, the content of this branch
will be updated so that the next chunk to be staged into master can
be reviewed in the appropriate context.

                               * * * * *

GROMACS is free software, distributed under the GNU Lesser General
Public License, version 2.1 However, scientific software is a little
special compared to most other programs. Both you, we, and all other
GROMACS users depend on the quality of the code, and when we find bugs
(every piece of software has them) it is crucial that we can correct
it and say that it was fixed in version X of the file or package
release. For the same reason, it is important that you can reproduce
other people's result from a certain GROMACS version.

The easiest way to avoid this kind of problems is to get your modifications
included in the main distribution. We'll be happy to consider any decent 
code. If it's a separate program it can probably be included in the contrib 
directory straight away (not supported by us), but for major changes in the 
main code we appreciate if you first test that it works with (and without) 
MPI, threads, double precision, etc.

If you still want to distribute a modified version or use part of GROMACS
in your own program, remember that the entire project must be licensed
according to the requirements of the LGPL v2.1 license under which you
received this copy of GROMACS. We request that it must clearly be labeled as
derived work. It should not use the name "official GROMACS", and make
sure support questions are directed to you instead of the GROMACS developers.
Sorry for the hard wording, but it is meant to protect YOUR reseach results!

                               * * * * *

The development of GROMACS is mainly funded by academic research grants. 
To help us fund development, we humbly ask that you cite the GROMACS papers:

* GROMACS: A message-passing parallel molecular dynamics implementation
  H.J.C. Berendsen, D. van der Spoel and R. van Drunen
  Comp. Phys. Comm. 91, 43-56 (1995)
  DOI: https://doi.org/10.1016/0010-4655(95)00042-E
 
* GROMACS 4: Algorithms for highly efficient, load-balanced, and scalable
  molecular simulation
  B. Hess and C. Kutzner and D. van der Spoel and E. Lindahl
  J. Chem. Theory Comput. 4 (2008) pp. 435-447
  DOI: https://doi.org/10.1021/ct700301q

* GROMACS 4.5: a high-throughput and highly parallel open source
  molecular simulation toolkit
  Sander Pronk, Szilárd Páll, Roland Schulz, Per Larsson, Pär Bjelkmar,
  Rossen Apostolov, Michael R. Shirts, Jeremy C. Smith, Peter M. Kasson,
  David van der Spoel, Berk Hess, Erik Lindahl.
  Bioinformatics 29 (2013) pp. 845-54
  DOI: https://doi.org/10.1093/bioinformatics/btt055

* Tackling Exascale Software Challenges in Molecular Dynamics Simulations
  with GROMACS
  Szilárd Páll, Mark J. Abraham, Carsten Kutzner, Berk Hess, Erik Lindahl
  In S. Markidis & E. Laure (Eds.), Solving Software Challenges for Exascale,
  Lecture Notes for Computer Science, 8759 (2015) pp. 3–27
  DOI: https://doi.org/10.1007/978-3-319-15976-8_1

* GROMACS: High performance molecular simulations through multi-level parallelism from laptops to supercomputers
  M. J. Abraham, T. Murtola, R. Schulz, S. Páll, J. C. Smith, B. Hess, E. Lindahl,
  SoftwareX, 1, (2015), 19-25
  DOI: https://doi.org/10.1016/j.softx.2015.06.001

There are a lot of cool features we'd like to include in future versions,
but our resources are limited. All kinds of donations are welcome, both in 
form of code, hardware and funding! Industrial users who choose to pay
for a license pro bono (it is still LGPL and can be redistributed freely) or
contribute in other ways are listed as GROMACS supporters on our webpages. 
Don't hesitate to contact us if you are interested.


                       Good luck with your simulations!

                              The GROMACS Crew