|
| 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