Skip to content

Commit d6e1fda

Browse files
zbeekmanzbeekman
authored
Merge branch 'master' into nc-fix
2 parents 1ad0806 + 74a2250 commit d6e1fda

File tree

1 file changed

+140
-0
lines changed

1 file changed

+140
-0
lines changed

‎FAQ.md

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
Frequently Asked Questions
2+
==========================
3+
4+
* [1. I have installed OpenCoarrays with OpenMPI but I'm having trouble running with more than a few images, why?]
5+
* [2. I have installed OpenCoarrays with a recent version of OpenMPI, but my Coarray Fortran programs won't run when launched with cafrun, why?]
6+
* [3. `install.sh` is trying to download and install GCC/GFortran and its prerequisites, but I want to use GCC version X already present on my system, how can I do this?]
7+
* [4. How can I uninstall OpenCoarrays?]
8+
* [5. OpenCoarrays was built with MPICH as the MPI back end, but I am running into bugs, what should I do?]
9+
* [6. How can I pass additional flags through to the underlying parallel run-time or compiler?]
10+
* [7. When `install.sh` builds the GCC compilers, it takes forever (hours). How can I speed up the build?]
11+
12+
## 1. I have installed OpenCoarrays with OpenMPI but I'm having trouble running with more than a few images, why? ##
13+
14+
OpenMPI requires oversubscribed jobs (more MPI ranks/coarray
15+
images than logical CPU cores available) to pass the
16+
`--oversubscribe` flag to `mpirun`. To run a Coarray program with
17+
more images than available logical CPU cores, please pass
18+
`--oversubscribe` as an argument to the `cafrun` wrapper
19+
script. `cafrun` will pass any additional flags through to the
20+
underlying run-time launcher (i.e., `mpirun`). Here is an example
21+
invocation of `cafrun` demonstrating this procedure:
22+
23+
```
24+
cafrun -np 32 --oversubscribe ./a.out <arg1> <arg2>
25+
```
26+
27+
## 2. I have installed OpenCoarrays with a recent version of OpenMPI, but my Coarray Fortran programs won't run when launched with `cafrun`, why? ##
28+
29+
Recent versions of OpenMPI require a hostfile to be used,
30+
specifying the number of "slots" (i.e., logical CPU cores)
31+
available on each node or host on the system. If you are running
32+
OpenCoarrays on a production HPC system, your system
33+
administrator should have configured OpenMPI with a default hosts
34+
file or should provide instructions on how to generate your
35+
own. If you are running OpenCoarrays on a shared memory machine,
36+
such as a laptop, desktop, or workstation, then you may have to
37+
provide your own hostfile. On a shared memory machine, this
38+
hostfile should look something like:
39+
40+
```
41+
hostname.local 8
42+
```
43+
44+
where `hostname` is the hostname of the machine you are running on
45+
and `8` is the number of logical CPU cores. On a Macbook Pro (late
46+
2013) with a 4 core Intel core i7 CPU with two hyper threads per
47+
core, 8 is the number of logical CPU cores. When OpenCoarrays is
48+
configured and installed, if OpenMPI is detected a hostfile is
49+
created in the build directory for use when running the test
50+
suite. (This hostfile corresponds to the machine/node used to
51+
configure OpenCoarrays using CMake.) If you installed OpenCoarrays
52+
via the [`install.sh`] script, then it will be located at
53+
`./prerequisites/builds/opencoarrays/<version>/hostfile` or if you
54+
invoked CMake yourself it should be in the top level of your build
55+
directory at `/path/to/build/dir/hostfile`. (You must run CMake
56+
first, to create this file.)
57+
58+
## 3. `install.sh` is trying to download and install GCC/GFortran and its prerequisites, but I want to use GCC version X already present on my system, how can I do this? ##
59+
60+
[`install.sh`] defaults to trying to install the most recent stable
61+
version of GFortran and GCC that has the best functionality with
62+
OpenCoarrays. This is usually the latest stable version of
63+
GCC/GFortran, however, sometimes regressions are present and a
64+
slightly older version is set as the default until most of the serious
65+
regressions are resolved. If you know what you are doing and wish to
66+
use a different Fortran/C compiler, you can explicitly pass arguments
67+
to [`install.sh`] to specify which compilers to use. Please see the
68+
usage information for [`install.sh`] by invoking it with the `--help`
69+
flag. For example, the `-f` or `--with-fortran` flag is passed with
70+
the path to the desired Fortran compiler, the `-c` or `--with-c` flag
71+
is passed with the path to the desired C compiler and the `-C` or
72+
`--with-cxx` flag is passed with the path to the desired C++
73+
compiler. Alternatively the "Developer/quick-start instructions"
74+
(located in the [`INSTALL`] file) may be followed to perform the
75+
installation using CMake directly, without calling [`install.sh`]. The
76+
compilers are specified using the `FC`, `CC` and `CXX` environment
77+
variables, and all prerequisites (GFortran, CMake, and a suitable MPI
78+
implementation) are assumed to be already installed on the system. If
79+
you pass one compiler-specification argument (e.g., `-f`), it is best
80+
to pass all three (e.g., `-f`, `-c`, and `-C`) to ensure consistency.
81+
82+
## 4. How can I uninstall OpenCoarrays? ##
83+
84+
After installing OpenCoarrays, you can enter the build directory
85+
(`prerequisites/builds/opencoarrays/<version>` if installed via
86+
[`install.sh`]) and run `make uninstall`. A script or additional flag
87+
to [`install.sh`] is planned to automate this process, but has yet to
88+
be implemented. When OpenCoarrays is installed a file manifest is
89+
written in this build directory, so you can examine which files get
90+
installed and their locations on your system.
91+
92+
## 5. OpenCoarrays was built with MPICH as the MPI back end, but I am running into bugs, what should I do? ##
93+
94+
There is a bug in MPICH that, as of this writing, is patched, but is
95+
not yet in a stable release. This bug effects the failed images
96+
functionality, which can be disabled during configuration. If you
97+
encounter issues using OpenCoarrays with MPICH, reinstalling
98+
OpenCoarrays _without_ failed image support may resolve the issue. To
99+
do so you will have to perform a manual CMake configuration and
100+
installation as described in the "Developer/quick start" installation
101+
guide documented in the file [`INSTALL`]. Please pass the
102+
`-DCAF_ENABLE_FAILED_IMAGES=FALSE` flag to CMake when configuring
103+
OpenCoarrays. If this doesn't resolve your issue, please file a
104+
[new issue].
105+
106+
## 6. How can I pass additional flags through to the underlying parallel run-time or compiler? ##
107+
108+
The `caf` compiler wrapper script and the `cafrun` Coarray Fortran
109+
program launch script will both pass additional flags through to
110+
the underlying compiler and parallel run-time job launcher,
111+
respectively. Specify the additional flags to be passed to
112+
GFortran or `mpirun` after any flags specific to `caf` or `cafrun`
113+
such as the `-s` flag to show the underlying command, or the `-np <N>`
114+
flag to specify the number of images in the `cafrun` script and before
115+
any files such as Fortran source files or Coarray Fortran executables.
116+
117+
## 7. When `install.sh` builds the GCC compilers, it takes forever (hours). How can I speed up the build? ##
118+
119+
To increase the odds of success, `install.sh` defaults to a GCC
120+
bootstrap build, which builds a minimal compiler to build the ultimate
121+
compiler (not every version of GCC can build every other version of
122+
GCC). For a much faster build process that has a somewhat higher
123+
chance of failing, pass the `--disable-bootstrap` or `-z` argument and
124+
use more threads by passing, for example, `--num-threads -4` or `-j 4`
125+
to use four threads. In combination, these two recommendations can
126+
decrease the GCC build time from several hours to 15 or fewer minutes.
127+
128+
129+
[`install.sh`]: https://github.com/sourceryinstitute/OpenCoarrays/blob/master/install.sh
130+
[`INSTALL']: https://github.com/sourceryinstitute/OpenCoarrays/blob/master/INSTALL
131+
[new issue]: https://github.com/sourceryinstitute/OpenCoarrays/issues/new
132+
133+
[TOC links]: #
134+
[1. I have installed OpenCoarrays with OpenMPI but I'm having trouble running with more than a few images, why?]: #1-i-have-installed-opencoarrays-with-openmpi-but-im-having-trouble-running-with-more-than-a-few-images-why
135+
[2. I have installed OpenCoarrays with a recent version of OpenMPI, but my Coarray Fortran programs won't run when launched with cafrun, why?]: #2-i-have-installed-opencoarrays-with-a-recent-version-of-openmpi-but-my-coarray-fortran-programs-wont-run-when-launched-with-cafrun-why
136+
[3. `install.sh` is trying to download and install GCC/GFortran and its prerequisites, but I want to use GCC version X already present on my system, how can I do this?]: #3-installsh-is-trying-to-download-and-install-gccgfortran-and-its-prerequisites-but-i-want-to-use-gcc-version-x-already-present-on-my-system-how-can-i-do-this
137+
[4. How can I uninstall OpenCoarrays?]: #4-how-can-i-uninstall-opencoarrays
138+
[5. OpenCoarrays was built with MPICH as the MPI back end, but I am running into bugs, what should I do?]: #5-opencoarrays-was-built-with-mpich-as-the-mpi-back-end-but-i-am-running-into-bugs-what-should-i-do
139+
[6. How can I pass additional flags through to the underlying parallel run-time or compiler?]: #6-how-can-i-pass-additional-flags-through-to-the-underlying-parallel-run-time-or-compiler
140+
[7. When `install.sh` builds the GCC compilers, it takes forever (hours). How can I speed up the build?]: #7-when-installsh-builds-the-gcc-compilers-it-takes-forever-hours--how-can-i-speed-up-the-build

0 commit comments

Comments
 (0)