File Types (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 within one associated 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 within in one program-level PSCF namespace may not use entities such classes or functions that are defined in any other program-level namespace.
Each of these three program-level directories contains a main 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 but 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 main 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 other directories that each namespace level directory depends 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 that is used throughout PSCF to construct unit tests. This framework contains 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
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
from within that subdirectory.
Developer Information (Up / Prev) File Types (Next)
Generated on for PSCF by
1.14.0