Code Organization

Modules

MPQC is a collection of libraries linked into a small end-user program. Each library is a logical module; eventually they will become C++ modules, with proper separation between public interface and implementation details, when support for modules by the compilers and build tools becomes more mature. In the meantime, it is programmer's responsibility to organize the MPQC source code and build harness appropriately to emulate modular behavior.

Modular structure of MPQC is shown below.

Modular structure of MPQC

Source code organization, as detailed in The Source Tree , directly mirrors the modular structure of MPQC. The following rules govern the source code structure, and the related structure of the build harness.

1 Library per Directory: Each library should be located in its own directory, with single CMakeLists.txt. There may be additional subdirectories, if needed, but they should not contain their own CMakeLists.txt. Library's CMakeLists.txt defines the CMake library target by invoking either add_mpqc_hdr_library (for a header-only library) or add_mpqc_library (for non-header-only library). Dependence of the library on other MPQC libraries and external dependencies (which have corresponding CMake imported targets) must be explicitly expressed by establishing dependence of the CMake library target of the corresponding prerequisite targets. Library's dependence on its prerequisites can occur at compile-time (by #include public header files of the prerequisite) and link-time (by containing references to symbols defined in the prerequisite's public binary artifacts, such as, object files, static libraries, shared libraries, and frameworks). Both types of dependencies must be specified explicitly. N.B. although omitting compile-time dependence on other MPQC libraries usually will not cause a mis-build, it can; specifying compile-time dependencies between CMake targets will also help to determine dependencies between MPQC C++ modules in the future.

This example shows how the CMake target is defined for the library located in src/mpqc/chemistry/qc/lcao/wfn:

# usually single list of source files is sufficient
# if some headers are non-public it may be necessary
# to specify the list of public headers separately
set(sources
  ao_wfn.cpp  ao_wfn.h  fwd.h
  lcao_wfn.cpp  lcao_wfn.ipp  lcao_wfn.h
  linkage.h  periodic_ao_wfn.cpp  periodic_ao_wfn.h
  population_analysis.cpp  population_analysis.h
  util.h  wfn.cpp  wfn.h
)
 
# this defines MPQClcao_wfn library target
add_mpqc_library(
  # library basename
  lcao_wfn
  # list of source files (header files in the list will be ignored)
  sources
  # list of public header files (non-header files in the list will be ignored)
  sources
  # list of CMake targets on which this target will depend on
  # this may include both MPQC target and non-MPQC (hence, imported) targets
  "MPQCwfn;MPQClcao_factory;MPQCutil_misc;MPQCutil_keyval;MPQCmolecule;tiledarray"
  # location of the public headers in the install tree
  "mpqc/chemistry/qc/lcao/wfn"
)

Single Forward Declaration Header: Each library's forward declarations are collected in the fwd.h file. work in progress

Explicit Instantiation of Template Functions/Classes: Expensive-to-compile template classes and functions should be instantiated and included in library's binary artifact. Implementations of such templates should be separated from the header file in which they are declared and included in a separate "implementation header" file; following Boost such file should have .ipp extension. work in progress

Single Linkage Artifacts Header: Each library's forward declarations are collected in the linkage.h file. work in progress