File Types (Next)
This page provides a description of the directory structure of the PSCF repository, focusing on the contents of the src directory.
In what follows, we describe file name patterns and standard file name suffixes by 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
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 from the new location 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 in detail here.
The names and purposes of all of the top-level subdirectories of the PSCF root directory are listed below:
| Name | 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 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 |
| r1d | Pscf::R1d | Code used only by the pscf_r1d program |
| prdc | Pscf::Prdc | Code for periodic systems |
| rp | Pscf::Rp | Class templates used in programs for real periodic fields |
| rpc | Pscf::Rpc | Code used only by the pscf_rpc CPU program for real periodic fields |
| rpg | Pscf::Rpg | Code used only by the pscf_rpg GPU program for real periodic fields |
| cp | Pscf::Cp | Class templates used in programs for complex periodic fields |
| cpc | Pscf::Cpc | Code used only by the pscf_cpc CPU program for complex periodic fields |
| cpg | Pscf::Cpg | Code used only by the pscf_cpg GPU program for complex periodic fields |
The src/pscf directory contains files that contain code for classes and functions that are accessible throughout the package, most of which are defined directly in the Pscf namespace. The src/prdc, src/r1d, src/rp, src/rpc, src/rpg and src/cp, src/cpc, and src/cpg directories instead each contain code for entities that are defined in a specific enclosed namespace of Pscf, and that are used in only some of the main programs constructed by the package.
The PSCF makefile system constructs a static library file each of the namespace level directories that contains compilable source files. Specifically, static libraries are constructed in the pscf, r1d, prdc, rpc, rpg, cpc, and cpg namespace level directories. Each such static library contains the object code created by compiling all of the compilable source files (with file extension .cpp or .cu) in the asssociated namespace-level directory. Each static library is a file with a name of the form lib[namespace].a, where [namespace] represents the name of the relevant namespace level directory. For example, a library named libprdc.a is created in the src/prdc directory.
Static library files are not created in the src/rp and src/cp directories because these directories currently only contain files with filename extensions .h and .tpp that are included by other files, and that do not contain any source files with filename extensions .cpp or .cu that are separately compiled and linked.
Program-level namespaces and directories:
The Pscf::R1d, Pscf::Rpc, Pscf::Rpg, Pscf::Cpc and Pscf::Cpg namespaces and the corresponding r1d, rpc, rpg, cpc, and cpg namespace-level subdirectories of src each contain code is only used within one associated executable program. These five 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 the pscf_r1d program. Subdirectories rpc and rpg contains code that is only used by the pscf_rpc and pscf_rpg programs, respectively. Subdirectories cpc and cpg contain code that will only be used by the the pscf_cpc and pscf_cpg CL-FTS programs, though these programs aree still under development. By convention, code within in any program-level PSCF namespace may not use named entities (e.g., classes or functions) that are defined in any other program-level namespace.
Each of the five program-level directories either contains or will contain a main program file that defines a main C 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_rpc is defined in the file src/rpc/pscf_rpc.cpp.
Subdirectories util, pscf, prdc, rp and rc are namespace-level directories but are not also program-level directories. Each of these directories contains code for classes and functions that can be used as building blocks in more than program.
Dependencies among namespace level directories:
PSCF imposes a set of rules for dependencies among the 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 other directories that each namespace level directory depends upon in this sense:
| Subdirectory | Dependencies |
|---|---|
| util | (None) |
| pscf | util |
| r1d | pscf, util |
| prdc | pscf, util |
| rp | prdc, pscf, util |
| rpc | rp, prdc, pscf, util |
| rpg | rp, prdc, pscf, util |
| cp | prdc, pscf, util |
| cpc | cp, prdc, pscf, util |
| cpg | cp, prdc, pscf, util |
Note that every directory other than util depends on util, and all directories other than util and pscf depend 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 may be used throughout the pscf_rpc, pscf_rpg, pscf_cpc and pscf_cpg programs for systems with periodic boundary conditions. The rp directory contains code that is used only in the pscf_rpc and pscf_rpg directory, while the cp directory contains code that is used only in the pscf_cpc and pscf_cpg programs. None of the five program-level directories (r1d, rpc, prg, cpc, and cpg) depends on any other program-level directory.
Unit test framework:
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 that is used throughout PSCF to construct unit tests. This framework contains only header (*.h) files, and thus does not contain any source files that 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.
Namespace-level unit test directories:
Each of the namespace level directories that contains compilable source code files contains a subdirectory named "tests". Each such directory contains unit tests for classes and functions defined in the parent namespace-level directory. 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 (i.e., src or bld) and entering the command
All of the tests associated with any single namespace-level directory can be compiled and run by changing directory to the subdirectory named "tests" within that namespace directory in the relevant build directory (i.e., within the bld directory tree for an out-of source build, or the src directory tree for an in-source-build), and then entering
from within that "tests" subdirectory.
The src/rp and src/cp directories do not contain unit test directories.
Developer Information (Up / Prev) File Types (Next)
Generated on for PSCF by
1.14.0