From 45e3e25f93474bc9ff37a667685c71fe90765954 Mon Sep 17 00:00:00 2001 From: moritzleucke Date: Tue, 25 Feb 2025 16:34:12 +0100 Subject: [PATCH 1/3] changing number of components build by default --- CMakeLists.txt | 6 +- GX-AnalyticContinuation/README.md | 3 +- README.md | 156 ++++++++++++++++-------------- 3 files changed, 85 insertions(+), 80 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 2c5ab9f9..2389e504 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -90,13 +90,13 @@ if (${MINIMAX_COMPONENT}) add_subdirectory(GX-TimeFrequency) endif () -option (LBASIS_COMPONENT "Enable the localized basis component" ON) +option (LBASIS_COMPONENT "Enable the localized basis component" OFF) if (${LBASIS_COMPONENT}) add_subdirectory(GX-LocalizedBasis) endif() # Elements to compile the libraries inside submodules -option(COMPILE_SUBMODULES "Compile GreenX component contained inside submodules" ON) +option(COMPILE_SUBMODULES "Compile GreenX component contained inside submodules" OFF) if (${COMPILE_SUBMODULES}) # zofu is needed for IDieL regression tests if (${ENABLE_GREENX_UNIT_TESTS}) @@ -133,7 +133,7 @@ if (${COMPILE_SUBMODULES}) endif() # Install libpaw -option(PAW_COMPONENT "Enable the PAW component" ON) +option(PAW_COMPONENT "Enable the PAW component" OFF) if (${PAW_COMPONENT}) set(LIBPAW_SOURCE "${PROJECT_SOURCE_DIR}/GX-PAW/") ExternalProject_Add(LIBPAW diff --git a/GX-AnalyticContinuation/README.md b/GX-AnalyticContinuation/README.md index 1ad66bbb..7a3dbeea 100644 --- a/GX-AnalyticContinuation/README.md +++ b/GX-AnalyticContinuation/README.md @@ -13,8 +13,7 @@ The analytic continuation component (GX-AC) provides routines to interpolate fun If you want to compile only the Analytic Continuation (AC) component of Greenx, change to the GreenX root, then type: ```bash mkdir build && cd build -cmake -DMINIMAX_COMPONENT=OFF -DLBASIS_COMPONENT=OFF \ - -DPAW_COMPONENT=OFF -DCOMPILE_SUBMODULES=OFF ../ +cmake -DMINIMAX_COMPONENT=OFF .. make -j make install diff --git a/README.md b/README.md index 706fd8ff..fd7d35b9 100644 --- a/README.md +++ b/README.md @@ -53,37 +53,37 @@ configure with: cmake ../ -DBUILD_SHARED_LIBS=OFF ``` -Specific shared libraries can be disable, e.g to disable the Projector-Augmented Wave (PAW) component of GreenX, run CMake configure with: +Specific shared libraries can be disabled or enabled, e.g to enable the Projector-Augmented Wave (PAW) component of GreenX, run CMake configure with: ```bash -cmake ../ -DPAW_COMPONENT=OFF +cmake ../ -DPAW_COMPONENT=ON ``` Available options to disable one or more components -| Component | CMake configure | -|----------------------------------------|------------------------------------| -| Analytical Continuation component | `cmake .. -DAC_COMPONENT=OFF` | -| Minimax Time-Frequency grids component | `cmake .. -DMINIMAX_COMPONENT=OFF` | -| Localized Basis component | `cmake .. -DLBASIS_COMPONENT=OFF` | -| Projector-Augmented Wave component | `cmake .. -DPAW_COMPONENT=OFF` | +| Component | CMake configure | Default | +|----------------------------------------|------------------------------------|---------| +| Analytical Continuation component | `-DAC_COMPONENT` | `ON` | +| Minimax Time-Frequency grids component | `-DMINIMAX_COMPONENT` | `ON` | +| Localized Basis component | `-DLBASIS_COMPONENT` | `OFF` | +| Projector-Augmented Wave component | `-DPAW_COMPONENT` | `OFF` | -GreenX uses GNU Multiple Precision Arithmetic Library by default in the Analytical Continuation component, you can disable it without any harm by runing CMake configure with: +GreenX uses GNU Multiple Precision Arithmetic Library by default in the Analytical Continuation component, you can disable it without any harm by running CMake configure with: ```bash cmake ../ -DENABLE_GNU_GMP=OFF ``` -GreenX uses submodules and they are built by default. You can obtained them by executing: +To build GreenX with submodules (they are turned off by default), one can configure with: ```bash -git submodule update --init --recursive +cmake ../ -DCOMPILE_SUBMODULES=ON ``` -To build GreenX without the submodules, one can configure with: +You can obtained them by executing: ```bash -cmake ../ -DCOMPILE_SUBMODULES=OFF +git submodule update --init --recursive ``` If all requirements are found, build and install the project: @@ -96,14 +96,15 @@ make install Minimal example to build and install only the Time-Frequency component of GreenX: ```bash -cmake .. -DAC_COMPONENT=OFF -DLBASIS_COMPONENT=OFF -DPAW_COMPONENT=OFF -DCOMPILE_SUBMODULES=OFF +cmake .. -DAC_COMPONENT=OFF make -j make install ``` -## Running the Tests +## Regression Tests +### Running Regression Tests GreenX uses pytest as its regression testing framework, in conjunction with the custom python module `pygreenx`. First, one must ensure that `pygreenx` is installed. From the GreenX root directory: @@ -130,34 +131,61 @@ cd build ctest ``` -## Building Documentation - -GreenX is documented using Doxygen, and documentation support is disabled by -default. To enable CMake looking for Doxygen, configure with: - -```bash -cmake ../ -DENABLE_GREENX_DOCS=ON -``` - -To build the document, type in the build directory: - -```bash -make docs -``` - -Documentation is built in `documentation` and can be viewed by opening -`html/index.html` in a browser. - -When adding new files with documentation, please ensure the directory is listed -in the `INPUT` tag of Doxyfile. - -For more information and benchmark examples see also the [GreenX website](https://nomad-coe.github.io/greenX/). - -## Unit Testing +#### Adding Regression Tests + + + 1. Add a New Test Source File: Create a test file in the `test/` directory of the component. If testing a Fortran function, create a file like `test_new_feature.f90` with the necessary test logic. + + 2. Update `CMakeLists.txt`: Modify `CMakeLists.txt` in the component directory to include the new test: + - Add the source file to the test executable + ```cmake + # Define the new test target + add_executable(test_gx_new_feature) + + # Set binary name + set_target_properties(test_gx_new_feature + PROPERTIES + RUNTIME_OUTPUT_NAME test_gx_new_feature.exe) + + # Add source file for the new test + target_sources(test_gx_new_feature + PRIVATE + test/test_new_feature.f90 + ) + + # Link the test executable to the necessary libraries + target_link_libraries(test_gx_new_feature + PUBLIC + LibGXNewFeature + ) + + # Specify the runtime output directory + set_target_properties(test_gx_new_feature + PROPERTIES + RUNTIME_OUTPUT_DIRECTORY ${CMAKE_Fortran_BIN_DIRECTORY}) + ``` + + - Copy Python test files. If the test involves Python, ensure the test scripts are copied to the build directory: + ```cmake + add_custom_command( + TARGET LibGXNewFeature POST_BUILD + COMMAND ${CMAKE_COMMAND} -E copy + ${CMAKE_CURRENT_SOURCE_DIR}/test/test_new_feature.py + ${PROJECT_BINARY_DIR}/test/new_feature/) + ``` + + - Add the new test to CTest + ```cmake + add_test( + NAME test_gx_new_feature + COMMAND pytest -s test_new_feature.py --build-dir ${CMAKE_BINARY_DIR} + WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/test/new_feature + ) + ``` ### Running Unit Tests -Unit tests require the unit-testing framework [Zofu](https://github.com/acroucher/zofu). This library is build together with Greenx when `ENABLE_GREENX_UNIT_TESTS=ON`: +The GX-q=0 component of GreenX uses the unit-testing framework [Zofu](https://github.com/acroucher/zofu). This library is build together with Greenx when `ENABLE_GREENX_UNIT_TESTS=ON`: ```bash cmake -DENABLE_GREENX_UNIT_TESTS=ON ../ @@ -165,9 +193,6 @@ cmake -DENABLE_GREENX_UNIT_TESTS=ON ../ Unit tests are run with the application tests, using ctest. Simply type `ctest` in the build directory. - -### Installing the Unit-Testing Framework manually - It is also possible to compile Zofu manually. To build Zofu, from GreenX's root (noting that one must define `$GX_ROOT`): ```bash @@ -194,48 +219,29 @@ make install ``` Again, typing `ctest` in the GreenX build directory starts the unit tests together with the application tests. -### Adding Unit Tests - -For an example of writing a unit test, see `GX-AnalyticContinuation/src/test_pade_approximant.f90`. -A unit test is a module and follows the naming convention `test_MODULENAME.f90`. -The unit test itself is a module containing subroutines which set up some data, -call the routine under test, and make some assertions on the resulting data. -Zofu provides the object with which to make the assertions and carry the result. -One should write a separate test module for each fortran module they wish to test. -Unit tests are added to the build system straightforwardly: +## Building Documentation -1. Create a directory in the build folder that will contain the test binary. -A good convention is `unit_tests/sublibrary_name`: +GreenX is documented using Doxygen, and documentation support is disabled by +default. To enable CMake looking for Doxygen, configure with: -```cmake -set(UNIT_TEST_DIR "${PROJECT_BINARY_DIR}/unit_tests/analytic-continuation") -file(MAKE_DIRECTORY ${UNIT_TEST_DIR}) -message("-- Analytic continuation unit tests written to: ${UNIT_TEST_DIR}") +```bash +cmake ../ -DENABLE_GREENX_DOCS=ON ``` -Noting one is free to choose any name for `UNIT_TEST_DIR`. - -2. Create a list of libraries which your unit tests depend upon. Typically -the library associated with that subfolder, for which the module is a part of. +To build the document, type in the build directory: -```cmake -# Libraries on which the unit tests depend -set(LIBS_FOR_UNIT_TESTS LibGXAC) +```bash +make docs ``` -Noting one is free to choose any name for `LIBS_FOR_UNIT_TESTS`. - -3. Call the function `create_unit_test_executable` to define the unit test: +Documentation is built in `documentation` and can be viewed by opening +`html/index.html` in a browser. -```cmake -create_unit_test_executable(TARGET_TEST_DIR ${UNIT_TEST_DIR} - TEST_NAME "test_pade_approximant" - REQUIRED_LIBS ${LIBS_FOR_UNIT_TESTS}) -``` +When adding new files with documentation, please ensure the directory is listed +in the `INPUT` tag of Doxyfile. -For multiple tests, one could call `create_unit_test_executable` in a loop over -a list of modules. +For more information and benchmark examples see also the [GreenX website](https://nomad-coe.github.io/greenX/). ## Contribute From 17008d0c15a1ae606217cc8437ec88955a41fbb6 Mon Sep 17 00:00:00 2001 From: moritzleucke Date: Tue, 25 Feb 2025 16:39:16 +0100 Subject: [PATCH 2/3] italize GW in documentation --- docs/gx_ac.md | 4 ++-- docs/index.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/gx_ac.md b/docs/gx_ac.md index 4e66f2a3..147e505f 100644 --- a/docs/gx_ac.md +++ b/docs/gx_ac.md @@ -35,7 +35,7 @@ Padé approximants are known to be [numerical unstable](https://doi.org/10.1093/ # Benchmarks -In this benchmark section, we first analyze the effect of various parameters by using simple model functions, providing insights into their behavior, and then demonstrate practical applications in the field of ab initio electronic structure calculations. Specifically, we showcase the performance of our library for $GW$ calculations and real-time time-dependent density functional theory (RT-TDDFT) simulations. +In this benchmark section, we first analyze the effect of various parameters by using simple model functions, providing insights into their behavior, and then demonstrate practical applications in the field of ab initio electronic structure calculations. Specifically, we showcase the performance of our library for *GW* calculations and real-time time-dependent density functional theory (RT-TDDFT) simulations. ## Model Functions In this section we benchmark the numerical stability of the Padé interpolant of the GX-AC component using three model functions, a 2-pole model, an 8-pole model and the cosine function. A pole in the first two functions refers to a singularity of the function on the real axis of $x$, e.g. the 2-pole model has two of these singularities. In each case, a grid along the imaginary axis $z \in [0i, 1i]$ was used to determine the Padé parameters, followed by the evaluation of 1,000 function values on the real axis $z \in [0 + \eta i, 1 + \eta i]$ using the created Padé model. A small imaginary shift $\eta=0.01$ was introduced to broaden the functions, this helps avoid arbitrarily high function values or singularities in case of the pole models. The 1,000 computed points were then compared to the exact function values of the model functions to assess the mean absolute error. @@ -106,7 +106,7 @@ Evaluating the Padé model (calling `evaluate_thiele_Padé_at()`) scales linear The [*GW* approach](https://doi.org/10.3389/fchem.2019.00377) in many body perturbation theory is used for calculating electronic excitations in photoemission spectroscopy. Padé approximants are used in *GW* to continue analytic functions like the [self-energy](https://dx.doi.org/10.1088/1367-2630/14/5/053020) $\Sigma(\omega)$ or the [screened coulomb interaction](https://doi.org/10.1021/acs.jctc.3c00555) $W(\omega)$ from the imaginary to the real frequency axis. Both, $\Sigma$ and $W$ exhibit poles on the real frequencies axis. Similarly, as for the three model functions, we added a small broadening parameter $i\eta$ when plotting the functions in Fig. 4. -In this test, we present $GW$ calculations using the [FHI-aims](https://fhi-aims.org/) package, which is an all-electron code based on numeric atom-centered orbitals (NAOs). The self-energy or the screened coulomb interaction is interpolated using Padé approximants from the GX-AC component. The G0W0 calculations are performed on top of a preceding DFT calculation with the Perdew-Burke-Ernzerhof (PBE) functional ($G_0W_0$@PBE). We used NAO basis sets of tier 1 quality and 400 imaginary frequency points to obtain the Padé models. For comparison, we reference a G0W0@PBE calculation using the [contour deformation](https://doi.org/10.1021/acs.jctc.8b00458) (CD) approach. The CD technique is more accurate than AC, as it evaluates $\Sigma$ and $W$ directly on the real frequency axis. See [The GW Compendium](https://www.frontiersin.org/journals/chemistry/articles/10.3389/fchem.2019.00377/full) for a comparison of different frequency integration techniques. +In this test, we present *GW* calculations using the [FHI-aims](https://fhi-aims.org/) package, which is an all-electron code based on numeric atom-centered orbitals (NAOs). The self-energy or the screened coulomb interaction is interpolated using Padé approximants from the GX-AC component. The G0W0 calculations are performed on top of a preceding DFT calculation with the Perdew-Burke-Ernzerhof (PBE) functional ($G_0W_0$@PBE). We used NAO basis sets of tier 1 quality and 400 imaginary frequency points to obtain the Padé models. For comparison, we reference a G0W0@PBE calculation using the [contour deformation](https://doi.org/10.1021/acs.jctc.8b00458) (CD) approach. The CD technique is more accurate than AC, as it evaluates $\Sigma$ and $W$ directly on the real frequency axis. See [The *GW* Compendium](https://www.frontiersin.org/journals/chemistry/articles/10.3389/fchem.2019.00377/full) for a comparison of different frequency integration techniques. Figure 4 shows that, regardless of the GX-AC component settings (greedy/non-greedy algorithm and floating-point precision), the self-energy and screened coulomb interaction can be accurately described using Padé approximants. For the self-energy (Fig. 4, left) the analytic continuation slightly deviates from the contour deformation because the error is dominated by the number of Padé parameters. In the case of the screened coulomb interaction (Figure 4, right) all poles are well approximated by the analytic continuation. However, the 128 bit setting performs slightly better than the double precision one when looking at the median absolute error with respect to contour deformation (0.03 eV for 64 bit; 0.02 eV for 128 bit). The analytic continuation of the screened Coulomb interaction using the greedy algorithm performs similarly to the 64 bit setting and is therefore omitted from the plot. diff --git a/docs/index.md b/docs/index.md index 13b5b9f8..1cff9029 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,7 @@ An open-source library that supports exascale implementations of Green's-functio Currently, our library supports the following electronic structure methods: - conventional and low-scaling RPA -- low-scaling \\(GW\\) +- low-scaling *GW* - Laplace-transformed direct MP2 # Components From 1fba977f3a5b714a03c3308d16eb6da84657247d Mon Sep 17 00:00:00 2001 From: moritzleucke Date: Tue, 25 Feb 2025 16:48:39 +0100 Subject: [PATCH 3/3] enable all components explicitely in the pipeline --- .github/workflows/action.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/action.yml b/.github/workflows/action.yml index 199d8dc6..152611b5 100644 --- a/.github/workflows/action.yml +++ b/.github/workflows/action.yml @@ -42,6 +42,10 @@ jobs: mkdir -p build cd build cmake -DENABLE_GREENX_UNIT_TESTS=ON \ + -DAC_COMPONENT=ON \ + -DMINIMAX_COMPONENT=ON \ + -DLBASIS_COMPONENT=ON \ + -DPAW_COMPONENT=ON \ -DGMPXX_INCLUDE_DIR=/usr/include/ \ -DGMPXX_LIBRARY=/usr/lib/x86_64-linux-gnu/libgmpxx.so ../ make -j$(nproc)