Source File Lists (Next)

This page provides an introduction to the directory structure of the PSCF repository aimed at developers, as well as very brief introduction to the build system. The PSCF build system is discussed in greater detail in following pages.

PSCF root directory

A user's local copy of the PSCF repository is normally created by cloning project dmorse/pscfpp from github.com, while using the –recursive option to load the contents of two other github repositories into subdirectories as git submodules. By default, this creates a directory named pscfpp as a subdirectory of the directory from which the git clone command was issued. In what follows, we refer to the resulting directory, which contains the contents of the entire PSCF repository and its submodules, as the PSCF root directory.

The PSCF root directory can be renamed or moved by the user after it is created. If a user does so, however, they must then run or rerun the configure script in order to allow this script to assign new values for some makefile variables that contains absolute paths to the PSCF root directory and some of its subdirectories, as discussed below.

The names and purposes of all of the top-level subdirectories of the PSCF root directory are given briefly below:

Directory	Purpose
src	Contains all C++ and CUDA C++ source code
bld	Build directory for out-of-source builds
bin	Default installation location for executable files
lib	Source code for interpreted languages (python and bash)
docs	Documentation, including source pages for web manual
examples	Examples input files for various types of calculation
data	Read-only data, such as lists of space group symmetry elements
make	Files copied to otherwise used by the "configure" script

The three most important top-level subdirectories are the first three listed above: src, bld and bin.

In what follows, we describe file name patterns and standard file extension using the * (asterisk) symbol to represent a wildcard that can represent any string of characters. For example, the pattern *.h can represent any file name that ends in extension .h, which is a standard file name extension for C++ header files. We sometimes refer to file names that match such a pattern either as, for example, *.h files.

Overview of build process

PSCF is compiled by the user using a system of unix makefiles. Compilation and installation of the package involves the following steps:

Compiling all source files in the src directory
Creating several static library files
Creating executable files (pscf_1d, pscf_pc, and pscf_pg)

Several aspects of this process are described in more detail below.

All C++ and C++/CUDA source files for PSCF are located in the src directory tree. When a source file in this directory is compiled, the build system creates two associated files that we refer to as an object file and a dependency file.

An object file is a file with file name extension .o that contains the object code created by compiling the associated source file.
A dependency file is a makefile fragment with file name extension .d that contains a makefile rule that lists all the the pre-requisites of the associated source file.

The object and dependency file that are created by compiling a source file have the same base file name as the associated source file.

The PSCF build system also creates several static libraries with file names of the form lib*.a. Each such library contains all of the assembly code created by compiling the source files in one top-level subdirectory of the src directory.

The object, dependency and library files that are created during the build process are referred to in what follows as "intermediate" files. The directory in which all such intermediate files are placed is referred to as the build directory.

The PSCF makefile system is designed to allow a user to perform either an "out-of-source" build or an "in-source" build. In an "out-of-source" build, all intermediate files created during compilation are placed in a build directory that is distinct from the src directory. By default, PSCF uses the bld subdirectory of the PSCF root directory as the build directory for this purpose. In an "in-source" build, these intermediate files are instead placed within the src directory, alongside the source files from which they were created.

During an in-source build, the PSCF build system places the *.o object file and the *.d dependency file that are created by compiling one source file in the same subdirectory of src as the associated source file. During an out-of-source build, these two files are instead placed in an analogous subdirectory of the bld directory tree. To make this convention possible, the bld directory must have an internal directory structure exactly analogous to that of the src directory.

PSCF is built by invoking the "make" command. The choice between in-source and out-of-source compilation is determined by the working directory from which a user invokes "make": Invoking "make" from either the PSCF root directory or from the bld directory causes make to perform an out-of-source build in which intermediate files are placed in the the bld directory. Invoking "make" from the src directory instead causes make to be built in-source.

Source file (src) directory

The src directory contains all of the C++ and C++/CUDA source code files for PSCF. The structure of subdirectories of src reflects the organization of entities defined in the source code (i.e., classes and functions) into several C++ namespaces.

C++ namespaces:

The source code for PSCF is divided between two top-level C++ namespaces, named Util and Pscf.

The Util namespace contains a collection of general utilities for scientific computation that are also used by projects other than PSCF. The code is maintained in a separate github repository (project dmorse/util) and imported into the pscfpp repository as a git submodule. All source code files for entities that are defined in the Util namespace are located in the src/util directory.

The Pscf namespace contains all of source code files that are contained in the dmorse/pscfpp github repository, all of which are specific to the PSCF package. The Pscf namespace contains several enclosed sub-namespaces. All source code for each such enclosed namespace is located within a specific subdirectory of the src directory, as discussed below.

Namespace-level directories:

The src directory contains six subdirectories that each contain code defined in a specific C++ namespace. These six directories will be referred to in what follows as "namespace" level subdirectories of src. These six namespace-level subdirectories are listed below:

Subdirectory	Namespace	Purpose
util	Util	General utilities
pscf	Pscf	Code defined directly in Pscf, used by all PSCF programs
prdc	Pscf::Prdc	Code for periodic structures, used by pscf_pc and pscf_pg programs
r1d	Pscf::R1d	Code used only by the pscf_1d program
rpc	Pscf::Rpc	Code used only by the pscf_pc CPU program for periodic structures
rpg	Pscf::Rpg	Code used only by the pscf_pg GPU program for periodic structures

The src/pscf directory contains files that contain code for class and functions that are defined directly in the Pscf namespace, rather than in one of the enclosed sub namespaces of Pscf. The src/prdc, src/r1d, src/rpc, and src/rpg instead each contain code for entities that are defined in a specific sub-namespace of Pscf.

The PSCF makefile system constructs a static library in each of these six namespace level directories. Each static library file is a file with a name of the form lib[namespace].a, where [namespace] represents the name of the relevant subdirectory. For example, the build system creates a library file named libprdc.a in the src/prdc directory.

The r1d, rpc and rpg subdirectories of src each contain code is only used in a one executable program. Specifically r1d contains code that is only used by pscf_1d, rpc contains all code that only used by pscf_pc, and rpg contains code that only used by pscf_pg. Each of these three directories also contains a main program file that defines the main function for the associated program. The directories util, pscf and prdc do not contain any main program files, and instead contain code for classes and functions that can be used in more than program.

Dependencies among namespace level directories:

PSCF imposes a set of rules for dependencies among the various namespace level directories. A namespace level directory named A is said to depend on another such directory named B if C++ files in directory A are allowed to use entities (i.e., classes, class templates or functions) that are defined by files in directory B. The following table lists the directories that each of the namespace level directories depend upon in this sense:

Subdirectory	Dependencies
util	(None)
pscf	util
prdc	pscf, util
r1d	pscf, util
rpc	prdc, pscf, util
rpg	prdc, pscf, util

Every directory other than util depends on util, and every directory other than util and pscf depends on util and pscf. These two directories thus provide code that used through PSCF code. The prdc directory contains code that is only needed in the pscf_pc and pscf_pg programs for systems with periodic boundary conditions, and so is listed as a dependency of associated directories rpc and rpg.

Unit test directories:

In addition to these namespace level subdirectories, the src directory has one additional top-level subdirectory named "test" that contains files that define a C++ unit test framework. This framework is defined using only header (*.h) files, and thus does not need to be compiled or linked. The unit test framework used by PSCF is maintained on github in a separate repository (dmorse/test) and is imported into the src/test directory of a user's PSCF repository as a submodule.

Each of the six namespace level subdirectories of the src directory also contains a subdirectory named "tests" that contains unit tests for classes and functions defined in the associated namespace. These unit tests are not automatically compiled or run by the commands that build the PSCF executable programs.

All of the PSCF unit tests can be run by changing directory to the desired build directory (src or bld/) and entering the command

make test

All of the tests associated with a single namespace level directory can be compiled and run by changing directory to the corresponding tests subdirectory within that namespace directory in the relevant build directory (i.e., within a namespace level subdirectory of the bld directory for an out-of source build, or within a namespace level subdirectory of src for an in-source-build) and entering

make run

from within that subdirectory.

Source code file types:

All C++ files associated with a given class or set of functions are placed in the same directory and have the same base name. The name of a file that contains C++ code for a specific class or class template has a base name that is same as the class name, and has a file name extension that indicates the file type. All class names are upper space camel (such as Pscf::Monomer).

PSCF uses the following file name patterns and file extensions for C++ and CUDA C++ files:

Pattern	Purpose
*.h	C++ header file
*.tpp	implementation of a class template
*.cpp	compilable C++ source file
*.cu	compilable CUDA C++ source file

Header files, with extension .h, may be included into other C++ files using a C/C++ #include directive. C++ and CUDA C++ source files, with extension .cpp or .cu, are compiled, and may never be included by other program files. Template implementation files, with extension .tpp, are generally included into either an associated *.h header file or an associated *.cpp or *.cu source file with the same base name (as discussed in more detail developer_template_page "here"), and may not be directly included by other files.

Compilable source files that contain or include only standard C++ code should be given file extension .cpp. Compilable source files that contain or include any CUDA C++ code must instead use file extension .cu. Different makefile pattern rules are used to compile files with filename extension .cpp and .cu, using different compilers, using the NVIDIA nvcc compiler to compile files with file extension .cu.

Build system and documentation files types:

The following table explains the purposes of several other types of file that are the user will see in the src directory after running the configure script.

Pattern	Purpose
makefile	makefile (instructions for the make command)
*.mk	makefile fragment (included by other makefiles)
*.dox	doxygen documentation file (manual page)
*.mod	doxygen documentation file (topic module)

After the configure script is run, the bld directory will also contain several files named "makefile", but not either of the types of documentation files listed above.

Configuration (config.mk) files

After the configure script is run, the src and bld directory will each contain a makefile fragment named config.mk. Each of this is the main configuration file used by the build system to build in the directory that contains the configuration file. This file assigns values to a variety of makefile variables that are needed throughout the build system.

The config.mk configuration file in each build directory (i.e., in the src or bld directory) is included in every other makefile in the same build directory tree. The config.mk file in the src directory is thus included by all makefiles in the src directory tree, but not those in the bld directory, and so only affects in-source builds that are performed by calling make from within the src directory. Conversely, the config.mk file in the bld directory is included by all makefiles in the bld directory tree, but not those in the src directory, and so only affects out-of-source builds.

Directory path variables

Among the variables defined in the config.mk file in each build directory are makefile variables whose values give paths to the PSCF root directory and several of its subdirectories. The names and meanings of the most important such path variables are listed below:

Name	Meaning
ROOT_DIR	Path to PSCF root directory
SRC_DIR	Path to the source directory
BLD_DIR	Path to the build directory
BIN_DIR	Path to directory for installing executables

The values assigned to all of these variables are absolute paths. On any unix-like system, the first character of an absolute path is a backslash ("/") character that represents the root of the computer filesystem. The value of the ROOT_DIR variable is set by the configure script to be the absolute path to the root directory as identified by this script at the time that the configure script was run. Values of other variables are defined using the value of ROOT_DIR, as discussed below.

As an example, suppose that a user with user name smith has a home directory /users/smith, and suppose that this user has installed the PSCF root directory as a subdirectory of their home directory, as /users/smith/pscfpp. In this case, the part of the config.mk file that is located in the users bld directory that defines these path variables would look like this after the configure script has been run:

ROOT_DIR=/users/smith/pscfpp
SRC_DIR=$(ROOT_DIR)/src
BLD_DIR=$(ROOT_DIR)/bld
BIN_DIR=$(ROOT_DIR)/bin

The symbol represents the value of the makefile variable ROOT_DIR, which is given here by the string /usrs/smith/pscfpp. The config.mk file in the bld directory is only included by makefiles in the bld directory, and is only used during an out-of-source build that is performed by invoking make from within the PSCF root directory or the bld directory. This configuration file thus declares /bld to be the build directory in which all intermediate files should be placed.

The corresponding variable definitions in the config.mk file in the src directory in this example would be almost identical to those shown above, except for the value assigned to the variable BLD_DIR: In the file src/config.mk, BLD_DIR would be assigned a value /src rather than /bld. In both cases, the value of BLD_DIR is an absolute path to the directory that contains the config.mk file This configuration file thus declares the build directory BLD_DIR used during in-source-bld is the same as the src directory.

If the name or location of the PSCF root directory is changed after the configure script has been run, users will need to rerun the configure script to reset the value of the makefile variable ROOT_DIR to the correct location.

Users can, if desired, change the location in which executable files are installed by using an text editor to change the value assigned to BIN_DIR within either or both of these configuration files. The executable files produced by PSCF are self-contained and may be moved after they are created. Users may thus also simply move the executable files to a new location after building PSCF.

If the name or location of the PSCF root directory is changed after after executables have been created, however, users will need to rerun the configure script and then rebuild PSCF to create new executables.
This is necessary because some of the PSCF executables contain a path to the PSCF data directory that is used to access read-only data files at run time. Currently, the only files that are accessed in this way are files in the directory data/groups that specify the symmetry elements for all standard crystallographic space groups. The files are accessed by the pscf_pc and pscf_pg programs. In order for these programs to function correctly, the path to the data directory cannot change after these executables are created.

Developer Information (Up) Source File Lists (Next)