Getting the Source Code (Prev) Environment Variables (Next)

Below is a brief overview of instructions for compiling all of the PSCF programs using default settings. Using git to clone the PSCF repository will create a directory named pscfpp/, which we hereafter refer to as the PSCF root directory.

Directory name conventions: Here and herafter, a backslash after a name is used to indicate that a string is the name of a directory. In what follows, we also often use PSCF as an adjective when specifying a directory name to indicate a directory within the PSCF directory tree that is specified by a path relative to the PSCF root directory. For example, the "PSCF src/ directory" thus refers to the src/ subdirectory of the PSCF root directory.

Below, have divided the instructions into a set of instructions for compiling and installing the programs that use only CPU hardware, and additional instructions for compiling programs that use an NVIDIA GPU.

Preliminary steps

The following steps must be taken before attempting to compile any part of the PSCF package. The first two steps have been described in previous pages:

Install dependencies: This was previously discussed here
Clone source code repository: This was previously discussed here
Set environment variables: Modify the users PATH and PYTHONPATH unix environment variables so as to include PSCF bin/ directory (i.e., the bin/ subdiretory of the PSCF root directory) in the PATH (the unix shell command search path) and so as to include PSCF lib/python directory in the PYTHONPATH (the Python module search path). This is discussed in greater detail here.
Navigate to root directory: Change directory (cd) to the PSCF root directory.
Configure: Invoke the "configure" script from the PSCF root directory. To configure the build system with default compiler options appropriate to most linux or Mac OS X systems, enter the command
./configure

from the root directory. Note the use of the prefix "./" before the name of the script, which indicates that the operating system should look for this script in the present working directory.

To customize compiler options, one may also invoke the configure script with a filename argument that is the name of a user-defined compiler configuration file. The creation and use of such a custom configuration file is discussed in detail here.

Compiling C++ code (CPU hardware)

We recommend that users first attempt to compile only the pscf_1d and pscf_pc CPU programs, leaving compilation of the GPU-enabled pscf_pg program as a separate step.

Compilation of GPU-enabled code is disabled by default. To compile only the pscf_1d and pscf_pc CPU programs, you may simply enter

make all

from the PSCF directory immediately after running the configure script. If successful, this will install executables named "pscf_1d" and "pscf_pc" in the PSCF bin/ directory.

Compiling all the PSCF C++ code using "make all" takes a bit of time (e.g., 2 to 3 minutes on a 2020 Mac air laptop with an M1 chip). This can be completed more quickly on a multi-core machine by using the -j option of the "make" command to use multiple CPU cores in parallel to compile different C++ files. The argument of the -j option is the number of cores that should be used, if available. For example, you could enter

make -j8 all

to use all 8 CPU cores of an 8-core computer to compile.

Entering "make all" or "make -jn all" from the PSCF root directory, as described above, will create a large number of intermediate object (*.o), dependency (*.d) and library (*.a) files in subdirectories of the PSCF bld/ directory, in addition to the executable files that are created in the PSCF bin/ directory.

Compiling CUDA C++ Code (GPU hardware)

The GPU-enabled pscf_pg program can only be compiled on computers that have an NVIDIA CUDA development kit installed, and can only be run on machines that have an appropriate CUDA-capable NVIDIA GPU and CUDA driver software installed. Before compiling pscf_pg, the user must first enable compilation of CUDA code and set the appropriate target GPU architecture, as described below. The following instructions assume that you have already completed the preliminary steps described above.

Enable compilation of GPU-enabled programs: To enable compilation of CUDA code for GPU-enabled programs on a machine that is set up to allow this, enter
./setopts -c1

from the PSCF root directory. If you later want to disable compilation of CUDA code, instead enter
./setopts -c0

Commands issued by the setops script set variables that affect subsequent behavior of the build system and compiler. Usage of the setopts script is discussed in more detail here.

To check if CUDA compilation is currently enabled, change directory to the PSCF bld/ directory, and enter
./setopts -q

from that directory. This should yield a report that indicates (among other things) whether the "CUDA" options is currently set to be enabled (ON) or disabled (OFF) for code built in the bld/ directory (the default build directory).
Set the target GPU architecture: CUDA must be compiled for a particular target GPU architecture. To set the target architecture to correspond to the GPU on your computer, you must change directory to PSCF root directory and issue a command of the form
./setopts -a [architecture id]

where [architecture id] denotes a string that identifies the architecture of the GPU for which you are compiling. Valid values of this string have the form "sm_IJ", where IJ denotes a integer string that represents the NVIDIA "compute capability" for the target GPU. You can look up the compute capabability for the type of NVIDIA GPU installed on your computer by consulting the NVIDIA developer documentation. The compute capability for an NVIDIA GPU is a number of the form I.J in which I is an integer major version number and J is a minor version number. The architecture id required as an argument of the -a option, however, uses a string of the form sm_IJ that drops the dot between the major and minor version.

For example, an NVIDIA V100 GPU has a compute capability of 70. To set this as the target architecture, one would enter
./setopts -a sm_70

from the PSCF root directory, using "sm_70" as the architecture id.
Compile all programs (including pscf_pg): After enabling CUDA compilation and setting the appropriate architecture, you can compile all programs, including pscf_pg, by simply re-entering
make all

from within the PSCF root directory. As when compiling pure C++ code, one may use multiple cores to compile by instead entering "make -jn all", where "n" is the number of CPU cores to be used.

If successful, the "make all" command will install an executable file named pscf_pg in the PSCF bin/ directory in addition to the files named pscf_1d and pscf_pc that are created by compiling only C++ code.

Several of the above steps are discussed in more detail in subsequent pages.

Out-of-source vs. in-source compilation

The above instructions explain how to perform an "out-of-source" build in which intermediate files created during compilation process are placed in the PSCF bld/ sub-directory tree. One can instead perform an "in-source" build in which these files are instead placed in the PSCF src/ directory that also contains all C++ and CUDA source code files. The option of in-source compilation is discussed in more detail here. We recommend out-of-source compilation for users who are not actively working on development. Some programmers may prefer to use in-source compilation during development.

Getting the Source Code (Prev) Installation (Up) Environment Variables (Next)