Build System (Next)

This page provides a description of the directory structure of the PSCF repository, focusing on the contents of the src directory.

A user's local copy of the PSCF repository is normally created by cloning project dmorse/pscfpp from github.com. The required git clone command should use use the –recursive option to download and install the contents of two other github repositories into subdirectories as git submodules. By default, this operation 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, 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 elsewhere.

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 also use this as as a shorthand to refer to types of file, thus referring to files with names that end with a suffix .h as *.h files, for example.

PSCF root directory

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 a variety of calculations
data	Read-only data, such as lists of space group symmetry elements
make	Files used only by the "configure" script

Source file (src) directory

The src directory contains all of the C++ and CUDA C++ 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 source 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.

Program-level namespaces and directories:

The Pscf::R1d, Pscf::Rpc and Pscf::Rpg namespaces and the corresponding r1d, rpc and rpg subdirectories of src each contain code is only used to construct one executable program. These three namespaces and corresponding directories are referred to hereafter as program-level namespaces and program-level directories, respectively. Subdirectory r1d contains code that is only used by pscf_1d, rpc contains code that is only used by pscf_pc, and rpg contains code that is only used by pscf_pg. By convention, code defined in one program-level PSCF namespace may not use entities such classes or functions that are defined in any other namespace-level namespace.

Each of these three program-level directories contains a program file that defines the main function for the associated program. The base name of each such file is the same as the executable name, followed by a suffix .cpp or .cu. For example, the main function for program pscf_1d is defined in the file src/r1d/pscf_1d.cpp.

Subdirectories util, pscf and prdc are namespace-level directories that are not program-level directories. These contain code for classes and functions that can be used in more than program, and do not contain any program files.

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 source code files in directory A are allowed to use named entities (i.e., classes, class templates, functions, etc.) 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

Note that every directory other than util depends on util, and every directory other than util and pscf depends on both util and pscf. These two directories thus contain code that is available for use through the PSCF source code. The prdc directory contains code that is only used in the pscf_pc and pscf_pg programs for systems with periodic boundary conditions, and so is listed as a dependency of the rpc and rpg directories. None of the three program-level directories (r1d, rpc, and rpg) depends on any other program-level directories

Unit test directories:

In addition to these namespace level subdirectories, the src directory has one additional top-level subdirectory named "test". This directory contains files that define a C++ unit test framework used throughout PSCF to construct unit tests. 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 the 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 makefile targets that build the PSCF executable programs.

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

make test

All of the tests associated with any 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.

File Types

The src directory contains several different types of file, as discussed below.

Source code file types:

All C++ code files associated with a given class or set of functions are placed in the same directory and have the same base name, with different file name extensions. The name of a file that contains C++ code for a single class or class template almost always has a base name that is same as the class name, with a file name extension that indicates the file type. All namespace and class names upper space camel capitalization, in which the first letter of each word in a name is capitalized.

PSCF uses the following file name 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++ preprocessor #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, usually contain definitions of non-inline member functions of a class template, much like the compilable source file for a non-template class. These files are almost always included either into an associated *.h header file (for standard class templates that rely on implicit instantiation) or into an associated *.cpp or *.cu source file with the same base name (for class templates that are compiled by explicit instantiation), as discussed in detail developer_template_page "here". Template implementation files should generally not be directly included into other source code files.

Compilable source files that contain or include only standard C++ code may 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 files types:

The PSCF build system is based on the unix make command, and uses several types of file that are placed in the src directory. The following table list two types of file that are part of this build system:

Pattern	Purpose
makefile	makefile (instructions for the make command)
*.mk	makefile fragment (included by other makefiles)

Immediately after the PSCF repository is cloned, almost every subdirectory of the src directory will contain a makefile and a makefile fragment named sources.mk. Each namespace-level directories of src will also contain several additional makefile fragments named patterns.mk and include.mk.

After the configure script is run, the src and bld directory will each contain an additional makefile fragment named config.mk, and the bld directory and each namespace-level subdirectory of the build directory will also contain a makefile.

The PSCF build system is discussed in detail on the following page.

Documentation files types:

The web manual for PSCF is constructed using the doxgen documentation utility. This utility extracts API documentation from source code files, but also incorporates manual pages that are placed in separate files.

Files that contain the contents of a web manual page have file names that end with file name extension .dox. The main manual pages are *.dox files that are located in the docs/manual directory. Some other files that are used by doxygen also appear in the src/ directory alongside the source code files.

The following two file name extensions are used for files that are used by doxygen to construct a web manual:

Pattern	Purpose
*.dox	doxygen web manual page
*.mod	doxygen topic module definition

Each files with file name extension .mod defines one of the doxygen "Topic" modules that is used to create the hierarchical presentation of class API documentation that is accessible via the "Topics" tab at the top of every web manual page.

Most of the *.dox files that appear in the src directory contain the contents manual pages that provide additional information for users about a particular class or class template. The name of a file that contains the content of such a manual page usually has a prefix that is the same the name of the class or class template (which is also used as a prefix for the associated source code files) followed by a suffix .dox. Each such web manual page usually describe the syntax of the parameter file block associated with a class, and may also provide information about algorithm or mathematical conventions that a user would need to understand in order to write the parameter file block and choose appropriate values for parameters. The resulting user-oriented web manual pages do not contain the API documentation that is extracted from comments in the source code, which doxygen uses to create a separate API documentation page for each class or class template. The user documentation page and the API documentation page for each class or class template are usually accessible to one another via html links.

Developer Information (Up / Prev) Build System (Next)