Project

General

Profile

Feature #1440

missing reference to SIMD/CPU acceleration in the install guide

Added by Szilárd Páll over 6 years ago. Updated over 6 years ago.

Status:
Closed
Priority:
High
Assignee:
Category:
documentation
Target version:
Difficulty:
uncategorized
Close

Description

The installation guide contains no general information on how to compile for correct SIMD support, nor the role of the GMX_CPU_ACCELERATION CMake variable. I think this is rather important aspect of building GROMACS and it needs to be explained in the install guide.

Additionally, I think users not familiar with cmake will have little chance in figuring out what configuration options exist and which are the ones relevant for their use-case. That's because cmake does not provide a self-documenting capability of the build system options like configure --help does (unless one uses ccmake or interactive mode which many may not even know of). A configuration summary could help, but that may not be appropriate for 4.6.

Hence, even those who know what SSE and AVX is will not even notice if they did not build binaries with correct SIMD support. Hence, a brief technical documentation which at least mentions the most important features/options of the build system would also be useful.

Associated revisions

Revision ec2c9197 (diff)
Added by Mark Abraham over 6 years ago

Convert install guide to markdown

Adds `make install-guide` to make both a plain-text INSTALL for the
tarball, and a monolithic HTML install guide for uploading to the
website. Intended for processing with pandoc, but I don't think
there's any pandoc-specific extensions used. Naturally, if the build
system doesn't have pandoc, then this make target is not available,
just like the other documentation features.

Added more description about various SIMD instruction sets,
portability, and how to use compilers and the GMX_SIMD setting.

Added summary of important CMake options for typical GROMACS
installations.

This now does some variable interpolation to keep accuracy up without
active maintenance, so setting some such variables gets changed a bit.

Mentioned more optional build components

Minor textual changes to the install guide.

Fixes #1440. Refs #1242

Change-Id: Iff8e165759fbf8cc5199c8447e912403b8a79a17

History

#1 Updated by Mark Abraham over 6 years ago

Agree needed. Surprised I never wrote anything in the first place.

#2 Updated by Mark Abraham over 6 years ago

Mark Abraham wrote:

Agree needed. Surprised I never wrote anything in the first place.

Don't think I want to bother writing one for 4.6.6 and then changing half the words for 5.0, though.

#3 Updated by Szilárd Páll over 6 years ago

Mark Abraham wrote:

Mark Abraham wrote:

Agree needed. Surprised I never wrote anything in the first place.

Don't think I want to bother writing one for 4.6.6 and then changing half the words for 5.0, though.

I don't see why can't a section written for 4.6 be used for 5.0. The only thing that changes is that GMX_CPU_ACCELERATION gets renamed to GMX_SIMD. That's simply solved by a sed 's/GMX_CPU_ACCELERATION/GMX_SIMD/'. We can't just abandon 4.6 for the sake of convenience and this info is badly missing.

#4 Updated by Justin Lemkul over 6 years ago

I fully agree that we need to improve the cmake documentation; it's something I said a long time ago that got lost in the shuffle :)

The question that comes to my mind is this: what belongs in the manual and what belongs on the wiki? Do we need to provide "example" install commands in the manual, or leave that for the web so that users can contribute to it? I don't know what the participation rate will be, and the lack of updates to the wiki from non-developers is pretty disheartening, but then too, people may not know that they can (and should!) be contributing this information.

So where do we draw the line? Do we put a simple list of cmake options in the manual that most people would use, like:

1. GMX_CPU_ACCELERATION
2. CMAKE_PREFIX_PATH (for FFTW)
3. GMX_GPU
4. CMAKE_C_COMPILER
5. ???

Those are the ones I usually need. Are they sufficient for the manual? As it is, Appendix A just says to refer to the website, but then of course there's missing information on the website :) So which do we update? Do we keep them in sync? That's probably not feasible, but if we can determine a dividing line between what goes in the manual and what goes on the wiki, I'm glad to write something up reasonably quickly. Perhaps the "normal" case and an explanation of SIMD features can go in the manual (since we all love performance!) as well as anything else critical that people might need to know.

#5 Updated by Mark Abraham over 6 years ago

Szilárd Páll wrote:

Mark Abraham wrote:

Mark Abraham wrote:

Agree needed. Surprised I never wrote anything in the first place.

Don't think I want to bother writing one for 4.6.6 and then changing half the words for 5.0, though.

I don't see why can't a section written for 4.6 be used for 5.0. The only thing that changes is that GMX_CPU_ACCELERATION gets renamed to GMX_SIMD. That's simply solved by a sed 's/GMX_CPU_ACCELERATION/GMX_SIMD/'. We can't just abandon 4.6 for the sake of convenience and this info is badly missing.

And RDTSCP behaviour, which is different for different 4.6.x versions. All possible, but I am not going to spend time on documenting 4.6 until we have written it for 5.0, and maybe not going to prioritise it even then. But go right ahead!

#6 Updated by Mark Abraham over 6 years ago

Justin Lemkul wrote:

I fully agree that we need to improve the cmake documentation; it's something I said a long time ago that got lost in the shuffle :)

The question that comes to my mind is this: what belongs in the manual and what belongs on the wiki? Do we need to provide "example" install commands in the manual, or leave that for the web so that users can contribute to it? I don't know what the participation rate will be, and the lack of updates to the wiki from non-developers is pretty disheartening, but then too, people may not know that they can (and should!) be contributing this information.

Szilard and I have been discussing lately that we need to be more explicit about structuring the installation information
  • that a cluster sysadmin needs (e.g. compile for the target, not the head node!)
  • that a noob doing a tutorial needs (quick and dirty)
  • that a noob wanting to do a decent install of mdrun needs (get a real compiler, compile on the build host)
  • that someone wanting to tweak the last few percent might need

So where do we draw the line? Do we put a simple list of cmake options in the manual that most people would use, like:

1. GMX_CPU_ACCELERATION
2. CMAKE_PREFIX_PATH (for FFTW)
3. GMX_GPU
4. CMAKE_C_COMPILER
5. ???

Those are the ones I usually need. Are they sufficient for the manual? As it is, Appendix A just says to refer to the website, but then of course there's missing information on the website :) So which do we update? Do we keep them in sync? That's probably not feasible, but if we can determine a dividing line between what goes in the manual and what goes on the wiki, I'm glad to write something up reasonably quickly. Perhaps the "normal" case and an explanation of SIMD features can go in the manual (since we all love performance!) as well as anything else critical that people might need to know.

I think the wiki model is close to broken these days. It served the purpose of exporting the writing of lots of documentation to volunteers outside Stockholm. I joined it because I was sick of answering the same questions on gmx-users. However, the details of an installation (and usage!) are closely tied to version numbers, and the wiki-based service of letting users/devs fix documentation easily (and sometimes retrospectively) is compromised by the dis-services of
  • random quality control (content and style),
  • the ability of developers to get away with not documenting changes to the installation procedure when they make them (e.g. I gather nobody much not involved with the change knew how to do the mdrun-only build in master after it changed from a make target to a configuration option), and
  • the need to have lots of tedious clauses about things that were broken in x.y.z1 and are now fixed/different in x.y.z3.

Also, the barrier to wiki participation is higher now, because we think we need to manually accept applications for editing rights.

I would like to have an install guide (and similarly a user guide with some of the content now on the wiki) written in markdown in the code repo that can be automatically deployed to the website (as HTML and PDF, and maybe the install guide into the tarball as text in INSTALL) with explicit version stamps that will be available permanently.

There's content that should stay on the wiki for now / ever. But for example, genbox is now two tools, so some stuff is probably out of date. When I get my way, trjconv will become about four tools, so there's a whole pile of wiki content that will just fall out of date. We cannot have developers writing code in May and having to document using it next February at release time because it's stupid to document the git master branch in some wiki sandbox. How to do a trjconv to make a nice visualization is reasonably static these days, and can go in the user guide, IMO.

#7 Updated by Erik Lindahl over 6 years ago

  • Tracker changed from Bug to Feature

#8 Updated by Mark Abraham over 6 years ago

  • Assignee changed from Justin Lemkul to Mark Abraham
  • Target version changed from 4.6.6 to 5.0

#9 Updated by Erik Lindahl over 6 years ago

  • Status changed from New to Fix uploaded

#10 Updated by Erik Lindahl over 6 years ago

  • Status changed from Fix uploaded to Resolved

#11 Updated by Erik Lindahl over 6 years ago

  • Status changed from Resolved to Closed

Also available in: Atom PDF