Source Code (Prev) Environment Variables (Next)

Below is a brief overview of instructions for compiling all of the PSCF programs using default settings. The directions given here and in subsequent pages assume that you have already cloned the pscfpp repository and installed all required dependencies. The descriptions assume that the root directory of the repository is named pscfpp/. You are free to rename the root directory before running or rerunning the setup script.

Below, have divided the instructions i 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 Setup

The following steps must be taken after installing required dependencies but before atttempting to compile any part of PSCF:

Set environment variables: Modify the users PATH and PYTHONPATH unix environment variables so as to include pscfpp/bin directory in the PATH (the unix shell command search path) and so as to include pscfpp/lib/python in the PYTHONPATH (the Python module search path). This is discussed in greater detail here.
Navigate to root directory: Change directory (cd) to the pscfpp/ root directory.
Setup: Invoke the "setup" script from the pscfpp/ root directory. To setup the build system with default compiler options appropriate to most linux systems, enter the command
./setup

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.

Alternatively, to customize compiler options, one may invoke the setup script with a filename argument that is the name of a compiler configuration file that contains non-default compiler options, as discussed here). An environment appropriate for compiling on a Mac OS X system with Apple silicon hardware (e.g., an M1 or M2 chip) in which the dependencies were installed using the homebrew package mamager can be created by entering
./setup mac-si-homebrew

from the pscfpp/ directory.

Compiling C++ Code (CPU Hardware)

We recommend that users first compile only the programs in PSCF that use standard CPU hardware, leaving compilation GPU-enabled C++/CUDA programs as a separate step.

Compilation of GPU-enabled CUDA code is disabled by default after the setup operation described above. To compile only C++ CPU programs, but no GPU-enabled code, you may simply enter

make all

from the pscfpp/ directory immediately after running the setup script.
If successful, this will install executables named "pscf_fd", "pscf_pc1", "pscf_pc2" and "pscf_pc3" in the pscfpp/bin directory.

Compiling all the PSCF C++ code using "make all" takes a little 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 PSCF.

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

Compiling C++/CUDA Code (GPU Hardware)

The GPU-enabled C++/CUDA programs provided as part of PSCF can only be compiled on computers that have an NVIDIA development kit installed, and can only be run on machines that have an appropriate NVIDIA GPU and CUDA driver software. Before compiling this code, the user must 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 setup 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
./configure -c1

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

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

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

from that directory. This should yield a report indicating whether the "debugging" and "CUDA" options are 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 pscfpp/ root directory and issue a command of the form
.\configure -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 K40 GPU has a compute capability of 3.5. To set this as the target architecture, one would enter
./configure -a sm_35

from the pscfpp/ directory, using "sm_35" as the architecture id.
Compile all programs (including GPU-enabled programs): After enabling CUDA compilation and setting the appropriate architecture, you can compile all programs, inluding GPU enabled programs, by simply re-entering "make all" or
make -jn all

from within the pscfpp/ root directory, where "n" is the number of CPU cores to be used during compilation.

If successful, the "make all" command will install executables files named "pscf_pg1", "pscf_pg2" and "pscf_pg3" in the pscfpp/bin directory in addition to the files "pscf_fd", "pspc_pc1", "pscf_pc2" and "pscf_pc3" that are created by compiling only C++ code.

Several of the above steps is discussed in more detail in the following 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 pscfpp/bld directory tree. It is also possible to perform an "in-source" build in which these files are instead placed in the pscfpp/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 the use of out-of-source compilation for package users who are not actively working on development. Some developers may find in-source compilation more convenient during development.

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