|
pFUnit
|
Comentatry for the page.
The development work for pFUnit has mostly been carried out on a mixture of systems, including high-end computers, Apple Mac OSX, and linux-based systems. A preliminary Windows/CYGWIN port has been contributed by a user. Full use of the system depends on the following being available.
Note: Recent changes have exposed a latent bug in GCC 4.8.2. The fix is available in the GCC 4.9 development branch and will also appear in GCC 4.8.3 when that is released. Users that require older versions of GCC should use pFUnit 2.1.x.
Doxygen is used to generate documentation.
The system routinely undergoes regression testing with GNU, Intel, and NAG fortran compilers and OpenMPI.
The best way to obtain pFUnit is to clone pFUnit from the git repository from SourceForge as follows.
This will create the directory pFUnit in the current working directory.
You may also visit the project page at SourceForge and download the source tarfile "pFUnit.tar.gz" there.
http://sourceforge.net/projects/pfunit/ or http://sourceforge.net/projects/pfunit/files/latest/download
Extracting this tarfile via a command like
$ tar zxf ./pFUnit.tar.gz
will place the pFUnit files into the current working directory.
For other ways to acquire the code visit
https://sourceforge.net/p/pfunit/code/ci/master/tree/
or contact the pFUnit team.
In the top level of the pFUnit distribution you will see the following files.
CMakeLists.txt - Initial support for cmake-based builds.
COPYRIGHT - Contains information pertaining to the use and distribution of pFUnit.
Examples - Contains examples of how to use pFUnit once it is installed.
GNUmakefile - The top level makefile for building and installing pFUnit.
LICENSE - The NASA Open Source Agreement for GSC-15,137-1 F-UNIT, also known as pFUnit.
README-INSTALL - Basic documentation on pFUnit installation and use.
bin - Executables used to construct and perform unit tests.
include - Files to be included into makefiles or source, including use code.
source - Source code and scripts of the pFUnit library and framework.
tests - Source code for unit testing pFUnit itself.
tools - Tools used to help develop, build, and install pFUnit.
VERSION - Contains a string describing the current version of the framework.
Little needs to be done to configure pFUnit for the build, however there are several environment variables on which the package depends.
F90_VENDOR - is set to include the correct makefile in /include, i.e. GNU, Intel, NAG, or PGI. Case insensitive file systems may cause some confusion from time-to-time.
F90 - is set to the Fortran compiler being used: e.g. ifort for Intel, gfortran for GNU.
COMPILER - is set according to F90_VENDOR and is automatically set in the top level makefile.
For MPI-based unit testing, your setup may require the following as well.
MPIF90
As a convenience for working with multiple MPI configurations, you may also set the following.
MPIRUN
PFUNIT_MAX_ARRAY_RANK
PFUNIT_MAX_ARRAY_RANK - controls the maximum size of the arrays asserts are defined over. If PFUNIT_MAX_ARRAY_RANK is not set, the default is 5 and pFUnit's assertions will be able to handle arrays up to rank 5, i.e. A(:,:,:,:,:). PFUNIT_MAX_ARRAY_RANK and MAX_RANK do not refer to MPI ranks (process id within a group). Example:
PFUNIT_MAX_RANK is a deprecated way to set maximum rank and is to be removed in version 4.
DOXYGEN - To generate documentation, set DOXYGEN to the desired executable. NOTE: Doxygen Version 1.8.5 does not respect CamelCase names from Fortran source code by currently converting all to lowercase. It does this to get HTML links correct for references in the source code that also do not respect the CamelCase convention. The Fortran standard specifies case insensitivity. Doxygen 1.7.x seems to better respect CamelCase.
To build pFUnit for unit testing MPI-based codes, be sure that the environment is properly set up for the MPI implementation you are using. Depending on your local environment, you may need execute the build within a batch or other job queing system, e.g. an interactive batch job under PBS. The steps for building pFUnit start out the same as for the serial case above, but add MPI=YES to the environment to switch on MPI support. The MPI-based unit tests for pFUnit itself will run automatically. Again, occasionally a spurious (runtime) error may appear on the first execution.
Also, one may get some harmless "no symbols" warnings when the pFUnit library is constructed.
Initial (limited) support for OPENMP has been implemented. At this writing, a basic functionality is available.
The process for building pFUnit for testing OPENMP-based codes is similar to that for other paradigms.
To clean the pFUnit build directory for the space or to rebuild there are two options.
make src_clean to remove intermediate products in subdirectories.A start at documentation for pFUnit is in the documentation directory. Doxygen is our primary documentation tool. To make the documentation, which will be generated in the documentation directory, please invoke the following from the top level of your pFUnit distribution.
Or to make a reference manual.
To select a specific version of Doxygen, please set the DOXYGEN environment variable as in Configuration. You may wish to do this if your code uses CamelCase names as current versions of Doxygen (1.8.5) do not respect this convention for Fortran.
Initial support for CMAKE has been implemented. At this writing, a basic functionality is available.
One may also set the environment variable PFUNIT instead of setting INSTALL_PATH on the cmake command line as given above.
If your MPI installation does not provide mpirun, you may try to set -DMPI_USE_MPIEXEC=YES to tell CMake to use its FindMPI function to find out how to execute the tests.
To install pFUnit for regular use, set INSTALL_DIR to the location in which to place pFUnit. This can be done on the make command line. For example, after compiling pFUnit for serial use (MPI absent or MPI=NO), please try.
Note: you may need special priveleges to install in some locations, e.g. via sudo.
To test the installation set PFUNIT to INSTALL_DIR, then change the working directory to Examples in pFUnit distribution and execute "make," which will run a number of examples. These include some expected (intentional) failures.
For installing an MPI-enabled pFUnit library, change to the top of the distribution and execute make with MPI=YES. You may need to "make distclean" first. After compilation and pFUnit passes its self-tests, then installation proceeds as for the serial case above.
To test, set PFUNIT and go into Examples/MPI_Halo directory.
This will compile and run a set of parallel examples that includes intentional failures. To run all of the examples try executing "make MPI=YES" in the Examples directory.
At this time the OPENMP version of pFUnit can be installed in the same way as for the serial or MPI-parallel codes. OPENMP support, tests, and examples are limited as of this writing.
If INSTALL_DIR is not set, "make install" will attempt to install pFUnit into the top build directory. This will create directories such as lib and mod in the top level of the build directory and will overwrite the include/base.mk with include/base-install.mk. If this is not desired, then "make develop" will put back the original base.mk, which is the file to be used for development and building pFUnit. In general, we recommend installing to a directory that is not also the build directory.
1.8.13