hwloc: null check for cpuset
[mpich-dev.git] / README.vin
1                         MPICH Release %VERSION%
2
3 MPICH is a high-performance and widely portable implementation of the
4 MPI-3.1 standard from the Argonne National Laboratory.  This release
5 has all MPI 3.1 functions and features required by the standard with
6 the exception of support for the "external32" portable I/O format and
7 user-defined data representations for I/O.
8
9 This README file should contain enough information to get you started
10 with MPICH. More extensive installation and user guides can be found
11 in the doc/installguide/install.pdf and doc/userguide/user.pdf files
12 respectively. Additional information regarding the contents of the
13 release can be found in the CHANGES file in the top-level directory,
14 and in the RELEASE_NOTES file, where certain restrictions are
15 detailed. Finally, the MPICH web site, http://www.mpich.org, contains
16 information on bug fixes and new releases.
17
18
19 1.  Getting Started
20 2.  Reporting Installation or Usage Problems
21 3.  Compiler Flags
22 4.  Alternate Channels and Devices
23 5.  Alternate Process Managers
24 6.  Alternate Configure Options
25 7.  Testing the MPICH installation
26 8.  Fault Tolerance
27 9.  Developer Builds
28 10. Multiple Fortran compiler support
29 11. ABI Compatibility
30 12. Capability Sets
31 13. Threads
32
33
34 -------------------------------------------------------------------------
35
36 1. Getting Started
37 ==================
38
39 The following instructions take you through a sequence of steps to get
40 the default configuration (ch3 device, nemesis channel (with TCP and
41 shared memory), Hydra process management) of MPICH up and running.
42
43 (a) You will need the following prerequisites.
44
45     - REQUIRED: This tar file mpich-%VERSION%.tar.gz
46
47     - REQUIRED: A C compiler (gcc is sufficient)
48
49     - OPTIONAL: A C++ compiler, if C++ applications are to be used
50       (g++, etc.). If you do not require support for C++ applications,
51       you can disable this support using the configure option
52       --disable-cxx (configuring MPICH is described in step 1(d)
53       below).
54
55     - OPTIONAL: A Fortran compiler, if Fortran applications are to be
56       used (gfortran, ifort, etc.). If you do not require support for
57       Fortran applications, you can disable this support using
58       --disable-fortran (configuring MPICH is described in step 1(d)
59       below).
60
61     Also, you need to know what shell you are using since different shell
62     has different command syntax. Command "echo $SHELL" prints out the
63     current shell used by your terminal program.
64
65 (b) Unpack the tar file and go to the top level directory:
66
67       tar xzf mpich-%VERSION%.tar.gz
68       cd mpich-%VERSION%
69
70     If your tar doesn't accept the z option, use
71
72       gunzip mpich-%VERSION%.tar.gz
73       tar xf mpich-%VERSION%.tar
74       cd mpich-%VERSION%
75
76 (c) Choose an installation directory, say
77     /home/<USERNAME>/mpich-install, which is assumed to non-existent
78     or empty. It will be most convenient if this directory is shared
79     by all of the machines where you intend to run processes. If not,
80     you will have to duplicate it on the other machines after
81     installation.
82
83 (d) Configure MPICH specifying the installation directory:
84
85     for csh and tcsh:
86
87       ./configure --prefix=/home/<USERNAME>/mpich-install |& tee c.txt
88
89     for bash and sh:
90
91       ./configure --prefix=/home/<USERNAME>/mpich-install 2>&1 | tee c.txt
92
93     Bourne-like shells, sh and bash, accept "2>&1 |".  Csh-like shell,
94     csh and tcsh, accept "|&". If a failure occurs, the configure
95     command will display the error. Most errors are straight-forward
96     to follow. For example, if the configure command fails with:
97
98        "No Fortran compiler found. If you don't need to build any
99         Fortran programs, you can disable Fortran support using
100         --disable-fortran. If you do want to build Fortran programs,
101         you need to install a Fortran compiler such as gfortran or
102         ifort before you can proceed."
103
104     ... it means that you don't have a Fortran compiler :-). You will
105     need to either install one, or disable Fortran support in MPICH.
106
107     If you are unable to understand what went wrong, please go to step
108     (2) below, for reporting the issue to the MPICH developers and
109     other users.
110
111 (e) Build MPICH:
112
113     for csh and tcsh:
114
115       make |& tee m.txt
116
117     for bash and sh:
118
119       make 2>&1 | tee m.txt
120
121     This step should succeed if there were no problems with the
122     preceding step. Check file m.txt. If there were problems, do a
123     "make clean" and then run make again with V=1.
124
125       make V=1 |& tee m.txt       (for csh and tcsh)
126
127       OR
128
129       make V=1 2>&1 | tee m.txt   (for bash and sh)
130
131     Then go to step (2) below, for reporting the issue to the MPICH
132     developers and other users.
133
134 (f) Install the MPICH commands:
135
136     for csh and tcsh:
137
138       make install |& tee mi.txt
139
140     for bash and sh:
141
142       make install 2>&1 | tee mi.txt
143
144     This step collects all required executables and scripts in the bin
145     subdirectory of the directory specified by the prefix argument to
146     configure.
147
148 (g) Add the bin subdirectory of the installation directory to your
149     path in your startup script (.bashrc for bash, .cshrc for csh,
150     etc.):
151
152     for csh and tcsh:
153
154       setenv PATH /home/<USERNAME>/mpich-install/bin:$PATH
155
156     for bash and sh:
157   
158       PATH=/home/<USERNAME>/mpich-install/bin:$PATH ; export PATH
159
160     Check that everything is in order at this point by doing:
161
162       which mpicc
163       which mpiexec
164
165     These commands should display the path to your bin subdirectory of
166     your install directory.
167
168     IMPORTANT NOTE: The install directory has to be visible at exactly
169     the same path on all machines you want to run your applications
170     on. This is typically achieved by installing MPICH on a shared
171     NFS file-system. If you do not have a shared NFS directory, you
172     will need to manually copy the install directory to all machines
173     at exactly the same location.
174
175 (h) MPICH uses a process manager for starting MPI applications. The
176     process manager provides the "mpiexec" executable, together with
177     other utility executables. MPICH comes packaged with multiple
178     process managers; the default is called Hydra.
179
180     Now we will run an MPI job, using the mpiexec command as specified
181     in the MPI standard. There are some examples in the install
182     directory, which you have already put in your path, as well as in
183     the directory mpich-%VERSION%/examples. One of them is the classic
184     CPI example, which computes the value of pi by numerical
185     integration in parallel.
186
187     To run the CPI example with 'n' processes on your local machine,
188     you can use:
189
190       mpiexec -n <number> ./examples/cpi
191
192     Test that you can run an 'n' process CPI job on multiple nodes:
193
194       mpiexec -f machinefile -n <number> ./examples/cpi
195
196     The 'machinefile' is of the form:
197
198       host1
199       host2:2
200       host3:4   # Random comments
201       host4:1
202
203     'host1', 'host2', 'host3' and 'host4' are the hostnames of the
204     machines you want to run the job on. The ':2', ':4', ':1' segments
205     depict the number of processes you want to run on each node. If
206     nothing is specified, ':1' is assumed.
207
208     More details on interacting with Hydra can be found at
209     http://wiki.mpich.org/mpich/index.php/Using_the_Hydra_Process_Manager
210
211 If you have completed all of the above steps, you have successfully
212 installed MPICH and run an MPI example.
213
214 -------------------------------------------------------------------------
215
216 2. Reporting Installation or Usage Problems
217 ===========================================
218
219 [VERY IMPORTANT: PLEASE COMPRESS ALL FILES BEFORE SENDING THEM TO
220 US. DO NOT SPAM THE MAILING LIST WITH LARGE ATTACHMENTS.]
221
222 The distribution has been tested by us on a variety of machines in our
223 environments as well as our partner institutes. If you have problems
224 with the installation or usage of MPICH, please follow these steps:
225
226 1. First see the Frequently Asked Questions (FAQ) page at
227 http://wiki.mpich.org/mpich/index.php/Frequently_Asked_Questions to
228 see if the problem you are facing has a simple solution. Many common
229 problems and their solutions are listed here.
230
231 2. If you cannot find an answer on the FAQ page, look through previous
232 email threads on the discuss@mpich.org mailing list archive
233 (https://lists.mpich.org/mailman/listinfo/discuss). It is likely
234 someone else had a similar problem, which has already been resolved
235 before.
236
237 3. If neither of the above steps work, please send an email to
238 discuss@mpich.org. You need to subscribe to this list
239 (https://lists.mpich.org/mailman/listinfo/discuss) before sending an
240 email.
241
242 Your email should contain the following files.  ONCE AGAIN, PLEASE
243 COMPRESS BEFORE SENDING, AS THE FILES CAN BE LARGE.  Note that,
244 depending on which step the build failed, some of the files might not
245 exist.
246
247     mpich-%VERSION%/c.txt (generated in step 1(d) above)
248     mpich-%VERSION%/m.txt (generated in step 1(e) above)
249     mpich-%VERSION%/mi.txt (generated in step 1(f) above)
250     mpich-%VERSION%/config.log (generated in step 1(d) above)
251     mpich-%VERSION%/src/openpa/config.log (generated in step 1(d) above)
252     mpich-%VERSION%/src/mpl/config.log (generated in step 1(d) above)
253     mpich-%VERSION%/src/pm/hydra/config.log (generated in step 1(d) above)
254     mpich-%VERSION%/src/pm/hydra/tools/topo/hwloc/hwloc/config.log (generated in step 1(d) above)
255
256     DID WE MENTION? DO NOT FORGET TO COMPRESS THESE FILES!
257
258 If you have compiled MPICH and are having trouble running an
259 application, please provide the output of the following command in
260 your email.
261
262     mpiexec -info
263
264 Finally, please include the actual error you are seeing when running
265 the application, including the mpiexec command used, and the host
266 file. If possible, please try to reproduce the error with a smaller
267 application or benchmark and send that along in your bug report.
268
269 4. If you have found a bug in MPICH, we request that you report it at
270 our bug tracking system:
271 (https://trac.mpich.org/projects/mpich/newticket). Even if you believe
272 you have found a bug, we recommend you sending an email to
273 discuss@mpich.org first.
274
275
276 -------------------------------------------------------------------------
277
278 3. Compiler Flags
279 =================
280
281 MPICH allows several sets of compiler flags to be used. The first
282 three sets are configure-time options for MPICH, while the fourth is
283 only relevant when compiling applications with mpicc and friends.
284
285 (a) CFLAGS, CPPFLAGS, CXXFLAGS, FFLAGS, FCFLAGS, LDFLAGS and LIBS
286 (abbreviated as xFLAGS): Setting these flags would result in the
287 MPICH library being compiled/linked with these flags and the flags
288 internally being used in mpicc and friends.
289
290 (b) MPICHLIB_CFLAGS, MPICHLIB_CPPFLAGS, MPICHLIB_CXXFLAGS,
291 MPICHLIB_FFLAGS, and MPICHLIB_FCFLAGS (abbreviated as
292 MPICHLIB_xFLAGS): Setting these flags would result in the MPICH
293 library being compiled with these flags.  However, these flags will
294 *not* be used by mpicc and friends.
295
296 (c) MPICH_MAKE_CFLAGS: Setting these flags would result in MPICH's
297 configure tests to not use these flags, but the makefile's to use
298 them. This is a temporary hack for certain cases that advanced
299 developers might be interested in, but which break existing configure
300 tests (e.g., -Werror). These are NOT recommended for regular users.
301
302 (d) MPICH_MPICC_CFLAGS, MPICH_MPICC_CPPFLAGS, MPICH_MPICC_LDFLAGS,
303 MPICH_MPICC_LIBS, and so on for MPICXX, MPIF77 and MPIFORT
304 (abbreviated as MPICH_MPIX_FLAGS): These flags do *not* affect the
305 compilation of the MPICH library itself, but will be internally used
306 by mpicc and friends.
307
308
309   +--------------------------------------------------------------------+
310   |                    |                      |                        |
311   |                    |    MPICH library     |    mpicc and friends   |
312   |                    |                      |                        |
313   +--------------------+----------------------+------------------------+
314   |                    |                      |                        |
315   |     xFLAGS         |         Yes          |           Yes          |
316   |                    |                      |                        |
317   +--------------------+----------------------+------------------------+
318   |                    |                      |                        |
319   |  MPICHLIB_xFLAGS   |         Yes          |           No           |
320   |                    |                      |                        |
321   +--------------------+----------------------+------------------------+
322   |                    |                      |                        |
323   | MPICH_MAKE_xFLAGS  |         Yes          |           No           |
324   |                    |                      |                        |
325   +--------------------+----------------------+------------------------+
326   |                    |                      |                        |
327   | MPICH_MPIX_FLAGS   |         No           |           Yes          |
328   |                    |                      |                        |
329   +--------------------+----------------------+------------------------+
330
331
332 All these flags can be set as part of configure command or through
333 environment variables.
334
335
336 Default flags
337 --------------
338 By default, MPICH automatically adds certain compiler optimizations
339 to MPICHLIB_CFLAGS. The currently used optimization level is -O2.
340
341 ** IMPORTANT NOTE: Remember that this only affects the compilation of
342 the MPICH library and is not used in the wrappers (mpicc and friends)
343 that are used to compile your applications or other libraries.
344
345 This optimization level can be changed with the --enable-fast option
346 passed to configure. For example, to build an MPICH environment with
347 -O3 for all language bindings, one can simply do:
348
349   ./configure --enable-fast=O3
350
351 Or to disable all compiler optimizations, one can do:
352
353   ./configure --disable-fast
354
355 For more details of --enable-fast, see the output of "configure
356 --help".
357
358 For performance testing, we recommend the following flags:
359
360   ./configure --enable-fast=O3,ndebug --disable-error-checking --without-timing \
361               --without-mpit-pvars
362
363
364 Examples
365 --------
366
367 Example 1:
368
369   ./configure --disable-fast MPICHLIB_CFLAGS=-O3 MPICHLIB_FFLAGS=-O3 \
370         MPICHLIB_CXXFLAGS=-O3 MPICHLIB_FCFLAGS=-O3
371
372 This will cause the MPICH libraries to be built with -O3, and -O3
373 will *not* be included in the mpicc and other MPI wrapper script.
374
375 Example 2:
376
377   ./configure --disable-fast CFLAGS=-O3 FFLAGS=-O3 CXXFLAGS=-O3 FCFLAGS=-O3
378
379 This will cause the MPICH libraries to be built with -O3, and -O3
380 will be included in the mpicc and other MPI wrapper script.
381
382 Example 3:
383
384 There are certain compiler flags that should not be used with MPICH's
385 configure, e.g. gcc's -Werror, which would confuse configure and cause
386 certain configure tests to fail to detect the correct system features.
387 To use -Werror in building MPICH libraries, you can pass the compiler
388 flags during the make step through the Makefile variable
389 MPICH_MAKE_CFLAGS as follows:
390
391   make MPICH_MAKE_CFLAGS="-Wall -Werror"
392
393 The content of MPICH_MAKE_CFLAGS is appended to the CFLAGS in all
394 relevant Makefiles.
395
396 -------------------------------------------------------------------------
397
398 4. Alternate Channels and Devices
399 =================================
400
401 The communication mechanisms in MPICH are called "devices". MPICH
402 supports ch3 (default) and ch4 (experimental), as well as many
403 third-party devices that are released and maintained by other
404 institutes.
405
406                    *************************************
407
408 ch3 device
409 **********
410 The ch3 device contains different internal communication options
411 called "channels". We currently support nemesis (default) and sock
412 channels.
413
414 nemesis channel
415 ---------------
416 Nemesis provides communication using different networks (tcp, mx) as
417 well as various shared-memory optimizations. To configure MPICH with
418 nemesis, you can use the following configure option:
419
420   --with-device=ch3:nemesis
421
422 The TCP network module gets configured in by default. To specify a
423 different network module such as MX, you can use:
424
425   --with-device=ch3:nemesis:mx
426
427 If the MX include files and libraries are not in the normal search
428 paths, you can specify them with the following options:
429
430   --with-mx-include= and --with-mx-lib=
431
432 ... or the if lib/ and include/ are in the same directory, you can use
433 the following option:
434
435   --with-mx=
436
437 If the MX libraries are shared libraries, they need to be in the
438 shared library search path. This can be done by adding the path to
439 /etc/ld.so.conf, or by setting the LD_LIBRARY_PATH variable in your
440 .bashrc (or .tcshrc) file.  It's also possible to set the shared
441 library search path in the binary. If you're using gcc, you can do
442 this by adding
443
444   LD_LIBRARY_PATH=/path/to/lib
445
446   (and)
447
448   LDFLAGS="-Wl,-rpath -Wl,/path/to/lib"
449
450 ... as arguments to configure.
451
452 By default, MX allows for only eight endpoints per node causing
453 ch3:nemesis:mx to give initialization errors with greater than 8
454 processes on the same node (this is an MX error and not an inherent
455 limitation in the MPICH/Nemesis design). If needed, this can be set
456 to a higher number when MX is loaded. We recommend the user to contact
457 help@myri.com for details on how to do this.
458
459 Shared-memory optimizations are enabled by default to improve
460 performance for multi-processor/multi-core platforms. They can be
461 disabled (at the cost of performance) either by setting the
462 environment variable MPICH_NO_LOCAL to 1, or using the following
463 configure option:
464
465   --enable-nemesis-dbg-nolocal
466
467 The --with-shared-memory= configure option allows you to choose how
468 Nemesis allocates shared memory.  The options are "auto", "sysv", and
469 "mmap".  Using "sysv" will allocate shared memory using the System V
470 shmget(), shmat(), etc. functions.  Using "mmap" will allocate shared
471 memory by creating a file (in /dev/shm if it exists, otherwise /tmp),
472 then mmap() the file.  The default is "auto". Note that System V
473 shared memory has limits on the size of shared memory segments so
474 using this for Nemesis may limit the number of processes that can be
475 started on a single node.
476
477 mxm network module
478 ``````````````````
479 The mxm netmod provides support for Mellanox InfiniBand adapters.  It
480 can be built with the following configure option:
481
482   --with-device=ch3:nemesis:mxm
483
484 If your MXM library is installed in a non-standard location, you might
485 need to help configure find it using the following configure option
486 (assuming the libraries are present in /path/to/mxm/lib and the
487 include headers are present in /path/to/mxm/include):
488
489   --with-mxm=/path/to/mxm
490
491 (or)
492
493   --with-mxm-lib=/path/to/mxm/lib
494   --with-mxm-include=/path/to/mxm/include
495
496 By default, the mxm library throws warnings when the system does not
497 enable certain features that might hurt performance.  These are
498 important warnings that might cause performance degradation on your
499 system.  But you might need root privileges to fix some of them.  If
500 you would like to disable such warnings, you can set the MXM log level
501 to "error" instead of the default "warn" by using:
502
503   MXM_LOG_LEVEL=error
504   export MXM_LOG_LEVEL
505
506
507 portals4 network module
508 ```````````````````````
509 The portals4 netmod provides support for the Portals 4 network
510 programming interface. To enable, configure with the following option:
511
512   --with-device=ch3:nemesis:portals4
513
514 If the Portals 4 include files and libraries are not in the normal
515 search paths, you can specify them with the following options:
516
517   --with-portals4-include= and --with-portals4-lib=
518
519 ... or the if lib/ and include/ are in the same directory, you can use
520 the following option:
521
522   --with-portals4=
523
524 If the Portals libraries are shared libraries, they need to be in the
525 shared library search path. This can be done by adding the path to
526 /etc/ld.so.conf, or by setting the LD_LIBRARY_PATH variable in your
527 environment. It's also possible to set the shared library search path
528 in the binary. If you're using gcc, you can do this by adding
529
530   LD_LIBRARY_PATH=/path/to/lib
531
532   (and)
533
534   LDFLAGS="-Wl,-rpath -Wl,/path/to/lib"
535
536 ... as arguments to configure.
537
538 Currently, use of MPI_ANY_SOURCE and MPI dynamic processes are unsupported
539 with the portals4 netmod.
540
541 ofi network module
542 ```````````````````
543 The ofi netmod provides support for the OFI network programming interface.
544 To enable, configure with the following option:
545
546   --with-device=ch3:nemesis:ofi
547
548 If the OFI include files and libraries are not in the normal search paths,
549 you can specify them with the following options:
550
551   --with-ofi-include= and --with-ofi-lib=
552
553 ... or the if lib/ and include/ are in the same directory, you can use
554 the following option:
555
556   --with-ofi=
557
558 If the OFI libraries are shared libraries, they need to be in the
559 shared library search path. This can be done by adding the path to
560 /etc/ld.so.conf, or by setting the LD_LIBRARY_PATH variable in your
561 environment. It's also possible to set the shared library search path
562 in the binary. If you're using gcc, you can do this by adding
563
564   LD_LIBRARY_PATH=/path/to/lib
565
566   (and)
567
568   LDFLAGS="-Wl,-rpath -Wl,/path/to/lib"
569
570 ... as arguments to configure.
571
572
573 sock channel
574 ------------
575 sock is the traditional TCP sockets based communication channel. It
576 uses TCP/IP sockets for all communication including intra-node
577 communication. So, though the performance of this channel is worse
578 than that of nemesis, it should work on almost every platform. This
579 channel can be configured using the following option:
580
581   --with-device=ch3:sock
582
583
584 ch4 device
585 **********
586 The ch4 device contains different network and shared memory modules
587 for communication. We currently support the ofi and ucx network
588 modules, and posix shared memory module.
589
590 ofi network module
591 ```````````````````
592 The ofi netmod provides support for the OFI network programming interface.
593 To enable, configure with the following option:
594
595   --with-device=ch4:ofi
596
597 If the OFI include files and libraries are not in the normal search paths,
598 you can specify them with the following options:
599
600   --with-libfabric-include= and --with-libfabric-lib=
601
602 ... or the if lib/ and include/ are in the same directory, you can use
603 the following option:
604
605   --with-libfabric=
606
607 ucx network module
608 ``````````````````
609 The ucx netmod provides support for the Unified Communication X
610 library. It can be built with the following configure option:
611
612   --with-device=ch4:ucx
613
614 If the UCX include files and libraries are not in the normal search paths,
615 you can specify them with the following options:
616
617   --with-ucx-include= and --with-ucx-lib=
618
619 ... or the if lib/ and include/ are in the same directory, you can use
620 the following option:
621
622   --with-ucx=
623
624 By default, the UCX library throws warnings when the system does not
625 enable certain features that might hurt performance.  These are
626 important warnings that might cause performance degradation on your
627 system.  But you might need root privileges to fix some of them.  If
628 you would like to disable such warnings, you can set the UCX log level
629 to "error" instead of the default "warn" by using:
630
631   UCX_LOG_LEVEL=error
632   export UCX_LOG_LEVEL
633
634 -------------------------------------------------------------------------
635
636 5. Alternate Process Managers
637 =============================
638
639 hydra
640 -----
641 Hydra is the default process management framework that uses existing
642 daemons on nodes (e.g., ssh, pbs, slurm, sge) to start MPI
643 processes. More information on Hydra can be found at
644 http://wiki.mpich.org/mpich/index.php/Using_the_Hydra_Process_Manager
645
646 gforker
647 -------
648 gforker is a process manager that creates processes on a single
649 machine, by having mpiexec directly fork and exec them. gforker is
650 mostly meant as a research platform and for debugging purposes, as it
651 is only meant for single-node systems.
652
653 slurm
654 -----
655 SLURM is an external process manager not distributed with
656 MPICH. MPICH's default process manager, hydra, has native support
657 for slurm and you can directly use it in slurm environments (it will
658 automatically detect slurm and use slurm capabilities). However, if
659 you want to use the slurm provided "srun" process manager, you can use
660 the "--with-pmi=slurm --with-pm=no" option with configure. Note that
661 the "srun" process manager that comes with slurm uses an older PMI
662 standard which does not have some of the performance enhancements that
663 hydra provides in slurm environments.
664
665 -------------------------------------------------------------------------
666
667 6. Alternate Configure Options
668 ==============================
669
670 MPICH has a number of other features. If you are exploring MPICH as
671 part of a development project, you might want to tweak the MPICH
672 build with the following configure options. A complete list of
673 configuration options can be found using:
674
675    ./configure --help
676
677 -------------------------------------------------------------------------
678
679 7. Testing the MPICH installation
680 ==================================
681
682 To test MPICH, we package the MPICH test suite in the MPICH
683 distribution. You can run the test suite using:
684
685      make testing
686
687 The results summary will be placed in test/summary.xml
688
689 -------------------------------------------------------------------------
690
691 8. Fault Tolerance
692 ==================
693
694 MPICH has some tolerance to process failures, and supports
695 checkpointing and restart. 
696
697 Tolerance to Process Failures
698 -----------------------------
699
700 The features described in this section should be considered
701 experimental.  Which means that they have not been fully tested, and
702 the behavior may change in future releases. The below notes are some
703 guidelines on what can be expected in this feature:
704
705  - ERROR RETURNS: Communication failures in MPICH are not fatal
706    errors.  This means that if the user sets the error handler to
707    MPI_ERRORS_RETURN, MPICH will return an appropriate error code in
708    the event of a communication failure.  When a process detects a
709    failure when communicating with another process, it will consider
710    the other process as having failed and will no longer attempt to
711    communicate with that process.  The user can, however, continue
712    making communication calls to other processes.  Any outstanding
713    send or receive operations to a failed process, or wildcard
714    receives (i.e., with MPI_ANY_SOURCE) posted to communicators with a
715    failed process, will be immediately completed with an appropriate
716    error code.
717
718  - COLLECTIVES: For collective operations performed on communicators
719    with a failed process, the collective would return an error on
720    some, but not necessarily all processes. A collective call
721    returning MPI_SUCCESS on a given process means that the part of the
722    collective performed by that process has been successful.
723
724  - PROCESS MANAGER: If used with the hydra process manager, hydra will
725    detect failed processes and notify the MPICH library.  Users can
726    query the list of failed processes using MPIX_Comm_group_failed().
727    This functions returns a group consisting of the failed processes
728    in the communicator.  The function MPIX_Comm_remote_group_failed()
729    is provided for querying failed processes in the remote processes
730    of an intercommunicator.
731
732    Note that hydra by default will abort the entire application when
733    any process terminates before calling MPI_Finalize.  In order to
734    allow an application to continue running despite failed processes,
735    you will need to pass the -disable-auto-cleanup option to mpiexec.
736
737  - FAILURE NOTIFICATION: THIS IS AN UNSUPPORTED FEATURE AND WILL
738    ALMOST CERTAINLY CHANGE IN THE FUTURE!
739
740    In the current release, hydra notifies the MPICH library of failed
741    processes by sending a SIGUSR1 signal.  The application can catch
742    this signal to be notified of failed processes.  If the application
743    replaces the library's signal handler with its own, the application
744    must be sure to call the library's handler from it's own
745    handler.  Note that you cannot call any MPI function from inside a
746    signal handler.
747
748 Checkpoint and Restart
749 ----------------------
750
751 MPICH supports checkpointing and restart fault-tolerance using BLCR.
752
753 CONFIGURATION
754
755 First, you need to have BLCR version 0.8.2 or later installed on your
756 machine.  If it's installed in the default system location, you don't
757 need to do anything.
758
759 If BLCR is not installed in the default system location, you'll need
760 to tell MPICH's configure where to find it. You might also need to
761 set the LD_LIBRARY_PATH environment variable so that BLCR's shared
762 libraries can be found.  In this case add the following options to
763 your configure command:
764
765   --with-blcr=<BLCR_INSTALL_DIR> 
766   LD_LIBRARY_PATH=<BLCR_INSTALL_DIR>/lib
767
768 where <BLCR_INSTALL_DIR> is the directory where BLCR has been
769 installed (whatever was specified in --prefix when BLCR was
770 configured).
771
772 After it's configured compile as usual (e.g., make; make install).
773
774 Note, checkpointing is only supported with the Hydra process manager.
775
776
777 VERIFYING CHECKPOINTING SUPPORT
778
779 Make sure MPICH is correctly configured with BLCR. You can do this
780 using:
781
782   mpiexec -info
783
784 This should display 'BLCR' under 'Checkpointing libraries available'.
785
786
787 CHECKPOINTING THE APPLICATION
788
789 There are two ways to cause the application to checkpoint. You can ask
790 mpiexec to periodically checkpoint the application using the mpiexec
791 option -ckpoint-interval (seconds):
792
793   mpiexec -ckpointlib blcr -ckpoint-prefix /tmp/app.ckpoint \
794       -ckpoint-interval 3600 -f hosts -n 4 ./app
795
796 Alternatively, you can also manually force checkpointing by sending a
797 SIGUSR1 signal to mpiexec.
798
799 The checkpoint/restart parameters can also be controlled with the
800 environment variables HYDRA_CKPOINTLIB, HYDRA_CKPOINT_PREFIX and
801 HYDRA_CKPOINT_INTERVAL.
802
803 To restart a process:
804
805   mpiexec -ckpointlib blcr -ckpoint-prefix /tmp/app.ckpoint -f hosts -n 4 -ckpoint-num <N>
806
807 where <N> is the checkpoint number you want to restart from.
808
809 These instructions can also be found on the MPICH wiki:
810
811   http://wiki.mpich.org/mpich/index.php/Checkpointing
812
813 -------------------------------------------------------------------------
814
815 9. Developer Builds
816 ===================
817 For MPICH developers who want to directly work on the primary version
818 control system, there are a few additional steps involved (people
819 using the release tarballs do not have to follow these steps). Details
820 about these steps can be found here:
821 http://wiki.mpich.org/mpich/index.php/Getting_And_Building_MPICH
822
823 -------------------------------------------------------------------------
824
825 10. Multiple Fortran compiler support
826 =====================================
827
828 If the C compiler that is used to build MPICH libraries supports both
829 multiple weak symbols and multiple aliases of common symbols, the
830 Fortran binding can support multiple Fortran compilers. The
831 multiple weak symbols support allow MPICH to provide different name
832 mangling scheme (of subroutine names) required by differen Fortran
833 compilers. The multiple aliases of common symbols support enables
834 MPICH to equal different common block symbols of the MPI Fortran
835 constant, e.g. MPI_IN_PLACE, MPI_STATUS_IGNORE. So they are understood
836 by different Fortran compilers.
837
838 Since the support of multiple aliases of common symbols is
839 new/experimental, users can disable the feature by using configure
840 option --disable-multi-aliases if it causes any undesirable effect,
841 e.g. linker warnings of different sizes of common symbols, MPIFCMB*
842 (the warning should be harmless).
843
844 We have only tested this support on a limited set of
845 platforms/compilers.  On linux, if the C compiler that builds MPICH is
846 either gcc or icc, the above support will be enabled by configure.  At
847 the time of this writing, pgcc does not seem to have this multiple
848 aliases of common symbols, so configure will detect the deficiency and
849 disable the feature automatically.  The tested Fortran compilers
850 include GNU Fortran compilers (gfortan), Intel Fortran compiler
851 (ifort), Portland Group Fortran compilers (pgfortran), Absoft Fortran
852 compilers (af90), and IBM XL fortran compiler (xlf).  What this means
853 is that if mpich is built by gcc/gfortran, the resulting mpich library
854 can be used to link a Fortran program compiled/linked by another
855 fortran compiler, say pgf90, say through mpifort -fc=pgf90.  As long
856 as the Fortran program is linked without any errors by one of these
857 compilers, the program shall be running fine.
858
859 -------------------------------------------------------------------------
860
861 11. ABI Compatibility
862 =====================
863
864 The MPICH ABI compatibility initiative was announced at SC 2014
865 (http://www.mpich.org/abi).  As a part of this initiative, Argonne,
866 Intel, IBM and Cray have committed to maintaining ABI compatibility
867 with each other.
868
869 As a first step in this initiative, starting with version 3.1, MPICH
870 is binary (ABI) compatible with Intel MPI 5.0.  This means you can
871 build your program with one MPI implementation and run with the other.
872 Specifically, binary-only applications that were built and distributed
873 with one of these MPI implementations can now be executed with the
874 other MPI implementation.
875
876 Some setup is required to achieve this.  Suppose you have MPICH
877 installed in /path/to/mpich and Intel MPI installed in /path/to/impi.
878
879 You can run your application with mpich using:
880
881    % export LD_LIBRARY_PATH=/path/to/mpich/lib:$LD_LIBRARY_PATH
882    % mpiexec -np 100 ./foo
883
884 or using Intel MPI using:
885
886    % export LD_LIBRARY_PATH=/path/to/impi/lib:$LD_LIBRARY_PATH
887    % mpiexec -np 100 ./foo
888
889 This works irrespective of which MPI implementation your application
890 was compiled with, as long as you use one of the MPI implementations
891 in the ABI compatibility initiative.
892
893 -------------------------------------------------------------------------
894
895 12. Capability Sets
896 =====================
897
898 The CH4 device contains a feature called "capability sets" to simplify
899 configuration of MPICH on systems using the OFI netmod. This feature
900 configures MPICH to use a predetermined set of OFI features based on the
901 provider being used. Capability sets can be configured at compile time or
902 runtime. Compile time configuration provides better performance by
903 reducing unnecessary code branches, but at the cost of flexibility.
904
905 To configure at compile time, the device string should be amended to include
906 the OFI provider with the following option:
907
908     --with-device=ch4:ofi:sockets
909
910 This will setup the OFI netmod to use the optimal configuration for the
911 sockets provider, and will set various compile time constants. These settings
912 cannot be changed at runtime.
913
914 If runtime configuration is needed, continue to use the device string as before
915 (without the OFI provider extension) and set various environment variables to
916 achieve a similar configuration. To select the desired provider:
917
918     % export MPIR_CVAR_OFI_USE_PROVIDER=sockets
919
920 This will select the OFI provider and the associated MPICH capability set. To
921 change the preset configuration, there exists an extended set of environment
922 variables. As an example, the immediate data fields can be disabled by using
923 the environment variable:
924
925     % export MPIR_CVAR_OFI_ENABLE_DATA=0
926
927 A full list of capability set configuration variables can be found in the
928 environment variables README.envvar.
929
930 -------------------------------------------------------------------------
931
932 13. Threads
933 ===========
934
935 MPICH supports multiple threading packages.  The default is posix
936 threads (pthreads), but solaris threads, windows threads and argobots
937 are also supported.
938
939 To configure mpich to work with argobots threads, use the following
940 configure options:
941
942     --with-thread-package=argobots \
943         CFLAGS="-I<path_to_argobots/include>" \
944         LDFLAGS="-L<path_to_argobots/lib>"