pyAMReX Structure

Repo Organization

The pyAMReX source code is located in src/ and contains pybind11 C++ code, exposing C++ objects and functions to Python. All sub-directories have a pretty straightforward name, mirroring the AMReX Src/ structure.

Additionally, the src/amrex/ directory contains Python import modules and extensions written in pyre Python.

Code organization

The main pyAMReX import module(s) are amrex.space1d, amrex.space2d and amrex.space3d, implemented in src/pyAMReX.cpp. This import calls helper functions to initialize all other Python objects on import.

Build System

pyAMReX uses the CMake build system generator. Each sub-folder contains a file CMakeLists.txt with the names of the source files (.cpp) that are added to the build. Do not list header files (.H) here.

C++ Includes

All pyAMReX header files need to be specified relative to the src/ directory.

  • e.g. #include "pyAMReX.H"

  • files in the same directory as the including header-file can be included with #include "FileName.H"

By default, in a MyName.cpp source file we do not include headers already included in MyName.H. Besides this exception, if a function or a class is used in a source file, the header file containing its declaration must be included, unless the inclusion of a facade header is more appropriate. This is sometimes the case for AMReX headers. For instance AMReX_GpuLaunch.H is a façade header for AMReX_GpuLaunchFunctsC.H and AMReX_GpuLaunchFunctsG.H, which contain respectively the CPU and the GPU implemetation of some methods, and which should not be included directly. Whenever possible, forward declarations headers are included instead of the actual headers, in order to save compilation time (see dedicated section below). In pyAMReX forward declaration headers have the suffix *_fwd.H, while in AMReX they have the suffix *Fwd.H. The include order (see PR #874 and PR #1947) and proper quotation marks are:

In a MyName.cpp file:

  1. #include "MyName.H" (its header) then

  2. (further) pyAMReX header files #include "..." then

  3. pyAMReX forward declaration header files #include "..._fwd.H"

  4. AMReX header files #include <...> then

  5. AMReX forward declaration header files #include <...Fwd.H> then

  6. other third party includes #include <...> then

  7. standard library includes, e.g. #include <vector>

In a MyName.H file:

  1. #include "MyName_fwd.H" (the corresponding forward declaration header, if it exists) then

  2. pyAMReX header files #include "..." then

  3. pyAMReX forward declaration header files #include "..._fwd.H"

  4. AMReX header files #include <...> then

  5. AMReX forward declaration header files #include <...Fwd.H> then

  6. other third party includes #include <...> then

  7. standard library includes, e.g. #include <vector>

Each of these groups of header files should ideally be sorted alphabetically, and a blank line should be placed between the groups.

For details why this is needed, please see PR #874, PR #1947, the LLVM guidelines, and include-what-you-use.

Forward Declaration Headers

Forward declarations can be used when a header file needs only to know that a given class exists, without any further detail (e.g., when only a pointer to an instance of that class is used). Forward declaration headers are a convenient way to organize forward declarations. If a forward declaration is needed for a given class MyClass, declared in MyClass.H, the forward declaration should appear in a header file named MyClass_fwd.H, placed in the same folder containing MyClass.H. As for regular header files, forward declaration headers must have include guards. Below we provide a simple example:

MyClass_fwd.H:

#ifndef MY_CLASS_FWD_H
#define MY_CLASS_FWD_H

class MyClass;

#endif //MY_CLASS_FWD_H

MyClass.H:

#ifndef MY_CLASS_H
#define MY_CLASS_H

#include "MyClass_fwd.H"
#include "someHeader.H"
class MyClass{/* stuff */};

#endif //MY_CLASS_H

MyClass.cpp:

#include "MyClass.H"
class MyClass{/* stuff */};

Usage: in SimpleUsage.H

#include "MyClass_fwd.H"
#include <memory>

/* stuff */
std::unique_ptr<MyClass> p_my_class;
/* stuff */