Installation (Up/ Prev) Installing Dependencies: GSL and FFTW (Next)

PSCF is distributed only as source code, and so must be compiled by the user. All C++ source code follows the ANSI 2011 C++ language standard. Code that uses an NVIDIA (GPU) is written in CUDA.

PSCF is designed to be compiled and run in a unix-like environment. The package has been tested and used on systems running either linux or recent versions of the Mac OS X operating systems. PSCF can take advantage of a CUDA-capable Nvidia GPU if one is available, or can run on standard CPU hardware. Compilation is controlled by a system of unix makefiles.

Overview

PSCF currently contains code for two programs that are designed to run on a conventional CPU (pscf_r1d and pscf_rpg), and one that is designed to use an NVIDIA GPU (pscf_rpg). We distinguish these in what follows by referring to CPU programs and a GPU-enabled program.

In order to compile just the two CPU programs in the PSCF package, the system on which the code is compiled and run must have:

a git version control client
a C++ compiler
a Python interpreter, version 3 or greater
the GNU Scientific Library (GSL) (header and library)
the FFTW fast Fourier transform library (header and library)

A git client is needed to obtain the source code, by cloning the git repository in which PSCF is maintained on the github.com site. A Python interpreter is needed during compilation because the build system that compiles PSCF uses several Python scripts that are provided within the PSCF repository. A git client, C++ compiler and Python interpreter will all normally come pre-installed in common linux distributions or in a Mac OS operating system in which command line tools have been installed. The GNU scientific library is used by several programs within the package for linear algebra operations. The FFTW fast Fourier transform library is used extensively by the pscf_rpc programs for periodic microstructures.

In order to compile the GPU-enabled pscf_rpg program, the user's system must also have:

a CUDA-enabled NVIDIA graphics card
the NVIDIA CUDA Toolkit

The CUDA Toolkit is a development environment that provides the nvcc C++/CUDA compiler and a variety of GPU-accelerated libraries, including the cuFFT fast Fourier transform library.

Users who wish to generate a local copy of this web manual, as a set of html pages that reside on the user's computer, will also need to install the "doxygen" documentation utility.

Mac XCode command line tools

In order to compile the PSCF CPU programs in Mac OS X, the user's operating system must first be configured to provide a unix command-line development environment. This can be done by installing the Mac Command Line Tools package for XCode. In recent versions of Mac OS X, it is not necessary to install the large XCode integrated development environment (IDE) to obtain just the much smaller set of command line tools. The full XCode environment is not needed to compile and use PSCF.

To install just the command line tools, follow the instructions given here. Briefly, the instructions are to:

Launch the Terminal application, found in the Applications/Utilities folder
From a terminal, type the command string: "xcode-select --install"

This will a open a software update window that contains the following text: "The xcode-select command requires the command line developer tools. Would you like to install the tools now?" Confirm by clicking the "Install" button on this window. When prompted, also agree to the Terms of Service. The package will then download and install.

If you choose to install the full XCode package from the Apple App store, installation of the Command Line Tools is offered as an option during the installation process, which you should accept.

To use PSCF on a Mac, you must type commands from a terminal window, as in a traditional unix command line environment. Mac users may thus want to add the Terminal app to their Dock for easy access.

Searching for executable files

In the following instructions, we recommend that users use the unix "command -v" built in shell command to check whether several required executable files are installed on their system. This command takes the name of an executable command an argument and, if possible, returns the full path to a corresponding executable file of that name. For example, on systems on which the g++ command invokes a C++ compiler, invoking

command -v g++

from a command line will normally return a path such as "/usr/bin/g++". This is the full path to the "g++" executable file, if one is found. The unix shell searches for executable files in a list of directories that are listed by the PATH environment variable. If the operating system cannot find a command of the specified name in this list of directories, then "command -v" instead returns nothing.

The "which" command is another utility that is essentially equivalent to "command -v", and that is also available on most unix systems. If the "which" command exists, one could invoke

which g++

as an alternate way to search for the g++ executable file. Like "command -v", this command returns a path to an executable file with a specified base name (e.g., "g++") if one is found, and returns nothing if no matching file is found.

We suggest use of "command -v" in this manual primarily because this command is required to exist by the POSIX portability standard for unix operating systems, while the "which" command is not required by POSIX. In practice, both commands exist on many unix systems, while a few variants of unix have one but not the other.

Git client

The source code for the C++/CUDA version of PSCF described here is hosted on the github server, at github.com, as project dmorse/pscfpp. The older Fortran PSCF program is maintained in a separate github repository, as project dmorse/pscf.

The source code of the current version of PSCF should be obtained by using the git version control manager to clone the public git repository, as will be described in detail elsewhere. To get the source code in this way, a git client must be installed on your computer.

One can check whether the git package is already installed by entering

git --version

from the unix command line. If git is installed and functional, this should return a git version number, such as "git version 2.30.1". One can also check that the shell can find an exectuable named "git" by entering

command -v git

and checking if this returns a valid path, such as /usr/bin/git .

Instructions for installing git on different platforms are given on the git web page, and in chapter 1.5 of the Pro Git book by Scott Chacon, which is available to be read for free online. If you are using linux, and git is not already installed, you should use the preferred package manager on your linux distribution to install a git client. If you are using Mac OS X, a git client should be installed as a part of the XCode Command Line Tools package, which is also needed by PSCF for other purposes.

Python interpeter

The system used to compile and install PSCF requires access to a Python 3 interpreter. One can check if a python interpreter is accessible by issuing the command

python3 --version

confirming that the command works, and confirming that it returns a version number 3.0 or greater. In addition, one can issue the command

command -v python3

and check that it returns a non-empty path such as /user/bin/python3.

We recommend using the command "python3" rather than "python" to make sure that you access a python 3 interpreter on any system in which a Python 2 interpreter may still also be installed. A Python 3 interpeter should be available from the command line by default in any common linux distribution (e.g., Ubuntu or Fedora), and should be installed on a Mac OS X as part of the XCode command line tools package.

C++ compiler

By default, the PSCF build system invokes a C++ compiler using the compiler command name "g++". On linux systems, this command normally invokes the GNU compiler collection (GCC) C++ compiler. On an Apple computer running Mac OS X that is configured for unix C++ development (see above), the "g++" command is normally a link to the Clang compiler, which is the default compiler for C++ development on Mac OS X. The Clang compiler accepts almost all the same command line options as the GNU compiler, and so functions as a compatible replacement for the GCC C++ compiler.

It is possible to configure the PSCF build system during the initial configuration process so as to instead use a different C++ compiler, as discussed here. Even when a different compiler command is used to compile source code, however, the PSCF build system will still invoke the "g++" command with appropriate options to analyse dependencies among source files. The PSCF makefile system thus always requires that the "g++" command be available.

One can check if the "g++" command exists by entering "command -v g++", as described above.

The name of the command used to invoke the compiler when compiling C++ files and the choices of options passed to the compiler can be changed by modifying a compiler configuration file that is read during initial configuration of the build system. The configuration process is described in more detail here.

CUDA compiler

To compile the GPU-accelerated pscf_rpg program, the system must have an appropriate NVIDIA GPU and a CUDA development toolkit installed. The NVIDIA nvcc C++/CUDA compiler is designed to integrate with the GNU g++ compiler, so we recommend using the GNU compiler to compile C++ source files if you are planning to compile CUDA code for use on the same machine.

Installation (Up / Prev) Installing Dependencies: GSL and FFTW (Next)