Skip to content

Commit 0f988ad

Browse files
committed
Add FAQ.md frequently asked questions file.
1 parent 16ebe99 commit 0f988ad

File tree

1 file changed

+109
-0
lines changed

1 file changed

+109
-0
lines changed

FAQ.md

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

0 commit comments

Comments
 (0)