Skip to content

Commit 7b07f9f

Browse files
author
dyzheng
committed
Revert PW sigma_y sign fix + doc test analysis
PW basis 2x2 matrix layout differs from LCAO convention: LCAO: coeff[1]=H[up,dn], coeff[2]=H[dn,up] PW: coeff[1]=H[dn,up], coeff[2]=H[up,dn] (kernel: cols swapped) All test energy differences are from deliberate formula changes: - E_lambda = -sum(lambda*(Mi-Mtarget)) instead of -sum(lambda*Mi) - gga_grad=3 SF correction (0.05-0.08 eV for nspin=4) - Remove neg/ux_/lsign_ mechanism (0.016 eV for nspin=4)
1 parent e7ba46c commit 7b07f9f

2,706 files changed

Lines changed: 6651489 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to agentic coding agents working with the ABACUS codebase.
4+
5+
## Build System
6+
7+
ABACUS uses CMake as its build system. The main build configuration is in `CMakeLists.txt` at the root.
8+
9+
### Basic Build Commands
10+
11+
```bash
12+
# Configure with default options (LCAO enabled, MPI enabled)
13+
cmake -B build
14+
15+
# Build with specific number of processors
16+
cmake --build build -j${number_of_processors}
17+
18+
# Install (required before running tests)
19+
cmake --install build
20+
```
21+
22+
### Common Build Options
23+
24+
- `-DBUILD_TESTING=ON` - Enable unit tests (required for testing)
25+
- `-DENABLE_LCAO=ON/OFF` - Enable/disable LCAO calculations (default: ON)
26+
- `-DUSE_CUDA=ON` - Enable CUDA support
27+
- `-DUSE_ROCM=ON` - Enable ROCm/HIP support
28+
- `-DUSE_OPENMP=ON/OFF` - Enable OpenMP (default: ON)
29+
- `-DENABLE_COVERAGE=ON` - Enable code coverage (sets Debug build)
30+
- `-DENABLE_ASAN=ON` - Enable AddressSanitizer (sets RelWithDebInfo build)
31+
- `-DCMAKE_BUILD_TYPE=Debug/Release/RelWithDebInfo` - Build type
32+
- `-DENABLE_DEEPKS=ON` - Enable DeePKS functionality
33+
- `-DENABLE_LIBXC=ON` - Enable LibXC functionality
34+
- `-DUSE_ELPA=ON/OFF` - Enable ELPA diagonalization (default: ON)
35+
- `-DENABLE_LIBRI=ON` - Enable EXX with LibRI
36+
- `-DENABLE_PAW=ON` - Enable PAW calculations
37+
- `-DMKLROOT=$MKLROOT` - Use Intel MKL for math libraries
38+
39+
### Build Variants
40+
41+
The executable name depends on build configuration:
42+
- `abacus` - LCAO enabled, MPI enabled (default)
43+
- `abacus_pw` - LCAO disabled, MPI enabled
44+
- `abacus_serial` - LCAO enabled, MPI disabled
45+
- `abacus_pw_serial` - LCAO disabled, MPI disabled
46+
47+
## Testing
48+
49+
### Unit Tests
50+
51+
Unit tests use GoogleTest framework and are located in `source/*/test` directories.
52+
53+
```bash
54+
# Build with unit tests enabled
55+
cmake -B build -DBUILD_TESTING=ON
56+
cmake --build build -j${nproc}
57+
cmake --install build # REQUIRED before running tests
58+
59+
# Run all tests
60+
cd build
61+
ctest -V
62+
63+
# Run specific test by name
64+
ctest -R <test-name>
65+
66+
# Run tests matching pattern
67+
ctest -R <pattern>
68+
69+
# Build specific unit test
70+
cmake --build build -j${nproc} --target ${unit_test_name}
71+
```
72+
73+
Unit test executables are located in `build/source/${module_name}/test` (or `test_parallel`, `test_pw` for specialized tests).
74+
75+
### Integration Tests
76+
77+
Integration tests are in `tests/integrate/` directory. Each test case is a subdirectory with input files (INPUT, STRU, KPT) and reference results (result.ref).
78+
79+
```bash
80+
# Run all integration tests
81+
cd tests/integrate
82+
bash Autotest.sh
83+
84+
# Run specific test case
85+
cd tests/integrate/<test_case_name>
86+
bash ../Single_job.sh
87+
88+
# Run with custom parameters
89+
bash Autotest.sh -a /path/to/abacus -n 4 -t 0.0000001
90+
91+
# Generate reference results for new test
92+
bash Autotest.sh -g -r <test_case_name>
93+
```
94+
95+
Key Autotest.sh options:
96+
- `-a <path>` - ABACUS executable path (default: abacus)
97+
- `-n <num>` - Number of MPI processes (default: 4)
98+
- `-t <threshold>` - Energy threshold in eV (default: 0.0000001)
99+
- `-c <accuracy>` - Check accuracy (default: 8)
100+
- `-g` - Generate reference results
101+
- `-r <regex>` - Test case name regex filter
102+
- `-f <file>` - Test cases file (default: CASES_CPU.txt)
103+
104+
## Code Style and Formatting
105+
106+
### Formatting
107+
108+
- Use `clang-format` with the `.clang-format` file in root directory
109+
- Based on Microsoft style with customizations
110+
- 4-space indentation, no tabs
111+
- Left-aligned pointers (`int* ptr` not `int *ptr`)
112+
- Sort includes and using declarations
113+
114+
### Documentation
115+
116+
- Doxygen comments for documentation (Javadoc style preferred)
117+
- Comment only in `.h` files for Doxygen visibility
118+
- Use `@param` for parameters, `\f$...\f$` for inline formulas
119+
120+
### Code Conventions
121+
122+
**Naming:**
123+
- Classes: PascalCase (e.g., `HSolver`, `Matrix`)
124+
- Functions: snake_case (e.g., `solve_hamiltonian`, `calculate_energy`)
125+
- Variables: snake_case (e.g., `num_bands`, `ecutwfc`)
126+
- Constants: UPPER_SNAKE_CASE (e.g., `MAX_ITERATIONS`)
127+
- Private members: trailing underscore (e.g., `num_bands_`)
128+
129+
**Imports and Includes:**
130+
- System headers first, then project headers
131+
- Use angle brackets for system headers, quotes for project headers
132+
- Group includes: C standard library, C++ standard library, external libraries, internal headers
133+
- Sort includes alphabetically within groups
134+
135+
**Types:**
136+
- Use `double` for floating-point by default, `float` only when memory is critical
137+
- Use `std::complex<double>` for complex numbers
138+
- Prefer `std::vector` over C-style arrays
139+
- Use `size_t` for sizes and indices
140+
- Use `const` and references where appropriate
141+
142+
**Error Handling:**
143+
- Use assertions (`assert()`) for internal invariants
144+
- Return error codes or use exceptions for recoverable errors
145+
- Log errors using the existing logging infrastructure
146+
- Validate input parameters at function boundaries
147+
148+
**Templates:**
149+
- Use templates for generic algorithms and data structures
150+
- Provide explicit instantiations for common types
151+
- Use `template <>` for specializations
152+
153+
**Memory Management:**
154+
- Use RAII principles with smart pointers (`std::unique_ptr`, `std::shared_ptr`)
155+
- Avoid raw `new`/`delete` when possible
156+
- Follow the Rule of Three/Five for classes managing resources
157+
158+
**Parallelization:**
159+
- Use MPI for distributed memory parallelization
160+
- Use OpenMP for shared memory parallelization
161+
- Follow existing patterns for communicator splitting
162+
- Be careful with global variables in parallel contexts
163+
164+
### Module Structure
165+
166+
The source code is organized into modules under `source/`:
167+
168+
**Core Infrastructure:**
169+
- `module_base/` - Mathematical library interfaces, data structures, parallelization, utilities
170+
- `module_container/` - Container module for data storage and operations
171+
- `module_parameter/` - Input parameters and global variables
172+
173+
**Basis Sets:**
174+
- `module_basis/module_pw/` - Plane wave basis
175+
- `module_basis/module_nao/` - Numerical atomic orbital basis
176+
- `module_basis/module_ao/` - Legacy atomic orbital basis
177+
178+
**Cell and Structure:**
179+
- `module_cell/` - Unit cell definition and operations
180+
- `module_cell/module_neighbor/` - Neighbor finding
181+
- `module_cell/module_symmetry/` - Symmetry operations
182+
183+
**Electronic Structure:**
184+
- `module_elecstate/` - Electronic state definition and operations
185+
- `module_elecstate/module_charge/` - Charge density calculation and mixing
186+
- `module_elecstate/potentials/` - Potential calculations
187+
- `module_psi/` - Wave function definition and operations
188+
189+
**Hamiltonians:**
190+
- `module_hamilt_general/` - General Hamiltonian components
191+
- `module_hamilt_pw/` - PW-specific Hamiltonians
192+
- `module_hamilt_lcao/` - LCAO-specific Hamiltonians
193+
194+
**Solvers and Drivers:**
195+
- `module_hsolver/` - Hamiltonian diagonalization methods
196+
- `module_esolver/` - Task-specific workflow drivers
197+
- `module_md/` - Molecular dynamics
198+
- `module_relax/` - Structural optimization
199+
200+
**I/O:**
201+
- `module_io/` - INPUT file reading and property output
202+
203+
## Development Workflow
204+
205+
### Adding New Features
206+
207+
1. Read relevant source files first before proposing changes
208+
2. Follow existing code patterns in the module
209+
3. Add unit tests in `source/${module}/test/` using GoogleTest
210+
4. Add integration tests in `tests/integrate/` if needed
211+
5. Update CMakeLists.txt if adding new source files or tests
212+
6. Ensure code follows clang-format style
213+
214+
### Important Notes
215+
216+
- Always run `cmake --install build` after building and before running tests
217+
- For PW calculations, set `pw_seed 1` in INPUT file for reproducible tests
218+
- Integration tests should run in < 20 seconds (reduce atoms, k-points, ecutwfc, steps)
219+
- Pseudopotential and orbital files go in `tests/PP_ORB/`
220+
- Use relative paths in INPUT for `pseudo_dir` and `orb_dir`
221+
- The main development branch is `develop`, not `main` or `master`
222+
223+
### Commit Message Format
224+
225+
Follow Conventional Commits specification:
226+
227+
```
228+
<type>[optional scope]: <description>
229+
230+
[optional body]
231+
232+
[optional footer]
233+
```
234+
235+
Types: `Feature`, `Fix`, `Docs`, `Style`, `Refactor`, `Perf`, `Test`, `Build`, `CI`, `Revert`
236+
237+
Example:
238+
```
239+
Fix(lcao): use correct scalapack interface
240+
241+
`pzgemv_` and `pzgemm_` used `double*` for alpha and beta parameters
242+
but not `complex*`, this would cause error in GNU compiler.
243+
244+
Fix #753.
245+
```

0 commit comments

Comments
 (0)