diff --git a/.ci/slurm/README.md b/.ci/slurm/README.md index 53abd6f0a09..89e44941a29 100644 --- a/.ci/slurm/README.md +++ b/.ci/slurm/README.md @@ -1,39 +1,53 @@ # Remote GPU validation -This workflow rebuilds one committed ABACUS revision on a remote GPU cluster, runs the test matrix in `config.ini` through Slurm, and reports each build and test group separately. It is a functional test, not a benchmark. +This workflow rebuilds one committed ABACUS revision on a remote GPU cluster, runs the test matrix +in `config.ini` through Slurm, and reports each build and test group separately. It is a functional +test, not a benchmark. -The maintained setup runs at the [Open Source Supercomputing Center of SAI](https://www.open-sai.com/). The same client can be configured for another Slurm cluster. +The maintained setup runs at the +[Open Source Supercomputing Center of SAI](https://www.open-sai.com/). The same client can be +configured for another Slurm cluster. -**Trust boundary:** the selected commit is compiled and executed as the remote SSH user. Approve only code that may run with that account's permissions. +**Trust boundary:** the selected commit is compiled and executed as the remote SSH user. Approve +only code that may run with that account's permissions. ## Set up GitHub -A repository administrator performs these steps once. Forks start disabled because GitHub does not copy variables or secrets from the parent repository. +A repository administrator performs these steps once. Forks start disabled because GitHub does not +copy variables or secrets from the parent repository. -1. Open **Settings > Secrets and variables > Actions > Variables**, choose **New repository variable**, and set: +1. Open **Settings > Secrets and variables > Actions > Variables**, choose **New repository + variable**, and set: - Name: `GPU_VALIDATION_ENABLED` - Value: `true` - The value is the lowercase text `true`. If this variable is absent or has another value, the workflow skips all remote work. + The value is the lowercase text `true`. If this variable is absent or has another value, the + workflow skips all remote work. -2. Open **Settings > Environments** and create: +1. Open **Settings > Environments** and create: - `gpu-ci-scheduled`, with no required reviewers, for daily tests. - - `gpu-ci-manual`, with the maintainers who may approve PR and manual tests listed as required reviewers. + - `gpu-ci-manual`, with the maintainers who may approve PR and manual tests listed as required + reviewers. -3. Open each environment, choose **Environment secrets > Add environment secret**, and add: +1. Open each environment, choose **Environment secrets > Add environment secret**, and add: - Name: `REMOTE_SSH_PRIVATE_KEY` - Value: the complete private key, including its `BEGIN` and `END` lines. - Install the matching public key in `authorized_keys` for the remote account named in `config.ini`. Add the private key to both environments because they have different approval rules. Do not create a repository-level SSH secret; the workflow reads this environment secret only after entering the selected environment. + Install the matching public key in `authorized_keys` for the remote account named in + `config.ini`. Add the private key to both environments because they have different approval + rules. Do not create a repository-level SSH secret; the workflow reads this environment secret + only after entering the selected environment. -Host, port, user, and the normal remote project directory are read from the trusted `[remote]` section of `config.ini`. +Host, port, user, and the normal remote project directory are read from the trusted `[remote]` +section of `config.ini`. ## Run validation -All GitHub methods below require `GPU_VALIDATION_ENABLED=true`. The workflow must already be present on the repository's default branch. +All GitHub methods below require `GPU_VALIDATION_ENABLED=true`. The workflow must already be present +on the repository's default branch. ### Test a pull request @@ -43,25 +57,32 @@ On an open pull request, add this exact comment: /abacus-ci gpu ``` -The comment cannot contain other text. The author of the comment needs Triage, Write, Maintain, or Admin permission. The bot immediately posts a link to the queued Actions run. After a reviewer approves the `gpu-ci-manual` environment, the workflow tests the PR head commit and updates that same bot comment with the result and raw-file link. +The comment cannot contain other text. The author of the comment needs Triage, Write, Maintain, or +Admin permission. The bot immediately posts a link to the queued Actions run. After a reviewer +approves the `gpu-ci-manual` environment, the workflow tests the PR head commit and updates that +same bot comment with the result and raw-file link. ### Run the daily test -No manual action is needed. The workflow is scheduled every day at 20:30 UTC (`30 20 * * *`). It tests the current default branch of `deepmodeling/abacus-develop` and uses `gpu-ci-scheduled`, so it does not wait for approval. +No manual action is needed. The workflow is scheduled every day at 20:30 UTC (`30 20 * * *`). It +tests the current default branch of `deepmodeling/abacus-develop` and uses `gpu-ci-scheduled`, so it +does not wait for approval. ### Start a run from Actions 1. Open **Actions > GPU validation > Run workflow**. -2. Select the repository default branch under **Use workflow from**. -3. Enter the full, lowercase 40-character commit SHA in `source_sha`. -4. Leave `project_root` empty to use `config.ini`, or enter another permitted remote directory. -5. Start the run and approve the `gpu-ci-manual` environment when prompted. +1. Select the repository default branch under **Use workflow from**. +1. Enter the full, lowercase 40-character commit SHA in `source_sha`. +1. Leave `project_root` empty to use `config.ini`, or enter another permitted remote directory. +1. Start the run and approve the `gpu-ci-manual` environment when prompted. -The commit must exist in the repository where the workflow is running. For an external contributor's pull request, use the PR comment command instead. +The commit must exist in the repository where the workflow is running. For an external contributor's +pull request, use the PR comment command instead. ### Run from a local checkout -Create an SSH host entry. The default alias is `gpu-ci`; use the host, port, user, and key for your account: +Create an SSH host entry. The default alias is `gpu-ci`; use the host, port, user, and key for your +account: ```sshconfig Host gpu-ci @@ -77,9 +98,15 @@ Then run this command from a committed ABACUS checkout: python3 .ci/slurm/runner.py run ``` -By default, the command uses the checkout's committed `HEAD`, `~/.ssh/config`, the `gpu-ci` alias, and the remote directory from `config.ini`. Uncommitted candidate-source changes are not sent. The local command does use the current `.ci/slurm` control files, including local changes to its scripts and templates. The command waits for Slurm, prints live build and test progress, downloads the results, and exits nonzero if validation fails. +By default, the command uses the checkout's committed `HEAD`, `~/.ssh/config`, the `gpu-ci` alias, +and the remote directory from `config.ini`. Uncommitted candidate-source changes are not sent. The +local command does use the current `.ci/slurm` control files, including local changes to its scripts +and templates. The command waits for Slurm, prints live build and test progress, downloads the +results, and exits nonzero if validation fails. -Local results go to `/tmp/abacus_gpu_ci_//_/`. Use `--artifacts` for a permanent local directory or `--target my-cluster` for another SSH alias. All available options and defaults are shown by: +Local results go to `/tmp/abacus_gpu_ci_//_/`. Use `--artifacts` +for a permanent local directory or `--target my-cluster` for another SSH alias. All available +options and defaults are shown by: ```bash python3 .ci/slurm/runner.py --help @@ -90,14 +117,28 @@ python3 .ci/slurm/runner.py run --help `config.ini` is validated before jobs are submitted. -- `[site]`: the resource acknowledgement, site name, and public URL shown at the end of result reports. Change these values for another cluster. -- `[remote]`: SSH `host`, `port`, `user`, `project_root`, and comma-separated `allowed_project_roots`. The project root may use `~/` or an absolute path, but its remote resolved path must be below one of the allowed roots. Prefixes are also resolved remotely, so aliases such as `/home` pointing to `/org` are accepted. -- `[cluster]`: Slurm `partition`, absolute `mapping_root` for the MPI mapping script, `disable_nccl_ib` (`true` or `false`), and `poll_seconds` (1-300). +- `[site]`: the resource acknowledgement, site name, and public URL shown at the end of result + reports. Change these values for another cluster. +- `[remote]`: SSH `host`, `port`, `user`, `project_root`, and comma-separated + `allowed_project_roots`. The project root may use `~/` or an absolute path, but its remote + resolved path must be below one of the allowed roots. Prefixes are also resolved remotely, so + aliases such as `/home` pointing to `/org` are accepted. +- `[cluster]`: Slurm `partition`, absolute `mapping_root` for the MPI mapping script, + `disable_nccl_ib` (`true` or `false`), and `poll_seconds` (1-300). - `[build]`: build-job `qos`, `nodes`, `tasks_per_node`, `gpus_per_node`, and `time_seconds`. -- `[resource.NAME]`: the same allocation fields plus `parallelism`, the maximum number of array tasks running at once. Each resource must have a case. There is one rank per GPU and no resource may exceed 16 GPUs. -- `[case.NNN]`: contiguous, zero-padded sections with `suite`, `name`, `resource`, and `runner` (`autotest`, `autotest_gpu`, or `cusolvermp`). `autotest_gpu` copies the case into an isolated working directory and changes only `device` to `gpu` before running the normal reference comparisons. - -Resource labels are generated, not configured separately. A single-node resource is shown as `N GPU` or `N GPUs`; a multi-node resource is shown as `N nodes / M GPUs`. Thus `gpu1`, `gpu2`, and `gpu4` display `1 GPU`, `2 GPUs`, and `4 GPUs`; `gpu4x2` displays `2 nodes / 8 GPUs`. Test results are reported by their `tests/` folder even though Slurm arrays remain grouped by resource. `case.049` is `05_rtTDDFT/00_NO_Si48_CUSOLVERMP_TDDFT_GPU`; it uses `gpu4x2` and the `cusolvermp` runner. +- `[resource.NAME]`: the same allocation fields plus `parallelism`, the maximum number of array + tasks running at once. Each resource must have a case. There is one rank per GPU and no resource + may exceed 16 GPUs. +- `[case.NNN]`: contiguous, zero-padded sections with `suite`, `name`, `resource`, and `runner` + (`autotest`, `autotest_gpu`, or `cusolvermp`). `autotest_gpu` copies the case into an isolated + working directory and changes only `device` to `gpu` before running the normal reference + comparisons. + +Resource labels are generated, not configured separately. A single-node resource is shown as `N GPU` +or `N GPUs`; a multi-node resource is shown as `N nodes / M GPUs`. Thus `gpu1`, `gpu2`, and `gpu4` +display `1 GPU`, `2 GPUs`, and `4 GPUs`; `gpu4x2` displays `2 nodes / 8 GPUs`. Test results are +reported by their `tests/` folder even though Slurm arrays remain grouped by resource. `case.049` is +`05_rtTDDFT/00_NO_Si48_CUSOLVERMP_TDDFT_GPU`; it uses `gpu4x2` and the `cusolvermp` runner. ## Results and retention @@ -107,24 +148,48 @@ On the remote cluster, a run is created below: /runs//-/ ``` -Its `results/` directory contains `result.json`, `summary.md`, build and case logs, Slurm output, module/tool records, and status files. The coordinator and working data are alongside it while the run is active. After results are collected, the client archives `results/` and `jobs/` as: +Its `results/` directory contains `result.json`, `summary.md`, build and case logs, Slurm output, +module/tool records, and status files. The coordinator and working data are alongside it while the +run is active. After results are collected, the client archives `results/` and `jobs/` as: ``` /archives//-.tar.gz ``` -The client removes archived files older than 72 hours when preparing a later run, and removes the active run after archiving. On the GitHub runner, `ARTIFACT_ROOT` is `${runner.temp}/gpu-ci-artifacts`; it contains the collected `results/`, `run.json`, and `client.log`. CI uploads that directory as `gpu-validation--` and retains it for 30 days. A pull-request comment links to the Actions run and the uploaded raw files. If the client stops before completion, the remote run is left in place so that its detached coordinator and Slurm jobs are not interrupted. +The client removes archived files older than 72 hours when preparing a later run, and removes the +active run after archiving. On the GitHub runner, `ARTIFACT_ROOT` is +`${runner.temp}/gpu-ci-artifacts`; it contains the collected `results/`, `run.json`, and +`client.log`. CI uploads that directory as `gpu-validation--` and retains it for 30 +days. A pull-request comment links to the Actions run and the uploaded raw files. If the client +stops before completion, the remote run is left in place so that its detached coordinator and Slurm +jobs are not interrupted. -Source is sent as a compressed Git bundle. The remote Git cache keeps the three most recent PR or manual revisions, the latest two daily dates, the first daily revision of every UTC month, and one weekly revision for the current month. Weekly revisions from earlier months are removed. Concurrent runs reserve the cache revisions they use, so another run cannot remove their transfer base. +Source is sent as a compressed Git bundle. The remote Git cache keeps the three most recent PR or +manual revisions, the latest two daily dates, the first daily revision of every UTC month, and one +weekly revision for the current month. Weekly revisions from earlier months are removed. Concurrent +runs reserve the cache revisions they use, so another run cannot remove their transfer base. ## Troubleshooting -**SSH fails.** Check the `[remote]` values in `config.ini`, that the key matches the configured account, and that the target is reachable. CI uses the committed `.ci/slurm/known_hosts` with strict host-key checking. Test the same target with the SSH config before retrying; do not disable host-key checking. +**SSH fails.** Check the `[remote]` values in `config.ini`, that the key matches the configured +account, and that the target is reachable. CI uses the committed `.ci/slurm/known_hosts` with strict +host-key checking. Test the same target with the SSH config before retrying; do not disable host-key +checking. -**A module cannot be loaded.** `modules.sh` sources Lmod, purges modules, and loads `cmake/3.31.6` and the configured ABACUS dependency module. Ask the site administrator to provide or update those modules. Modules provide the compiler, CUDA, MPI, and library dependencies; do not add library paths to CI (`LD_LIBRARY_PATH`, `CPATH`, or `CMAKE_PREFIX_PATH`) or hard-code site paths. +**A module cannot be loaded.** `modules.sh` sources Lmod, purges modules, and loads `cmake/3.31.6` +and the configured ABACUS dependency module. Ask the site administrator to provide or update those +modules. Modules provide the compiler, CUDA, MPI, and library dependencies; do not add library paths +to CI (`LD_LIBRARY_PATH`, `CPATH`, or `CMAKE_PREFIX_PATH`) or hard-code site paths. -**CMake or linking fails.** Inspect `results/configure.log`, `build.log`, `install.log`, `CMakeCache.txt`, `tools.txt`, and `ldd.txt`. The build uses Unix Makefiles, CUDA architecture 70, CUDA MPI, cuSOLVERMP, cuBLASMP, and NCCL parallel-device options. A missing runtime library causes the `ldd` check to fail; fix the module environment rather than adding a CI path. +**CMake or linking fails.** Inspect `results/configure.log`, `build.log`, `install.log`, +`CMakeCache.txt`, `tools.txt`, and `ldd.txt`. The build uses Unix Makefiles, CUDA architecture 70, +CUDA MPI, cuSOLVERMP, cuBLASMP, and NCCL parallel-device options. A missing runtime library causes +the `ldd` check to fail; fix the module environment rather than adding a CI path. -**A job stays pending or times out.** Check the selected partition and QoS, GPU availability, node and task limits, and the `time_seconds` value for that resource. Slurm output is in `results/`; an allocation or queue delay is an infrastructure issue, not a case failure. +**A job stays pending or times out.** Check the selected partition and QoS, GPU availability, node +and task limits, and the `time_seconds` value for that resource. Slurm output is in `results/`; an +allocation or queue delay is an infrastructure issue, not a case failure. -**MPI/PMIx initialization fails.** Both runners retry once after a recognized MPI startup failure. If it persists, inspect the attempt logs and the loaded MPI module, Slurm allocation, and mapping file. +**MPI/PMIx initialization fails.** Both runners retry once after a recognized MPI startup failure. +If it persists, inspect the attempt logs and the loaded MPI module, Slurm allocation, and mapping +file. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index afe203f9a91..53f2cbba82b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,15 +1,14 @@ # ABACUS Copilot Instructions -Before generating code or reviewing pull requests in this repository, follow -the ABACUS development baseline in: +Before generating code or reviewing pull requests in this repository, follow the ABACUS development +baseline in: - `AGENTS.md` - `docs/developers_guide/agent_governance.md` -Treat `AGENTS.md` as the short entry point and -`docs/developers_guide/agent_governance.md` as the complete rule source. Review -the pull request diff before general style feedback, and separate blocking -diff-scoped issues from historical or advisory observations. +Treat `AGENTS.md` as the short entry point and `docs/developers_guide/agent_governance.md` as the +complete rule source. Review the pull request diff before general style feedback, and separate +blocking diff-scoped issues from historical or advisory observations. Use the ABACUS review finding format for actionable findings: diff --git a/.github/instructions/abacus-governance.instructions.md b/.github/instructions/abacus-governance.instructions.md index 6695b1b8d6e..864810c376a 100644 --- a/.github/instructions/abacus-governance.instructions.md +++ b/.github/instructions/abacus-governance.instructions.md @@ -1,37 +1,34 @@ ---- -applyTo: "**" ---- +______________________________________________________________________ + +## applyTo: "\*\*" # ABACUS Governance Review Instructions Apply these instructions when reviewing or changing ABACUS code: -- Use `AGENTS.md` and `docs/developers_guide/agent_governance.md` as the - authoritative project baseline. -- Keep review scope diff-oriented: new files, diff-added lines, new includes, - newly introduced symbols, and changed text files for line-ending checks. -- Do not treat untouched historical debt as a default blocker. Mention it only - when it affects the changed area, and label it as advisory. -- Flag PRs that increase `GlobalV`, `GlobalC`, or `PARAM` code references as - blocker-level governance issues. Flag migration-neutral added usage as a - warning that requires reason, scope, risk, and cleanup/follow-up rationale. - Prefer explicit dependencies or narrow local interfaces. -- Flag new default arguments in existing header interfaces. Prefer explicit - call-site updates, overloads, or a clearer configuration object. -- Review header include growth and `.hpp` propagation carefully. These are - usually warnings unless the PR records a narrow reason. -- Require LF line endings for text files. `.bat` and `.cmd` files are the CRLF - exceptions. -- Flag new `#pragma once` in header files as a blocker-level governance issue. - Require traditional `#ifndef`/`#define`/`#endif` include guards instead. -- For INPUT parameter behavior changes, require corresponding C++ `Input_Item` - metadata updates, or a clear no-update explanation in the PR. Do not require - generated YAML or Markdown documentation files to be committed. -- Check that new source files are linked through the relevant `CMakeLists.txt` - unless the PR explains generated or indirect inclusion. +- Use `AGENTS.md` and `docs/developers_guide/agent_governance.md` as the authoritative project + baseline. +- Keep review scope diff-oriented: new files, diff-added lines, new includes, newly introduced + symbols, and changed text files for line-ending checks. +- Do not treat untouched historical debt as a default blocker. Mention it only when it affects the + changed area, and label it as advisory. +- Flag PRs that increase `GlobalV`, `GlobalC`, or `PARAM` code references as blocker-level + governance issues. Flag migration-neutral added usage as a warning that requires reason, scope, + risk, and cleanup/follow-up rationale. Prefer explicit dependencies or narrow local interfaces. +- Flag new default arguments in existing header interfaces. Prefer explicit call-site updates, + overloads, or a clearer configuration object. +- Review header include growth and `.hpp` propagation carefully. These are usually warnings unless + the PR records a narrow reason. +- Require LF line endings for text files. `.bat` and `.cmd` files are the CRLF exceptions. +- Flag new `#pragma once` in header files as a blocker-level governance issue. Require traditional + `#ifndef`/`#define`/`#endif` include guards instead. +- For INPUT parameter behavior changes, require corresponding C++ `Input_Item` metadata updates, or + a clear no-update explanation in the PR. Do not require generated YAML or Markdown documentation + files to be committed. +- Check that new source files are linked through the relevant `CMakeLists.txt` unless the PR + explains generated or indirect inclusion. - Keep default C++ changes compatible with the repository C++11 baseline. -- Ask for focused tests or explicit test rationale for feature changes, bug - fixes, INPUT behavior changes, heterogeneous kernels, and core-module - refactors. -- Treat CI governance findings as deterministic evidence and semantic review - findings as advisory until maintainers approve them. +- Ask for focused tests or explicit test rationale for feature changes, bug fixes, INPUT behavior + changes, heterogeneous kernels, and core-module refactors. +- Treat CI governance findings as deterministic evidence and semantic review findings as advisory + until maintainers approve them. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 83c986d168c..0eaf47cdfa6 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,24 +1,30 @@ ### Reminder + - [ ] I have read `AGENTS.md` and `docs/developers_guide/agent_governance.md`. - [ ] I have linked an issue or explained why this PR does not need one. - [ ] I have added adequate unit tests and/or case tests, or explained why not. - [ ] I have listed the exact verification commands run and their results. - [ ] I have described user-visible behavior changes, including INPUT parameter changes. -- [ ] I have explained core-module impact for ESolver, HSolver, ElecState, Hamilt, Operator, Psi, or other `source/` changes. +- [ ] I have explained core-module impact for ESolver, HSolver, ElecState, Hamilt, Operator, Psi, or + other `source/` changes. - [ ] I have requested any needed governance exception below. ### Linked Issue + Fix # ### Unit Tests and/or Case Tests for my changes + - Commands run: - Result summary: - Checks not run, with reason: ### What's changed? + - Example: brief summary of the user-visible or developer-facing change. ### Governance Notes + - INPUT/docs changes: - Core module impact: - Exceptions requested: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b94491ca55f..fb233792263 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -15,6 +15,13 @@ repos: hooks: - id: cmake-format additional_dependencies: [pyyaml] + - repo: https://github.com/executablebooks/mdformat + rev: 1.0.0 + hooks: + - id: mdformat + args: [--wrap, "100"] + additional_dependencies: + - mdformat-gfm - repo: local hooks: - id: abacus-agent-governance diff --git a/AGENTS.md b/AGENTS.md index 0705adefe89..75a7c86d933 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,171 +1,150 @@ # ABACUS Agent Instructions -This file is the entry point for AI agents, automated review tools, and human -contributors who want the short operational version of the ABACUS development -rules. Read the complete governance document before making or reviewing changes: +This file is the entry point for AI agents, automated review tools, and human contributors who want +the short operational version of the ABACUS development rules. Read the complete governance document +before making or reviewing changes: - `docs/developers_guide/agent_governance.md` ## Required Baseline - Follow the nine ABACUS coding rules summarized from the project governance: - 1. Do not increase cross-layer control through `GlobalV`, `GlobalC`, or - `PARAM`; pass dependencies explicitly where practical. Migration-neutral - moves must keep the PR-level global dependency budget non-increasing and - explain the remaining global usage. - 2. Do not hide workflow switches in mutable member variables that can be - changed from multiple places. - 3. Keep header dependencies minimal. - 4. Avoid adding `.hpp` implementation headers or propagating them through - other headers unless there is a narrow reason. - 5. Do not add default arguments to existing interfaces; update call sites or - design a clearer extension. - 6. Add focused tests for key features, bug fixes, INPUT behavior changes, - heterogeneous kernels, and core-module refactors. - 7. Keep code compatible with the repository C++11 baseline. - 8. Declare one variable per line; do not use comma-separated declarations. - 9. Do not call MPI routines directly; use the internally-guarded wrappers - (e.g., `Parallel_Reduce::reduce_*`, `Parallel_Common::bcast_*`) instead. - 10. Do not write new `#define private public` or `#define protected public` - access hacks in test files; the governance checker **blocks** a net - increase. These macros reinterpret access control for every declaration - in the translation unit -- standard library headers included -- and make - the test TU disagree with the rest of the build. The usual root cause is - that the code under test reads global `PARAM` itself, so the test has to - reach in to drive it; the fix is to pass those INPUT values as explicit - arguments (see `Relax_Criteria` and `K_Vectors::read_kpoints`). Where the - test genuinely needs internal state, add a public `const` observer, or an - explicit `friend class XxxTest;` on the class under test. - 11. New unit test source files shall be named `test_.cpp`, - matching the source file they exercise. For example, the test for - `rhog_io.cpp` shall be `test_rhog_io.cpp`. This naming keeps the - file-to-test relationship discoverable and consistent across the - repository. Historical tests are not required to be renamed. - 12. Place `ModuleBase::timer::start`/`end` at the beginning and end of a - function, not around isolated statements inside the function body. Use - the enclosing function name (or constructor name) as the timer label so - the timer scopes the whole unit of work. - 13. Do not call non-trivial functions inside a constructor's member - initializer list (e.g., `member(compute_something(...))`); limit the - initializer list to direct parameter passthrough. Perform multi-step - computations in the constructor body instead, so failures are easy to - debug and each intermediate result is inspectable. - 14. Do not write conditional or computed expressions in a function's - argument list; first assign the value to a named local variable, then - pass that variable. This keeps each argument inspectable and makes the - call site self-documenting. For example, prefer - `const int isk = (nspin == 2 && isk_ptr) ? isk_ptr[ik] : 0;` - followed by `f(..., isk, ...)` over inlining the ternary into the call. - 15. Do not use `#pragma once` in header files; use traditional - `#ifndef`/`#define`/`#endif` include guards instead. - 16. When reading a file, print a one-line confirmation with its full path to - both stdout and the running log; when creating or overwriting a file, - print the same confirmation to the running log. - 17. Do not create or delete files or directories from inside a unit test - via shell calls (`std::system("mkdir")`, `std::system("rm")`); scratch - files shall be written to `testing::TempDir()` rather than the working - directory. Direct library calls (`std::remove`, - `std::filesystem::remove_all`) on test-written files are acceptable. - 18. Do not use non-reentrant C standard library functions that return - pointers to static internal buffers (`std::localtime`, `std::gmtime`, - `std::asctime`, `std::ctime`, `std::strtok`, etc.) in new or modified - code; use the `_r` suffix variants or equivalent thread-safe - alternatives instead. - 19. When reading structured numerical data from user-supplied files, check - the stream state (`fail()`/`eof()`) after extraction and abort with a - diagnostic message on malformed input rather than silently defaulting - to zero. - 20. Do not introduce new `#define` macros without approval. Include - guards and `#ifdef`/`#ifndef` usages of existing macros are exempt. - 21. Do not initialize member variables from `PARAM` in `.h`/`.hpp` - files; pass the value through the constructor or a setter instead. + 1. Do not increase cross-layer control through `GlobalV`, `GlobalC`, or `PARAM`; pass dependencies + explicitly where practical. Migration-neutral moves must keep the PR-level global dependency + budget non-increasing and explain the remaining global usage. + 1. Do not hide workflow switches in mutable member variables that can be changed from multiple + places. + 1. Keep header dependencies minimal. + 1. Avoid adding `.hpp` implementation headers or propagating them through other headers unless + there is a narrow reason. + 1. Do not add default arguments to existing interfaces; update call sites or design a clearer + extension. + 1. Add focused tests for key features, bug fixes, INPUT behavior changes, heterogeneous kernels, + and core-module refactors. + 1. Keep code compatible with the repository C++11 baseline. + 1. Declare one variable per line; do not use comma-separated declarations. + 1. Do not call MPI routines directly; use the internally-guarded wrappers (e.g., + `Parallel_Reduce::reduce_*`, `Parallel_Common::bcast_*`) instead. + 1. Do not write new `#define private public` or `#define protected public` access hacks in test + files; the governance checker **blocks** a net increase. These macros reinterpret access + control for every declaration in the translation unit -- standard library headers included -- + and make the test TU disagree with the rest of the build. The usual root cause is that the code + under test reads global `PARAM` itself, so the test has to reach in to drive it; the fix is to + pass those INPUT values as explicit arguments (see `Relax_Criteria` and + `K_Vectors::read_kpoints`). Where the test genuinely needs internal state, add a public `const` + observer, or an explicit `friend class XxxTest;` on the class under test. + 1. New unit test source files shall be named `test_.cpp`, matching the source file + they exercise. For example, the test for `rhog_io.cpp` shall be `test_rhog_io.cpp`. This naming + keeps the file-to-test relationship discoverable and consistent across the repository. + Historical tests are not required to be renamed. + 1. Place `ModuleBase::timer::start`/`end` at the beginning and end of a function, not around + isolated statements inside the function body. Use the enclosing function name (or constructor + name) as the timer label so the timer scopes the whole unit of work. + 1. Do not call non-trivial functions inside a constructor's member initializer list (e.g., + `member(compute_something(...))`); limit the initializer list to direct parameter passthrough. + Perform multi-step computations in the constructor body instead, so failures are easy to debug + and each intermediate result is inspectable. + 1. Do not write conditional or computed expressions in a function's argument list; first assign + the value to a named local variable, then pass that variable. This keeps each argument + inspectable and makes the call site self-documenting. For example, prefer + `const int isk = (nspin == 2 && isk_ptr) ? isk_ptr[ik] : 0;` followed by `f(..., isk, ...)` + over inlining the ternary into the call. + 1. Do not use `#pragma once` in header files; use traditional `#ifndef`/`#define`/`#endif` include + guards instead. + 1. When reading a file, print a one-line confirmation with its full path to both stdout and the + running log; when creating or overwriting a file, print the same confirmation to the running + log. + 1. Do not create or delete files or directories from inside a unit test via shell calls + (`std::system("mkdir")`, `std::system("rm")`); scratch files shall be written to + `testing::TempDir()` rather than the working directory. Direct library calls (`std::remove`, + `std::filesystem::remove_all`) on test-written files are acceptable. + 1. Do not use non-reentrant C standard library functions that return pointers to static internal + buffers (`std::localtime`, `std::gmtime`, `std::asctime`, `std::ctime`, `std::strtok`, etc.) in + new or modified code; use the `_r` suffix variants or equivalent thread-safe alternatives + instead. + 1. When reading structured numerical data from user-supplied files, check the stream state + (`fail()`/`eof()`) after extraction and abort with a diagnostic message on malformed input + rather than silently defaulting to zero. + 1. Do not introduce new `#define` macros without approval. Include guards and `#ifdef`/`#ifndef` + usages of existing macros are exempt. + 1. Do not initialize member variables from `PARAM` in `.h`/`.hpp` files; pass the value through + the constructor or a setter instead. - Use LF line endings for text files. Only `.bat` and `.cmd` files may use CRLF. -- Keep source file additions deterministic: update the relevant `CMakeLists.txt` - or explain why the file is generated or included indirectly. -- Report the exact verification performed. Do not claim completion without - fresh test or check output. -- For multi-step refactors (e.g., splitting a large `.cpp` into several - files), build and commit after each step rather than batching all changes - before verification. This keeps the blast radius small when a step - surfaces a missing include or instantiation error. -- Prefer `std::vector` over raw `new`/`delete` for dynamic arrays; before - converting class members, confirm no external code consumes them as raw - pointers (e.g., `std::vector` has no `.data()`), and use - `std::fill`/`std::copy` instead of `ZEROS`/`COPYARRAY` on vector buffers. +- Keep source file additions deterministic: update the relevant `CMakeLists.txt` or explain why the + file is generated or included indirectly. +- Report the exact verification performed. Do not claim completion without fresh test or check + output. +- For multi-step refactors (e.g., splitting a large `.cpp` into several files), build and commit + after each step rather than batching all changes before verification. This keeps the blast radius + small when a step surfaces a missing include or instantiation error. +- Prefer `std::vector` over raw `new`/`delete` for dynamic arrays; before converting class members, + confirm no external code consumes them as raw pointers (e.g., `std::vector` has no + `.data()`), and use `std::fill`/`std::copy` instead of `ZEROS`/`COPYARRAY` on vector buffers. ## Repository Map -- Core C++ implementation lives under `source/`; source additions must be wired - through the relevant `CMakeLists.txt`. -- INPUT parsing and help metadata live under `source/source_io/`; user-facing - INPUT reference is generated from that metadata during the documentation - build. -- Unit tests are colocated under module `test/` directories such as - `source/source_md/test/`; integration and workflow tests are selected through - CTest labels and patterns. -- Developer and user build/install references live in `docs/quick_start/`, - `docs/advanced/`, `toolchain/`, `Dockerfile.gnu`, `Dockerfile.intel`, and - `Dockerfile.cuda`. +- Core C++ implementation lives under `source/`; source additions must be wired through the relevant + `CMakeLists.txt`. +- INPUT parsing and help metadata live under `source/source_io/`; user-facing INPUT reference is + generated from that metadata during the documentation build. +- Unit tests are colocated under module `test/` directories such as `source/source_md/test/`; + integration and workflow tests are selected through CTest labels and patterns. +- Developer and user build/install references live in `docs/quick_start/`, `docs/advanced/`, + `toolchain/`, `Dockerfile.gnu`, `Dockerfile.intel`, and `Dockerfile.cuda`. ## File Move / Split Checklist When moving, splitting, or deleting a `.cpp`/`.h`, update **all** build surfaces: 1. `source/Makefile.Objects` (legacy Makefile object lists) -2. All C++ `CMakeLists.txt` -3. `python/pyabacus/src/*/CMakeLists.txt` โ€” pyabacus has independent hardcoded source lists that do not track the main CMake build +1. All C++ `CMakeLists.txt` +1. `python/pyabacus/src/*/CMakeLists.txt` โ€” pyabacus has independent hardcoded source lists that do + not track the main CMake build -When splitting a function into a new `.cpp`, if its callers span LCAO and PW, put it in an unconditionally-built OBJECT library, not inside `if(ENABLE_LCAO)`. +When splitting a function into a new `.cpp`, if its callers span LCAO and PW, put it in an +unconditionally-built OBJECT library, not inside `if(ENABLE_LCAO)`. ## Build And Test Entry Points -- Prefer the repository CMake/CTest flow already used by CI. For focused local - checks, use commands such as `ctest --test-dir build -V -R MODULE_MD` after a - usable build exists. -- For INPUT-related changes, verify both documentation and CLI behavior when an - executable is available: `./build/abacus -h ` and - `./build/abacus --check-input` from a valid case directory. -- For executable identity, record `./build/abacus --version` or the equivalent - installed `abacus --version` command used during verification. -- Reuse existing Docker and toolchain assets. Do not add a new container, - compiler setup, or calculation-task skill unless the PR explicitly requires - and justifies it. +- Prefer the repository CMake/CTest flow already used by CI. For focused local checks, use commands + such as `ctest --test-dir build -V -R MODULE_MD` after a usable build exists. +- For INPUT-related changes, verify both documentation and CLI behavior when an executable is + available: `./build/abacus -h ` and `./build/abacus --check-input` from a valid case + directory. +- For executable identity, record `./build/abacus --version` or the equivalent installed + `abacus --version` command used during verification. +- Reuse existing Docker and toolchain assets. Do not add a new container, compiler setup, or + calculation-task skill unless the PR explicitly requires and justifies it. ## Local Runtime Testing -- Set `OMP_NUM_THREADS=1` for ABACUS runtime, integration, and MPI tests unless - a test explicitly requires another value. -- Run MPI/runtime tests outside restricted sandboxes when process visibility, - sockets, or MPI launch behavior matters. -- Treat OpenMPI `opal_ifinit: socket() failed errno=1` warnings from sandboxed - MPI-linked builds or runs as expected sandbox artifacts; rerun outside the - sandbox before treating them as ABACUS failures. -- Do not relax existing tests or references merely to make a failure pass. - Update references only when the intended behavior changed and the PR explains - why. +- Set `OMP_NUM_THREADS=1` for ABACUS runtime, integration, and MPI tests unless a test explicitly + requires another value. +- Run MPI/runtime tests outside restricted sandboxes when process visibility, sockets, or MPI launch + behavior matters. +- Treat OpenMPI `opal_ifinit: socket() failed errno=1` warnings from sandboxed MPI-linked builds or + runs as expected sandbox artifacts; rerun outside the sandbox before treating them as ABACUS + failures. +- Do not relax existing tests or references merely to make a failure pass. Update references only + when the intended behavior changed and the PR explains why. ## Review And Exception Flow -- Mechanical blockers are enforced by hook and CI only for new files, changed - files, or diff-added lines. Historical untouched code is not a default blocker. -- Warnings from CI or AI review require reviewer attention but do not block by - themselves. -- Semantic questions such as module ownership, member-variable workflow state, - test sufficiency, and exception approval require human review. -- Exceptions must be recorded in the PR with reason, scope, risk, and a follow-up - cleanup plan. -- After a refactor, propose brief lessons worth recording in this file, then - ask the developer whether to write them in; be cautious and skip unclear - or unverified lessons. +- Mechanical blockers are enforced by hook and CI only for new files, changed files, or diff-added + lines. Historical untouched code is not a default blocker. +- Warnings from CI or AI review require reviewer attention but do not block by themselves. +- Semantic questions such as module ownership, member-variable workflow state, test sufficiency, and + exception approval require human review. +- Exceptions must be recorded in the PR with reason, scope, risk, and a follow-up cleanup plan. +- After a refactor, propose brief lessons worth recording in this file, then ask the developer + whether to write them in; be cautious and skip unclear or unverified lessons. ## Refactoring Patterns -- Member -> free function: inventory `this->` reads; pass as params (const - for config, ref for mutable state); move only when body is `this`-free; - keep thin wrapper; compile each step. -- Extract a base-class nested-vector member in three steps (hold + forward, - switch writers, delete legacy) so no commit mixes old-storage writes with - new-storage reads. +- Member -> free function: inventory `this->` reads; pass as params (const for config, ref for + mutable state); move only when body is `this`-free; keep thin wrapper; compile each step. +- Extract a base-class nested-vector member in three steps (hold + forward, switch writers, delete + legacy) so no commit mixes old-storage writes with new-storage reads. ## Local Commands @@ -177,32 +156,28 @@ pre-commit run abacus-agent-governance --all-files python3 tools/03_code_analysis/code_quality_score.py $(git diff --name-only upstream/develop...HEAD | grep -E '\.(cpp|h)$') ``` -The repository text files have been normalized to LF once. Day-to-day line -ending enforcement should rely on staged/changed-file hooks and CI; rerun the -full mixed-line-ending hook only for intentional repository-wide normalization. +The repository text files have been normalized to LF once. Day-to-day line ending enforcement should +rely on staged/changed-file hooks and CI; rerun the full mixed-line-ending hook only for intentional +repository-wide normalization. ## Upstream Repository - Repository: https://github.com/deepmodeling/abacus-develop - Issues: https://github.com/deepmodeling/abacus-develop/issues - Pull requests: https://github.com/deepmodeling/abacus-develop/pulls -- Upstream PRs are opened from personal fork branches - (`:` into `develop`). -- When synchronizing a local branch with `upstream/develop`, prefer - `git merge upstream/develop` over `git rebase upstream/develop`. Merge - preserves the original commit SHAs of the local work, keeps the branch - pushable without `--force`, and avoids re-applying a long patch series - when conflicts arise. Use rebase only when the user explicitly asks for - a linear history. -- `workflow_dispatch`-only workflows (e.g. `.github/workflows/interface.yml`) - are not triggered by push/PR events; PR CI cannot verify such fixes, so - state "manual dispatch run required" in the PR verification notes. +- Upstream PRs are opened from personal fork branches (`:` into `develop`). +- When synchronizing a local branch with `upstream/develop`, prefer `git merge upstream/develop` + over `git rebase upstream/develop`. Merge preserves the original commit SHAs of the local work, + keeps the branch pushable without `--force`, and avoids re-applying a long patch series when + conflicts arise. Use rebase only when the user explicitly asks for a linear history. +- `workflow_dispatch`-only workflows (e.g. `.github/workflows/interface.yml`) are not triggered by + push/PR events; PR CI cannot verify such fixes, so state "manual dispatch run required" in the PR + verification notes. ## PR Self-Check -- Confirm the PR body states exact commands run, whether they passed or failed, - and why any expected check could not be run. -- Keep warning rationales concrete. For example, a header include warning can be - acceptable when the header owns a value member that requires the complete type. -- Keep historical-debt notes separate from new deterministic errors introduced - by the PR. +- Confirm the PR body states exact commands run, whether they passed or failed, and why any expected + check could not be run. +- Keep warning rationales concrete. For example, a header include warning can be acceptable when the + header owns a value member that requires the complete type. +- Keep historical-debt notes separate from new deterministic errors introduced by the PR. diff --git a/README.md b/README.md index e0c81ae6554..4ecfb9e2da3 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,21 @@ # About ABACUS -ABACUS (**A**tomic-orbital **B**ased **A**b-initio **C**omputation at **US**tc) is an open-source package based on density functional theory (DFT). The package utilizes both plane wave and numerical atomic basis sets with the usage of pseudopotentials to describe the interactions between nuclear ions and valence electrons. ABACUS supports LDA, GGA, meta-GGA, and hybrid functionals. Apart from single-point calculations, the package allows geometry optimizations and ab-initio molecular dynamics with various ensembles. The package also provides a variety of advanced functionalities for simulating materials, including the DFT+U, VdW corrections, and implicit solvation model, etc. In addition, ABACUS strives to provide a general infrastructure to facilitate the developments and applications of novel machine-learning-assisted DFT methods (DeePKS, DP-GEN, DeepH, DeePTB etc.) in molecular and material simulations. +ABACUS (**A**tomic-orbital **B**ased **A**b-initio **C**omputation at **US**tc) is an open-source +package based on density functional theory (DFT). The package utilizes both plane wave and numerical +atomic basis sets with the usage of pseudopotentials to describe the interactions between nuclear +ions and valence electrons. ABACUS supports LDA, GGA, meta-GGA, and hybrid functionals. Apart from +single-point calculations, the package allows geometry optimizations and ab-initio molecular +dynamics with various ensembles. The package also provides a variety of advanced functionalities for +simulating materials, including the DFT+U, VdW corrections, and implicit solvation model, etc. In +addition, ABACUS strives to provide a general infrastructure to facilitate the developments and +applications of novel machine-learning-assisted DFT methods (DeePKS, DP-GEN, DeepH, DeePTB etc.) in +molecular and material simulations. # Online Documentation -For detailed documentation, please refer to [our documentation website](https://abacus.deepmodeling.com/). -See our [Github Pages](https://mcresearch.github.io/abacus-user-guide/) for more tutorials and developer guides. \ No newline at end of file +For detailed documentation, please refer to +[our documentation website](https://abacus.deepmodeling.com/). + +See our [Github Pages](https://mcresearch.github.io/abacus-user-guide/) for more tutorials and +developer guides. diff --git a/docs/CITATIONS.md b/docs/CITATIONS.md index 43176829a1d..85f594870bc 100644 --- a/docs/CITATIONS.md +++ b/docs/CITATIONS.md @@ -4,54 +4,77 @@ The following references are required to be cited when using ABACUS. Specificall - **For general purpose:** - *For LCAO basis:* + *For LCAO basis:* - Mohan Chen, G. C. Guo, and Lixin He. "Systematically improvable optimized atomic basis sets for ab initio calculations." Journal of Physics: Condensed Matter 22.44 (2010): 445501. + Mohan Chen, G. C. Guo, and Lixin He. "Systematically improvable optimized atomic basis sets for ab + initio calculations." Journal of Physics: Condensed Matter 22.44 (2010): 445501. - Pengfei Li, et al. "Large-scale ab initio simulations based on systematically improvable atomic basis." Computational Materials Science 112 (2016): 503-517. + Pengfei Li, et al. "Large-scale ab initio simulations based on systematically improvable atomic + basis." Computational Materials Science 112 (2016): 503-517. - Peize Lin, Xinguo Ren, Xiaohui Liu, Lixin He. Ab initio electronic structure calculations based on numerical atomic orbitals: Basic fomalisms and recent progresses. Wiley Interdisciplinary Reviews: Computational Molecular Science, 2024, 14(1): e1687. + Peize Lin, Xinguo Ren, Xiaohui Liu, Lixin He. Ab initio electronic structure calculations based on + numerical atomic orbitals: Basic fomalisms and recent progresses. Wiley Interdisciplinary Reviews: + Computational Molecular Science, 2024, 14(1): e1687. - *For LCAO and PW basis:* + *For LCAO and PW basis:* - Weiqing Zhou, Daye Zheng, Qianrui Liu, et al. ABACUS: An Electronic Structure Analysis Package for the AI Era. arXiv preprint arXiv:2501.08697, 2025. + Weiqing Zhou, Daye Zheng, Qianrui Liu, et al. ABACUS: An Electronic Structure Analysis Package for + the AI Era. arXiv preprint arXiv:2501.08697, 2025. - **If Stochastic DFT is used:** - Qianrui Liu, and Mohan Chen. "Plane-Wave-Based Stochastic-Deterministic Density Functional Theory for Extended Systems." . + Qianrui Liu, and Mohan Chen. "Plane-Wave-Based Stochastic-Deterministic Density Functional Theory + for Extended Systems." . - **If DFT+U is used:** - Xin Qu, et al. "DFT+ U within the framework of linear combination of numerical atomic orbitals." The Journal of Chemical Physics (2022). + Xin Qu, et al. "DFT+ U within the framework of linear combination of numerical atomic orbitals." + The Journal of Chemical Physics (2022). - **If second generation numerical orbital basis is used:** - Peize Lin, Xinguo Ren, and Lixin He. "Strategy for constructing compact numerical atomic orbital basis sets by incorporating the gradients of reference wavefunctions." Physical Review B 103.23 (2021): 235131. + Peize Lin, Xinguo Ren, and Lixin He. "Strategy for constructing compact numerical atomic orbital + basis sets by incorporating the gradients of reference wavefunctions." Physical Review B 103.23 + (2021): 235131. - **If berry curvature calculation is used in LCAO base:** - Gan Jin, Daye Zheng, and Lixin He. "Calculation of Berry curvature using non-orthogonal atomic orbitals." Journal of Physics: Condensed Matter 33.32 (2021): 325503. + Gan Jin, Daye Zheng, and Lixin He. "Calculation of Berry curvature using non-orthogonal atomic + orbitals." Journal of Physics: Condensed Matter 33.32 (2021): 325503. - **If DeePKS is used:** - Wenfei Li, Qi Ou, et al. "DeePKS+ABACUS as a Bridge between Expensive Quantum Mechanical Models and Machine Learning Potentials." J. Phys. Chem. A 126.49 (2022): 9154-9164. + Wenfei Li, Qi Ou, et al. "DeePKS+ABACUS as a Bridge between Expensive Quantum Mechanical Models + and Machine Learning Potentials." J. Phys. Chem. A 126.49 (2022): 9154-9164. - **If hybrid functional is used:** - Peize Lin, Xinguo Ren, and Lixin He. "Efficient Hybrid Density Functional Calculations for Large Periodic Systems Using Numerical Atomic Orbitals." Journal of Chemical Theory and Computation 2021, 17(1), 222โ€“239. + Peize Lin, Xinguo Ren, and Lixin He. "Efficient Hybrid Density Functional Calculations for Large + Periodic Systems Using Numerical Atomic Orbitals." Journal of Chemical Theory and Computation + 2021, 17(1), 222โ€“239. - Peize Lin, Xinguo Ren, and Lixin He. "Accuracy of Localized Resolution of the Identity in Periodic Hybrid Functional Calculations with Numerical Atomic Orbitals." Journal of Physical Chemistry Letters 2020, 11, 3082-3088. + Peize Lin, Xinguo Ren, and Lixin He. "Accuracy of Localized Resolution of the Identity in Periodic + Hybrid Functional Calculations with Numerical Atomic Orbitals." Journal of Physical Chemistry + Letters 2020, 11, 3082-3088. - **If ML-KEDF is used:** - Sun, Liang, and Mohan Chen. "Machine learning based nonlocal kinetic energy density functional for simple metals and alloys." Physical Review B 109.11 (2024): 115135. + Sun, Liang, and Mohan Chen. "Machine learning based nonlocal kinetic energy density functional for + simple metals and alloys." Physical Review B 109.11 (2024): 115135. - Sun, Liang, and Mohan Chen. "Multi-channel machine learning based nonlocal kinetic energy density functional for semiconductors." Electronic Structure 6.4 (2024): 045006. + Sun, Liang, and Mohan Chen. "Multi-channel machine learning based nonlocal kinetic energy density + functional for semiconductors." Electronic Structure 6.4 (2024): 045006. - **If DFT-D4 dispersion correction is used:** - Eike Caldeweyher, Sebastian Ehlert, Andreas Hansen, Hagen Neugebauer, Sebastian Spicher, Christoph Bannwarth, and Stefan Grimme. "A generally applicable atomic-charge dependent London dispersion correction." The Journal of Chemical Physics 150, 154122 (2019). DOI: 10.1063/1.5090222. + Eike Caldeweyher, Sebastian Ehlert, Andreas Hansen, Hagen Neugebauer, Sebastian Spicher, Christoph + Bannwarth, and Stefan Grimme. "A generally applicable atomic-charge dependent London dispersion + correction." The Journal of Chemical Physics 150, 154122 (2019). DOI: 10.1063/1.5090222. - Eike Caldeweyher, Jan-Michael Mewes, Sebastian Ehlert, and Stefan Grimme. "Extension and evaluation of the D4 London-dispersion model for periodic systems." Physical Chemistry Chemical Physics 22, 8499-8512 (2020). DOI: 10.1039/D0CP00502A. + Eike Caldeweyher, Jan-Michael Mewes, Sebastian Ehlert, and Stefan Grimme. "Extension and + evaluation of the D4 London-dispersion model for periodic systems." Physical Chemistry Chemical + Physics 22, 8499-8512 (2020). DOI: 10.1039/D0CP00502A. - Nikolay V. Tkachenko, Linus B. Dittmer, Rebecca Tomann, and Martin Head-Gordon. "Smooth D4S model." The Journal of Physical Chemistry Letters 15, 10629-10637 (2024). DOI: 10.1021/acs.jpclett.4c02653. + Nikolay V. Tkachenko, Linus B. Dittmer, Rebecca Tomann, and Martin Head-Gordon. "Smooth D4S + model." The Journal of Physical Chemistry Letters 15, 10629-10637 (2024). DOI: + 10.1021/acs.jpclett.4c02653. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index e655379c727..dd30135585d 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,8 +1,8 @@ # Contributing to ABACUS -First of all, thank you for taking time to make contributions to ABACUS! -This file provides the more technical guidelines on how to realize it. -For more non-technical aspects, please refer to the [ABACUS Contribution Guide](./community/contribution_guide.md) +First of all, thank you for taking time to make contributions to ABACUS! This file provides the more +technical guidelines on how to realize it. For more non-technical aspects, please refer to the +[ABACUS Contribution Guide](./community/contribution_guide.md) ## Table of Contents @@ -22,14 +22,22 @@ For more non-technical aspects, please refer to the [ABACUS Contribution Guide]( ## Got a question? -Please referring to our GitHub [issue tracker](https://github.com/deepmodeling/abacus-develop/issues), and our developers are willing to help. -If you find a bug, you can help us by submitting an issue to our GitHub Repository. Even better, you can submit a Pull Request with a patch. You can request a new feature by submitting an issue to our GitHub Repository. -If you would like to implement a new feature, please submit an issue with a proposal for your work first, and that ensures your work collaborates with our development road map well. For a major feature, first open an issue and outline your proposal so that it can be discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, and help you to craft the change so that it is successfully accepted into the project. +Please referring to our GitHub +[issue tracker](https://github.com/deepmodeling/abacus-develop/issues), and our developers are +willing to help. If you find a bug, you can help us by submitting an issue to our GitHub Repository. +Even better, you can submit a Pull Request with a patch. You can request a new feature by submitting +an issue to our GitHub Repository. If you would like to implement a new feature, please submit an +issue with a proposal for your work first, and that ensures your work collaborates with our +development road map well. For a major feature, first open an issue and outline your proposal so +that it can be discussed. This will also allow us to better coordinate our efforts, prevent +duplication of work, and help you to craft the change so that it is successfully accepted into the +project. ## Structure of the package -Please refer to [our instructions](./quick_start/easy_install.md) on how to installing ABACUS. -The source code of ABACUS is based on several modules. Under the ABACUS root directory, there are the following folders: +Please refer to [our instructions](./quick_start/easy_install.md) on how to installing ABACUS. The +source code of ABACUS is based on several modules. Under the ABACUS root directory, there are the +following folders: - `cmake`: relevant files for finding required packages when compiling the code with cmake; - `docs`: documents and supplementary info about ABACUS; @@ -38,7 +46,8 @@ The source code of ABACUS is based on several modules. Under the ABACUS root dir - `tests`: End-to-end test cases; - `tools`: the script for generating the numerical atomic orbitals. -For those who are interested in the source code, the following figure shows the structure of the source code. +For those who are interested in the source code, the following figure shows the structure of the +source code. ```text |-- source_base A basic module including @@ -89,76 +98,89 @@ For those who are interested in the source code, the following figure shows the ## Submitting an Issue -Before you submit an issue, please search the issue tracker, and maybe your problem has been discussed and fixed. You can [submit new issues](https://github.com/deepmodeling/abacus-develop/issues/new/choose) by filling our issue forms. -To help us reproduce and confirm a bug, please provide a test case and building environment in your issue. +Before you submit an issue, please search the issue tracker, and maybe your problem has been +discussed and fixed. You can +[submit new issues](https://github.com/deepmodeling/abacus-develop/issues/new/choose) by filling our +issue forms. To help us reproduce and confirm a bug, please provide a test case and building +environment in your issue. ## Agent governance and automated review Before coding or requesting review, read the repository governance entry point [`AGENTS.md`](https://github.com/deepmodeling/abacus-develop/blob/develop/AGENTS.md) and the full -[ABACUS Agent Governance](./developers_guide/agent_governance.md) guide. -These rules apply to human contributors, AI agents, GitHub CI, and CodeRabbit. +[ABACUS Agent Governance](./developers_guide/agent_governance.md) guide. These rules apply to human +contributors, AI agents, GitHub CI, and CodeRabbit. -Pull requests must complete the governance checklist in the PR template, -including issue linkage, test evidence, behavior-change notes, INPUT parameter -metadata changes, core-module impact, and any requested exceptions. Local -pre-commit checks cover deterministic rules such as LF line endings and staged -diff checks; CI repeats the governance check against the PR diff and PR body. +Pull requests must complete the governance checklist in the PR template, including issue linkage, +test evidence, behavior-change notes, INPUT parameter metadata changes, core-module impact, and any +requested exceptions. Local pre-commit checks cover deterministic rules such as LF line endings and +staged diff checks; CI repeats the governance check against the PR diff and PR body. ## Comment style for documentation ABACUS uses Doxygen to generate docs directly from `.h` and `.cpp` code files. -For comments that need to be shown in documents, these formats should be used -- **Javadoc style** (as follow) is recommended, though Qt style is also ok. See it in [official manual](https://www.doxygen.nl/manual/docblocks.html). +For comments that need to be shown in documents, these formats should be used -- **Javadoc style** +(as follow) is recommended, though Qt style is also ok. See it in +[official manual](https://www.doxygen.nl/manual/docblocks.html). -A helpful VS Code extension -- [Doxygen Documentation Generator](https://marketplace.visualstudio.com/items?itemName=cschlosser.doxdocgen), can help you formating comments. +A helpful VS Code extension -- +[Doxygen Documentation Generator](https://marketplace.visualstudio.com/items?itemName=cschlosser.doxdocgen), +can help you formating comments. -An practical example is class [LCAO_Deepks](https://github.com/deepmodeling/abacus-develop/blob/deepks/source/source_lcao/module_deepks/LCAO_deepks.h), the effects can be seen on [readthedocs page](https://abacus-deepks.readthedocs.io/en/latest/DeePKS_API/classLCAO__Descriptor.html#exhale-class-classLCAO-Descriptor) +An practical example is class +[LCAO_Deepks](https://github.com/deepmodeling/abacus-develop/blob/deepks/source/source_lcao/module_deepks/LCAO_deepks.h), +the effects can be seen on +[readthedocs page](https://abacus-deepks.readthedocs.io/en/latest/DeePKS_API/classLCAO__Descriptor.html#exhale-class-classLCAO-Descriptor) - Tips - - Only comments in .h file will be visible in generated by Doxygen + Sphinx; + + - Only comments in .h file will be visible in generated by Doxygen + Sphinx; - Private class members will not be documented; - - Use [Markdown features](https://www.doxygen.nl/manual/markdown.html), such as using a empty new line for a new paragraph. + - Use [Markdown features](https://www.doxygen.nl/manual/markdown.html), such as using a empty new + line for a new paragraph. - Detailed Comment Block - ```cpp - /** - * ... text ... - */ - ``` + ```cpp + /** + * ... text ... + */ + ``` - Brief + Detailed Comment Block - ```cpp - /// Brief description which ends at this dot. Details follow - /// here. + ```cpp + /// Brief description which ends at this dot. Details follow + /// here. - /// Brief description. - /** Detailed description. */ - ``` + /// Brief description. + /** Detailed description. */ + ``` -- Comments After the Item: Add a "<" +- Comments After the Item: Add a "\<" - ```cpp - int var; /** to format the code. -It is performed after pushing new commits to a PR. You might need to pull the changes before adding new commits. +We use to format the code. It is performed after pushing new commits to a +PR. You might need to pull the changes before adding new commits. -To use pre-commit locally (**generally not required**): -Please install the pre-commit tool by running the following command: +To use pre-commit locally (**generally not required**): Please install the pre-commit tool by +running the following command: ```bash pip install pre-commit @@ -243,190 +276,241 @@ pre-commit install ## Adding a unit test -We use [GoogleTest](https://github.com/google/googletest) as our test framework. Write your test under the corresponding module folder at `abacus-develop/tests`, then append the test to `tests/CMakeLists.txt`. If there are currently no unit tests provided for the module, do as follows. `source_base` provides a simple demonstration. +We use [GoogleTest](https://github.com/google/googletest) as our test framework. Write your test +under the corresponding module folder at `abacus-develop/tests`, then append the test to +`tests/CMakeLists.txt`. If there are currently no unit tests provided for the module, do as follows. +`source_base` provides a simple demonstration. - Add a folder named `test` under the module. + - Append the content below to `CMakeLists.txt` of the module: - ```cmake - IF (BUILD_TESTING) - add_subdirectory(test) - endif() - ``` + ```cmake + IF (BUILD_TESTING) + add_subdirectory(test) + endif() + ``` - Add a blank `CMakeLists.txt` under `module*/test`. To add a unit test: - Write your test under `GoogleTest` framework. + - Add your testing source code with suffix `*_test.cpp` in `test` directory. + - Append the content below to `CMakeLists.txt` of the module: - ```cmake - AddTest( - TARGET _ # this is the executable file name of the test - SOURCES .cpp + ```cmake + AddTest( + TARGET _ # this is the executable file name of the test + SOURCES .cpp - # OPTIONAL: if this test requires external libraries, add them with "LIBS" statement. - LIBS math_libs # `math_libs` includes all math libraries in ABACUS. - ) - ``` + # OPTIONAL: if this test requires external libraries, add them with "LIBS" statement. + LIBS math_libs # `math_libs` includes all math libraries in ABACUS. + ) + ``` + +- Build with `-D BUILD_TESTING=1` flag, `cmake` will look for `GoogleTest` in the default path + (usually `/usr/local`); if not found, you can specify the path with `-D GTEST_DIR`. You can find + built testing programs under `build/source//test`. -- Build with `-D BUILD_TESTING=1` flag, `cmake` will look for `GoogleTest` in the default path (usually `/usr/local`); if not found, you can specify the path with `-D GTEST_DIR`. You can find built testing programs under `build/source//test`. - Follow the installing procedure of CMake. The tests will move to `build/test`. -- Considering `-D BUILD_TESTING=1`, the compilation will be slower compared with the case `-D BUILD_TESTING=0`. + +- Considering `-D BUILD_TESTING=1`, the compilation will be slower compared with the case + `-D BUILD_TESTING=0`. ## Running unit tests 1. Compiling ABACUS with unit tests. - In order to run unit tests, ABACUS needs to be configured with `-D BUILD_TESTING=ON` flag. For example: + In order to run unit tests, ABACUS needs to be configured with `-D BUILD_TESTING=ON` flag. For + example: - ```bash - cmake -B build -DBUILD_TESTING=ON - ``` + ```bash + cmake -B build -DBUILD_TESTING=ON + ``` - then build ABACUS and unit testing with + then build ABACUS and unit testing with - ```bash - cmake --build build -j${number of processors} - ``` + ```bash + cmake --build build -j${number of processors} + ``` - It is import to run the folloing command before running unit tests: + It is import to run the folloing command before running unit tests: - ```bash - cmake --install build - ``` + ```bash + cmake --install build + ``` - to install mandatory supporting input files for unit tests. - If you modified the unit tests to add new tests or learn how to write unit tests, it is convenient to run + to install mandatory supporting input files for unit tests. If you modified the unit tests to add + new tests or learn how to write unit tests, it is convenient to run - ```bash - cmake --build build -j${number of processors} --target ${unit test name} - ``` + ```bash + cmake --build build -j${number of processors} --target ${unit test name} + ``` - to build a specific unit test. And please remember to run `cmake --install build` after building the unit test if the unit test requires supporting input files. + to build a specific unit test. And please remember to run `cmake --install build` after building + the unit test if the unit test requires supporting input files. -2. Running unit tests +1. Running unit tests - The test cases are located in `build/source/${module_name}/test` directory. Note that there are other directory names for unit tests, for example, `test_parallel` for running parallel unit tests, `test_pw` for running unit tests only used in plane wave basis calculation. + The test cases are located in `build/source/${module_name}/test` directory. Note that there are + other directory names for unit tests, for example, `test_parallel` for running parallel unit + tests, `test_pw` for running unit tests only used in plane wave basis calculation. - You can run a single test in the specific directory. For example, run + You can run a single test in the specific directory. For example, run - ```bash - ./cell_unitcell_test - ``` + ```bash + ./cell_unitcell_test + ``` - under the directory of `build/source/source_cell/test` to run the test `cell_unitcell_test`. - However, it is more convenient to run unit tests with `ctest` command under the `build` directory. You can check all unit tests by + under the directory of `build/source/source_cell/test` to run the test `cell_unitcell_test`. + However, it is more convenient to run unit tests with `ctest` command under the `build` + directory. You can check all unit tests by - ```bash - ctest -N - ``` + ```bash + ctest -N + ``` - The results will be shown as + The results will be shown as - ```text - Test project /root/abacus/build - Test #1: integrated_test - Test #2: Container_UTs - Test #3: base_blas_connector - Test #4: base_blacs_connector - Test #5: base_timer - ... - ``` + ```text + Test project /root/abacus/build + Test #1: integrated_test + Test #2: Container_UTs + Test #3: base_blas_connector + Test #4: base_blacs_connector + Test #5: base_timer + ... + ``` - Note that the first one is integrated test, which is not a unit test. It is the test - suite for testing the whole ABACUS package. The examples are located in the `tests/integrate` directory. + Note that the first one is integrated test, which is not a unit test. It is the test suite for + testing the whole ABACUS package. The examples are located in the `tests/integrate` directory. - To run a subset of tests, run the following command + To run a subset of tests, run the following command - ```bash - ctest -R -V - ``` + ```bash + ctest -R -V + ``` - For example, `ctest -R cell` will perform tests with name matched by `cell`. - You can also run a single test with + For example, `ctest -R cell` will perform tests with name matched by `cell`. You can also run a + single test with - ```bash - ctest -R - ``` + ```bash + ctest -R + ``` - For example, `ctest -R cell_unitcell_test_readpp` will perform test `cell_unitcell_test_readpp`. - To run all the unit tests, together with the integrated test, run + For example, `ctest -R cell_unitcell_test_readpp` will perform test `cell_unitcell_test_readpp`. + To run all the unit tests, together with the integrated test, run - ```bash - cmake --build build --target test ARGS="-V --timeout 21600" - ``` + ```bash + cmake --build build --target test ARGS="-V --timeout 21600" + ``` - in the `abacus-develop` directory. + in the `abacus-develop` directory. ## Adding an integrate test -The integrate test is a test suite for testing the whole ABACUS package. The examples are located in the `tests/integrate` directory. Before adding a new test, please firstly read `README.md` in `tests/integrate` to understand the structure of the integrate test. To add an integrate test: + +The integrate test is a test suite for testing the whole ABACUS package. The examples are located in +the `tests/integrate` directory. Before adding a new test, please firstly read `README.md` in +`tests/integrate` to understand the structure of the integrate test. To add an integrate test: + 1. Add a new directory under `tests/integrate` for the new test. -2. Prepare the input files for the new test. - - The input files should be placed in the new directory. Pseudopotential files and orbital files should be placed in `tests/PP_ORB`. You should define the correct `pseudo_dir` and `orb_dir`(if need orbital files) in INPUT with the relative path to the `tests/PP_ORB` directory, and be sure the new test can be run successfully. - - The running time of the new test should not exceed 20 seconds. You can try to reduce the time by below methods (on the premise of ensuring the effectiveness of the test): - - Reduce the number of atoms in the unit cell (1~2 atoms). - - Reduce the number of k-points (`1 1 1` or `2 2 2`). - - Reduce ecutwfc (20~50 Ry). - - Reduce the number of steps for relax or md job (2~3 steps). - - Reduce the basis set for LCAO calculations (DZP orbital and 6 a.u. cutoff). - - For PW calculations, should set `pw_seed 1` in INPUT file to ensure the reproducibility of the test. -3. Generate the reference results for the new test. - - Run the new test with GNU compiler and 4 MPI processes 2 OpenMP threads. The command is `OMP_NUM_THREADS=2 mpirun -np 4 abacus > log.txt`. - - Execute tests/integrate/validation_tools/catch_properties.sh script to generate the reference results. At the new test directory, run `bash ../../integrate/validation_tools/catch_properties.sh result.ref`. - A `result.ref` file may be like: - ```text - etotref -3439.007931317310 - etotperatomref -3439.0079313173 - totaltimeref 2.78 +1. Prepare the input files for the new test. + - The input files should be placed in the new directory. Pseudopotential files and orbital files + should be placed in `tests/PP_ORB`. You should define the correct `pseudo_dir` and `orb_dir`(if + need orbital files) in INPUT with the relative path to the `tests/PP_ORB` directory, and be + sure the new test can be run successfully. + - The running time of the new test should not exceed 20 seconds. You can try to reduce the time + by below methods (on the premise of ensuring the effectiveness of the test): + - Reduce the number of atoms in the unit cell (1~2 atoms). + - Reduce the number of k-points (`1 1 1` or `2 2 2`). + - Reduce ecutwfc (20~50 Ry). + - Reduce the number of steps for relax or md job (2~3 steps). + - Reduce the basis set for LCAO calculations (DZP orbital and 6 a.u. cutoff). + - For PW calculations, should set `pw_seed 1` in INPUT file to ensure the reproducibility of the + test. +1. Generate the reference results for the new test. + - Run the new test with GNU compiler and 4 MPI processes 2 OpenMP threads. The command is + `OMP_NUM_THREADS=2 mpirun -np 4 abacus > log.txt`. + - Execute tests/integrate/validation_tools/catch_properties.sh script to generate the reference + results. At the new test directory, run + `bash ../../integrate/validation_tools/catch_properties.sh result.ref`. A `result.ref` file may + be like: + ```text + etotref -3439.007931317310 + etotperatomref -3439.0079313173 + totaltimeref 2.78 + ``` + - If you want to test the correctness of some output files, you need to do extra below steps: + 1. add the corresponding comparison method in `catch_properties.sh`. For example, to verify + whether the output of the BANDS_1.dat file is correct, you need to add the following code in + `catch_properties.sh`: + + ```bash + has_band=$(awk '$1=="out_band" {a=$2} END{print a}' INPUT) # check if the BAND is outputed + if ! test -z "$has_band" && [ $has_band == 1 ]; then # if band is outputed, then check if the band is correct + bandref=refBANDS_1.dat # this file should be prepared in new test directory + bandcal=OUT.autotest/BANDS_1.dat # this file is generated by each run of test + python3 ../../integrate/validation_tools/CompareFile.py $bandref $bandcal 8 # compare the new band file with the reference file + echo "CompareBand_pass $?" >>$1 # record the comparison result, $? is the return value of last command + fi ``` - - If you want to test the correctness of some output files, you need to do extra below steps: - 1. add the corresponding comparison method in `catch_properties.sh`. For example, to verify whether the output of the BANDS_1.dat file is correct, you need to add the following code in `catch_properties.sh`: - ```bash - has_band=$(awk '$1=="out_band" {a=$2} END{print a}' INPUT) # check if the BAND is outputed - if ! test -z "$has_band" && [ $has_band == 1 ]; then # if band is outputed, then check if the band is correct - bandref=refBANDS_1.dat # this file should be prepared in new test directory - bandcal=OUT.autotest/BANDS_1.dat # this file is generated by each run of test - python3 ../../integrate/validation_tools/CompareFile.py $bandref $bandcal 8 # compare the new band file with the reference file - echo "CompareBand_pass $?" >>$1 # record the comparison result, $? is the return value of last command - fi - ``` - `CompareFile.py` is used to determine if two files are identical. It accepts three arguments: the first two are the files to be compared, and the third specifies the precision for comparing numerical values. The comparison fails if the difference between any two corresponding numerical values exceeds 1e-{precision} (such as: 1e-8 in previous case). If the files are identical, the script returns 0; otherwise, it returns 1. - 2. Add the reference file (such as: `refBANDS_1.dat` in previous case) to the new test directory. - - 3. Add the reference comparison result to the `result.ref` file. For example, `CompareBand_pass 0` means the comparison of the band file is passed. (This statement should be added before the `totaltimeref` line) -4. Add a `jd` file in the new test directory, which is one setence to describe the new test. -5. Add the new test to `tests/integrate/CASES_CPU.txt` file (or `tests/integrate/CASES_GPU.txt` file if it is for GPU verion). -6. Enter directory tests/integrate and run `bash Autotest.sh -r ` to check if the new test can be run successfully. + `CompareFile.py` is used to determine if two files are identical. It accepts three + arguments: the first two are the files to be compared, and the third specifies the precision + for comparing numerical values. The comparison fails if the difference between any two + corresponding numerical values exceeds 1e-{precision} (such as: 1e-8 in previous case). If + the files are identical, the script returns 0; otherwise, it returns 1. + 1. Add the reference file (such as: `refBANDS_1.dat` in previous case) to the new test + directory. + 1. Add the reference comparison result to the `result.ref` file. For example, + `CompareBand_pass 0` means the comparison of the band file is passed. (This statement should + be added before the `totaltimeref` line) +1. Add a `jd` file in the new test directory, which is one setence to describe the new test. +1. Add the new test to `tests/integrate/CASES_CPU.txt` file (or `tests/integrate/CASES_GPU.txt` file + if it is for GPU verion). +1. Enter directory tests/integrate and run `bash Autotest.sh -r ` to check if the + new test can be run successfully. ## Debugging the codes -For the unexpected results when developing ABACUS, [GDB](https://www.sourceware.org/gdb/) will come in handy. +For the unexpected results when developing ABACUS, [GDB](https://www.sourceware.org/gdb/) will come +in handy. 1. Compile ABACUS with debug mode. - ```bash - cmake -B build -DCMAKE_BUILD_TYPE=Debug - ``` + ```bash + cmake -B build -DCMAKE_BUILD_TYPE=Debug + ``` -2. After building and installing the executable, enter the input directory, and launch the debug session with `gdb abacus`. For [debugging in Visual Studio Code](https://code.visualstudio.com/docs/cpp/cpp-debug), please set [cwd](https://code.visualstudio.com/docs/cpp/launch-json-reference#_cwd) to the input directory, and [program](https://code.visualstudio.com/docs/cpp/launch-json-reference#_program-required) to the path of ABACUS executable. +1. After building and installing the executable, enter the input directory, and launch the debug + session with `gdb abacus`. For + [debugging in Visual Studio Code](https://code.visualstudio.com/docs/cpp/cpp-debug), please set + [cwd](https://code.visualstudio.com/docs/cpp/launch-json-reference#_cwd) to the input directory, + and [program](https://code.visualstudio.com/docs/cpp/launch-json-reference#_program-required) to + the path of ABACUS executable. -3. Set breakpoints, and run ABACUS by typing "run" in GDB command line interface. If the program hits the breakpoints or exception is throwed, GDB will stop at the erroneous code line. Type "where" to show the stack backtrace, and "print i" to get the value of variable i. +1. Set breakpoints, and run ABACUS by typing "run" in GDB command line interface. If the program + hits the breakpoints or exception is throwed, GDB will stop at the erroneous code line. Type + "where" to show the stack backtrace, and "print i" to get the value of variable i. -4. For debugging ABACUS in multiprocessing situation, `mpirun -n 1 gdb abacus : -n 3 abacus` will attach GDB to the master process, and launch 3 other MPI processes. +1. For debugging ABACUS in multiprocessing situation, `mpirun -n 1 gdb abacus : -n 3 abacus` will + attach GDB to the master process, and launch 3 other MPI processes. -For segmentation faults, ABACUS can be built with [Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) to locate the bugs. +For segmentation faults, ABACUS can be built with +[Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) to locate the bugs. ```bash cmake -B build -DENABLE_ASAN=1 ``` -Run ABACUS as usual, and it will automatically detect the buffer overflow problems and memory leaks. It is also possible to [use GDB with binaries built by Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizerAndDebugger). +Run ABACUS as usual, and it will automatically detect the buffer overflow problems and memory leaks. +It is also possible to +[use GDB with binaries built by Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizerAndDebugger). [Valgrind](https://valgrind.org/) is another option for performing dynamic analysis. @@ -434,27 +518,33 @@ Run ABACUS as usual, and it will automatically detect the buffer overflow proble ABACUS uses CMake as its default building system. To add a new building component: -1. Add an `OPTION` to toggle the component to the `CMakeLists.txt` file under root directory. For example: +1. Add an `OPTION` to toggle the component to the `CMakeLists.txt` file under root directory. For + example: - ```cmake - OPTION(ENABLE_NEW_COMPONENT "Enable new component" OFF) - ``` + ```cmake + OPTION(ENABLE_NEW_COMPONENT "Enable new component" OFF) + ``` -2. Add the new component. For example: +1. Add the new component. For example: - ```cmake - IF (ENABLE_NEW_COMPONENT) - add_subdirectory(module_my_new_feature) # if the feature is implemented in a subdirectory - find_package(NewComponent REQUIRED) # if third-party libs are required - target_link_libraries(${ABACUS_BIN_NAME} PRIVATE NewComponent) # if the component is linked - include_directories(${NewComponent_INCLUDE_DIRS}) # if the component is included - endif() - ``` + ```cmake + IF (ENABLE_NEW_COMPONENT) + add_subdirectory(module_my_new_feature) # if the feature is implemented in a subdirectory + find_package(NewComponent REQUIRED) # if third-party libs are required + target_link_libraries(${ABACUS_BIN_NAME} PRIVATE NewComponent) # if the component is linked + include_directories(${NewComponent_INCLUDE_DIRS}) # if the component is included + endif() + ``` + +1. Add the required third-party libraries to Dockerfiles. -3. Add the required third-party libraries to Dockerfiles. -4. After the changes above are merged, submit another PR to build and test the new component in the CI pipeline. - - For integration test and unit test: add `-DENABLE_NEW_COMPONENT=ON` to the building step at `.github/workflows/test.yml`. - - For building test: add `-DENABLE_NEW_COMPONENT=ON` as a new configuration at `.github/workflows/build_test_cmake.yml`. +1. After the changes above are merged, submit another PR to build and test the new component in the + CI pipeline. + + - For integration test and unit test: add `-DENABLE_NEW_COMPONENT=ON` to the building step at + `.github/workflows/test.yml`. + - For building test: add `-DENABLE_NEW_COMPONENT=ON` as a new configuration at + `.github/workflows/build_test_cmake.yml`. ## Generating code coverage report @@ -462,86 +552,107 @@ This feature requires using GCC compiler. We use `gcov` and `lcov` to generate c 1. Add `-DENABLE_COVERAGE=ON` for CMake configure command. - ```bash - cmake -B build -DBUILD_TESTING=ON -DENABLE_COVERAGE=ON - ``` + ```bash + cmake -B build -DBUILD_TESTING=ON -DENABLE_COVERAGE=ON + ``` -2. Build, install ABACUS, and run test cases. Please note that since all optimizations are disabled to gather running status line by line, the performance is drastically decreased. Set a longer time out to ensure all tests are executed. +1. Build, install ABACUS, and run test cases. Please note that since all optimizations are disabled + to gather running status line by line, the performance is drastically decreased. Set a longer + time out to ensure all tests are executed. - ```bash - cmake --build build --target test ARGS="-V --timeout 21600" - ``` + ```bash + cmake --build build --target test ARGS="-V --timeout 21600" + ``` - If configuration fails unfortunately, you can find [required files](https://github.com/baixiaokuang/CMake-codecov/tree/master/cmake) (including three *.cmake and llvm-cov-wrapper), and copy these four files into `/abacus-develop/cmake`. Alternatively, you can define the path with option `-D CMAKE_CURRENT_SOURCE_DIR`. + If configuration fails unfortunately, you can find + [required files](https://github.com/baixiaokuang/CMake-codecov/tree/master/cmake) (including + three \*.cmake and llvm-cov-wrapper), and copy these four files into `/abacus-develop/cmake`. + Alternatively, you can define the path with option `-D CMAKE_CURRENT_SOURCE_DIR`. -3. Generate HTML report. +1. Generate HTML report. - ```bash - cd build/ - make lcov - ``` + ```bash + cd build/ + make lcov + ``` -Now you can copy `build/lcov` to your local device, and view `build/lcov/html/all_targets/index.html`. +Now you can copy `build/lcov` to your local device, and view +`build/lcov/html/all_targets/index.html`. -We use [Codecov](https://codecov.io/) to host and visualize our [**code coverage report**](https://app.codecov.io/gh/deepmodeling/abacus-develop). Analysis is scheduled after a new version releases; this [action](https://github.com/deepmodeling/abacus-develop/actions/workflows/coverage.yml) can also be manually triggered. +We use [Codecov](https://codecov.io/) to host and visualize our +[**code coverage report**](https://app.codecov.io/gh/deepmodeling/abacus-develop). Analysis is +scheduled after a new version releases; this +[action](https://github.com/deepmodeling/abacus-develop/actions/workflows/coverage.yml) can also be +manually triggered. ## Submitting a Pull Request -1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the [ABACUS repository](https://github.com/deepmodeling/abacus-develop). If you already had an existing fork, [sync](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) the fork to keep your modification up-to-date. +1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the + [ABACUS repository](https://github.com/deepmodeling/abacus-develop). If you already had an + existing fork, + [sync](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) + the fork to keep your modification up-to-date. -2. Pull your forked repository, create a new git branch, and make your changes in it: +1. Pull your forked repository, create a new git branch, and make your changes in it: - ```shell - git checkout -b my-fix-branch - ``` + ```shell + git checkout -b my-fix-branch + ``` -3. Coding your patch, including appropriate test cases and docs. -To run a subset of unit test, use `ctest -R ` to perform tests with name matched by given pattern. +1. Coding your patch, including appropriate test cases and docs. To run a subset of unit test, use + `ctest -R ` to perform tests with name matched by given pattern. -4. After tests passed, commit your changes [with a proper message](#commit-message-guidelines). +1. After tests passed, commit your changes [with a proper message](#commit-message-guidelines). -5. Push your branch to GitHub: +1. Push your branch to GitHub: - ```shell - git push origin my-fix-branch - ``` + ```shell + git push origin my-fix-branch + ``` -6. In GitHub, send a pull request (PR) with `deepmodeling/abacus-develop:develop` as the base repository. It is **required** to document your PR following [our guidelines](#commit-message-guidelines). +1. In GitHub, send a pull request (PR) with `deepmodeling/abacus-develop:develop` as the base + repository. It is **required** to document your PR following + [our guidelines](#commit-message-guidelines). -7. If more changes are needed, you can add more commits to your branch and push them to GitHub. Your PR will be updated automatically. +1. If more changes are needed, you can add more commits to your branch and push them to GitHub. Your + PR will be updated automatically. -8. After your pull request is merged, you can safely delete your branch and sync the changes from the main (upstream) repository: +1. After your pull request is merged, you can safely delete your branch and sync the changes from + the main (upstream) repository: - - Delete the remote branch on GitHub either [through the GitHub web UI](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request#deleting-a-branch-used-for-a-pull-request) or your local shell as follows: + - Delete the remote branch on GitHub either + [through the GitHub web UI](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request#deleting-a-branch-used-for-a-pull-request) + or your local shell as follows: - ```shell - git push origin --delete my-fix-branch - ``` + ```shell + git push origin --delete my-fix-branch + ``` - - Check out the master branch: + - Check out the master branch: - ```shell - git checkout develop -f - ``` + ```shell + git checkout develop -f + ``` - - Delete the local branch: + - Delete the local branch: - ```shell - git branch -D my-fix-branch - ``` + ```shell + git branch -D my-fix-branch + ``` - - Update your master with the latest upstream version: + - Update your master with the latest upstream version: - ```shell - git pull --ff upstream develop - ``` + ```shell + git pull --ff upstream develop + ``` ## Commit message guidelines -A well-formatted commit message leads a more readable history when we look through some changes, and helps us generate change log. -We follow up [The Conventional Commits specification](https://www.conventionalcommits.org) for commit message format. -This format is also required for PR title and message. -The commit message should be structured as follows: +A well-formatted commit message leads a more readable history when we look through some changes, and +helps us generate change log. We follow up +[The Conventional Commits specification](https://www.conventionalcommits.org) for commit message +format. This format is also required for PR title and message. The commit message should be +structured as follows: ```text [optional scope]: @@ -565,8 +676,11 @@ The commit message should be structured as follows: - `Revert`: Reverting commits - scope: optional, could be the module which this commit changes; for example, `orbital` - description: A short summary of the code changes: tell others what you did in one sentence. -- Body: optional, providing detailed, additional, or contextual information about the code changes, e.g. the motivation of this commit, referenced materials, the coding implementation, and so on. -- Footer: optional, reference GitHub issues or PRs that this commit closes or is related to. [Use a keyword](https://docs.github.com/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) to close an issue, e.g. "Fix #753". +- Body: optional, providing detailed, additional, or contextual information about the code changes, + e.g. the motivation of this commit, referenced materials, the coding implementation, and so on. +- Footer: optional, reference GitHub issues or PRs that this commit closes or is related to. + [Use a keyword](https://docs.github.com/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) + to close an issue, e.g. "Fix #753". Here is an example: diff --git a/docs/DevelopingTeam.md b/docs/DevelopingTeam.md index 333e923c67c..fdee775d978 100644 --- a/docs/DevelopingTeam.md +++ b/docs/DevelopingTeam.md @@ -1,8 +1,9 @@ - # Development team + The current development team consists the following research groups/affiliations: + - University of Science and Technology of China (Dr. Lixin He) - Peking University (Dr. Mohan Chen) - Institute of Physics, Chinese Academy of Sciences (Dr. Xinguo Ren) - Beijing AI for Science Institute (Dr. Daye Zheng) -- Institute of Artificial Intelligence, Hefei Comprehensive National Science Center (Dr. Lixin He). +- Institute of Artificial Intelligence, Hefei Comprehensive National Science Center (Dr. Lixin He). diff --git a/docs/README.md b/docs/README.md index fd7e82c5e2c..e78d17a526c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -44,8 +44,8 @@ directory: > > The "optional but recommended" steps above are used to generate the > [Full List of INPUT Keywords](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html) -> page. If you've modified input parameters in the source code and want to preview the changes, -> you should complete these steps. +> page. If you've modified input parameters in the source code and want to preview the changes, you +> should complete these steps. ______________________________________________________________________ diff --git a/docs/advanced/acceleration/cuda.md b/docs/advanced/acceleration/cuda.md index 782e0990ee8..1bef5262ac3 100644 --- a/docs/advanced/acceleration/cuda.md +++ b/docs/advanced/acceleration/cuda.md @@ -1,61 +1,105 @@ # CUDA GPU Implementations -In ABACUS, we provide the option to use GPU devices to accelerate performance. The implementation of GPU acceleration differs between PW basis and LCAO basis. Specifically, under PW basis, it has the following features: +In ABACUS, we provide the option to use GPU devices to accelerate performance. The implementation of +GPU acceleration differs between PW basis and LCAO basis. Specifically, under PW basis, it has the +following features: -- **Full gpu implementations**: During the SCF progress, `Psi`, `Hamilt`, `Hsolver`, `DiagCG`, and `DiagoDavid` classes are stored or calculated by the GPU devices. +- **Full gpu implementations**: During the SCF progress, `Psi`, `Hamilt`, `Hsolver`, `DiagCG`, and + `DiagoDavid` classes are stored or calculated by the GPU devices. -- **Electronic state data**: (e.g. electronic density) are moved from the GPU to the CPU(s) every scf step. +- **Electronic state data**: (e.g. electronic density) are moved from the GPU to the CPU(s) every + scf step. -- **Accelerated by the NVIDIA libraries**: `cuBLAS` for common linear algebra calculations, `cuSolver` for eigen values/vectors, and `cuFFT` for the conversions between the real and recip spaces. +- **Accelerated by the NVIDIA libraries**: `cuBLAS` for common linear algebra calculations, + `cuSolver` for eigen values/vectors, and `cuFFT` for the conversions between the real and recip + spaces. -- **Multi GPU supprted**: Using multiple MPI tasks will often give the best performance. Note each MPI task will be bind to a GPU device with automatically computing load balancing. +- **Multi GPU supprted**: Using multiple MPI tasks will often give the best performance. Note each + MPI task will be bind to a GPU device with automatically computing load balancing. - **Parallel strategy**: K point parallel. -Unlike PW basis, only the grid integration module (module_gint) and the diagonalization of the Hamiltonian matrix (source_hsolver) have been implemented with GPU acceleration under LCAO basis. +Unlike PW basis, only the grid integration module (module_gint) and the diagonalization of the +Hamiltonian matrix (source_hsolver) have been implemented with GPU acceleration under LCAO basis. ## Required hardware/software -To compile and use ABACUS in CUDA mode, you currently need to have an NVIDIA GPU and install the corresponding NVIDIA CUDA toolkit software on your system (this is only tested on Linux and unsupported on Windows): +To compile and use ABACUS in CUDA mode, you currently need to have an NVIDIA GPU and install the +corresponding NVIDIA CUDA toolkit software on your system (this is only tested on Linux and +unsupported on Windows): -- Check if you have an NVIDIA GPU: cat /proc/driver/nvidia/gpus/*/information +- Check if you have an NVIDIA GPU: cat /proc/driver/nvidia/gpus/\*/information - Go to https://developer.nvidia.com/cuda-downloads - Install a driver and toolkit appropriate for your system (SDK is not necessary) -NVIDIA reports that cuSOLVERMp 0.4.2 through 0.8.0 contain an STEDC defect -affecting non-power-of-two block sizes and certain 2D process grids. Because -`Syevd` and `Sygvd` use STEDC internally, affected versions may fail or hang -during distributed diagonalization. ABACUS therefore requires cuSOLVERMp 0.9.0 -or newer when `ENABLE_CUSOLVERMP=ON`. The recommended stack is cuSOLVERMp 0.9.0 -with cuBLASMp 0.9.1. See the +NVIDIA reports that cuSOLVERMp 0.4.2 through 0.8.0 contain an STEDC defect affecting +non-power-of-two block sizes and certain 2D process grids. Because `Syevd` and `Sygvd` use STEDC +internally, affected versions may fail or hang during distributed diagonalization. ABACUS therefore +requires cuSOLVERMp 0.9.0 or newer when `ENABLE_CUSOLVERMP=ON`. The recommended stack is cuSOLVERMp +0.9.0 with cuBLASMp 0.9.1. See the [cuSOLVERMp 0.9.0 release notes](https://docs.nvidia.com/cuda/cusolvermp/release_notes/index.html#cusolvermp-v0-9-0) for the upstream fix details. ## Building ABACUS with the GPU support: -Check the [Advanced Installation Options](https://abacus-rtd.readthedocs.io/en/latest/advanced/install.html#build-with-cuda-support) for the installation of CUDA version support. +Check the +[Advanced Installation Options](https://abacus-rtd.readthedocs.io/en/latest/advanced/install.html#build-with-cuda-support) +for the installation of CUDA version support. -Setting both `ENABLE_ELPA` and `USE_CUDA` to ON does not automatically enable ELPA to run on GPUs. ELPA support for GPUs needs to be enabled when ELPA is compiled. [enable GPU support](https://github.com/marekandreas/elpa/blob/master/documentation/INSTALL.md). +Setting both `ENABLE_ELPA` and `USE_CUDA` to ON does not automatically enable ELPA to run on GPUs. +ELPA support for GPUs needs to be enabled when ELPA is compiled. +[enable GPU support](https://github.com/marekandreas/elpa/blob/master/documentation/INSTALL.md). -The ABACUS program will automatically determine whether the current ELPA supports GPU based on the elpa/elpa_configured_options.h header file. Users can also check this header file to determine the GPU support of ELPA in their environment. ELPA introduced a new API elpa_setup_gpu in version 2023.11.001. So if you want to enable ELPA GPU in ABACUS, the ELPA version must be greater than or equal to 2023.11.001. +The ABACUS program will automatically determine whether the current ELPA supports GPU based on the +elpa/elpa_configured_options.h header file. Users can also check this header file to determine the +GPU support of ELPA in their environment. ELPA introduced a new API elpa_setup_gpu in version +2023.11.001. So if you want to enable ELPA GPU in ABACUS, the ELPA version must be greater than or +equal to 2023.11.001. ## Run with the GPU support by editing the INPUT script: -In `INPUT` file we need to set the input parameter [device](../input_files/input-main.md#device) to `gpu`. If this parameter is not set, ABACUS will try to determine if there are available GPUs. -- Set `ks_solver`: For the PW basis, CG, BPCG, Davidson, and Davidson subspace methods are supported on GPU; set the input parameter [ks_solver](../input_files/input-main.md#ks_solver) to `cg`, `bpcg`, `dav`, or `dav_subspace`. For the LCAO basis, `cusolver`, `cusolvermp`, and `elpa` are supported on GPU. -- **single-card**: ABACUS allows for single-GPU acceleration. You can run ABACUS without any MPI process by command `abacus`, and `ks_solver cusolver` is recommended for the LCAO basis. *note: avoid using `mpirun -n 1 abacus`*. -- **multi-cards**: ABACUS allows for multi-GPU acceleration. If you have multiple GPU cards, you can run ABACUS with several MPI processes, and each process will utilize one GPU card. For example, the command `mpirun -n 2 abacus` will by default launch two GPUs for computation. If you only have one card, this command will only start one GPU. *note: the number of MPI processes SHOULD be equal to the number of GPU cards, unless you are using MPS in your computer.* +In `INPUT` file we need to set the input parameter [device](../input_files/input-main.md#device) to +`gpu`. If this parameter is not set, ABACUS will try to determine if there are available GPUs. + +- Set `ks_solver`: For the PW basis, CG, BPCG, Davidson, and Davidson subspace methods are supported + on GPU; set the input parameter [ks_solver](../input_files/input-main.md#ks_solver) to `cg`, + `bpcg`, `dav`, or `dav_subspace`. For the LCAO basis, `cusolver`, `cusolvermp`, and `elpa` are + supported on GPU. +- **single-card**: ABACUS allows for single-GPU acceleration. You can run ABACUS without any MPI + process by command `abacus`, and `ks_solver cusolver` is recommended for the LCAO basis. *note: + avoid using `mpirun -n 1 abacus`*. +- **multi-cards**: ABACUS allows for multi-GPU acceleration. If you have multiple GPU cards, you can + run ABACUS with several MPI processes, and each process will utilize one GPU card. For example, + the command `mpirun -n 2 abacus` will by default launch two GPUs for computation. If you only have + one card, this command will only start one GPU. *note: the number of MPI processes SHOULD be equal + to the number of GPU cards, unless you are using MPS in your computer.* ## Examples -We provides [examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/34_gpu) of gpu calculations. + +We provides [examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/34_gpu) +of gpu calculations. ## Known limitations + PW basis: -- Only k point parallelization is supported, so the input keyword `kpar` will be set to match the number of MPI tasks automatically. -- By default, CUDA architectures are automatically selected based on the CUDA Toolkit version. For CUDA versions before 13.0, architectures 60, 70, 75, 80, 86, 89, and 90 are compiled (if supported by the CUDA version). For CUDA 13.0 and later, only architectures 75 and above are compiled, as CUDA 13 dropped support for older architectures. This can be overridden using the CMake variable [`CMAKE_CUDA_ARCHITECTURES`](https://cmake.org/cmake/help/latest/variable/CMAKE_CUDA_ARCHITECTURES.html) or the environmental variable [`CUDAARCHS`](https://cmake.org/cmake/help/latest/envvar/CUDAARCHS.html). + +- Only k point parallelization is supported, so the input keyword `kpar` will be set to match the + number of MPI tasks automatically. +- By default, CUDA architectures are automatically selected based on the CUDA Toolkit version. For + CUDA versions before 13.0, architectures 60, 70, 75, 80, 86, 89, and 90 are compiled (if supported + by the CUDA version). For CUDA 13.0 and later, only architectures 75 and above are compiled, as + CUDA 13 dropped support for older architectures. This can be overridden using the CMake variable + [`CMAKE_CUDA_ARCHITECTURES`](https://cmake.org/cmake/help/latest/variable/CMAKE_CUDA_ARCHITECTURES.html) + or the environmental variable + [`CUDAARCHS`](https://cmake.org/cmake/help/latest/envvar/CUDAARCHS.html). LCAO basis: -- Unless there is a specific reason, avoid using multiple GPUs, as it can be slower than using a single GPU. This is because the generalized eigenvalue solution of the LCAO basis set will incur additional communication overhead when calculated on multiple cards. When the memory limit of a GPU card makes it insufficient to complete the task, it is recommended to use multiple cards for calculation. + +- Unless there is a specific reason, avoid using multiple GPUs, as it can be slower than using a + single GPU. This is because the generalized eigenvalue solution of the LCAO basis set will incur + additional communication overhead when calculated on multiple cards. When the memory limit of a + GPU card makes it insufficient to complete the task, it is recommended to use multiple cards for + calculation. - When using elpa on GPUs, some ELPA internal logs will be output. diff --git a/docs/advanced/elec_properties/Berry_phase.md b/docs/advanced/elec_properties/Berry_phase.md index 37d81518dab..4764aa21512 100644 --- a/docs/advanced/elec_properties/Berry_phase.md +++ b/docs/advanced/elec_properties/Berry_phase.md @@ -1,21 +1,32 @@ # Berry Phase Calculation -From version 2.0.0, ABACUS is capable of calculating macroscopic polarization of insulators by using the Berry phase method, known as the ["modern theory of polarization"](https://www.sciencedirect.com/science/article/abs/pii/S0022459612003234). To calculate the polarization, you need first to do a self-consistent calculation to get the converged charge density. Then, do a non-self-consistent calculation with berry_phase setting to 1. You need also to specify the direction of the polarization you want to calculate. An example is given in the directory [examples/berryphase/lcao_PbTiO3](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/26_berryphase/02_lcao_PbTiO3). +From version 2.0.0, ABACUS is capable of calculating macroscopic polarization of insulators by using +the Berry phase method, known as the +["modern theory of polarization"](https://www.sciencedirect.com/science/article/abs/pii/S0022459612003234). +To calculate the polarization, you need first to do a self-consistent calculation to get the +converged charge density. Then, do a non-self-consistent calculation with berry_phase setting to 1. +You need also to specify the direction of the polarization you want to calculate. An example is +given in the directory +[examples/berryphase/lcao_PbTiO3](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/26_berryphase/02_lcao_PbTiO3). To run this example, first do a self-consistent calculation: + ``` cp INPUT-scf INPUT cp KPT-scf KPT mpirun -np 4 abacus ``` + Then run a non-self-consistent berry-phase calculation: + ``` cp INPUT-nscf-c INPUT cp KPT-nscf-c KPT mpirun -np 4 abacus ``` -In this example, we calculate the electric polarization along c axis for PbTiO~3~, and below are the INPUT file (nscf) and KPT file (nscf): +In this example, we calculate the electric polarization along c axis for PbTiO~3~, and below are the +INPUT file (nscf) and KPT file (nscf): ``` INPUT_PARAMETERS @@ -31,11 +42,19 @@ berry_phase 1 // calculate Berry phase gdir 3 // calculate polarization along c axis ``` -Note: You need to turn off the symmetry when do Berry phase calculations. Currently, ABACUS support Berry phase calculation with nspin=1 and nspin=2. The Berry phase can be calculated in both pw and lcao bases. -- [berry_phase](../input_files/input-main.md#berry_phase) : 1, calculate berry phase; 0, no calculate berry phase. -- [gdir](../input_files/input-main.md#gdir) : 1, 2, 3, the lattice vector direction of the polarization you want to calculate. +Note: You need to turn off the symmetry when do Berry phase calculations. Currently, ABACUS support +Berry phase calculation with nspin=1 and nspin=2. The Berry phase can be calculated in both pw and +lcao bases. -The KPT file need to be modified according to gdir in the INPUT file. Generally, you need denser k points along this direction. For example, in the following KPT file, 4 k-points are taken along the a and b axes, and 8 k-points are taken along the c-axis. You should check the convergence of the k points when calculating the polarization. +- [berry_phase](../input_files/input-main.md#berry_phase) : 1, calculate berry phase; 0, no + calculate berry phase. +- [gdir](../input_files/input-main.md#gdir) : 1, 2, 3, the lattice vector direction of the + polarization you want to calculate. + +The KPT file need to be modified according to gdir in the INPUT file. Generally, you need denser k +points along this direction. For example, in the following KPT file, 4 k-points are taken along the +a and b axes, and 8 k-points are taken along the c-axis. You should check the convergence of the k +points when calculating the polarization. ``` K_POINTS @@ -43,9 +62,12 @@ K_POINTS Gamma 4 4 8 0 0 0 ``` -The results of the berry phase calculation are written in the โ€œrunning_nscf.logโ€ in the OUT folder. You may search for these results by searching for keywords โ€œPOLARIZATION CALCULATIONโ€. + +The results of the berry phase calculation are written in the โ€œrunning_nscf.logโ€ in the OUT folder. +You may search for these results by searching for keywords โ€œPOLARIZATION CALCULATIONโ€. The results are shown as follows: + ``` >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> | | @@ -70,6 +92,11 @@ The results are shown as follows: P = 0.8906925 (mod 2.1748536) ( 0.0000000, 0.0000000, 0.8906925) C/m^2 ``` -The electric polarization **P** is multivalued, which modulo a quantum e**R**/V~cell~. +The electric polarization **P** is multivalued, which modulo a quantum e**R**/V~cell~. -Note: The vectors R1, R2, and R3 refer to the three lattice vectors of the unit cell. When gdir=3, the calculated polarization is along the R3 direction. The three values in parentheses represent the re-projection of the polarization along the R3 direction onto the Cartesian coordinate system (i.e., the xyz coordinate system). To obtain the full polarization components in the Cartesian system, you need to calculate the polarization for R1, R2, and R3 separately, and then sum their respective x, y, and z components. +Note: The vectors R1, R2, and R3 refer to the three lattice vectors of the unit cell. When gdir=3, +the calculated polarization is along the R3 direction. The three values in parentheses represent the +re-projection of the polarization along the R3 direction onto the Cartesian coordinate system (i.e., +the xyz coordinate system). To obtain the full polarization components in the Cartesian system, you +need to calculate the polarization for R1, R2, and R3 separately, and then sum their respective x, +y, and z components. diff --git a/docs/advanced/elec_properties/Mulliken.md b/docs/advanced/elec_properties/Mulliken.md index c768e83c7ff..9bc50bfb8d0 100644 --- a/docs/advanced/elec_properties/Mulliken.md +++ b/docs/advanced/elec_properties/Mulliken.md @@ -1,7 +1,14 @@ # Mulliken Charge Analysis -From version 2.1.0, ABACUS has the function of Mulliken population analysis. The example can be found in [examples/mulliken](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/14_mulliken). \ -To use this function, set [out_mul](../input_files/input-main.md#out_mul) to `1` in the INPUT file. After calculation, there will be an output file named `mulliken.txt` in the output directory. In MD calculations, the output interval is controlled by the keyword [out_freq_ion](../input_files/input-main.md#out_freq_ion). In the file, there are contents like (`nspin 1`): +From version 2.1.0, ABACUS has the function of Mulliken population analysis. The example can be +found in +[examples/mulliken](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/14_mulliken). +\ +To use this function, set [out_mul](../input_files/input-main.md#out_mul) to `1` in the INPUT file. +After calculation, there will be an output file named `mulliken.txt` in the output directory. In MD +calculations, the output interval is controlled by the keyword +[out_freq_ion](../input_files/input-main.md#out_freq_ion). In the file, there are contents like +(`nspin 1`): ``` STEP: 0 @@ -35,7 +42,8 @@ Total Charge on atom: Si 4 ... ``` -The file gives Mulliken charge in turn according to the order of atoms in the system. For example, the following block is for the first atom in system (`nspin 2`), +The file gives Mulliken charge in turn according to the order of atoms in the system. For example, +the following block is for the first atom in system (`nspin 2`), ``` 0 Zeta of Si Spin 1 Spin 2 Sum Diff @@ -53,10 +61,11 @@ And the next block is for the second atom in system, and so on. For each atom, the file gives detailed Mulliken population analysis at different levels, -- magnetic quantum number level: such as lines beigin with โ€˜s,px,py,pz,...โ€™ -- azimuthal quantum number level: such as lines begin with โ€˜sum over mโ€™. -- principal quantum number level: such as lines begin with โ€˜sum over m+zetaโ€™. Here โ€˜zetaโ€™ - equals โ€˜zetaโ€™ in the file, which means how many radial atomic orbitals there are for a given orbital angular momentum. -- atomic level: such as lines begin with โ€˜Total Charge on atomโ€™. +- magnetic quantum number level: such as lines beigin with โ€˜s,px,py,pz,...โ€™ +- azimuthal quantum number level: such as lines begin with โ€˜sum over mโ€™. +- principal quantum number level: such as lines begin with โ€˜sum over m+zetaโ€™. Here โ€˜zetaโ€™ equals + โ€˜zetaโ€™ in the file, which means how many radial atomic orbitals there are for a given orbital + angular momentum. +- atomic level: such as lines begin with โ€˜Total Charge on atomโ€™. More orbital information can be found in 'Orbital' file output with 'mulliken.txt' when `out_mul 1` diff --git a/docs/advanced/elec_properties/band.md b/docs/advanced/elec_properties/band.md index c33f5fc829e..cff5db62d94 100644 --- a/docs/advanced/elec_properties/band.md +++ b/docs/advanced/elec_properties/band.md @@ -1,16 +1,26 @@ # Extracting Band Structure -For plane-wave screened hybrid calculations, follow the [hybrid NSCF workflow](hybrid_nscf.md), which additionally requires the frozen SCF orbitals and source q mesh. - -In ABACUS, in order to obtain the eigenvalues of Hamiltonian, or generally called band structure, examples can be found in [examples/band](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/12_band). -Similar to the [DOS case](https://abacus-rtd.readthedocs.io/en/latest/advanced/elec_properties/dos.html), one first needs to perform a ground-state energy calculation ***with one additional keyword "[out_chg](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-chg)" in the INPUT file***: +For plane-wave screened hybrid calculations, follow the [hybrid NSCF workflow](hybrid_nscf.md), +which additionally requires the frozen SCF orbitals and source q mesh. + +In ABACUS, in order to obtain the eigenvalues of Hamiltonian, or generally called band structure, +examples can be found in +[examples/band](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/12_band). +Similar to the +[DOS case](https://abacus-rtd.readthedocs.io/en/latest/advanced/elec_properties/dos.html), one first +needs to perform a ground-state energy calculation ***with one additional keyword +"[out_chg](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-chg)" +in the INPUT file***: ``` out_chg 1 ``` -With this input parameter, the converged charge density will be output in the files such as `chgs1.cube`, `chgs2.cube`, etc. -Then, one can use the same `STRU` file, pseudopotential files and atomic orbital files (and the local density matrix file occ_mat.txt if DFT+U is used) to do a non-self-consistent (NSCF) calculation. In this example, the potential is constructed from the ground-state charge density from the proceeding calculation. Now the INPUT file is like: +With this input parameter, the converged charge density will be output in the files such as +`chgs1.cube`, `chgs2.cube`, etc. Then, one can use the same `STRU` file, pseudopotential files and +atomic orbital files (and the local density matrix file occ_mat.txt if DFT+U is used) to do a +non-self-consistent (NSCF) calculation. In this example, the potential is constructed from the +ground-state charge density from the proceeding calculation. Now the INPUT file is like: ``` INPUT_PARAMETERS @@ -52,18 +62,18 @@ Line # line-mode This means we are using the following k-points: -- 6 k points, here means 6 k points: - (0.5, 0.0, 0.5) (0.0, 0.0, 0.0) (0.5, 0.5, 0.5) (0.5, 0.25, 0.75) (0.375, 0.375, 0.75) (0.0, 0.0, - 0.0) -- 20/1 number of k points along the segment line, which is constructed by two adjacent k - points. +- 6 k points, here means 6 k points: (0.5, 0.0, 0.5) (0.0, 0.0, 0.0) (0.5, 0.5, 0.5) (0.5, 0.25, + 0.75) (0.375, 0.375, 0.75) (0.0, 0.0, 0.0) +- 20/1 number of k points along the segment line, which is constructed by two adjacent k points. -Next, run ABACUS and you will see a file named `eigs1.txt` in the output directory. -Plot it and you will obtain the energy band structure! +Next, run ABACUS and you will see a file named `eigs1.txt` in the output directory. Plot it and you +will obtain the energy band structure! -If "out_proj_band" set 1, it will also produce the projected band structure in a file called PBAND_1 in xml format. +If "out_proj_band" set 1, it will also produce the projected band structure in a file called PBAND_1 +in xml format. -The PBAND_1 file starts with number of atomic orbitals in the system, the text contents of element `` is the same as data in the BANDS_1.dat file, such as: +The PBAND_1 file starts with number of atomic orbitals in the system, the text contents of element +`` is the same as data in the BANDS_1.dat file, such as: ``` diff --git a/docs/advanced/elec_properties/charge.md b/docs/advanced/elec_properties/charge.md index 393f5cdaa9c..302cb5b1fb2 100644 --- a/docs/advanced/elec_properties/charge.md +++ b/docs/advanced/elec_properties/charge.md @@ -1,13 +1,16 @@ # Extracting Charge Density -ABACUS can output the charge density by adding the keyword [out_chg](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-chg) in INPUT file: +ABACUS can output the charge density by adding the keyword +[out_chg](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-chg) +in INPUT file: ``` out_chg 1 ``` -After finishing the calculation, the information of the charge density is stroed in files `OUT.${suffix}/SPIN${spin}_CHG.cube`, which can be used to do visualization. -The SPIN${spin}_CHG.cube file looks like: +After finishing the calculation, the information of the charge density is stroed in files +`OUT.${suffix}/SPIN${spin}_CHG.cube`, which can be used to do visualization. The +SPIN${spin}\_CHG.cube file looks like: ``` STEP: 0 Cubefile created from ABACUS. Inner loop is z, followed by y and x @@ -34,10 +37,13 @@ STEP: 0 Cubefile created from ABACUS. Inner loop is z, followed by y and x The first line contains the current ion step.\ The second line contains NSPIN and Fermi energy.\ The following 4 lines are the informations of lattice, in order:\ - total number of atoms, the coordinate of original point.\ - the number of lattice points along lattice vector a1 (nx), a1/nx, in Bohr.\ - the number of lattice points along lattice vector a2 (ny), a2/ny, in Bohr.\ - the number of lattice points along lattice vector a3 (nz), a3/nz, in Bohr.\ -The following lines are about the elements and coordinates, in order: the atom number of each atoms, the electron number in pseudopotential, the Cartesian coordinates, in Bohr.\ -The rest lines are the value of charge density at each grid. Note that the inner loop is z index, followed by y index, x index in turn.\ -The examples can be found in [examples/charge_density](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/08_charge_density) +total number of atoms, the coordinate of original point.\ +the number of lattice points along lattice vector a1 (nx), a1/nx, in Bohr.\ +the number of lattice points along lattice vector a2 (ny), a2/ny, in Bohr.\ +the number of lattice points along lattice vector a3 (nz), a3/nz, in Bohr.\ +The following lines are about the elements and coordinates, in order: the atom number of each atoms, +the electron number in pseudopotential, the Cartesian coordinates, in Bohr.\ +The rest lines are the value of charge density at each grid. Note that the inner loop is z index, +followed by y index, x index in turn.\ +The examples can be found in +[examples/charge_density](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/08_charge_density) diff --git a/docs/advanced/elec_properties/density_matrix.md b/docs/advanced/elec_properties/density_matrix.md index 2155af8a239..b29f0d98f6d 100644 --- a/docs/advanced/elec_properties/density_matrix.md +++ b/docs/advanced/elec_properties/density_matrix.md @@ -1,20 +1,29 @@ # Extracting Density Matrices -ABACUS can output the density matrix by adding the keyword "[out_dmk](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out_dmk)" in INPUT file: +ABACUS can output the density matrix by adding the keyword +"[out_dmk](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out_dmk)" +in INPUT file: + ``` out_dmk 1 ``` + After finishing the calculation, the density matrix is written into `OUT.${suffix}/`. For current develop versions: -- gamma-only (`gamma_only = 1`): `dmg1_nao.txt` (`nspin=1/4`) or `dms1g1_nao.txt` and `dms2g1_nao.txt` (`nspin=2`) -- multi-k (`gamma_only = 0`): `dmk1g1_nao.txt`, `dmk2g1_nao.txt`, ... (`nspin=1/4`) or `dmk1s1g1_nao.txt`, `dmk1s2g1_nao.txt`, ... (`nspin=2`) + +- gamma-only (`gamma_only = 1`): `dmg1_nao.txt` (`nspin=1/4`) or `dms1g1_nao.txt` and + `dms2g1_nao.txt` (`nspin=2`) +- multi-k (`gamma_only = 0`): `dmk1g1_nao.txt`, `dmk2g1_nao.txt`, ... (`nspin=1/4`) or + `dmk1s1g1_nao.txt`, `dmk1s2g1_nao.txt`, ... (`nspin=2`) Here `g{istep}` denotes the geometry/step index in the output filename. -For 3.10-LTS, the corresponding keyword is `out_dm`, and file names follow the legacy style such as `SPIN1_DM` and `SPIN2_DM`. +For 3.10-LTS, the corresponding keyword is `out_dm`, and file names follow the legacy style such as +`SPIN1_DM` and `SPIN2_DM`. The file content looks like: + ``` test 5.39761 @@ -34,36 +43,49 @@ Direct 3.904e-01 1.114e-02 2.050e-14 1.655e-13 1.517e-13 -7.492e-15 -1.729e-14 5.915e-15 -9.099e-15 2.744e-14 3.146e-14 6.631e-15 2.594e-15 3.904e-01 1.114e-02 -7.395e-15 ... - ``` +``` + The first 5 lines are the informations of lattice, in order: \ - lattice name (if keyword [latname](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#latname) is not specified in INPUT, this will be "test"), \ - lattice constance with unit in angstrom, \ - lattice vector a, \ - lattice vector b, \ - lattice vector c. \ -The following lines are about the elements and coordinates, in order: all elements, the atom number of each elements, the type of coordinate, the coordinates.\ +lattice name (if keyword +[latname](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#latname) +is not specified in INPUT, this will be "test"), \ +lattice constance with unit in angstrom, \ +lattice vector a, \ +lattice vector b, \ +lattice vector c. \ +The following lines are about the elements and coordinates, in order: all elements, the atom number +of each elements, the type of coordinate, the coordinates.\ After a blank line, the output is the values of NSPIN and fermi energy.\ -The following line is dimension of the density matrix, and the rest lines are the value of each matrix element. +The following line is dimension of the density matrix, and the rest lines are the value of each +matrix element. -The examples can be found in [examples/density_matrix](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/09_density_matrix) +The examples can be found in +[examples/density_matrix](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/09_density_matrix) - Note: Version difference summary: - - develop: `out_dmk` supports both gamma-only and multi-k-point output. - - 3.10-LTS: use `out_dm`. + - develop: `out_dmk` supports both gamma-only and multi-k-point output. + - 3.10-LTS: use `out_dm`. ## Real-space Density Matrix (CSR format) -ABACUS can also output the real-space density matrix DM(R) in CSR (Compressed Sparse Row) format by setting: +ABACUS can also output the real-space density matrix DM(R) in CSR (Compressed Sparse Row) format by +setting: + ``` out_dmr 1 ``` + This feature is only valid for multi-k calculations (`gamma_only = 0`). After the calculation, the density matrix files are written to `OUT.${suffix}/`: + - develop naming pattern: `dmr{s}{spin index}{g}{geometry index}{_nao}.csr` - `nspin=1`: `dmrs1_nao.csr` - `nspin=2` (spin-polarized): `dmrs1_nao.csr` (spin-up) and `dmrs2_nao.csr` (spin-down) -For 3.10-LTS, the corresponding keyword is `out_dm1`, and the file names are `data-DMR-sparse_SPIN0.csr` and `data-DMR-sparse_SPIN1.csr`, etc. +For 3.10-LTS, the corresponding keyword is `out_dm1`, and the file names are +`data-DMR-sparse_SPIN0.csr` and `data-DMR-sparse_SPIN1.csr`, etc. -These files can be used to restart calculations by setting `init_chg dm` in the INPUT file together with `read_file_dir` pointing to the directory containing the CSR files. This is supported for both `nspin=1` and `nspin=2`. +These files can be used to restart calculations by setting `init_chg dm` in the INPUT file together +with `read_file_dir` pointing to the directory containing the CSR files. This is supported for both +`nspin=1` and `nspin=2`. diff --git a/docs/advanced/elec_properties/dos.md b/docs/advanced/elec_properties/dos.md index 47076b54cd5..fd7b61ce6ca 100644 --- a/docs/advanced/elec_properties/dos.md +++ b/docs/advanced/elec_properties/dos.md @@ -2,15 +2,21 @@ ## DOS -ABACUS can calculate the density of states (DOS) of the system, and the examples can be found in [examples/dos](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/13_dos). -We first, do a ground-state energy calculation ***with one additional keyword "[out_chg](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-chg)" in the INPUT file***: +ABACUS can calculate the density of states (DOS) of the system, and the examples can be found in +[examples/dos](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/13_dos). We +first, do a ground-state energy calculation ***with one additional keyword +"[out_chg](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-chg)" +in the INPUT file***: ``` out_chg 1 ``` -this will produce the converged charge density, which is contained in the file chg.cube. -Then, use the same `STRU` file, pseudopotential file and atomic orbital file (and the local density matrix file occ_mat.txt if DFT+U is used) to do a non-self-consistent calculation. In this example, the potential is constructed from the ground-state charge density from the proceeding calculation. Now the INPUT file is like: +this will produce the converged charge density, which is contained in the file chg.cube. Then, use +the same `STRU` file, pseudopotential file and atomic orbital file (and the local density matrix +file occ_mat.txt if DFT+U is used) to do a non-self-consistent calculation. In this example, the +potential is constructed from the ground-state charge density from the proceeding calculation. Now +the INPUT file is like: ``` INPUT_PARAMETERS @@ -39,27 +45,48 @@ Some parameters in the INPUT file are explained: - calculation - choose which kind of calculation: scf calculation, nscf calculation, structure relaxation or Molecular Dynamics. Now we need to do one step of nscf calculation. - Attention: This is a main variable of ABACUS, and for its more information please see the [here](https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#calculation). + choose which kind of calculation: scf calculation, nscf calculation, structure relaxation or + Molecular Dynamics. Now we need to do one step of nscf calculation. Attention: This is a main + variable of ABACUS, and for its more information please see the + [here](https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#calculation). + - pw_diag_thr - threshold for the CG method which diagonalizes the Hamiltonian to get eigenvalues and eigen wave functions. If one wants to do nscf calculation, pw_diag_thr needs to be changed to a smaller account, typically smaller than 1.0e-3. Note that this parameter only apply to plane-wave calculations that employ the CG or Davidson method to diagonalize the Hamiltonian. For its more information please see the [here](https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#pw_diag_thr). + threshold for the CG method which diagonalizes the Hamiltonian to get eigenvalues and eigen wave + functions. If one wants to do nscf calculation, pw_diag_thr needs to be changed to a smaller + account, typically smaller than 1.0e-3. Note that this parameter only apply to plane-wave + calculations that employ the CG or Davidson method to diagonalize the Hamiltonian. For its more + information please see the + [here](https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#pw_diag_thr). For LCAO calculations, this parameter will be neglected ! + - init_chg - the type of starting density. When doing scf calculation, this variable can be set โ€atomicโ€. When doing nscf calculation, the charge density already exists(eg. in chg.cube), and the variable should be set as โ€fileโ€. It means the density will be read from the existing file chg.cube. For its more information please see the [here](https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#init_chg). + the type of starting density. When doing scf calculation, this variable can be set โ€atomicโ€. When + doing nscf calculation, the charge density already exists(eg. in chg.cube), and the variable + should be set as โ€fileโ€. It means the density will be read from the existing file chg.cube. For + its more information please see the + [here](https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#init_chg). + - out_dos - output density of state(DOS). The unit of DOS is `(number of states)/(eV * unitcell)`. For its more information please see the [here](https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#out_dos). + output density of state(DOS). The unit of DOS is `(number of states)/(eV * unitcell)`. For its + more information please see the + [here](https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#out_dos). + - dos_sigma - the gaussian smearing parameter(DOS), in unit of eV. For its more information please see the [here](https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#dos_sigma). + the gaussian smearing parameter(DOS), in unit of eV. For its more information please see the + [here](https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#dos_sigma). + - read_file_dir - the location of electron density file. For its more information please see the [here](https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#read_file_dir). + the location of electron density file. For its more information please see the + [here](https://abacus-rtd--1282.org.readthedocs.build/en/1282/advanced/input_files/input-main.html#read_file_dir). -To have an accurate DOS, one needs to have a denser k-point mesh. For example, the KPT file can be set as: +To have an accurate DOS, one needs to have a denser k-point mesh. For example, the KPT file can be +set as: ``` K_POINTS @@ -68,9 +95,17 @@ Gamma 8 8 8 0 0 0 ``` -Run the program, and you will see a file named doss1g1.txt in the output directory. The columns are: energy(eV), dos (number of states in each energy bin), dos_int (integrated DOS), dos_smear(1/eV) (Gaussian-smeared DOS), dos_smear_int (integrated smeared DOS). Plot the file with graphing software, and you'll get the DOS. +Run the program, and you will see a file named doss1g1.txt in the output directory. The columns are: +energy(eV), dos (number of states in each energy bin), dos_int (integrated DOS), dos_smear(1/eV) +(Gaussian-smeared DOS), dos_smear_int (integrated smeared DOS). Plot the file with graphing +software, and you'll get the DOS. -The `dos` column is a raw per-bin histogram, while `dos_smear` is the physically meaningful density of states in 1/eV. The `abacus-plot` tool plots `dos_smear` by default; set `"smearing": false` in its config.json to plot the raw histogram instead, or apply your own smearing to the raw column with `abacus_plot.utils.gaussian_smearing`. For nspin=2, two files (doss1*/doss2*) are written, one per spin channel; the tool pairs them automatically whether you pass either file, a directory, or a list of both files. For nspin=4, a single spinor-summed file is written. +The `dos` column is a raw per-bin histogram, while `dos_smear` is the physically meaningful density +of states in 1/eV. The `abacus-plot` tool plots `dos_smear` by default; set `"smearing": false` in +its config.json to plot the raw histogram instead, or apply your own smearing to the raw column with +`abacus_plot.utils.gaussian_smearing`. For nspin=2, two files (doss1\*/doss2\*) are written, one per +spin channel; the tool pairs them automatically whether you pass either file, a directory, or a list +of both files. For nspin=4, a single spinor-summed file is written. ``` # energy(eV) dos dos_int dos_smear(1/eV) dos_smear_int @@ -82,9 +117,12 @@ The `dos` column is a raw per-bin histogram, while `dos_smear` is the physically ## PDOS -Along with the DOS files, we also produce the projected density of states (PDOS) in files named pdoss{spin}g{geom}.txt (e.g., pdoss1g1.txt). +Along with the DOS files, we also produce the projected density of states (PDOS) in files named +pdoss{spin}g{geom}.txt (e.g., pdoss1g1.txt). -The PDOS file uses a plain-text format. Each row corresponds to one energy point and one atom. Columns: energy(eV), atom (1-based), species, then pdos values ordered as s(1), p(3), d(5), f(7), etc. Zeta components are summed, and values below 1e-6 are zeroed out. +The PDOS file uses a plain-text format. Each row corresponds to one energy point and one atom. +Columns: energy(eV), atom (1-based), species, then pdos values ordered as s(1), p(3), d(5), f(7), +etc. Zeta components are summed, and values below 1e-6 are zeroed out. ``` # istep: 1 @@ -94,6 +132,10 @@ The PDOS file uses a plain-text format. Each row corresponds to one energy point ... ``` -The `# istep:` line is only present for geometry-optimization (istep) output. Within each angular momentum `l`, the `2l+1` columns follow the magnetic-quantum-number order `m = 0, +1, -1, +2, -2, ...`. +The `# istep:` line is only present for geometry-optimization (istep) output. Within each angular +momentum `l`, the `2l+1` columns follow the magnetic-quantum-number order +`m = 0, +1, -1, +2, -2, ...`. -For nspin=2, two files are written (pdoss1* and pdoss2*), one per spin channel. For nspin=4, the two spinor components are summed into a single file. The unit of PDOS is also `(number of states)/(eV * unitcell)`. +For nspin=2, two files are written (pdoss1\* and pdoss2\*), one per spin channel. For nspin=4, the +two spinor components are summed into a single file. The unit of PDOS is also +`(number of states)/(eV * unitcell)`. diff --git a/docs/advanced/elec_properties/hs_matrix.md b/docs/advanced/elec_properties/hs_matrix.md index 5adf14e3971..92e130f883d 100644 --- a/docs/advanced/elec_properties/hs_matrix.md +++ b/docs/advanced/elec_properties/hs_matrix.md @@ -1,93 +1,140 @@ # Extracting Hamiltonian and Overlap Matrices -In ABACUS, we provide the option to write the Hamiltonian and Overlap matrices to files after SCF calculations. +In ABACUS, we provide the option to write the Hamiltonian and Overlap matrices to files after SCF +calculations. -For periodic systems, there are two ways to construct the matrices. The reciprocal-space representation writes the entire square matrices $H(k)$ and $S(k)$ for each $k$ point in the Brillouin zone. The real-space representation writes $H(R)$ and $S(R)$ indexed by the Bravais lattice vector $R$. The two representations are connected by Fourier transform: +For periodic systems, there are two ways to construct the matrices. The reciprocal-space +representation writes the entire square matrices $H(k)$ and $S(k)$ for each $k$ point in the +Brillouin zone. The real-space representation writes $H(R)$ and $S(R)$ indexed by the Bravais +lattice vector $R$. The two representations are connected by Fourier transform: -- $H(k)=\sum_R H(R)e^{-ikR}$ +- $H(k)=\\sum_R H(R)e^{-ikR}$ and -- $S(k)=\sum_R S(R)e^{-ikR}$ +- $S(k)=\\sum_R S(R)e^{-ikR}$ ## out_hsk -Use [out_hsk](../input_files/input-main.md#out_hsk) to print the upper triangular part of the Hamiltonian and overlap matrices for each k point into `OUT.${suffix}`. It is available for both gamma-only and multi-k calculations. The format value is: +Use [out_hsk](../input_files/input-main.md#out_hsk) to print the upper triangular part of the +Hamiltonian and overlap matrices for each k point into `OUT.${suffix}`. It is available for both +gamma-only and multi-k calculations. The format value is: -| Value | Format | -| --- | --- | -| `0` | Disabled | -| `1` | Text; an optional second value controls precision, for example `out_hsk 1 12` | -| `2` | Native binary `.dat` output | -| `3` | Reserved for H(k)/S(k) NPZ output; not implemented | +| Value | Format | +| ----- | ----------------------------------------------------------------------------- | +| `0` | Disabled | +| `1` | Text; an optional second value controls precision, for example `out_hsk 1 12` | +| `2` | Native binary `.dat` output | +| `3` | Reserved for H(k)/S(k) NPZ output; not implemented | -The legacy keyword `out_mat_hs 1 [precision]` remains supported as an alias for `out_hsk 1 [precision]`. If both names are present, `out_hsk` takes precedence. +The legacy keyword `out_mat_hs 1 [precision]` remains supported as an alias for +`out_hsk 1 [precision]`. If both names are present, `out_hsk` takes precedence. -The $H(k)$ and $S(k)$ matrices are stored with numerical atomic orbitals as basis, and the corresponding sequence of the numerical atomic orbitals can be seen in [Basis Set](../pp_orb.md#basis-set). +The $H(k)$ and $S(k)$ matrices are stored with numerical atomic orbitals as basis, and the +corresponding sequence of the numerical atomic orbitals can be seen in +[Basis Set](../pp_orb.md#basis-set). -As for information on the k points, one may look for the `SETUP K-POINTS` section in the running log. +As for information on the k points, one may look for the `SETUP K-POINTS` section in the running +log. The output filenames depend on the k-point algorithm and `nspin`: -| Calculation mode | `nspin` | Hamiltonian files | Overlap files | -| --- | --- | --- | --- | -| `gamma_only = 1` | 1 | `hk_nao.txt` | `sk_nao.txt` | -| `gamma_only = 1` | 2 | `hks1_nao.txt`, `hks2_nao.txt` | `sk_nao.txt` | -| `gamma_only = 0` | 1 | `hk${k}_nao.txt` | `sk${k}_nao.txt` | -| `gamma_only = 0` | 2 | `hk${k}s1_nao.txt`, `hk${k}s2_nao.txt` | `sk${k}_nao.txt` | -| `gamma_only = 0` | 4 | `hk${k}s4_nao.txt` | `sk${k}_nao.txt` | +| Calculation mode | `nspin` | Hamiltonian files | Overlap files | +| ---------------- | ------- | -------------------------------------- | ---------------- | +| `gamma_only = 1` | 1 | `hk_nao.txt` | `sk_nao.txt` | +| `gamma_only = 1` | 2 | `hks1_nao.txt`, `hks2_nao.txt` | `sk_nao.txt` | +| `gamma_only = 0` | 1 | `hk${k}_nao.txt` | `sk${k}_nao.txt` | +| `gamma_only = 0` | 2 | `hk${k}s1_nao.txt`, `hk${k}s2_nao.txt` | `sk${k}_nao.txt` | +| `gamma_only = 0` | 4 | `hk${k}s4_nao.txt` | `sk${k}_nao.txt` | -Here `${k}` is the one-based k-point index. For `nspin = 2`, the overlap matrix is spin-independent, so only one overlap file is written for each physical k point. The gamma-only algorithm does not support `nspin = 4`; use the multi-k algorithm with an explicit Gamma-only `KPT` file for a noncollinear calculation at Gamma. +Here `${k}` is the one-based k-point index. For `nspin = 2`, the overlap matrix is spin-independent, +so only one overlap file is written for each physical k point. The gamma-only algorithm does not +support `nspin = 4`; use the multi-k algorithm with an explicit Gamma-only `KPT` file for a +noncollinear calculation at Gamma. -When `out_app_flag` is false, `g${step}` is inserted before `_nao`, where `${step}` is the one-based ionic-step index. For example, the first spin channel at the first k point and first ionic step is written to `hk1s1g1_nao.txt`. +When `out_app_flag` is false, `g${step}` is inserted before `_nao`, where `${step}` is the one-based +ionic-step index. For example, the first spin channel at the first k point and first ionic step is +written to `hk1s1g1_nao.txt`. -Each output block starts with a comment header containing the one-based ionic-step index, filename, `gamma only` flag, and matrix dimensions. It is followed by `Row 1`, `Row 2`, and so on. Each row contains the matrix elements from the diagonal through the upper triangle. +Each output block starts with a comment header containing the one-based ionic-step index, filename, +`gamma only` flag, and matrix dimensions. It is followed by `Row 1`, `Row 2`, and so on. Each row +contains the matrix elements from the diagonal through the upper triangle. -For multi-k calculations, the matrices are Hermitian and each matrix element is written as `(real,imag)`. For gamma-only calculations, the matrices are symmetric and the matrix elements are written as real numbers. +For multi-k calculations, the matrices are Hermitian and each matrix element is written as +`(real,imag)`. For gamma-only calculations, the matrices are symmetric and the matrix elements are +written as real numbers. -> **Note (3.10-LTS):** In the 3.10-LTS version, the corresponding keyword is `out_mat_hs`, and the output file names are `data-0-H` and `data-0-S`, etc. +> **Note (3.10-LTS):** In the 3.10-LTS version, the corresponding keyword is `out_mat_hs`, and the +> output file names are `data-0-H` and `data-0-S`, etc. ### Native Binary Format -For `out_hsk 2`, the filenames in the table above use `.dat` instead of `.txt`. Each matrix record is written without padding or a self-describing header: +For `out_hsk 2`, the filenames in the table above use `.dat` instead of `.txt`. Each matrix record +is written without padding or a self-describing header: 1. the matrix dimension as a native C++ `int`; -2. the upper-triangular elements in row-major order, from `(0,0)` through `(0,N-1)`, then `(1,1)` through `(1,N-1)`, and so on; -3. each gamma-only element as one native `double`, or each multi-k/spinor element as two consecutive native `double` values containing the real and imaginary parts. +1. the upper-triangular elements in row-major order, from `(0,0)` through `(0,N-1)`, then `(1,1)` + through `(1,N-1)`, and so on; +1. each gamma-only element as one native `double`, or each multi-k/spinor element as two consecutive + native `double` values containing the real and imaginary parts. -The file therefore contains `sizeof(int) + N(N+1)/2 * sizeof(double)` bytes for a gamma-only record and `sizeof(int) + N(N+1) * sizeof(double)` bytes for a multi-k or spinor record. The format uses the host integer representation and byte order and is intended for readers using a compatible ABI. +The file therefore contains `sizeof(int) + N(N+1)/2 * sizeof(double)` bytes for a gamma-only record +and `sizeof(int) + N(N+1) * sizeof(double)` bytes for a multi-k or spinor record. The format uses +the host integer representation and byte order and is intended for readers using a compatible ABI. -When `out_app_flag` is true, the first ionic step truncates the shared file and every later step appends another complete record. When it is false, each ionic step has a separate filename containing `g${step}` before `_nao`. +When `out_app_flag` is true, the first ionic step truncates the shared file and every later step +appends another complete record. When it is false, each ionic step has a separate filename +containing `g${step}` before `_nao`. ## out_hsr -The output of $H(R)$ and $S(R)$ matrices is controlled by [out_hsr](../input_files/input-main.md#out_hsr). It is available for both gamma-only and multi-k LCAO calculations: - -| Value | Format | -| --- | --- | -| `0` | Disabled | -| `1` | Text CSR; an optional second value controls precision, for example `out_hsr 1 12` | -| `2` | Native binary CSR using `.dat` files | -| `3` | NPZ: `hrs1_nao.npz`, `hrs2_nao.npz` when needed, and `sr_nao.npz` | - -The legacy keywords `out_mat_hs2 1 [precision]` and `out_hsr_npz 1` remain supported as aliases for text and NPZ output respectively. If `out_hsr` is present together with either legacy keyword, `out_hsr` takes precedence. - -For a multi-k calculation, the files contain the individual real-space blocks stored for the Bravais lattice vectors $R$. For a gamma-only calculation, ABACUS stores the real-space contributions in a folded representation. Text CSR, native binary, and NPZ output write this internal representation directly: all stored $R$-space contributions are summed into a single block labelled `R = (0, 0, 0)`. - -The folded gamma-only output is sufficient to inspect the matrix used by the gamma-only real-space container, but it does not retain the original lattice-vector resolution and cannot be used to interpolate matrices at arbitrary k points. Terms that are added only while constructing $H(k)$, rather than stored in the internal $H(R)$ container, are not guaranteed to be present. Use [out_hsk](../input_files/input-main.md#out_hsk) when the final $H(\Gamma)$ and $S(\Gamma)$ matrices are required. - -> **Note (3.10-LTS):** In the 3.10-LTS version, the corresponding keyword is `out_mat_hs2`, and the output file names are `data-HR-sparse_SPIN0.csr` and `data-SR-sparse_SPIN0.csr`, etc. +The output of $H(R)$ and $S(R)$ matrices is controlled by +[out_hsr](../input_files/input-main.md#out_hsr). It is available for both gamma-only and multi-k +LCAO calculations: + +| Value | Format | +| ----- | --------------------------------------------------------------------------------- | +| `0` | Disabled | +| `1` | Text CSR; an optional second value controls precision, for example `out_hsr 1 12` | +| `2` | Native binary CSR using `.dat` files | +| `3` | NPZ: `hrs1_nao.npz`, `hrs2_nao.npz` when needed, and `sr_nao.npz` | + +The legacy keywords `out_mat_hs2 1 [precision]` and `out_hsr_npz 1` remain supported as aliases for +text and NPZ output respectively. If `out_hsr` is present together with either legacy keyword, +`out_hsr` takes precedence. + +For a multi-k calculation, the files contain the individual real-space blocks stored for the Bravais +lattice vectors $R$. For a gamma-only calculation, ABACUS stores the real-space contributions in a +folded representation. Text CSR, native binary, and NPZ output write this internal representation +directly: all stored $R$-space contributions are summed into a single block labelled +`R = (0, 0, 0)`. + +The folded gamma-only output is sufficient to inspect the matrix used by the gamma-only real-space +container, but it does not retain the original lattice-vector resolution and cannot be used to +interpolate matrices at arbitrary k points. Terms that are added only while constructing $H(k)$, +rather than stored in the internal $H(R)$ container, are not guaranteed to be present. Use +[out_hsk](../input_files/input-main.md#out_hsk) when the final $H(\\Gamma)$ and $S(\\Gamma)$ +matrices are required. + +> **Note (3.10-LTS):** In the 3.10-LTS version, the corresponding keyword is `out_mat_hs2`, and the +> output file names are `data-HR-sparse_SPIN0.csr` and `data-SR-sparse_SPIN0.csr`, etc. ### Text CSR Format -The H(R) and S(R) matrices are output in standard Compressed Sparse Row (CSR) format, matching the format used by `out_dmr`. +The H(R) and S(R) matrices are output in standard Compressed Sparse Row (CSR) format, matching the +format used by `out_dmr`. For single-point SCF calculations: -- **nspin = 1**: Two files `hrs1_nao.csr` and `sr_nao.csr` are generated, containing the Hamiltonian matrix $H(R)$ and overlap matrix $S(R)$ respectively. -- **nspin = 2**: Three files `hrs1_nao.csr`, `hrs2_nao.csr`, and `sr_nao.csr` are created, where the first two files correspond to $H(R)$ for spin up and spin down, respectively. -- **nspin = 4**: Multi-k calculations generate `hrs1_nao.csr` and `sr_nao.csr`. The gamma-only algorithm itself does not support `nspin = 4`. -In gamma-only mode, every generated file reports one Bravais lattice vector and contains one CSR block for `0 0 0`. The header also contains: +- **nspin = 1**: Two files `hrs1_nao.csr` and `sr_nao.csr` are generated, containing the Hamiltonian + matrix $H(R)$ and overlap matrix $S(R)$ respectively. +- **nspin = 2**: Three files `hrs1_nao.csr`, `hrs2_nao.csr`, and `sr_nao.csr` are created, where the + first two files correspond to $H(R)$ for spin up and spin down, respectively. +- **nspin = 4**: Multi-k calculations generate `hrs1_nao.csr` and `sr_nao.csr`. The gamma-only + algorithm itself does not support `nspin = 4`. + +In gamma-only mode, every generated file reports one Bravais lattice vector and contains one CSR +block for `0 0 0`. The header also contains: ```text # representation: gamma-only folded matrix; stored R-space contributions are summed into R = (0, 0, 0) @@ -95,27 +142,41 @@ In gamma-only mode, every generated file reports one Bravais lattice vector and ### Native Binary CSR Format -Set `out_hsr 2` to write the same H(R) and S(R) matrix sets with a `.dat` suffix. For example, an `nspin = 2` calculation writes `hrs1_nao.dat`, `hrs2_nao.dat`, and `sr_nao.dat`. When `out_app_flag` is false, the one-based ionic step is included before `_nao`, for example `hrs1g1_nao.dat` and `srg1_nao.dat`. +Set `out_hsr 2` to write the same H(R) and S(R) matrix sets with a `.dat` suffix. For example, an +`nspin = 2` calculation writes `hrs1_nao.dat`, `hrs2_nao.dat`, and `sr_nao.dat`. When `out_app_flag` +is false, the one-based ionic step is included before `_nao`, for example `hrs1g1_nao.dat` and +`srg1_nao.dat`. Each ionic step is a complete record with no padding or self-describing header: 1. Native `int`: zero-based ionic step, matrix dimension, number of R blocks. -2. For every R block in lexicographic `(Rx, Ry, Rz)` order, four native `int` values: `Rx`, `Ry`, `Rz`, and `nnz`. -3. `nnz` matrix values in CSR order. Real matrices use one native `double`; complex matrices use consecutive real and imaginary `double` values. -4. `nnz` native `int` column indices. -5. `dimension + 1` native `long long` row pointers. - -All R blocks stored by the internal HContainer are present, including blocks with zero nonzero values. The sparse threshold is `1e-10`, matching text CSR output. The format uses the host integer representation and byte order and therefore requires a compatible ABI. It does not contain unit-cell, spin, or matrix-label metadata; those are determined by the calculation input and filename. - -When `out_app_flag` is true, the first ionic step truncates the shared file and later ionic steps append complete records. Otherwise every ionic step is written to its own file. +1. For every R block in lexicographic `(Rx, Ry, Rz)` order, four native `int` values: `Rx`, `Ry`, + `Rz`, and `nnz`. +1. `nnz` matrix values in CSR order. Real matrices use one native `double`; complex matrices use + consecutive real and imaginary `double` values. +1. `nnz` native `int` column indices. +1. `dimension + 1` native `long long` row pointers. + +All R blocks stored by the internal HContainer are present, including blocks with zero nonzero +values. The sparse threshold is `1e-10`, matching text CSR output. The format uses the host integer +representation and byte order and therefore requires a compatible ABI. It does not contain +unit-cell, spin, or matrix-label metadata; those are determined by the calculation input and +filename. + +When `out_app_flag` is true, the first ionic step truncates the shared file and later ionic steps +append complete records. Otherwise every ionic step is written to its own file. ### NPZ Format -Set `out_hsr 3` to write `hrs1_nao.npz`, `hrs2_nao.npz` when a second spin channel is present, and `sr_nao.npz`. Matrix entry names include the atom-pair indices and the three components of $R$. Multi-k calculations retain the stored $R$ blocks, while gamma-only calculations contain only matrix entry names ending in `_0_0_0`. +Set `out_hsr 3` to write `hrs1_nao.npz`, `hrs2_nao.npz` when a second spin channel is present, and +`sr_nao.npz`. Matrix entry names include the atom-pair indices and the three components of $R$. +Multi-k calculations retain the stored $R$ blocks, while gamma-only calculations contain only matrix +entry names ending in `_0_0_0`. ### File Structure Each file starts with a header: + ``` --- Ionic Step 1 --- # print H matrix in real space H(R) @@ -138,31 +199,48 @@ Each file starts with a header: 0 3 7 ... ``` -The spin index line may carry an optional `, E_Fermi = eV` suffix when the Fermi energy is available (only for the H matrix). The value is printed in eV with 6 significant digits. +The spin index line may carry an optional `, E_Fermi = eV` suffix when the Fermi energy is +available (only for the H matrix). The value is printed in eV with 6 significant digits. -The CSR format stores a sparse m ร— n matrix M in row form using three arrays (values, column indices, row pointers). According to Wikipedia: +The CSR format stores a sparse m ร— n matrix M in row form using three arrays (values, column +indices, row pointers). According to Wikipedia: -- The arrays **values** and **column indices** are of length NNZ (number of nonzero entries), and contain the non-zero values and the column indices of those values respectively. -- The array **row pointers** is of length m + 1 and encodes the index where each row starts. The last element is NNZ. +- The arrays **values** and **column indices** are of length NNZ (number of nonzero entries), and + contain the non-zero values and the column indices of those values respectively. +- The array **row pointers** is of length m + 1 and encodes the index where each row starts. The + last element is NNZ. ### Precision Control -Use `out_hsr 1 12` to output text CSR files with 12-digit precision (default is 8). Precision is ignored for native binary and NPZ output. +Use `out_hsr 1 12` to output text CSR files with 12-digit precision (default is 8). Precision is +ignored for native binary and NPZ output. -For calculations involving ionic movements, the output frequency of the matrix is controlled by [out_freq_ion](../input_files/input-main.md#out_freq_ion) and [out_app_flag](../input_files/input-main.md#out_app_flag). +For calculations involving ionic movements, the output frequency of the matrix is controlled by +[out_freq_ion](../input_files/input-main.md#out_freq_ion) and +[out_app_flag](../input_files/input-main.md#out_app_flag). ## get_s -We also offer the option of only calculating the overlap matrix without running SCF. For that purpose, in `INPUT` file we need to set the value keyword [calculation](../input_files/input-main.md#calculation) to be `get_s`. -A file named `sr_nao.csr` will be generated in `OUT.${suffix}`, which contains the overlap matrix. +We also offer the option of only calculating the overlap matrix without running SCF. For that +purpose, in `INPUT` file we need to set the value keyword +[calculation](../input_files/input-main.md#calculation) to be `get_s`. -> When `nspin` is set to 1 or 2, the dimension of the overlap matrix is nlocal $\times$ nlocal, where nlocal is the total number of numerical atomic orbitals. -These numerical atomic orbitals are ordered from outer to inner loop as atom, angular quantum number $l$, zeta (multiple radial orbitals corresponding to each $l$), and magnetic quantum number $m$. -When `nspin` is set to 4, the dimension of the overlap matrix is (2 $\times$ nlocal) $\times$ (2 $\times$ nlocal). In this case, the numerical atomic orbitals are ordered from outer to inner loop as atom, angular quantum number $l$, zeta (multiple radial orbitals corresponding to each $l$), magnetic quantum number $m$, and npol (index of spin, ranges from 0 to 1). +A file named `sr_nao.csr` will be generated in `OUT.${suffix}`, which contains the overlap matrix. +> When `nspin` is set to 1 or 2, the dimension of the overlap matrix is nlocal $\\times$ nlocal, +> where nlocal is the total number of numerical atomic orbitals. These numerical atomic orbitals are +> ordered from outer to inner loop as atom, angular quantum number $l$, zeta (multiple radial +> orbitals corresponding to each $l$), and magnetic quantum number $m$. When `nspin` is set to 4, +> the dimension of the overlap matrix is (2 $\\times$ nlocal) $\\times$ (2 $\\times$ nlocal). In +> this case, the numerical atomic orbitals are ordered from outer to inner loop as atom, angular +> quantum number $l$, zeta (multiple radial orbitals corresponding to each $l$), magnetic quantum +> number $m$, and npol (index of spin, ranges from 0 to 1). ## examples -We provide [examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/10_hs_matrix) of outputting the matrices. + +We provide +[examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/10_hs_matrix) of +outputting the matrices. - `03_out_hsk_gamma`: writing H(k) and S(k) for a gamma-only calculation - `04_out_hsk_multik`: writing H(k) and S(k) for a multi-k calculation diff --git a/docs/advanced/elec_properties/hybrid_nscf.md b/docs/advanced/elec_properties/hybrid_nscf.md index 1994a14e5d7..29c7880f149 100644 --- a/docs/advanced/elec_properties/hybrid_nscf.md +++ b/docs/advanced/elec_properties/hybrid_nscf.md @@ -1,9 +1,8 @@ # PW screened hybrid NSCF -Hybrid NSCF reads the charge density, binary `wfk*_pw.dat` wavefunctions and -weighted occupations in `eig_occ.txt` from a converged SCF calculation. It keeps -that source fixed while solving a new K-point list or additional target bands. -No new file format is required. +Hybrid NSCF reads the charge density, binary `wfk*_pw.dat` wavefunctions and weighted occupations in +`eig_occ.txt` from a converged SCF calculation. It keeps that source fixed while solving a new +K-point list or additional target bands. No new file format is required. ## SCF @@ -29,9 +28,8 @@ cal_stress 0 ## NSCF -Keep the same structure, pseudopotentials and cutoffs. In a separate output -directory, retain the shared settings above, replace `KPT` with the target -points, and change: +Keep the same structure, pseudopotentials and cutoffs. In a separate output directory, retain the +shared settings above, replace `KPT` with the target points, and change: ```text calculation nscf @@ -43,18 +41,16 @@ out_wfc_pw 0 out_chg 0 ``` -Supports CPU/CUDA and `nspin 1/2`; use one MPI rank for CUDA. ACE, SOC, -unscreened exchange, forces and stress are unsupported in this workflow. -Set `symmetry -1`: input `0` is accepted but PW EXX resets it to `-1` at runtime. +Supports CPU/CUDA and `nspin 1/2`; use one MPI rank for CUDA. ACE, SOC, unscreened exchange, forces +and stress are unsupported in this workflow. Set `symmetry -1`: input `0` is accepted but PW EXX +resets it to `-1` at runtime. -HSE defaults to `exx_singularity_correction limits`, as in LCAO. Set `gygi` to -retain the historical PW correction, which can produce jumps at source K points. -Use matching SCF/NSCF settings for consistent bands. Do not use Methfessel-Paxton -smearing (`mp`/`mp2`/`mp3`) for the source: it can write occupations outside -`[0, k-point weight]`, which hybrid NSCF rejects; the non-negative schemes -(`fixed`, `gauss`, `mv`, `fd`) are accepted. Configuration differences -or missing `INPUT.info` produce warnings; missing or incompatible numerical -source data produces an error. +HSE defaults to `exx_singularity_correction limits`, as in LCAO. Set `gygi` to retain the historical +PW correction, which can produce jumps at source K points. Use matching SCF/NSCF settings for +consistent bands. Do not use Methfessel-Paxton smearing (`mp`/`mp2`/`mp3`) for the source: it can +write occupations outside `[0, k-point weight]`, which hybrid NSCF rejects; the non-negative schemes +(`fixed`, `gauss`, `mv`, `fd`) are accepted. Configuration differences or missing `INPUT.info` +produce warnings; missing or incompatible numerical source data produces an error. ## Verification diff --git a/docs/advanced/elec_properties/position_matrix.md b/docs/advanced/elec_properties/position_matrix.md index c504a866b64..85f63ca435e 100644 --- a/docs/advanced/elec_properties/position_matrix.md +++ b/docs/advanced/elec_properties/position_matrix.md @@ -1,12 +1,19 @@ # Extracting Position Matrices -In ABACUS, we provide the INPUT keyword [out_mat_r](../input_files/input-main.md#out_mat_r) to write the position matrices into a file named `data-rR-tr` in the directory `OUT.${suffix}`. The position matrices is defined as: +In ABACUS, we provide the INPUT keyword [out_mat_r](../input_files/input-main.md#out_mat_r) to write +the position matrices into a file named `data-rR-tr` in the directory `OUT.${suffix}`. The position +matrices is defined as: -$$\langle \chi_\mu|\hat{r}|\chi_\nu\rangle$$ +$$\\langle \\chi\_\\mu|\\hat{r}|\\chi\_\\nu\\rangle$$ -This functionality is not available for gamma_only calculations. If you want to use it in gamma_only calculations, you should turn off [gamma_only](../input_files/input-main.md#gamma_only), and explicitly specifies that gamma point is the only k point in the KPT file. +This functionality is not available for gamma_only calculations. If you want to use it in gamma_only +calculations, you should turn off [gamma_only](../input_files/input-main.md#gamma_only), and +explicitly specifies that gamma point is the only k point in the KPT file. -Each file or each section of the appended file starts with "STEP: " followed by the current ion/md step, then the second line starts with "Matrix Dimension of $r(R)$: " followed by the dimension of the matrix, and the third line starts with "Matrix number of $r(R)$: " followed by the matrix number. The rest of the format is arranged into blocks, such as: +Each file or each section of the appended file starts with "STEP: " followed by the current ion/md +step, then the second line starts with "Matrix Dimension of $r(R)$: " followed by the dimension of +the matrix, and the third line starts with "Matrix number of $r(R)$: " followed by the matrix +number. The rest of the format is arranged into blocks, such as: ``` -5 -5 -5 //R (lattice vector) @@ -16,9 +23,20 @@ Each file or each section of the appended file starts with "STEP: " followed by -5 -5 -3 //R (lattice vector) ``` -Each block here contains the matrix for the corresponding cell. There are three columns in each block, giving the matrix elements in x, y, z directions, respectively. There are altogether nbasis * nbasis lines in each block, which emulates the matrix elements. +Each block here contains the matrix for the corresponding cell. There are three columns in each +block, giving the matrix elements in x, y, z directions, respectively. There are altogether nbasis +\* nbasis lines in each block, which emulates the matrix elements. -In molecular dynamics (MD) calculations, if [out_app_flag](../input_files/input-main.md#out_app_flag) is set to true, then `data-rR-tr` is written in an append manner. Otherwise, output files will be put in a separate directory, `matrix`, and named as `$x`_data-rR-tr, where `$x` is the number of MD step. In addition, the output frequency is controlled by [out_freq_ion](../input_files/input-main.md#out_freq_ion). For example, if we are running a 10-step MD with out_freq_ion = 3, then `$x` will be 0, 3, 6, and 9. +In molecular dynamics (MD) calculations, if +[out_app_flag](../input_files/input-main.md#out_app_flag) is set to true, then `data-rR-tr` is +written in an append manner. Otherwise, output files will be put in a separate directory, `matrix`, +and named as `$x`\_data-rR-tr, where `$x` is the number of MD step. In addition, the output +frequency is controlled by [out_freq_ion](../input_files/input-main.md#out_freq_ion). For example, +if we are running a 10-step MD with out_freq_ion = 3, then `$x` will be 0, 3, 6, and 9. ## get_s -We also offer the option of only calculating the position matrix without running SCF. For that purpose, in `INPUT` file we need to set the keyword [calculation](../input_files/input-main.md#calculation) to `get_s`, and [out_mat_r](../input_files/input-main.md#out_mat_r) to `true`. + +We also offer the option of only calculating the position matrix without running SCF. For that +purpose, in `INPUT` file we need to set the keyword +[calculation](../input_files/input-main.md#calculation) to `get_s`, and +[out_mat_r](../input_files/input-main.md#out_mat_r) to `true`. diff --git a/docs/advanced/elec_properties/potential.md b/docs/advanced/elec_properties/potential.md index 960ceda0c70..836deb25374 100644 --- a/docs/advanced/elec_properties/potential.md +++ b/docs/advanced/elec_properties/potential.md @@ -1,6 +1,11 @@ # Extracting Electrostatic Potential -From version 2.1.0, ABACUS has the function of outputing electrostatic potential, which consists of Hartree potential and the local pseudopotential. To use this function, set โ€˜[out_pot](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-pot)โ€™ to โ€˜2โ€™ in the INPUT file. Here is an example for the [Si-111 surface](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/30_elec_pot/01_lcao_Si), and the INPUT file is: +From version 2.1.0, ABACUS has the function of outputing electrostatic potential, which consists of +Hartree potential and the local pseudopotential. To use this function, set +โ€˜[out_pot](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-pot)โ€™ +to โ€˜2โ€™ in the INPUT file. Here is an example for the +[Si-111 surface](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/30_elec_pot/01_lcao_Si), +and the INPUT file is: ``` INPUT_PARAMETERS @@ -104,4 +109,5 @@ Gamma Run the program, and you will see the following two files in the output directory, -- ElecStaticPot.cube: contains electrostatic potential (unit: Rydberg) in realspace. This file can be visually viewed by the software of VESTA. +- ElecStaticPot.cube: contains electrostatic potential (unit: Rydberg) in realspace. This file can + be visually viewed by the software of VESTA. diff --git a/docs/advanced/elec_properties/wfc.md b/docs/advanced/elec_properties/wfc.md index 354d8844fc4..1f3bc8b8563 100644 --- a/docs/advanced/elec_properties/wfc.md +++ b/docs/advanced/elec_properties/wfc.md @@ -1,27 +1,59 @@ # Extracting Wave Functions -ABACUS is able to output electron wave functions in both PW and LCAO basis calculations. One can find the examples in [examples/11_wfc](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/11_wfc). +ABACUS is able to output electron wave functions in both PW and LCAO basis calculations. One can +find the examples in +[examples/11_wfc](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/11_wfc). ## Wave Function in G-Space -For `basis_type=pw` and `esolver_type=ksdft`, [`out_wfc_pw`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-pw) controls the output of plane-wave Kohn-Sham coefficients: - -* `0`: Do not write wave-function coefficients. -* `1`: Write text files with the `.txt` suffix. -* `2`: Write binary files with the `.dat` suffix. - -The files are stored in `OUT.${suffix}/`. Their pattern is `wfk{k}[s{spin}][g{geometry step}][e{electronic iteration}]_pw.txt` for `out_wfc_pw=1` and `wfk{k}[s{spin}][g{geometry step}][e{electronic iteration}]_pw.dat` for `out_wfc_pw=2`. The `s*` label is omitted for `nspin=1`, is `s1` or `s2` for `nspin=2`, and is `s4` for `nspin=4`. All PW files include the `k*` label, including Gamma-only calculations. - -With `out_freq_ion=0`, files are written only when the electronic calculation converges or reaches `scf_nmax`, and the names contain neither `g*` nor `e*`. During structural relaxation or molecular dynamics, each later ionic step overwrites the same files. With `out_freq_ion>0`, output is restricted to the ionic steps selected by `out_freq_ion` and occurs at multiples of `out_freq_elec`, at convergence, or at `scf_nmax`; both `g*` and `e*` are included in the file names. A static `calculation=scf` or `calculation=nscf` run also receives `g1e*` indices when `out_freq_ion>0`. - -The [`init_wfc file binary`](../scf/initialization.md#wavefunction) path reads only unindexed binary `wf*_pw.dat` files from `read_file_dir`. Generate directly reusable files with `out_wfc_pw=2` and normally `out_freq_ion=0`. Text `wf*_pw.txt` files and files containing `g*` or `e*` indices are not matched automatically. - -For `basis_type=lcao`, [`out_wfc_lcao`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-lcao) controls the output of numerical-atomic-orbital coefficients: `1` writes text files with the `.txt` suffix and `2` writes binary files with the `.dat` suffix. Multi-k calculations generate `wfs{spin}k{k-point}_nao.txt` or `.dat`, while Gamma-only calculations generate `wfs{spin}_nao.txt` or `.dat`. - -To reuse LCAO coefficients, point `read_file_dir` to the coefficient files and set `init_wfc file txt` for text input or `init_wfc file binary` for binary input. The selected extension is required; there is no automatic format fallback. Only independent files without geometry-step indices are supported, not files accumulated with `out_app_flag`. +For `basis_type=pw` and `esolver_type=ksdft`, +[`out_wfc_pw`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-pw) +controls the output of plane-wave Kohn-Sham coefficients: + +- `0`: Do not write wave-function coefficients. +- `1`: Write text files with the `.txt` suffix. +- `2`: Write binary files with the `.dat` suffix. + +The files are stored in `OUT.${suffix}/`. Their pattern is +`wfk{k}[s{spin}][g{geometry step}][e{electronic iteration}]_pw.txt` for `out_wfc_pw=1` and +`wfk{k}[s{spin}][g{geometry step}][e{electronic iteration}]_pw.dat` for `out_wfc_pw=2`. The `s*` +label is omitted for `nspin=1`, is `s1` or `s2` for `nspin=2`, and is `s4` for `nspin=4`. All PW +files include the `k*` label, including Gamma-only calculations. + +With `out_freq_ion=0`, files are written only when the electronic calculation converges or reaches +`scf_nmax`, and the names contain neither `g*` nor `e*`. During structural relaxation or molecular +dynamics, each later ionic step overwrites the same files. With `out_freq_ion>0`, output is +restricted to the ionic steps selected by `out_freq_ion` and occurs at multiples of `out_freq_elec`, +at convergence, or at `scf_nmax`; both `g*` and `e*` are included in the file names. A static +`calculation=scf` or `calculation=nscf` run also receives `g1e*` indices when `out_freq_ion>0`. + +The [`init_wfc file binary`](../scf/initialization.md#wavefunction) path reads only unindexed binary +`wf*_pw.dat` files from `read_file_dir`. Generate directly reusable files with `out_wfc_pw=2` and +normally `out_freq_ion=0`. Text `wf*_pw.txt` files and files containing `g*` or `e*` indices are not +matched automatically. + +For `basis_type=lcao`, +[`out_wfc_lcao`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-lcao) +controls the output of numerical-atomic-orbital coefficients: `1` writes text files with the `.txt` +suffix and `2` writes binary files with the `.dat` suffix. Multi-k calculations generate +`wfs{spin}k{k-point}_nao.txt` or `.dat`, while Gamma-only calculations generate `wfs{spin}_nao.txt` +or `.dat`. + +To reuse LCAO coefficients, point `read_file_dir` to the coefficient files and set +`init_wfc file txt` for text input or `init_wfc file binary` for binary input. The selected +extension is required; there is no automatic format fallback. Only independent files without +geometry-step indices are supported, not files accumulated with `out_app_flag`. ## Wave Function in Real Space -One can also choose to output real-space wave functions with the keyword [`out_wfc_norm`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-norm) or [`out_wfc_re_im`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-re-im). - -Notice: When the [`basis_type`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#basis-type) is `lcao`, only `get_wf` [`calculation`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#calculation) is effective. An example is [examples/11_wfc/lcao_ienvelope_Si2](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/11_wfc/lcao_ienvelope_Si2). +One can also choose to output real-space wave functions with the keyword +[`out_wfc_norm`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-norm) +or +[`out_wfc_re_im`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#out-wfc-re-im). + +Notice: When the +[`basis_type`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#basis-type) +is `lcao`, only `get_wf` +[`calculation`](https://abacus-rtd.readthedocs.io/en/latest/advanced/input_files/input-main.html#calculation) +is effective. An example is +[examples/11_wfc/lcao_ienvelope_Si2](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/11_wfc/lcao_ienvelope_Si2). diff --git a/docs/advanced/input_files/kpt.md b/docs/advanced/input_files/kpt.md index 1aac138fd00..e3551812417 100644 --- a/docs/advanced/input_files/kpt.md +++ b/docs/advanced/input_files/kpt.md @@ -4,20 +4,27 @@ - [Set k-points explicitly](#set-k-points-explicitly) - [Band structure calculations](#band-structure-calculations) -ABACUS uses periodic boundary conditions for both crystals and finite systems. For isolated systems, such as atoms, molecules, clusters, etc., one uses the so-called supercell model. Lattice vectors of the supercell are set in the `STRU` file. For the input k-point (`KPT`) file, the file should either contain the k-point coordinates and weights or the mesh size for creating the k-point gird. Both options are allowed in `ABACUS`. +ABACUS uses periodic boundary conditions for both crystals and finite systems. For isolated systems, +such as atoms, molecules, clusters, etc., one uses the so-called supercell model. Lattice vectors of +the supercell are set in the `STRU` file. For the input k-point (`KPT`) file, the file should either +contain the k-point coordinates and weights or the mesh size for creating the k-point gird. Both +options are allowed in `ABACUS`. ## Gamma-only Calculations -In ABACUS, we offer the option of running gamma-only calculations for LCAO basis by setting [gamma_only](./input-main.md#gamma_only) to be 1. Due to details of implementation, gamma-only calculation will be slightly faster than running a non gamma-only calculation and explicitly setting gamma point to be the only the k-point, but the results should be consistent. +In ABACUS, we offer the option of running gamma-only calculations for LCAO basis by setting +[gamma_only](./input-main.md#gamma_only) to be 1. Due to details of implementation, gamma-only +calculation will be slightly faster than running a non gamma-only calculation and explicitly setting +gamma point to be the only the k-point, but the results should be consistent. -> If gamma_only is set to 1, the KPT file will be overwritten. So make sure to turn off gamma_only for multi-k calculations. +> If gamma_only is set to 1, the KPT file will be overwritten. So make sure to turn off gamma_only +> for multi-k calculations. ## Generate k-mesh automatically -To generate k-mesh automatically, it requires the input subdivisions of the Brillouin zone -in each direction and the origin for the k-mesh. ABACUS uses the Monkhorst-Pack -method to generate k-mesh, and the following is an example input k-point (`KPT`) file used in -`ABACUS`. +To generate k-mesh automatically, it requires the input subdivisions of the Brillouin zone in each +direction and the origin for the k-mesh. ABACUS uses the Monkhorst-Pack method to generate k-mesh, +and the following is an example input k-point (`KPT`) file used in `ABACUS`. ``` K_POINTS //keyword for start @@ -27,22 +34,23 @@ Gamma //which kind of Monkhorst-Pack method, `Gamma' or `MP' //last three number: shift of the mesh ``` -In the above example, the first line is a keyword, and it can be set as `K_POINTS`, or `KPOINTS` or just `K`. -The second line is an integer, and its value determines how to get k-points. In this example, `0` means using Monkhorst-Pack (MP) method to generate k-points automatically. +In the above example, the first line is a keyword, and it can be set as `K_POINTS`, or `KPOINTS` or +just `K`. The second line is an integer, and its value determines how to get k-points. In this +example, `0` means using Monkhorst-Pack (MP) method to generate k-points automatically. -The third line tells the input type of k-points, `Gamma` or `MP`, different Monkhorst Pack -(MP) method. Monkhorst-Pack (MP) is a method which uses the uniform k-points sampling in -Brillouin-zone, while `Gamma` means the Γ-centered Monkhorst-Pack method. -The first three numbers of the last line are integers, which give the MP k grid dimensions, and -the rest three are real numbers, which give the offset of the k grid. In this example, the numbers -`0 0 0` means that there is no offset, and this is the a standard 2by2by2 k grid. +The third line tells the input type of k-points, `Gamma` or `MP`, different Monkhorst Pack (MP) +method. Monkhorst-Pack (MP) is a method which uses the uniform k-points sampling in Brillouin-zone, +while `Gamma` means the ฮ“-centered Monkhorst-Pack method. The first three numbers of the last line +are integers, which give the MP k grid dimensions, and the rest three are real numbers, which give +the offset of the k grid. In this example, the numbers `0 0 0` means that there is no offset, and +this is the a standard 2by2by2 k grid. [back to top](#the-kpt-file) ## Set k-points explicitly -If the user wants to set up the k-points explicitly, the input k-point file should contain -the k-point coordinates and weights. An example is given as follows: +If the user wants to set up the k-points explicitly, the input k-point file should contain the +k-point coordinates and weights. An example is given as follows: ``` K_POINTS //keyword for start @@ -60,17 +68,26 @@ Direct //`Direct' or `Cartesian' coordinate ### K-point Weights and Symmetry -When explicitly setting k-points, you can specify custom weights for each k-point. These weights determine the contribution of each k-point to the total energy and density calculations. +When explicitly setting k-points, you can specify custom weights for each k-point. These weights +determine the contribution of each k-point to the total energy and density calculations. **Important notes about k-point weights:** -1. **Custom weights are preserved**: When using explicit k-point lists (non-Monkhorst-Pack), ABACUS preserves the custom weights you specify, even when symmetry operations are applied to reduce the k-points to the irreducible Brillouin zone (IBZ). +1. **Custom weights are preserved**: When using explicit k-point lists (non-Monkhorst-Pack), ABACUS + preserves the custom weights you specify, even when symmetry operations are applied to reduce the + k-points to the irreducible Brillouin zone (IBZ). -2. **Symmetry reduction**: When [`symmetry`](./input-main.md#symmetry) is set to 1, ABACUS will analyze the crystal symmetry and reduce the k-point set to the irreducible Brillouin zone. During this reduction: - - For **Monkhorst-Pack grids** (automatically generated): All k-points have uniform weights (1/N where N is the total number of k-points) - - For **explicit k-point lists**: Custom weights are preserved and properly combined when symmetry-equivalent k-points are merged +1. **Symmetry reduction**: When [`symmetry`](./input-main.md#symmetry) is set to 1, ABACUS will + analyze the crystal symmetry and reduce the k-point set to the irreducible Brillouin zone. During + this reduction: -3. **Weight normalization**: After symmetry reduction, k-point weights are normalized so that their sum equals `degspin` (2 for non-spin-polarized calculations, 1 for spin-polarized calculations). + - For **Monkhorst-Pack grids** (automatically generated): All k-points have uniform weights (1/N + where N is the total number of k-points) + - For **explicit k-point lists**: Custom weights are preserved and properly combined when + symmetry-equivalent k-points are merged + +1. **Weight normalization**: After symmetry reduction, k-point weights are normalized so that their + sum equals `degspin` (2 for non-spin-polarized calculations, 1 for spin-polarized calculations). **Example with custom weights:** @@ -86,20 +103,23 @@ Direct ``` In this example, different k-points have different weights, which might be useful for: + - Special sampling schemes - Convergence testing with specific k-point importance - Custom integration methods -> **Note**: When using custom weights with symmetry, ensure that your weight distribution is consistent with the crystal symmetry. ABACUS will preserve your weights during IBZ reduction, but inconsistent weights may lead to unexpected results. +> **Note**: When using custom weights with symmetry, ensure that your weight distribution is +> consistent with the crystal symmetry. ABACUS will preserve your weights during IBZ reduction, but +> inconsistent weights may lead to unexpected results. [back to top](#the-kpt-file) ## Band structure calculations ABACUS uses specified high-symmetry directions of the Brillouin zone for band structure -calculations. The third line of k-point file should start with 'Line' or 'Line_Cartesian' for -line mode. 'Line' means the positions below are in Direct coordinates, while 'Line_Cartesian' -means in Cartesian coordinates: +calculations. The third line of k-point file should start with 'Line' or 'Line_Cartesian' for line +mode. 'Line' means the positions below are in Direct coordinates, while 'Line_Cartesian' means in +Cartesian coordinates: ``` K_POINTS // keyword for start @@ -113,7 +133,7 @@ Line // line-mode 0.0 0.0 0.0 1 // G ``` -The fourth line and the following are special k-point coordinates and number of k-points -between this special k-point and the next. +The fourth line and the following are special k-point coordinates and number of k-points between +this special k-point and the next. [back to top](#the-kpt-file) diff --git a/docs/advanced/input_files/stru.md b/docs/advanced/input_files/stru.md index 885a1e833fc..6d459222335 100644 --- a/docs/advanced/input_files/stru.md +++ b/docs/advanced/input_files/stru.md @@ -14,12 +14,15 @@ ## Examples -The `STRU` file contains the information about the lattice geometry, the name(s) and/or location(s) of the pseudopotential and numerical orbital files, as well as the structural information about the system. -We supply two ways of specifying the lattice geometry. Below are two examples of the `STRU` file for the same system: +The `STRU` file contains the information about the lattice geometry, the name(s) and/or location(s) +of the pseudopotential and numerical orbital files, as well as the structural information about the +system. We supply two ways of specifying the lattice geometry. Below are two examples of the `STRU` +file for the same system: ### No latname -For this example, no need to supply any input to the variable `latname` in the INPUT file. (See [input parameters](input-main.md#latname).) +For this example, no need to supply any input to the variable `latname` in the INPUT file. (See +[input parameters](input-main.md#latname).) ``` ATOMIC_SPECIES @@ -47,8 +50,10 @@ Si // Element type ### latname fcc -We see that this example is a silicon fcc lattice. Apart from setting the lattice vectors manually, we also provide another solution where only the Bravais lattice type is required, and the lattice vectors will be generated automatically. For this example, we need to set `latname="fcc"` in the INPUT file. (See [input parameters](input-main.md#latname).) -And the `STRU` file becomes: +We see that this example is a silicon fcc lattice. Apart from setting the lattice vectors manually, +we also provide another solution where only the Bravais lattice type is required, and the lattice +vectors will be generated automatically. For this example, we need to set `latname="fcc"` in the +INPUT file. (See [input parameters](input-main.md#latname).) And the `STRU` file becomes: ``` ATOMIC_SPECIES @@ -79,277 +84,392 @@ information that comes below. ### ATOMIC_SPECIES - This section provides information about the type of chemical elements contained the unit cell. Each line defines one type of element. The user should specify the name, the mass, and the pseudopotential file used for each element. The mass of the elment is only used in molecular dynamics simulations. For electronic-structure calculations, the actual mass value isnโ€™t important. - In the above example, we see information is provided for the element `Si`: +This section provides information about the type of chemical elements contained the unit cell. Each +line defines one type of element. The user should specify the name, the mass, and the +pseudopotential file used for each element. The mass of the elment is only used in molecular +dynamics simulations. For electronic-structure calculations, the actual mass value isnโ€™t important. +In the above example, we see information is provided for the element `Si`: - ``` - Si 28.00 Si_ONCV_PBE-1.0.upf upf201 // label; mass; pseudo_file; pseudo_type - ``` - Here `Si_ONCV_PBE-1.0.upf` is the pseudopotential file. When the path is not specified, the file is assumed to be located in work directory. Otherwise, please explicitly specify the location of the pseudopotential files. +``` +Si 28.00 Si_ONCV_PBE-1.0.upf upf201 // label; mass; pseudo_file; pseudo_type +``` + +Here `Si_ONCV_PBE-1.0.upf` is the pseudopotential file. When the path is not specified, the file is +assumed to be located in work directory. Otherwise, please explicitly specify the location of the +pseudopotential files. - After the pseudopotential file, `upf201` is the type of pseudopotential. There are five options: `upf`(.UPF format), `upf201`(the new .UPF format), `vwr`(.vwr format), `blps`(bulk-derived local pseudopotential), and `auto`(automatically identified). If no pseudopotential type is assigned, the default value is `auto`, and the pseudopotential type will be automatically identified. +After the pseudopotential file, `upf201` is the type of pseudopotential. There are five options: +`upf`(.UPF format), `upf201`(the new .UPF format), `vwr`(.vwr format), `blps`(bulk-derived local +pseudopotential), and `auto`(automatically identified). If no pseudopotential type is assigned, the +default value is `auto`, and the pseudopotential type will be automatically identified. - When [esolver_type](./input-main.md#esolver_type) is set to `lj` or `dp`, the keyword `pseudo_file` and `pseudo_type` is needless. +When [esolver_type](./input-main.md#esolver_type) is set to `lj` or `dp`, the keyword `pseudo_file` +and `pseudo_type` is needless. - Different types of pseudopotentials can be used for different elements, but note that the XC functionals assigned by all pseudopotentials should be the same one. If not, the choice of XC functional must be set explicitly using the [dft_functional](./input-main.md#dft_functional) keyword. +Different types of pseudopotentials can be used for different elements, but note that the XC +functionals assigned by all pseudopotentials should be the same one. If not, the choice of XC +functional must be set explicitly using the [dft_functional](./input-main.md#dft_functional) +keyword. - Common sources of the pseudopotential files include: +Common sources of the pseudopotential files include: - 1. [Quantum ESPRESSO](http://www.quantum-espresso.org/pseudopotentials/). - 2. [SG15-ONCV](http://quantum-simulation.org/potentials/sg15_oncv/upf/). - 3. [DOJO](http://www.pseudo-dojo.org/). - 4. [BLPS](https://github.com/PrincetonUniversity/BLPSLibrary). - 5. For additional pseudopotential options and to view the basic benchmark test results of these pseudopotentials in ABACUS, please refer to the [Benchmarks website](https://kirk0830.github.io/ABACUS-Pseudopot-Nao-Square/pseudopotential/pseudopotential.html) +1. [Quantum ESPRESSO](http://www.quantum-espresso.org/pseudopotentials/). +1. [SG15-ONCV](http://quantum-simulation.org/potentials/sg15_oncv/upf/). +1. [DOJO](http://www.pseudo-dojo.org/). +1. [BLPS](https://github.com/PrincetonUniversity/BLPSLibrary). +1. For additional pseudopotential options and to view the basic benchmark test results of these + pseudopotentials in ABACUS, please refer to the + [Benchmarks website](https://kirk0830.github.io/ABACUS-Pseudopot-Nao-Square/pseudopotential/pseudopotential.html) ### NUMERICAL_ORBITAL - Numerical atomic orbitals are only needed for `LCAO` calculations. Thus this section will be neglected in calcultions with plane wave basis. In the above example, numerical atomic orbitals is specified for the element `Si`: +Numerical atomic orbitals are only needed for `LCAO` calculations. Thus this section will be +neglected in calcultions with plane wave basis. In the above example, numerical atomic orbitals is +specified for the element `Si`: - ``` - Si_gga_8au_60Ry_2s2p1d.orb //numerical_orbital_file - ``` - โ€˜Si_gga_8au_60Ry_2s2p1d.orbโ€™ is name of the numerical orbital file. Again here the path is not specified, which means that this file is located in the work directory. +``` +Si_gga_8au_60Ry_2s2p1d.orb //numerical_orbital_file +``` + +โ€˜Si_gga_8au_60Ry_2s2p1d.orbโ€™ is name of the numerical orbital file. Again here the path is not +specified, which means that this file is located in the work directory. - Numerical atomic orbitals may be downloaded from the [official website](http://abacus.ustc.edu.cn/pseudo/list.htm). - Recommendation for Pseudopotential and Orbital Sets -For general usage requirements, the APNSv1.0 pseudopotential and orbital set is recommended. You can access it via [AIS square website](https://www.aissquare.com/datasets/detail?pageType=datasets&name=ABACUS-APNS-PPORBs-v1%253Apre-release&id=326) +Numerical atomic orbitals may be downloaded from the +[official website](http://abacus.ustc.edu.cn/pseudo/list.htm). Recommendation for Pseudopotential +and Orbital Sets For general usage requirements, the APNSv1.0 pseudopotential and orbital set is +recommended. You can access it via +[AIS square website](https://www.aissquare.com/datasets/detail?pageType=datasets&name=ABACUS-APNS-PPORBs-v1%253Apre-release&id=326) ### LATTICE_CONSTANT - The lattice constant of the system in unit of Bohr. In output structure files (e.g., `STRU`, `STRU1`, `STRU2`), a trailing comment `# in Bohr` is appended to the value line. +The lattice constant of the system in unit of Bohr. In output structure files (e.g., `STRU`, +`STRU1`, `STRU2`), a trailing comment `# in Bohr` is appended to the value line. + ### LATTICE_VECTORS - The lattice vectors of the unit cell. It is a 3by3 matrix written in 3 lines. Please note that *the lattice vectors given here are scaled by the lattice constant*. This section must be removed if the type Bravais lattice is specified using the input parameter `latname`. (See [input parameters](input-main.md#latname).) In output structure files, a trailing comment `# in units of lat0` is appended to the section header. +The lattice vectors of the unit cell. It is a 3by3 matrix written in 3 lines. Please note that *the +lattice vectors given here are scaled by the lattice constant*. This section must be removed if the +type Bravais lattice is specified using the input parameter `latname`. (See +[input parameters](input-main.md#latname).) In output structure files, a trailing comment +`# in units of lat0` is appended to the section header. + ### LATTICE_PARAMETERS - This section is only relevant when `latname` (see [input parameters](input-main.md#latname)) is used to specify the Bravais lattice type. The example above is a fcc lattice, where no additional information except the lattice constant is required to determine the geometry of the lattice. +This section is only relevant when `latname` (see [input parameters](input-main.md#latname)) is used +to specify the Bravais lattice type. The example above is a fcc lattice, where no additional +information except the lattice constant is required to determine the geometry of the lattice. - However, for other types of Bravais lattice, other parameters might be necessary. In that case, the section `LATTICE_PARAMETERS` must be present. It contains **one single line** with some parameters (separated by blank space if multiple parameters are needed), where the number of parameters required depends on specific type of lattice. +However, for other types of Bravais lattice, other parameters might be necessary. In that case, the +section `LATTICE_PARAMETERS` must be present. It contains **one single line** with some parameters +(separated by blank space if multiple parameters are needed), where the number of parameters +required depends on specific type of lattice. - The three lattice vectors v1, v2, v3 (in units of lattice constant) are generated in the following way: +The three lattice vectors v1, v2, v3 (in units of lattice constant) are generated in the following +way: - - latname = "sc": the LATTICE_PARAMETERS section is not required: +- latname = "sc": the LATTICE_PARAMETERS section is not required: - ``` - v1 = (1, 0, 0) - v2 = (0, 1, 0) - v3 = (0, 0, 1) - ``` - - latname = "fcc": the LATTICE_PARAMETERS section is not required: + ``` + v1 = (1, 0, 0) + v2 = (0, 1, 0) + v3 = (0, 0, 1) + ``` - ``` - v1 = (-0.5, 0, 0.5) - v2 = (0, 0.5, 0.5) - v3 = (-0.5, 0.5, 0) - ``` - - latname = "bcc" : the LATTICE_PARAMETERS section is not required: +- latname = "fcc": the LATTICE_PARAMETERS section is not required: - ``` - v1 = (0.5, 0.5, 0.5) - v2 = (-0.5, 0.5, 0.5) - v3 = (-0.5, -0.5, 0.5) - ``` - - latname = "hexagonal" : One single parameter is required in the LATTICE_PARAMETERS section, being the ratio between axis length c/a. Denote it by x then: + ``` + v1 = (-0.5, 0, 0.5) + v2 = (0, 0.5, 0.5) + v3 = (-0.5, 0.5, 0) + ``` - ``` - v1 = (1.0, 0, 0) - v2 = (-0.5, sqrt(3)/2, 0) - v3 = (0, 0, x) - ``` - - latname = "trigonal" : One single parameter is required in the LATTICE_PARAMETERS section, which specifies cosγ with γ being the angle between any pair of crystallographic vectors. Denote it by x then: +- latname = "bcc" : the LATTICE_PARAMETERS section is not required: - ``` - v1 = (tx, -ty, tz) - v2 = (0, 2ty, tz) - v3 = (-tx, -ty, tz) - ``` - where tx=sqrt((1-x)/2), ty=sqrt((1-x)/6), and tz=sqrt((1+2x)/3). - - latname = "st" (simple tetragonal) : One single parameter is required in the LATTICE_PARAMETERS section, which gives ratio between axis length c/a. Denote it by x then: + ``` + v1 = (0.5, 0.5, 0.5) + v2 = (-0.5, 0.5, 0.5) + v3 = (-0.5, -0.5, 0.5) + ``` - ``` - v1 = (1, 0, 0) - v2 = (0, 1, 0) - v3 = (0, 0, x) - ``` - - latname = "bct" (body-centered tetragonal) : One single parameter is required in the LATTICE_PARAMETERS section, which gives ratio between axis length c/a. Denote it by x then: +- latname = "hexagonal" : One single parameter is required in the LATTICE_PARAMETERS section, being + the ratio between axis length c/a. Denote it by x then: - ``` - v1 = (0.5, -0.5, x) - v2 = (0.5, 0.5, x) - v3 = (-0.5, -0.5, x) - ``` - - latname = "so" (simple orthorhombic) : Two parameters are required in the LATTICE_PARAMETERS section, which gives ratios between axis length b/a and c/a. Denote them by x, y then: + ``` + v1 = (1.0, 0, 0) + v2 = (-0.5, sqrt(3)/2, 0) + v3 = (0, 0, x) + ``` - ``` - v1 = (1, 0, 0) - v2 = (0, x, 0) - v3 = (0, 0, y) - ``` - - latname = "baco" (base-centered orthorhombic) : Two parameters are required in the LATTICE_PARAMETERS section, which gives ratios between axis length b/a and c/a. Denote them by x, y then: +- latname = "trigonal" : One single parameter is required in the LATTICE_PARAMETERS section, which + specifies cosฮณ with ฮณ being the angle between any pair of crystallographic vectors. Denote it by x + then: - ``` - v1 = (0.5, x/2, 0) - v2 = (-0.5, x/2, 0) - v3 = (0, 0, y) - ``` - - latname = "fco" (face-centered orthorhombic) : Two parameters are required in the LATTICE_PARAMETERS section, which gives ratios between axis length b/a and c/a. Denote them by x, y then: + ``` + v1 = (tx, -ty, tz) + v2 = (0, 2ty, tz) + v3 = (-tx, -ty, tz) + ``` - ``` - v1 = (0.5, 0, y/2) - v2 = (0.5, x/2, 0) - v3 = (0, x/2, y/2) - ``` - - latname = "bco" (body-centered orthorhombic) : Two parameters are required in the LATTICE_PARAMETERS section, which gives ratios between lattice vector length b/a and c/a. Denote them by x, y then: + where tx=sqrt((1-x)/2), ty=sqrt((1-x)/6), and tz=sqrt((1+2x)/3). - ``` - v1 = (0.5, x/2, y/2) - v2 = (-0.5, x/2, y/2) - v3 = (-0.5, -x/2, y/2) - ``` - - latname = "sm" (simple monoclinic) : Three parameters are required in the LATTICE_PARAMETERS section, which are the ratios of lattice vector length b/a, c/a as well as the cosine of angle between axis a and b. Denote them by x, y, z then: +- latname = "st" (simple tetragonal) : One single parameter is required in the LATTICE_PARAMETERS + section, which gives ratio between axis length c/a. Denote it by x then: + + ``` + v1 = (1, 0, 0) + v2 = (0, 1, 0) + v3 = (0, 0, x) + ``` + +- latname = "bct" (body-centered tetragonal) : One single parameter is required in the + LATTICE_PARAMETERS section, which gives ratio between axis length c/a. Denote it by x then: + + ``` + v1 = (0.5, -0.5, x) + v2 = (0.5, 0.5, x) + v3 = (-0.5, -0.5, x) + ``` + +- latname = "so" (simple orthorhombic) : Two parameters are required in the LATTICE_PARAMETERS + section, which gives ratios between axis length b/a and c/a. Denote them by x, y then: + + ``` + v1 = (1, 0, 0) + v2 = (0, x, 0) + v3 = (0, 0, y) + ``` + +- latname = "baco" (base-centered orthorhombic) : Two parameters are required in the + LATTICE_PARAMETERS section, which gives ratios between axis length b/a and c/a. Denote them by x, + y then: + + ``` + v1 = (0.5, x/2, 0) + v2 = (-0.5, x/2, 0) + v3 = (0, 0, y) + ``` + +- latname = "fco" (face-centered orthorhombic) : Two parameters are required in the + LATTICE_PARAMETERS section, which gives ratios between axis length b/a and c/a. Denote them by x, + y then: + + ``` + v1 = (0.5, 0, y/2) + v2 = (0.5, x/2, 0) + v3 = (0, x/2, y/2) + ``` + +- latname = "bco" (body-centered orthorhombic) : Two parameters are required in the + LATTICE_PARAMETERS section, which gives ratios between lattice vector length b/a and c/a. Denote + them by x, y then: + + ``` + v1 = (0.5, x/2, y/2) + v2 = (-0.5, x/2, y/2) + v3 = (-0.5, -x/2, y/2) + ``` + +- latname = "sm" (simple monoclinic) : Three parameters are required in the LATTICE_PARAMETERS + section, which are the ratios of lattice vector length b/a, c/a as well as the cosine of angle + between axis a and b. Denote them by x, y, z then: + + ``` + v1 = (1, 0, 0) + v2 = (x*z, x*sqrt(1-z^2, 0) + v3 = (0, 0, y) + ``` + +- latname = "bacm" (base-centered monoclinic) : Three parameters are required in the + LATTICE_PARAMETERS section, which are the ratios of lattice vector length b/a, c/a as well as the + cosine of angle between axis a and b. Denote them by x, y, z then: + + ``` + v1 = (0.5, 0, -y/2) + v2 = (x*z, x*sqrt(1-z^2), 0) + v3 = (0.5, 0, y/2) + ``` + +- latname = "triclinic" : Five parameters are required in the LATTICE_PARAMETERS section, namely the + ratios b/a, c/a; the cosines of angle ab, ac, bc. Denote them by x,y,m,n,l, then: + + ``` + v1 = (1, 0, 0) + v2 = (x*m, x*sqrt(1-m^2), 0) + v3 = (y*n, y*(l-n*m/sqrt(1-m^2)), y*fac) + ``` + + where $fac=\\frac{\\sqrt{1+2*m*n\*l-m^2 -n^2 -l^2 }}{\\sqrt{1-m^2}}$ + +### ATOMIC_POSITIONS + +This section specifies the positions and other information of individual atoms. + +The first line signifies method that atom positions are given, the following options are supported: + +- `Direct` : coordinates of atom positions below would in fraction coordinates. +- `Cartesian` : Cartesian coordinates in unit of 'LATTICE_CONSTANT'. +- `Cartesian_au` : Cartesian coordinates in unit of Bohr, same as setting of `Cartesian` with + `LATTICE_CONSTANT` = 1.0 . +- `Cartesian_angstrom` : Cartesian coordinates in unit of Angstrom, same as setting of `Cartesian` + with `LATTICE_CONSTANT` = 1.889726125457828 . +- `Cartesian_angstrom_center_xy` : Cartesian coordinates in unit of Angstrom, with Direct coordinate + (0.5, 0.5, 0.0) as reference. +- `Cartesian_angstrom_center_xz` : Cartesian coordinates in unit of Angstrom, with Direct coordinate + (0.5, 0.0, 0.5) as reference.. +- `Cartesian_angstrom_center_yz` : Cartesian coordinates in unit of Angstrom, with Direct coordinate + (0.0, 0.5, 0.5) as reference.. +- `Cartesian_angstrom_center_xyz` : Cartesian coordinates in unit of Angstrom, with Direct + coordinate (0.5, 0.5, 0.5) as reference.. + +The following three lines tells the elemental type (`Fe`), the initial magnetic moment (`1.0`), and +the number of atoms for this particular element (`2`) repsectively. Notice this magnetic moment will +be a default value for every atom of this type but will be overrided if one define it for each atom +by keyword(see below). + +The last two lines in this example are the coordinates of atomic positions. There are three numbers +in each line, which specifies the atomic positions, following by other parameters marked by +keywords. + +### More Key Words + +Several other parameters could be defined after the atom position using key words : + +- `m` or NO key word: three numbers, which take value in 0 or 1, control how the atom move in + geometry relaxation calculations. In example below, the numbers `0 0 0` following the coordinates + of the first atom means this atom are *not allowed* to move in all three directions, and the + numbers `1 1 1` following the coordinates of the second atom means this atom *can* move in all + three directions. + +- `v` or `vel` or `velocity`: set the three components of initial velocity of atoms, used only for + restarting MD calculations (e.g., `v 1.0 1.0 1.0`). + +- `mag` or `magmom` : set the start magnetization for each atom. In colinear case only one number + should be given. In non-colinear case one have two choice:either set one number for the norm of + magnetization here and specify two polar angle later(e. g. see below), or set three number for the + xyz commponent of magnetization here (e. g. `mag 0.0 0.0 1.0`). Note that if this parameter is + set, the initial magnetic moment setting in the second line will be overrided. + + - `angle1`: in non-colinear case, specify the angle between z-axis and real spin, in angle measure + instead of radian measure + + - `angle2`: in non-colinear case, specify angle between x-axis and real spin in projection in + xy-plane , in angle measure instead of radian measure + + e.g.: ``` - v1 = (1, 0, 0) - v2 = (x*z, x*sqrt(1-z^2, 0) - v3 = (0, 0, y) + Fe + 1.0 + 2 + 0.0 0.0 0.0 m 0 0 0 mag 1.0 angle1 90 angle2 0 + 0.5 0.5 0.5 m 1 1 1 mag 1.0 angle1 90 angle2 180 ``` - - latname = "bacm" (base-centered monoclinic) : Three parameters are required in the LATTICE_PARAMETERS section, which are the ratios of lattice vector length b/a, c/a as well as the cosine of angle between axis a and b. Denote them by x, y, z then: + + - Default: If users do not specalize a finite magnetic moment for all atoms in a magnetic + calculations (`nspin==2 || nspin == 4`), e.g.: ``` - v1 = (0.5, 0, -y/2) - v2 = (x*z, x*sqrt(1-z^2), 0) - v3 = (0.5, 0, y/2) + Fe + 0.0 + 2 + 0.0 0.0 0.0 m 0 0 0 + 0.5 0.5 0.5 m 1 1 1 + + O + 0.0 + 2 + 0.0 0.0 0.0 m 0 0 0 + 0.5 0.5 0.5 m 1 1 1 ``` - - latname = "triclinic" : Five parameters are required in the LATTICE_PARAMETERS section, namely the ratios b/a, c/a; the cosines of angle ab, ac, bc. Denote them by x,y,m,n,l, then: + + For `nspin==2`, the atomic magnetic moment is autoset to `1.0`: ``` - v1 = (1, 0, 0) - v2 = (x*m, x*sqrt(1-m^2), 0) - v3 = (y*n, y*(l-n*m/sqrt(1-m^2)), y*fac) + Fe + 1.0 + 2 + 0.0 0.0 0.0 m 0 0 0 + 0.5 0.5 0.5 m 1 1 1 + + Fe + 1.0 + 2 + 0.0 0.0 0.0 m 0 0 0 + 0.5 0.5 0.5 m 1 1 1 ``` - where $fac=\frac{\sqrt{1+2*m*n*l-m^2 -n^2 -l^2 }}{\sqrt{1-m^2}}$ -### ATOMIC_POSITIONS - This section specifies the positions and other information of individual atoms. + This autoset is skipped as soon as `STRU` specifies a finite moment for any single atom, and + also when [`symmetry`](input-main.md#symmetry) is `1`, because an all-zero moment is a + legitimate nonmagnetic choice under the full point group. - The first line signifies method that atom positions are given, the following options are supported: + For `nspin==4`, **no** moment is autoset: the calculation starts from a zero magnetic moment and + a warning is printed. Zero magnetization is a stationary point, so such a run stays nonmagnetic. + Set `mag` explicitly on the magnetic atoms if a magnetic ground state is expected, e.g.: - - `Direct` : coordinates of atom positions below would in fraction coordinates. - - `Cartesian` : Cartesian coordinates in unit of 'LATTICE_CONSTANT'. - - `Cartesian_au` : Cartesian coordinates in unit of Bohr, same as setting of `Cartesian` with `LATTICE_CONSTANT` = 1.0 . - - `Cartesian_angstrom` : Cartesian coordinates in unit of Angstrom, same as setting of `Cartesian` with `LATTICE_CONSTANT` = 1.889726125457828 . - - `Cartesian_angstrom_center_xy` : Cartesian coordinates in unit of Angstrom, with Direct coordinate (0.5, 0.5, 0.0) as reference. - - `Cartesian_angstrom_center_xz` : Cartesian coordinates in unit of Angstrom, with Direct coordinate (0.5, 0.0, 0.5) as reference.. - - `Cartesian_angstrom_center_yz` : Cartesian coordinates in unit of Angstrom, with Direct coordinate (0.0, 0.5, 0.5) as reference.. - - `Cartesian_angstrom_center_xyz` : Cartesian coordinates in unit of Angstrom, with Direct coordinate (0.5, 0.5, 0.5) as reference.. + ``` + Fe + 0.0 + 2 + 0.0 0.0 0.0 m 0 0 0 mag 0.0 0.0 2.0 + 0.5 0.5 0.5 m 1 1 1 mag 0.0 0.0 2.0 + + O + 0.0 + 2 + 0.0 0.0 0.0 m 0 0 0 + 0.5 0.5 0.5 m 1 1 1 + ``` - The following three lines tells the elemental type (`Fe`), the initial magnetic moment (`1.0`), and the number of atoms for this particular element (`2`) repsectively. Notice this magnetic moment will be a default value for every atom of this type but will be overrided if one define it for each atom by keyword(see below). + With [`noncolin`](input-main.md#noncolin) `0`, only the z component of `mag` is used; the x/y + components are discarded and the number of affected atoms is reported per atom type. A moment + given purely along x/y therefore also leaves a zero starting moment. - The last two lines in this example are the coordinates of atomic positions. There are three numbers in each line, which specifies the atomic positions, following by other parameters marked by keywords. +- `lambda`: Lagrange multiplier vector for spin constraint method. Can specify one value + (z-component) or three values for x, y, z components (e.g., `lambda 0.5` or `lambda 0.1 0.2 0.3`). + Values are in eV and will be converted to Rydberg internally. Used with spin-constrained DFT + (enable with `sc_mag_switch` in INPUT file). -### More Key Words +- `sc`: set the spin constraint target magnetization for each atom. Can specify one value + (z-component) or three values for x, y, z components (e.g., `sc 1.0` or `sc 0.5 0.5 1.0`). Used + with spin-constrained DFT (enable with `sc_mag_switch` in INPUT file). - Several other parameters could be defined after the atom position using key words : - - - `m` or NO key word: three numbers, which take value in 0 or 1, control how the atom move in geometry relaxation calculations. In example below, the numbers `0 0 0` following the coordinates of the first atom means this atom are *not allowed* to move in all three directions, and the numbers `1 1 1` following the coordinates of the second atom means this atom *can* move in all three directions. - - `v` or `vel` or `velocity`: set the three components of initial velocity of atoms, used only for restarting MD calculations (e.g., `v 1.0 1.0 1.0`). - - `mag` or `magmom` : set the start magnetization for each atom. In colinear case only one number should be given. In non-colinear case one have two choice:either set one number for the norm of magnetization here and specify two polar angle later(e. g. see below), or set three number for the xyz commponent of magnetization here (e. g. `mag 0.0 0.0 1.0`). Note that if this parameter is set, the initial magnetic moment setting in the second line will be overrided. - - `angle1`: in non-colinear case, specify the angle between z-axis and real spin, in angle measure instead of radian measure - - `angle2`: in non-colinear case, specify angle between x-axis and real spin in projection in xy-plane , in angle measure instead of radian measure - - e.g.: - - ``` - Fe - 1.0 - 2 - 0.0 0.0 0.0 m 0 0 0 mag 1.0 angle1 90 angle2 0 - 0.5 0.5 0.5 m 1 1 1 mag 1.0 angle1 90 angle2 180 - ``` - - - Default: If users do not specalize a finite magnetic moment for all atoms in a magnetic calculations (`nspin==2 || nspin == 4`), e.g.: - ``` - Fe - 0.0 - 2 - 0.0 0.0 0.0 m 0 0 0 - 0.5 0.5 0.5 m 1 1 1 - - O - 0.0 - 2 - 0.0 0.0 0.0 m 0 0 0 - 0.5 0.5 0.5 m 1 1 1 - ``` - For `nspin==2`, the atomic magnetic moment is autoset to `1.0`: - ``` - Fe - 1.0 - 2 - 0.0 0.0 0.0 m 0 0 0 - 0.5 0.5 0.5 m 1 1 1 - - Fe - 1.0 - 2 - 0.0 0.0 0.0 m 0 0 0 - 0.5 0.5 0.5 m 1 1 1 - ``` - This autoset is skipped as soon as `STRU` specifies a finite moment for - any single atom, and also when [`symmetry`](input-main.md#symmetry) is - `1`, because an all-zero moment is a legitimate nonmagnetic choice under - the full point group. - - For `nspin==4`, **no** moment is autoset: the calculation starts from a - zero magnetic moment and a warning is printed. Zero magnetization is a - stationary point, so such a run stays nonmagnetic. Set `mag` explicitly - on the magnetic atoms if a magnetic ground state is expected, e.g.: - ``` - Fe - 0.0 - 2 - 0.0 0.0 0.0 m 0 0 0 mag 0.0 0.0 2.0 - 0.5 0.5 0.5 m 1 1 1 mag 0.0 0.0 2.0 - - O - 0.0 - 2 - 0.0 0.0 0.0 m 0 0 0 - 0.5 0.5 0.5 m 1 1 1 - ``` - With [`noncolin`](input-main.md#noncolin) `0`, only the z component of - `mag` is used; the x/y components are discarded and the number of - affected atoms is reported per atom type. A moment given purely along - x/y therefore also leaves a zero starting moment. - - - `lambda`: Lagrange multiplier vector for spin constraint method. Can specify one value (z-component) or three values for x, y, z components (e.g., `lambda 0.5` or `lambda 0.1 0.2 0.3`). Values are in eV and will be converted to Rydberg internally. Used with spin-constrained DFT (enable with `sc_mag_switch` in INPUT file). - - - `sc`: set the spin constraint target magnetization for each atom. Can specify one value (z-component) or three values for x, y, z components (e.g., `sc 1.0` or `sc 0.5 0.5 1.0`). Used with spin-constrained DFT (enable with `sc_mag_switch` in INPUT file). - - - `f` or `force` or `forces`: three numbers giving the per-atom force (fx, fy, fz) in **eV/Angstrom**. This field is *output-only*: it is written into structure files (STRU{istep}, STRU_NOW, STRU_FINAL) when [`out_stru`](input-main.md#out_stru) is enabled, [`cal_force`](input-main.md#cal_force) is true, and the geometry has been evaluated. When such a file is read back as an input STRU, the `f` values are consumed but ignored -- they are informational only and do not affect the calculation. +- `f` or `force` or `forces`: three numbers giving the per-atom force (fx, fy, fz) in + **eV/Angstrom**. This field is *output-only*: it is written into structure files (STRU{istep}, + STRU_NOW, STRU_FINAL) when [`out_stru`](input-main.md#out_stru) is enabled, + [`cal_force`](input-main.md#cal_force) is true, and the geometry has been evaluated. When such a + file is read back as an input STRU, the `f` values are consumed but ignored -- they are + informational only and do not affect the calculation. ### Important Notes for ATOMIC_POSITIONS 1. **Coordinate System Selection**: Choose the appropriate coordinate system based on your needs: + - Use `Direct` for fractional coordinates (most common for periodic systems) - Use `Cartesian_angstrom` when working with molecular structures or experimental data - - Use centered coordinate systems (`Cartesian_angstrom_center_xy/xz/yz/xyz`) for surface or slab calculations where you want to center the structure + - Use centered coordinate systems (`Cartesian_angstrom_center_xy/xz/yz/xyz`) for surface or slab + calculations where you want to center the structure + +1. **Magnetization Settings**: -2. **Magnetization Settings**: - For collinear calculations (`nspin=2`), only specify one magnetization value per atom - For non-collinear calculations (`nspin=4`), you can specify: - Three components directly: `mag 1.0 0.0 0.0` (mx, my, mz) - Magnitude with angles: `mag 1.0 angle1 90 angle2 0` (magnitude, polar angle, azimuthal angle) - - If no magnetization is specified for any atom, ABACUS will automatically set default values (1.0 for nspin=2, or (1,1,1) for nspin=4) + - If no magnetization is specified for any atom, ABACUS will automatically set default values + (1.0 for nspin=2, or (1,1,1) for nspin=4) + +1. **Movement Constraints**: -3. **Movement Constraints**: - Use `m 1 1 1` to allow the atom to move freely in all directions during relaxation - Use `m 0 0 0` to fix the atom completely - - Use `m 1 0 1` to allow movement only in x and z directions (useful for constraining surface atoms) + - Use `m 1 0 1` to allow movement only in x and z directions (useful for constraining surface + atoms) + +1. **Keyword Order**: The optional keywords (m, v, mag, angle1, angle2, lambda, sc) can appear in + any order after the atomic coordinates, but each keyword should only appear once per atom. -4. **Keyword Order**: The optional keywords (m, v, mag, angle1, angle2, lambda, sc) can appear in any order after the atomic coordinates, but each keyword should only appear once per atom. +1. **Common Mistakes to Avoid**: -5. **Common Mistakes to Avoid**: - Don't mix Direct and Cartesian coordinates in the same STRU file - Ensure the number of atoms specified matches the actual number of coordinate lines provided - When using vector magnetization (`mag x y z`), don't also specify angles for the same atom @@ -357,7 +477,9 @@ For general usage requirements, the APNSv1.0 pseudopotential and orbital set is ### Header of structure files written by ABACUS -When [`out_stru`](input-main.md#out_stru) writes STRU{istep}, STRU_NOW or STRU_FINAL, the file begins with a fixed **7-line** comment header so that downstream parsers can skip a constant-size block: +When [`out_stru`](input-main.md#out_stru) writes STRU{istep}, STRU_NOW or STRU_FINAL, the file +begins with a fixed **7-line** comment header so that downstream parsers can skip a constant-size +block: ``` # ABACUS version: @@ -371,13 +493,25 @@ When [`out_stru`](input-main.md#out_stru) writes STRU{istep}, STRU_NOW or STRU_F Rules: -- Line 3 carries the total energy in eV only when that energy was computed for the geometry written below. If the geometry was proposed by the optimizer but never evaluated (early relaxation exit), line 3 is written as `# RELAX STEP [ (FINAL)], Energy: N/A` so the energy label and the coordinates always describe the same frame. -- Lines 4-6 always carry the stress tensor in **kbar**, one row per line. If stress was not computed ([`cal_stress`](input-main.md#cal_stress) = 0) or the geometry was proposed by the optimizer but not yet evaluated (early relaxation exit), all three rows are written as `# Stress (kbar): N/A N/A N/A` with no extra inline comment, so every stress line has the same token shape. +- Line 3 carries the total energy in eV only when that energy was computed for the geometry written + below. If the geometry was proposed by the optimizer but never evaluated (early relaxation exit), + line 3 is written as `# RELAX STEP [ (FINAL)], Energy: N/A` so the energy label and the + coordinates always describe the same frame. +- Lines 4-6 always carry the stress tensor in **kbar**, one row per line. If stress was not computed + ([`cal_stress`](input-main.md#cal_stress) = 0) or the geometry was proposed by the optimizer but + not yet evaluated (early relaxation exit), all three rows are written as + `# Stress (kbar): N/A N/A N/A` with no extra inline comment, so every stress line has the same + token shape. - Line 7 is a single `# NOTE:` line describing the state: - `# NOTE: stress and forces computed for this geometry` (normal case) - `# NOTE: stress not computed (cal_stress=0)` - `# NOTE: forces not computed (cal_force=0); per-atom f fields omitted intentionally` - `# NOTE: stress not computed (cal_stress=0); forces not computed (cal_force=0); per-atom f fields omitted intentionally` - `# NOTE: geometry proposed by optimizer but not evaluated; energy N/A; stress N/A; forces omitted` -- Per-atom `f fx fy fz` fields (forces in eV/Angstrom) are appended to the atom lines only when [`cal_force`](input-main.md#cal_force) is true **and** the geometry was evaluated. They are omitted on early relaxation exit so the geometry and the property data always come from the same configuration. -- The coordinate format line of the ATOMIC_POSITIONS section is always `Cartesian_angstrom`, independent of force availability; `has_force` only controls the per-atom `f` fields. `Direct` and the other coordinate keywords remain fully supported as **input** formats. +- Per-atom `f fx fy fz` fields (forces in eV/Angstrom) are appended to the atom lines only when + [`cal_force`](input-main.md#cal_force) is true **and** the geometry was evaluated. They are + omitted on early relaxation exit so the geometry and the property data always come from the same + configuration. +- The coordinate format line of the ATOMIC_POSITIONS section is always `Cartesian_angstrom`, + independent of force availability; `has_force` only controls the per-atom `f` fields. `Direct` and + the other coordinate keywords remain fully supported as **input** formats. diff --git a/docs/advanced/install.md b/docs/advanced/install.md index 86d63cfd1ee..1e6eec86a1a 100644 --- a/docs/advanced/install.md +++ b/docs/advanced/install.md @@ -1,23 +1,29 @@ # Advanced Installation Options -This guide helps you install ABACUS with advanced features. Please make sure to read the [easy-installation guide](../quick_start/easy_install.md) before. +This guide helps you install ABACUS with advanced features. Please make sure to read the +[easy-installation guide](../quick_start/easy_install.md) before. ## Build with ELPA -The [ELPA](https://elpa.mpcdf.mpg.de/) library provides highly efficient and highly scalable direct eigensolvers for symmetric (hermitian) matrices. ABACUS uses ELPA in the following cases: +The [ELPA](https://elpa.mpcdf.mpg.de/) library provides highly efficient and highly scalable direct +eigensolvers for symmetric (hermitian) matrices. ABACUS uses ELPA in the following cases: -- LCAO calculations with `ks_solver` set to `elpa` or `genelpa`, which is generally faster than `scalapack_gvx`; +- LCAO calculations with `ks_solver` set to `elpa` or `genelpa`, which is generally faster than + `scalapack_gvx`; - PW calculations with `ks_solver` set to `dav_subspace` and `diag_subspace` set to `1`. To build ABACUS with ELPA support, pass `-DENABLE_ELPA=ON` to CMake. ## Build with Libxc -ABACUS use exchange-correlation functionals by default. However, for some functionals (such as HSE hybrid functional), Libxc is required. +ABACUS use exchange-correlation functionals by default. However, for some functionals (such as HSE +hybrid functional), Libxc is required. Dependency: [Libxc](https://tddft.org/programs/libxc/) >= 5.1.7 . -> Note: Building Libxc from source with Autotools is NOT supported when building ABACUS with CMake. Please compile Libxc with CMake instead and pass its installation prefix path to `CMAKE_PREFIX_PATH` environment variable. +> Note: Building Libxc from source with Autotools is NOT supported when building ABACUS with CMake. +> Please compile Libxc with CMake instead and pass its installation prefix path to +> `CMAKE_PREFIX_PATH` environment variable. ```bash cmake -B build -DENABLE_LIBXC=ON @@ -25,7 +31,9 @@ cmake -B build -DENABLE_LIBXC=ON ## Build with ML-ALGO -If machine learning algorithms, including DeePKS and machine learning based kinetic energy density functional (ML-KEDF) for OFDFT, is required for DFT calculation, the following prerequisites and steps are needed: +If machine learning algorithms, including DeePKS and machine learning based kinetic energy density +functional (ML-KEDF) for OFDFT, is required for DFT calculation, the following prerequisites and +steps are needed: - C++ compiler, supporting **C++14** (GCC >= 5 is sufficient) - CMake >= 3.18 @@ -40,54 +48,81 @@ cmake -B build -DENABLE_MLALGO=1 -DTorch_DIR=~/libtorch/share/cmake/Torch/ -Dlib ## Build with DeePMD-kit -> Note: This part is only required if you want to load a trained DeeP Potential and run molecular dynamics with that. To train the DeeP Potential with DP-GEN, no extra prerequisite is needed and please refer to [this page](http://abacus.deepmodeling.com/en/latest/advanced/interface/dpgen.html) for ABACUS interface with DP-GEN. +> Note: This part is only required if you want to load a trained DeeP Potential and run molecular +> dynamics with that. To train the DeeP Potential with DP-GEN, no extra prerequisite is needed and +> please refer to +> [this page](http://abacus.deepmodeling.com/en/latest/advanced/interface/dpgen.html) for ABACUS +> interface with DP-GEN. -If the Deep Potential model is employed in Molecule Dynamics calculations, the following prerequisites and steps are needed: +If the Deep Potential model is employed in Molecule Dynamics calculations, the following +prerequisites and steps are needed: - [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit) - [TensorFlow](https://www.tensorflow.org/) (optional) - [LibTorch](https://pytorch.org/) (optional) -In the simplest case, the `tensorflow_cc` and `torch` libraries are in the same directory as the `deepmd_c`/`deepmd_cc` libraries, then +In the simplest case, the `tensorflow_cc` and `torch` libraries are in the same directory as the +`deepmd_c`/`deepmd_cc` libraries, then + ```bash cmake -B build -DDeePMD_DIR=/dir_to_deepmd-kit ``` + DeePMD-kit supports TensorFlow backend but its libraries are placed at another directory, then ```bash cmake -B build -DDeePMD_DIR=/dir_to_deepmd-kit -DTensorFlow_DIR=/dir_to_tensorflow ``` -Similarly, DeePMD-kit supports PyTorch backend but its libraries are placed at another directory, then + +Similarly, DeePMD-kit supports PyTorch backend but its libraries are placed at another directory, +then + ```bash cmake -B build -DDeePMD_DIR=/dir_to_deepmd-kit -DTorch_DIR=/dir_to_pytorch ``` ## Build with NEP -This interface enables running MD simulations with the NEP model. It requires the [NEP_CPU](https://github.com/brucefan1983/NEP_CPU) library, which can be easily installed using toolchain as shown below: + +This interface enables running MD simulations with the NEP model. It requires the +[NEP_CPU](https://github.com/brucefan1983/NEP_CPU) library, which can be easily installed using +toolchain as shown below: + ```bash ./install_abacus_toolchain_new.sh --with-nep=install ``` To build ABACUS: + ```bash cmake -B build -DNEP_DIR=/path/to/nep_cpu ``` ## Build with LibRI support -The new EXX implementation directly depends on [LibRI](https://github.com/abacusmodeling/LibRI) to provide RI implementation, while LibRI requires two external dependencies: [LibComm](https://github.com/abacusmodeling/LibComm) for inter-process communication, and [cereal](https://github.com/USCiLab/cereal) for serialization. Set `-DENABLE_LIBRI=ON` to build with these libraries. +The new EXX implementation directly depends on [LibRI](https://github.com/abacusmodeling/LibRI) to +provide RI implementation, while LibRI requires two external dependencies: +[LibComm](https://github.com/abacusmodeling/LibComm) for inter-process communication, and +[cereal](https://github.com/USCiLab/cereal) for serialization. Set `-DENABLE_LIBRI=ON` to build with +these libraries. ```{note} -`ENABLE_LIBCOMM` is deprecated because LibComm is not a standalone ABACUS feature. CMake locates it automatically as a dependency of LibRI. If you prefer using manually downloaded libraries, enable LibRI and provide their locations via `-DLIBRI_DIR=/path/to/LibRI` and `-DLIBCOMM_DIR=/path/to/LibComm`. +`ENABLE_LIBCOMM` is deprecated because LibComm is not a standalone ABACUS feature. CMake locates it +automatically as a dependency of LibRI. If you prefer using manually downloaded libraries, enable +LibRI and provide their locations via `-DLIBRI_DIR=/path/to/LibRI` and +`-DLIBCOMM_DIR=/path/to/LibComm`. ``` ## Build with DFT-D4 support -ABACUS can use the external [DFT-D4](https://github.com/dftd4/dftd4) library for Grimme's DFT-D4 dispersion correction. DFT-D4 support is optional and disabled by default. +ABACUS can use the external [DFT-D4](https://github.com/dftd4/dftd4) library for Grimme's DFT-D4 +dispersion correction. DFT-D4 support is optional and disabled by default. -DFT-D4 must be built and installed with CMake, so that ABACUS can locate it through the exported `dftd4-config.cmake` package. Meson-built installations, including the Conda package of `dftd4`, are not supported unless they provide a compatible CMake package file. +DFT-D4 must be built and installed with CMake, so that ABACUS can locate it through the exported +`dftd4-config.cmake` package. Meson-built installations, including the Conda package of `dftd4`, are +not supported unless they provide a compatible CMake package file. -To build ABACUS with DFT-D4 support, pass `-DENABLE_DFTD4=ON` to CMake and provide `CMAKE_PREFIX_PATH` environment variable. +To build ABACUS with DFT-D4 support, pass `-DENABLE_DFTD4=ON` to CMake and provide +`CMAKE_PREFIX_PATH` environment variable. In the input file, enable DFT-D4 with: @@ -97,15 +132,21 @@ vdw_d4_xc pbe vdw_d4_model d4 # or d4s for the smooth D4S model ``` -If `vdw_d4_xc` is set to `default`, ABACUS will infer the functional name from `dft_functional` or pseudopotential metadata and pass it to the DFT-D4 library. The `vdw_d4_model` keyword selects the dispersion model inside the DFT-D4 library; the default is `d4`, while `d4s` enables the smooth D4S model. +If `vdw_d4_xc` is set to `default`, ABACUS will infer the functional name from `dft_functional` or +pseudopotential metadata and pass it to the DFT-D4 library. The `vdw_d4_model` keyword selects the +dispersion model inside the DFT-D4 library; the default is `d4`, while `d4s` enables the smooth D4S +model. ## Build with JSON support -ABACUS uses [nlohmann-json](https://github.com/nlohmann/json) for optional JSON output. To build ABACUS with JSON support, pass `-DENABLE_JSON=ON` to CMake. +ABACUS uses [nlohmann-json](https://github.com/nlohmann/json) for optional JSON output. To build +ABACUS with JSON support, pass `-DENABLE_JSON=ON` to CMake. ## Build Unit Tests -To build tests for ABACUS, define `BUILD_TESTING` flag. You can also specify path to local installation of [Googletest](https://github.com/google/googletest) by setting `GTEST_DIR` flags. If not found in local, the configuration process will try to download it automatically. +To build tests for ABACUS, define `BUILD_TESTING` flag. You can also specify path to local +installation of [Googletest](https://github.com/google/googletest) by setting `GTEST_DIR` flags. If +not found in local, the configuration process will try to download it automatically. ```bash cmake -B build -DBUILD_TESTING=1 @@ -113,17 +154,23 @@ cmake -B build -DBUILD_TESTING=1 After building, unit tests can be performed with `ctest`. -To run a subset of unit test, use `ctest -R ` to perform tests with name matched by given pattern. +To run a subset of unit test, use `ctest -R ` to perform tests with name matched +by given pattern. ## Build Performance Tests -To build performance tests for ABACUS, define `ENABLE_GOOGLEBENCH` flag. You can also specify the path to a local installation of [Google Benchmark](https://github.com/google/benchmark.git) by setting `BENCHMARK_DIR` flags. If not found locally, the configuration process will try to download it automatically. +To build performance tests for ABACUS, define `ENABLE_GOOGLEBENCH` flag. You can also specify the +path to a local installation of [Google Benchmark](https://github.com/google/benchmark.git) by +setting `BENCHMARK_DIR` flags. If not found locally, the configuration process will try to download +it automatically. ```bash cmake -B build -DENABLE_GOOGLEBENCH=1 ``` -Google Benchmark requires Google Test to build and run the tests. When setting `ENABLE_GOOGLEBENCH` to ON, `BUILD_TESTING` is automatically enabled. After building and installing, performance tests can be executed with `ctest`. +Google Benchmark requires Google Test to build and run the tests. When setting `ENABLE_GOOGLEBENCH` +to ON, `BUILD_TESTING` is automatically enabled. After building and installing, performance tests +can be executed with `ctest`. ## Build with CUDA support @@ -131,13 +178,17 @@ Google Benchmark requires Google Test to build and run the tests. When setting ` - [CUDA-Toolkit](https://developer.nvidia.com/cuda-toolkit) -To build NVIDIA GPU support for ABACUS, define `USE_CUDA` flag. You can also specify path to local installation of CUDA Toolkit by setting `CMAKE_CUDA_COMPILER` flags. +To build NVIDIA GPU support for ABACUS, define `USE_CUDA` flag. You can also specify path to local +installation of CUDA Toolkit by setting `CMAKE_CUDA_COMPILER` flags. ```bash cmake -B build -DUSE_CUDA=1 -DCMAKE_CUDA_COMPILER=${path to cuda toolkit}/bin/nvcc ``` -If you are confident that your MPI supports CUDA Aware, you can add `-DUSE_CUDA_MPI=ON`. In this case, the program will directly communicate data with the CUDA hardware, rather than transferring it to the CPU first before communication. But note that if CUDA Aware is not supported, adding `-DUSE_CUDA_MPI=ON` will cause the program to throw an error. +If you are confident that your MPI supports CUDA Aware, you can add `-DUSE_CUDA_MPI=ON`. In this +case, the program will directly communicate data with the CUDA hardware, rather than transferring it +to the CPU first before communication. But note that if CUDA Aware is not supported, adding +`-DUSE_CUDA_MPI=ON` will cause the program to throw an error. ## Build math library from source @@ -145,10 +196,11 @@ If you are confident that your MPI supports CUDA Aware, you can add `-DUSE_CUDA_ We recommend using the latest available compiler sets instead, since they offer faster implementations of math functions. ``` -This flag is disabled by default. To build math functions from source code, define `ENABLE_ABACUS_LIBM` flag. It is expected to get a better performance on legacy versions of `gcc` and `clang`. +This flag is disabled by default. To build math functions from source code, define +`ENABLE_ABACUS_LIBM` flag. It is expected to get a better performance on legacy versions of `gcc` +and `clang`. -Currently supported math functions: - `sin`, `cos`, `sincos`, `exp`, `cexp` +Currently supported math functions: `sin`, `cos`, `sincos`, `exp`, `cexp` ```bash cmake -B build -DENABLE_ABACUS_LIBM=1 @@ -156,17 +208,24 @@ cmake -B build -DENABLE_ABACUS_LIBM=1 ## Build with PEXSI support -ABACUS supports the PEXSI library for gamma only LCAO calculations. PEXSI version >=2.0.0 is required. +ABACUS supports the PEXSI library for gamma only LCAO calculations. PEXSI version >=2.0.0 is +required. -To build ABACUS with PEXSI support, you need to compile PEXSI and its dependencies first. Please refer to the [PEXSI Installation Guide](https://pexsi.readthedocs.io/en/latest/install.html) for more details. You can also use [Spack](https://github.com/spack/spack) to install the required packages more easily. Note that PEXSI requires ParMETIS and SuperLU_DIST. +To build ABACUS with PEXSI support, you need to compile PEXSI and its dependencies first. Please +refer to the [PEXSI Installation Guide](https://pexsi.readthedocs.io/en/latest/install.html) for +more details. You can also use [Spack](https://github.com/spack/spack) to install the required +packages more easily. Note that PEXSI requires ParMETIS and SuperLU_DIST. -After compiling PEXSI, pass `-DENABLE_PEXSI=ON` to CMake. ABACUS uses the CMake config package provided by PEXSI; if PEXSI or its dependencies are not installed in standard paths, add their installation prefixes to `CMAKE_PREFIX_PATH`. +After compiling PEXSI, pass `-DENABLE_PEXSI=ON` to CMake. ABACUS uses the CMake config package +provided by PEXSI; if PEXSI or its dependencies are not installed in standard paths, add their +installation prefixes to `CMAKE_PREFIX_PATH`. ## Build ABACUS with make > Note: We suggest using CMake to configure and compile. -To compile the ABACUS program using legacy `make`, users need to specify the location of the compilers, headers and libraries in `source/Makefile.vars`: +To compile the ABACUS program using legacy `make`, users need to specify the location of the +compilers, headers and libraries in `source/Makefile.vars`: ```makefile # This is the Makefile of ABACUS API @@ -259,8 +318,8 @@ ENABLE_MLALGO = OFF #====================================================================== ``` -For example, below is a case where the Intel C++ compiler, Intel MPI and CEREAL are used, along with Intel MKL library. The file Makefile.vars can be set as -follows: +For example, below is a case where the Intel C++ compiler, Intel MPI and CEREAL are used, along with +Intel MKL library. The file Makefile.vars can be set as follows: ```makefile CXX = mpiicpc #(or CXX = icpc) @@ -269,7 +328,8 @@ ELPA_INCLUDE_DIR = ${ELPA_DIR}/include/elpa-2021.05.002 CEREAL_DIR = /public/soft/cereal ``` -When `CXX=mpiicpc`, a parallel version will be compiled. When `CXX=icpc`, a sequential version will be compiled. +When `CXX=mpiicpc`, a parallel version will be compiled. When `CXX=icpc`, a sequential version will +be compiled. Another example is where the Gnu C++ compiler, MPICH, OPENBLAS, ScaLAPACK, ELPA and CEREAL are used: @@ -283,7 +343,8 @@ ELPA_INCLUDE_DIR = ${ELPA_DIR}/include/elpa-2021.05.002 CEREAL_DIR = /public/soft/cereal ``` -When `CXX=mpicxx`, a parallel version will be compiled. When `CXX=g++`, a sequential version will be compiled. +When `CXX=mpicxx`, a parallel version will be compiled. When `CXX=g++`, a sequential version will be +compiled. Except modifying `Makefile.vars`, you can also directly use @@ -293,15 +354,21 @@ ELPA_INCLUDE_DIR=${ELPA_DIR}/include/elpa-2021.05.002 \ CEREAL_DIR=/public/soft/cereal ``` -ABACUS now support full version and pw version. Use `make` or `make abacus` to compile full version which supports LCAO calculations. Use `make pw` to compile pw version which only supports pw calculations. For pw version, `make pw CXX=mpiicpc`, you do not need to provide any libs. For `make pw CXX=mpicxx`, you need provide `FFTW_DIR` and `OPENBLAS_LIB_DIR`. +ABACUS now support full version and pw version. Use `make` or `make abacus` to compile full version +which supports LCAO calculations. Use `make pw` to compile pw version which only supports pw +calculations. For pw version, `make pw CXX=mpiicpc`, you do not need to provide any libs. For +`make pw CXX=mpicxx`, you need provide `FFTW_DIR` and `OPENBLAS_LIB_DIR`. After modifying the `Makefile.vars` file, execute `make` or `make -j12` to build the program. -After the compilation finishes without error messages (except perhaps for some warnings), an executable program `ABACUS.mpi` will be created in directory `bin/`. +After the compilation finishes without error messages (except perhaps for some warnings), an +executable program `ABACUS.mpi` will be created in directory `bin/`. ### Add Libxc Support -The program compiled using the above instructions do not link with LIBXC and use exchange-correlation functionals as written in the ABACUS program. However, for some functionals (such as HSE hybrid functional), LIBXC is required. +The program compiled using the above instructions do not link with LIBXC and use +exchange-correlation functionals as written in the ABACUS program. However, for some functionals +(such as HSE hybrid functional), LIBXC is required. To compile ABACUS with LIBXC, you need to define `LIBXC_DIR` in the file `Makefile.vars` or use @@ -313,7 +380,8 @@ directly. ### Add ML-ALGO Support -To compile ABACUS with machine learning algorithms, you need to set `ENABLE_MLALGO = ON`, and define `LIBTORCH_DIR` and `LIBNPY_DIR` in the file `Makefile.vars` or use +To compile ABACUS with machine learning algorithms, you need to set `ENABLE_MLALGO = ON`, and define +`LIBTORCH_DIR` and `LIBNPY_DIR` in the file `Makefile.vars` or use ```bash make ENABLE_MLALGO=ON LIBTORCH_DIR=/opt/libtorch/ LIBNPY_DIR=/opt/libnpy/ @@ -321,30 +389,45 @@ make ENABLE_MLALGO=ON LIBTORCH_DIR=/opt/libtorch/ LIBNPY_DIR=/opt/libnpy/ directly. - ### Add DeePMD-kit Support -> Note: This part is only required if you want to load a trained DeeP Potential and run molecular dynamics with that. To train the DeeP Potential with DP-GEN, no extra prerequisite is needed and please refer to [this page](http://abacus.deepmodeling.com/en/latest/advanced/interface/dpgen.html) for ABACUS interface with DP-GEN. +> Note: This part is only required if you want to load a trained DeeP Potential and run molecular +> dynamics with that. To train the DeeP Potential with DP-GEN, no extra prerequisite is needed and +> please refer to +> [this page](http://abacus.deepmodeling.com/en/latest/advanced/interface/dpgen.html) for ABACUS +> interface with DP-GEN. -To compile ABACUS with DeePMD-kit, you need to define `DeePMD_DIR` and `TensorFlow_DIR` (TensorFlow Backend, optional) and/or `LIBTORCH_DIR` (PyTorch Backend, optional) in the file `Makefile.vars`. +To compile ABACUS with DeePMD-kit, you need to define `DeePMD_DIR` and `TensorFlow_DIR` (TensorFlow +Backend, optional) and/or `LIBTORCH_DIR` (PyTorch Backend, optional) in the file `Makefile.vars`. + +Or the `tensorflow_cc` and `torch` libraries are in the same directory as the `deepmd_c`/`deepmd_cc` +libraries, then -Or the `tensorflow_cc` and `torch` libraries are in the same directory as the `deepmd_c`/`deepmd_cc` libraries, then ```bash make DeePMD_DIR=/dir_to_deepmd-kit ``` + DeePMD-kit supports TensorFlow backend but its libraries are placed at another directory, then ```bash make DeePMD_DIR=/dir_to_deepmd-kit TensorFlow_DIR=/dir_to_tensorflow ``` -Similarly, DeePMD-kit supports PyTorch backend but its libraries are placed at another directory, then + +Similarly, DeePMD-kit supports PyTorch backend but its libraries are placed at another directory, +then + ```bash make DeePMD_DIR=/dir_to_deepmd-kit Torch_DIR=/dir_to_pytorch ``` ### Add LibRI Support -To use new EXX, you need two libraries: [LibRI](https://github.com/abacusmodeling/LibRI) and [LibComm](https://github.com/abacusmodeling/LibComm) and need to define `LIBRI_DIR` and `LIBCOMM_DIR` in the file `Makefile.vars` or use + +To use new EXX, you need two libraries: [LibRI](https://github.com/abacusmodeling/LibRI) and +[LibComm](https://github.com/abacusmodeling/LibComm) and need to define `LIBRI_DIR` and +`LIBCOMM_DIR` in the file `Makefile.vars` or use + ```bash make LIBRI_DIR=/public/software/LibRI LIBCOMM_DIR=/public/software/LibComm ``` + directly. diff --git a/docs/advanced/interface/Hefei-NAMD.md b/docs/advanced/interface/Hefei-NAMD.md index 84246f0ef4d..29a619ec5e3 100644 --- a/docs/advanced/interface/Hefei-NAMD.md +++ b/docs/advanced/interface/Hefei-NAMD.md @@ -1,30 +1,43 @@ # Hefei-NAMD -[Hefei-NAMD](https://github.com/QijingZheng/Hefei-NAMD) Non-adiabatic molecular dynamics applies surface hopping to incorporate quantum mechanical effects into molecular dynamics simulations. Surface hopping partially incorporates the non-adiabatic effects by including excited adiabatic surfaces in the calculations, and allowing for โ€˜hopsโ€™ between these surfaces. +[Hefei-NAMD](https://github.com/QijingZheng/Hefei-NAMD) Non-adiabatic molecular dynamics applies +surface hopping to incorporate quantum mechanical effects into molecular dynamics simulations. +Surface hopping partially incorporates the non-adiabatic effects by including excited adiabatic +surfaces in the calculations, and allowing for โ€˜hopsโ€™ between these surfaces. -Detailed instructions on installing and running Hefei-NAMD can be found on its official [website](http://staff.ustc.edu.cn/~zqj/posts/Hefei-NAMD-Training/). +Detailed instructions on installing and running Hefei-NAMD can be found on its official +[website](http://staff.ustc.edu.cn/~zqj/posts/Hefei-NAMD-Training/). -ABACUS provides results of molecular dynamics simulations for Hefei-NAMD to do non-adiabatic molecular dynamics simulations. +ABACUS provides results of molecular dynamics simulations for Hefei-NAMD to do non-adiabatic +molecular dynamics simulations. The steps are as follows : + 1. Add output parameters in INPUT when running MD using ABACUS . + ``` out_wfc_lcao 1 out_hsk 1 ``` -Then we obtain output files of hamiltonian matrix, overlap matrix, and wavefunction to do NAMD simulation. + +Then we obtain output files of hamiltonian matrix, overlap matrix, and wavefunction to do NAMD +simulation. 2. Clone Hefei-NAMD codes optimized for ABACUS from [website](https://github.com/vtzf/abacus-namd). -3. Modify parameters in `Args.py` including directory of ABACUS output files and NAMD parameters. We can see detailed explanation for all parameters in `Args.py`. +1. Modify parameters in `Args.py` including directory of ABACUS output files and NAMD parameters. We + can see detailed explanation for all parameters in `Args.py`. + +1. Run `NAC.py` to prepare related files for NAMD simulations. -4. Run `NAC.py` to prepare related files for NAMD simulations. ``` sbatch sub_nac ``` -5. Run `SurfHop.py` to perform NAMD simulations. +5. Run `SurfHop.py` to perform NAMD simulations. + ``` sbatch sub_sh ``` + And results are under directory namddir in `Args.py`. diff --git a/docs/advanced/interface/ShengBTE.md b/docs/advanced/interface/ShengBTE.md index e8264aa891e..9acfb50a5c6 100644 --- a/docs/advanced/interface/ShengBTE.md +++ b/docs/advanced/interface/ShengBTE.md @@ -1,11 +1,19 @@ # ShengBTE + ## Introduction -This tutorial aims to introduce the process of performing density functional theory calculations using ABACUS and calculating lattice thermal conductivity using the ShengBTE software. During the entire calculation process, the following external software are also used: 1) Phonopy for calculating second-order force constants, 2) ASE for converting atomic structures, 3) ShengBTE's thirdorder program for calculating third-order force constants, and 4) finally using ShengBTE to calculate the material's lattice thermal conductivity. +This tutorial aims to introduce the process of performing density functional theory calculations +using ABACUS and calculating lattice thermal conductivity using the ShengBTE software. During the +entire calculation process, the following external software are also used: 1) Phonopy for +calculating second-order force constants, 2) ASE for converting atomic structures, 3) ShengBTE's +thirdorder program for calculating third-order force constants, and 4) finally using ShengBTE to +calculate the material's lattice thermal conductivity. -Here is the announcement of ShengBTE with ABACUS: [ShengBTE - The ABACUS DFT software can now be used with ShengBTE](https://www.shengbte.org/announcements/the-abacus-dft-software-can-now-be-used-with-shengbte) +Here is the announcement of ShengBTE with ABACUS: +[ShengBTE - The ABACUS DFT software can now be used with ShengBTE](https://www.shengbte.org/announcements/the-abacus-dft-software-can-now-be-used-with-shengbte) -Some external packages that need to be combined are mentioned above, and here it is recommended to read the relevant documentation and instructions of these packages: +Some external packages that need to be combined are mentioned above, and here it is recommended to +read the relevant documentation and instructions of these packages: ShengBTE๏ผš[https://bitbucket.org/sousaw/shengbte/src/master/](https://bitbucket.org/sousaw/shengbte/src/master/) @@ -13,23 +21,39 @@ phonopy๏ผš[http://abacus.deepmodeling.com/en/latest/advanced/interface/phonopy.h ASE๏ผš[http://abacus.deepmodeling.com/en/latest/advanced/interface/ase.html](http://abacus.deepmodeling.com/en/latest/advanced/interface/ase.html) -thirdorder: [https://bitbucket.org/sousaw/thirdorder/src/master/](https://bitbucket.org/sousaw/thirdorder/src/master/) +thirdorder: +[https://bitbucket.org/sousaw/thirdorder/src/master/](https://bitbucket.org/sousaw/thirdorder/src/master/) ## Prepare -The ABACUS software package provides an example of using ABACUS+ShengBTE to calculate the lattice thermal conductivity in the `examples/interface_ShengBTE` folder. The example includes two folders: `LCAO` (Linear Combination of Atomic Orbitals) which uses numerical atomic orbitals and `PW` (Plane wave) which uses plane wave basis vectors. Each folder contains three subfolders: `2nd`, `3rd`, and `shengbte`, which respectively store the relevant files for calculating second-order force constants using Phonopy (`2nd`), third-order force constants using the thirdorder program (`3rd`), and lattice thermal conductivity using ShengBTE (`shengbte`). +The ABACUS software package provides an example of using ABACUS+ShengBTE to calculate the lattice +thermal conductivity in the `examples/interface_ShengBTE` folder. The example includes two folders: +`LCAO` (Linear Combination of Atomic Orbitals) which uses numerical atomic orbitals and `PW` (Plane +wave) which uses plane wave basis vectors. Each folder contains three subfolders: `2nd`, `3rd`, and +`shengbte`, which respectively store the relevant files for calculating second-order force constants +using Phonopy (`2nd`), third-order force constants using the thirdorder program (`3rd`), and lattice +thermal conductivity using ShengBTE (`shengbte`). ## How to use -Taking the `LCAO` folder as an example, we provide the test case of a diamond structure Si structure containing 2 atoms with the norm-conserving pseudopotential `Si_ONCV_PBE-1.0.upf` and the atomic orbital file `Si_gga_7au_100Ry_2s2p1d.orb` (GGA functional, 7 a.u. cut-off radius, 100 Ry energy cut-off, and DZP orbitals containing 2s2p1d). +Taking the `LCAO` folder as an example, we provide the test case of a diamond structure Si structure +containing 2 atoms with the norm-conserving pseudopotential `Si_ONCV_PBE-1.0.upf` and the atomic +orbital file `Si_gga_7au_100Ry_2s2p1d.orb` (GGA functional, 7 a.u. cut-off radius, 100 Ry energy +cut-off, and DZP orbitals containing 2s2p1d). ### 1. Calculating the second-order force constants -It would be best to combine Phonopy and ASE with ABACUS to calculate the second-order force constants. First, enter the `2nd` folder. +It would be best to combine Phonopy and ASE with ABACUS to calculate the second-order force +constants. First, enter the `2nd` folder. ### 1.1 Structure optimization -Before performing lattice thermal conductivity calculations, it is necessary to optimize the atomic configuration of the simulated material system. The following is the atomic configuration file `STRU` obtained after structure optimization (relax) using ABACUS. In this example, for simplicity, a 2\*2\*2 Brillouin zone k-point sampling was used in the structure optimization process, with an energy cutoff value of 100 Ry for plane waves (the plane wave basis vector is also used in LCAO). Note that the actual calculation should use more convergent k-point sampling. +Before performing lattice thermal conductivity calculations, it is necessary to optimize the atomic +configuration of the simulated material system. The following is the atomic configuration file +`STRU` obtained after structure optimization (relax) using ABACUS. In this example, for simplicity, +a 2\*2\*2 Brillouin zone k-point sampling was used in the structure optimization process, with an +energy cutoff value of 100 Ry for plane waves (the plane wave basis vector is also used in LCAO). +Note that the actual calculation should use more convergent k-point sampling. ```bash ATOMIC_SPECIES @@ -58,7 +82,8 @@ Si #label ### 1.2 Calculating the second-order force constants -The Phonopy software is called to generate multiple atomic configurations of the supercell and corresponding perturbations needed for calculation with the following command: +The Phonopy software is called to generate multiple atomic configurations of the supercell and +corresponding perturbations needed for calculation with the following command: ```bash phonopy setting.conf --abacus -d @@ -71,21 +96,28 @@ DIM = 2 2 2 ATOM_NAME = Si ``` -In this Si example, we only need to generate one perturbed atomic configuration, `STRU-001`. Perform SCF calculations (SCF stands for Self-Consistent Field and represents the iterative self-consistent calculation of density functional theory) on all perturbed configurations (in this case, there is only one for Si) to obtain the forces on the atoms. Afterward, use the following command to generate the `FORCE_SET` file: +In this Si example, we only need to generate one perturbed atomic configuration, `STRU-001`. Perform +SCF calculations (SCF stands for Self-Consistent Field and represents the iterative self-consistent +calculation of density functional theory) on all perturbed configurations (in this case, there is +only one for Si) to obtain the forces on the atoms. Afterward, use the following command to generate +the `FORCE_SET` file: ```bash phonopy -f OUT.DIA-50/running_scf.log ``` -Tip: In the input file `INPUT` of ABACUS, you can set the variable `stru_file`, which corresponds to the atomic configuration file `STRU-001`, and ABACUS will read the structure file directly. +Tip: In the input file `INPUT` of ABACUS, you can set the variable `stru_file`, which corresponds to +the atomic configuration file `STRU-001`, and ABACUS will read the structure file directly. -Next, set the `band.conf` file to calculate the phonon spectrum and the second-order force constants: +Next, set the `band.conf` file to calculate the phonon spectrum and the second-order force +constants: ```bash phonopy -p band.conf --abacus ``` -The `band.conf` file mentioned here contains the following contents (you can refer to the Phonopy documentation for specific parameter meanings): +The `band.conf` file mentioned here contains the following contents (you can refer to the Phonopy +documentation for specific parameter meanings): ```bash ATOM_NAME = Si @@ -99,9 +131,13 @@ FORCE_CONSTANTS = WRITE FULL_FORCE_CONSTANTS = .TRUE. ``` -After this step, the Phonopy software will generate `band.yaml` (for plotting the phonon spectrum) and the `FORCE_CONSTANTS` file. The data contained in the `FORCE_CONSTANTS` file is the second-order force constants. It is important to set `FULL_FORCE_CONSTANTS = .TRUE.`, which outputs all the second-order force constants. Otherwise, there may be errors when ShengBTE reads the data. +After this step, the Phonopy software will generate `band.yaml` (for plotting the phonon spectrum) +and the `FORCE_CONSTANTS` file. The data contained in the `FORCE_CONSTANTS` file is the second-order +force constants. It is important to set `FULL_FORCE_CONSTANTS = .TRUE.`, which outputs all the +second-order force constants. Otherwise, there may be errors when ShengBTE reads the data. -In addition, you can use the following command to output the gnuplot format of the phonon spectrum for plotting: +In addition, you can use the following command to output the gnuplot format of the phonon spectrum +for plotting: ```bash phonopy-bandplot --gnuplot > pho.dat @@ -109,41 +145,63 @@ phonopy-bandplot --gnuplot > pho.dat ### 1.3 Post-processing -Note that ShengBTE software requires the unit of the data in the `FORCE_CONSTANTS_2ND` file to be eV/ร…^2, but the unit of the `FORCE_CONSTANTS` calculated by ABACUS combined with Phonopy is eV/(ร…*au), where au is the atomic unit system and 1 au = 0.52918 ร…. You can use the provided `au2si.py` script in the `2nd` directory to convert the units and generate the `FORCE_CONSTANTS_2ND` file. The command is as follows: +Note that ShengBTE software requires the unit of the data in the `FORCE_CONSTANTS_2ND` file to be +eV/ร…^2, but the unit of the `FORCE_CONSTANTS` calculated by ABACUS combined with Phonopy is +eV/(ร…\*au), where au is the atomic unit system and 1 au = 0.52918 ร…. You can use the provided +`au2si.py` script in the `2nd` directory to convert the units and generate the `FORCE_CONSTANTS_2ND` +file. The command is as follows: ```python python au2si.py ``` -The `FORCE_CONSTANTS_2ND` file is provided in the shengbte folder for reference to the calculation results. +The `FORCE_CONSTANTS_2ND` file is provided in the shengbte folder for reference to the calculation +results. ### 2. Calculating the third-order force constants -To calculate the third-order force constants, you need to combine with the thirdorder program and output the third-order force constant file `FORCE_CONSTANTS_3RD`. However, thirdorder currently only supports reading input and output files from VASP and QE. Therefore, we are using thirdorder by converting ABACUS's structure and output force files to `POSCAR` and `vasprun.xml`, respectively. Please enter the `3rd` folder first, and the specific steps will be described below. +To calculate the third-order force constants, you need to combine with the thirdorder program and +output the third-order force constant file `FORCE_CONSTANTS_3RD`. However, thirdorder currently only +supports reading input and output files from VASP and QE. Therefore, we are using thirdorder by +converting ABACUS's structure and output force files to `POSCAR` and `vasprun.xml`, respectively. +Please enter the `3rd` folder first, and the specific steps will be described below. ### 2.1 Obtaining perturbed configurations -First, convert the optimized `STRU` file from ABACUS software to `POSCAR` (the converted `POSCAR` file is already provided in the directory, or you can do this conversion by yourself). +First, convert the optimized `STRU` file from ABACUS software to `POSCAR` (the converted `POSCAR` +file is already provided in the directory, or you can do this conversion by yourself). -Then, run the `thirdorder_vasp.py` program to generate a series of atomic configuration files `3RD.POSCAR.*` after perturbation. For example, in this example, a total of 40 configurations were generated: +Then, run the `thirdorder_vasp.py` program to generate a series of atomic configuration files +`3RD.POSCAR.*` after perturbation. For example, in this example, a total of 40 configurations were +generated: ```bash thirdorder_vasp.py sow 2 2 2 -2 ``` -Run `pos2stru.py` to convert the above `POSCAR` to `STRU` file. Note that this script calls functions from the ASE software package (ASE needs to be installed in advance): +Run `pos2stru.py` to convert the above `POSCAR` to `STRU` file. Note that this script calls +functions from the ASE software package (ASE needs to be installed in advance): ```python python pos2stru.py ``` -Note: The dpdata software cannot be called here to perform the conversion. This is because the dpdata software forces the lattice to change into a lower triangular matrix, which is equivalent to rotating the lattice and leads to a corresponding rotation in the direction of the interatomic forces, which will cause errors. +Note: The dpdata software cannot be called here to perform the conversion. This is because the +dpdata software forces the lattice to change into a lower triangular matrix, which is equivalent to +rotating the lattice and leads to a corresponding rotation in the direction of the interatomic +forces, which will cause errors. ### 2.2 Calculation of atomic forces for perturbation configurations -You can refer to the `run_stru.sh` script provided in the directory to batch generate `SCF-*` folders and submit calculations. Here, ABACUS needs to perform SCF calculations on 40 atomic configurations, which may take some time. It is recommended to run each SCF separately in the `SCF-*` folder. The `scf_thr` parameter in INPUT file should be set to at least 1e-8 to obtain converged results. +You can refer to the `run_stru.sh` script provided in the directory to batch generate `SCF-*` +folders and submit calculations. Here, ABACUS needs to perform SCF calculations on 40 atomic +configurations, which may take some time. It is recommended to run each SCF separately in the +`SCF-*` folder. The `scf_thr` parameter in INPUT file should be set to at least 1e-8 to obtain +converged results. -After the calculations are complete, run `aba2vasp.py` to package the atomic forces calculated by ABACUS into the `vasprun.xml` format and place them in each `SCF-\*` folder with the following command: +After the calculations are complete, run `aba2vasp.py` to package the atomic forces calculated by +ABACUS into the `vasprun.xml` format and place them in each `SCF-\*` folder with the following +command: ```python python aba2vasp.py @@ -198,11 +256,17 @@ Finally, execute the following command: find SCF-* -name vasprun.xml|sort -n|thirdorder_vasp.py reap 2 2 2 -2 ``` -Then, the third-order force constant file `FORCE_CONSTANTS_3RD` can be obtained by running the above command. The `FORCE_CONSTANTS_3RD` file is provided in the shengbte folder for reference in calculating the results. +Then, the third-order force constant file `FORCE_CONSTANTS_3RD` can be obtained by running the above +command. The `FORCE_CONSTANTS_3RD` file is provided in the shengbte folder for reference in +calculating the results. ### 3. Run ShengBTE to obtain lattice thermal conductivity -Enter the `shengbte` folder, in which the three files `CONTROL` (parameter file of ShengBTE), `FORCE_CONSTANTS_2ND` (second-order force constant file), and `FORCE_CONSTANTS_3RD` (third-order force constant file) have been prepared. Next, run ShengBTE with the following command to obtain the lattice thermal conductivity, where the calculation results are given in the Ref folder for reference: +Enter the `shengbte` folder, in which the three files `CONTROL` (parameter file of ShengBTE), +`FORCE_CONSTANTS_2ND` (second-order force constant file), and `FORCE_CONSTANTS_3RD` (third-order +force constant file) have been prepared. Next, run ShengBTE with the following command to obtain the +lattice thermal conductivity, where the calculation results are given in the Ref folder for +reference: ```bash mpirun -n 10 ShengBTE @@ -210,4 +274,11 @@ mpirun -n 10 ShengBTE ## Conclusion -For using plane wave (PW) in ABACUS to perform ShengBTE calculations, similar procedures should be followed. However, the `scf_thr` parameter in the `INPUT` file for calculating the third-order force constant needs to be set to at least 1e-12. The experimental lattice thermal conductivity of Si at 300 K is around 150 W/(m K), while the calculated thermal conductivity of Si at 300 K is around 100 W/(m K) by using the provided example. This is because, as a demo, a 2\*2\*2 expanded cell and a 2\*2\*2 K-point are used in the example, but the results are not converged yet with respect to the given system size and k-points. In actual research, the size of the supercell and the sampling scheme of K-points need to be tested to obtain converged results. +For using plane wave (PW) in ABACUS to perform ShengBTE calculations, similar procedures should be +followed. However, the `scf_thr` parameter in the `INPUT` file for calculating the third-order force +constant needs to be set to at least 1e-12. The experimental lattice thermal conductivity of Si at +300 K is around 150 W/(m K), while the calculated thermal conductivity of Si at 300 K is around 100 +W/(m K) by using the provided example. This is because, as a demo, a 2\*2\*2 expanded cell and a +2\*2\*2 K-point are used in the example, but the results are not converged yet with respect to the +given system size and k-points. In actual research, the size of the supercell and the sampling +scheme of K-points need to be tested to obtain converged results. diff --git a/docs/advanced/interface/TB2J.md b/docs/advanced/interface/TB2J.md index e246ca5cce6..8b8d47e8bec 100644 --- a/docs/advanced/interface/TB2J.md +++ b/docs/advanced/interface/TB2J.md @@ -2,7 +2,12 @@ ## Introduction -[TB2J](https://github.com/mailhexu/TB2J) is an open-source Python package for the automatic computation of magnetic interactions (including exchange and Dzyaloshinskii-Moriya) between atoms of magnetic crystals from density functional Hamiltonians based on Wannier functions or linear combinations of atomic orbitals. The program is based on Greenโ€™s function method with the local rigid spin rotation treated as a perturbation. The ABACUS interface has been added since TB2J version 0.8.0. +[TB2J](https://github.com/mailhexu/TB2J) is an open-source Python package for the automatic +computation of magnetic interactions (including exchange and Dzyaloshinskii-Moriya) between atoms of +magnetic crystals from density functional Hamiltonians based on Wannier functions or linear +combinations of atomic orbitals. The program is based on Greenโ€™s function method with the local +rigid spin rotation treated as a perturbation. The ABACUS interface has been added since TB2J +version 0.8.0. For more information, see the documentation on https://tb2j.readthedocs.io/en/latest/ @@ -23,24 +28,33 @@ python setup.py install ``` ## The Heisenberg model + The Heisenberg Hamiltonian in TB2J contains three different parts, which are: -$E = -\sum_{i \neq j} \left[ J_{\text{iso}}^{ij} \vec{S}_i \cdot \vec{S}_j + \vec{S}_i J_{\text{ani}}^{ij} \vec{S}_j + \vec{D}_{ij} \cdot (\vec{S}_i \times \vec{S}_j) \right],$ +$E = -\\sum\_{i \\neq j} \\left\[ J\_{\\text{iso}}^{ij} \\vec{S}\_i \\cdot \\vec{S}\_j + \\vec{S}_i +J_{\\text{ani}}^{ij} \\vec{S}_j + \\vec{D}_{ij} \\cdot (\\vec{S}\_i \\times \\vec{S}\_j) \\right\],$ -where $J_{\text{iso}}^{ij}$ represents the isotropic exchange, $J_{\text{ani}}^{ij}$ represents the symmetric anisotropic exhcange which is a 3 $\times$ 3 tensor with $J^{\text{ani}} = J^{\text{ani,T}}$, $\vec{D}_{ij}$ represents the Dzyaloshinskii-Moriya interaction (DMI). +where $J\_{\\text{iso}}^{ij}$ represents the isotropic exchange, $J\_{\\text{ani}}^{ij}$ represents +the symmetric anisotropic exhcange which is a 3 $\\times$ 3 tensor with $J^{\\text{ani}} = +J^{\\text{ani,T}}$, $\\vec{D}\_{ij}$ represents the Dzyaloshinskii-Moriya interaction (DMI). -> **Note:** Exchange parameters conventions for other Heisenberg Hamiltonian can be found in [Conventions of Heisenberg Model](https://tb2j.readthedocs.io/en/latest/src/convention.html). +> **Note:** Exchange parameters conventions for other Heisenberg Hamiltonian can be found in +> [Conventions of Heisenberg Model](https://tb2j.readthedocs.io/en/latest/src/convention.html). ## How to use -With the LCAO basis set, TB2J can directly take the output and compute the exchange parameters. For the PW and LCAO-in-PW basis set, the Wannier90 interace can be used instead. In this tutorial we will use LCAO. +With the LCAO basis set, TB2J can directly take the output and compute the exchange parameters. For +the PW and LCAO-in-PW basis set, the Wannier90 interace can be used instead. In this tutorial we +will use LCAO. ### Collinear calculation without SOC -We take Fe as an example to illustrate how to use ABACUS to generate the input files required for TB2J. +We take Fe as an example to illustrate how to use ABACUS to generate the input files required for +TB2J. + +#### 1. Perform ABACUS calculation. -#### 1. Perform ABACUS calculation. - `INPUT` file: +`INPUT` file: ``` INPUT_PARAMETERS @@ -84,6 +98,7 @@ out_hsr 1 ``` `STRU` file: + ``` ATOMIC_SPECIES Fe 55.845 Fe_ONCV_PBE_FR-1.0.upf @@ -110,21 +125,29 @@ Fe ``` and `KPT` file: + ``` K_POINTS 0 Gamma 8 8 8 0 0 0 ``` -After the key parameter `out_hsr` is set to 1, the Hamiltonian matrix $H(R)$ (in $Ry$) and overlap matrix $S(R)$ will be written into files in the directory `OUT.${suffix}` . In the INPUT, the line: + +After the key parameter `out_hsr` is set to 1, the Hamiltonian matrix $H(R)$ (in $Ry$) and overlap +matrix $S(R)$ will be written into files in the directory `OUT.${suffix}` . In the INPUT, the line: ``` suffix Fe ``` -specifies the suffix of the output, in this calculation, we set the path to the directory of the DFT calculation, which is the current directory (".") and the suffix to Fe. +specifies the suffix of the output, in this calculation, we set the path to the directory of the DFT +calculation, which is the current directory (".") and the suffix to Fe. -> **Note (ABACUS v3.9.0.25+):** Starting from ABACUS v3.9.0.25, the output format has changed to standard CSR format with filenames `hrs1_nao.csr`, `hrs2_nao.csr` (for nspin=2), and `sr_nao.csr`. The parameter `out_hsr` supports optional precision control: `out_hsr 1 8` (default 8 digits); the legacy spelling `out_mat_hs2` remains accepted. TB2J v0.9.0+ is required to read the new format. For older TB2J versions, please use ABACUS v3.8.x or earlier. +> **Note (ABACUS v3.9.0.25+):** Starting from ABACUS v3.9.0.25, the output format has changed to +> standard CSR format with filenames `hrs1_nao.csr`, `hrs2_nao.csr` (for nspin=2), and `sr_nao.csr`. +> The parameter `out_hsr` supports optional precision control: `out_hsr 1 8` (default 8 digits); the +> legacy spelling `out_mat_hs2` remains accepted. TB2J v0.9.0+ is required to read the new format. +> For older TB2J versions, please use ABACUS v3.8.x or earlier. #### 2. Perform TB2J calculation: @@ -132,17 +155,27 @@ specifies the suffix of the output, in this calculation, we set the path to the abacus2J.py --path . --suffix Fe --elements Fe --kmesh 7 7 7 ``` -This first reads the atomic structures from the `STRU` file, then reads the Hamiltonian and overlap matrices. For ABACUS v3.9.0.25+, the matrices are stored in `hrs1_nao.csr`, `hrs2_nao.csr` (nspin=2), and `sr_nao.csr` files. For older versions, they are in `data-HR-*` and `data-SR-*` files. It also reads the fermi energy from the `OUT.Fe/running_scf.log` file. +This first reads the atomic structures from the `STRU` file, then reads the Hamiltonian and overlap +matrices. For ABACUS v3.9.0.25+, the matrices are stored in `hrs1_nao.csr`, `hrs2_nao.csr` +(nspin=2), and `sr_nao.csr` files. For older versions, they are in `data-HR-*` and `data-SR-*` +files. It also reads the fermi energy from the `OUT.Fe/running_scf.log` file. -With the command above, we can calculate the $J$ with a $7 \times 7 \times 7$ k-point grid. This allows for the calculation of exchange between spin pairs between $7 \times 7 \times 7$ supercell. Note: the kmesh is not dense enough for a practical calculation. For a very dense k-mesh, the `--rcut` option can be used to set the maximum distance of the magnetic interactions and thus reduce the computation cost. But be sure that the cutoff is not too small. +With the command above, we can calculate the $J$ with a $7 \\times 7 \\times 7$ k-point grid. This +allows for the calculation of exchange between spin pairs between $7 \\times 7 \\times 7$ supercell. +Note: the kmesh is not dense enough for a practical calculation. For a very dense k-mesh, the +`--rcut` option can be used to set the maximum distance of the magnetic interactions and thus reduce +the computation cost. But be sure that the cutoff is not too small. -The description of the output files in `TB2J_results` can be found in the [TB2J documentation](https://tb2j.readthedocs.io/en/latest/src/output.html). We can find the exchange parameters with `Fe` by : +The description of the output files in `TB2J_results` can be found in the +[TB2J documentation](https://tb2j.readthedocs.io/en/latest/src/output.html). We can find the +exchange parameters with `Fe` by : ```bash grep "Fe" exchange.out ``` -the following contents showing the first, second and third nearest neighbor exchange parameters as 18.6873, 9.9213 and 0.8963 meV, resoectively. More equivalent exchange parameters are also shown. +the following contents showing the first, second and third nearest neighbor exchange parameters as +18.6873, 9.9213 and 0.8963 meV, resoectively. More equivalent exchange parameters are also shown. ``` Fe1 Fe2 ( -1, -1, -1) 18.6873 (-1.433, -1.433, -1.433) 2.482 @@ -179,28 +212,34 @@ the following contents showing the first, second and third nearest neighbor exch Fe2 Fe2 ( -1, 0, -1) 0.8970 (-2.866, 0.000, -2.866) 4.053 ``` -Several other formats of the exchange parameters are also provided in the `TB2J_results` directory , which can be used in spin dynamics code, e.g. [MULTIBINIT](https://docs.abinit.org/tutorial/spin_model/), [Vampire](https://vampire.york.ac.uk/). +Several other formats of the exchange parameters are also provided in the `TB2J_results` directory , +which can be used in spin dynamics code, e.g. +[MULTIBINIT](https://docs.abinit.org/tutorial/spin_model/), [Vampire](https://vampire.york.ac.uk/). ### Non-collinear calculation with SOC -The DMI and anisotropic exchange are result of the SOC, therefore requires the DFT calculation to be done with SOC enabled. To get the full set of exchange parameters, a "rotate and merge" procedure is needed, in which several DFT calculations with either the structure or the spin rotated are needed. For each of the non-collinear calcualtion, we compute the exchange parameters from the DFT calculation with the same command as in the collienar case. +The DMI and anisotropic exchange are result of the SOC, therefore requires the DFT calculation to be +done with SOC enabled. To get the full set of exchange parameters, a "rotate and merge" procedure is +needed, in which several DFT calculations with either the structure or the spin rotated are needed. +For each of the non-collinear calcualtion, we compute the exchange parameters from the DFT +calculation with the same command as in the collienar case. ```bash abacus2J.py --path . --suffix Fe --elements Fe --kmesh 7 7 7 ``` -And then the "TB2J_merge.py" command can be used to get the final spin interaction parameters. - +And then the "TB2J_merge.py" command can be used to get the final spin interaction parameters. ### Parameters of abacus2J.py -We can use the command +We can use the command ```bash abacus2J.py --help ``` -to view the parameters and the usage of them in abacus2J.py. +to view the parameters and the usage of them in abacus2J.py. ### Acknowledgments + We thanks to Xu He to provide critical interface support. diff --git a/docs/advanced/interface/Wannier90.md b/docs/advanced/interface/Wannier90.md index 5d898a1f20c..b0f5689186e 100644 --- a/docs/advanced/interface/Wannier90.md +++ b/docs/advanced/interface/Wannier90.md @@ -1,131 +1,156 @@ # Wannier90 -[Wannier90](http://www.wannier.org/) is a useful package to generating the maximally-localized Wannier functions (MLWFs), which can be used to compute advanced electronic properties. Some post-processing tools (such as WannierTools, etc.) will use MLWFs for further analysis and calculations. - -Currently ABACUS provides an interface to Wannier90 package. The users are assumed to be familiar with the use of Wannier90. The ABACUS-Wannier90 interface is suitable for nspin=1, 2, 4 (including lspinorb=1). - -To construct the MLWFs using the wave functions of ABACUS generally requires four steps. Here we use the diamond as an example which can be found in [examples/interface_wannier90/](https://github.com/abacusmodeling/abacus-develop/tree/develop/examples/interface_wannier90). - -1. Enter the `ABACUS_towannier90_pw/` folder, prepare a Wannier90 input file `diamond.win`, which is the main input file for Wannier90. Then To generate `diamond.nnkp` file by running Wannier90, which ABACUS will read later: - - ``` - wannier90 -pp diamond.win - ``` - - The content of `diamond.win` is as follows: - - ``` - num_wann = 4 - num_iter = 20 - - wannier_plot=.true. - wannier_plot_supercell = 3 - wvfn_formatted = .true. - - begin atoms_frac - C -0.12500 -0.1250 -0.125000 - C 0.12500 0.1250 0.125000 - end atoms_frac - - begin projections - f=0.0,0.0,0.0:s - f=0.0,0.0,0.5:s - f=0.0,0.5,0.0:s - f=0.5,0.0,0.0:s - end projections - - begin unit_cell_cart - -1.613990 0.000000 1.613990 - 0.000000 1.613990 1.613990 - -1.613990 1.613990 0.000000 - end unit_cell_cart - - mp_grid : 4 4 4 - - begin kpoints - 0.0000 0.0000 0.0000 - 0.0000 0.2500 0.0000 - 0.0000 0.5000 0.0000 - 0.0000 0.7500 0.0000 - ... - end kpoints - ``` - -2. Do a self-consistent calculation and get the converged charge density: - - ``` - cp INPUT-scf INPUT - cp KPT-scf KPT - mpirun -np 4 abacus - ``` - - -3. Do a non-self-consistent calculation: - - ``` - cp INPUT-nscf INPUT - cp KPT-nscf KPT - mpirun -np 4 abacus - ``` - - below are the INPUT file (nscf): - - ``` - INPUT_PARAMETERS - - pseudo_dir ../../../tests/PP_ORB - orbital_dir ../../../tests/PP_ORB - ntype 1 - ecutwfc 50 - nbands 4 - smearing_method fixed - calculation nscf - scf_nmax 50 - pw_diag_thr 1.0e-12 - scf_thr 1.0e-13 - init_chg file - symmetry -1 - towannier90 1 - nnkpfile diamond.nnkp - basis_type pw - out_wannier_unk 0 - ``` - - There are seven interface-related parameters in the `INPUT` file: - - - [towannier90](../input_files/input-main.md#towannier90): `1`, generate files for wannier90 code; `0`, do not generate. - - [nnkpfile](../input_files/input-main.md#nnkpfile) : the name of the file generated by running "wannier90 -pp ...". - - [wannier_spin](../input_files/input-main.md#wannier_spin): If you use nspin=2, `up`: calculate the Wannier functions for the spin up components ; `down`: calculate the Wannier functions spin down components. - - [out_wannier_mmn](../input_files/input-main.md#out_wannier_mmn): control whether to output the "*.mmn" file. - - [out_wannier_amn](../input_files/input-main.md#out_wannier_amn): control whether to output the "*.amn" file. - - [out_wannier_eig](../input_files/input-main.md#out_wannier_eig): control whether to output the "*.eig" file. - - [out_wannier_unk](../input_files/input-main.md#out_wannier_unk): control whether to output the "UNK.*" file. - - [out_wannier_wvfn_formatted](../input_files/input-main.md#out_wannier_wvfn_formatted): control what format of the Wannier function file to output, `true`: output the formatted text file; `false`: output the binary file. Note that the `wvfn_formatted` option in `*.win` file (input file of Wannier90) has to be set accordingly with this option. - - **Note: You need to turn off the symmetry during the entire nscf calculation.** - - To setup the `KPT` file according to the `diamond.win` file, which is similar to "begin kpoints ..." in the `diamond.win` file: - - ``` - K_POINTS - 64 - Direct - 0.0000 0.0000 0.0000 0.0156250 - 0.0000 0.2500 0.0000 0.0156250 - 0.0000 0.5000 0.0000 0.0156250 - 0.0000 0.7500 0.0000 0.0156250 - ... - ``` - - After the nscf calculation, ABACUS will generate `diamond.amn`, `diamond.mmn`, `diamond.eig`, `UNK` files in the `OUT.` folder which are input files needed by Wannier90 code. - -4. Copy `.amn`, `.mmn`, `.eig`, `UNK` file to `wannier/` folder, to get the MLWFs by running Wannier90: - - ``` - wannier90 diamond.win - ``` +[Wannier90](http://www.wannier.org/) is a useful package to generating the maximally-localized +Wannier functions (MLWFs), which can be used to compute advanced electronic properties. Some +post-processing tools (such as WannierTools, etc.) will use MLWFs for further analysis and +calculations. + +Currently ABACUS provides an interface to Wannier90 package. The users are assumed to be familiar +with the use of Wannier90. The ABACUS-Wannier90 interface is suitable for nspin=1, 2, 4 (including +lspinorb=1). + +To construct the MLWFs using the wave functions of ABACUS generally requires four steps. Here we use +the diamond as an example which can be found in +[examples/interface_wannier90/](https://github.com/abacusmodeling/abacus-develop/tree/develop/examples/interface_wannier90). + +1. Enter the `ABACUS_towannier90_pw/` folder, prepare a Wannier90 input file `diamond.win`, which is + the main input file for Wannier90. Then To generate `diamond.nnkp` file by running Wannier90, + which ABACUS will read later: + + ``` + wannier90 -pp diamond.win + ``` + + The content of `diamond.win` is as follows: + + ``` + num_wann = 4 + num_iter = 20 + + wannier_plot=.true. + wannier_plot_supercell = 3 + wvfn_formatted = .true. + + begin atoms_frac + C -0.12500 -0.1250 -0.125000 + C 0.12500 0.1250 0.125000 + end atoms_frac + + begin projections + f=0.0,0.0,0.0:s + f=0.0,0.0,0.5:s + f=0.0,0.5,0.0:s + f=0.5,0.0,0.0:s + end projections + + begin unit_cell_cart + -1.613990 0.000000 1.613990 + 0.000000 1.613990 1.613990 + -1.613990 1.613990 0.000000 + end unit_cell_cart + + mp_grid : 4 4 4 + + begin kpoints + 0.0000 0.0000 0.0000 + 0.0000 0.2500 0.0000 + 0.0000 0.5000 0.0000 + 0.0000 0.7500 0.0000 + ... + end kpoints + ``` + +1. Do a self-consistent calculation and get the converged charge density: + + ``` + cp INPUT-scf INPUT + cp KPT-scf KPT + mpirun -np 4 abacus + ``` + +1. Do a non-self-consistent calculation: + + ``` + cp INPUT-nscf INPUT + cp KPT-nscf KPT + mpirun -np 4 abacus + ``` + + below are the INPUT file (nscf): + + ``` + INPUT_PARAMETERS + + pseudo_dir ../../../tests/PP_ORB + orbital_dir ../../../tests/PP_ORB + ntype 1 + ecutwfc 50 + nbands 4 + smearing_method fixed + calculation nscf + scf_nmax 50 + pw_diag_thr 1.0e-12 + scf_thr 1.0e-13 + init_chg file + symmetry -1 + towannier90 1 + nnkpfile diamond.nnkp + basis_type pw + out_wannier_unk 0 + ``` + + There are seven interface-related parameters in the `INPUT` file: + + - [towannier90](../input_files/input-main.md#towannier90): `1`, generate files for wannier90 + code; `0`, do not generate. + - [nnkpfile](../input_files/input-main.md#nnkpfile) : the name of the file generated by running + "wannier90 -pp ...". + - [wannier_spin](../input_files/input-main.md#wannier_spin): If you use nspin=2, `up`: calculate + the Wannier functions for the spin up components ; `down`: calculate the Wannier functions spin + down components. + - [out_wannier_mmn](../input_files/input-main.md#out_wannier_mmn): control whether to output the + "\*.mmn" file. + - [out_wannier_amn](../input_files/input-main.md#out_wannier_amn): control whether to output the + "\*.amn" file. + - [out_wannier_eig](../input_files/input-main.md#out_wannier_eig): control whether to output the + "\*.eig" file. + - [out_wannier_unk](../input_files/input-main.md#out_wannier_unk): control whether to output the + "UNK.\*" file. + - [out_wannier_wvfn_formatted](../input_files/input-main.md#out_wannier_wvfn_formatted): control + what format of the Wannier function file to output, `true`: output the formatted text file; + `false`: output the binary file. Note that the `wvfn_formatted` option in `*.win` file (input + file of Wannier90) has to be set accordingly with this option. + + **Note: You need to turn off the symmetry during the entire nscf calculation.** + + To setup the `KPT` file according to the `diamond.win` file, which is similar to "begin kpoints + ..." in the `diamond.win` file: + + ``` + K_POINTS + 64 + Direct + 0.0000 0.0000 0.0000 0.0156250 + 0.0000 0.2500 0.0000 0.0156250 + 0.0000 0.5000 0.0000 0.0156250 + 0.0000 0.7500 0.0000 0.0156250 + ... + ``` + + After the nscf calculation, ABACUS will generate `diamond.amn`, `diamond.mmn`, `diamond.eig`, + `UNK` files in the `OUT.` folder which are input files needed by Wannier90 code. + +1. Copy `.amn`, `.mmn`, `.eig`, `UNK` file to `wannier/` folder, to get the MLWFs by running + Wannier90: + + ``` + wannier90 diamond.win + ``` Notes: - The ABACUS-wannier90 interface can be used in both PW and LCAO basis. -- If you want to plot the Wannier function, you must set `wvfn_formatted = .true.` in `diamond.win`, otherwise Wannier90 code cannot read files generated by ABACUS because these files are not binary files. You also have to generate the `diamond.amn` and `UNK` files for the plot. Otherwise, the two types of file are not necessary. +- If you want to plot the Wannier function, you must set `wvfn_formatted = .true.` in `diamond.win`, + otherwise Wannier90 code cannot read files generated by ABACUS because these files are not binary + files. You also have to generate the `diamond.amn` and `UNK` files for the plot. Otherwise, the + two types of file are not necessary. diff --git a/docs/advanced/interface/ase.md b/docs/advanced/interface/ase.md index b7b02d3a279..7d57bce9bf7 100644 --- a/docs/advanced/interface/ase.md +++ b/docs/advanced/interface/ase.md @@ -2,13 +2,22 @@ ## Introduction -[ASE](https://wiki.fysik.dtu.dk/ase/) (Atomic Simulation Environment) performs as a powerful Pythonic platform for atomistic simulations, in which there are plenty of functionalties supported, such as various geometry optimization algorithms for finding both the minimum energy point and the transition states, including BFGS, BFGSLineSearch, FIRE, NEB, AUTO-NEB, etc, and various molecular dynamics techniques, including thermostats (Langevin, CSVR, Nose-Hoover Chain, etc) and metadynamics (via the interface with Plumed). +[ASE](https://wiki.fysik.dtu.dk/ase/) (Atomic Simulation Environment) performs as a powerful +Pythonic platform for atomistic simulations, in which there are plenty of functionalties supported, +such as various geometry optimization algorithms for finding both the minimum energy point and the +transition states, including BFGS, BFGSLineSearch, FIRE, NEB, AUTO-NEB, etc, and various molecular +dynamics techniques, including thermostats (Langevin, CSVR, Nose-Hoover Chain, etc) and metadynamics +(via the interface with Plumed). -Due to the growing number of softwares and machine-learning forcefields, we turn to maintain the interface with ASE by our own, while a legacy version of ASE interface can still be found at [our GitLab repository of ase-abacus](https://gitlab.com/1041176461/ase-abacus ). +Due to the growing number of softwares and machine-learning forcefields, we turn to maintain the +interface with ASE by our own, while a legacy version of ASE interface can still be found at +[our GitLab repository of ase-abacus](https://gitlab.com/1041176461/ase-abacus). ## Installation -We strongly recommend you create a virtual environment for the installation of Python packages of abacus, such as `conda` or `venv`, to avoid conflicts with other packages, for example, with the `conda`: +We strongly recommend you create a virtual environment for the installation of Python packages of +abacus, such as `conda` or `venv`, to avoid conflicts with other packages, for example, with the +`conda`: ```bash conda create -n abacus python=3.10 @@ -24,8 +33,8 @@ pip install . ## ABACUS Calculator -Present calculator implementation requires a "profile" to act as an interface between the Python runtime and the file system. -Instantiate an `AbacusProfile` object with proper settings: +Present calculator implementation requires a "profile" to act as an interface between the Python +runtime and the file system. Instantiate an `AbacusProfile` object with proper settings: ```python from abacuslite import AbacusProfile @@ -36,8 +45,9 @@ aprof = AbacusProfile( orbital_dir='/path/to/folder/of/orbitals', # OPTIONAL! ) ``` -, by such lines, you build the interface between the computational environment and the Python runtime. -This interface can be reused in multiple calculations. + +, by such lines, you build the interface between the computational environment and the Python +runtime. This interface can be reused in multiple calculations. Then, you can instantiate the `Abacus` calculator with the profile by: @@ -63,7 +73,10 @@ abacus = Abacus( } ) ``` -, where except the `directory`, you can focus on the setting of ABACUS itself. In `inp`, you can set everything as you do in INPUT file of ABACUS. The kpoint sampling can also be set by the `kpts` parameter, like: + +, where except the `directory`, you can focus on the setting of ABACUS itself. In `inp`, you can set +everything as you do in INPUT file of ABACUS. The kpoint sampling can also be set by the `kpts` +parameter, like: ```python abacus = Abacus( @@ -77,7 +90,8 @@ abacus = Abacus( ) ``` -If with the `tempfile` module, you can create an abacus instance whose directory will be automatically removed when leaves from the context: +If with the `tempfile` module, you can create an abacus instance whose directory will be +automatically removed when leaves from the context: ```python import tempfile @@ -99,7 +113,10 @@ with tempfile.TemporaryDirectory() as tmpdir: ## Perform Calculations -In the new implementation, we limit the range of functionalties supported to mainly include the necessary ones, such as the SCF calculation, the energy and force/stress evaluation. The other features, such as starting the molecule dynamics directly in ABACUS from Python, is not supported anymore. Instead, it is encouraged to use the ASE tools to perform the molecule dynamics. +In the new implementation, we limit the range of functionalties supported to mainly include the +necessary ones, such as the SCF calculation, the energy and force/stress evaluation. The other +features, such as starting the molecule dynamics directly in ABACUS from Python, is not supported +anymore. Instead, it is encouraged to use the ASE tools to perform the molecule dynamics. Please read the examples in `interfaces/ASE_interface/examples/` for more details. @@ -107,32 +124,37 @@ Please read the examples in `interfaces/ASE_interface/examples/` for more detail #### When to use socket mode -`AbacusSocketIO` is designed for a sequence of electronic-structure -evaluations in which the atomic positions change while the simulation context -remains fixed. Reuse one socket calculator only when the cell and periodic -boundary conditions, atom count and species, pseudopotentials and orbitals, -k-point sampling, spin settings, and other electronic-structure parameters do -not change. The socket session can then keep one ABACUS process alive and -receive successive position updates. - -This pattern is suitable for fixed-cell ASE optimization and molecular -dynamics, fixed-cell NEB (use an independent calculator/session for each image), -finite-displacement phonon or ASE finite-difference frequency calculations, -position-only P-RFO or transition-state searches, and repeated fixed-cell -force evaluations in larger workflows such as thermal-property or active- -learning data generation. These workflows can use the socket calculator only -when their driver calls the ASE calculator interface; the existing Phonopy, -ShengBTE, DP-GEN, or transition-state tools are not automatically converted -to socket workflows by installing abacuslite. - -Use the regular `Abacus` FileIO calculator when the cell, composition, or -electronic-structure settings must change. Direct DFPT or dynamical-matrix -calculations, and external workflows that require properties beyond energy, -forces, and stress, also remain outside the current socket property interface. - -For socket-driven ASE workflows, use the `AbacusSocketIO` calculator. ASE runs the i-PI socket server, while ABACUS keeps `calculation=scf` and is launched with `socket_driver=1` as the client. Energy, forces, and stress are independent properties controlled by `cal_force` and `cal_stress`; the fixed i-PI wire layout still contains padding fields, while extras metadata identifies which values were actually computed. See the [ASE socket I/O documentation](https://ase-lib.org/ase/calculators/socketio/socketio.html) and the i-PI reference paper, [Ceriotti et al., Comput. Phys. Commun. 185, 1019-1026 (2014)](https://doi.org/10.1016/j.cpc.2013.10.027), for the protocol background. - -Build ABACUS as usual before using this interface. PW-only builds work with `basis_type=pw`; LCAO socket calculations require an LCAO-enabled executable. No extra socket library is required. +`AbacusSocketIO` is designed for a sequence of electronic-structure evaluations in which the atomic +positions change while the simulation context remains fixed. Reuse one socket calculator only when +the cell and periodic boundary conditions, atom count and species, pseudopotentials and orbitals, +k-point sampling, spin settings, and other electronic-structure parameters do not change. The socket +session can then keep one ABACUS process alive and receive successive position updates. + +This pattern is suitable for fixed-cell ASE optimization and molecular dynamics, fixed-cell NEB (use +an independent calculator/session for each image), finite-displacement phonon or ASE +finite-difference frequency calculations, position-only P-RFO or transition-state searches, and +repeated fixed-cell force evaluations in larger workflows such as thermal-property or active- +learning data generation. These workflows can use the socket calculator only when their driver calls +the ASE calculator interface; the existing Phonopy, ShengBTE, DP-GEN, or transition-state tools are +not automatically converted to socket workflows by installing abacuslite. + +Use the regular `Abacus` FileIO calculator when the cell, composition, or electronic-structure +settings must change. Direct DFPT or dynamical-matrix calculations, and external workflows that +require properties beyond energy, forces, and stress, also remain outside the current socket +property interface. + +For socket-driven ASE workflows, use the `AbacusSocketIO` calculator. ASE runs the i-PI socket +server, while ABACUS keeps `calculation=scf` and is launched with `socket_driver=1` as the client. +Energy, forces, and stress are independent properties controlled by `cal_force` and `cal_stress`; +the fixed i-PI wire layout still contains padding fields, while extras metadata identifies which +values were actually computed. See the +[ASE socket I/O documentation](https://ase-lib.org/ase/calculators/socketio/socketio.html) and the +i-PI reference paper, +[Ceriotti et al., Comput. Phys. Commun. 185, 1019-1026 (2014)](https://doi.org/10.1016/j.cpc.2013.10.027), +for the protocol background. + +Build ABACUS as usual before using this interface. PW-only builds work with `basis_type=pw`; LCAO +socket calculations require an LCAO-enabled executable. No extra socket library is required. With CMake, choose the executable according to the basis: @@ -144,9 +166,19 @@ cmake -S . -B build-lcao -DENABLE_MPI=ON -DENABLE_LCAO=ON cmake --build build-lcao --target abacus_basic_para -j ``` -With the ABACUS toolchain workflow, build the normal ABACUS executable with LCAO support when `basis_type=lcao` is needed, then pass that executable to `AbacusProfile(command=...)`. The command can include an MPI launcher, for example `mpirun -np 4 /path/to/abacus`; ABACUS rank 0 opens the socket connection and broadcasts the i-PI data to the other ranks internally. On managed clusters, keep scheduler-specific launch options outside the calculator when possible and test the exact launcher command on a compute node. +With the ABACUS toolchain workflow, build the normal ABACUS executable with LCAO support when +`basis_type=lcao` is needed, then pass that executable to `AbacusProfile(command=...)`. The command +can include an MPI launcher, for example `mpirun -np 4 /path/to/abacus`; ABACUS rank 0 opens the +socket connection and broadcasts the i-PI data to the other ranks internally. On managed clusters, +keep scheduler-specific launch options outside the calculator when possible and test the exact +launcher command on a compute node. -For PW calculations on CUDA/ROCm with multiple MPI ranks, use a k-point layout compatible with ABACUS' GPU parallelization. In practice, make sure each k-point pool contains one MPI rank; for example, a 4-rank PW GPU socket calculation should use at least four k-points so the default GPU `kpar` adjustment can assign one rank per pool. A one-k-point PW GPU job with several MPI ranks can fail in the PW GPU transform path; reduce the rank count or use a denser k-point mesh such as a smaller `kspacing`. +For PW calculations on CUDA/ROCm with multiple MPI ranks, use a k-point layout compatible with +ABACUS' GPU parallelization. In practice, make sure each k-point pool contains one MPI rank; for +example, a 4-rank PW GPU socket calculation should use at least four k-points so the default GPU +`kpar` adjustment can assign one rank per pool. A one-k-point PW GPU job with several MPI ranks can +fail in the PW GPU transform path; reduce the rank count or use a denser k-point mesh such as a +smaller `kspacing`. The ASE interface can be installed from this repository with: @@ -182,30 +214,75 @@ with abacus as calc: BFGS(atoms).run(fmax=0.05) ``` -`AbacusSocketIO` sets `socket_driver=1` automatically. The adapter enables properties requested through ASE, restarting the client if a later request expands the active property set. Set `inp={'cal_force': 1}` and/or `inp={'cal_stress': 1}` when a fixed-cell optimizer, MD integrator, or stress evaluation client needs those properties. Energy is always available. The interface selects the socket endpoint and passes it to ABACUS through `ABACUS_SOCKET_ADDRESS`, so users normally do not set this environment variable by hand when using abacuslite. +`AbacusSocketIO` sets `socket_driver=1` automatically. The adapter enables properties requested +through ASE, restarting the client if a later request expands the active property set. Set +`inp={'cal_force': 1}` and/or `inp={'cal_stress': 1}` when a fixed-cell optimizer, MD integrator, or +stress evaluation client needs those properties. Energy is always available. The interface selects +the socket endpoint and passes it to ABACUS through `ABACUS_SOCKET_ADDRESS`, so users normally do +not set this environment variable by hand when using abacuslite. There are two endpoint styles: -- `unixsocket="abacus_si"` uses a local Unix-domain socket. ASE creates and listens on `/tmp/ipi_abacus_si`; abacuslite launches ABACUS with `ABACUS_SOCKET_ADDRESS=/tmp/ipi_abacus_si:UNIX`. The `:UNIX` suffix is part of ABACUS' address syntax and means that `/tmp/ipi_abacus_si` is a filesystem socket path, not a TCP host. This is usually the best choice when ASE and ABACUS run on the same node because it avoids TCP port conflicts. -- `port=31415` uses a TCP socket. abacuslite launches ABACUS with `ABACUS_SOCKET_ADDRESS=localhost:31415`, meaning host `localhost` and TCP port `31415`. Use this style when the socket server should listen on a TCP port. If ABACUS is launched manually instead of through `AbacusSocketIO`, set `ABACUS_SOCKET_ADDRESS` yourself to the same `host:port` or `path:UNIX` endpoint. - -Calling `atoms.get_potential_energy()` does not force a force or stress calculation. If a requested property was disabled, ASE raises `PropertyNotImplementedError`; zero-filled i-PI padding is never treated as a physical result. When SCF does not converge, `AbacusSocketIO.last_scf_converged` is set to `False` and the caller decides whether to continue or stop. - -The ABACUS metadata extension is required to expose force/stress presence safely. If a legacy client returns an empty extras field, the adapter accepts only an energy-only response and refuses to infer forces or stress from the fixed-wire padding. Generic i-PI/ASE clients that ignore ABACUS extras cannot distinguish mandatory padding from a computed zero; use `AbacusSocketIO` or another metadata-aware client when requesting optional properties. When launching ABACUS with a generic client, explicitly set `cal_force=1` for force-driven workflows and `cal_stress=1` for stress evaluation; an omitted switch defaults to disabled. Such clients also need their own policy for unconverged SCF results. - -A socket calculator owns one ABACUS process initialized from one fixed `INPUT`/`STRU` setup. Reuse the same `AbacusSocketIO` instance only for position updates under the same electronic-structure settings and the same cell. Do not change `kpts`, `kspacing`, `nspin`, `basis_type`, `basissets`, pseudopotentials, species, atom count, cell, or other core `INPUT`/`STRU` parameters through an existing socket calculator; create a new `AbacusSocketIO` instance and a new ABACUS client process for those changes. `AbacusSocketIO` rejects cell changes before sending them to ABACUS, and the ABACUS socket driver also checks incoming POSDATA cells against the initial `STRU` cell and exits if they differ. - -In socket mode, ABACUS keeps one client process alive. All SCF evaluations produced by the same `AbacusSocketIO` instance are appended to the same `OUT.ABACUS/running_scf.log`, because the ABACUS calculation type remains `scf`. The authoritative per-step energy and force results are returned through the i-PI socket to ASE. Use ASE trajectory and optimizer log files, such as `BFGS(atoms, trajectory="opt.traj", logfile="opt.log")`, when each optimizer or MD step should be saved separately. Treat `running_scf.log` mainly as the ABACUS diagnostic log for the socket client, not as one independent FileIO result per structure. - -The i-PI protocol does not transmit element symbols. `AbacusSocketIO` therefore sorts the internal socket atoms with the same first-occurrence species grouping used when writing `STRU`, and maps returned forces back to the original ASE `Atoms` order. This avoids silent force/atom mismatches when structures are read from CIF, extxyz, POSCAR, or other formats whose atom order is not already grouped for ABACUS. Users should not manually reorder atoms for socket I/O; pass the physical ASE `Atoms` object directly to the calculator. - -A complete fixed-cell validation and benchmark example is available in `interfaces/ASE_interface/examples/socketio.py`. +- `unixsocket="abacus_si"` uses a local Unix-domain socket. ASE creates and listens on + `/tmp/ipi_abacus_si`; abacuslite launches ABACUS with + `ABACUS_SOCKET_ADDRESS=/tmp/ipi_abacus_si:UNIX`. The `:UNIX` suffix is part of ABACUS' address + syntax and means that `/tmp/ipi_abacus_si` is a filesystem socket path, not a TCP host. This is + usually the best choice when ASE and ABACUS run on the same node because it avoids TCP port + conflicts. +- `port=31415` uses a TCP socket. abacuslite launches ABACUS with + `ABACUS_SOCKET_ADDRESS=localhost:31415`, meaning host `localhost` and TCP port `31415`. Use this + style when the socket server should listen on a TCP port. If ABACUS is launched manually instead + of through `AbacusSocketIO`, set `ABACUS_SOCKET_ADDRESS` yourself to the same `host:port` or + `path:UNIX` endpoint. + +Calling `atoms.get_potential_energy()` does not force a force or stress calculation. If a requested +property was disabled, ASE raises `PropertyNotImplementedError`; zero-filled i-PI padding is never +treated as a physical result. When SCF does not converge, `AbacusSocketIO.last_scf_converged` is set +to `False` and the caller decides whether to continue or stop. + +The ABACUS metadata extension is required to expose force/stress presence safely. If a legacy client +returns an empty extras field, the adapter accepts only an energy-only response and refuses to infer +forces or stress from the fixed-wire padding. Generic i-PI/ASE clients that ignore ABACUS extras +cannot distinguish mandatory padding from a computed zero; use `AbacusSocketIO` or another +metadata-aware client when requesting optional properties. When launching ABACUS with a generic +client, explicitly set `cal_force=1` for force-driven workflows and `cal_stress=1` for stress +evaluation; an omitted switch defaults to disabled. Such clients also need their own policy for +unconverged SCF results. + +A socket calculator owns one ABACUS process initialized from one fixed `INPUT`/`STRU` setup. Reuse +the same `AbacusSocketIO` instance only for position updates under the same electronic-structure +settings and the same cell. Do not change `kpts`, `kspacing`, `nspin`, `basis_type`, `basissets`, +pseudopotentials, species, atom count, cell, or other core `INPUT`/`STRU` parameters through an +existing socket calculator; create a new `AbacusSocketIO` instance and a new ABACUS client process +for those changes. `AbacusSocketIO` rejects cell changes before sending them to ABACUS, and the +ABACUS socket driver also checks incoming POSDATA cells against the initial `STRU` cell and exits if +they differ. + +In socket mode, ABACUS keeps one client process alive. All SCF evaluations produced by the same +`AbacusSocketIO` instance are appended to the same `OUT.ABACUS/running_scf.log`, because the ABACUS +calculation type remains `scf`. The authoritative per-step energy and force results are returned +through the i-PI socket to ASE. Use ASE trajectory and optimizer log files, such as +`BFGS(atoms, trajectory="opt.traj", logfile="opt.log")`, when each optimizer or MD step should be +saved separately. Treat `running_scf.log` mainly as the ABACUS diagnostic log for the socket client, +not as one independent FileIO result per structure. + +The i-PI protocol does not transmit element symbols. `AbacusSocketIO` therefore sorts the internal +socket atoms with the same first-occurrence species grouping used when writing `STRU`, and maps +returned forces back to the original ASE `Atoms` order. This avoids silent force/atom mismatches +when structures are read from CIF, extxyz, POSCAR, or other formats whose atom order is not already +grouped for ABACUS. Users should not manually reorder atoms for socket I/O; pass the physical ASE +`Atoms` object directly to the calculator. + +A complete fixed-cell validation and benchmark example is available in +`interfaces/ASE_interface/examples/socketio.py`. ## SPAP Analysis -[SPAP](https://github.com/chuanxun/StructurePrototypeAnalysisPackage) (Structure Prototype Analysis Package) is written by Dr. Chuanxun Su to analyze symmetry and compare similarity of large amount of atomic structures. The coordination characterization function (CCF) is used to -measure structural similarity. An unique and advanced clustering method is developed to automatically classify structures into groups. - +[SPAP](https://github.com/chuanxun/StructurePrototypeAnalysisPackage) (Structure Prototype Analysis +Package) is written by Dr. Chuanxun Su to analyze symmetry and compare similarity of large amount of +atomic structures. The coordination characterization function (CCF) is used to measure structural +similarity. An unique and advanced clustering method is developed to automatically classify +structures into groups. If you use this program and method in your research, please read and cite the publication: @@ -213,9 +290,8 @@ If you use this program and method in your research, please read and cite the pu and you should install it first with command `pip install spap`. -Socket results are read directly from the completed in-memory solver frame, not -parsed from output files. The client clears cached results and convergence -metadata before a new request and publishes them only after validating the full -response. A failed request therefore leaves no previous-frame result available -in the calculator cache. This protocol guarantee does not establish SCF -convergence or numerical agreement with independent single-point calculations. +Socket results are read directly from the completed in-memory solver frame, not parsed from output +files. The client clears cached results and convergence metadata before a new request and publishes +them only after validating the full response. A failed request therefore leaves no previous-frame +result available in the calculator cache. This protocol guarantee does not establish SCF convergence +or numerical agreement with independent single-point calculations. diff --git a/docs/advanced/interface/candela.md b/docs/advanced/interface/candela.md index 753b305aee2..649145b6748 100644 --- a/docs/advanced/interface/candela.md +++ b/docs/advanced/interface/candela.md @@ -1,19 +1,26 @@ # CANDELA -[CANDELA](https://github.com/MCresearch/Candela) is short for Collection of ANalysis DEsigned for Large-scale Atomic simulations. -It is developed by MCresearch to conduct analyses on MD trajectory in different formats. -Right now the program only supports analysis of pair distribution function (PDF), static structure factor (SSF) and mean square displacement (MSD). -The minimum supported version of ABACUS is 3.2.0. - -## Requirements for using CANDELA -For Detailed usage of CANDELA, please refer to the [official document](https://candela-docs.readthedocs.io/en/latest/). -There are two things which need special attention in using CANDELA with ABACUS. -First, the input file of CANDELA only takes the name of `INPUT`, the same as ABACUS input file, so you should not run CANDELA in the same folder where you run ABACUS. -Second, to use CANDELA to postprocess ABACUS MD trajectory, the following parameters have to be specified in the `INPUT` file of CANDELA in addition to other required parameters: +[CANDELA](https://github.com/MCresearch/Candela) is short for Collection of ANalysis DEsigned for +Large-scale Atomic simulations. It is developed by MCresearch to conduct analyses on MD trajectory +in different formats. Right now the program only supports analysis of pair distribution function +(PDF), static structure factor (SSF) and mean square displacement (MSD). The minimum supported +version of ABACUS is 3.2.0. + +## Requirements for using CANDELA + +For Detailed usage of CANDELA, please refer to the +[official document](https://candela-docs.readthedocs.io/en/latest/). There are two things which need +special attention in using CANDELA with ABACUS. First, the input file of CANDELA only takes the name +of `INPUT`, the same as ABACUS input file, so you should not run CANDELA in the same folder where +you run ABACUS. Second, to use CANDELA to postprocess ABACUS MD trajectory, the following parameters +have to be specified in the `INPUT` file of CANDELA in addition to other required parameters: + 1. `geo_in_type` has to be set to `ABACUS`; -2. `msd_dt` has to be specified in unit of picosecond, especially in the case of `calculation` = `msd`; -3. `geo_directory` has to be set to the path to the `MD_dump` file in the `OUT.xxx` folder. -As a result, a CANDELA `INPUT` file for calculating PDF from ABACUS should be something like this: +1. `msd_dt` has to be specified in unit of picosecond, especially in the case of `calculation` = + `msd`; +1. `geo_directory` has to be set to the path to the `MD_dump` file in the `OUT.xxx` folder. As a + result, a CANDELA `INPUT` file for calculating PDF from ABACUS should be something like this: + ``` calculation pdf # Pair Distribution Function. system Al @@ -36,4 +43,5 @@ struf_dgx 0.05 struf_ng 200 ``` -More examples of CANDELA `INPUT` with ABACUS can be found in the [test](https://github.com/MCresearch/Candela/tree/main/test) directory. \ No newline at end of file +More examples of CANDELA `INPUT` with ABACUS can be found in the +[test](https://github.com/MCresearch/Candela/tree/main/test) directory. diff --git a/docs/advanced/interface/deeph.md b/docs/advanced/interface/deeph.md index c27cd0386e8..44f7e59ad36 100644 --- a/docs/advanced/interface/deeph.md +++ b/docs/advanced/interface/deeph.md @@ -1,32 +1,52 @@ # DeepH -[DeepH](https://doi.org/10.1038/s43588-022-00265-6) applies meaching learning to predict the Hamiltonian in atomic basis representation. For such purpose, DeepH uses the Hamiltonian and overlap matrices from DFT calculations. Here we introduce how to extract relevant information from ABACUS for the purpose of DeepH training and prediction. +[DeepH](https://doi.org/10.1038/s43588-022-00265-6) applies meaching learning to predict the +Hamiltonian in atomic basis representation. For such purpose, DeepH uses the Hamiltonian and overlap +matrices from DFT calculations. Here we introduce how to extract relevant information from ABACUS +for the purpose of DeepH training and prediction. -Detailed instructions on installing and running DeepH can be found on its official [website](https://deeph-pack.deepmodeling.com/en/latest/#deeph). An [example](https://deeph-pack.deepmodeling.com/en/latest/demo/demo3.html) for using DeepH with ABACUS is also provided. +Detailed instructions on installing and running DeepH can be found on its official +[website](https://deeph-pack.deepmodeling.com/en/latest/#deeph). An +[example](https://deeph-pack.deepmodeling.com/en/latest/demo/demo3.html) for using DeepH with ABACUS +is also provided. -Here I intend not to repeat information from the above sources, but to add some minor details related to the setting of ABACUS `INPUT` files. +Here I intend not to repeat information from the above sources, but to add some minor details +related to the setting of ABACUS `INPUT` files. > Note: Use the LCAO basis for DeepH-related calculations -As mentioned in the README.md file in the above-mentioned example, there are two stages where users need to run ABACUS calculations. +As mentioned in the README.md file in the above-mentioned example, there are two stages where users +need to run ABACUS calculations. -The first stage is during the data preparation phase, where we need to run a series of SCF calculations and output the Hamiltonian and overlap matrices. For such purpose, one needs to add the following line in the `INPUT` file: +The first stage is during the data preparation phase, where we need to run a series of SCF +calculations and output the Hamiltonian and overlap matrices. For such purpose, one needs to add the +following line in the `INPUT` file: ``` out_hsr 1 ``` -**For ABACUS v3.9.0.25+:** Files named `hrs1_nao.csr`, `hrs2_nao.csr` (for nspin=2), and `sr_nao.csr` will be generated in `OUT.${suffix}/` directory, containing the Hamiltonian and overlap matrices in standard CSR format. You can optionally specify precision: `out_hsr 1 8` (default 8 digits). The legacy spelling `out_mat_hs2` remains accepted. +**For ABACUS v3.9.0.25+:** Files named `hrs1_nao.csr`, `hrs2_nao.csr` (for nspin=2), and +`sr_nao.csr` will be generated in `OUT.${suffix}/` directory, containing the Hamiltonian and overlap +matrices in standard CSR format. You can optionally specify precision: `out_hsr 1 8` (default 8 +digits). The legacy spelling `out_mat_hs2` remains accepted. -**For ABACUS v3.8.x and earlier:** Files named `data-HR-sparse_SPIN${x}.csr` and `data-SR-sparse_SPIN${x}.csr` will be generated, where `${x}` takes value of 0 or 1 based on the spin component. +**For ABACUS v3.8.x and earlier:** Files named `data-HR-sparse_SPIN${x}.csr` and +`data-SR-sparse_SPIN${x}.csr` will be generated, where `${x}` takes value of 0 or 1 based on the +spin component. -> **Note:** DeepH v1.0.0+ is required to read the new CSR format from ABACUS v3.9.0.25+. For older DeepH versions, please use ABACUS v3.8.x or earlier. +> **Note:** DeepH v1.0.0+ is required to read the new CSR format from ABACUS v3.9.0.25+. For older +> DeepH versions, please use ABACUS v3.8.x or earlier. -More details on this keyword can be found in the [list of input keywords](../input_files/input-main.md#out_hsr). +More details on this keyword can be found in the +[list of input keywords](../input_files/input-main.md#out_hsr). -The second stage is during the inference phase. After DeepH training completes, we can apply the model to predict the Hamiltonian on other systems. For that purpose, we also need the overlap matrices from the new systems, but no SCF calculation is required. +The second stage is during the inference phase. After DeepH training completes, we can apply the +model to predict the Hamiltonian on other systems. For that purpose, we also need the overlap +matrices from the new systems, but no SCF calculation is required. -For that purpose, in `INPUT` file we need to make the following specification of the keyword `calculation`: +For that purpose, in `INPUT` file we need to make the following specification of the keyword +`calculation`: ``` calculation get_S diff --git a/docs/advanced/interface/deepks.md b/docs/advanced/interface/deepks.md index 3fb2cb5b4ce..e271aad8d27 100644 --- a/docs/advanced/interface/deepks.md +++ b/docs/advanced/interface/deepks.md @@ -1,14 +1,26 @@ # DeePKS -[DeePKS](https://pubs.acs.org/doi/10.1021/acs.jctc.0c00872) is a machine-learning (ML) aided density funcitonal model that fits the energy difference between highly accurate but computationally demanding method and effcient but less accurate method via neural-network. Common high-precision methods include hybrid functionals or CCSD-T, while common low-precision methods are LDA/GGA. - -As such, the trained DeePKS model can provide highly accurate energetics (and forces/band gap/density) with relatively low computational cost, and can therefore act as a bridge to connect expensive quantum mechanic data and machine-learning-based potentials. -While the original framework of DeePKS is for molecular systems, please refer to this [J. Phys. Chem. A 126.49 (2022): 9154-9164](https://pubs.acs.org/doi/abs/10.1021/acs.jpca.2c05000) for the application of DeePKS in periodic systems. - -Detailed instructions on installing and running DeePKS can be found on this [website](https://deepks-kit.readthedocs.io/en/latest/index.html). The DeePKS-related keywords in `INPUT` file can be found [here](http://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#deepks). An [example](https://github.com/deepmodeling/deepks-kit/tree/abacus/examples/water_single_lda2pbe_abacus) for training DeePKS model with ABACUS is also provided. For practical applications, users can refer to a series of [Notebooks](https://bohrium.dp.tech/collections/1921409690). These Notebooks provide detailed instructions on how to train and use the DeePKS model using perovskite as an example. Currently, these tutorials are available in Chinese, but we plan to release corresponding English versions in the near future. - - +[DeePKS](https://pubs.acs.org/doi/10.1021/acs.jctc.0c00872) is a machine-learning (ML) aided density +funcitonal model that fits the energy difference between highly accurate but computationally +demanding method and effcient but less accurate method via neural-network. Common high-precision +methods include hybrid functionals or CCSD-T, while common low-precision methods are LDA/GGA. + +As such, the trained DeePKS model can provide highly accurate energetics (and forces/band +gap/density) with relatively low computational cost, and can therefore act as a bridge to connect +expensive quantum mechanic data and machine-learning-based potentials. While the original framework +of DeePKS is for molecular systems, please refer to this +[J. Phys. Chem. A 126.49 (2022): 9154-9164](https://pubs.acs.org/doi/abs/10.1021/acs.jpca.2c05000) +for the application of DeePKS in periodic systems. + +Detailed instructions on installing and running DeePKS can be found on this +[website](https://deepks-kit.readthedocs.io/en/latest/index.html). The DeePKS-related keywords in +`INPUT` file can be found +[here](http://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#deepks). An +[example](https://github.com/deepmodeling/deepks-kit/tree/abacus/examples/water_single_lda2pbe_abacus) +for training DeePKS model with ABACUS is also provided. For practical applications, users can refer +to a series of [Notebooks](https://bohrium.dp.tech/collections/1921409690). These Notebooks provide +detailed instructions on how to train and use the DeePKS model using perovskite as an example. +Currently, these tutorials are available in Chinese, but we plan to release corresponding English +versions in the near future. > Note: DeePKS calculations can only be performed by the LCAO basis. - - diff --git a/docs/advanced/interface/deeptb.md b/docs/advanced/interface/deeptb.md index 13cdf406dc2..6a004d57154 100644 --- a/docs/advanced/interface/deeptb.md +++ b/docs/advanced/interface/deeptb.md @@ -1,5 +1,17 @@ # DeePTB -[DeePTB](https://github.com/deepmodeling/DeePTB) is an innovative Python package that uses deep learning to accelerate ab initio electronic structure simulations. It offers versatile, accurate, and efficient simulations for a wide range of materials and phenomena. Trained on small systems, DeePTB can predict electronic structures of large systems, handle structural perturbations, and integrate with molecular dynamics for finite temperature simulations, providing comprehensive insights into atomic and electronic behavior. See more details in [DeePTB-SK: Nat Commun 15, 6772 (2024)](https://www.nature.com/articles/s41467-024-51006-4) and [DeePTB-E3: arXiv:2407.06053](https://arxiv.org/pdf/2407.06053). +[DeePTB](https://github.com/deepmodeling/DeePTB) is an innovative Python package that uses deep +learning to accelerate ab initio electronic structure simulations. It offers versatile, accurate, +and efficient simulations for a wide range of materials and phenomena. Trained on small systems, +DeePTB can predict electronic structures of large systems, handle structural perturbations, and +integrate with molecular dynamics for finite temperature simulations, providing comprehensive +insights into atomic and electronic behavior. See more details in +[DeePTB-SK: Nat Commun 15, 6772 (2024)](https://www.nature.com/articles/s41467-024-51006-4) and +[DeePTB-E3: arXiv:2407.06053](https://arxiv.org/pdf/2407.06053). -DeePTB trains the model based on the Structure, Eigenvalues, Hamiltonian, Density matrix, and Overlap matrix from first-principles calcualtions. DeePTB team provides the interfaces [dftio](https://github.com/deepmodeling/dftio) with other first-principles softwares. [dftio](https://github.com/deepmodeling/dftio) fully supports the interfaces with ABACUS, and can transfer the Structure, Eigenvalues, Hamiltonian, Density matrix, and Overlap matrix from ABACUS into the format used in [DeePTB](https://github.com/deepmodeling/DeePTB). +DeePTB trains the model based on the Structure, Eigenvalues, Hamiltonian, Density matrix, and +Overlap matrix from first-principles calcualtions. DeePTB team provides the interfaces +[dftio](https://github.com/deepmodeling/dftio) with other first-principles softwares. +[dftio](https://github.com/deepmodeling/dftio) fully supports the interfaces with ABACUS, and can +transfer the Structure, Eigenvalues, Hamiltonian, Density matrix, and Overlap matrix from ABACUS +into the format used in [DeePTB](https://github.com/deepmodeling/DeePTB). diff --git a/docs/advanced/interface/dpgen.md b/docs/advanced/interface/dpgen.md index 9d1d926bf25..ab4687fb634 100644 --- a/docs/advanced/interface/dpgen.md +++ b/docs/advanced/interface/dpgen.md @@ -1,17 +1,24 @@ # DP-GEN - -[DP-GEN](https://github.com/deepmodeling/dpgen), the deep potential generator, is a package designed to generate deep learning based model of interatomic potential energy and force fields (Yuzhi Zhang, Haidi Wang, Weijie Chen, Jinzhe Zeng, Linfeng Zhang, Han Wang, and Weinan E, DP-GEN: A concurrent learning platform for the generation of reliable deep learning based potential energy models, Computer Physics Communications, 2020, 107206). ABACUS can now interface with DP-GEN to generate deep potentials and perform autotests. The minimum recommended version is ABACUS 3.0, dpdata 0.2.8, and dpgen 0.10.7 . In the following part, we take the FCC aluminum as an example. +[DP-GEN](https://github.com/deepmodeling/dpgen), the deep potential generator, is a package designed +to generate deep learning based model of interatomic potential energy and force fields (Yuzhi Zhang, +Haidi Wang, Weijie Chen, Jinzhe Zeng, Linfeng Zhang, Han Wang, and Weinan E, DP-GEN: A concurrent +learning platform for the generation of reliable deep learning based potential energy models, +Computer Physics Communications, 2020, 107206). ABACUS can now interface with DP-GEN to generate +deep potentials and perform autotests. The minimum recommended version is ABACUS 3.0, dpdata 0.2.8, +and dpgen 0.10.7 . In the following part, we take the FCC aluminum as an example. ## init_bulk and run This example can be found in examples/dpgen-example/init_and_run directory. -Firstly, one needs to prepare input files for ABACUS calculation, e.g., โ€œINPUTโ€, "INPUT.md", "KPT", "Al.STRU", "Al_ONCV_PBE-1.0.upf", which are the main input file containing input tags, k-point mesh, crystal structure and pseudoptential, respectively. "INPUT" is for scf calculation, and "INPUT.md" is for AIMD (ab-initio molecular dynamic) calculation. +Firstly, one needs to prepare input files for ABACUS calculation, e.g., โ€œINPUTโ€, "INPUT.md", "KPT", +"Al.STRU", "Al_ONCV_PBE-1.0.upf", which are the main input file containing input tags, k-point mesh, +crystal structure and pseudoptential, respectively. "INPUT" is for scf calculation, and "INPUT.md" +is for AIMD (ab-initio molecular dynamic) calculation. Secondly, for the "dpgen init_bulk" step, an `init.json` file should be provided: - ```json { "init_fp_style": "ABACUS", @@ -38,6 +45,7 @@ Secondly, for the "dpgen init_bulk" step, an `init.json` file should be provided ``` Next, for the "dpgen run" step, the following `run_param.json` should be provided. + ```json { "type_map": [ @@ -194,9 +202,12 @@ Next, for the "dpgen run" step, the following `run_param.json` should be provide This example can be found in examples/dpgen-example/autotest directory. -`dpgen autotest` supports to perform `relaxation`,`eos` (equation of state),`elastic`,`surface`,`vacancy`, and `interstitial` calculations with ABACUS. A `property.json` and `machine.json` file need to be provided. For example, +`dpgen autotest` supports to perform `relaxation`,`eos` (equation of +state),`elastic`,`surface`,`vacancy`, and `interstitial` calculations with ABACUS. A `property.json` +and `machine.json` file need to be provided. For example, `property.json`: + ```json { @@ -370,8 +381,10 @@ This example can be found in examples/dpgen-example/autotest directory. ``` -For each property, the command `dpgen autotest make property.json` will generate the input files, `dpgen autotest run property.json machine.json` will run the corresponding tasks, and `dpgen autotest post property.json` will collect the final results. +For each property, the command `dpgen autotest make property.json` will generate the input files, +`dpgen autotest run property.json machine.json` will run the corresponding tasks, and +`dpgen autotest post property.json` will collect the final results. Notes: -- The ABACUS-DPGEN interface can be used in both pw and lcao basis. +- The ABACUS-DPGEN interface can be used in both pw and lcao basis. diff --git a/docs/advanced/interface/migration-guide-csr-format.md b/docs/advanced/interface/migration-guide-csr-format.md index 0703ed22980..ad0010719fa 100644 --- a/docs/advanced/interface/migration-guide-csr-format.md +++ b/docs/advanced/interface/migration-guide-csr-format.md @@ -1,10 +1,13 @@ -# Migration Guide: New CSR Format for H\(R\) and S\(R\) Matrices +# Migration Guide: New CSR Format for H(R) and S(R) Matrices ## Overview -Starting from ABACUS v3.9.0.25, the output format for Hamiltonian H\(R\) and overlap S\(R\) matrices has been unified to use standard CSR (Compressed Sparse Row) format, matching the format used by `out_dmr` for density matrices. +Starting from ABACUS v3.9.0.25, the output format for Hamiltonian H(R) and overlap S(R) matrices has +been unified to use standard CSR (Compressed Sparse Row) format, matching the format used by +`out_dmr` for density matrices. + +This change affects downstream tools that read H(R) and S(R) matrices, including: -This change affects downstream tools that read H\(R\) and S\(R\) matrices, including: - TB2J (magnetic exchange parameters) - DeepH (machine learning Hamiltonian) - pyATB (tight-binding analysis) @@ -15,6 +18,7 @@ This change affects downstream tools that read H\(R\) and S\(R\) matrices, inclu ### File Names **Old format (ABACUS โ‰ค v3.8.x):** + ``` OUT.${suffix}/data-HR-sparse_SPIN0.csr OUT.${suffix}/data-HR-sparse_SPIN1.csr (nspin=2 only) @@ -22,6 +26,7 @@ OUT.${suffix}/data-SR-sparse_SPIN0.csr ``` **New format (ABACUS โ‰ฅ v3.9.0.25):** + ``` OUT.${suffix}/hrs1_nao.csr OUT.${suffix}/hrs2_nao.csr (nspin=2 only) @@ -33,6 +38,7 @@ OUT.${suffix}/sr_nao.csr Both old and new formats use CSR structure, but with different headers and metadata. #### Old Format Header + ``` STEP: 0 Matrix Dimension of H(R): 26 @@ -42,6 +48,7 @@ Matrix number of H(R): 183 ``` #### New Format Header + ``` --- Ionic Step 1 --- # print H matrix in real space H(R) @@ -81,11 +88,14 @@ Matrix number of H(R): 183 ### Key Differences -1. **UnitCell Information**: New format includes complete unit cell information (lattice vectors, atomic positions) -2. **Header Format**: New format uses descriptive comments with `#` prefix -3. **Section Labels**: New format explicitly labels CSR sections ("# CSR values", "# CSR column indices", "# CSR row pointers") -4. **Ionic Step**: New format uses "Ionic Step N" instead of "STEP: N" -5. **Precision Control**: New format supports optional precision parameter: `out_hsr 1 12` (default 8) +1. **UnitCell Information**: New format includes complete unit cell information (lattice vectors, + atomic positions) +1. **Header Format**: New format uses descriptive comments with `#` prefix +1. **Section Labels**: New format explicitly labels CSR sections ("# CSR values", "# CSR column + indices", "# CSR row pointers") +1. **Ionic Step**: New format uses "Ionic Step N" instead of "STEP: N" +1. **Precision Control**: New format supports optional precision parameter: `out_hsr 1 12` (default + 8\) ## Migration Steps for Tool Developers @@ -251,11 +261,13 @@ def read_hamiltonian(filename): **Required version:** TB2J v0.9.0+ **Changes needed:** + - Update file name detection to look for `hrs*_nao.csr` and `srs*_nao.csr` - Update parser to handle new header format with UnitCell information - Update parser to skip comment lines starting with `#` **Example:** + ```python # In abacus2J.py or relevant parser def find_hr_files(path, suffix): @@ -282,6 +294,7 @@ def find_hr_files(path, suffix): **Required version:** DeepH v1.0.0+ **Changes needed:** + - Update `parse_abacus.py` to handle new file names - Update CSR parser to skip UnitCell section - Update parser to handle comment lines with `#` prefix @@ -289,6 +302,7 @@ def find_hr_files(path, suffix): ### pyATB **Changes needed:** + - Update file I/O module to detect and parse new format - Add format version detection - Maintain backward compatibility with old format @@ -309,7 +323,8 @@ abacus_new > log_new ### 2. Verify Numerical Equivalence -The CSR data (values, indices, pointers) should be numerically identical between old and new formats, only the header differs. +The CSR data (values, indices, pointers) should be numerically identical between old and new +formats, only the header differs. ```python def compare_csr_data(old_file, new_file): @@ -352,17 +367,20 @@ This affects the output format of floating-point values in the CSR data. ## Support and Resources - **ABACUS Documentation:** [https://abacus.deepmodeling.com/](https://abacus.deepmodeling.com/) -- **GitHub Issues:** [https://github.com/deepmodeling/abacus-develop/issues](https://github.com/deepmodeling/abacus-develop/issues) +- **GitHub Issues:** + [https://github.com/deepmodeling/abacus-develop/issues](https://github.com/deepmodeling/abacus-develop/issues) - **Design Document:** `docs/plans/2026-02-28-unify-out-mat-hs2-design.md` - **Implementation Plan:** `docs/plans/2026-02-28-unify-out-mat-hs2-plan.md` ## Summary The new CSR format provides: + - โœ… Unified interface with `out_dmr` output - โœ… Complete UnitCell information in output files - โœ… Precision control for output values - โœ… Better documentation with inline comments - โœ… Clearer section labels for easier parsing -Tool developers should update their parsers to support the new format while maintaining backward compatibility with the old format for users running older ABACUS versions. +Tool developers should update their parsers to support the new format while maintaining backward +compatibility with the old format for users running older ABACUS versions. diff --git a/docs/advanced/interface/phonopy.md b/docs/advanced/interface/phonopy.md index f514ec5ab41..ef2bc410415 100644 --- a/docs/advanced/interface/phonopy.md +++ b/docs/advanced/interface/phonopy.md @@ -1,14 +1,18 @@ # Phonopy -[Phonopy](https://phonopy.github.io/phonopy) is a powerful package to calculate phonon and related properties. The ABACUS interface has been added in Phonopy v.2.19.1. In the following, we take the FCC aluminum as an example: +[Phonopy](https://phonopy.github.io/phonopy) is a powerful package to calculate phonon and related +properties. The ABACUS interface has been added in Phonopy v.2.19.1. In the following, we take the +FCC aluminum as an example: -1. To obtain supercells ($2\times 2\times 2$) with displacements, run phonopy: +1. To obtain supercells ($2\\times 2\\times 2$) with displacements, run phonopy: ``` phonopy -d --dim="2 2 2" --abacus ``` -2. Calculate forces on atoms in the supercells with displacements. For each SCF calculation, you should specify `stru_file` with `STRU-{number}` and `cal_force=1` in INPUT in order to calculate force using ABACUS. Be careful not to relax the structures +2. Calculate forces on atoms in the supercells with displacements. For each SCF calculation, you + should specify `stru_file` with `STRU-{number}` and `cal_force=1` in INPUT in order to calculate + force using ABACUS. Be careful not to relax the structures ``` echo 'stru_file ./STRU-001' >> INPUT diff --git a/docs/advanced/interface/pyabacus.md b/docs/advanced/interface/pyabacus.md index 36d06fe9ea4..0420c6a33fd 100644 --- a/docs/advanced/interface/pyabacus.md +++ b/docs/advanced/interface/pyabacus.md @@ -1,6 +1,7 @@ # PyABACUS -PyABACUS is the official Python interface for ABACUS, providing a convenient way to run DFT calculations directly from Python scripts. +PyABACUS is the official Python interface for ABACUS, providing a convenient way to run DFT +calculations directly from Python scripts. ## Installation @@ -13,7 +14,8 @@ pip install -e . ### With C++ Driver Support -For full functionality including direct library calls (faster than subprocess), build ABACUS with Python bindings: +For full functionality including direct library calls (faster than subprocess), build ABACUS with +Python bindings: ```bash cmake -B build -DENABLE_PYABACUS=ON -DENABLE_LCAO=ON @@ -21,7 +23,8 @@ cmake --build build -j8 pip install -e python/pyabacus ``` -**Note:** The `pyabacus` package on PyPI is a different project and is NOT related to ABACUS. Please install from source as shown above. +**Note:** The `pyabacus` package on PyPI is a different project and is NOT related to ABACUS. Please +install from source as shown above. ## Quick Start @@ -70,6 +73,7 @@ result = pyabacus.abacus( ``` This is equivalent to running: + ```bash OMP_NUM_THREADS=2 mpirun -np 4 abacus ``` @@ -107,20 +111,20 @@ def abacus( **Parameters:** -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `input_dir` | str | `"."` | Directory containing INPUT, STRU, KPT files | -| `input_file` | str | None | Explicit path to INPUT file | -| `stru_file` | str | None | Explicit path to STRU file | -| `kpt_file` | str | None | Explicit path to KPT file | -| `pseudo_dir` | str | None | Directory containing pseudopotentials | -| `orbital_dir` | str | None | Directory containing orbital files (LCAO) | -| `output_dir` | str | `"OUT.PYABACUS"` | Directory for output files | -| `calculate_force` | bool | True | Whether to calculate forces | -| `calculate_stress` | bool | False | Whether to calculate stress tensor | -| `verbosity` | int | 1 | Output level (0=silent, 1=normal, 2=verbose) | -| `nprocs` | int | 1 | Number of MPI processes | -| `nthreads` | int | 1 | Number of OpenMP threads | +| Parameter | Type | Default | Description | +| ------------------ | ---- | ---------------- | -------------------------------------------- | +| `input_dir` | str | `"."` | Directory containing INPUT, STRU, KPT files | +| `input_file` | str | None | Explicit path to INPUT file | +| `stru_file` | str | None | Explicit path to STRU file | +| `kpt_file` | str | None | Explicit path to KPT file | +| `pseudo_dir` | str | None | Directory containing pseudopotentials | +| `orbital_dir` | str | None | Directory containing orbital files (LCAO) | +| `output_dir` | str | `"OUT.PYABACUS"` | Directory for output files | +| `calculate_force` | bool | True | Whether to calculate forces | +| `calculate_stress` | bool | False | Whether to calculate stress tensor | +| `verbosity` | int | 1 | Output level (0=silent, 1=normal, 2=verbose) | +| `nprocs` | int | 1 | Number of MPI processes | +| `nthreads` | int | 1 | Number of OpenMP threads | **Returns:** `CalculationResult` object @@ -130,37 +134,37 @@ Container for calculation results. **Attributes:** -| Attribute | Type | Description | -|-----------|------|-------------| -| `converged` | bool | Whether SCF converged | -| `niter` | int | Number of SCF iterations | -| `drho` | float | Final charge density difference | -| `etot` | float | Total energy (Ry) | -| `etot_ev` | float | Total energy (eV) | -| `forces` | ndarray | Forces on atoms (nat, 3) in Ry/Bohr | -| `forces_ev_ang` | ndarray | Forces in eV/Angstrom | -| `stress` | ndarray | Stress tensor (3, 3) in kbar | -| `fermi_energy` | float | Fermi energy (eV) | -| `bandgap` | float | Band gap (eV) | -| `nat` | int | Number of atoms | -| `ntype` | int | Number of atom types | -| `nbands` | int | Number of bands | -| `nks` | int | Number of k-points | -| `output_dir` | str | Path to output directory (OUT.$suffix) | -| `log_file` | str | Path to the main log file | -| `output_files` | dict | Dictionary of output files (filename -> path) | +| Attribute | Type | Description | +| --------------- | ------- | --------------------------------------------- | +| `converged` | bool | Whether SCF converged | +| `niter` | int | Number of SCF iterations | +| `drho` | float | Final charge density difference | +| `etot` | float | Total energy (Ry) | +| `etot_ev` | float | Total energy (eV) | +| `forces` | ndarray | Forces on atoms (nat, 3) in Ry/Bohr | +| `forces_ev_ang` | ndarray | Forces in eV/Angstrom | +| `stress` | ndarray | Stress tensor (3, 3) in kbar | +| `fermi_energy` | float | Fermi energy (eV) | +| `bandgap` | float | Band gap (eV) | +| `nat` | int | Number of atoms | +| `ntype` | int | Number of atom types | +| `nbands` | int | Number of bands | +| `nks` | int | Number of k-points | +| `output_dir` | str | Path to output directory (OUT.$suffix) | +| `log_file` | str | Path to the main log file | +| `output_files` | dict | Dictionary of output files (filename -> path) | **Methods:** -| Method | Description | -|--------|-------------| -| `summary()` | Return a formatted summary string | -| `energies` | Dictionary of all energy components | -| `has_forces` | Whether forces are available | -| `has_stress` | Whether stress is available | -| `has_output_dir` | Whether output directory exists | +| Method | Description | +| ----------------------- | ------------------------------------- | +| `summary()` | Return a formatted summary string | +| `energies` | Dictionary of all energy components | +| `has_forces` | Whether forces are available | +| `has_stress` | Whether stress is available | +| `has_output_dir` | Whether output directory exists | | `get_output_file(name)` | Get full path to specific output file | -| `list_output_files()` | List all output file names | +| `list_output_files()` | List all output file names | ## Output File Tracking @@ -188,16 +192,16 @@ if bands_file: ### Common Output Files -| File | Description | -|------|-------------| -| `running_scf.log` | Main calculation log | -| `BANDS_1.dat` | Band structure data | -| `pdoss1_*.txt` | Projected density of states (one file per spin channel) | -| `chg.cube` | Charge density in cube format | -| `chgs1.cube` | Spin-up charge density | -| `chgs2.cube` | Spin-down charge density | -| `istate.info` | Band eigenvalues and occupations | -| `kpoints` | K-point information | +| File | Description | +| ----------------- | ------------------------------------------------------- | +| `running_scf.log` | Main calculation log | +| `BANDS_1.dat` | Band structure data | +| `pdoss1_*.txt` | Projected density of states (one file per spin channel) | +| `chg.cube` | Charge density in cube format | +| `chgs1.cube` | Spin-up charge density | +| `chgs2.cube` | Spin-down charge density | +| `istate.info` | Band eigenvalues and occupations | +| `kpoints` | K-point information | ## Convenience Functions @@ -277,25 +281,29 @@ for system, data in results.items(): ### ABACUS executable not found If you see "ABACUS executable not found", ensure: + 1. ABACUS is installed and in your PATH -2. Or build with C++ driver support (see Installation) +1. Or build with C++ driver support (see Installation) ### MPI not found If you see "mpirun/mpiexec not found" when using `nprocs > 1`: + 1. Install MPI (OpenMPI or MPICH) -2. Ensure `mpirun` or `mpiexec` is in your PATH -3. Or set `nprocs=1` to run without MPI +1. Ensure `mpirun` or `mpiexec` is in your PATH +1. Or set `nprocs=1` to run without MPI ### Import errors If `import pyabacus` fails: + 1. Ensure pyabacus is installed: `pip install pyabacus` -2. Check Python version compatibility (Python 3.8+) +1. Check Python version compatibility (Python 3.8+) ### Calculation not converging Check the log file for details: + ```python result = pyabacus.abacus("./problem_case/") if not result.converged: @@ -308,6 +316,7 @@ if not result.converged: ### Forces or stress not available Forces and stress are parsed from the ABACUS output log. Ensure: + 1. `cal_force` is set in your INPUT file for forces -2. `cal_stress` is set in your INPUT file for stress -3. The calculation completed successfully +1. `cal_stress` is set in your INPUT file for stress +1. The calculation completed successfully diff --git a/docs/advanced/interface/pyatb.md b/docs/advanced/interface/pyatb.md index 31b0cd68cff..845e891966b 100644 --- a/docs/advanced/interface/pyatb.md +++ b/docs/advanced/interface/pyatb.md @@ -2,7 +2,12 @@ ## Introduction -[PYATB](https://github.com/pyatb/pyatb) (Python ab initio tight binding simulation package) is an open-source software package designed for computing electronic structures and related properties based on the ab initio tight binding Hamiltonian. The Hamiltonian can be directly obtained after conducting self-consistent calculations with ABACUS using numerical atomic orbital (NAO) bases. The package comprises three modules - Bands, Geometric, and Optical, each providing a comprehensive set of tools for analyzing different aspects of a material's electronic structure. +[PYATB](https://github.com/pyatb/pyatb) (Python ab initio tight binding simulation package) is an +open-source software package designed for computing electronic structures and related properties +based on the ab initio tight binding Hamiltonian. The Hamiltonian can be directly obtained after +conducting self-consistent calculations with ABACUS using numerical atomic orbital (NAO) bases. The +package comprises three modules - Bands, Geometric, and Optical, each providing a comprehensive set +of tools for analyzing different aspects of a material's electronic structure. ## Installation @@ -12,13 +17,18 @@ cd pyatb python setup.py install --record log ``` -To customize the `setup.py` file, you must make changes to the **CXX** and **LAPACK_DIR** variables in line with your environment. **CXX** denotes the C++ compiler you intend to use, for instance, icpc (note that it should not be the mpi version). Furthermore, **LAPACK_DIR** is used to specify the Intel MKL path. +To customize the `setup.py` file, you must make changes to the **CXX** and **LAPACK_DIR** variables +in line with your environment. **CXX** denotes the C++ compiler you intend to use, for instance, +icpc (note that it should not be the mpi version). Furthermore, **LAPACK_DIR** is used to specify +the Intel MKL path. -After completing the installation process, you can access the `pyatb` executable and corresponding module, which can be imported using the `import pyatb` command. +After completing the installation process, you can access the `pyatb` executable and corresponding +module, which can be imported using the `import pyatb` command. ## How to use -We take Bi$_2$Se$_3$ as an example to illustrate how to use ABACUS to generate the tight binding Hamiltonian required for PYATB, and then perform calculations related to PYATB functions. +We take Bi$\_2$Se$\_3$ as an example to illustrate how to use ABACUS to generate the tight binding +Hamiltonian required for PYATB, and then perform calculations related to PYATB functions. 1. Perform ABACUS self consistent calculation: @@ -55,9 +65,15 @@ out_hsr 1 out_mat_r 1 ``` -After the key parameters `out_hsr` and `out_mat_r` are turned on, ABACUS will generate files containing the Hamiltonian matrix $H(R)$, overlap matrix $S(R)$, and dipole matrix $r(R)$ after completing the self-consistent calculation. These parameters can be found in the ABACUS `INPUT` file. +After the key parameters `out_hsr` and `out_mat_r` are turned on, ABACUS will generate files +containing the Hamiltonian matrix $H(R)$, overlap matrix $S(R)$, and dipole matrix $r(R)$ after +completing the self-consistent calculation. These parameters can be found in the ABACUS `INPUT` +file. -2. Copy the HR, SR, and rR files output by ABACUS's self-consistent calculation, which are located in the `OUT*` directory and named `data-HR-sparse_SPIN0.csr`, `data-SR-sparse_SPIN0.csr`, and `data-rR-sparse.csr`, respectively. Copy these files to the working directory and write the `Input` file for PYATB: +2. Copy the HR, SR, and rR files output by ABACUS's self-consistent calculation, which are located + in the `OUT*` directory and named `data-HR-sparse_SPIN0.csr`, `data-SR-sparse_SPIN0.csr`, and + `data-rR-sparse.csr`, respectively. Copy these files to the working directory and write the + `Input` file for PYATB: ``` INPUT_PARAMETERS @@ -107,4 +123,5 @@ export OMP_NUM_THREADS=2 mpirun -np 6 pyatb ``` -After the calculation is completed, the band structure data and figures of Bi$_2$Se$_3$ can be found in the `Out/Band_Structure` folder. +After the calculation is completed, the band structure data and figures of Bi$\_2$Se$\_3$ can be +found in the `Out/Band_Structure` folder. diff --git a/docs/advanced/json/json_add.md b/docs/advanced/json/json_add.md index 2ec0ee9d2c5..cd5751d96b8 100644 --- a/docs/advanced/json/json_add.md +++ b/docs/advanced/json/json_add.md @@ -2,9 +2,12 @@ ## Overview -ABACUS uses [nlohmann-json](https://github.com/nlohmann/json) for its optional JSON output. The implementation lives in `source/source_io/module_json` and uses `Json::jsonValue`, an alias for `nlohmann::ordered_json`, to retain object-key insertion order. +ABACUS uses [nlohmann-json](https://github.com/nlohmann/json) for its optional JSON output. The +implementation lives in `source/source_io/module_json` and uses `Json::jsonValue`, an alias for +`nlohmann::ordered_json`, to retain object-key insertion order. -`AbacusJson` provides access to the shared document and writes it to a file. Its declarations are in namespace `Json`: +`AbacusJson` provides access to the shared document and writes it to a file. Its declarations are in +namespace `Json`: ```cpp using jsonValue = nlohmann::ordered_json; @@ -20,11 +23,19 @@ class AbacusJson }; ``` -Keep the document root an object. Its state remains shared within each process; this change does not introduce independent output contexts or make concurrent writes safe. The mutable accessor is for the schema generators and tests in `module_json`. Other modules should continue to pass data to functions such as `add_output_energy()` instead of directly editing the document. +Keep the document root an object. Its state remains shared within each process; this change does not +introduce independent output contexts or make concurrent writes safe. The mutable accessor is for +the schema generators and tests in `module_json`. Other modules should continue to pass data to +functions such as `add_output_energy()` instead of directly editing the document. -The old path-component type and generic set/append interface have been removed. Use native object assignment, shallow `update()`, and array `push_back()` inside the schema generators; do not introduce another generic path wrapper. +The old path-component type and generic set/append interface have been removed. Use native object +assignment, shallow `update()`, and array `push_back()` inside the schema generators; do not +introduce another generic path wrapper. -`abacusjson.h` includes only `nlohmann/json_fwd.hpp`. Source files that construct or manipulate JSON values must include `nlohmann/json.hpp` under `__JSON`. The existing CMake option `ENABLE_JSON` controls this feature. Callers using only the higher-level declarations in `init_info.h` or `output_info.h` do not need the backend header. +`abacusjson.h` includes only `nlohmann/json_fwd.hpp`. Source files that construct or manipulate JSON +values must include `nlohmann/json.hpp` under `__JSON`. The existing CMake option `ENABLE_JSON` +controls this feature. Callers using only the higher-level declarations in `init_info.h` or +`output_info.h` do not need the backend header. ## Constructing metadata @@ -45,14 +56,19 @@ AbacusJson::document()["general_info"] = { {"end_time", end_time_str}}; ``` -The `init` section is shared by `gen_stru()`, `gen_init()`, and `add_nkstot()`. The first two construct the fields they own in a local object, then apply a **shallow** update: +The `init` section is shared by `gen_stru()`, `gen_init()`, and `add_nkstot()`. The first two +construct the fields they own in a local object, then apply a **shallow** update: ```cpp // Inside init_info.cpp; init_section() is local to this source file. init_section().update(info); ``` -The local helper creates a missing `init` object but rejects an existing non-object, including `null`. The update preserves fields supplied by the other generators and replaces each supplied value as a whole. In particular, per-species maps and coordinate arrays must not retain stale entries or accumulate on repeated generation. Do not assign a newly generated object to the entire `init` section, and do not enable recursive object merging here. +The local helper creates a missing `init` object but rejects an existing non-object, including +`null`. The update preserves fields supplied by the other generators and replaces each supplied +value as a whole. In particular, per-species maps and coordinate arrays must not retain stale +entries or accumulate on repeated generation. Do not assign a newly generated object to the entire +`init` section, and do not enable recursive object merging here. `add_nkstot()` only sets its own field: @@ -62,20 +78,26 @@ init_section()["nkstot"] = nkstot; ## Output-record lifecycle -The workflow starts each record with `init_output_array_obj()` **before** the corresponding solver writes SCF or other result data. That function alone creates the `output` array and appends the initial record. It rejects an existing `output` value that is not an array; an explicit `null` is not treated as a missing field. +The workflow starts each record with `init_output_array_obj()` **before** the corresponding solver +writes SCF or other result data. That function alone creates the `output` array and appends the +initial record. It rejects an existing `output` value that is not an array; an explicit `null` is +not treated as a missing field. The existing workflow entry points own this initialization: -| Workflow | Record initialization | -| --- | --- | -| SCF/relaxation | `Relax_Driver::iter_info()` starts the record, except for the first `ks-lr` step described below. | -| `ks-lr` | `ESolver_LR::before_all_runners()` starts the record before its embedded KS calculation; the first relaxation-driver step reuses it. | -| UnitCell-backed MD | `Run_MD::md_line()` starts a record at the beginning of each MD iteration when `mdcell.has_backing_unitcell()` is true. | -| Socket/i-PI | `SocketHandlers::handle_posdata()` starts a record before running the solver for the received `POSDATA` frame. | +| Workflow | Record initialization | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | +| SCF/relaxation | `Relax_Driver::iter_info()` starts the record, except for the first `ks-lr` step described below. | +| `ks-lr` | `ESolver_LR::before_all_runners()` starts the record before its embedded KS calculation; the first relaxation-driver step reuses it. | +| UnitCell-backed MD | `Run_MD::md_line()` starts a record at the beginning of each MD iteration when `mdcell.has_backing_unitcell()` is true. | +| Socket/i-PI | `SocketHandlers::handle_posdata()` starts a record before running the solver for the received `POSDATA` frame. | -Do not move record creation into individual field writers, create a second record for the same step, or reset the whole document to start a new step. +Do not move record creation into individual field writers, create a second record for the same step, +or reset the whole document to start a new step. -The result writers use `current_output()`, a helper local to `output_info.cpp`. It rejects a missing or non-array `output`, an empty array, or a final element that is not an object. It never creates a record as a side effect of writing a result. +The result writers use `current_output()`, a helper local to `output_info.cpp`. It rejects a missing +or non-array `output`, an empty array, or a final element that is not an object. It never creates a +record as a side effect of writing a result. For example, inside namespace `Json` in `output_info.cpp`: @@ -86,9 +108,13 @@ void add_output_energy(const double energy) } ``` -Coordinate, force, stress, magnetic-moment, and cell arrays are built locally and assigned as complete arrays. Repeatedly updating the same record must replace these arrays rather than append rows. +Coordinate, force, stress, magnetic-moment, and cell arrays are built locally and assigned as +complete arrays. Repeatedly updating the same record must replace these arrays rather than append +rows. -SCF iterations are different: they form a history and must be appended. `add_output_scf_mag()` creates a missing `scf` array, rejects an existing non-array history, and appends one iteration object. Its implementation uses: +SCF iterations are different: they form a history and must be appended. `add_output_scf_mag()` +creates a missing `scf` array, rejects an existing non-array history, and appends one iteration +object. Its implementation uses: ```cpp jsonValue& output = current_output(); @@ -103,15 +129,27 @@ scf.push_back({{"energy", energy}, {"ediff", ediff}, {"drho", drho}, {"time", time}}); ``` -`ordered_json` may invalidate references to child values when new members are inserted into their parent object. Acquire the `scf` reference after inserting `total_mag` and `absolute_mag`, and do not retain a record reference across appending another `output` record. The same caution applies to references to root sections when new root keys are inserted. +`ordered_json` may invalidate references to child values when new members are inserted into their +parent object. Acquire the `scf` reference after inserting `total_mag` and `absolute_mag`, and do +not retain a record reference across appending another `output` record. The same caution applies to +references to root sections when new root keys are inserted. ## Serialization and tests -`document()` and `write_to_json()` do not perform MPI rank filtering. The existing `json_output()` wrapper writes `abacus.json` only on rank 0 in MPI builds; callers outside `module_json` should retain the existing integration wrappers. +`document()` and `write_to_json()` do not perform MPI rank filtering. The existing `json_output()` +wrapper writes `abacus.json` only on rank 0 in MPI builds; callers outside `module_json` should +retain the existing integration wrappers. -`write_to_json()` preserves the existing four-space formatting and reports file-open and write/close failures. It serializes the document before opening the destination, so a serialization error does not first truncate the file. Non-finite numbers serialize as JSON `null`; decimal versus scientific float notation is not part of the schema contract. +`write_to_json()` preserves the existing four-space formatting and reports file-open and write/close +failures. It serializes the document before opening the destination, so a serialization error does +not first truncate the file. Non-finite numbers serialize as JSON `null`; decimal versus scientific +float notation is not part of the schema contract. -The tests reset the shared document through `document()` in their fixture; no access-control macro or friend accessor is needed. Focus coverage on ABACUS behavior: generated fields and units, repeated metadata updates, record initialization and SCF accumulation, invalid section types, insertion order, escaping and non-finite values through the real writer, and file errors. Do not replace removed path-walker tests with tests of nlohmann-json's generic container API. +The tests reset the shared document through `document()` in their fixture; no access-control macro +or friend accessor is needed. Focus coverage on ABACUS behavior: generated fields and units, +repeated metadata updates, record initialization and SCF accumulation, invalid section types, +insertion order, escaping and non-finite values through the real writer, and file errors. Do not +replace removed path-walker tests with tests of nlohmann-json's generic container API. ## Code structure @@ -125,10 +163,16 @@ source/source_io/module_json/ โ””โ”€โ”€ test/ # focused unit tests ``` -`init_section()` and `current_output()` are file-local helpers, not public interfaces for workflow callers. +`init_section()` and `current_output()` are file-local helpers, not public interfaces for workflow +callers. ## Guidelines for extending JSON output -Keep construction in the existing schema generator, pass its required data explicitly, and avoid adding `GlobalV`, `GlobalC`, or `PARAM` access. Preserve field names, value types, units, and order unless a schema change is intentional. Add focused tests for new fields and lifecycle behavior, and update the [JSON output reference](json_para.md) when the public schema changes. +Keep construction in the existing schema generator, pass its required data explicitly, and avoid +adding `GlobalV`, `GlobalC`, or `PARAM` access. Preserve field names, value types, units, and order +unless a schema change is intentional. Add focused tests for new fields and lifecycle behavior, and +update the [JSON output reference](json_para.md) when the public schema changes. -Keep examples and new implementation code compatible with the C++11 baseline. Include complete domain-type definitions in the source or test file that needs them, keep public header dependencies minimal, and do not reintroduce access-control macros for testing. +Keep examples and new implementation code compatible with the C++11 baseline. Include complete +domain-type definitions in the source or test file that needs them, keep public header dependencies +minimal, and do not reintroduce access-control macros for testing. diff --git a/docs/advanced/json/json_para.md b/docs/advanced/json/json_para.md index eba7f35022a..4f5aedc4c41 100644 --- a/docs/advanced/json/json_para.md +++ b/docs/advanced/json/json_para.md @@ -9,9 +9,14 @@ ## Overview -When JSON support is enabled with the CMake option `ENABLE_JSON`, ABACUS writes calculation metadata and results to `abacus.json` for post-processing using nlohmann-json. In MPI builds, the output wrapper writes this file only on rank 0. +When JSON support is enabled with the CMake option `ENABLE_JSON`, ABACUS writes calculation metadata +and results to `abacus.json` for post-processing using nlohmann-json. In MPI builds, the output +wrapper writes this file only on rank 0. -The current top-level JSON members are `comment`, `init`, `output`, and `general_info`. Some fields are populated only when the corresponding calculation data are available. The native-schema refactor changes the internal construction API, not these field names or their units. See the [JSON development guide](json_add.md) for implementation details. +The current top-level JSON members are `comment`, `init`, `output`, and `general_info`. Some fields +are populated only when the corresponding calculation data are available. The native-schema refactor +changes the internal construction API, not these field names or their units. See the +[JSON development guide](json_add.md) for implementation details. ## General Information @@ -31,10 +36,15 @@ The `general_info` object records basic build and runtime metadata: ## Initialization Information -The top-level `comment` describes the default units used by the JSON output. The `init` object records the initial structure and calculation settings. Depending on the calculation path, it can contain: +The top-level `comment` describes the default units used by the JSON output. The `init` object +records the initial structure and calculation settings. Depending on the calculation path, it can +contain: -- `element` - [object(string:string)] Element/pseudopotential element information keyed by atom label. -- `orb` - [object(string:string/null)] Numerical orbital path for each atom type, formed by concatenating the configured orbital-directory string and the per-type filename; `null` when that combined string is empty. +- `element` - [object(string:string)] Element/pseudopotential element information keyed by atom + label. +- `orb` - [object(string:string/null)] Numerical orbital path for each atom type, formed by + concatenating the configured orbital-directory string and the per-type filename; `null` when that + combined string is empty. - `pp` - [object(string:string)] Pseudopotential file for each atom type. - `coordinate` - [array(array(double))] Initial Cartesian coordinates in Angstrom. - `mag` - [array(double)] Initial magnetic moment for each atom. @@ -59,14 +69,19 @@ The top-level `comment` describes the default units used by the JSON output. The ## Output -`output` is an array. Each element represents one calculation/ionic-step output record, initialized before its results are written. A newly initialized record has `null` values for `e_fermi`, `energy`, `scf_converge`, `force`, and `stress`, and empty arrays for `coordinate`, `mag`, and `cell`. The `total_mag`, `absolute_mag`, and `scf` members are added by the SCF writer. +`output` is an array. Each element represents one calculation/ionic-step output record, initialized +before its results are written. A newly initialized record has `null` values for `e_fermi`, +`energy`, `scf_converge`, `force`, and `stress`, and empty arrays for `coordinate`, `mag`, and +`cell`. The `total_mag`, `absolute_mag`, and `scf` members are added by the SCF writer. -Fields are filled as the corresponding results become available; not every workflow populates all of them: +Fields are filled as the corresponding results become available; not every workflow populates all of +them: - `energy` - [double/null] Total energy in eV. - `e_fermi` - [double/null] Fermi energy in eV. - `scf_converge` - [bool/null] Whether the SCF calculation converged. -- `force` - [array(array(double))/null] Atomic forces in eV/Angstrom when force calculation is enabled. +- `force` - [array(array(double))/null] Atomic forces in eV/Angstrom when force calculation is + enabled. - `stress` - [array(array(double))/null] Stress tensor in kbar when stress calculation is enabled. - `coordinate` - [array(array(double))] Cartesian coordinates in Angstrom. - `mag` - [array(double)] Magnetic moment for each atom. @@ -79,10 +94,17 @@ Fields are filled as the corresponding results become available; not every workf - `drho` - [double] Charge-density difference. - `time` - [double] Time used by the SCF step in seconds. -Updating geometry data for an existing record replaces its coordinate, magnetic-moment, and cell arrays, together with force and stress arrays when requested; it does not append duplicate rows. SCF iterations are appended to that record's `scf` history, while starting a new calculation/ionic step appends a new `output` record. +Updating geometry data for an existing record replaces its coordinate, magnetic-moment, and cell +arrays, together with force and stress arrays when requested; it does not append duplicate rows. SCF +iterations are appended to that record's `scf` history, while starting a new calculation/ionic step +appends a new `output` record. ## Serialization -The writer uses four-space indentation and retains object-key insertion order. Non-finite floating-point values (NaN and positive or negative infinity) are serialized as `null`, not as nonstandard JSON numeric tokens. A `null` numeric field can therefore mean either that no value has been written or that the stored value was non-finite; it should not be interpreted as zero. +The writer uses four-space indentation and retains object-key insertion order. Non-finite +floating-point values (NaN and positive or negative infinity) are serialized as `null`, not as +nonstandard JSON numeric tokens. A `null` numeric field can therefore mean either that no value has +been written or that the stored value was non-finite; it should not be interpreted as zero. -JSON numbers are intended to be consumed as numeric values. Their textual representation (for example, decimal versus scientific notation) is not part of the output schema. +JSON numbers are intended to be consumed as numeric values. Their textual representation (for +example, decimal versus scientific notation) is not part of the output schema. diff --git a/docs/advanced/md.md b/docs/advanced/md.md index 25c01b1c8a4..163b7d319e9 100644 --- a/docs/advanced/md.md +++ b/docs/advanced/md.md @@ -1,99 +1,174 @@ # Molecular Dynamics -Molecular dynamics (MD) is a computer simulation method for analyzing the physical movements of atoms and molecules. The atoms and molecules are allowed to interact for a fixed period of time, giving a view of the dynamic "evolution" of the system. In the most common version, the trajectories of atoms and molecules are determined by numerically solving Newton's equations of motion for a system of interacting particles, where forces between the particles and their potential energies are calculated using first-principles calculations (first-principles molecular dynamics, FPMD), or interatomic potentials and molecular mechanics force fields (classical molecular dynamics, CMD). - -By setting [calculation](./input_files/input-main.md#calculation) to be `md`, ABACUS currently provides several different MD evolution methods, which is specified by keyword [md_type](./input_files/input-main.md#md_type) in the `INPUT` file: - - - fire: a MD-based relaxation algorithm, see [details](#fire) here - - nve: NVE ensemble with velocity Verlet algorithm - - nvt: NVT ensemble - - npt: Nose-Hoover style NPT ensemble - - langevin: NVT ensemble with Langevin thermostat - - msst: MSST method - -When [md_type](./input_files/input-main.md#md_type) is set to nvt, [md_thermostat](./input_files/input-main.md#md_thermostat) is used to specify the temperature control method used in NVT ensemble. - - - nhc: Nose-Hoover chain - - anderson: Anderson thermostat - - berendsen: Berendsen thermostat - - rescaling: velocity Rescaling method 1 - - rescale_v: velocity Rescaling method 2 - - csvr: Canonical Sampling through Velocity Rescaling (CSVR) thermostat - -When [md_type](./input_files/input-main.md#md_type) is set to npt, [md_pmode](./input_files/input-main.md#md_pmode) is used to specify the cell fluctuation mode in NPT ensemble based on the Nose-Hoover style non-Hamiltonian equations of motion. - - - iso: isotropic cell fluctuations - - aniso: anisotropic cell fluctuations - - tri: non-orthogonal (triclinic) simulation box - -Furthermore, ABACUS also provides a [list of keywords](./input_files/input-main.md#molecular-dynamics) to control relevant parmeters used in MD simulations. - -The MD output information will be written into the file `MD_dump`๏ผŒ in which the atomic forces, atomic velocities, and lattice virial are controlled by keyword [dump_force](./input_files/input-main.md#dump_force), [dump_vel](./input_files/input-main.md#dump_vel), and [dump_virial](./input_files/input-main.md#dump_virial), respectively. - -[Examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/18_md/01_LCAO_NVE_Si8) of MD simulations are also provided. -There are eight INPUT files corresponding to eight different MD evolution methods in the directory. -For examlpe, `INPUT_0` shows how to employ the NVE simulation. - -To run any of the fix cases, users may enter the directory, copy the corresponding input file to `INPUT`, and run ABACUS. +Molecular dynamics (MD) is a computer simulation method for analyzing the physical movements of +atoms and molecules. The atoms and molecules are allowed to interact for a fixed period of time, +giving a view of the dynamic "evolution" of the system. In the most common version, the trajectories +of atoms and molecules are determined by numerically solving Newton's equations of motion for a +system of interacting particles, where forces between the particles and their potential energies are +calculated using first-principles calculations (first-principles molecular dynamics, FPMD), or +interatomic potentials and molecular mechanics force fields (classical molecular dynamics, CMD). + +By setting [calculation](./input_files/input-main.md#calculation) to be `md`, ABACUS currently +provides several different MD evolution methods, which is specified by keyword +[md_type](./input_files/input-main.md#md_type) in the `INPUT` file: + +- fire: a MD-based relaxation algorithm, see [details](#fire) here +- nve: NVE ensemble with velocity Verlet algorithm +- nvt: NVT ensemble +- npt: Nose-Hoover style NPT ensemble +- langevin: NVT ensemble with Langevin thermostat +- msst: MSST method + +When [md_type](./input_files/input-main.md#md_type) is set to nvt, +[md_thermostat](./input_files/input-main.md#md_thermostat) is used to specify the temperature +control method used in NVT ensemble. + +- nhc: Nose-Hoover chain +- anderson: Anderson thermostat +- berendsen: Berendsen thermostat +- rescaling: velocity Rescaling method 1 +- rescale_v: velocity Rescaling method 2 +- csvr: Canonical Sampling through Velocity Rescaling (CSVR) thermostat + +When [md_type](./input_files/input-main.md#md_type) is set to npt, +[md_pmode](./input_files/input-main.md#md_pmode) is used to specify the cell fluctuation mode in NPT +ensemble based on the Nose-Hoover style non-Hamiltonian equations of motion. + +- iso: isotropic cell fluctuations +- aniso: anisotropic cell fluctuations +- tri: non-orthogonal (triclinic) simulation box + +Furthermore, ABACUS also provides a +[list of keywords](./input_files/input-main.md#molecular-dynamics) to control relevant parmeters +used in MD simulations. + +The MD output information will be written into the file `MD_dump`๏ผŒ in which the atomic forces, +atomic velocities, and lattice virial are controlled by keyword +[dump_force](./input_files/input-main.md#dump_force), +[dump_vel](./input_files/input-main.md#dump_vel), and +[dump_virial](./input_files/input-main.md#dump_virial), respectively. + +[Examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/18_md/01_LCAO_NVE_Si8) +of MD simulations are also provided. There are eight INPUT files corresponding to eight different MD +evolution methods in the directory. For examlpe, `INPUT_0` shows how to employ the NVE simulation. + +To run any of the fix cases, users may enter the directory, copy the corresponding input file to +`INPUT`, and run ABACUS. ## FIRE -[FIRE](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.97.170201) (fast inertial relaxation engine) is a MD-based minimization algorithm. It is based on conventional molecular dynamics with additional velocity modifications and adaptive time steps. The MD trajectory will descend to an energy-minimum. -## NVE +[FIRE](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.97.170201) (fast inertial +relaxation engine) is a MD-based minimization algorithm. It is based on conventional molecular +dynamics with additional velocity modifications and adaptive time steps. The MD trajectory will +descend to an energy-minimum. -NVE ensemble (i. e. microcanonical ensemble) is a statistical ensemble that represents the possible states of a mechanical system whose total energy is exactly specified. The system is assumed to be isolated in the sense that it cannot exchange energy or particles with its environment, so that the energy of the system does not change with time. +## NVE -The primary macroscopic variables of the microcanonical ensemble are the total number of particles in the system (symbol: N), the system's volume (symbol: V), as well as the total energy in the system (symbol: E). Each of these is assumed to be constant in the ensemble. +NVE ensemble (i. e. microcanonical ensemble) is a statistical ensemble that represents the possible +states of a mechanical system whose total energy is exactly specified. The system is assumed to be +isolated in the sense that it cannot exchange energy or particles with its environment, so that the +energy of the system does not change with time. -Currently NVE ensemble in ABACUS is implemented based on the [velocity verlet algorithm](https://aip.scitation.org/doi/abs/10.1063/1.442716). +The primary macroscopic variables of the microcanonical ensemble are the total number of particles +in the system (symbol: N), the system's volume (symbol: V), as well as the total energy in the +system (symbol: E). Each of these is assumed to be constant in the ensemble. +Currently NVE ensemble in ABACUS is implemented based on the +[velocity verlet algorithm](https://aip.scitation.org/doi/abs/10.1063/1.442716). ## Nose Hoover Chain -NVT ensemble (i. e. canonical ensemble) is the statistical ensemble that represents the possible states of a mechanical system in thermal equilibrium with a heat bath at a fixed temperature. The system can exchange energy with the heat bath, so that the states of the system will differ in total energy. - -The principal thermodynamic variable of the canonical ensemble, determining the probability distribution of states, is the absolute temperature (symbol: T). The ensemble typically also depends on mechanical variables such as the number of particles in the system (symbol: N) and the system's volume (symbol: V), each of which influence the nature of the system's internal states. An ensemble with these three parameters is sometimes called the NVT ensemble. +NVT ensemble (i. e. canonical ensemble) is the statistical ensemble that represents the possible +states of a mechanical system in thermal equilibrium with a heat bath at a fixed temperature. The +system can exchange energy with the heat bath, so that the states of the system will differ in total +energy. +The principal thermodynamic variable of the canonical ensemble, determining the probability +distribution of states, is the absolute temperature (symbol: T). The ensemble typically also depends +on mechanical variables such as the number of particles in the system (symbol: N) and the system's +volume (symbol: V), each of which influence the nature of the system's internal states. An ensemble +with these three parameters is sometimes called the NVT ensemble. -The isothermalโ€“isobaric ensemble (constant temperature and constant pressure ensemble), also called NPT ensemble, is a statistical mechanical ensemble that maintains the number of particles N, constant temperature T, and constant pressure P. This ensemble plays an important role in chemistry as chemical reactions are usually carried out under constant pressure condition. The NPT ensemble is also useful for measuring the equation of state of model systems whose virial expansion for pressure cannot be evaluated, or systems near first-order phase transitions. - -ABACUS perform time integration on [Nose-Hoover style non-Hamiltonian equations of motion](https://journals.aps.org/pra/abstract/10.1103/PhysRevA.31.1695) which are designed to generate positions and velocities sampled from NVT and NPT ensemble. - +The isothermalโ€“isobaric ensemble (constant temperature and constant pressure ensemble), also called +NPT ensemble, is a statistical mechanical ensemble that maintains the number of particles N, +constant temperature T, and constant pressure P. This ensemble plays an important role in chemistry +as chemical reactions are usually carried out under constant pressure condition. The NPT ensemble is +also useful for measuring the equation of state of model systems whose virial expansion for pressure +cannot be evaluated, or systems near first-order phase transitions. +ABACUS perform time integration on +[Nose-Hoover style non-Hamiltonian equations of motion](https://journals.aps.org/pra/abstract/10.1103/PhysRevA.31.1695) +which are designed to generate positions and velocities sampled from NVT and NPT ensemble. ## Langevin -[Langevin thermostat](https://en.wikipedia.org/wiki/Langevin_dynamics) can be used for molecular dynamics equations by assuming that the atoms being simulated are embedded in a sea of much smaller fictional particles. In many instances of solute-solvent systems, the behavior of the solute is desired, and the behavior of the solvent is non-interesting(e.g. proteins, DNA, nanoparticles in solution). In these cases, the solvent influences the dynamics of the solute(typically nanoparticles) via random collisions, and by imposing a frictional drag force on the motion of the nanoparticle in the solvent. The damping factor and the random force combine to give the correct NVT ensemble. +[Langevin thermostat](https://en.wikipedia.org/wiki/Langevin_dynamics) can be used for molecular +dynamics equations by assuming that the atoms being simulated are embedded in a sea of much smaller +fictional particles. In many instances of solute-solvent systems, the behavior of the solute is +desired, and the behavior of the solvent is non-interesting(e.g. proteins, DNA, nanoparticles in +solution). In these cases, the solvent influences the dynamics of the solute(typically +nanoparticles) via random collisions, and by imposing a frictional drag force on the motion of the +nanoparticle in the solvent. The damping factor and the random force combine to give the correct NVT +ensemble. ## Anderson -[Anderson thermostat](https://aip.scitation.org/doi/abs/10.1063/1.439486) couples the system to a heat bath that imposes the desired temperature to simulate the NVT ensemble. The coupling to a heat bath is represented by stochastic collision that act occasionally on randomly selected particles. +[Anderson thermostat](https://aip.scitation.org/doi/abs/10.1063/1.439486) couples the system to a +heat bath that imposes the desired temperature to simulate the NVT ensemble. The coupling to a heat +bath is represented by stochastic collision that act occasionally on randomly selected particles. ## Berendsen -Reset the temperature of a group of atoms by using a [Berendsen thermostat](https://aip.scitation.org/doi/10.1063/1.448118), which rescales their velocities every timestep. In this scheme, the system is weakly coupled to a heat bath with some temperature. Though the thermostat does not generate a correct canonical ensemble (especially for small systems), for large systems on the order of hundreds or thousands of atoms/molecules, the approximation yields roughly correct results for most calculated properties. +Reset the temperature of a group of atoms by using a +[Berendsen thermostat](https://aip.scitation.org/doi/10.1063/1.448118), which rescales their +velocities every timestep. In this scheme, the system is weakly coupled to a heat bath with some +temperature. Though the thermostat does not generate a correct canonical ensemble (especially for +small systems), for large systems on the order of hundreds or thousands of atoms/molecules, the +approximation yields roughly correct results for most calculated properties. ## Rescaling -Reset the temperature of a group of atoms by explicitly rescaling their velocities. Velocities are rescaled if the current and target temperature differ more than [md_tolerance](./input_files/input-main.md#md_tolerance) (Kelvin). +Reset the temperature of a group of atoms by explicitly rescaling their velocities. Velocities are +rescaled if the current and target temperature differ more than +[md_tolerance](./input_files/input-main.md#md_tolerance) (Kelvin). ## Rescale_v -Reset the temperature of a group of atoms by explicitly rescaling their velocities. Every [md_nraise](./input_files/input-main.md#md_nraise) steps the current temperature is rescaled to target temperature. +Reset the temperature of a group of atoms by explicitly rescaling their velocities. Every +[md_nraise](./input_files/input-main.md#md_nraise) steps the current temperature is rescaled to +target temperature. ## CSVR -The CSVR (Canonical Sampling through Velocity Rescaling) thermostat is a stochastic velocity rescaling approach proposed by [Bussi, Donadio, and Parrinello](https://doi.org/10.1063/1.2408420). It rescales the velocities by a factor that is drawn from the appropriate distribution to ensure a canonical ensemble, combining the simplicity of Berendsen-like rescaling with the correct canonical sampling of the Nosรฉ-Hoover chain. The coupling strength is controlled by [md_csvr_tau](./input_files/input-main.md#md_csvr_tau). +The CSVR (Canonical Sampling through Velocity Rescaling) thermostat is a stochastic velocity +rescaling approach proposed by [Bussi, Donadio, and Parrinello](https://doi.org/10.1063/1.2408420). +It rescales the velocities by a factor that is drawn from the appropriate distribution to ensure a +canonical ensemble, combining the simplicity of Berendsen-like rescaling with the correct canonical +sampling of the Nosรฉ-Hoover chain. The coupling strength is controlled by +[md_csvr_tau](./input_files/input-main.md#md_csvr_tau). ## MSST -ABACUS performs the [Multi-Scale Shock Technique (MSST) integration](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.90.235503) to update positions and velocities each timestep to mimic a compressive shock wave passing over the system. The MSST varies the cell volume and temperature in such a way as to restrain the system to the shock Hugoniot and the Rayleigh line. These restraints correspond to the macroscopic conservation laws dictated by a shock front. + +ABACUS performs the +[Multi-Scale Shock Technique (MSST) integration](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.90.235503) +to update positions and velocities each timestep to mimic a compressive shock wave passing over the +system. The MSST varies the cell volume and temperature in such a way as to restrain the system to +the shock Hugoniot and the Rayleigh line. These restraints correspond to the macroscopic +conservation laws dictated by a shock front. ## DPMD -Compiling ABACUS with [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit), MD calculations based on machine learning DP model is enabled. -To employ DPMD calculations, [esolver_type](./input_files/input-main.md#esolver_type) should be set to `dp`. -And the filename of DP model is specified by keyword [pot_file](./input_files/input-main.md#pot_file). +Compiling ABACUS with [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit), MD calculations +based on machine learning DP model is enabled. + +To employ DPMD calculations, [esolver_type](./input_files/input-main.md#esolver_type) should be set +to `dp`. And the filename of DP model is specified by keyword +[pot_file](./input_files/input-main.md#pot_file). ## NEP -If ABACUS is compiled with the Neuroevolution Potential ([NEP](https://gpumd.org/potentials/nep.html)), MD simulations using NEP models are enabled. To use this feature, set [esolver_type](./input_files/input-main.md#esolver_type) to `nep` and specify the potential file path with the [pot_file](./input_files/input-main.md#pot_file) keyword in your INPUT file. \ No newline at end of file +If ABACUS is compiled with the Neuroevolution Potential +([NEP](https://gpumd.org/potentials/nep.html)), MD simulations using NEP models are enabled. To use +this feature, set [esolver_type](./input_files/input-main.md#esolver_type) to `nep` and specify the +potential file path with the [pot_file](./input_files/input-main.md#pot_file) keyword in your INPUT +file. diff --git a/docs/advanced/opt.md b/docs/advanced/opt.md index 72d4f8fb204..cd6a032bbde 100644 --- a/docs/advanced/opt.md +++ b/docs/advanced/opt.md @@ -1,14 +1,24 @@ # Geometry Optimization -By setting `calculation` to be `relax` or `cell-relax`, ABACUS supports structural relaxation and variable-cell relaxation. +By setting `calculation` to be `relax` or `cell-relax`, ABACUS supports structural relaxation and +variable-cell relaxation. -ABACUS provides two CG implementations for variable-cell relaxation, selected by the [relax_method](./input_files/input-main.md#relax_method) parameter: +ABACUS provides two CG implementations for variable-cell relaxation, selected by the +[relax_method](./input_files/input-main.md#relax_method) parameter: -- **Simultaneous CG** (`relax_method = cg`, default since v3.8): Uses simultaneous conjugate gradient (CG) optimization for both ionic positions and cell parameters. Both degrees of freedom are optimized together in each step. +- **Simultaneous CG** (`relax_method = cg`, default since v3.8): Uses simultaneous conjugate + gradient (CG) optimization for both ionic positions and cell parameters. Both degrees of freedom + are optimized together in each step. -- **Nested CG** (`relax_method = cg_trad`): Follows a nested procedure where fixed-cell structural relaxation is performed first, followed by an update of the cell parameters, and the process is repeated until convergence is achieved. +- **Nested CG** (`relax_method = cg_trad`): Follows a nested procedure where fixed-cell structural + relaxation is performed first, followed by an update of the cell parameters, and the process is + repeated until convergence is achieved. + +An example of the variable cell relaxation can be found in our +[repository](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/17_relax/01_pw_cell_relax_BFGS_Al), +which is provided with the reference output file log.ref. When using Nested CG, each ionic step is +labelled in the following manner: -An example of the variable cell relaxation can be found in our [repository](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/17_relax/01_pw_cell_relax_BFGS_Al), which is provided with the reference output file log.ref. When using Nested CG, each ionic step is labelled in the following manner: ``` ------------------------------------------- RELAX CELL : 3 @@ -16,61 +26,91 @@ An example of the variable cell relaxation can be found in our [repository](http ------------------------------------------- ``` -indicating that this is the first ionic step of the 3rd cell configuration, and it is the 15-th ionic step in total. - +indicating that this is the first ionic step of the 3rd cell configuration, and it is the 15-th +ionic step in total. ## Optimization Algorithms -ABACUS offers multiple optimization algorithms for structural relaxation, which can be selected using the [relax_method](./input_files/input-main.md#relax_method) keyword. Specify one scalar value. +ABACUS offers multiple optimization algorithms for structural relaxation, which can be selected +using the [relax_method](./input_files/input-main.md#relax_method) keyword. Specify one scalar +value. ### Available Algorithms -- **CG (Conjugate Gradient)**: `cg_trad` optimizes ionic positions and cell parameters in separate stages; `cg` optimizes them simultaneously with line search. +- **CG (Conjugate Gradient)**: `cg_trad` optimizes ionic positions and cell parameters in separate + stages; `cg` optimizes them simultaneously with line search. - **BFGS**: Quasi-Newton method for ionic relaxation. - **LBFGS**: Limited-memory BFGS for ionic relaxation. - **SD (Steepest Descent)**: Simple gradient descent for ionic relaxation. -- **CG-BFGS**: Mixed method that starts with CG and switches to BFGS when force convergence reaches the threshold set by [relax_cg_thr](./input_files/input-main.md#relax_cg_thr). +- **CG-BFGS**: Mixed method that starts with CG and switches to BFGS when force convergence reaches + the threshold set by [relax_cg_thr](./input_files/input-main.md#relax_cg_thr). -We also provide a [list of keywords](./input_files/input-main.md#geometry-relaxation) for controlling the relaxation process. +We also provide a [list of keywords](./input_files/input-main.md#geometry-relaxation) for +controlling the relaxation process. ### BFGS method -The [BFGS method](https://en.wikipedia.org/wiki/Broyden%E2%80%93Fletcher%E2%80%93Goldfarb%E2%80%93Shanno_algorithm) is a quasi-Newton method for solving nonlinear optimization problems. It belongs to the class of quasi-Newton methods where the Hessian matrix is approximated during the optimization process. If the initial point is not far from the extrema, BFGS tends to work better than gradient-based methods. +The +[BFGS method](https://en.wikipedia.org/wiki/Broyden%E2%80%93Fletcher%E2%80%93Goldfarb%E2%80%93Shanno_algorithm) +is a quasi-Newton method for solving nonlinear optimization problems. It belongs to the class of +quasi-Newton methods where the Hessian matrix is approximated during the optimization process. If +the initial point is not far from the extrema, BFGS tends to work better than gradient-based +methods. -ABACUS provides two BFGS implementations, selected by [relax_method](./input_files/input-main.md#relax_method): +ABACUS provides two BFGS implementations, selected by +[relax_method](./input_files/input-main.md#relax_method): -- **Default BFGS** (`relax_method = bfgs`): Updates the inverse of the approximate Hessian matrix B directly. This is the recommended implementation. +- **Default BFGS** (`relax_method = bfgs`): Updates the inverse of the approximate Hessian matrix B + directly. This is the recommended implementation. -- **Traditional BFGS** (`relax_method = bfgs_trad`): Updates the approximate Hessian matrix B itself, then obtains the inverse by solving matrix eigenvalues and taking their reciprocals. Both methods are mathematically equivalent, but in some cases the traditional variant may perform better. +- **Traditional BFGS** (`relax_method = bfgs_trad`): Updates the approximate Hessian matrix B + itself, then obtains the inverse by solving matrix eigenvalues and taking their reciprocals. Both + methods are mathematically equivalent, but in some cases the traditional variant may perform + better. ### LBFGS method -The [L-BFGS (Limited-memory BFGS)](https://en.wikipedia.org/wiki/Limited-memory_BFGS) method is a memory-efficient variant of BFGS that stores only a few vectors representing the Hessian approximation instead of the full matrix. This makes it particularly suitable for large systems with many atoms. +The [L-BFGS (Limited-memory BFGS)](https://en.wikipedia.org/wiki/Limited-memory_BFGS) method is a +memory-efficient variant of BFGS that stores only a few vectors representing the Hessian +approximation instead of the full matrix. This makes it particularly suitable for large systems with +many atoms. Set `relax_method = lbfgs` to use this method. ### SD method -The [SD (steepest descent) method](https://en.wikipedia.org/wiki/Gradient_descent) is one of the simplest first-order optimization methods, where in each step the motion is along the direction of the gradient, where the function descends the fastest. +The [SD (steepest descent) method](https://en.wikipedia.org/wiki/Gradient_descent) is one of the +simplest first-order optimization methods, where in each step the motion is along the direction of +the gradient, where the function descends the fastest. -In practice, the SD method may take many iterations to converge, and is generally not recommended for production calculations. +In practice, the SD method may take many iterations to converge, and is generally not recommended +for production calculations. ### CG method -The [CG (conjugate gradient) method](https://en.wikipedia.org/wiki/Conjugate_gradient_method) is one of the most widely used methods for solving optimization problems. +The [CG (conjugate gradient) method](https://en.wikipedia.org/wiki/Conjugate_gradient_method) is one +of the most widely used methods for solving optimization problems. ABACUS provides two implementations of the CG method: -- **Simultaneous CG** (`relax_method = cg`, default): Performs simultaneous optimization of both ionic positions and cell parameters using a line search algorithm. This implementation is more efficient for `cell-relax` calculations as it optimizes all degrees of freedom together. The step size can be controlled by [relax_scale_force](./input_files/input-main.md#relax_scale_force). +- **Simultaneous CG** (`relax_method = cg`, default): Performs simultaneous optimization of both + ionic positions and cell parameters using a line search algorithm. This implementation is more + efficient for `cell-relax` calculations as it optimizes all degrees of freedom together. The step + size can be controlled by [relax_scale_force](./input_files/input-main.md#relax_scale_force). -- **Nested CG** (`relax_method = cg_trad`): Uses a nested procedure where ionic positions are optimized first using CG, followed by cell parameter optimization (also using CG) in `cell-relax` calculations. This is the traditional approach where the two optimization steps are separated. +- **Nested CG** (`relax_method = cg_trad`): Uses a nested procedure where ionic positions are + optimized first using CG, followed by cell parameter optimization (also using CG) in `cell-relax` + calculations. This is the traditional approach where the two optimization steps are separated. ## Constrained Optimization -Apart from conventional optimization where all degrees of freedom are allowed to move, we also offer the option of doing constrained optimization in ABACUS. +Apart from conventional optimization where all degrees of freedom are allowed to move, we also offer +the option of doing constrained optimization in ABACUS. -### Fixing Atomic Positions -Users may note that in the above-mentioned example, the atomic positions in STRU file are given along with three integers: +### Fixing Atomic Positions + +Users may note that in the above-mentioned example, the atomic positions in STRU file are given +along with three integers: ``` Al @@ -82,7 +122,9 @@ Al 0.00 0.50 0.50 1 1 1 ``` -For relaxation calculations, the three integers denote whether the corresponding degree of freedom is allowed to move. For example, if we replace the STRU file by: +For relaxation calculations, the three integers denote whether the corresponding degree of freedom +is allowed to move. For example, if we replace the STRU file by: + ``` Al 0.0 @@ -95,22 +137,30 @@ Al then the first Al atom will not be allowed to move in z direction. -Fixing atomic position is sometimes helpful during relaxation of isolated molecule/cluster, to prevent the system from drifting in space. +Fixing atomic position is sometimes helpful during relaxation of isolated molecule/cluster, to +prevent the system from drifting in space. ### Fixing Cell Parameters -Sometimes we want to do variable-cell relaxation with some of the cell degrees of freedom fixed. This is achieved by keywords such as [fixed_axes](./input_files/input-main.md#fixed_axes), [fixed_ibrav](./input_files/input-main.md#fixed_ibrav) and [fixed_atoms](./input_files/input-main.md#fixed_atoms). +Sometimes we want to do variable-cell relaxation with some of the cell degrees of freedom fixed. +This is achieved by keywords such as [fixed_axes](./input_files/input-main.md#fixed_axes), +[fixed_ibrav](./input_files/input-main.md#fixed_ibrav) and +[fixed_atoms](./input_files/input-main.md#fixed_atoms). **Available constraints by implementation:** - **Simultaneous CG** (`relax_method = cg`): + - `fixed_axes = "shape"`: Only allows volume changes (hydrostatic pressure), cell shape is fixed - `fixed_axes = "volume"`: Allows shape changes but keeps volume constant - - `fixed_axes = "a"`, `"b"`, `"c"`, `"ab"`, `"ac"`, `"bc"`, or `"abc"`: Fix specific lattice vectors or combinations + - `fixed_axes = "a"`, `"b"`, `"c"`, `"ab"`, `"ac"`, `"bc"`, or `"abc"`: Fix specific lattice + vectors or combinations - `fixed_ibrav = True`: Maintain the Bravais lattice type during relaxation - **`relax_method = cg_trad`, `bfgs`, `bfgs_trad`, `lbfgs`, `sd`, or `cg_bfgs`**: - - `fixed_axes = "a"`, `"b"`, `"c"`, `"ab"`, `"ac"`, `"bc"`, or `"abc"`: Fix specific lattice vectors or combinations + + - `fixed_axes = "a"`, `"b"`, `"c"`, `"ab"`, `"ac"`, `"bc"`, or `"abc"`: Fix specific lattice + vectors or combinations - `fixed_axes = "shape"`, `"volume"` and `fixed_ibrav = True` are not available **VASP ISIF correspondence:** @@ -127,9 +177,11 @@ If you are familiar with the `ISIF` option from VASP, here is the correspondence ### Stop Geometry Optimization Manually -It is usually difficult to converge when calculating large systems, but people do not want to give up this calculation result. -Providing a file named `EXIT`: +It is usually difficult to converge when calculating large systems, but people do not want to give +up this calculation result. Providing a file named `EXIT`: + ``` stop_ion true ``` + ABACUS will end normally and produce a complete file. diff --git a/docs/advanced/output_files/output-specification.md b/docs/advanced/output_files/output-specification.md index 71e55026865..b6e38666a0c 100644 --- a/docs/advanced/output_files/output-specification.md +++ b/docs/advanced/output_files/output-specification.md @@ -2,11 +2,16 @@ ## 1. Background and Motivation -ABACUS is an integrated software package designed to provide a cohesive user experience. To achieve this goal, **we are establishing unified output file standards** that all developers should follow. +ABACUS is an integrated software package designed to provide a cohesive user experience. To achieve +this goal, **we are establishing unified output file standards** that all developers should follow. -Recent versions of ABACUS have been working on standardizing all output file naming conventions. This work is ongoing, and if there are discrepancies between actual file names and this document, please refer to the latest documentation. +Recent versions of ABACUS have been working on standardizing all output file naming conventions. +This work is ongoing, and if there are discrepancies between actual file names and this document, +please refer to the latest documentation. -All output file naming conventions can be found in the online documentation (with corresponding 3.10-LTS file names): [ABACUS Input Documentation](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html) +All output file naming conventions can be found in the online documentation (with corresponding +3.10-LTS file names): +[ABACUS Input Documentation](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html) ## 2. File Naming Conventions @@ -15,117 +20,125 @@ All output file naming conventions can be found in the online documentation (wit **Rule 1:** All ABACUS output files are stored in the `OUT.{suffix}/` directory. **Rule 2:** File extensions by category: -| Extension | Description | -|-----------|-------------| -| `.txt` | Text file | -| `.dat` | Binary file | -| `.csr` | Sparse matrix format | -| `.cube` | 3D spatial data format | -**Rule 3:** For special output quantities (e.g., wavefunctions), add `_pw` or `_nao` to distinguish between plane wave basis and numerical atomic orbital basis. +| Extension | Description | +| --------- | ---------------------- | +| `.txt` | Text file | +| `.dat` | Binary file | +| `.csr` | Sparse matrix format | +| `.cube` | 3D spatial data format | + +**Rule 3:** For special output quantities (e.g., wavefunctions), add `_pw` or `_nao` to distinguish +between plane wave basis and numerical atomic orbital basis. **Rule 4:** File names are lowercase. Physical quantities appear at the beginning: -| Prefix | Physical Quantity | -|--------|-------------------| -| `chg` | Charge density | -| `pot` | Potential | -| `eig` | Eigenvalue / Energy level | -| `wf` | Wavefunction | -| `dm` | Density matrix | -| `h` | Hamiltonian matrix H | -| `s` | Overlap matrix S | -| `t` | Kinetic energy operator | -| `r` | Position operator or Bravais lattice vector R | -| `k` | k-point in Brillouin zone | -| `xyz` | Three spatial directions | -| `ini` | Initial state (before electronic iteration) | +| Prefix | Physical Quantity | +| ------ | --------------------------------------------- | +| `chg` | Charge density | +| `pot` | Potential | +| `eig` | Eigenvalue / Energy level | +| `wf` | Wavefunction | +| `dm` | Density matrix | +| `h` | Hamiltonian matrix H | +| `s` | Overlap matrix S | +| `t` | Kinetic energy operator | +| `r` | Position operator or Bravais lattice vector R | +| `k` | k-point in Brillouin zone | +| `xyz` | Three spatial directions | +| `ini` | Initial state (before electronic iteration) | **Rule 5:** Suffixes following the physical quantity: -| Suffix | Meaning | -|--------|---------| +| Suffix | Meaning | +| ---------------------- | ------------------------------------------------------------------------ | | `s1`, `s2`, `s3`, `s4` | Spin channel (1, 2 for collinear; 1, 2, 3, 4 for non-collinear with SOC) | -| `s12` | Non-collinear spin calculation | -| `k#` | k-point index (e.g., `k1`, `k2`) | -| `g#` | Ionic step index for relax/md (e.g., `g1`, `g2`) | -| `ini` | Initial state (before electronic iteration), used before or after `g#` | +| `s12` | Non-collinear spin calculation | +| `k#` | k-point index (e.g., `k1`, `k2`) | +| `g#` | Ionic step index for relax/md (e.g., `g1`, `g2`) | +| `ini` | Initial state (before electronic iteration), used before or after `g#` | **Important:** + - All index numbers start from 1 (not 0) - For Gamma-only algorithm in LCAO, no `k` index is included - Overlap matrix `s` does not distinguish spin, so only one matrix is output - For initial charge density output (`out_chg = 2`): - - `out_freq_ion = 0`: `chg_ini.cube` (nspin=1) or `chgs{#}_ini.cube` (nspin=2/4) - output at every step (overwrite same file) - - `out_freq_ion > 0`: `chgg{#}_ini.cube` (nspin=1) or `chgs{#}g{#}_ini.cube` (nspin=2/4) - output every out_freq_ion steps + - `out_freq_ion = 0`: `chg_ini.cube` (nspin=1) or `chgs{#}_ini.cube` (nspin=2/4) - output at every + step (overwrite same file) + - `out_freq_ion > 0`: `chgg{#}_ini.cube` (nspin=1) or `chgs{#}g{#}_ini.cube` (nspin=2/4) - output + every out_freq_ion steps - For initial potential output (`out_pot = 3`): - - `out_freq_ion = 0`: `pot_ini.cube` (nspin=1) or `pots{#}_ini.cube` (nspin=2/4) - output at every step (overwrite same file) - - `out_freq_ion > 0`: `potg{#}_ini.cube` (nspin=1) or `pots{#}g{#}_ini.cube` (nspin=2/4) - output every out_freq_ion steps + - `out_freq_ion = 0`: `pot_ini.cube` (nspin=1) or `pots{#}_ini.cube` (nspin=2/4) - output at every + step (overwrite same file) + - `out_freq_ion > 0`: `potg{#}_ini.cube` (nspin=1) or `pots{#}g{#}_ini.cube` (nspin=2/4) - output + every out_freq_ion steps ### 2.2 Examples -| File Name | Interpretation | -|-----------|----------------| -| `chgs1.cube` | Charge density, spin 1 | -| `chgs2.cube` | Charge density, spin 2 | -| `chgs3.cube` | Charge density, spin 3 (non-collinear with SOC) | -| `chg_ini.cube` | Initial charge density (out_freq_ion=0, nspin=1) | -| `chgs1_ini.cube` | Initial charge density (out_freq_ion=0, spin 1, nspin=2/4) | -| `chgg1_ini.cube` | Initial charge density, geometry step 1 (nspin=1) | +| File Name | Interpretation | +| ------------------ | ----------------------------------------------------------- | +| `chgs1.cube` | Charge density, spin 1 | +| `chgs2.cube` | Charge density, spin 2 | +| `chgs3.cube` | Charge density, spin 3 (non-collinear with SOC) | +| `chg_ini.cube` | Initial charge density (out_freq_ion=0, nspin=1) | +| `chgs1_ini.cube` | Initial charge density (out_freq_ion=0, spin 1, nspin=2/4) | +| `chgg1_ini.cube` | Initial charge density, geometry step 1 (nspin=1) | | `chgs1g1_ini.cube` | Initial charge density, spin 1, geometry step 1 (nspin=2/4) | -| `pot_ini.cube` | Initial potential (out_freq_ion=0, nspin=1) | -| `pots1_ini.cube` | Initial potential (out_freq_ion=0, spin 1, nspin=2/4) | -| `potg1_ini.cube` | Initial potential, geometry step 1 (nspin=1) | -| `pots1g1_ini.cube` | Initial potential, spin 1, geometry step 1 (nspin=2/4) | -| `pots1.cube` | Local potential, spin 1 | -| `elftot.cube` | ELF, total (nspin=1/4) | -| `elfs1.cube` | ELF, spin 1 (nspin=2) | -| `elfs2.cube` | ELF, spin 2 (nspin=2) | -| `elftot.cube` | ELF, total (nspin=2) | -| `elftotg1.cube` | ELF, total, geometry step 1 (nspin=1/4) | -| `elfs1g1.cube` | ELF, spin 1, geometry step 1 (nspin=2) | -| `elftotg1.cube` | ELF, total, geometry step 1 (nspin=2) | -| `eig_occ.txt` | Eigenvalues and occupations | -| `doss1g1.txt` | DOS, spin 1, geometry step 1 | -| `wf_pw.dat` | Wavefunction, plane wave basis | -| `sr.csr` | Overlap matrix in real space (no spin index) | +| `pot_ini.cube` | Initial potential (out_freq_ion=0, nspin=1) | +| `pots1_ini.cube` | Initial potential (out_freq_ion=0, spin 1, nspin=2/4) | +| `potg1_ini.cube` | Initial potential, geometry step 1 (nspin=1) | +| `pots1g1_ini.cube` | Initial potential, spin 1, geometry step 1 (nspin=2/4) | +| `pots1.cube` | Local potential, spin 1 | +| `elftot.cube` | ELF, total (nspin=1/4) | +| `elfs1.cube` | ELF, spin 1 (nspin=2) | +| `elfs2.cube` | ELF, spin 2 (nspin=2) | +| `elftot.cube` | ELF, total (nspin=2) | +| `elftotg1.cube` | ELF, total, geometry step 1 (nspin=1/4) | +| `elfs1g1.cube` | ELF, spin 1, geometry step 1 (nspin=2) | +| `elftotg1.cube` | ELF, total, geometry step 1 (nspin=2) | +| `eig_occ.txt` | Eigenvalues and occupations | +| `doss1g1.txt` | DOS, spin 1, geometry step 1 | +| `wf_pw.dat` | Wavefunction, plane wave basis | +| `sr.csr` | Overlap matrix in real space (no spin index) | ### 2.3 Common Output Files -| File Name | Description | -|-----------|-------------| -| `running_scf.log` | SCF iteration log | -| `doss1g1.txt` | Density of states | -| `eig_occ.txt` | Eigenvalues and occupations | -| `mulliken.txt` | Mulliken population analysis | -| `band.txt` | Band structure | -| `chgs1.cube`, `chgs2.cube` | Charge density (spin 1, spin 2) | -| `chg.cube` | Total charge density | -| Initial charge density (out_chg=2) | | -| `chg_ini.cube` | Initial charge density (out_freq_ion=0, nspin=1) | -| `chgs{#}_ini.cube` | Initial charge density (out_freq_ion=0, spin {#}, nspin=2/4) | -| `chgg{#}_ini.cube` | Initial charge density (out_freq_ion>0, geometry step {#}, nspin=1) | -| `chgs{#}g{#}_ini.cube` | Initial charge density (out_freq_ion>0, spin {#}, geometry step {#}, nspin=2/4) | -| Initial potential (out_pot=3) | | -| `pot_ini.cube` | Initial potential (out_freq_ion=0, nspin=1) | -| `pots{#}_ini.cube` | Initial potential (out_freq_ion=0, spin {#}, nspin=2/4) | -| `potg{#}_ini.cube` | Initial potential (out_freq_ion>0, geometry step {#}, nspin=1) | -| `pots{#}g{#}_ini.cube` | Initial potential (out_freq_ion>0, spin {#}, geometry step {#}, nspin=2/4) | -| `taus1.cube`, `taus2.cube` | Kinetic energy density (tau) | -| `pots1.cube`, `pots2.cube` | Local potential | -| ELF (out_elf) | | -| `elftot.cube` | ELF, total (nspin=1/4) | -| `elfs1.cube`, `elfs2.cube` | ELF, spin 1/2 (nspin=2) | -| `elftot.cube` | ELF, total (nspin=2) | -| `elftotg{#}.cube` | ELF, total, geometry step {#} (nspin=1/4) | -| `elfs{#}g{#}.cube` | ELF, spin {#}, geometry step {#} (nspin=2) | -| `elftotg{#}.cube` | ELF, total, geometry step {#} (nspin=2) | +| File Name | Description | +| ---------------------------------- | ------------------------------------------------------------------------------- | +| `running_scf.log` | SCF iteration log | +| `doss1g1.txt` | Density of states | +| `eig_occ.txt` | Eigenvalues and occupations | +| `mulliken.txt` | Mulliken population analysis | +| `band.txt` | Band structure | +| `chgs1.cube`, `chgs2.cube` | Charge density (spin 1, spin 2) | +| `chg.cube` | Total charge density | +| Initial charge density (out_chg=2) | | +| `chg_ini.cube` | Initial charge density (out_freq_ion=0, nspin=1) | +| `chgs{#}_ini.cube` | Initial charge density (out_freq_ion=0, spin {#}, nspin=2/4) | +| `chgg{#}_ini.cube` | Initial charge density (out_freq_ion>0, geometry step {#}, nspin=1) | +| `chgs{#}g{#}_ini.cube` | Initial charge density (out_freq_ion>0, spin {#}, geometry step {#}, nspin=2/4) | +| Initial potential (out_pot=3) | | +| `pot_ini.cube` | Initial potential (out_freq_ion=0, nspin=1) | +| `pots{#}_ini.cube` | Initial potential (out_freq_ion=0, spin {#}, nspin=2/4) | +| `potg{#}_ini.cube` | Initial potential (out_freq_ion>0, geometry step {#}, nspin=1) | +| `pots{#}g{#}_ini.cube` | Initial potential (out_freq_ion>0, spin {#}, geometry step {#}, nspin=2/4) | +| `taus1.cube`, `taus2.cube` | Kinetic energy density (tau) | +| `pots1.cube`, `pots2.cube` | Local potential | +| ELF (out_elf) | | +| `elftot.cube` | ELF, total (nspin=1/4) | +| `elfs1.cube`, `elfs2.cube` | ELF, spin 1/2 (nspin=2) | +| `elftot.cube` | ELF, total (nspin=2) | +| `elftotg{#}.cube` | ELF, total, geometry step {#} (nspin=1/4) | +| `elfs{#}g{#}.cube` | ELF, spin {#}, geometry step {#} (nspin=2) | +| `elftotg{#}.cube` | ELF, total, geometry step {#} (nspin=2) | ## 3. File Format Standards ### 3.1 Header Section with Comments **Every output file should include `#` comment lines** to explain: + - Data meaning - Units - Source module @@ -140,6 +153,7 @@ All output file naming conventions can be found in the online documentation (wit ``` **Example:** + ``` 1 # ionic step 8207 # number of points @@ -150,18 +164,20 @@ All output file naming conventions can be found in the online documentation (wit ### 3.2 Data Section -| Requirement | Description | -|-------------|-------------| -| **Separator** | Use spaces for column alignment | +| Requirement | Description | +| ------------- | ----------------------------------------------- | +| **Separator** | Use spaces for column alignment | | **Precision** | Controlled by input parameter (see Section 3.4) | -| **Units** | Always specify units in header or column names | -| **Comments** | Use `#` for comment lines | +| **Units** | Always specify units in header or column names | +| **Comments** | Use `#` for comment lines | ### 3.3 Compact Data Layout -**Avoid sparse format with single value per line.** Instead, output 6-8 values per line with proper alignment: +**Avoid sparse format with single value per line.** Instead, output 6-8 values per line with proper +alignment: **Bad (sparse):** + ``` 1.234567 2.345678 @@ -170,6 +186,7 @@ All output file naming conventions can be found in the online documentation (wit ``` **Good (compact):** + ``` 1.234567 2.345678 3.456789 4.567890 5.678901 6.789012 7.890123 8.901234 @@ -180,13 +197,16 @@ All output file naming conventions can be found in the online documentation (wit Output precision should be controllable via input parameters, similar to `out_chg` and `out_pot`: **Example (from `out_pot`):** + ``` out_pot 1 8 ``` + - First integer: output type (1 = output total local potential) - Second integer: precision (number of significant digits, default 8) **Implementation pattern:** + ```cpp // In input parameters int out_type = 0; // output type @@ -202,10 +222,10 @@ ofs << std::setprecision(out_precision) << value; Current integration tests have output files with tens of thousands of lines. Recommendations: -| Issue | Solution | -|-------|----------| -| Too many output files | Consolidate related data into fewer files | -| Files too large | Reduce output frequency, use compact format | +| Issue | Solution | +| --------------------- | ------------------------------------------------- | +| Too many output files | Consolidate related data into fewer files | +| Files too large | Reduce output frequency, use compact format | | Redundant information | Avoid repeating header information in every block | ### 4.2 Balance Test Coverage and Efficiency @@ -218,20 +238,20 @@ Current integration tests have output files with tens of thousands of lines. Rec ### 5.1 Standard Names (Keep Short: 3-8 Characters) -| Physical Quantity | Recommended Name | Unit | -|-------------------|------------------|------| -| Total energy | `etot` | eV | -| Kinetic energy | `ekin` | eV | -| Potential energy | `epot` | eV | -| Force | `force` | eV/Angstrom | -| Stress | `stress` | kBar | -| Charge | `chg` | e | -| Magnetization | `mag` | ฮผB | -| Band index | `n` | - | -| k-point | `kpt` | - | -| Spin | `spin` | - | -| Occupation | `occ` | - | -| Energy level | `eig` | eV | +| Physical Quantity | Recommended Name | Unit | +| ----------------- | ---------------- | ----------- | +| Total energy | `etot` | eV | +| Kinetic energy | `ekin` | eV | +| Potential energy | `epot` | eV | +| Force | `force` | eV/Angstrom | +| Stress | `stress` | kBar | +| Charge | `chg` | e | +| Magnetization | `mag` | ฮผB | +| Band index | `n` | - | +| k-point | `kpt` | - | +| Spin | `spin` | - | +| Occupation | `occ` | - | +| Energy level | `eig` | eV | ### 5.2 Naming Style @@ -298,42 +318,42 @@ void OutputMyData::write(const std::string& filename, int precision) ### 7.2 Key Points 1. **Keep file names short (3-8 characters)** -2. **Add `#` comment lines for data meaning, units, and source module** -3. **Use compact format: 6-8 values per line** -4. **Make precision controllable via input parameter** -5. **Use `std::setw()` for column alignment** +1. **Add `#` comment lines for data meaning, units, and source module** +1. **Use compact format: 6-8 values per line** +1. **Make precision controllable via input parameter** +1. **Use `std::setw()` for column alignment** ## 8. Existing Good Examples -| File | Location | Strengths | -|------|----------|-----------| -| `chgs1.cube` | `tests/03_NAO_multik/scf_out_chg_tau/OUT.autotest/` | Short name, spin index convention | -| `doss1g1.txt` | `tests/03_NAO_multik/scf_out_dos_spin2/OUT.autotest/` | Clear header with metadata | -| `eig_occ.txt` | Same as above | Clear block structure for spin/k-point | -| `mulliken.txt` | `tests/03_NAO_multik/scf_out_mul/OUT.autotest/` | Clear atom separators | +| File | Location | Strengths | +| -------------- | ----------------------------------------------------- | -------------------------------------- | +| `chgs1.cube` | `tests/03_NAO_multik/scf_out_chg_tau/OUT.autotest/` | Short name, spin index convention | +| `doss1g1.txt` | `tests/03_NAO_multik/scf_out_dos_spin2/OUT.autotest/` | Clear header with metadata | +| `eig_occ.txt` | Same as above | Clear block structure for spin/k-point | +| `mulliken.txt` | `tests/03_NAO_multik/scf_out_mul/OUT.autotest/` | Clear atom separators | ## 9. Review Process For new output formats: 1. Check if similar output already exists - reuse format if possible -2. Follow this specification -3. Add documentation in `docs/advanced/output_files/` -4. Submit PR with output sample for review +1. Follow this specification +1. Add documentation in `docs/advanced/output_files/` +1. Submit PR with output sample for review ## 10. Summary -| Aspect | Requirement | -|--------|-------------| -| Directory | All outputs in `OUT.{suffix}/` | -| File name | **Short (3-8 chars)**, lowercase, physical quantity prefix | -| Extensions | `.txt`, `.dat`, `.csr`, `.cube` | -| Basis suffix | `_pw` or `_nao` for basis-specific outputs | -| Spin index | `s1`, `s2`, `s3`, `s4` (SOC), `s12` (non-collinear) | -| Numbering | Start from 1, not 0 | -| Header | `#` comments with meaning, units, source module | -| Data | **Compact: 6-8 values per line**, space-separated | -| Precision | Controllable via input parameter | -| Volume | Reasonable file size, avoid excessive output | +| Aspect | Requirement | +| ------------ | ---------------------------------------------------------- | +| Directory | All outputs in `OUT.{suffix}/` | +| File name | **Short (3-8 chars)**, lowercase, physical quantity prefix | +| Extensions | `.txt`, `.dat`, `.csr`, `.cube` | +| Basis suffix | `_pw` or `_nao` for basis-specific outputs | +| Spin index | `s1`, `s2`, `s3`, `s4` (SOC), `s12` (non-collinear) | +| Numbering | Start from 1, not 0 | +| Header | `#` comments with meaning, units, source module | +| Data | **Compact: 6-8 values per line**, space-separated | +| Precision | Controllable via input parameter | +| Volume | Reasonable file size, avoid excessive output | **Remember: ABACUS outputs should present a unified, professional interface to users.** diff --git a/docs/advanced/output_files/output_dipole.md b/docs/advanced/output_files/output_dipole.md index dfb57930d76..6aa5cb5db1d 100644 --- a/docs/advanced/output_files/output_dipole.md +++ b/docs/advanced/output_files/output_dipole.md @@ -19,22 +19,25 @@ This feature is available for all types of DFT calculations that use charge dens ## Input Parameters -| Parameter | Type | Description | Default | -|-----------|------|-------------|---------| -| `out_dipole` | Integer | Whether to output dipole moment | 0 | +| Parameter | Type | Description | Default | +| ------------ | ------- | ------------------------------- | ------- | +| `out_dipole` | Integer | Whether to output dipole moment | 0 | - `out_dipole = 0`: Disable dipole output - `out_dipole = 1`: Enable dipole output ## Output Files -When `out_dipole` is set to 1, ABACUS will generate files named `dipole_s${spin}.txt` for each spin channel in the output directory. +When `out_dipole` is set to 1, ABACUS will generate files named `dipole_s${spin}.txt` for each spin +channel in the output directory. For spin-polarized calculation (nspin=2): + - `dipole_s1.txt` - `dipole_s2.txt` For non-spin-polarized calculation (nspin=1): + - `dipole_s1.txt` ## Output Format @@ -46,9 +49,12 @@ step_index dipole_x dipole_y dipole_z ``` - `step_index`: The current step number (starts from 1) -- `dipole_x, dipole_y, dipole_z`: The Cartesian x, y, z components of the electronic dipole moment for the corresponding spin channel, in units of elementary charge times Bohr ($e a_0$). +- `dipole_x, dipole_y, dipole_z`: The Cartesian x, y, z components of the electronic dipole moment + for the corresponding spin channel, in units of elementary charge times Bohr ($e a_0$). -These components refer to the Cartesian axes, including for nonorthogonal or rotated cells; they are not components along the lattice vectors. The electronic dipole includes the negative sign of the electron charge. +These components refer to the Cartesian axes, including for nonorthogonal or rotated cells; they are +not components along the lattice vectors. The electronic dipole includes the negative sign of the +electron charge. Example output: @@ -61,9 +67,12 @@ Example output: ## Additional Information During the calculation, the dipole moment is also printed in the `running_*.log` file, including: + - Electronic dipole moment - Ionic dipole moment - Total dipole moment - Total dipole moment norm -The log reports Cartesian components in the same units. The total dipole moment is the sum of the electronic and ionic dipoles, and its norm is calculated from these Cartesian components. The `dipole_s${spin}.txt` files contain only the electronic contribution. +The log reports Cartesian components in the same units. The total dipole moment is the sum of the +electronic and ionic dipoles, and its norm is calculated from these Cartesian components. The +`dipole_s${spin}.txt` files contain only the electronic contribution. diff --git a/docs/advanced/output_files/running_scf.log.md b/docs/advanced/output_files/running_scf.log.md index be80ffc44ca..47364ad83a1 100644 --- a/docs/advanced/output_files/running_scf.log.md +++ b/docs/advanced/output_files/running_scf.log.md @@ -1,6 +1,6 @@ # The running_scf.log file -- [The running\_scf.log file](#the-running_scflog-file) +- [The running_scf.log file](#the-running_scflog-file) - [Reading information](#reading-information) - [Reading version information](#reading-version-information) - [Reading general information](#reading-general-information) @@ -18,16 +18,15 @@ - [Results summary](#results-summary) - [TOTAL-FORCE](#total-force) - [TOTAL-STRESS](#total-stress) - - [FINAL\_ETOT\_IS](#final_etot_is) + - [FINAL_ETOT_IS](#final_etot_is) - [TIME STATISTICS](#time-statistics) - [MEMORY STATISTICS](#memory-statistics) - [Start and end times](#start-and-end-times) - - - ## Reading information + ### Reading version information + ``` ABACUS v3.7.0 Atomic-orbital Based Ab-initio Computation at UStc @@ -51,10 +50,10 @@ Start Time is Thu Jul 18 11:34:56 2024 // The start time of the ABACUS calculation. ``` +______________________________________________________________________ - ------------------------------------------------------------------------------------- ### Reading general information + ``` READING GENERAL INFORMATION // The following section is reading general settings and preparing the computation. @@ -84,6 +83,7 @@ RUNNING WITH DEVICE : CPU / Intel(R) Xeon(R) Platinum ``` ### Reading unitcell + ``` >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>= | | @@ -177,6 +177,7 @@ Reciprocal vectors: (Cartesian coordinate: in unit of 2 pi/a_0) ``` ### Reading pseudopotentials files + ``` >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> | | @@ -271,8 +272,11 @@ Warning_Memory_Consuming allocated: FFT::grid 6.5918 MB // A warning about the memory consumption for the Fast Fourier Transform (FFT) grid. ``` + ## Setup Tasks + ### Setup plane waves of charge/potential + ``` >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> | | @@ -356,6 +360,7 @@ DONE : SETUP UNITCELL Time : 0.611609 (SEC) ``` ### Doing symmetry analysis + ``` >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> | | @@ -438,6 +443,7 @@ DONE : SYMMETRY Time : 0.781568 (SEC) ``` ### Setup K-points + ``` >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> | | @@ -520,8 +526,8 @@ K-POINTS DIRECT COORDINATES // The time taken to initialize the k-points. ``` - ### Setup plane waves of wave functions + ``` >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> | | @@ -605,8 +611,11 @@ SELF-CONSISTENT ------------------------------------------- // The beginning of the self-consistent field (SCF) calculation section. ``` + ## Running scf processes + ### Search adjacent atoms (init) + ``` >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> | | @@ -687,6 +696,7 @@ DONE : INIT SCF Time : 4.10934 (SEC) ``` ### Scf iteration + ``` LC AO ALGORITHM --------------- ION= 1 ELEC= 1-------------------------------- @@ -889,7 +899,9 @@ Density error is 6.53205775131e-08 // The error in the electron density has become very small, indicating near-convergence of the SCF cycle. // Additional iterations of the SCF calculation, showing the gradual convergence of the density error and energies. ``` + ### Scf results + ``` ---------------------------------------------------------- @@ -1151,8 +1163,11 @@ correction force for each atom along direction 2 is 2.49665e-14 correction force for each atom along direction 3 is -3.50742e-14 // The correction forces applied to each atom in the unit cell along the three principal directions. ``` + ## Results summary + ### TOTAL-FORCE + ``` ------------------------------------------------------------------------------------------ TOTAL-FORCE (eV/Angstrom) @@ -1187,6 +1202,7 @@ correction force for each atom along direction 3 is -3.50742e-14 ``` ### TOTAL-STRESS + ``` ---------------------------------------------------------------- TOTAL-STRESS (KBAR) @@ -1202,6 +1218,7 @@ TOTAL-PRESSURE: 20.928031 KBAR ``` ### FINAL_ETOT_IS + ``` -------------------------------------------- !FINAL_ETOT_IS -40425.5513255625628517 eV @@ -1209,9 +1226,8 @@ TOTAL-PRESSURE: 20.928031 KBAR // The final total energy of the system after the SCF calculation, expressed in electron volts. ``` - - ### TIME STATISTICS + ``` TIME STATISTICS -------------------------------------------------------------------------------- @@ -1330,6 +1346,7 @@ TIME STATISTICS ``` ### MEMORY STATISTICS + ``` NAME-------------------------|MEMORY(MB)-------- @@ -1382,8 +1399,10 @@ NAME-------------------------|MEMORY(MB)-------- ``` ### Start and end times + ``` Start Time : Thu Jul 18 11:34:56 2024 Finish Time : Thu Jul 18 11:43:20 2024 Total Time : 0 h 8 mins 24 secs -// The start and end times of the calculation, along with the total duration. \ No newline at end of file +// The start and end times of the calculation, along with the total duration. +``` diff --git a/docs/advanced/pp_orb.md b/docs/advanced/pp_orb.md index 8cc56839b9e..a978a02b8d6 100644 --- a/docs/advanced/pp_orb.md +++ b/docs/advanced/pp_orb.md @@ -2,56 +2,90 @@ ## Basis Set -ABACUS supports both PW and LCAO basis set, controlled by keyword [basis_type](./input_files/input-main.md#basis_type) in INPUT file. +ABACUS supports both PW and LCAO basis set, controlled by keyword +[basis_type](./input_files/input-main.md#basis_type) in INPUT file. -The default value of basis_type is pw. The size of pw basis set is controlled by imposing an upper bound for the [kinetic energy cutoff](./input_files/input-main.md#ecutwfc) of the plane wave. +The default value of basis_type is pw. The size of pw basis set is controlled by imposing an upper +bound for the [kinetic energy cutoff](./input_files/input-main.md#ecutwfc) of the plane wave. -When choosing lcao basis set, users need to prepare a set of atomic orbitals. Such files may be downloaded from the [official website](http://abacus.ustc.edu.cn/pseudo/list.htm). For more information, also check the `NUMERICAL_ORBITAL` section in the specification of the [STRU file](./input_files/stru.md). +When choosing lcao basis set, users need to prepare a set of atomic orbitals. Such files may be +downloaded from the [official website](http://abacus.ustc.edu.cn/pseudo/list.htm). For more +information, also check the `NUMERICAL_ORBITAL` section in the specification of the +[STRU file](./input_files/stru.md). -The angular part of orbitals are real spherical harmonics defined (in terms of conventional spherical harmonics in quantum mechanical literature) as +The angular part of orbitals are real spherical harmonics defined (in terms of conventional +spherical harmonics in quantum mechanical literature) as -$$Y_{lm} = \left\{\begin{matrix}\sqrt{2}~\text{Im} Y_l^{|m|} & m \lt 0 \\[6pt] Y_l^0 & m = 0 \\[6pt] \sqrt{2}~\text{Re}Y_{l}^{|m|} & m \gt 0\end{matrix}\right. $$ +$$Y\_{lm} = \\left{\\begin{matrix}\\sqrt{2}~\\text{Im} Y_l^{|m|} & m \\lt 0 \\[6pt] Y_l^0 & m = 0 +\\[6pt] \\sqrt{2}~\\text{Re}Y\_{l}^{|m|} & m \\gt 0\\end{matrix}\\right. $$ -Note that real spherical harmonics adopted by ABACUS differ from some other definition, e.g. [Table of spherical harmonics - Wikipedia](https://en.wikipedia.org/wiki/Table_of_spherical_harmonics#Real_spherical_harmonics), by a factor of $(-1)^m$. - -Inside ABACUS, orbitals in LCAO basis are arranged lexicographically by species-position-l-zeta-m **except for the intra-m ordering**. Specifically, orbitals are first ordered by their atomic species in accordance with the `ATOMIC_SPECIES` section of the STRU file. For orbitals of the same species, orbitals belonging to each atom are put together, with their overall order following the `ATOMIC_POSITIONS` section of the STRU file. Orbitals on each atom are further ascendingly ordered by their angular momentum (s,p,d,f,...), followed by an order based on their their zeta number. Finally, m is ordered as 0, 1, -1, 2, 2, $\ldots$, l, -l, which is the only exception of the lexicographic order. +Note that real spherical harmonics adopted by ABACUS differ from some other definition, e.g. +[Table of spherical harmonics - Wikipedia](https://en.wikipedia.org/wiki/Table_of_spherical_harmonics#Real_spherical_harmonics), +by a factor of $(-1)^m$. +Inside ABACUS, orbitals in LCAO basis are arranged lexicographically by species-position-l-zeta-m +**except for the intra-m ordering**. Specifically, orbitals are first ordered by their atomic +species in accordance with the `ATOMIC_SPECIES` section of the STRU file. For orbitals of the same +species, orbitals belonging to each atom are put together, with their overall order following the +`ATOMIC_POSITIONS` section of the STRU file. Orbitals on each atom are further ascendingly ordered +by their angular momentum (s,p,d,f,...), followed by an order based on their their zeta number. +Finally, m is ordered as 0, 1, -1, 2, 2, $\\ldots$, l, -l, which is the only exception of the +lexicographic order. ## Generating atomic orbital bases -Users may also generate ABACUS numerical atomic obitals based on their own flavor. The theoretical background of orbital generation can be found in following works: +Users may also generate ABACUS numerical atomic obitals based on their own flavor. The theoretical +background of orbital generation can be found in following works: -- Spillage: [Chen M, Guo G C, He L. Systematically improvable optimized atomic basis sets for ab initio calculations[J]. Journal of Physics: Condensed Matter, 2010, 22(44): 445501.](https://iopscience.iop.org/article/10.1088/0953-8984/22/44/445501) -- PTG DPSI: [Lin P, Ren X, He L. Strategy for constructing compact numerical atomic orbital basis sets by incorporating the gradients of reference wavefunctions[J]. Physical Review B, 2021, 103(23): 235131.](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.103.235131) +- Spillage: + [Chen M, Guo G C, He L. Systematically improvable optimized atomic basis sets for ab initio calculations[J]. Journal of Physics: Condensed Matter, 2010, 22(44): 445501.](https://iopscience.iop.org/article/10.1088/0953-8984/22/44/445501) +- PTG DPSI: + [Lin P, Ren X, He L. Strategy for constructing compact numerical atomic orbital basis sets by incorporating the gradients of reference wavefunctions[J]. Physical Review B, 2021, 103(23): 235131.](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.103.235131) Guidelines for generating atomic orbital bases are as follows: -- [Numerical Atomic Orbitals 1: the nomenclature and usage of numerical atomic orbitals in ABACUS](https://mcresearch.github.io/abacus-user-guide/abacus-nac1.html) (Chinese) -- [Numerical Atomic Orbitals 2: generate numerical atomic orbitals based on given norm-conserving pseudopotential](https://mcresearch.github.io/abacus-user-guide/abacus-nac1.html) (Chinese) -- [Numerical Atomic Orbitals 3: generate high-precision numerical atomic orbitals](https://mcresearch.github.io/abacus-user-guide/abacus-nac1.html) (Chinese) +- [Numerical Atomic Orbitals 1: the nomenclature and usage of numerical atomic orbitals in ABACUS](https://mcresearch.github.io/abacus-user-guide/abacus-nac1.html) + (Chinese) +- [Numerical Atomic Orbitals 2: generate numerical atomic orbitals based on given norm-conserving pseudopotential](https://mcresearch.github.io/abacus-user-guide/abacus-nac1.html) + (Chinese) +- [Numerical Atomic Orbitals 3: generate high-precision numerical atomic orbitals](https://mcresearch.github.io/abacus-user-guide/abacus-nac1.html) + (Chinese) -Stable orbital generation programs can be found in guidelines above, there is also another developing version of orbital generation program, in which algorithms are consecutively improved: [Github repository of ABACUS ORBGEN project](https://github.com/kirk0830/ABACUS-ORBGEN), the usage of which can be found in README (in English) file. +Stable orbital generation programs can be found in guidelines above, there is also another +developing version of orbital generation program, in which algorithms are consecutively improved: +[Github repository of ABACUS ORBGEN project](https://github.com/kirk0830/ABACUS-ORBGEN), the usage +of which can be found in README (in English) file. -*NOTE*: users are encouraged to cite the above works when numerical atomic orbitals and its generation codes are used in their research. +*NOTE*: users are encouraged to cite the above works when numerical atomic orbitals and its +generation codes are used in their research. ## BSSE Correction -For treating BSSE(Basis Set Superposition Error), we allow for the inclusion of "empty" or "ghost" atoms in the calculation. Namely, when expanding the Hamiltonian, basis sets on the atoms are used, while the ionic potentials on those atoms are not included when constructing the Hamiltonian. +For treating BSSE(Basis Set Superposition Error), we allow for the inclusion of "empty" or "ghost" +atoms in the calculation. Namely, when expanding the Hamiltonian, basis sets on the atoms are used, +while the ionic potentials on those atoms are not included when constructing the Hamiltonian. -An empty atom is defined in the `STRU` file when an element name contains the "empty" suffix, such as "H_empty", "O_empty" and so on. Here we provide an [example](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/32_bsse/01_water) of calculating the molecular formation energy of $H_2O$ with BSSE correction. +An empty atom is defined in the `STRU` file when an element name contains the "empty" suffix, such +as "H_empty", "O_empty" and so on. Here we provide an +[example](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/32_bsse/01_water) of +calculating the molecular formation energy of $H_2O$ with BSSE correction. In the example, we provide four STRU files: -- STRU_0 : used along with ntype = 2;normal calculation of water molecule ($E(\text{H}_2\text{O})$) +- STRU_0 : used along with ntype = 2;normal calculation of water molecule + ($E(\\text{H}\_2\\text{O})$) obtained total energy of -466.4838149140513 eV + - STRU_1 : used along with ntype = 2;calculation of single O atom ($E_O$) obtained total energy of -427.9084406198214 eV -- STRU_2 : used along with ntype = 3;calculation of 1st H atom ($E_{H1}$) + +- STRU_2 : used along with ntype = 3;calculation of 1st H atom ($E\_{H1}$) obtained total energy of -12.59853381731160 eV -- STRU_3 : used along with ntype = 3;calculation of 2nd H atom ($E_{H2}$) + +- STRU_3 : used along with ntype = 3;calculation of 2nd H atom ($E\_{H2}$) obtained total energy of -12.59853378720844 eV @@ -59,21 +93,26 @@ In the example, we provide four STRU files: Thus, the formation energy is given by: -$$ -\Delta E(\text{H}_2\text{O}) = E(\text{H}_2\text{O}) - E(\text{O}) - E(\text{H}^1) - E(\text{H}^2) \approx -13.38 eV -$$ +$$ \\Delta E(\\text{H}\_2\\text{O}) = E(\\text{H}\_2\\text{O}) - E(\\text{O}) - E(\\text{H}^1) - +E(\\text{H}^2) \\approx -13.38 eV $$ ## Pseudopotentials + ### Supported formats -ABACUS supports both norm-conserving and ultrasoft pseudopotentials. For norm-conserving pseudopotentials, UPF, UPF2, VWR, and BLPS formats are supported. For ultrasoft pseudopotentials, UPF and UPF2 formats are supported. + +ABACUS supports both norm-conserving and ultrasoft pseudopotentials. For norm-conserving +pseudopotentials, UPF, UPF2, VWR, and BLPS formats are supported. For ultrasoft pseudopotentials, +UPF and UPF2 formats are supported. ### Pseudopotentials for SOC Calculations -When performing spin-orbit coupling (SOC) calculations with `lspinorb=1`, specific pseudopotential requirements must be met: +When performing spin-orbit coupling (SOC) calculations with `lspinorb=1`, specific pseudopotential +requirements must be met: #### Identifying SOC Pseudopotentials -Full-relativistic pseudopotentials suitable for SOC calculations can be identified by checking the UPF file header (`PP_HEADER` section): +Full-relativistic pseudopotentials suitable for SOC calculations can be identified by checking the +UPF file header (`PP_HEADER` section): ```xml @@ -89,20 +128,26 @@ Full-relativistic pseudopotentials suitable for SOC calculations can be identifi #### Usage Rules 1. **SOC calculations** (`lspinorb=1`): + - **Required**: Full-relativistic pseudopotentials with `has_so=true` - **Error if not met**: "no soc upf used for lspinorb calculation" -2. **Non-SOC calculations** (`lspinorb=0`): - - **Flexible**: Can use either scalar-relativistic (`relativistic="scalar"`) or full-relativistic pseudopotentials - - **Automatic conversion**: If full-relativistic PP is used, ABACUS automatically transforms it to scalar-relativistic version +1. **Non-SOC calculations** (`lspinorb=0`): + + - **Flexible**: Can use either scalar-relativistic (`relativistic="scalar"`) or full-relativistic + pseudopotentials + - **Automatic conversion**: If full-relativistic PP is used, ABACUS automatically transforms it + to scalar-relativistic version + +1. **Ultrasoft pseudopotentials (USPP)**: -3. **Ultrasoft pseudopotentials (USPP)**: - **Constraint**: Full-relativistic USPP must be used with `lspinorb=true` - **Warning if violated**: "FR-USPP please use lspinorb=.true." #### Validation by ABACUS ABACUS performs automatic validation when reading pseudopotentials: + - Checks if `lspinorb=1` but pseudopotential has `has_so=false` โ†’ terminates with error - Checks if full-relativistic USPP is used without `lspinorb=1` โ†’ shows warning - Automatically averages SOC-related beta functions when `lspinorb=0` @@ -110,49 +155,90 @@ ABACUS performs automatic validation when reading pseudopotentials: #### Where to Find SOC Pseudopotentials For SOC calculations, download full-relativistic pseudopotentials from: -- **SG15_ONCV**: [quantum-simulation.org](http://quantum-simulation.org/potentials/sg15_oncv/upf/) - widely used in ABACUS -- **PseudoDOJO**: [pseudo-dojo.org](http://www.pseudo-dojo.org/) - provides both scalar and full-relativistic versions -- **ABACUS official**: [abacus.ustc.edu.cn](http://abacus.ustc.edu.cn/pseudo/list.htm) - includes both pseudopotentials and numerical atomic orbitals + +- **SG15_ONCV**: [quantum-simulation.org](http://quantum-simulation.org/potentials/sg15_oncv/upf/) - + widely used in ABACUS +- **PseudoDOJO**: [pseudo-dojo.org](http://www.pseudo-dojo.org/) - provides both scalar and + full-relativistic versions +- **ABACUS official**: [abacus.ustc.edu.cn](http://abacus.ustc.edu.cn/pseudo/list.htm) - includes + both pseudopotentials and numerical atomic orbitals For more details on SOC calculations, see [Spin-polarization and SOC](./scf/spin.md#soc-effects). ### Usage -For more information about pseudopotential usage, check the `ATOMIC_SPECIES` section in the specification of the [STRU file](./input_files/stru.md). + +For more information about pseudopotential usage, check the `ATOMIC_SPECIES` section in the +specification of the [STRU file](./input_files/stru.md). ### Download + Users can find pseudopotentials in the following links: **Website** -- [Quantum ESPRESSO](https://www.quantum-espresso.org/pseudopotentials): the official website of Quantum ESPRESSO, where you can find a large number of pseudopotential files. -- [Stantard Solid State Pseudopotential library](https://www.materialscloud.org/sssp): a library of **high-quality** pseudopotentials for solid-state calculations, with **a large number of tests on efficiency and precison**. -- [PWmat](http://www.pwmat.com/potential-download): a website that provides a large number of pseudopotential files, various kinds of semi-core constructed pseudopotentials are included. **Several sets (with or without f-electrons/noncolinear core correction) of Lanthanide pseudopotentials are also available**. -- [THEOS](http://theossrv1.epfl.ch/Main/Pseudopotentials): PSlibrary 0.3.1, a library of pseudopotentials for DFT calculations, including ultrasoft, norm-conserving both full-relativistic and scalar-relativistic pseudopotentials. -- [ABACUS@USTC](https://abacus.ustc.edu.cn/pseudo/list.htm): **ABACUS official website** where you can find a large number of pseudopotential files and numerical atomic orbital files. + +- [Quantum ESPRESSO](https://www.quantum-espresso.org/pseudopotentials): the official website of + Quantum ESPRESSO, where you can find a large number of pseudopotential files. +- [Stantard Solid State Pseudopotential library](https://www.materialscloud.org/sssp): a library of + **high-quality** pseudopotentials for solid-state calculations, with **a large number of tests on + efficiency and precison**. +- [PWmat](http://www.pwmat.com/potential-download): a website that provides a large number of + pseudopotential files, various kinds of semi-core constructed pseudopotentials are included. + **Several sets (with or without f-electrons/noncolinear core correction) of Lanthanide + pseudopotentials are also available**. +- [THEOS](http://theossrv1.epfl.ch/Main/Pseudopotentials): PSlibrary 0.3.1, a library of + pseudopotentials for DFT calculations, including ultrasoft, norm-conserving both full-relativistic + and scalar-relativistic pseudopotentials. +- [ABACUS@USTC](https://abacus.ustc.edu.cn/pseudo/list.htm): **ABACUS official website** where you + can find a large number of pseudopotential files and numerical atomic orbital files. - [BLPS](https://github.com/PrincetonUniversity/BLPSLibrary): BLPS format pseudopotential library **Norm-conserving pseudopotentials** -- [SG15](http://www.quantum-simulation.org/potentials/sg15_oncv/): **vastly used in ABACUS** DFT calculation and numerical atomic orbital generation. -- [PseudoDOJO](http://www.pseudo-dojo.org/): another widely used pseudopotential database, developed by Abinit group, **including Lanthanide pseudopotentials (f-electrons frozen)**. -- [The Rappe group](https://www.sas.upenn.edu/rappegroup/research/pseudo-potential-gga.html): a collection of GGA pseudopotentials which are generated with Opium code, several tests proves that are out-performing in alloy systems. -- [Matteo Giantomassi's Github repo](https://github.com/gmatteo/pseudos_ac_she): a Github repository that contains norm-conserving pseudopotentials for **Actinides and superheavy elements to 120-th element**. + +- [SG15](http://www.quantum-simulation.org/potentials/sg15_oncv/): **vastly used in ABACUS** DFT + calculation and numerical atomic orbital generation. +- [PseudoDOJO](http://www.pseudo-dojo.org/): another widely used pseudopotential database, developed + by Abinit group, **including Lanthanide pseudopotentials (f-electrons frozen)**. +- [The Rappe group](https://www.sas.upenn.edu/rappegroup/research/pseudo-potential-gga.html): a + collection of GGA pseudopotentials which are generated with Opium code, several tests proves that + are out-performing in alloy systems. +- [Matteo Giantomassi's Github repo](https://github.com/gmatteo/pseudos_ac_she): a Github repository + that contains norm-conserving pseudopotentials for **Actinides and superheavy elements to 120-th + element**. **Ultrasoft pseudopotentials** -- [Vanderbilt](http://www.physics.rutgers.edu/~dhv/uspp/): a collection of ultrasoft pseudopotentials generated by Vanderbilt group. -- [GBRV](https://www.physics.rutgers.edu/gbrv/) by Kevin F. Garrity, Joseph W. Bennett, Karin M. Rabe, and David Vanderbilt: presently the most popular ultrasoft pseudpotentials in Quantum ESPRESSO user community. + +- [Vanderbilt](http://www.physics.rutgers.edu/~dhv/uspp/): a collection of ultrasoft + pseudopotentials generated by Vanderbilt group. +- [GBRV](https://www.physics.rutgers.edu/gbrv/) by Kevin F. Garrity, Joseph W. Bennett, Karin M. + Rabe, and David Vanderbilt: presently the most popular ultrasoft pseudpotentials in Quantum + ESPRESSO user community. ### Pseudopotential Generation + For pseudopotential generation, please refer to the following links for more information: + - [Quantum ESPRESSO](http://www.quantum-espresso.org/pseudopotentials/) - [ONCVPSP](http://www.mat-simresearch.com/) - [Opium](https://opium.sourceforge.net/) -A Chinese guideline is also available here: [A brief introduction of norm-conserving pseudopotential generation](https://mcresearch.github.io/abacus-user-guide/abacus-upf.html) +A Chinese guideline is also available here: +[A brief introduction of norm-conserving pseudopotential generation](https://mcresearch.github.io/abacus-user-guide/abacus-upf.html) # ABACUS Pseudopotential-Numerical atomic orbital Square (APNS) project -For the purpose of providing high-quality pseudopotentials and numerical atomic orbitals, we have initiated the APNS project. The project is aimed at providing a large number of high-quality pseudopotentials and numerical atomic orbitals, along with diverse test data for the ABACUS user community, reduce the cost of generating and testing pseudopotentials and numerical atomic orbitals by users, and promote the development of ABACUS software. The project is currently in the development stage, and we welcome contributions from the community. For more information, please refer to the following links: + +For the purpose of providing high-quality pseudopotentials and numerical atomic orbitals, we have +initiated the APNS project. The project is aimed at providing a large number of high-quality +pseudopotentials and numerical atomic orbitals, along with diverse test data for the ABACUS user +community, reduce the cost of generating and testing pseudopotentials and numerical atomic orbitals +by users, and promote the development of ABACUS software. The project is currently in the +development stage, and we welcome contributions from the community. For more information, please +refer to the following links: + - [APNS website: test data and results](https://kirk0830.github.io/ABACUS-Pseudopot-Nao-Square/) - [APNS workflow (Github repository): high-throughput test of pseudopotentials and numerical atomic orbitals](https://github.com/kirk0830/ABACUS-Pseudopot-Nao-Square) -There are also other excellent projects that provide high-quality pseudopotentials along with test data: +There are also other excellent projects that provide high-quality pseudopotentials along with test +data: + - [Solid State Pseudopotential library](https://www.materialscloud.org/sssp) - [Verification of the precision of DFT implementation via AiiDA common workflows](https://acwf-verification.materialscloud.org/) diff --git a/docs/advanced/scf/advanced.md b/docs/advanced/scf/advanced.md index a01280344bb..29f266c9746 100644 --- a/docs/advanced/scf/advanced.md +++ b/docs/advanced/scf/advanced.md @@ -2,11 +2,23 @@ ## Implicit Solvation Model -Solid-liquid interfaces are ubiquitous in nature and frequently encountered and employed in materials simulation. The solvation effect should be taken into account in first-principles calculations of such systems so as to obtain accurate predictions. - -Implicit solvation model is a well-developed method to deal with solvation effects, which has been widely used in finite and periodic systems. This approach treats the solvent as a continuous medium instead of individual โ€œexplicitโ€ solvent molecules, which means that the solute embedded in an implicit solvent, and the average over the solvent degrees of freedom becomes implicit in the properties of the solvent bath. Compared to the โ€œexplicitโ€ method, such implicit solvation model can provide qualitatively correct results with much less computational cost, which is particularly suited for large and complex systems. The implicit solvation model implemented in ABACUS follows the [methodology](https://aip.scitation.org/doi/10.1063/1.4865107) developed by Mathew, Sundararaman, Letchworth-Weaver, Arias, and Hennig in 2014. - -Input parameters that control the implicit solvation model are listed as follows with detailed explaination and recommended values provided on this [webpage](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#implicit-solvation-model): +Solid-liquid interfaces are ubiquitous in nature and frequently encountered and employed in +materials simulation. The solvation effect should be taken into account in first-principles +calculations of such systems so as to obtain accurate predictions. + +Implicit solvation model is a well-developed method to deal with solvation effects, which has been +widely used in finite and periodic systems. This approach treats the solvent as a continuous medium +instead of individual โ€œexplicitโ€ solvent molecules, which means that the solute embedded in an +implicit solvent, and the average over the solvent degrees of freedom becomes implicit in the +properties of the solvent bath. Compared to the โ€œexplicitโ€ method, such implicit solvation model can +provide qualitatively correct results with much less computational cost, which is particularly +suited for large and complex systems. The implicit solvation model implemented in ABACUS follows the +[methodology](https://aip.scitation.org/doi/10.1063/1.4865107) developed by Mathew, Sundararaman, +Letchworth-Weaver, Arias, and Hennig in 2014. + +Input parameters that control the implicit solvation model are listed as follows with detailed +explaination and recommended values provided on this +[webpage](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#implicit-solvation-model): ``` INPUT_PARAMETERS @@ -17,14 +29,20 @@ sigma_k 0.6 nc_k 0.00037 ``` -Example of running DFT calculation with the implicit solvation model is provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/27_imp_sol/01_pw_Pt_slab). +Example of running DFT calculation with the implicit solvation model is provided in this +[directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/27_imp_sol/01_pw_Pt_slab). + +## External Electric Field -## External Electric Field +A saw-like potential simulating an electric field can be added to the bare ionic potential, which is +a simplified simulation to the field-effect measurements, in which the system is separated from the +gate electrode by a dielectric such as silicon oxide. -A saw-like potential simulating an electric field -can be added to the bare ionic potential, which is a simplified simulation to the field-effect measurements, in which the system is separated from the gate electrode by a dielectric such as silicon oxide. +Whether to apply the external field is controlled via the keyword `efield_flag` in `INPUT` (setting +to 1 to turn on the field). Related keywords that control the external field are listed as follows +with detailed explaination provided +[here](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#electric-field-and-dipole-correction): -Whether to apply the external field is controlled via the keyword `efield_flag` in `INPUT` (setting to 1 to turn on the field). Related keywords that control the external field are listed as follows with detailed explaination provided [here](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#electric-field-and-dipole-correction): ``` INPUT_PARAMETERS efield_flag 1 @@ -34,11 +52,22 @@ efield_pos_dec 0.1 efield_amp 0.001 ``` -Example of running DFT calculation with added external electric field is provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/28_efield/01_Pt_slab). - +Example of running DFT calculation with added external electric field is provided in this +[directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/28_efield/01_Pt_slab). ## Dipole Correction -A dipole correction can be added to the bare ionic potential, which can compensate for the artificial dipole field within the context of a periodic supercell calculation. The dipole correction implemented in ABACUS follows the [methodology](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.59.12301) proposed by Bengtsson in 1999. This correction must be used ONLY in a slab geometry, for surface calculations, with the discontinuity FALLING IN THE EMPTY SPACE. Note that the common input parameters shared between the external electric field and dipole correction, with detailed explaination provided [here](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#electric-field-and-dipole-correction). The following keywords settings add dipole correction only without applying any external electric field: + +A dipole correction can be added to the bare ionic potential, which can compensate for the +artificial dipole field within the context of a periodic supercell calculation. The dipole +correction implemented in ABACUS follows the +[methodology](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.59.12301) proposed by Bengtsson +in 1999. This correction must be used ONLY in a slab geometry, for surface calculations, with the +discontinuity FALLING IN THE EMPTY SPACE. Note that the common input parameters shared between the +external electric field and dipole correction, with detailed explaination provided +[here](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#electric-field-and-dipole-correction). +The following keywords settings add dipole correction only without applying any external electric +field: + ``` INPUT_PARAMETERS efield_flag 1 @@ -49,7 +78,9 @@ efield_pos_dec 0.1 efield_amp 0 ``` -While The external electric field and dipole correction can also be added together to the bare ionic potential as follows: +While The external electric field and dipole correction can also be added together to the bare ionic +potential as follows: + ``` INPUT_PARAMETERS efield_flag 1 @@ -60,16 +91,27 @@ efield_pos_dec 0.1 efield_amp 0.001 ``` -Examples of running DFT calculations with dipole correction are provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/29_dipole_corr/01_Pt_slab). There are two input files, where `INPUT1` considers only the dipole correction without no applied external field, while `INPUT2` considers the dipole correction under an applied external field. - -To run any of the two cases, users may enter the directory, copy the corresponding input file to `INPUT`, and run ABACUS. +Examples of running DFT calculations with dipole correction are provided in this +[directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/29_dipole_corr/01_Pt_slab). +There are two input files, where `INPUT1` considers only the dipole correction without no applied +external field, while `INPUT2` considers the dipole correction under an applied external field. +To run any of the two cases, users may enter the directory, copy the corresponding input file to +`INPUT`, and run ABACUS. ## Compensating Charge -Modeling a constant-potential electronchemcial surface reaction requires adjustment of electron numbers in a simulation cell. At the mean time, we need to maintain the supercell's neutrality due to the periodic boundary condition. A distribution of compensating charge thus needs to be implemented in the vacuum region of surface models when extra electrons are added/extracted from the system. +Modeling a constant-potential electronchemcial surface reaction requires adjustment of electron +numbers in a simulation cell. At the mean time, we need to maintain the supercell's neutrality due +to the periodic boundary condition. A distribution of compensating charge thus needs to be +implemented in the vacuum region of surface models when extra electrons are added/extracted from the +system. -The compensating charge implemented in ABACUS follows the [methodology](http://dx.doi.org/10.1103/PhysRevB.89.245406) developed by Brumme, Calandra, and Mauri in 2014. Input parameters that control the compensating charge are listed as follows with detailed explaination provided [here](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#gate-field-compensating-charge): +The compensating charge implemented in ABACUS follows the +[methodology](http://dx.doi.org/10.1103/PhysRevB.89.245406) developed by Brumme, Calandra, and Mauri +in 2014. Input parameters that control the compensating charge are listed as follows with detailed +explaination provided +[here](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#gate-field-compensating-charge): ``` INPUT_PARAMETERS @@ -82,24 +124,42 @@ block_up 0.55 block_height 0.1 ``` -Example of running DFT calculation with the compensating charge is provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/31_comp_charge/01_Pt_slab). +Example of running DFT calculation with the compensating charge is provided in this +[directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/31_comp_charge/01_Pt_slab). ## Van-der-Waals Correction -Conventional DFT functionals often suffer from an inadequate treatment of long-range dispersion, or Van der Waals (VdW) interactions. In order to describe materials where VdW interactions are prominent, one simple and popular approach is to add a Lennard-Jones type term. The resulting VdW-corrected DFT has been proved to be a very effective method for description of both short-range chemical bonding and long-range dispersive interactions. -Currently ABACUS provides three Grimme DFT-D methods, including [D2](https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.20495), [D3(0)](https://aip.scitation.org/doi/10.1063/1.3382344) and [D3(BJ)](https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.21759), to describe Van der Waals interactions. Among them, the D3 method has been implemented in ABACUS based on the -dftd3 [program](https://www.chemie.uni-bonn.de/pctc/mulliken-center/software/dft-d3) written by Stefan Grimme, Stephan Ehrlich and Helge Krieg. +Conventional DFT functionals often suffer from an inadequate treatment of long-range dispersion, or +Van der Waals (VdW) interactions. In order to describe materials where VdW interactions are +prominent, one simple and popular approach is to add a Lennard-Jones type term. The resulting +VdW-corrected DFT has been proved to be a very effective method for description of both short-range +chemical bonding and long-range dispersive interactions. -To use VdW-correction, users need to supply value to the `vdw_method` keyword in the `INPUT` file: +Currently ABACUS provides three Grimme DFT-D methods, including +[D2](https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.20495), +[D3(0)](https://aip.scitation.org/doi/10.1063/1.3382344) and +[D3(BJ)](https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.21759), to describe Van der Waals +interactions. Among them, the D3 method has been implemented in ABACUS based on the dftd3 +[program](https://www.chemie.uni-bonn.de/pctc/mulliken-center/software/dft-d3) written by Stefan +Grimme, Stephan Ehrlich and Helge Krieg. - - (Default) none: no VdW correction - - d2: DFT-D2 method - - d3_0: DFT-D3(0) method - - d3_bj: DFT-D3(BJ) method +To use VdW-correction, users need to supply value to the `vdw_method` keyword in the `INPUT` file: -Furthermore, ABACUS also provides a [list of keywords](../input_files/input-main.md#vdw-correction) to control relevant parmeters used in calculating the VdW correction, such as the scale factor (s6) term. Recommended values of such parameters can be found on the [webpage](https://www.chemie.uni-bonn.de/pctc/mulliken-center/software/dft-d3). The default values of the parameters in ABACUS are set to be the recommended values for PBE. +- (Default) none: no VdW correction +- d2: DFT-D2 method +- d3_0: DFT-D3(0) method +- d3_bj: DFT-D3(BJ) method -Examples of VdW-corrected DFT calculations are provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/25_vdw). There are two input files, where `INPUT1` shows how to apply D2 correction with user-specified $C_6$ parameter, and `INPUT2` shows how to apply D3(BJ) correction with default VdW parameters. +Furthermore, ABACUS also provides a [list of keywords](../input_files/input-main.md#vdw-correction) +to control relevant parmeters used in calculating the VdW correction, such as the scale factor (s6) +term. Recommended values of such parameters can be found on the +[webpage](https://www.chemie.uni-bonn.de/pctc/mulliken-center/software/dft-d3). The default values +of the parameters in ABACUS are set to be the recommended values for PBE. -To run any of the two cases, users may enter the directory, copy the corresponding input file to `INPUT`, and run ABACUS. +Examples of VdW-corrected DFT calculations are provided in this +[directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/25_vdw). There are +two input files, where `INPUT1` shows how to apply D2 correction with user-specified $C_6$ +parameter, and `INPUT2` shows how to apply D3(BJ) correction with default VdW parameters. +To run any of the two cases, users may enter the directory, copy the corresponding input file to +`INPUT`, and run ABACUS. diff --git a/docs/advanced/scf/construct_H.md b/docs/advanced/scf/construct_H.md index 31e42b859d0..a38be02796e 100644 --- a/docs/advanced/scf/construct_H.md +++ b/docs/advanced/scf/construct_H.md @@ -2,81 +2,132 @@ ## Exchange-Correlation Functionals -In our package, the XC functional can be set explicitly using the `dft_functional` keyword in `INPUT` file. If `dft_functional` is not specified, ABACUS will use the xc functional indicated in the pseudopotential file. +In our package, the XC functional can be set explicitly using the `dft_functional` keyword in +`INPUT` file. If `dft_functional` is not specified, ABACUS will use the xc functional indicated in +the pseudopotential file. -Several common functionals are implemented in ABACUS, such as PZ and PBE. Users can check out this [file](https://github.com/deepmodeling/abacus-develop/blob/develop/source/source_hamilt/module_xc/xc_funcs.h) for a complete list of functionals implemented in ABACUS. Furthermore, if ABACUS is compiled with LIBXC, we also support all the LDA, GGA and meta-GGA functionals provided therein. +Several common functionals are implemented in ABACUS, such as PZ and PBE. Users can check out this +[file](https://github.com/deepmodeling/abacus-develop/blob/develop/source/source_hamilt/module_xc/xc_funcs.h) +for a complete list of functionals implemented in ABACUS. Furthermore, if ABACUS is compiled with +LIBXC, we also support all the LDA, GGA and meta-GGA functionals provided therein. -Here, we use a simple [example calculation](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/02_scf/02_lcao_Si2) for illustration. +Here, we use a simple +[example calculation](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/02_scf/02_lcao_Si2) +for illustration. 1. **Default setting:** - In the original `INPUT` file, there is no specification of the `dft_functional` keyword. As a result, we use the default option, that is to use the xc functional in the pseudopotential file, `Si.pz-vbc.UPF`. We can take a look at the first few lines of the `` section from the pseudopotential file: + In the original `INPUT` file, there is no specification of the `dft_functional` keyword. As a + result, we use the default option, that is to use the xc functional in the pseudopotential file, + `Si.pz-vbc.UPF`. We can take a look at the first few lines of the `` section from the + pseudopotential file: - ``` - - 0 Version Number - Si Element - NC Norm - Conserving pseudopotential - F Nonlinear Core Correction - SLA PZ NOGX NOGC PZ Exchange-Correlation functional - ``` + ``` + + 0 Version Number + Si Element + NC Norm - Conserving pseudopotential + F Nonlinear Core Correction + SLA PZ NOGX NOGC PZ Exchange-Correlation functional + ``` - From the line commented 'Exchange-Correlation functional', we see that this pseudopotential is generated using PZ functional. As a result, if we run ABACUS with the original setting, PZ functional will be used. + From the line commented 'Exchange-Correlation functional', we see that this pseudopotential is + generated using PZ functional. As a result, if we run ABACUS with the original setting, PZ + functional will be used. - > Note : for systems with multiple elements, if no `dft_functional` is specified, users should make sure that all pseudopotentials are using the same functional. Otherwise, the type of xc functional should be specified explicitly. + > Note : for systems with multiple elements, if no `dft_functional` is specified, users should + > make sure that all pseudopotentials are using the same functional. Otherwise, the type of xc + > functional should be specified explicitly. -2. **Using PBE** +1. **Using PBE** - On the other hand, users might also explicitly specify the xc functional through `dft_functional` parameter. For example, to use PBE functional, add the following line to `INPUT` file and rerun the calculation: + On the other hand, users might also explicitly specify the xc functional through `dft_functional` + parameter. For example, to use PBE functional, add the following line to `INPUT` file and rerun + the calculation: - ``` - dft_functional PBE - ``` + ``` + dft_functional PBE + ``` -3. **More functionals from LIBXC** +1. **More functionals from LIBXC** - ABACUS has its own implementation of the PBE functional as well as a few others, but our list is far from comprehensive. However, if ABACUS is compiled with LIBXC, we also support all the LDA, GGA and meta-GGA functionals provided therein. + ABACUS has its own implementation of the PBE functional as well as a few others, but our list is + far from comprehensive. However, if ABACUS is compiled with LIBXC, we also support all the LDA, + GGA and meta-GGA functionals provided therein. - For this part, users should compile the ABACUS code with LIBXC linked (version 5.1.7 or higher). + For this part, users should compile the ABACUS code with LIBXC linked (version 5.1.7 or higher). - To use SCAN functional, make the following modification to the `INPUT` file: + To use SCAN functional, make the following modification to the `INPUT` file: - ``` - dft_functional SCAN - ``` - - Note that in the case of PBE and SCAN, we are using 'short-hand' names to represent the entire functional, which is made up of individual exchange and correlation components. A complete list of 'short-hand' expressions supported by ABACUS can be found in [source code](../../../source/source_hamilt/module_xc/xc_functional.cpp). + ``` + dft_functional SCAN + ``` - Apart from the 'short-hand' names, ABACUS also allow supplying exchange-correlation functionals as combinations of LIBXC keywords for functional components, joined by plus sign, for example, setting: + Note that in the case of PBE and SCAN, we are using 'short-hand' names to represent the entire + functional, which is made up of individual exchange and correlation components. A complete list + of 'short-hand' expressions supported by ABACUS can be found in + [source code](../../../source/source_hamilt/module_xc/xc_functional.cpp). - ``` - dft_functional LDA_X_YUKAWA+LDA_C_1D_CSC - ``` - means we are using the short-range Yukawa attenuated exchange along with the Casula, Sorella & Senatore LDA correlation functional. + Apart from the 'short-hand' names, ABACUS also allow supplying exchange-correlation functionals + as combinations of LIBXC keywords for functional components, joined by plus sign, for example, + setting: - The list of LIBXC keywords can be found on its [website](https://www.tddft.org/programs/libxc/functionals/). + ``` + dft_functional LDA_X_YUKAWA+LDA_C_1D_CSC + ``` -4. **Temperature-dependent functional** + means we are using the short-range Yukawa attenuated exchange along with the Casula, Sorella & + Senatore LDA correlation functional. - In ABACUS, we provide temperature-dependent functionals through LIBXC. For such functionals, the keyword `xc_temperature` (unit is Rydberg) is used to specify the temperature, such as the following: + The list of LIBXC keywords can be found on its + [website](https://www.tddft.org/programs/libxc/functionals/). - ``` - dft_functional LDA_XC_CORRKSDT - xc_temperature 10 - ``` +1. **Temperature-dependent functional** -5. **Hybrid functional** + In ABACUS, we provide temperature-dependent functionals through LIBXC. For such functionals, the + keyword `xc_temperature` (unit is Rydberg) is used to specify the temperature, such as the + following: - ABACUS supports functionals with exact Hartree-Fock exchange in LCAO basis set only. The old INPUT parameter exx_hybrid_type for hybrid functionals has been absorbed into `dft_functional`. Options are `hf` (pure Hartree-Fock), `pbe0`(PBE0), `hse`, and `scan0`(SCAN0) (Note: in order to use HSE or SCAN0 functional, LIBXC is required). Note also that only HSE has been tested while other hybrid functionals have NOT been fully tested yet, and the maximum parallel cpus for running exx is N^4, with N being the number of atoms. + ``` + dft_functional LDA_XC_CORRKSDT + xc_temperature 10 + ``` - More information on the hybrid functional can be found from the section [Exact Exchange](../input_files/input-main.md#exact-exchange-common) in the list of input variables for more information. +1. **Hybrid functional** - An example HSE calculation is provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/20_hybrid/02_lcao_Si2). Apart from the input files (`INPUT`, `STRU`, `KPT`), we further provide two files: running_scf.log_ref and log_ref, which contains reference for running_scf.log and standard output from the program, respectively. - -## DFT+*U* + ABACUS supports functionals with exact Hartree-Fock exchange in LCAO basis set only. The old + INPUT parameter exx_hybrid_type for hybrid functionals has been absorbed into `dft_functional`. + Options are `hf` (pure Hartree-Fock), `pbe0`(PBE0), `hse`, and `scan0`(SCAN0) (Note: in order to + use HSE or SCAN0 functional, LIBXC is required). Note also that only HSE has been tested while + other hybrid functionals have NOT been fully tested yet, and the maximum parallel cpus for + running exx is N^4, with N being the number of atoms. + + More information on the hybrid functional can be found from the section + [Exact Exchange](../input_files/input-main.md#exact-exchange-common) in the list of input + variables for more information. -Conventional functionals, e.g., L(S)DA and GGAs, encounter failures in strongly correlated systems, usually characterized by partially filled *d*/*f* shells. These include transition metals (TM) and their oxides, rare-earth compounds, and actinides, to name a few, where L(S)DA/GGAs typically yield quantitatively or even qualitatively wrong results. To address this failure, an efficient and successful method named DFT+*U*, which inherits the efficiency of L(S)DA/GGA but gains the strength of the Hubbard model in describing the physics of strongly correlatedsystems, has been developed. + An example HSE calculation is provided in this + [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/20_hybrid/02_lcao_Si2). + Apart from the input files (`INPUT`, `STRU`, `KPT`), we further provide two files: + running_scf.log_ref and log_ref, which contains reference for running_scf.log and standard output + from the program, respectively. -Now the DFT+*U* method is accessible in ABACUS. The details of the DFT+*U* method could be found in this [paper](https://doi.org/10.1063/5.0090122). It should be noted that the DFT+*U* works only within the NAO scheme, which means that the value of the keyword `basis_type` must be lcao when DFT+*U* is called. To turn on DFT+*U*, users need to set the value of the `dft_plus_u` keyword in the `INPUT` file to be 1. All relevant parmeters used in DFT+*U* calculations are listed in the [DFT+*U* correction](../input_files/input-main.md#dftu-correction) part of the [list of keywords](../input_files/input-main.md). +## DFT+*U* -Examples of DFT+*U* calculations are provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/19_dftu). +Conventional functionals, e.g., L(S)DA and GGAs, encounter failures in strongly correlated systems, +usually characterized by partially filled *d*/*f* shells. These include transition metals (TM) and +their oxides, rare-earth compounds, and actinides, to name a few, where L(S)DA/GGAs typically yield +quantitatively or even qualitatively wrong results. To address this failure, an efficient and +successful method named DFT+*U*, which inherits the efficiency of L(S)DA/GGA but gains the strength +of the Hubbard model in describing the physics of strongly correlatedsystems, has been developed. + +Now the DFT+*U* method is accessible in ABACUS. The details of the DFT+*U* method could be found in +this [paper](https://doi.org/10.1063/5.0090122). It should be noted that the DFT+*U* works only +within the NAO scheme, which means that the value of the keyword `basis_type` must be lcao when +DFT+*U* is called. To turn on DFT+*U*, users need to set the value of the `dft_plus_u` keyword in +the `INPUT` file to be 1. All relevant parmeters used in DFT+*U* calculations are listed in the +[DFT+*U* correction](../input_files/input-main.md#dftu-correction) part of the +[list of keywords](../input_files/input-main.md). + +Examples of DFT+*U* calculations are provided in this +[directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/19_dftu). diff --git a/docs/advanced/scf/converge.md b/docs/advanced/scf/converge.md index fca624d9aec..62df29db342 100644 --- a/docs/advanced/scf/converge.md +++ b/docs/advanced/scf/converge.md @@ -1,31 +1,68 @@ # Converging SCF -As in any non-linear systems, numerical instabilities during SCF iterations may lead to nonconvergence. In ABACUS, we offer the following options to facilitate SCF convergence. +As in any non-linear systems, numerical instabilities during SCF iterations may lead to +nonconvergence. In ABACUS, we offer the following options to facilitate SCF convergence. ## Charge Mixing -In ABACUS, KS-DFT is solved by self-consistent field (SCF) iteration method. By mixing the electron density with that obtained from previous steps, numerical instabilities can be ameliorated while also accelerating convergence. ABACUS offers several mixing schemes, and users may make a selection by adjusting the [mixing_type](../input_files/input-main.md#mixing_type) keyword in INPUT file. +In ABACUS, KS-DFT is solved by self-consistent field (SCF) iteration method. By mixing the electron +density with that obtained from previous steps, numerical instabilities can be ameliorated while +also accelerating convergence. ABACUS offers several mixing schemes, and users may make a selection +by adjusting the [mixing_type](../input_files/input-main.md#mixing_type) keyword in INPUT file. -For each of the mixing types, we also provide variables for controlling relevant parameters, including `mixing_ndim`, `mixing_type`, `mixing_beta`, `mixing_gg0`, `mixing_beta_mag`, `mixing_gg0_mag`, `mixing_gg0_min`, `mixing_angle`. +For each of the mixing types, we also provide variables for controlling relevant parameters, +including `mixing_ndim`, `mixing_type`, `mixing_beta`, `mixing_gg0`, `mixing_beta_mag`, +`mixing_gg0_mag`, `mixing_gg0_min`, `mixing_angle`. -`mixing_ndim` is the mixing dimensions in DIIS (broyden or pulay) mixing. Gerenally, a larger `mixing_ndim` leads to a better convergence. the default choice `mixing_ndim=8` should work fine in most cases. For `mixing_type`, the default choice is `broyden`, which is slightly better than `Pulay` typically. Besides that, a large `mixing_beta` means a larger change in electron density for each SCF step. For well-behaved systems, a larger `mixing_beta` leads to faster convergence. However, for some difficult cases, a smaller `mixing_beta` is preferred to avoid numerical instabilities. +`mixing_ndim` is the mixing dimensions in DIIS (broyden or pulay) mixing. Gerenally, a larger +`mixing_ndim` leads to a better convergence. the default choice `mixing_ndim=8` should work fine in +most cases. For `mixing_type`, the default choice is `broyden`, which is slightly better than +`Pulay` typically. Besides that, a large `mixing_beta` means a larger change in electron density for +each SCF step. For well-behaved systems, a larger `mixing_beta` leads to faster convergence. +However, for some difficult cases, a smaller `mixing_beta` is preferred to avoid numerical +instabilities. -For most isolated systems, Kerker preconditioning is unnecessary. You can turn off it by setting `mixing_gg0 0.0` to get a faster convergence. +For most isolated systems, Kerker preconditioning is unnecessary. You can turn off it by setting +`mixing_gg0 0.0` to get a faster convergence. -For non-spin-polarized calculations, the default choices usually achieve convergence. If convergence issue arises in metallic systems, you can try different value of Kerker preconditioning [mixing_gg0](../input_files/input-main.md#mixing_gg0) and [mixing_gg0_min](../input_files/input-main.md#mixing_gg0_min), and try to reduce `mixing_beta`, which is 0.8 defaultly for `nspin=1`. +For non-spin-polarized calculations, the default choices usually achieve convergence. If convergence +issue arises in metallic systems, you can try different value of Kerker preconditioning +[mixing_gg0](../input_files/input-main.md#mixing_gg0) and +[mixing_gg0_min](../input_files/input-main.md#mixing_gg0_min), and try to reduce `mixing_beta`, +which is 0.8 defaultly for `nspin=1`. -For magnetic calculations, `mixing_beta_mag` and `mixing_gg0_mag` are activated. Considering collinear calculations, you can rely on the default value for most cases. If convergence issue arises, you can try to reduce `mixing_beta` and `mixing_beta_mag` together. For non-collinear calculations, tradtional broyden usually works, especially for a given magnetic configuration. If one is not interested in the energies of a given magnetic configuration but wants to determine the ground state by relaxing the magnetic momentsโ€™ directions, the standard Broyden mixing algorithm sometimes fails to find the correct magnetic configuration. If so, we can set [mixing_angle=1.0](../input_files/input-main.md#mixing_angle), which is a promising mixing method proposed by J. Phys. Soc. Jpn. 82 (2013) 114706. +For magnetic calculations, `mixing_beta_mag` and `mixing_gg0_mag` are activated. Considering +collinear calculations, you can rely on the default value for most cases. If convergence issue +arises, you can try to reduce `mixing_beta` and `mixing_beta_mag` together. For non-collinear +calculations, tradtional broyden usually works, especially for a given magnetic configuration. If +one is not interested in the energies of a given magnetic configuration but wants to determine the +ground state by relaxing the magnetic momentsโ€™ directions, the standard Broyden mixing algorithm +sometimes fails to find the correct magnetic configuration. If so, we can set +[mixing_angle=1.0](../input_files/input-main.md#mixing_angle), which is a promising mixing method +proposed by J. Phys. Soc. Jpn. 82 (2013) 114706. -An example showcasing different charge mixing methods can be found in our [repository](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/07_charge_mixing/01_pw_Al). Four INPUT files are provided, with description given in README. +An example showcasing different charge mixing methods can be found in our +[repository](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/07_charge_mixing/01_pw_Al). +Four INPUT files are provided, with description given in README. -As for DFT+U calculations, where the hamiltonian is not only dependent on charge density, but also dependent on density matrix. You can try `mixing_restart>0` and `mixing_dmr=1` to improve convergence. For case extremely hard to converge, you can use so-called U-Ramping method by setting a finite positive `uramping` with `mixing_restart>0` and `mixing_dmr=1`. +As for DFT+U calculations, where the hamiltonian is not only dependent on charge density, but also +dependent on density matrix. You can try `mixing_restart>0` and `mixing_dmr=1` to improve +convergence. For case extremely hard to converge, you can use so-called U-Ramping method by setting +a finite positive `uramping` with `mixing_restart>0` and `mixing_dmr=1`. ## Smearing -Thermal smearing is an efficient tool for accelerating SCF convergence by allowing fractional occupation of molecular orbitals near the band edge. It is important for metallic systems. +Thermal smearing is an efficient tool for accelerating SCF convergence by allowing fractional +occupation of molecular orbitals near the band edge. It is important for metallic systems. -In ABACUS, we provide a few smearing methods, which can be controlled using the keyword [smearing_method](../input_files/input-main.md#smearing_method). We also provide keyword `smearing_sigma` or `smearing_sigma_temp` to control the energy range of smearing. A larger value of smearing sigma leads to a more diffused occupation curve. +In ABACUS, we provide a few smearing methods, which can be controlled using the keyword +[smearing_method](../input_files/input-main.md#smearing_method). We also provide keyword +`smearing_sigma` or `smearing_sigma_temp` to control the energy range of smearing. A larger value of +smearing sigma leads to a more diffused occupation curve. -> Note : The two keywords `smearing_sigma` and `smearing_sigma_temp` should not be used concurrently. +> Note : The two keywords `smearing_sigma` and `smearing_sigma_temp` should not be used +> concurrently. -We provide an example showing the importance of smearing in our [repository](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/06_smearing/01_lcao_Fe). Two INPUT fiels rae provided, with description given in README. \ No newline at end of file +We provide an example showing the importance of smearing in our +[repository](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/06_smearing/01_lcao_Fe). +Two INPUT fiels rae provided, with description given in README. diff --git a/docs/advanced/scf/hsolver.md b/docs/advanced/scf/hsolver.md index cc85b4d87be..84d0c8ff8e9 100644 --- a/docs/advanced/scf/hsolver.md +++ b/docs/advanced/scf/hsolver.md @@ -4,31 +4,55 @@ Method of explicit solving KS-equation can be chosen by variable "ks_solver" in INPUT file. -When "basis_type = pw", `ks_solver` can be `cg`, `bpcg` or `dav`. The default setting `cg` is recommended, which is band-by-band conjugate gradient diagonalization method. There is a large probability that the use of setting of `dav` , which is block Davidson diagonalization method, can be tried to improve performance. +When "basis_type = pw", `ks_solver` can be `cg`, `bpcg` or `dav`. The default setting `cg` is +recommended, which is band-by-band conjugate gradient diagonalization method. There is a large +probability that the use of setting of `dav` , which is block Davidson diagonalization method, can +be tried to improve performance. -When "basis_type = lcao", `ks_solver` can be `genelpa` or `scalapack_gvx`. The default setting `genelpa` is recommended, which is based on ELPA (EIGENVALUE SOLVERS FOR PETAFLOP APPLICATIONS) (https://elpa.mpcdf.mpg.de/) and the kernel is auto choosed by GENELPA(https://github.com/pplab/GenELPA), usually faster than the setting of "scalapack_gvx", which is based on ScaLAPACK(Scalable Linear Algebra PACKage) +When "basis_type = lcao", `ks_solver` can be `genelpa` or `scalapack_gvx`. The default setting +`genelpa` is recommended, which is based on ELPA (EIGENVALUE SOLVERS FOR PETAFLOP APPLICATIONS) +(https://elpa.mpcdf.mpg.de/) and the kernel is auto choosed by +GENELPA(https://github.com/pplab/GenELPA), usually faster than the setting of "scalapack_gvx", which +is based on ScaLAPACK(Scalable Linear Algebra PACKage) ## Stochasic DFT -We support stochastic DFT calculation (SDFT) or mixed stochastic-deterministic DFT (MDFT) with plane-wave basis [[Phys. Rev. B 106, 125132 (2022)](https://doi.org/10.1103/PhysRevB.106.125132)]. Different from traditional KSDFT with the explicit diagonalization method, SDFT and MDFT calculate physical quantities with trace of the corresponding operators. The advantages of SDFT and MDFT compared to the traditional KSDFT are the ability to simulate larger sizes and higher temperatures. In our package, SDFT and MDFT can be used by setting the `esolver_type` parameter to `sdft` for SCF calculations or MD calculations. To start with, you can refer to two [examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/23_sdft) and an explanation of the [input variables](../input_files/input-main.md#electronic-structure-sdft). + +We support stochastic DFT calculation (SDFT) or mixed stochastic-deterministic DFT (MDFT) with +plane-wave basis \[[Phys. Rev. B 106, 125132 (2022)](https://doi.org/10.1103/PhysRevB.106.125132)\]. +Different from traditional KSDFT with the explicit diagonalization method, SDFT and MDFT calculate +physical quantities with trace of the corresponding operators. The advantages of SDFT and MDFT +compared to the traditional KSDFT are the ability to simulate larger sizes and higher temperatures. +In our package, SDFT and MDFT can be used by setting the `esolver_type` parameter to `sdft` for SCF +calculations or MD calculations. To start with, you can refer to two +[examples](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/23_sdft) and an +explanation of the [input variables](../input_files/input-main.md#electronic-structure-sdft). When we have a hamiltonian, the electronic density can be calculated with: -$\rho(\mathbf{r})={\rm Tr}[f(\hat{H})\ket{\mathbf{r}}\bra{\mathbf{r}}]$, +$\\rho(\\mathbf{r})={\\rm Tr}[f(\\hat{H})\\ket{\\mathbf{r}}\\bra{\\mathbf{r}}]$, -where the Fermi-Dirac function $f(\hat{H})=\frac{1}{1+\exp(\frac{\hat{H}-\mu}{kT})}$ and it can be calculated with the Chebyshev expansion. Here we only support the "fd" or "fermi-dirac" `smearing_method`, the parameter `smearing_sigma` is equal the temperature $T$ (in Ry) and `nche_sto` represents the order of the expansion. +where the Fermi-Dirac function $f(\\hat{H})=\\frac{1}{1+\\exp(\\frac{\\hat{H}-\\mu}{kT})}$ and it +can be calculated with the Chebyshev expansion. Here we only support the "fd" or "fermi-dirac" +`smearing_method`, the parameter `smearing_sigma` is equal the temperature $T$ (in Ry) and +`nche_sto` represents the order of the expansion. -For physical quantities represented by operator $\hat{O}$, SDFT calculates its trace with: +For physical quantities represented by operator $\\hat{O}$, SDFT calculates its trace with: -${\rm Tr}[\hat{O}]=\sum_{i=1}^{N_\chi}{\bra{\chi_i}\hat{O}\ket{\chi_i}}$, +${\\rm Tr}[\\hat{O}]=\\sum\_{i=1}^{N\_\\chi}{\\bra{\\chi_i}\\hat{O}\\ket{\\chi_i}}$, while MDFT calculates the trace as: -${\rm Tr}[\hat{O}]=\sum_{n=1}^{N_\phi}{\bra{\phi_n}\hat{O}\ket{\phi_n}}+\sum_{i=1}^{N_\chi}{\bra{\tilde \chi_i}\hat{O}\ket{\tilde \chi_i}}$, +${\\rm +Tr}[\\hat{O}]=\\sum\_{n=1}^{N\_\\phi}{\\bra{\\phi_n}\\hat{O}\\ket{\\phi_n}}+\\sum\_{i=1}^{N\_\\chi}{\\bra{\\tilde +\\chi_i}\\hat{O}\\ket{\\tilde \\chi_i}}$, -where $\{\ket{\tilde\chi_i}\}$ are obtaiend by projecting stochastic orbitals onto the subspace orthogonal to KS orbitals $\{\phi_n\}$: +where ${\\ket{\\tilde\\chi_i}}$ are obtaiend by projecting stochastic orbitals onto the subspace +orthogonal to KS orbitals ${\\phi_n}$: -$\ket{\tilde\chi_i}=\ket{\chi_i}-\sum_{n=1}^{N_\phi}\braket{\phi_n|\chi_i}\ket{\phi_n}$. +$\\ket{\\tilde\\chi_i}=\\ket{\\chi_i}-\\sum\_{n=1}^{N\_\\phi}\\braket{\\phi_n|\\chi_i}\\ket{\\phi_n}$. -Here the number of KS orbitals $N_\phi$ is controlled by the parameter `nbands` while the number of stochastic orbitals $N_\chi$ is controlled by `nbands_sto`. +Here the number of KS orbitals $N\_\\phi$ is controlled by the parameter `nbands` while the number +of stochastic orbitals $N\_\\chi$ is controlled by `nbands_sto`. -Besides, although SDFT does not diagonalize the hamiltonian, it can also caluclate DOS and electronic conductivities with parameters `out_dos` and `cal_cond` separately. +Besides, although SDFT does not diagonalize the hamiltonian, it can also caluclate DOS and +electronic conductivities with parameters `out_dos` and `cal_cond` separately. diff --git a/docs/advanced/scf/initialization.md b/docs/advanced/scf/initialization.md index 427146bf223..2c8247a7f72 100644 --- a/docs/advanced/scf/initialization.md +++ b/docs/advanced/scf/initialization.md @@ -1,33 +1,66 @@ # Initializing SCF -Good initializing would abate the number of iteration steps in SCF. -Charge density should be initialed for constructing the initial hamiltonian operator. -In PW basis, wavefunction should be initialized for iterate diagonalization method. -In LCAO basis, wavefunction can be read to calculate initial charge density. The wavefunction itself does not have to be initialized. +Good initializing would abate the number of iteration steps in SCF. Charge density should be +initialed for constructing the initial hamiltonian operator. + +In PW basis, wavefunction should be initialized for iterate diagonalization method. In LCAO basis, +wavefunction can be read to calculate initial charge density. The wavefunction itself does not have +to be initialized. ## Charge Density + `init_chg` is used for choosing the method of charge density initialization. - - `atomic` : initial charge density by atomic charge density from pseudopotential file under keyword `PP_RHOATOM` - - `file` : initial charge density from files produced by previous calculations with [`out_chg 1`](../elec_properties/charge.md). - - `auto`: Abacus first attempts to read the density from a file; if not found, it defaults to using atomic density. - - `dm` (LCAO only): initial charge density from density matrix files in CSR format. For `nspin=1`, reads `dmrs1_nao.csr`. For `nspin=2` (spin-polarized), reads both `dmrs1_nao.csr` (spin-up) and `dmrs2_nao.csr` (spin-down). These files are generated by previous calculations with [`out_dmr 1`](../elec_properties/density_matrix.md). This method is particularly useful for restarting spin-polarized calculations. - - `hr` (LCAO only): initial charge density from Hamiltonian matrix files in CSR format. The Hamiltonian is read from file, then diagonalized to obtain wavefunctions and charge density. For `nspin=1`, reads `hrs1_nao.csr`. For `nspin=2` (spin-polarized), reads both `hrs1_nao.csr` (spin-up) and `hrs2_nao.csr` (spin-down). These files are generated by previous calculations with [`out_hsr 1`](../input_files/input-main.md#out_hsr). + +- `atomic` : initial charge density by atomic charge density from pseudopotential file under keyword + `PP_RHOATOM` +- `file` : initial charge density from files produced by previous calculations with + [`out_chg 1`](../elec_properties/charge.md). +- `auto`: Abacus first attempts to read the density from a file; if not found, it defaults to using + atomic density. +- `dm` (LCAO only): initial charge density from density matrix files in CSR format. For `nspin=1`, + reads `dmrs1_nao.csr`. For `nspin=2` (spin-polarized), reads both `dmrs1_nao.csr` (spin-up) and + `dmrs2_nao.csr` (spin-down). These files are generated by previous calculations with + [`out_dmr 1`](../elec_properties/density_matrix.md). This method is particularly useful for + restarting spin-polarized calculations. +- `hr` (LCAO only): initial charge density from Hamiltonian matrix files in CSR format. The + Hamiltonian is read from file, then diagonalized to obtain wavefunctions and charge density. For + `nspin=1`, reads `hrs1_nao.csr`. For `nspin=2` (spin-polarized), reads both `hrs1_nao.csr` + (spin-up) and `hrs2_nao.csr` (spin-down). These files are generated by previous calculations with + [`out_hsr 1`](../input_files/input-main.md#out_hsr). ## Wavefunction -`init_wfc` selects how wavefunction coefficients are initialized. The available options and behavior depend on `basis_type`. +`init_wfc` selects how wavefunction coefficients are initialized. The available options and behavior +depend on `basis_type`. For `basis_type=pw`, the available options are: -* `atomic`: Use atomic pseudo wavefunctions from `PP_PSWFC`. If no `PP_PSWFC` states are available, all bands are initialized randomly. If the number of atomic states is smaller than `nbands`, the remaining bands are initialized randomly. -* `atomic+random`: If there are at least `nbands` atomic states, apply an approximately 5% multiplicative random perturbation to the atomic initialization. If there are fewer atomic states than `nbands`, use the atomic states and initialize the remaining bands randomly, as for `atomic`. -* `random`: Initialize all bands with random coefficients. -* `nao`: Use numerical atomic orbitals. If the number of NAO states is smaller than `nbands`, the remaining bands are initialized randomly. -* `nao+random`: Apply an approximately 5% multiplicative random perturbation to the NAO initialization; any bands not covered by NAO states are first initialized randomly. -* `file binary`: Read binary `wf*_pw.dat` files generated with [`out_wfc_pw=2`](../elec_properties/wfc.md) from `read_file_dir`. The files must match the current k points, `nbands`, plane-wave layout, and lattice. The `txt` format is not supported for PW wavefunctions. +- `atomic`: Use atomic pseudo wavefunctions from `PP_PSWFC`. If no `PP_PSWFC` states are available, + all bands are initialized randomly. If the number of atomic states is smaller than `nbands`, the + remaining bands are initialized randomly. +- `atomic+random`: If there are at least `nbands` atomic states, apply an approximately 5% + multiplicative random perturbation to the atomic initialization. If there are fewer atomic states + than `nbands`, use the atomic states and initialize the remaining bands randomly, as for `atomic`. +- `random`: Initialize all bands with random coefficients. +- `nao`: Use numerical atomic orbitals. If the number of NAO states is smaller than `nbands`, the + remaining bands are initialized randomly. +- `nao+random`: Apply an approximately 5% multiplicative random perturbation to the NAO + initialization; any bands not covered by NAO states are first initialized randomly. +- `file binary`: Read binary `wf*_pw.dat` files generated with + [`out_wfc_pw=2`](../elec_properties/wfc.md) from `read_file_dir`. The files must match the current + k points, `nbands`, plane-wave layout, and lattice. The `txt` format is not supported for PW + wavefunctions. -For `basis_type=lcao`, use `init_wfc file txt` to read text `wf*_nao.txt` files generated with [`out_wfc_lcao=1`](../elec_properties/wfc.md), or `init_wfc file binary` to read binary `wf*_nao.dat` files generated with `out_wfc_lcao=2`, from `read_file_dir`. LCAO wavefunctions initialize the density matrix and real-space charge density. The selected format is required; ABACUS does not automatically detect or fall back to the other format. The files must use a compatible NAO basis, match the current k-point and spin setup, and contain enough bands. Only independent files without geometry-step indices are supported, not files accumulated with `out_app_flag`. +For `basis_type=lcao`, use `init_wfc file txt` to read text `wf*_nao.txt` files generated with +[`out_wfc_lcao=1`](../elec_properties/wfc.md), or `init_wfc file binary` to read binary +`wf*_nao.dat` files generated with `out_wfc_lcao=2`, from `read_file_dir`. LCAO wavefunctions +initialize the density matrix and real-space charge density. The selected format is required; ABACUS +does not automatically detect or fall back to the other format. The files must use a compatible NAO +basis, match the current k-point and spin setup, and contain enough bands. Only independent files +without geometry-step indices are supported, not files accumulated with `out_app_flag`. For `basis_type=lcao_in_pw`, `init_wfc` is automatically set to `nao`. -For `calculation=get_wf` or `calculation=get_pchg`, a non-file initialization choice is automatically changed to the file option appropriate for the selected basis. An explicitly selected file format is preserved. If `basis_type=lcao_in_pw` is also used, the final value is `nao`. +For `calculation=get_wf` or `calculation=get_pchg`, a non-file initialization choice is +automatically changed to the file option appropriate for the selected basis. An explicitly selected +file format is preserved. If `basis_type=lcao_in_pw` is also used, the final value is `nao`. diff --git a/docs/advanced/scf/performance.md b/docs/advanced/scf/performance.md index 49e9d38d4dd..2972c36de7c 100644 --- a/docs/advanced/scf/performance.md +++ b/docs/advanced/scf/performance.md @@ -1,31 +1,47 @@ # Accelerating the Calculation -In ABACUS, we provide a few methods for accelerating the calculation. The parameters are usually set as default for calculations where there is not extreme concern for efficiency, as some of them may produce numerical issues under certain circumstances. In short, methods in this section should be used with care. It is better to calibrate the results against the default setting. +In ABACUS, we provide a few methods for accelerating the calculation. The parameters are usually set +as default for calculations where there is not extreme concern for efficiency, as some of them may +produce numerical issues under certain circumstances. In short, methods in this section should be +used with care. It is better to calibrate the results against the default setting. ## K-point Parallelization -In ABACUS, we offer k-point parallelization for calculations with PW basis, which should increase the efficiency when a large k-point mesh is used. +In ABACUS, we offer k-point parallelization for calculations with PW basis, which should increase +the efficiency when a large k-point mesh is used. -To use k-point parallelization, users may set keyword [kpar](../input_files/input-main.md#kpar) to be larger than 1. +To use k-point parallelization, users may set keyword [kpar](../input_files/input-main.md#kpar) to +be larger than 1. -> Note: It has been observed that k-point parallelization cannot work in conjunction with Davidson diagonalization. +> Note: It has been observed that k-point parallelization cannot work in conjunction with Davidson +> diagonalization. ## K-point Symmetry -Inclusion of k-point symmetry helps increasing the efficiency of calculations by reducing the effective number of k-points used. To turn on k-point symmetry, users may set keyword [symmetry](../input_files/input-main.md#symmetry) to be 1. +Inclusion of k-point symmetry helps increasing the efficiency of calculations by reducing the +effective number of k-points used. To turn on k-point symmetry, users may set keyword +[symmetry](../input_files/input-main.md#symmetry) to be 1. > Note: In ABACUS we only support point-group symmetry but not space-group symmetry. ## Accelerating Grid Integration -For LCAO calculation, the matrix elements of the local potential is evaluated using grid integration. In grid integration, we group real-space FFT grid points into boxes of dimension bx * by * bz, and then proceed with the boxes as the basis unit of calculation. +For LCAO calculation, the matrix elements of the local potential is evaluated using grid +integration. In grid integration, we group real-space FFT grid points into boxes of dimension bx \* +by * bz, and then proceed with the boxes as the basis unit of calculation. -Setting [bx](../input_files/input-main.md#bx), [by](../input_files/input-main.md#by), and [bz](../input_files/input-main.md#bz) to values other than default might help with the efficiency of grid integration. +Setting [bx](../input_files/input-main.md#bx), [by](../input_files/input-main.md#by), and +[bz](../input_files/input-main.md#bz) to values other than default might help with the efficiency of +grid integration. -> Note: the choice of bx, by, bz should be integer factors of the dimension of the real space FFT grid in each direction. +> Note: the choice of bx, by, bz should be integer factors of the dimension of the real space FFT +> grid in each direction. ## Low Dimension Materials -In grid integration, we chose to parallelize the grid points along the z direction. Therefore, when using LCAO calculation for low dimension materials, it is recommended to put the material more evenly in z direction to avoid imbalanced workload on different MPI threads. +In grid integration, we chose to parallelize the grid points along the z direction. Therefore, when +using LCAO calculation for low dimension materials, it is recommended to put the material more +evenly in z direction to avoid imbalanced workload on different MPI threads. -Namely, when calculating 2D materials, it is better to put the material in xz or yz direction; while for 1D materials, it is better to align the material with the z direction. \ No newline at end of file +Namely, when calculating 2D materials, it is better to put the material in xz or yz direction; while +for 1D materials, it is better to align the material with the z direction. diff --git a/docs/advanced/scf/spin.md b/docs/advanced/scf/spin.md index 40f349a43e2..1ac8bdcee4c 100644 --- a/docs/advanced/scf/spin.md +++ b/docs/advanced/scf/spin.md @@ -1,83 +1,117 @@ # Spin-polarization and SOC ## Non-spin-polarized Calculations -Setting of **"nspin 1"** in INPUT file means calculation with non-polarized spin. -In this case, electrons with spin up and spin down have same occupations at every energy states, weights of bands per k point would be double. + +Setting of **"nspin 1"** in INPUT file means calculation with non-polarized spin. In this case, +electrons with spin up and spin down have same occupations at every energy states, weights of bands +per k point would be double. ## Collinear Spin Polarized Calculations -Setting of **"nspin 2"** in INPUT file means calculation with polarized spin along z-axis. -In this case, electrons with spin up and spin down will be calculated respectively, number of k points would be doubled. -Potential of electron and charge density will separate to spin-up case and spin-down case. -Magnetic moment Settings in [STRU files](../input_files/stru.md) are not ignored until **"nspin 2"** is set in INPUT file +Setting of **"nspin 2"** in INPUT file means calculation with polarized spin along z-axis. In this +case, electrons with spin up and spin down will be calculated respectively, number of k points would +be doubled. Potential of electron and charge density will separate to spin-up case and spin-down +case. + +Magnetic moment Settings in [STRU files](../input_files/stru.md) are not ignored until **"nspin 2"** +is set in INPUT file When **"nspin 2"** is set, the screen output file will contain magnetic moment information. e.g. + ``` ITER TMAG AMAG ETOT(eV) EDIFF(eV) DRHO TIME(s) GE1 4.16e+00 4.36e+00 -6.440173e+03 0.000000e+00 6.516e-02 1.973e+01 ``` -where "TMAG" refers to total magnetization and "AMAG" refers to average magnetization. -For more detailed orbital magnetic moment information, please use [Mulliken charge analysis](../elec_properties/Mulliken.md). + +where "TMAG" refers to total magnetization and "AMAG" refers to average magnetization. For more +detailed orbital magnetic moment information, please use +[Mulliken charge analysis](../elec_properties/Mulliken.md). ### Constraint DFT for collinear spin polarized calculations + For some special need, there are two method to constrain electronic spin. -1. **"ocp"** and **"ocp_set"** -If **"ocp=1"** and **"ocp_set"** is set in INPUT file, the occupations of states would be fixed by **"ocp_set"**, this method is often used for excited states calculation. Be careful that: when **"nspin=1"**, spin-up and spin-down electrons will both be set, and when **"nspin=2"**, you should set spin-up and spin-down respectively. +1. **"ocp"** and **"ocp_set"** If **"ocp=1"** and **"ocp_set"** is set in INPUT file, the + occupations of states would be fixed by **"ocp_set"**, this method is often used for excited + states calculation. Be careful that: when **"nspin=1"**, spin-up and spin-down electrons will + both be set, and when **"nspin=2"**, you should set spin-up and spin-down respectively. -2. **"nupdown"** -If **"nupdown"** is set to non-zero, number of spin-up and spin-down electrons will be fixed, and Fermi energy level will split to E_Fermi_up and E_Fermi_down. By the way, total magnetization will also be fixed, and will be the value of **"nupdown"**. +1. **"nupdown"** If **"nupdown"** is set to non-zero, number of spin-up and spin-down electrons will + be fixed, and Fermi energy level will split to E_Fermi_up and E_Fermi_down. By the way, total + magnetization will also be fixed, and will be the value of **"nupdown"**. ## Noncollinear Spin Polarized Calculations -The spin non-collinear polarization calculation corresponds to setting **"noncolin 1"**, in which case the coupling between spin up and spin down will be taken into account. -In this case, **"nspin 4"** must also be specified. ABACUS reports an input error instead of silently changing an incompatible or omitted nspin value. -The weight of each band will not change, but the number of occupied states will be double. -If the nbands parameter is set manually, it is generally set to twice what it would be when nspin<4. -In general, non-collinear magnetic moment settings are often used in calculations considering [SOC effects](#soc-effects). When **"lspinorb 1"** is set in INPUT, **"nspin 4"** is also required. +The spin non-collinear polarization calculation corresponds to setting **"noncolin 1"**, in which +case the coupling between spin up and spin down will be taken into account. In this case, **"nspin +4"** must also be specified. ABACUS reports an input error instead of silently changing an +incompatible or omitted nspin value. The weight of each band will not change, but the number of +occupied states will be double. If the nbands parameter is set manually, it is generally set to +twice what it would be when nspin\<4. + +In general, non-collinear magnetic moment settings are often used in calculations considering +[SOC effects](#soc-effects). When **"lspinorb 1"** is set in INPUT, **"nspin 4"** is also required. Note: different settings for "noncolin" and "lspinorb" correspond to different calculations: -| noncolin | lspinorb | nspin | Effect | When to Use | -|----------|----------|-------|--------|-------------| -| 0 | 0 | <4 | No non-collinear magnetism, no SOC | Standard collinear spin-polarized or non-spin-polarized calculations | -| 0 | 0 | 4 | Same as above, but larger calculation | **Not recommended** - wastes computational resources | -| 1 | 0 | 4 | Non-collinear magnetism WITHOUT SOC | Systems with complex magnetic structures (e.g., spin spirals, frustrated magnets) where SOC is negligible | -| 0 | 1 | 4 | SOC WITH z-axis magnetism only | Non-magnetic materials with SOC (e.g., semiconductors with band splitting), or magnetic materials where magnetism is along z-axis | -| 1 | 1 | 4 | Both SOC AND non-collinear magnetism | Heavy-element magnetic materials where both SOC and non-collinear magnetism are important (e.g., magnetic anisotropy, Dzyaloshinskii-Moriya interaction) | +| noncolin | lspinorb | nspin | Effect | When to Use | +| -------- | -------- | ----- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0 | 0 | \<4 | No non-collinear magnetism, no SOC | Standard collinear spin-polarized or non-spin-polarized calculations | +| 0 | 0 | 4 | Same as above, but larger calculation | **Not recommended** - wastes computational resources | +| 1 | 0 | 4 | Non-collinear magnetism WITHOUT SOC | Systems with complex magnetic structures (e.g., spin spirals, frustrated magnets) where SOC is negligible | +| 0 | 1 | 4 | SOC WITH z-axis magnetism only | Non-magnetic materials with SOC (e.g., semiconductors with band splitting), or magnetic materials where magnetism is along z-axis | +| 1 | 1 | 4 | Both SOC AND non-collinear magnetism | Heavy-element magnetic materials where both SOC and non-collinear magnetism are important (e.g., magnetic anisotropy, Dzyaloshinskii-Moriya interaction) | -**Special case**: `noncolin=0, lspinorb=1` is commonly used for non-magnetic materials with SOC effects (e.g., topological insulators, semiconductors with spin-orbit splitting). In this case, the magnetization is NOT automatically set, implying no magnetic moments in the system. +**Special case**: `noncolin=0, lspinorb=1` is commonly used for non-magnetic materials with SOC +effects (e.g., topological insulators, semiconductors with spin-orbit splitting). In this case, the +magnetization is NOT automatically set, implying no magnetic moments in the system. ## For the continuation job -- Continuation job for "nspin 1" need file "chg.cube" which is generated by setting "out_chg=1" in task before. By setting "init_chg file" in new job's INPUT file, charge density will start from file but not atomic. -- Continuation job for "nspin 2" need files "chgs1.cube" and "chgs2.cube" which are generated by "out_chg 1" with "nspin 2", and refer to spin-up and spin-down charge densities respectively. It should be note that reading "chgs1.cube" only for the continuation target magnetic moment job is not supported now. -- Continuation job for "nspin 4" need files "chgs%s.cube", where %s in {1,2,3,4}, which are generated by "out_chg 1" with any variable setting leading to 'nspin'=4, and refer to charge densities in Pauli spin matrixes. It should be note that reading charge density files printing by 'nspin'=2 case is supported, which means only $\sigma_{tot}$ and $\sigma_{z}$ are read. + +- Continuation job for "nspin 1" need file "chg.cube" which is generated by setting "out_chg=1" in + task before. By setting "init_chg file" in new job's INPUT file, charge density will start from + file but not atomic. +- Continuation job for "nspin 2" need files "chgs1.cube" and "chgs2.cube" which are generated by + "out_chg 1" with "nspin 2", and refer to spin-up and spin-down charge densities respectively. It + should be note that reading "chgs1.cube" only for the continuation target magnetic moment job is + not supported now. +- Continuation job for "nspin 4" need files "chgs%s.cube", where %s in {1,2,3,4}, which are + generated by "out_chg 1" with any variable setting leading to 'nspin'=4, and refer to charge + densities in Pauli spin matrixes. It should be note that reading charge density files printing by + 'nspin'=2 case is supported, which means only $\\sigma\_{tot}$ and $\\sigma\_{z}$ are read. # SOC Effects + ## SOC + `lspinorb` is used for control whether or not SOC(spin-orbit coupling) effects should be considered. Both `basis_type=pw` and `basis_type=lcao` support `scf` and `nscf` calculation with SOC effects. -Atomic forces and cell stresses can be calculated with SOC effects (supported since ABACUS v3.9.0). +Atomic forces and cell stresses can be calculated with SOC effects (supported since ABACUS v3.9.0). ## Pseudopotentials and Numerical Atomic Orbitals + For Norm-Conserving pseudopotentials, there are differences between SOC version and non-SOC version. -Please check your pseudopotential files before calculating. -In `PP_HEADER` part, keyword `has_so=1` and `relativistic="full"` refer to SOC effects have been considered, -which would lead to different `PP_NONLOCAL` and `PP_PSWFC` parts. -Please be careful that `relativistic="full"` version can be used for SOC or non-SOC calculation, but `relativistic="scalar"` version only can be used for non-SOC calculation. -When full-relativistic pseudopotential is used for non-SOC calculation, ABACUS will automatically transform it to scalar-relativistic version. +Please check your pseudopotential files before calculating. In `PP_HEADER` part, keyword `has_so=1` +and `relativistic="full"` refer to SOC effects have been considered, which would lead to different +`PP_NONLOCAL` and `PP_PSWFC` parts. Please be careful that `relativistic="full"` version can be used +for SOC or non-SOC calculation, but `relativistic="scalar"` version only can be used for non-SOC +calculation. When full-relativistic pseudopotential is used for non-SOC calculation, ABACUS will +automatically transform it to scalar-relativistic version. -Numerical atomic orbitals in ABACUS are unrelated with spin, and same orbital file can be used for SOC and non-SOC calculation. +Numerical atomic orbitals in ABACUS are unrelated with spin, and same orbital file can be used for +SOC and non-SOC calculation. ## Partial-relativistic SOC Effect -Sometimes, for some real materials, both scalar-relativistic and full-relativistic can not describe the exact spin-orbit coupling. -Artificial modulation can help for these cases. -`soc_lambda`, which has value range [0.0, 1.0] , is used for modulate SOC effect. -In particular, `soc_lambda 0.0` refers to scalar-relativistic case and `soc_lambda 1.0` refers to full-relativistic case. +Sometimes, for some real materials, both scalar-relativistic and full-relativistic can not describe +the exact spin-orbit coupling. Artificial modulation can help for these cases. + +`soc_lambda`, which has value range [0.0, 1.0] , is used for modulate SOC effect. In particular, +`soc_lambda 0.0` refers to scalar-relativistic case and `soc_lambda 1.0` refers to full-relativistic +case. ## Pseudopotential Requirements for SOC @@ -86,10 +120,12 @@ When performing SOC calculations (`lspinorb=1`), specific pseudopotential requir ### Checking Pseudopotential Files In the UPF (Unified Pseudopotential Format) file header (`PP_HEADER` section), look for: + - `has_so="T"` or `has_so="1"`: Indicates SOC information is included - `relativistic="full"`: Indicates full-relativistic pseudopotential Example from a full-relativistic UPF file: + ``` =3.7,<3.8` is passed - through to conda). - - Detects the target distribution (`Ubuntu-22.04`) by querying the WSL - registry key `HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss`. This - is immune to UTF-16 parsing pitfalls and to Store appx leftovers that - can make `wsl -d -- true` falsely report success. - - Calls `wsl --install -d Ubuntu-22.04 --no-launch` if the distro is - missing, then verifies the registry entry appeared. - - Invokes `provision.sh` inside the distribution, stripping any `\r` - bytes on the fly (`sed 's/\r$//' script | bash`) so Windows line - endings don't break shell parsing. - - Writes two small launcher `.cmd` files and adds them to the user PATH - via PowerShell (avoiding `setx`'s 1024-character truncation). - -2. **`provision.sh`** (runs as root inside the WSL distribution) + - Prompts for an ABACUS version (blank = latest on conda-forge; an exact version like `3.7.4` is + pinned; a match-spec like `>=3.7,<3.8` is passed through to conda). + - Detects the target distribution (`Ubuntu-22.04`) by querying the WSL registry key + `HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss`. This is immune to UTF-16 parsing + pitfalls and to Store appx leftovers that can make `wsl -d -- true` falsely report + success. + - Calls `wsl --install -d Ubuntu-22.04 --no-launch` if the distro is missing, then verifies the + registry entry appeared. + - Invokes `provision.sh` inside the distribution, stripping any `\r` bytes on the fly + (`sed 's/\r$//' script | bash`) so Windows line endings don't break shell parsing. + - Writes two small launcher `.cmd` files and adds them to the user PATH via PowerShell (avoiding + `setx`'s 1024-character truncation). + +1. **`provision.sh`** (runs as root inside the WSL distribution) + - Optionally rewrites `/etc/apt/sources.list` to TUNA. - - `apt-get install`s a minimal set of prerequisites (curl, ca-certificates, - bzip2). - - Downloads the Miniforge installer (from GitHub or TUNA's GitHub-releases - mirror) and installs it to `/opt/abacus-miniforge`. - - `conda create -n abacus_env -c conda-forge abacus` (or the TUNA - conda-forge channel) โ€” a single package pulls in the entire scientific - runtime. conda-forge ships `abacus` for `linux-64` and `linux-aarch64`, - which is exactly what WSL2 provides. - - Writes two system-wide launchers, `/usr/local/bin/abacus` and - `/usr/local/bin/abacus-mpi`, that activate the env and exec the real - binary. Both set `OMP_NUM_THREADS=1` by default to avoid thread - oversubscription. `abacus-mpi` additionally sets OpenMPI 4/5 + PRRTE - "allow run as root" environment variables and passes - `--allow-run-as-root` to `mpirun`, so the default WSL root user can - launch parallel jobs without creating a non-root user. - -3. **Windows launchers** (`abacus.cmd`, `abacus-mpi.cmd`) + - `apt-get install`s a minimal set of prerequisites (curl, ca-certificates, bzip2). + - Downloads the Miniforge installer (from GitHub or TUNA's GitHub-releases mirror) and installs + it to `/opt/abacus-miniforge`. + - `conda create -n abacus_env -c conda-forge abacus` (or the TUNA conda-forge channel) โ€” a single + package pulls in the entire scientific runtime. conda-forge ships `abacus` for `linux-64` and + `linux-aarch64`, which is exactly what WSL2 provides. + - Writes two system-wide launchers, `/usr/local/bin/abacus` and `/usr/local/bin/abacus-mpi`, that + activate the env and exec the real binary. Both set `OMP_NUM_THREADS=1` by default to avoid + thread oversubscription. `abacus-mpi` additionally sets OpenMPI 4/5 + PRRTE "allow run as root" + environment variables and passes `--allow-run-as-root` to `mpirun`, so the default WSL root + user can launch parallel jobs without creating a non-root user. + +1. **Windows launchers** (`abacus.cmd`, `abacus-mpi.cmd`) + - Added to `%LOCALAPPDATA%\ABACUS\bin` and the user PATH. - - Each launcher sets `WSLENV=OMP_NUM_THREADS:MKL_NUM_THREADS:OPENBLAS_NUM_THREADS:...` - so thread-count overrides set on the Windows side are visible inside WSL. + - Each launcher sets `WSLENV=OMP_NUM_THREADS:MKL_NUM_THREADS:OPENBLAS_NUM_THREADS:...` so + thread-count overrides set on the Windows side are visible inside WSL. - Body is just: ``` wsl -d Ubuntu-22.04 --cd "%CD%" -- abacus %* ``` - `--cd "%CD%"` maps the current Windows directory (`C:\โ€ฆ\case`) to its - WSL path (`/mnt/c/โ€ฆ/case`), so users can `cd` into a case directory in - `cmd`/PowerShell/Terminal and just type `abacus`. - -4. **`uninstall-abacus.bat`** - - Reads `install-state.txt` (written by the installer) to learn whether - the Ubuntu-22.04 distribution was pre-existing or added by us. - - If it was added by us, prompts whether to `wsl --unregister` the entire - distribution, or to only wipe `/opt/abacus-miniforge` and the launchers. + `--cd "%CD%"` maps the current Windows directory (`C:\โ€ฆ\case`) to its WSL path + (`/mnt/c/โ€ฆ/case`), so users can `cd` into a case directory in `cmd`/PowerShell/Terminal and + just type `abacus`. + +1. **`uninstall-abacus.bat`** + + - Reads `install-state.txt` (written by the installer) to learn whether the Ubuntu-22.04 + distribution was pre-existing or added by us. + - If it was added by us, prompts whether to `wsl --unregister` the entire distribution, or to + only wipe `/opt/abacus-miniforge` and the launchers. - If it was pre-existing, only the ABACUS files inside are removed. - - Cleans Windows-side launchers and removes the bin directory from the - user PATH. - - Does **not** touch WSL itself (runtime, Windows optional features, or - other distributions). See *Uninstallation* below for how to fully - remove WSL if you want to. + - Cleans Windows-side launchers and removes the bin directory from the user PATH. + - Does **not** touch WSL itself (runtime, Windows optional features, or other distributions). See + *Uninstallation* below for how to fully remove WSL if you want to. ## Requirements @@ -83,22 +78,21 @@ The pipeline, end to end: - Administrator privileges for the first run (to enable WSL features). - Virtualization enabled in BIOS/UEFI. - ~2 GB free disk space (Ubuntu + conda env). -- Network access to GitHub and conda-forge, or to TUNA if you choose the - China mirror option. +- Network access to GitHub and conda-forge, or to TUNA if you choose the China mirror option. ## Installation 1. Clone or download this repository. -2. In `tools/04_windows_installation/`, right-click `install-abacus.bat` โ†’ **Run as administrator**. -3. Answer the China-mirror prompt (`y` recommended inside Mainland China). - Then pick an ABACUS version when prompted (leave blank for the latest on - conda-forge; for a pinned install, type an exact version such as `3.7.4`). -4. If this is the first time WSL is installed on the machine, the script - will ask you to reboot and run it again. -5. Wait for `[*] Provisioning ABACUS โ€ฆ` to finish (5โ€“15 minutes on first - run; most of it is the conda-forge download). -6. When you see `Installation complete!`, **open a new terminal window** - (so the updated PATH takes effect) and verify: +1. In `tools/04_windows_installation/`, right-click `install-abacus.bat` โ†’ **Run as administrator**. +1. Answer the China-mirror prompt (`y` recommended inside Mainland China). Then pick an ABACUS + version when prompted (leave blank for the latest on conda-forge; for a pinned install, type an + exact version such as `3.7.4`). +1. If this is the first time WSL is installed on the machine, the script will ask you to reboot and + run it again. +1. Wait for `[*] Provisioning ABACUS โ€ฆ` to finish (5โ€“15 minutes on first run; most of it is the + conda-forge download). +1. When you see `Installation complete!`, **open a new terminal window** (so the updated PATH takes + effect) and verify: ``` abacus --version ``` @@ -125,19 +119,18 @@ set OMP_NUM_THREADS=2 abacus-mpi -n 4 ``` -Set `OMP_NUM_THREADS` (and/or `MKL_NUM_THREADS`, `OPENBLAS_NUM_THREADS`) in -your Windows shell and the launcher will forward the value into WSL through -`WSLENV`. Unset, it defaults to 1 โ€” a safe choice when running pure MPI. +Set `OMP_NUM_THREADS` (and/or `MKL_NUM_THREADS`, `OPENBLAS_NUM_THREADS`) in your Windows shell and +the launcher will forward the value into WSL through `WSLENV`. Unset, it defaults to 1 โ€” a safe +choice when running pure MPI. -Interactive Linux shell (for advanced debugging, manually running -`mpirun`, inspecting logs, etc.): +Interactive Linux shell (for advanced debugging, manually running `mpirun`, inspecting logs, etc.): ``` wsl -d Ubuntu-22.04 ``` -Inside the shell you can `conda activate abacus_env` to get access to -`mpirun`, `mpiexec`, and other tools from the conda environment. +Inside the shell you can `conda activate abacus_env` to get access to `mpirun`, `mpiexec`, and other +tools from the conda environment. ## Uninstallation @@ -145,24 +138,21 @@ Inside the shell you can `conda activate abacus_env` to get access to Run `uninstall-abacus.bat`. This handles the common case: -- Removes `/opt/abacus-miniforge` and the `abacus` / `abacus-mpi` launchers - inside WSL. -- If the installer added the `Ubuntu-22.04` distribution, asks whether you - also want to `wsl --unregister` it (pick `y` to reclaim the disk space, - `n` to keep the Linux environment for other uses). -- Deletes `%LOCALAPPDATA%\ABACUS\` and removes its `bin\` directory from - your user PATH. +- Removes `/opt/abacus-miniforge` and the `abacus` / `abacus-mpi` launchers inside WSL. +- If the installer added the `Ubuntu-22.04` distribution, asks whether you also want to + `wsl --unregister` it (pick `y` to reclaim the disk space, `n` to keep the Linux environment for + other uses). +- Deletes `%LOCALAPPDATA%\ABACUS\` and removes its `bin\` directory from your user PATH. -This is enough for almost every user. WSL itself and any *other* WSL -distributions you have stay untouched โ€” important because WSL is commonly -shared with Docker Desktop, VS Code Remote, and other toolchains. +This is enough for almost every user. WSL itself and any *other* WSL distributions you have stay +untouched โ€” important because WSL is commonly shared with Docker Desktop, VS Code Remote, and other +toolchains. ### Nuclear: remove WSL itself -Only do this if you truly have no other use for WSL on this machine. -Removing WSL will break Docker Desktop, VS Code Remote-WSL, any other -Linux distros you have, and so on. Run the following in an elevated -PowerShell: +Only do this if you truly have no other use for WSL on this machine. Removing WSL will break Docker +Desktop, VS Code Remote-WSL, any other Linux distros you have, and so on. Run the following in an +elevated PowerShell: ```powershell # 1. Unregister every WSL distribution (this wipes all their files). @@ -191,19 +181,17 @@ Remove-Item "$env:UserProfile\.wslconfig" -ErrorAction SilentlyContinue Restart-Computer ``` -After the reboot `wsl.exe` no longer exists. If you also ran step 4, the -Hyper-V virtualization layer used by WSL2 is disabled. +After the reboot `wsl.exe` no longer exists. If you also ran step 4, the Hyper-V virtualization +layer used by WSL2 is disabled. -> On older Windows builds where `wsl --uninstall` is not available (WSL -> shipped via the in-box `wsl.exe` rather than the Store package), use -> `Get-AppxPackage *WindowsSubsystemForLinux* | Remove-AppxPackage` as a -> fallback for step 2. +> On older Windows builds where `wsl --uninstall` is not available (WSL shipped via the in-box +> `wsl.exe` rather than the Store package), use +> `Get-AppxPackage *WindowsSubsystemForLinux* | Remove-AppxPackage` as a fallback for step 2. ## Performance notes -- Files under `/mnt/c/...` are served through the 9P protocol and are - noticeably slower than native ext4. For heavy I/O (large SCF, MD - trajectories), run the case from inside the WSL filesystem: +- Files under `/mnt/c/...` are served through the 9P protocol and are noticeably slower than native + ext4. For heavy I/O (large SCF, MD trajectories), run the case from inside the WSL filesystem: ``` wsl -d Ubuntu-22.04 cp -r /mnt/c/path/to/case ~/case @@ -211,8 +199,8 @@ Hyper-V virtualization layer used by WSL2 is disabled. abacus ``` - The first `wsl` invocation after a boot triggers a 10โ€“30 s VM cold start. -- OpenMPI runs all ranks inside a single WSL2 VM, so there is no network - overhead between ranks โ€” you get near-native parallel performance. +- OpenMPI runs all ranks inside a single WSL2 VM, so there is no network overhead between ranks โ€” + you get near-native parallel performance. ## File layout @@ -242,20 +230,16 @@ Inside WSL (Ubuntu-22.04): ## Design choices and trade-offs -- **Why WSL2 + conda-forge instead of a native Windows build?** ABACUS's - MPI + ScaLAPACK + ELPA stack has no reliable native Windows build. Going - through WSL2 lets us reuse the Linux binaries conda-forge already ships, - turning a multi-week porting problem into a 200-line shell script. -- **Why a dedicated `Ubuntu-22.04` distribution?** conda-forge ABACUS is - built against glibc from 22.04-era Ubuntu. Using `Ubuntu` (rolling) risks - mismatches; pinning the version keeps the install reproducible. -- **Why put conda under `/opt/abacus-miniforge` rather than `/root`?** - Clean uninstall path, clear ownership, and doesn't interfere with a - user's personal conda install if they later add one inside the same - distribution. -- **Why not ship a pre-built WSL rootfs?** Would cut first-run time from - ~10 min to ~1 min, but balloons the installer from a few KB of scripts - to 300โ€“500 MB, requires CI infrastructure, and needs code signing to - avoid SmartScreen warnings. A scripted online installer is the - lowest-maintenance starting point; the pre-built rootfs path remains - open for a future v1. +- **Why WSL2 + conda-forge instead of a native Windows build?** ABACUS's MPI + ScaLAPACK + ELPA + stack has no reliable native Windows build. Going through WSL2 lets us reuse the Linux binaries + conda-forge already ships, turning a multi-week porting problem into a 200-line shell script. +- **Why a dedicated `Ubuntu-22.04` distribution?** conda-forge ABACUS is built against glibc from + 22.04-era Ubuntu. Using `Ubuntu` (rolling) risks mismatches; pinning the version keeps the install + reproducible. +- **Why put conda under `/opt/abacus-miniforge` rather than `/root`?** Clean uninstall path, clear + ownership, and doesn't interfere with a user's personal conda install if they later add one inside + the same distribution. +- **Why not ship a pre-built WSL rootfs?** Would cut first-run time from ~10 min to ~1 min, but + balloons the installer from a few KB of scripts to 300โ€“500 MB, requires CI infrastructure, and + needs code signing to avoid SmartScreen warnings. A scripted online installer is the + lowest-maintenance starting point; the pre-built rootfs path remains open for a future v1. diff --git a/docs/community/cicd.md b/docs/community/cicd.md index 7479d0262df..80ca4a81185 100644 --- a/docs/community/cicd.md +++ b/docs/community/cicd.md @@ -1,31 +1,58 @@ # Lists of continuous integration (CI) actions -The directory `.github/workflows` contains the continuous integration (CI) actions for the project. The actions are written in YAML format and are executed by GitHub Actions. Check the [Actions page](https://github.com/deepmodeling/abacus-develop/actions) of the repo for the status of the actions. +The directory `.github/workflows` contains the continuous integration (CI) actions for the project. +The actions are written in YAML format and are executed by GitHub Actions. Check the +[Actions page](https://github.com/deepmodeling/abacus-develop/actions) of the repo for the status of +the actions. ## On Pull Request (PR) -The following CI actions are triggered on pull request (PR) creation or update (the user pushes a new commit to the incoming branch): - -- Integration test and unit tests (`test.yml`): This action builds ABACUS with all available features, runs integration tests, and runs unit tests. It also performs [static analysis](../CONTRIBUTING.md#code-formatting-style) with . -- Building tests with CMake (`build_test_cmake.yml`) and Makefile (`build_test_makefile.yml`): This action builds ABACUS with each feature separately, ensuring: (i) there are no conflicts between features, (ii) the compilation is successful whether the feature is enabled, and (iii) it works well on multiple platforms, i.e. with GNU+OpenBLAS toolchain and Intel+MKL toolchain. -- [Rerender the docs site](https://readthedocs.org/projects/abacus-rtd/builds/): This action rerenders the documentation site on Read the Docs. It is automatically triggered when the documentation is updated. -- Testing GPU features (`cuda.yml`): This action builds ABACUS with GPU support and runs several tests on the GPU. - -> Some tests are executed on self-hosted runners, which are maintained by the deepmodeling community. To save resources, the actions triggered by new commits may cancel the previous actions in the same PR. +The following CI actions are triggered on pull request (PR) creation or update (the user pushes a +new commit to the incoming branch): + +- Integration test and unit tests (`test.yml`): This action builds ABACUS with all available + features, runs integration tests, and runs unit tests. It also performs + [static analysis](../CONTRIBUTING.md#code-formatting-style) with \. +- Building tests with CMake (`build_test_cmake.yml`) and Makefile (`build_test_makefile.yml`): This + action builds ABACUS with each feature separately, ensuring: (i) there are no conflicts between + features, (ii) the compilation is successful whether the feature is enabled, and (iii) it works + well on multiple platforms, i.e. with GNU+OpenBLAS toolchain and Intel+MKL toolchain. +- [Rerender the docs site](https://readthedocs.org/projects/abacus-rtd/builds/): This action + rerenders the documentation site on Read the Docs. It is automatically triggered when the + documentation is updated. +- Testing GPU features (`cuda.yml`): This action builds ABACUS with GPU support and runs several + tests on the GPU. + +> Some tests are executed on self-hosted runners, which are maintained by the deepmodeling +> community. To save resources, the actions triggered by new commits may cancel the previous actions +> in the same PR. ## On PR Merge After the PR merges into the main branch, the following actions are triggered: -- Building Docker images (`devcontainer.yml`): This action builds the Docker images with latest codes and executables. The images are tagged as `abacus-gnu:latest`, `abacus-intel:latest`, and `abacus-cuda:latest`, and then pushed to the GitHub Container Registry (`ghcr.io/deepmodeling`) and AliCloud Container Registry (`registry.dp.tech/deepmodeling`, recommended for one having issue connecting to GitHub). For example: `docker pull ghcr.io/deepmodeling/abacus-intel:latest`. -- Generate doxygen site (`doxygen.yml`): This action generates the Doxygen site for the project. The site is published on [GitHub Pages](https://deepmodeling.github.io/abacus-develop/). -- Mirror the repo to Gitee (`mirror.yml`): This action mirrors the repo to [Gitee](https://gitee.com/deepmodeling/abacus-develop). +- Building Docker images (`devcontainer.yml`): This action builds the Docker images with latest + codes and executables. The images are tagged as `abacus-gnu:latest`, `abacus-intel:latest`, and + `abacus-cuda:latest`, and then pushed to the GitHub Container Registry (`ghcr.io/deepmodeling`) + and AliCloud Container Registry (`registry.dp.tech/deepmodeling`, recommended for one having issue + connecting to GitHub). For example: `docker pull ghcr.io/deepmodeling/abacus-intel:latest`. +- Generate doxygen site (`doxygen.yml`): This action generates the Doxygen site for the project. The + site is published on [GitHub Pages](https://deepmodeling.github.io/abacus-develop/). +- Mirror the repo to Gitee (`mirror.yml`): This action mirrors the repo to + [Gitee](https://gitee.com/deepmodeling/abacus-develop). ## On Routine -- Dynamic analysis (`dynamic_analysis.yml`): This action runs integration tests with [AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) to detect memory errors. The action is scheduled to run **every Sunday**. The results are published to [the dashboard branch](https://github.com/deepmodeling/abacus-develop/blob/dashboard/README.md). +- Dynamic analysis (`dynamic_analysis.yml`): This action runs integration tests with + [AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) to detect memory + errors. The action is scheduled to run **every Sunday**. The results are published to + [the dashboard branch](https://github.com/deepmodeling/abacus-develop/blob/dashboard/README.md). ## On Release -- Coverage test (`coverage.yml`): This action builds ABACUS with all available features, runs integration tests, and runs unit tests. It also measures the code coverage of the tests. The results are published at [codecov.io](https://app.codecov.io/gh/deepmodeling/abacus-develop). -- Building tagged Docker images (`devcontainer.yml`): Same as that action above; in addition the built image is tagged in the pattern of `abacus-intel:3.6.0`. For example: `docker pull ghcr.io/deepmodeling/abacus-intel:3.6.0`. +- Coverage test (`coverage.yml`): This action builds ABACUS with all available features, runs + integration tests, and runs unit tests. It also measures the code coverage of the tests. The + results are published at [codecov.io](https://app.codecov.io/gh/deepmodeling/abacus-develop). +- Building tagged Docker images (`devcontainer.yml`): Same as that action above; in addition the + built image is tagged in the pattern of `abacus-intel:3.6.0`. For example: + `docker pull ghcr.io/deepmodeling/abacus-intel:3.6.0`. diff --git a/docs/community/contribution_guide.md b/docs/community/contribution_guide.md index 8d4052e8816..b91b7399157 100644 --- a/docs/community/contribution_guide.md +++ b/docs/community/contribution_guide.md @@ -2,22 +2,31 @@ ## Contribution Process -We welcome contributions from the open source community. The technical guide is provided in [Contributing to ABACUS](../CONTRIBUTING.md). Here is the basic contribution process: +We welcome contributions from the open source community. The technical guide is provided in +[Contributing to ABACUS](../CONTRIBUTING.md). Here is the basic contribution process: -- **Find out issues to work on.** -We assume you already have a good idea on what to do, otherwise the [issue tracker](https://github.com/deepmodeling/abacus-develop/issues) and [discussion](https://github.com/deepmodeling/abacus-develop/discussions) panel provide good starting points to find out what to work on and to get familiar with the project. +- **Find out issues to work on.** We assume you already have a good idea on what to do, otherwise + the [issue tracker](https://github.com/deepmodeling/abacus-develop/issues) and + [discussion](https://github.com/deepmodeling/abacus-develop/discussions) panel provide good + starting points to find out what to work on and to get familiar with the project. -- **Approach the issue.** -It is suggested to [submit new issues](https://github.com/deepmodeling/abacus-develop/issues/new/choose) before coding out changes to involve more discussions and suggestions from development team. Refer to the technical guide in [Contributing to ABACUS](../CONTRIBUTING.md) when needed. +- **Approach the issue.** It is suggested to + [submit new issues](https://github.com/deepmodeling/abacus-develop/issues/new/choose) before + coding out changes to involve more discussions and suggestions from development team. Refer to the + technical guide in [Contributing to ABACUS](../CONTRIBUTING.md) when needed. -- **Follow governance rules.** -Before implementation and review, read [`AGENTS.md`](https://github.com/deepmodeling/abacus-develop/blob/develop/AGENTS.md) and the -[ABACUS Agent Governance](../developers_guide/agent_governance.md) guide. New -code is reviewed against the shared rules for global dependencies, default -parameters, header dependencies, tests, INPUT metadata changes, LF line -endings, C++11 compatibility, and exception handling. +- **Follow governance rules.** Before implementation and review, read + [`AGENTS.md`](https://github.com/deepmodeling/abacus-develop/blob/develop/AGENTS.md) and the + [ABACUS Agent Governance](../developers_guide/agent_governance.md) guide. New code is reviewed + against the shared rules for global dependencies, default parameters, header dependencies, tests, + INPUT metadata changes, LF line endings, C++11 compatibility, and exception handling. -- **Open a pull request.** The ABACUS developers review the pull request (PR) list regularly. If the work is not ready, convert it to draft until finished, then you can mark it as "Ready for review". It is suggested to open a new PR through forking a repo and creating a new branch on you Github account. A new PR should include as much information as possible in `description` when submmited. Unittests or CI tests are required for new PRs. +- **Open a pull request.** The ABACUS developers review the pull request (PR) list regularly. If the + work is not ready, convert it to draft until finished, then you can mark it as "Ready for review". + It is suggested to open a new PR through forking a repo and creating a new branch on you Github + account. A new PR should include as much information as possible in `description` when submmited. + Unittests or CI tests are required for new PRs. -- **Iterate the pull request.** -All pull requests need to be tested through CI before reviewing. A pull request might need to be iterated several times before accepted, so splitting a long PR into parts reduces reviewing difficulty for us. +- **Iterate the pull request.** All pull requests need to be tested through CI before reviewing. A + pull request might need to be iterated several times before accepted, so splitting a long PR into + parts reduces reviewing difficulty for us. diff --git a/docs/community/faq.md b/docs/community/faq.md index 6896f8961a1..bb90c2d9179 100644 --- a/docs/community/faq.md +++ b/docs/community/faq.md @@ -10,13 +10,16 @@ **1. What are the merits of ABACUS in respect of functionality, performance, and/or accuracy?** -Users are referred to the introduction of features of ABACUS in the [feature list](http://abacus.ustc.edu.cn/features/list.htm). +Users are referred to the introduction of features of ABACUS in the +[feature list](http://abacus.ustc.edu.cn/features/list.htm). **2. How to contact the ABACUS community?** -Users can contact the ABACUS community by join ABACUS WeChat or QQ group. One can quickly join the QQ group via group ID: 759914681 +Users can contact the ABACUS community by join ABACUS WeChat or QQ group. One can quickly join the +QQ group via group ID: 759914681 -If users have any questions or suggestions, please feel free to contact us in group or by raising issue in GitHub repo. +If users have any questions or suggestions, please feel free to contact us in group or by raising +issue in GitHub repo. ## Installation @@ -24,63 +27,97 @@ If users have any questions or suggestions, please feel free to contact us in gr **1. Why pseudopotential files must be provided in LCAO calculation?** -The pseudopotentials are used to approximate the potential of nuclear and core electrons, while the numerical orbitals are basis sets used to expand the Hamiltonian. So both pseudopotential and numerical orbital files are needed in LCAO calculation. +The pseudopotentials are used to approximate the potential of nuclear and core electrons, while the +numerical orbitals are basis sets used to expand the Hamiltonian. So both pseudopotential and +numerical orbital files are needed in LCAO calculation. **2. What is the correlation between pseudopotential and numerical orbital files?** -The numerical orbital files are generated for a specific pseudopotential. So the right numerical orbital files must be chosen for a specific pseudopotential. We suggest users choose numerical orbital files and the corresponding pseudopotential files from the [ABACUS website](http://abacus.ustc.edu.cn/pseudo/list.htm) because their accuracy has been tested. However, interesting users may also generate their own numerical orbitals for a specific type of pseudopential by using the tools provided in the [abacus-develop/tools](https://github.com/deepmodeling/abacus-develop/tree/develop/tools) directory. +The numerical orbital files are generated for a specific pseudopotential. So the right numerical +orbital files must be chosen for a specific pseudopotential. We suggest users choose numerical +orbital files and the corresponding pseudopotential files from the +[ABACUS website](http://abacus.ustc.edu.cn/pseudo/list.htm) because their accuracy has been tested. +However, interesting users may also generate their own numerical orbitals for a specific type of +pseudopential by using the tools provided in the +[abacus-develop/tools](https://github.com/deepmodeling/abacus-develop/tree/develop/tools) directory. -**3. How to set `ecutwfc` in LCAO calculation? Must it be 100 Ry for a numerical orbital file like `Cu_lda_7.0au_100Ry_2s2p2d`?** +**3. How to set `ecutwfc` in LCAO calculation? Must it be 100 Ry for a numerical orbital file like +`Cu_lda_7.0au_100Ry_2s2p2d`?** -It is recommended to set `ecutwfc` to the value that the numerical orbital file suggests, but it is not a must. The `ecutwfc` value only affects the number of FFT grids. +It is recommended to set `ecutwfc` to the value that the numerical orbital file suggests, but it is +not a must. The `ecutwfc` value only affects the number of FFT grids. **4. Does ABACUS support LCAO calculations accounting for external electric field effects?** -Yes, users are referred to documentation on [external electric field](../advanced/scf/advanced.md#external-electric-field). +Yes, users are referred to documentation on +[external electric field](../advanced/scf/advanced.md#external-electric-field). **5. Can ABACUS calculate non-periodic systems, such as ionic liquids?** -Non-periodic systems such as liquid systems can be calculated by using supercell and gamma-only calculation. +Non-periodic systems such as liquid systems can be calculated by using supercell and gamma-only +calculation. **6. How to perform spin-orbital coupling (SOC) calculations in ABACUS?** To perform SOC calculations in ABACUS, follow these steps: 1. **Set `lspinorb=1` in the INPUT file**: This enables spin-orbit coupling effects -2. **Use full-relativistic pseudopotentials**: SOC calculations require pseudopotentials with `has_so=true` in the UPF header - - Download full-relativistic versions of SG15_ONCV pseudopotentials from [quantum-simulation.org](http://quantum-simulation.org/potentials/sg15_oncv/upf/) +1. **Use full-relativistic pseudopotentials**: SOC calculations require pseudopotentials with + `has_so=true` in the UPF header + - Download full-relativistic versions of SG15_ONCV pseudopotentials from + [quantum-simulation.org](http://quantum-simulation.org/potentials/sg15_oncv/upf/) - Check the UPF file header for `relativistic="full"` and `has_so="T"` -3. **Set the spin representation**: When `lspinorb=1` is set, explicitly set `nspin=4`; symmetry is automatically disabled +1. **Set the spin representation**: When `lspinorb=1` is set, explicitly set `nspin=4`; symmetry is + automatically disabled -**Basis set support**: Both `basis_type=pw` (plane wave) and `basis_type=lcao` (numerical atomic orbitals) support SOC calculations for both SCF and NSCF. +**Basis set support**: Both `basis_type=pw` (plane wave) and `basis_type=lcao` (numerical atomic +orbitals) support SOC calculations for both SCF and NSCF. -**Force and stress calculations**: Atomic forces and cell stresses can be calculated with SOC (supported since ABACUS v3.9.0). +**Force and stress calculations**: Atomic forces and cell stresses can be calculated with SOC +(supported since ABACUS v3.9.0). -**Numerical atomic orbitals**: The numerical orbital files generated from scalar-relativistic pseudopotentials (available at [abacus.ustc.edu.cn](http://abacus.ustc.edu.cn/pseudo/list.htm)) can be used with full-relativistic pseudopotentials, as orbitals are spin-independent. +**Numerical atomic orbitals**: The numerical orbital files generated from scalar-relativistic +pseudopotentials (available at [abacus.ustc.edu.cn](http://abacus.ustc.edu.cn/pseudo/list.htm)) can +be used with full-relativistic pseudopotentials, as orbitals are spin-independent. -**Common error**: If you see "no soc upf used for lspinorb calculation", ensure you are using full-relativistic pseudopotentials with `has_so=true`. +**Common error**: If you see "no soc upf used for lspinorb calculation", ensure you are using +full-relativistic pseudopotentials with `has_so=true`. -For detailed information, examples, and troubleshooting, see [Spin-polarization and SOC](../advanced/scf/spin.md#soc-effects). +For detailed information, examples, and troubleshooting, see +[Spin-polarization and SOC](../advanced/scf/spin.md#soc-effects). **7. How to restart jobs in abacus?** -For restarting SCF calculations, users are referred to the documentation about [continuation of job](../advanced/scf/spin.md#for-the-continuation-job). For restarting MD calculations, please see [md_restart](../advanced/input_files/input-main.md#md_restart). +For restarting SCF calculations, users are referred to the documentation about +[continuation of job](../advanced/scf/spin.md#for-the-continuation-job). For restarting MD +calculations, please see [md_restart](../advanced/input_files/input-main.md#md_restart). -**8. Can DeePKS model be used for structural optimization calculation? What parameters need to be modified or called?** +**8. Can DeePKS model be used for structural optimization calculation? What parameters need to be +modified or called?** -If you train the DeePKS model with force labels, then the DeePKS model can provide force calculation with the same accuracy as your target method, and can thus be used for structural optimization. To do that, you just need to train the model with force label enabled. +If you train the DeePKS model with force labels, then the DeePKS model can provide force calculation +with the same accuracy as your target method, and can thus be used for structural optimization. To +do that, you just need to train the model with force label enabled. **9. How to estimate the max memory consumption?** -Run `/usr/bin/time -v mpirun -n 4 abacus`, and locate "Maximum resident set size" in the output log at the end. Please note that this value is the peak memory size of the main MPI process. +Run `/usr/bin/time -v mpirun -n 4 abacus`, and locate "Maximum resident set size" in the output log +at the end. Please note that this value is the peak memory size of the main MPI process. **10. Why there are two sigma (smearing_sigma and dos_sigma) in some examples for dos calculation?** - The tag `smearing_sigma` is used for SCF calculation, and does not affect NSCF calculation. The tag `dos_smearing` is only used for plotting density of states, which does affect SCF or NSCF results. So `smearing_sigma` should not be set in dos calculation. +The tag `smearing_sigma` is used for SCF calculation, and does not affect NSCF calculation. The tag +`dos_smearing` is only used for plotting density of states, which does affect SCF or NSCF results. +So `smearing_sigma` should not be set in dos calculation. -**11. How to set `nbands` and `ncpus`?** +**11. How to set `nbands` and `ncpus`?** -For both pw and LCAO calculations, the default value for `nbands` can be found [here](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#nbands). Note that the number of CPUs called for a parallel job (i.e., the number specified after the command `mpirun -n`) should be smaller than `nbands`, otherwise the job will fail with an error message `nbands < ncpus`. Note also that for LCAO calculations, `nbands` should always be smaller than `nlocal`, i.e., the number of the atomic orbital basis of the system. +For both pw and LCAO calculations, the default value for `nbands` can be found +[here](https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#nbands). Note +that the number of CPUs called for a parallel job (i.e., the number specified after the command +`mpirun -n`) should be smaller than `nbands`, otherwise the job will fail with an error message +`nbands < ncpus`. Note also that for LCAO calculations, `nbands` should always be smaller than +`nlocal`, i.e., the number of the atomic orbital basis of the system. [back to top](#frequently-asked-questions) @@ -88,22 +125,37 @@ For both pw and LCAO calculations, the default value for `nbands` can be found [ **1. Why my calculation is pend by using mpirun?** -This is usually caused by overloading of CPUs' memory without specifying thread numbers. ABACUS detects available hardware threads, and provides these information at the beginning of the program if used threads mismatches with hardware availability. User should keep total used threads(i.e. the number of OpenMP threads times the number of MPI processes) no more than the count of available CPUs(can be determined by `lscpu`). Setting `export OMP_NUM_THREADS=1` will solve this problem, or one can use the command like `OMP_NUM_THREADS=1 mpirun -n 8 abacus` to rerun failed jobs. +This is usually caused by overloading of CPUs' memory without specifying thread numbers. ABACUS +detects available hardware threads, and provides these information at the beginning of the program +if used threads mismatches with hardware availability. User should keep total used threads(i.e. the +number of OpenMP threads times the number of MPI processes) no more than the count of available +CPUs(can be determined by `lscpu`). Setting `export OMP_NUM_THREADS=1` will solve this problem, or +one can use the command like `OMP_NUM_THREADS=1 mpirun -n 8 abacus` to rerun failed jobs. **2. My relaxation failed. How to deal with it?** -This is usually caused by the difficulty in converging charge density. Reducing charge mixing coefficient (`mixing_beta`) might help. For large systems up to hundreds of atoms, it is suggested to choose the Kerker mixing method by setting parameter "mixing_gg0" as "1.0". +This is usually caused by the difficulty in converging charge density. Reducing charge mixing +coefficient (`mixing_beta`) might help. For large systems up to hundreds of atoms, it is suggested +to choose the Kerker mixing method by setting parameter "mixing_gg0" as "1.0". -Sometimes, loose convergence threshold of charge density (parameter "scf_thr") will cause atomic forces not correctly enough, please set it at most "1e-7" for relaxation calculation. +Sometimes, loose convergence threshold of charge density (parameter "scf_thr") will cause atomic +forces not correctly enough, please set it at most "1e-7" for relaxation calculation. **3. Why the program is halted?** -If the program prompt something like "KILLED BY SIGNAL: 9 (Killed)", it may be caused by insufficient memory. You can use `dmesg` to print out system info regarding memory management, and check if there is "Out of memory: Killed" at the end of output info. Please try using less processes and threads for calculation, or modify the input parameters requiring less memory. +If the program prompt something like "KILLED BY SIGNAL: 9 (Killed)", it may be caused by +insufficient memory. You can use `dmesg` to print out system info regarding memory management, and +check if there is "Out of memory: Killed" at the end of output info. Please try using less processes +and threads for calculation, or modify the input parameters requiring less memory. -If the error message is "Segmentation fault", or there is no enough information on the error, please feel free to submit an issue. +If the error message is "Segmentation fault", or there is no enough information on the error, please +feel free to submit an issue. + +**4. Error "Read -1" when using mpirun in docker environment** This is a +[known issue](https://github.com/open-mpi/ompi/issues/4948) of OpenMPI running in a docker +container. In this case, please set environment variable +`OMPI_MCA_btl_vader_single_copy_mechanism=none`. -**4. Error "Read -1" when using mpirun in docker environment** -This is a [known issue](https://github.com/open-mpi/ompi/issues/4948) of OpenMPI running in a docker container. In this case, please set environment variable `OMPI_MCA_btl_vader_single_copy_mechanism=none`. ## Miscellaneous **1. How to visualize charge density file?** @@ -112,7 +164,9 @@ The output file chg.cube can be visualized by using VESTA. **2. How to change cif file directly to STRU file?** -One way to change from cif to STRU is to use the [ASE-ABACUS](https://gitlab.com/1041176461/ase-abacus) interface. An example of the converting script is provided below: +One way to change from cif to STRU is to use the +[ASE-ABACUS](https://gitlab.com/1041176461/ase-abacus) interface. An example of the converting +script is provided below: ```python from ase.io import read, write @@ -129,10 +183,16 @@ write(cs_stru, cs_atoms, format='abacus', pp=pp, basis=basis) **3. What is the convergence criterion for the SCF process in ABACUS?** -ABACUS applies the density difference between two SCF steps (labeled as `DRHO` in the screen output) as the convergence criterion, which is considered as a more robust choice compared with the energy difference. `DRHO` is calculated via `DRHO = |rho(G)-rho_previous(G)|^2`. Note that the energy difference between two SCF steps (labed as `EDIFF`) is also printed out in the screen output. +ABACUS applies the density difference between two SCF steps (labeled as `DRHO` in the screen output) +as the convergence criterion, which is considered as a more robust choice compared with the energy +difference. `DRHO` is calculated via `DRHO = |rho(G)-rho_previous(G)|^2`. Note that the energy +difference between two SCF steps (labed as `EDIFF`) is also printed out in the screen output. **4. Why EDIFF is much slower than DRHO?** -For metaGGA calculations, it is normal because in addition to charge density, kinetic density also needs to be considered in metaGGA calculations. In this case, you can try set `mixing_tau = true`. If you find EDIFF is much slower than DRHO for non-metaGGA calculations, please start a new issue to us. +For metaGGA calculations, it is normal because in addition to charge density, kinetic density also +needs to be considered in metaGGA calculations. In this case, you can try set `mixing_tau = true`. +If you find EDIFF is much slower than DRHO for non-metaGGA calculations, please start a new issue to +us. [back to top](#frequently-asked-questions) diff --git a/docs/developers_guide/agent_governance.md b/docs/developers_guide/agent_governance.md index a11d440d30b..1e3b738164b 100644 --- a/docs/developers_guide/agent_governance.md +++ b/docs/developers_guide/agent_governance.md @@ -1,17 +1,15 @@ # ABACUS Agent Governance -This document is the shared development and review contract for human -contributors, general AI agents, CodeRabbit, and GitHub CI. `AGENTS.md` is the -short entry point; this file is the complete rule source for implementation and -review. +This document is the shared development and review contract for human contributors, general AI +agents, CodeRabbit, and GitHub CI. `AGENTS.md` is the short entry point; this file is the complete +rule source for implementation and review. ## Source Materials -The governance rules consolidate project guidance from @mohanchen's coding -rules, the developer guide, contribution guide, PR template, existing CI, and -historical Chinese development notes. Historical notes are used only after path -modernization and rule grading; they are not copied directly into automated -checks. +The governance rules consolidate project guidance from @mohanchen's coding rules, the developer +guide, contribution guide, PR template, existing CI, and historical Chinese development notes. +Historical notes are used only after path modernization and rule grading; they are not copied +directly into automated checks. ## Diff Scope @@ -22,40 +20,36 @@ Automated checks default to the PR diff: - Newly introduced symbols or includes. - Changed text files for line-ending checks. -Untouched historical code is not a default blocker. Review tools may mention -historical debt when it is relevant to the changed area, but they must separate -that from blocking findings on new changes. +Untouched historical code is not a default blocker. Review tools may mention historical debt when it +is relevant to the changed area, but they must separate that from blocking findings on new changes. -When a PR edits code near historical violations, reviewers should identify which -findings are new deterministic problems and which are pre-existing context. Fix -only the new deterministic problems unless the PR intentionally includes a -focused cleanup. +When a PR edits code near historical violations, reviewers should identify which findings are new +deterministic problems and which are pre-existing context. Fix only the new deterministic problems +unless the PR intentionally includes a focused cleanup. ## Core Coding Rules -- Do not introduce new cross-layer control through `GlobalV`, `GlobalC`, or - `PARAM`. Prefer explicit parameters or narrow local interfaces. -- Do not store workflow switches in mutable member variables that can be changed - implicitly from multiple places. -- Keep header dependencies minimal; avoid adding includes to headers unless the - declaration truly requires them. -- Avoid adding `.hpp` implementation headers and avoid including `.hpp` files - from other headers unless the PR explains why header-only implementation is - needed. -- Do not add default arguments to existing interfaces. Update call sites - explicitly or design a clearer overload/configuration object. -- Add short, focused tests for key functionality, bug fixes, INPUT behavior - changes, heterogeneous kernels, and core-module refactors. -- Keep default and general-purpose C++ changes compatible with the repository - C++11 baseline. Backend-specific or dependency-constrained paths may use the - higher standard already selected by existing CMake configuration. +- Do not introduce new cross-layer control through `GlobalV`, `GlobalC`, or `PARAM`. Prefer explicit + parameters or narrow local interfaces. +- Do not store workflow switches in mutable member variables that can be changed implicitly from + multiple places. +- Keep header dependencies minimal; avoid adding includes to headers unless the declaration truly + requires them. +- Avoid adding `.hpp` implementation headers and avoid including `.hpp` files from other headers + unless the PR explains why header-only implementation is needed. +- Do not add default arguments to existing interfaces. Update call sites explicitly or design a + clearer overload/configuration object. +- Add short, focused tests for key functionality, bug fixes, INPUT behavior changes, heterogeneous + kernels, and core-module refactors. +- Keep default and general-purpose C++ changes compatible with the repository C++11 baseline. + Backend-specific or dependency-constrained paths may use the higher standard already selected by + existing CMake configuration. - Use LF line endings for text files. `.bat` and `.cmd` are the CRLF exception. -- Place `ModuleBase::timer::start`/`end` at the beginning and end of a function, - not around isolated statements inside the function body. Use the enclosing - function name (or constructor name) as the timer label so the timer scopes - the whole unit of work. -- Do not use `#pragma once` in header files; use traditional - `#ifndef`/`#define`/`#endif` include guards instead. +- Place `ModuleBase::timer::start`/`end` at the beginning and end of a function, not around isolated + statements inside the function body. Use the enclosing function name (or constructor name) as the + timer label so the timer scopes the whole unit of work. +- Do not use `#pragma once` in header files; use traditional `#ifndef`/`#define`/`#endif` include + guards instead. AI agents have additional workflow obligations: @@ -65,52 +59,48 @@ AI agents have additional workflow obligations: ## Rule Grading Matrix -The first implementation phase separates deterministic mechanical checks from -review-only rules. "Phase-one mechanical" means the local hook or CI checker can -act on the PR diff without semantic judgment. "AI review" and "human -confirmation" items must be reviewed, but the checker does not hard-code those -decisions. - -| Rule category | Typical rule | Phase-one status | Default executor | Severity | Default action | Detection scope | Notes | -| --- | --- | --- | --- | --- | --- | --- | --- | -| Basic text format | LF line endings | phase-one mechanical | hook + CI | medium | block | full changed text file | `.bat` and `.cmd` keep CRLF | -| Header include guard | New `#pragma once` in a header | phase-one mechanical | hook + CI | high | block | added header lines (`.h`/`.hh`/`.hpp`/`.hxx`/`.cuh`) | Use `#ifndef`/`#define`/`#endif` guards; no exception allowed | -| Language baseline | C++11 compatibility | build/toolchain | CI | high | block | build/static tooling | Actual compiler/toolchain result wins | -| Global dependency budget | Net increase of `GlobalV`/`GlobalC`/`PARAM` references in code diff | phase-one mechanical + AI review | CI + AI review | high | block on net increase, warn on non-increasing added usage | added and removed code lines | Historical untouched usage and documentation mentions are not blocked; migration-neutral moves require reviewer rationale | -| New default parameter | Header declaration adds a default argument | phase-one mechanical + AI review | CI + AI review | high | block | header diff | High misuse risk | -| `.hpp` propagation | New `.hpp` or header includes `.hpp` | phase-one mechanical warning | CI + AI review | medium | warn | new files and added includes | Exception can be recorded in PR | -| Header dependency growth | Header diff adds includes | phase-one mechanical warning + AI review | CI + AI review | medium | warn | added header includes | Necessity is semantic and not mechanically decided | -| Member variable workflow switch | Key flow state hidden as mutable member state | AI review + human confirmation | AI + human review | high | human confirmation | semantic review | Static matching is unreliable | -| Timer placement | `timer::start`/`end` wrap a whole function body | AI review | AI + human review | low | warn | semantic review | Mechanical matching is unreliable for scopes; label should name the enclosing function | -| Module path and build linkage | New source path and `CMakeLists.txt` linkage | phase-one mechanical | CI | medium | block | new source files and build-script diff | Deterministic path/build check only | -| Module semantic ownership | Best module/submodule placement | AI review + human confirmation | AI + human review | medium | human confirmation | semantic review | Final call belongs to maintainers | -| Heterogeneous code linkage | CUDA/ROCM/kernel source and `CMakeLists.txt` linkage | phase-one mechanical | CI + AI review | medium | block | new heterogeneous files and linkage | Mechanical path/linkage only | -| Heterogeneous test evidence | CUDA/ROCM/kernel change has test evidence or reason | phase-one mechanical warning + AI review | CI + AI review | high | warn | changed paths and PR body | Sufficiency is human-reviewed | -| Test existence | Source change has test evidence or reason | phase-one mechanical warning + AI review | CI + AI review | high | warn | PR body and changed paths | Sufficiency is human-reviewed | -| Test sufficiency | Tests cover important behavior | AI review + human confirmation | AI + human review | medium | human confirmation | semantic review | Not mechanically blocked | -| INPUT behavior linkage | Parameter metadata/default/type/parser behavior updates YAML and docs | phase-one mechanical + AI review | CI + AI review | high | warn | behavior-field diff plus docs/PR body | Comment-only parameter-file changes are not blocked | -| Documentation sync | Behavior/interface docs updated | phase-one mechanical warning + AI review | CI + AI review | medium | warn | changed paths and PR body | Major behavior changes escalate to reviewers | -| PR metadata completeness | Issue, tests, behavior, INPUT, core impact, exceptions | phase-one mechanical | CI or GitHub bot | medium | warn | PR template fields | Not run by local hook | -| AI workflow | Interface lookup, uncertainty, verification report | AI review | AI review | high | warn | review transcript/output | Applies to AI agents | -| Exceptions | Reason, scope, risk, follow-up plan | human confirmation | human review + CI | high | human confirmation | PR exception section | CI checks presence, not approval | - -Implementations must use this matrix as the default baseline. Upgrading warnings -to blockers or converting human-confirmation rules into mechanical blockers -requires an explicit governance change. - -Deterministic errors require a code or documentation fix before merge unless a -maintainer-approved exception is recorded. Deterministic warnings require a -reviewable rationale or cleanup, but they do not become blockers without an -explicit governance change. For header include warnings, the rationale should -state whether the header needs a complete type, for example because it owns a -value member rather than a pointer or reference. - -For global dependencies, the mechanical checker uses a PR-level budget during -the legacy migration period. A PR blocks only when the number of code references -to `GlobalV`, `GlobalC`, or `PARAM` increases after accounting for deleted -references. If a PR adds global references while deleting at least as many -elsewhere, the checker warns instead of blocking; reviewers should confirm the -change is a migration-neutral move or part of a cleanup path. +The first implementation phase separates deterministic mechanical checks from review-only rules. +"Phase-one mechanical" means the local hook or CI checker can act on the PR diff without semantic +judgment. "AI review" and "human confirmation" items must be reviewed, but the checker does not +hard-code those decisions. + +| Rule category | Typical rule | Phase-one status | Default executor | Severity | Default action | Detection scope | Notes | +| ------------------------------- | --------------------------------------------------------------------- | ---------------------------------------- | ----------------- | -------- | --------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| Basic text format | LF line endings | phase-one mechanical | hook + CI | medium | block | full changed text file | `.bat` and `.cmd` keep CRLF | +| Header include guard | New `#pragma once` in a header | phase-one mechanical | hook + CI | high | block | added header lines (`.h`/`.hh`/`.hpp`/`.hxx`/`.cuh`) | Use `#ifndef`/`#define`/`#endif` guards; no exception allowed | +| Language baseline | C++11 compatibility | build/toolchain | CI | high | block | build/static tooling | Actual compiler/toolchain result wins | +| Global dependency budget | Net increase of `GlobalV`/`GlobalC`/`PARAM` references in code diff | phase-one mechanical + AI review | CI + AI review | high | block on net increase, warn on non-increasing added usage | added and removed code lines | Historical untouched usage and documentation mentions are not blocked; migration-neutral moves require reviewer rationale | +| New default parameter | Header declaration adds a default argument | phase-one mechanical + AI review | CI + AI review | high | block | header diff | High misuse risk | +| `.hpp` propagation | New `.hpp` or header includes `.hpp` | phase-one mechanical warning | CI + AI review | medium | warn | new files and added includes | Exception can be recorded in PR | +| Header dependency growth | Header diff adds includes | phase-one mechanical warning + AI review | CI + AI review | medium | warn | added header includes | Necessity is semantic and not mechanically decided | +| Member variable workflow switch | Key flow state hidden as mutable member state | AI review + human confirmation | AI + human review | high | human confirmation | semantic review | Static matching is unreliable | +| Timer placement | `timer::start`/`end` wrap a whole function body | AI review | AI + human review | low | warn | semantic review | Mechanical matching is unreliable for scopes; label should name the enclosing function | +| Module path and build linkage | New source path and `CMakeLists.txt` linkage | phase-one mechanical | CI | medium | block | new source files and build-script diff | Deterministic path/build check only | +| Module semantic ownership | Best module/submodule placement | AI review + human confirmation | AI + human review | medium | human confirmation | semantic review | Final call belongs to maintainers | +| Heterogeneous code linkage | CUDA/ROCM/kernel source and `CMakeLists.txt` linkage | phase-one mechanical | CI + AI review | medium | block | new heterogeneous files and linkage | Mechanical path/linkage only | +| Heterogeneous test evidence | CUDA/ROCM/kernel change has test evidence or reason | phase-one mechanical warning + AI review | CI + AI review | high | warn | changed paths and PR body | Sufficiency is human-reviewed | +| Test existence | Source change has test evidence or reason | phase-one mechanical warning + AI review | CI + AI review | high | warn | PR body and changed paths | Sufficiency is human-reviewed | +| Test sufficiency | Tests cover important behavior | AI review + human confirmation | AI + human review | medium | human confirmation | semantic review | Not mechanically blocked | +| INPUT behavior linkage | Parameter metadata/default/type/parser behavior updates YAML and docs | phase-one mechanical + AI review | CI + AI review | high | warn | behavior-field diff plus docs/PR body | Comment-only parameter-file changes are not blocked | +| Documentation sync | Behavior/interface docs updated | phase-one mechanical warning + AI review | CI + AI review | medium | warn | changed paths and PR body | Major behavior changes escalate to reviewers | +| PR metadata completeness | Issue, tests, behavior, INPUT, core impact, exceptions | phase-one mechanical | CI or GitHub bot | medium | warn | PR template fields | Not run by local hook | +| AI workflow | Interface lookup, uncertainty, verification report | AI review | AI review | high | warn | review transcript/output | Applies to AI agents | +| Exceptions | Reason, scope, risk, follow-up plan | human confirmation | human review + CI | high | human confirmation | PR exception section | CI checks presence, not approval | + +Implementations must use this matrix as the default baseline. Upgrading warnings to blockers or +converting human-confirmation rules into mechanical blockers requires an explicit governance change. + +Deterministic errors require a code or documentation fix before merge unless a maintainer-approved +exception is recorded. Deterministic warnings require a reviewable rationale or cleanup, but they do +not become blockers without an explicit governance change. For header include warnings, the +rationale should state whether the header needs a complete type, for example because it owns a value +member rather than a pointer or reference. + +For global dependencies, the mechanical checker uses a PR-level budget during the legacy migration +period. A PR blocks only when the number of code references to `GlobalV`, `GlobalC`, or `PARAM` +increases after accounting for deleted references. If a PR adds global references while deleting at +least as many elsewhere, the checker warns instead of blocking; reviewers should confirm the change +is a migration-neutral move or part of a cleanup path. ## Automation Responsibilities @@ -129,8 +119,8 @@ CI: AI review: - Explain governance findings in actionable terms. -- Add semantic review for module ownership, header dependency growth, test - sufficiency, INPUT metadata consistency, and AI workflow discipline. +- Add semantic review for module ownership, header dependency growth, test sufficiency, INPUT + metadata consistency, and AI workflow discipline. - Use the output format below for actionable findings. Human review: @@ -141,39 +131,35 @@ Human review: ## Existing Build And Toolchain References -Agents and contributors should reuse ABACUS entry points that already exist in -the repository: +Agents and contributors should reuse ABACUS entry points that already exist in the repository: -- CMake/CTest builds and test selection used by `.github/workflows/test.yml`, - such as `ctest --test-dir build -V -R MODULE_MD` for MD-focused changes. -- Development containers and CI images based on `Dockerfile.gnu`, - `Dockerfile.intel`, `Dockerfile.cuda`, and - `ghcr.io/deepmodeling/abacus-*`. -- Dependency and compiler setup under `toolchain/`, including the GNU, Intel, - and CUDA variants already covered by workflow checks. +- CMake/CTest builds and test selection used by `.github/workflows/test.yml`, such as + `ctest --test-dir build -V -R MODULE_MD` for MD-focused changes. +- Development containers and CI images based on `Dockerfile.gnu`, `Dockerfile.intel`, + `Dockerfile.cuda`, and `ghcr.io/deepmodeling/abacus-*`. +- Dependency and compiler setup under `toolchain/`, including the GNU, Intel, and CUDA variants + already covered by workflow checks. -Do not add a new container recipe, toolchain path, or agent-specific skill for -calculation tasks as part of governance-only work. If a future PR needs one, it -must explain why the existing Docker/toolchain paths are insufficient. +Do not add a new container recipe, toolchain path, or agent-specific skill for calculation tasks as +part of governance-only work. If a future PR needs one, it must explain why the existing +Docker/toolchain paths are insufficient. ## Local Runtime And MPI Testing -Use `OMP_NUM_THREADS=1` as the default for ABACUS runtime, integration, and MPI -tests unless the test explicitly requires another thread count. Agent sandboxes -can interfere with process visibility, socket creation, and MPI launch behavior; -when those details affect a result, rerun the command outside the restricted -sandbox before diagnosing an ABACUS failure. +Use `OMP_NUM_THREADS=1` as the default for ABACUS runtime, integration, and MPI tests unless the +test explicitly requires another thread count. Agent sandboxes can interfere with process +visibility, socket creation, and MPI launch behavior; when those details affect a result, rerun the +command outside the restricted sandbox before diagnosing an ABACUS failure. -OpenMPI `opal_ifinit: socket() failed errno=1` warnings from sandboxed -MPI-linked builds or runs should be treated as sandbox artifacts first, not as -project regressions. Do not relax existing integration tests or reference files -just to make a failure pass. Update references only when the intended behavior -changed and the PR explains why the new reference is correct. +OpenMPI `opal_ifinit: socket() failed errno=1` warnings from sandboxed MPI-linked builds or runs +should be treated as sandbox artifacts first, not as project regressions. Do not relax existing +integration tests or reference files just to make a failure pass. Update references only when the +intended behavior changed and the PR explains why the new reference is correct. ## CLI Verification -When a usable ABACUS executable is present, INPUT and command-line changes -should include the relevant CLI checks in the PR verification record: +When a usable ABACUS executable is present, INPUT and command-line changes should include the +relevant CLI checks in the PR verification record: ```bash ./build/abacus --version @@ -181,69 +167,61 @@ should include the relevant CLI checks in the PR verification record: ./build/abacus --check-input ``` -Run `--check-input` from a directory containing a valid `INPUT` case. If no -local executable or valid case is available, state that explicitly in the PR. +Run `--check-input` from a directory containing a valid `INPUT` case. If no local executable or +valid case is available, state that explicitly in the PR. ## AI PR Review Integration ABACUS uses a layered review model: -- `Agent Governance` is the deterministic GitHub Actions check for low-noise - diff rules. Repository maintainers may make this workflow a required check in - branch protection. -- CodeRabbit is a PR-triggered AI reviewer for semantic review hints. Its - repository configuration lives in `.coderabbit.yaml` and uses this document - plus `AGENTS.md` as review guidelines. -- GitHub Copilot code review is also present on upstream PRs. Repository-level - Copilot guidance lives in `.github/copilot-instructions.md`, and path-level - review guidance lives in `.github/instructions/*.instructions.md`. These - files point Copilot back to this governance document and the short - `AGENTS.md` entry point. -- CodeRabbit and Copilot comments are advisory by default. They do not replace - maintainer approval, exception approval, or numerical/test sufficiency review. - -To activate CodeRabbit on real PRs, a repository or organization administrator -must install the CodeRabbit GitHub App for `deepmodeling/abacus-develop` and -grant it pull request review access. After installation, non-draft pull requests -and new commits should receive automatic review according to `.coderabbit.yaml`; -if automatic review does not start, maintainers may request it with +- `Agent Governance` is the deterministic GitHub Actions check for low-noise diff rules. Repository + maintainers may make this workflow a required check in branch protection. +- CodeRabbit is a PR-triggered AI reviewer for semantic review hints. Its repository configuration + lives in `.coderabbit.yaml` and uses this document plus `AGENTS.md` as review guidelines. +- GitHub Copilot code review is also present on upstream PRs. Repository-level Copilot guidance + lives in `.github/copilot-instructions.md`, and path-level review guidance lives in + `.github/instructions/*.instructions.md`. These files point Copilot back to this governance + document and the short `AGENTS.md` entry point. +- CodeRabbit and Copilot comments are advisory by default. They do not replace maintainer approval, + exception approval, or numerical/test sufficiency review. + +To activate CodeRabbit on real PRs, a repository or organization administrator must install the +CodeRabbit GitHub App for `deepmodeling/abacus-develop` and grant it pull request review access. +After installation, non-draft pull requests and new commits should receive automatic review +according to `.coderabbit.yaml`; if automatic review does not start, maintainers may request it with `@coderabbitai review`. -To make Copilot follow the governance baseline, keep the Copilot custom -instruction files synchronized with this document whenever the review contract -changes. Copilot review behavior still depends on GitHub organization and -repository settings, and pull request reviews use the custom instructions from -the target base branch. New or changed instruction files therefore take effect -for later reviews after they are present on the base branch. +To make Copilot follow the governance baseline, keep the Copilot custom instruction files +synchronized with this document whenever the review contract changes. Copilot review behavior still +depends on GitHub organization and repository settings, and pull request reviews use the custom +instructions from the target base branch. New or changed instruction files therefore take effect for +later reviews after they are present on the base branch. -Copilot coding-agent setup steps, Qodo, and PR-Agent are not part of the -phase-one baseline. They require separate organization settings, secrets, or -setup workflows and should be added only through a later governance change. +Copilot coding-agent setup steps, Qodo, and PR-Agent are not part of the phase-one baseline. They +require separate organization settings, secrets, or setup workflows and should be added only through +a later governance change. ## INPUT Parameter Changes -Changes to parameter metadata, default values, type, availability, description, -or parsing behavior should update the corresponding C++ `Input_Item` -registrations. The generated YAML and Markdown documentation are build artifacts -and should not be edited or committed. +Changes to parameter metadata, default values, type, availability, description, or parsing behavior +should update the corresponding C++ `Input_Item` registrations. The generated YAML and Markdown +documentation are build artifacts and should not be edited or committed. -If the diff touches parameter internals but does not require an `Input_Item` -metadata change, the PR should state why. Missing metadata updates trigger a -governance warning (not a block), but maintainers may still request updates -before merging. +If the diff touches parameter internals but does not require an `Input_Item` metadata change, the PR +should state why. Missing metadata updates trigger a governance warning (not a block), but +maintainers may still request updates before merging. ## PR Self-Consistency Before requesting review, check that the PR description matches the diff: -- New or changed INPUT behavior lists the changed parameters and any corresponding - `Input_Item` metadata updates. -- Source changes list focused unit, case, or CLI verification commands with the - observed result. -- Header include growth, `.hpp` propagation, missing tests, or other warnings - have either been fixed or have a rationale in the PR body. -- Exceptions include reason, scope, risk, why the normal rule cannot be followed - now, a follow-up cleanup plan, and the requested approver. +- New or changed INPUT behavior lists the changed parameters and any corresponding `Input_Item` + metadata updates. +- Source changes list focused unit, case, or CLI verification commands with the observed result. +- Header include growth, `.hpp` propagation, missing tests, or other warnings have either been fixed + or have a rationale in the PR body. +- Exceptions include reason, scope, risk, why the normal rule cannot be followed now, a follow-up + cleanup plan, and the requested approver. ## Exception Template diff --git a/docs/developers_guide/basic_types_class.md b/docs/developers_guide/basic_types_class.md index c582665e96c..56b74a4e506 100644 --- a/docs/developers_guide/basic_types_class.md +++ b/docs/developers_guide/basic_types_class.md @@ -2,7 +2,9 @@ ## Overview -This document provides guidelines for designing and implementing basic tool classes in the ABACUS codebase, focusing on best practices for memory management, code style, and testing. These guidelines apply to all basic mathematical and utility classes, including but not limited to: +This document provides guidelines for designing and implementing basic tool classes in the ABACUS +codebase, focusing on best practices for memory management, code style, and testing. These +guidelines apply to all basic mathematical and utility classes, including but not limited to: - vector3.h - matrix.h @@ -16,7 +18,8 @@ This document provides guidelines for designing and implementing basic tool clas - formatter.h - math_chebyshev.h -While this guide uses `IntArray` as an example for illustration purposes, the principles and practices described here are applicable to all basic tool classes in ABACUS. +While this guide uses `IntArray` as an example for illustration purposes, the principles and +practices described here are applicable to all basic tool classes in ABACUS. ## Memory Management @@ -26,11 +29,13 @@ Always use try-catch blocks when allocating memory to handle `std::bad_alloc` ex ### 2. Two-Stage Memory Allocation -When reallocating memory (e.g., in `create` methods), use a two-stage approach to ensure that the original object remains valid if memory allocation fails. +When reallocating memory (e.g., in `create` methods), use a two-stage approach to ensure that the +original object remains valid if memory allocation fails. ### 3. Null Pointer Checks -Always check for null pointers before accessing memory, especially in methods that might be called on objects with failed memory allocation. +Always check for null pointers before accessing memory, especially in methods that might be called +on objects with failed memory allocation. ## Class Design @@ -50,7 +55,8 @@ Add boundary checks to prevent out-of-bounds access. ### 1. Brace Style -Use separate lines for braces, and always use braces for "if" and "for" statements, even if they contain one line of code +Use separate lines for braces, and always use braces for "if" and "for" statements, even if they +contain one line of code ### 2. Indentation @@ -58,7 +64,8 @@ Use spaces instead of tabs for indentation (4 spaces per indent level). ### 3. Comments -Use English for comments and document important functionality. Follow Doxygen-style documentation for classes and methods. +Use English for comments and document important functionality. Follow Doxygen-style documentation +for classes and methods. ## Code Quality @@ -79,6 +86,7 @@ Ensure all necessary header files are included, especially for functions like `a ### 1. Unit Tests Write comprehensive unit tests for all classes, including: + - Constructor tests - Method tests - Exception handling tests @@ -107,34 +115,42 @@ protected: ## Best Practices -1. **Single Responsibility Principle**: Each class should have a single, well-defined responsibility. -2. **Encapsulation**: Hide implementation details and expose only necessary interfaces. -3. **Error Handling**: Handle errors gracefully, especially memory allocation failures. -4. **Performance**: Use move semantics and other performance optimizations where appropriate. -5. **Testing**: Write comprehensive tests for all functionality. -6. **Code Style**: Follow consistent code style guidelines, including: +1. **Single Responsibility Principle**: Each class should have a single, well-defined + responsibility. +1. **Encapsulation**: Hide implementation details and expose only necessary interfaces. +1. **Error Handling**: Handle errors gracefully, especially memory allocation failures. +1. **Performance**: Use move semantics and other performance optimizations where appropriate. +1. **Testing**: Write comprehensive tests for all functionality. +1. **Code Style**: Follow consistent code style guidelines, including: - Always use braces for if and for statements - Use separate lines for braces - Use spaces instead of tabs for indentation - Use English for comments -7. **Code Quality**: Maintain high code quality by: +1. **Code Quality**: Maintain high code quality by: - Using named constants instead of magic numbers - Ensuring all necessary header files are included - Adding boundary checks to prevent out-of-bounds access -8. **Documentation**: Document classes and methods to improve maintainability. -9. **Compatibility**: Ensure code is compatible with C++11 standard. -10. **Portability**: Write code that works across different platforms. -11. **Reusability**: Design classes to be reusable in different contexts. +1. **Documentation**: Document classes and methods to improve maintainability. +1. **Compatibility**: Ensure code is compatible with C++11 standard. +1. **Portability**: Write code that works across different platforms. +1. **Reusability**: Design classes to be reusable in different contexts. ## Application to Other Basic Tool Classes -While this guide uses `IntArray` as an example, these principles apply to all basic tool classes in ABACUS. For example: +While this guide uses `IntArray` as an example, these principles apply to all basic tool classes in +ABACUS. For example: -- **vector3.h**: Apply the same memory management and error handling principles, with additional focus on vector operations and operator overloading. -- **matrix.h**: Extend the memory management practices to 2D arrays, with additional considerations for matrix operations. +- **vector3.h**: Apply the same memory management and error handling principles, with additional + focus on vector operations and operator overloading. +- **matrix.h**: Extend the memory management practices to 2D arrays, with additional considerations + for matrix operations. - **timer.h**: Focus on static member management and time measurement accuracy. -- **ndarray.h**: Apply the same principles to multi-dimensional arrays, with additional considerations for shape manipulation. -- **formatter.h**: Focus on string manipulation and formatting, with attention to performance and usability. -- **math_chebyshev.h**: Apply the principles to template classes, with additional focus on mathematical algorithm implementation. - -By following these guidelines, you can ensure that all basic tool classes in ABACUS are well-designed, robust, and maintainable. +- **ndarray.h**: Apply the same principles to multi-dimensional arrays, with additional + considerations for shape manipulation. +- **formatter.h**: Focus on string manipulation and formatting, with attention to performance and + usability. +- **math_chebyshev.h**: Apply the principles to template classes, with additional focus on + mathematical algorithm implementation. + +By following these guidelines, you can ensure that all basic tool classes in ABACUS are +well-designed, robust, and maintainable. diff --git a/docs/developers_guide/input_availability.md b/docs/developers_guide/input_availability.md index 40a97e45d43..7cf4c202875 100644 --- a/docs/developers_guide/input_availability.md +++ b/docs/developers_guide/input_availability.md @@ -2,25 +2,23 @@ ## Purpose -Input item availability metadata describes when an INPUT parameter is -applicable. It is used by documentation and tooling; it does not reject or -alter a user's INPUT based on this condition. Runtime diagnostics, if added, -must define how explicitly supplied parameters whose conditions are false are -handled. +Input item availability metadata describes when an INPUT parameter is applicable. It is used by +documentation and tooling; it does not reject or alter a user's INPUT based on this condition. +Runtime diagnostics, if added, must define how explicitly supplied parameters whose conditions are +false are handled. ## Invariants -- The C++ `Input_Item` registration is the source of truth. YAML and Markdown - are generated artifacts. -- Every non-empty registration is canonical. `set_availability()` rejects - syntax errors and non-canonical spelling. -- The AST is the stored representation; the exported string is serialized from - it, so the two forms cannot diverge. -- Every expression is a complete, independently evaluable predicate. It must - include enclosing requirements rather than inheriting them implicitly from a - referenced parameter. -- After all INPUT items are registered, every referenced label, operator and - literal is checked against machine-readable parameter type information. +- The C++ `Input_Item` registration is the source of truth. YAML and Markdown are generated + artifacts. +- Every non-empty registration is canonical. `set_availability()` rejects syntax errors and + non-canonical spelling. +- The AST is the stored representation; the exported string is serialized from it, so the two forms + cannot diverge. +- Every expression is a complete, independently evaluable predicate. It must include enclosing + requirements rather than inheriting them implicitly from a referenced parameter. +- After all INPUT items are registered, every referenced label, operator and literal is checked + against machine-readable parameter type information. ## Grammar and meaning @@ -36,39 +34,32 @@ comparison := "==" | "!=" | ">" | ">=" | "<" | "<=" value := bare-value | '"' quote-required-value '"' ``` -The grammar describes the canonical form of a non-empty expression. A compound -expression contains only one kind of Boolean operator. When a compound -expression is used as an operand of another compound expression, it must be -parenthesized, even when operator precedence would make the grouping +The grammar describes the canonical form of a non-empty expression. A compound expression contains +only one kind of Boolean operator. When a compound expression is used as an operand of another +compound expression, it must be parenthesized, even when operator precedence would make the grouping unambiguous. A single condition must not be parenthesized. For example, -`(basis_type==pw and calculation==scf) or esolver_type==sdft` is canonical, -while `basis_type==pw and calculation==scf or esolver_type==sdft` and -`(basis_type==pw)` are not. +`(basis_type==pw and calculation==scf) or esolver_type==sdft` is canonical, while +`basis_type==pw and calculation==scf or esolver_type==sdft` and `(basis_type==pw)` are not. -Canonical formatting is required: comparison operators have no surrounding -spaces; `and`, `or`, `in`, and `contains` have one space on each side; and list -items are separated by a comma followed by one space. For example, -`mode in [a, b]` is valid, while `mode in [a,b]` is rejected. Leading or -trailing whitespace is not allowed, and a comma is not an alternative spelling -of `and`. The parser accepts only the spelling produced by the AST serializer, -so forms such as `basis_type == pw` and +Canonical formatting is required: comparison operators have no surrounding spaces; `and`, `or`, +`in`, and `contains` have one space on each side; and list items are separated by a comma followed +by one space. For example, `mode in [a, b]` is valid, while `mode in [a,b]` is rejected. Leading or +trailing whitespace is not allowed, and a comma is not an alternative spelling of `and`. The parser +accepts only the spelling produced by the AST serializer, so forms such as `basis_type == pw` and `basis_type==pw,calculation==scf` are also rejected. -`bare-value` is a non-empty value containing no whitespace or any of -`()[],=<>!`. A value containing at least one of those characters must use the -non-empty double-quoted form, and a value that does not require quotes must not -use them. Thus `basis_type==pw` and `relax_method==cg` are canonical, while -`basis_type=="pw"` is not. `==` compares one complete value. Two or more -alternatives use `in [...]`, while `parameter contains value` tests whether a -vector contains one element, such as `td_ttype contains 0`. `/` is an ordinary -value character, not another spelling of membership. Ordered comparisons -require a numeric scalar. +`bare-value` is a non-empty value containing no whitespace or any of `()[],=<>!`. A value containing +at least one of those characters must use the non-empty double-quoted form, and a value that does +not require quotes must not use them. Thus `basis_type==pw` and `relax_method==cg` are canonical, +while `basis_type=="pw"` is not. `==` compares one complete value. Two or more alternatives use +`in [...]`, while `parameter contains value` tests whether a vector contains one element, such as +`td_ttype contains 0`. `/` is an ordinary value character, not another spelling of membership. +Ordered comparisons require a numeric scalar. -A path that references a parameter must imply that parameter's availability. -Every `and` operand is required, while satisfying either branch of an `or` is -sufficient. Repeated `and` or `or` groups are order-independent. Different leaf -conditions are not related; for example, `mode==a` does not satisfy -`mode in [a, b]`. +A path that references a parameter must imply that parameter's availability. Every `and` operand is +required, while satisfying either branch of an `or` is sufficient. Repeated `and` or `or` groups are +order-independent. Different leaf conditions are not related; for example, `mode==a` does not +satisfy `mode in [a, b]`. Examples: @@ -82,11 +73,12 @@ item.set_availability("esolver_type==sdft and method_sto==2"); ## Registration and validation workflow 1. Parse and require canonical spelling in `set_availability()`. -2. Finish registering all `Input_Item` objects. -3. Validate referenced parameter names, operator compatibility, literal values, and that every referenced parameter carries its own enclosing requirements on the referencing path. -4. Serialize the AST to YAML as part of the documentation build. -5. Generate the INPUT reference documentation from that YAML. +1. Finish registering all `Input_Item` objects. +1. Validate referenced parameter names, operator compatibility, literal values, and that every + referenced parameter carries its own enclosing requirements on the referencing path. +1. Serialize the AST to YAML as part of the documentation build. +1. Generate the INPUT reference documentation from that YAML. -Runtime evaluation is outside this metadata contract. Any implementation must -define evaluation timing, treatment of defaults and reset values, and warning -behavior for explicitly supplied parameters. +Runtime evaluation is outside this metadata contract. Any implementation must define evaluation +timing, treatment of defaults and reset values, and warning behavior for explicitly supplied +parameters. diff --git a/docs/quick_start/easy_install.md b/docs/quick_start/easy_install.md index 637b4bb54fb..8cad0e54fc1 100644 --- a/docs/quick_start/easy_install.md +++ b/docs/quick_start/easy_install.md @@ -1,20 +1,37 @@ # Easy Installation -This guide helps you install ABACUS with basic features. **For DeePKS, DeePMD and Libxc support, or building with `make`, please refer to [the advanced installation guide](../advanced/install.md)** after going through this page. We recommend building ABACUS with `cmake` to avoid dependency issues. We recommend compiling ABACUS (and possibly its requirements) from the source code using the latest compiler for the best performace. You can use [toolchain](#install-by-toolchain) to install ABACUS and dependencies in a source-code compilation way with convience. You can also deploy ABACUS **without building** by [Docker](#container-deployment) or [conda](#install-by-conda). Please note that ABACUS only supports Linux; for Windows users, please consider using [WSL](https://learn.microsoft.com/en-us/windows/wsl/) or docker. For a scripted one-click setup that provisions WSL2 and installs ABACUS inside it automatically, see [Windows One-Click Installer](../advanced/windows_installer.md). +This guide helps you install ABACUS with basic features. **For DeePKS, DeePMD and Libxc support, or +building with `make`, please refer to [the advanced installation guide](../advanced/install.md)** +after going through this page. We recommend building ABACUS with `cmake` to avoid dependency issues. +We recommend compiling ABACUS (and possibly its requirements) from the source code using the latest +compiler for the best performace. You can use [toolchain](#install-by-toolchain) to install ABACUS +and dependencies in a source-code compilation way with convience. You can also deploy ABACUS +**without building** by [Docker](#container-deployment) or [conda](#install-by-conda). Please note +that ABACUS only supports Linux; for Windows users, please consider using +[WSL](https://learn.microsoft.com/en-us/windows/wsl/) or docker. For a scripted one-click setup that +provisions WSL2 and installs ABACUS inside it automatically, see +[Windows One-Click Installer](../advanced/windows_installer.md). ## Get ABACUS source code ABACUS source code can be obtained via one of the following choices: - Clone the whole repo with git: `git clone https://github.com/deepmodeling/abacus-develop.git` -- Clone the minimum required part of repo: `git clone https://github.com/deepmodeling/abacus-develop.git --depth=1` -- Download the latest source code without git: `wget https://github.com/deepmodeling/abacus-develop/archive/refs/heads/develop.zip` -- Get the source code of a stable version [here](https://github.com/deepmodeling/abacus-develop/releases) -- If you have connection issues accessing GitHub, please try out our official [Gitee repo](https://gitee.com/deepmodeling/abacus-develop/): e.g. `git clone https://gitee.com/deepmodeling/abacus-develop.git`. This Gitee repo is updated synchronously with GitHub. +- Clone the minimum required part of repo: + `git clone https://github.com/deepmodeling/abacus-develop.git --depth=1` +- Download the latest source code without git: + `wget https://github.com/deepmodeling/abacus-develop/archive/refs/heads/develop.zip` +- Get the source code of a stable version + [here](https://github.com/deepmodeling/abacus-develop/releases) +- If you have connection issues accessing GitHub, please try out our official + [Gitee repo](https://gitee.com/deepmodeling/abacus-develop/): e.g. + `git clone https://gitee.com/deepmodeling/abacus-develop.git`. This Gitee repo is updated + synchronously with GitHub. ## Update to latest release by git -Please check the [release page](https://github.com/deepmodeling/abacus-develop/releases) for the release note of a new version. +Please check the [release page](https://github.com/deepmodeling/abacus-develop/releases) for the +release note of a new version. It is OK to download the new source code from beginning following the previous step. @@ -32,7 +49,8 @@ git checkout v3.x.x # Replace the tag with the latest version, like v3.10.0 git describe --tags # Verify if the tag has been successfully checked out ``` -Then proceed to the [Build and Install](#build-and-install) part. If you encountered errors, try remove the `build` directory first and reconfigure. +Then proceed to the [Build and Install](#build-and-install) part. If you encountered errors, try +remove the `build` directory first and reconfigure. To use the codes under active development: @@ -46,33 +64,51 @@ git pull To compile ABACUS, please make sure that the following prerequisites are present: - [CMake](https://cmake.org/) >= 3.16 . -- C++ compiler, supporting C++11. You can use [Intelยฎ C++ compiler](https://software.intel.com/enus/c-compilers) or [GCC](https://gcc.gnu.org/). +- C++ compiler, supporting C++11. You can use + [Intelยฎ C++ compiler](https://software.intel.com/enus/c-compilers) or [GCC](https://gcc.gnu.org/). -> GCC version 5 or later is always required. Intel compilers also use GCC headers and libraries[(ref)](https://www.intel.com/content/www/us/en/develop/documentation/cpp-compiler-developer-guide-and-reference/top/compatibility-and-portability/gcc-compatibility-and-interoperability.html#gcc-compatibility-and-interoperability_GUID-52CB6FE0-83DA-4028-9EF4-0DFAF1652736). +> GCC version 5 or later is always required. Intel compilers also use GCC headers and +> libraries[(ref)](https://www.intel.com/content/www/us/en/develop/documentation/cpp-compiler-developer-guide-and-reference/top/compatibility-and-portability/gcc-compatibility-and-interoperability.html#gcc-compatibility-and-interoperability_GUID-52CB6FE0-83DA-4028-9EF4-0DFAF1652736). -- Fortran compiler if you are building dependencies written by Fortran, such as `BLAS`, `LAPACK`, `ScaLAPACK`, and `ELPA`, from source file. You can use [Intelยฎ Fortran Compiler](https://www.intel.com/content/www/us/en/developer/tools/oneapi/fortran-compiler.html) or [GFortran](https://gcc.gnu.org/fortran/). +- Fortran compiler if you are building dependencies written by Fortran, such as `BLAS`, `LAPACK`, + `ScaLAPACK`, and `ELPA`, from source file. You can use + [Intelยฎ Fortran Compiler](https://www.intel.com/content/www/us/en/developer/tools/oneapi/fortran-compiler.html) + or [GFortran](https://gcc.gnu.org/fortran/). - [BLAS](http://www.netlib.org/blas/). You can use [OpenBLAS](https://www.openblas.net/). - [LAPACK](http://www.netlib.org/lapack/). - [FFTW3](http://www.fftw.org/). If you are building ABACUS with MPI parallel support, you'll also need at least: -- MPI library. The recommended implementations include [Intel MPI](https://software.intel.com/enus/mpi-library), [MPICH](https://www.mpich.org/), and [Open MPI](https://www.open-mpi.org/). +- MPI library. The recommended implementations include + [Intel MPI](https://software.intel.com/enus/mpi-library), [MPICH](https://www.mpich.org/), and + [Open MPI](https://www.open-mpi.org/). - [ScaLAPACK](http://www.netlib.org/scalapack/). ## Install by toolchain We offer a set of [toolchain](https://github.com/deepmodeling/abacus-develop/tree/develop/toolchain) -scripts to compile and install all the requirements and ABACUS itself -automatically and suitable for machine characteristic in an online or offline way. -The toolchain can be downloaded with ABACUS repo, and users can easily compile the requirements by running `toolchain_[gnu,gcc-mkl,intel,gcc-aocl,aocc-aocl].sh` and ABACUS itself by running `build_abacus_[gnu,gcc-mkl,intel,gcc-aocl,aocc-aocl].sh` script in the toolchain directory in `GNU`, `Intel-oneAPI` , `GCC-AMD AOCL` and `AMD AOCC-AOCL` toolchain. -Sometimes, ABACUS by toolchain installation may have better efficient performance due to the suitable compiled dependencies. One should read the [README in toolchain](https://github.com/deepmodeling/abacus-develop/tree/develop/toolchain/README.md) for most of the information before use, and related tutorials can be accessed via ABACUS WeChat platform. +scripts to compile and install all the requirements and ABACUS itself automatically and suitable for +machine characteristic in an online or offline way. The toolchain can be downloaded with ABACUS +repo, and users can easily compile the requirements by running +`toolchain_[gnu,gcc-mkl,intel,gcc-aocl,aocc-aocl].sh` and ABACUS itself by running +`build_abacus_[gnu,gcc-mkl,intel,gcc-aocl,aocc-aocl].sh` script in the toolchain directory in `GNU`, +`Intel-oneAPI` , `GCC-AMD AOCL` and `AMD AOCC-AOCL` toolchain. Sometimes, ABACUS by toolchain +installation may have better efficient performance due to the suitable compiled dependencies. One +should read the +[README in toolchain](https://github.com/deepmodeling/abacus-develop/tree/develop/toolchain/README.md) +for most of the information before use, and related tutorials can be accessed via ABACUS WeChat +platform. ## Install by conda Conda is a package management system with a separated environment, not requiring system privileges. -You can refer to [DeepModeling conda FAQ](https://docs.deepmodeling.com/faq/conda.html) for how to setup a conda environment. -A pre-built ABACUS binary with all requirements is available at [conda-forge](https://anaconda.org/conda-forge/abacus). It supports advanced features including Libxc, LibRI, and DeePKS. Conda will install the GPU-supported version of ABACUS if a valid GPU driver is present. Please refer to [the advanced installation guide](../advanced/install.md) for more details. +You can refer to [DeepModeling conda FAQ](https://docs.deepmodeling.com/faq/conda.html) for how to +setup a conda environment. A pre-built ABACUS binary with all requirements is available at +[conda-forge](https://anaconda.org/conda-forge/abacus). It supports advanced features including +Libxc, LibRI, and DeePKS. Conda will install the GPU-supported version of ABACUS if a valid GPU +driver is present. Please refer to [the advanced installation guide](../advanced/install.md) for +more details. ```bash # Install @@ -87,13 +123,18 @@ OMP_NUM_THREADS=1 mpirun -n 4 abacus conda update -n abacus_env abacus -c conda-forge ``` -> If OpenBLAS gives warning about OpenMP threads, please install conda package `"openblas=*=openmp*"` or `"libblas=*=*mkl"`. See [switching BLAS implementation in conda](https://conda-forge.org/docs/maintainer/knowledge_base.html#switching-blas-implementation). +> If OpenBLAS gives warning about OpenMP threads, please install conda package +> `"openblas=*=openmp*"` or `"libblas=*=*mkl"`. See +> [switching BLAS implementation in conda](https://conda-forge.org/docs/maintainer/knowledge_base.html#switching-blas-implementation). -> ABACUS supports `OpenMPI` and `MPICH` variant. Install `mpich` or `openmpi` package to switch MPI library if required. +> ABACUS supports `OpenMPI` and `MPICH` variant. Install `mpich` or `openmpi` package to switch MPI +> library if required. -For more details on building a conda package of ABACUS locally, please refer to the [conda recipe file](https://github.com/deepmodeling/abacus-develop/blob/develop/conda/meta.yaml). +For more details on building a conda package of ABACUS locally, please refer to the +[conda recipe file](https://github.com/deepmodeling/abacus-develop/blob/develop/conda/meta.yaml). -> Note: The [deepmodeling conda channel](https://anaconda.org/deepmodeling/abacus) offers historical versions of ABACUS. +> Note: The [deepmodeling conda channel](https://anaconda.org/deepmodeling/abacus) offers historical +> versions of ABACUS. ### Developing with conda @@ -111,33 +152,44 @@ export CMAKE_PREFIX_PATH=`python -c 'import torch;print(torch.utils.cmake_prefix # usually expands to `$CONDA_PREFIX/lib/python3.1/site-packages/torch/share/cmake` ``` -And, follow the instructions in [Build and Install](#build-and-install) part above withou manually setting paths to dependencies. -See [the advanced installation guide](../advanced/install.md) for more features. -Make sure the environment variables are set before running `cmake`. -Possible command: `cmake -B build -DENABLE_MLALGO=ON -DENABLE_LIBXC=ON -DENABLE_LIBRI=ON`. - +And, follow the instructions in [Build and Install](#build-and-install) part above withou manually +setting paths to dependencies. See [the advanced installation guide](../advanced/install.md) for +more features. Make sure the environment variables are set before running `cmake`. Possible command: +`cmake -B build -DENABLE_MLALGO=ON -DENABLE_LIBXC=ON -DENABLE_LIBRI=ON`. ## Install ABACUS manually ### Install requirements -Some of these packages can be installed with popular package management system via root permission if you have, such as `apt` and `yum`. For example: +Some of these packages can be installed with popular package management system via root permission +if you have, such as `apt` and `yum`. For example: ```bash sudo apt update && sudo apt install -y libopenmpi-dev libopenblas-openmp-dev libscalapack-openmpi-dev libelpa-dev libfftw3-dev libcereal-dev libxc-dev nlohmann-json3-dev g++ make cmake bc git pkgconf ``` -> Installing ELPA by apt only matches requirements on Ubuntu 22.04. For earlier linux distributions, you should build ELPA from source. +> Installing ELPA by apt only matches requirements on Ubuntu 22.04. For earlier linux distributions, +> you should build ELPA from source. -You can also use [Intelยฎ oneAPI toolkit](https://www.intel.com/content/www/us/en/developer/tools/oneapi/oneapi-toolkit.html) (former Intelยฎ Parallel Studio) as toolchain. The [Intelยฎ oneAPI Base Toolkit](https://software.intel.com/content/www/us/en/develop/tools/oneapi/all-toolkits.html#base-kit) contains Intelยฎ oneAPI Math Kernel Library (aka `MKL`), including `BLAS`, `LAPACK`, `ScaLAPACK` and `FFTW3`. The [Intelยฎ oneAPI HPC Toolkit](https://software.intel.com/content/www/us/en/develop/tools/oneapi/all-toolkits.html#hpc-kit) contains Intelยฎ MPI Library, and C++ compiler (including MPI compiler). (Note: Since version 2026.0.0, the two toolkits has been merged into a single [Intelยฎ oneAPI toolkits](https://www.intel.com/content/www/us/en/developer/tools/oneapi/oneapi-toolkit.html)) +You can also use +[Intelยฎ oneAPI toolkit](https://www.intel.com/content/www/us/en/developer/tools/oneapi/oneapi-toolkit.html) +(former Intelยฎ Parallel Studio) as toolchain. The +[Intelยฎ oneAPI Base Toolkit](https://software.intel.com/content/www/us/en/develop/tools/oneapi/all-toolkits.html#base-kit) +contains Intelยฎ oneAPI Math Kernel Library (aka `MKL`), including `BLAS`, `LAPACK`, `ScaLAPACK` and +`FFTW3`. The +[Intelยฎ oneAPI HPC Toolkit](https://software.intel.com/content/www/us/en/develop/tools/oneapi/all-toolkits.html#hpc-kit) +contains Intelยฎ MPI Library, and C++ compiler (including MPI compiler). (Note: Since version +2026.0.0, the two toolkits has been merged into a single +[Intelยฎ oneAPI toolkits](https://www.intel.com/content/www/us/en/developer/tools/oneapi/oneapi-toolkit.html)) ```{note} - Please note that building `elpa` with a different MPI library may cause conflict. Don't forget to [set environment variables](https://software.intel.com/content/www/us/en/develop/documentation/get-started-with-intel-oneapi-render-linux/top/configure-your-system.html) before you start! - `cmake` will use Intel MKL if the environment variable `MKLROOT` is set. ``` -Please refer to our [guide](https://github.com/deepmodeling/abacus-develop/wiki/Building-and-Running-ABACUS) on installing requirements. - +Please refer to our +[guide](https://github.com/deepmodeling/abacus-develop/wiki/Building-and-Running-ABACUS) on +installing requirements. ### Configure @@ -148,15 +200,23 @@ cd abacus-develop cmake -B build [-D =] ... ``` -Here, 'build' is the path for building ABACUS; and '-D' is used for setting up some variables for CMake indicating optional components or requirement positions. +Here, 'build' is the path for building ABACUS; and '-D' is used for setting up some variables for +CMake indicating optional components or requirement positions. - `CMAKE_INSTALL_PREFIX`: the path of ABACUS binary to install; `/usr/local/bin/abacus` by default + - Compilers - - `CMAKE_CXX_COMPILER`: C++ compiler; usually `g++`(GNU C++ compiler) or `icpx`(Intel C++ compiler). Can also set from environment variable `CXX`. It is OK to use MPI compiler here. - - `MPI_CXX_COMPILER`: MPI wrapper for C++ compiler; usually `mpicxx` or `mpiicpx`(for Intel toolkits) or `mpiicpc`(for classic Intel Compiler Classic MPI before 2024.0). + + - `CMAKE_CXX_COMPILER`: C++ compiler; usually `g++`(GNU C++ compiler) or `icpx`(Intel C++ + compiler). Can also set from environment variable `CXX`. It is OK to use MPI compiler here. + - `MPI_CXX_COMPILER`: MPI wrapper for C++ compiler; usually `mpicxx` or `mpiicpx`(for Intel + toolkits) or `mpiicpc`(for classic Intel Compiler Classic MPI before 2024.0). - Requirements: Unless indicated, CMake will try to find under default paths. - - `MKLROOT`: If environment variable `MKLROOT` exists, `cmake` will take MKL as a preference, i.e. not using `LAPACK`, `ScaLAPACK` and `FFTW`. To disable MKL, unset environment variable `MKLROOT`, or pass `-DMKLROOT=OFF` to `cmake`. + + - `MKLROOT`: If environment variable `MKLROOT` exists, `cmake` will take MKL as a preference, i.e. + not using `LAPACK`, `ScaLAPACK` and `FFTW`. To disable MKL, unset environment variable + `MKLROOT`, or pass `-DMKLROOT=OFF` to `cmake`. - `LAPACK_DIR`: Path to OpenBLAS library `libopenblas.so`(including BLAS and LAPACK) - `SCALAPACK_DIR`: Path to ScaLAPACK library `libscalapack.so` - `FFTW3_DIR`: Path to FFTW3. @@ -164,21 +224,37 @@ Here, 'build' is the path for building ABACUS; and '-D' is used for setting up s - `LIBCOMM_DIR`: (Optional) Path to LibComm when `ENABLE_LIBRI=ON`. ```{important} -For some dependencies built with CMake, such as Libxc, dftd4, cereal, and nlohmann-json, you'll have to add their prefix paths to the environment variable `CMAKE_PREFIX_PATH` so that CMake can correctly find and use their CMake configuration files. A non-general variable such as `PKG_DIR` is discouraged for these packages. +For some dependencies built with CMake, such as Libxc, dftd4, cereal, and nlohmann-json, you'll have +to add their prefix paths to the environment variable `CMAKE_PREFIX_PATH` so that CMake can +correctly find and use their CMake configuration files. A non-general variable such as `PKG_DIR` is +discouraged for these packages. ``` -- Components: The values of these variables should be 'ON', '1' or 'OFF', '0'. The default values are given below. - - `ENABLE_LCAO=ON`: Enable LCAO calculation. If SCALAPACK, ELPA or CEREAL is absent and only require plane-wave calculations, the feature of calculating LCAO basis can be turned off. - - `ENABLE_LIBXC=OFF`: [Enable Libxc](../advanced/install.md#add-libxc-support) to suppport variety of functionals. - - `ENABLE_LIBRI=OFF`: [Enable LibRI](../advanced/install.md#add-libri-support) and its LibComm dependency for hybrid-functional calculations. Set `LIBRI_DIR` and `LIBCOMM_DIR` to use manually installed libraries. - - `ENABLE_JSON=OFF`: [Enable JSON output](../advanced/install.md#build-with-json-support) through nlohmann-json. - - `ENABLE_OPENMP=ON`: Enable OpenMP support. Building ABACUS without OpenMP is not fully tested yet. +- Components: The values of these variables should be 'ON', '1' or 'OFF', '0'. The default values + are given below. + - `ENABLE_LCAO=ON`: Enable LCAO calculation. If SCALAPACK, ELPA or CEREAL is absent and only + require plane-wave calculations, the feature of calculating LCAO basis can be turned off. + - `ENABLE_LIBXC=OFF`: [Enable Libxc](../advanced/install.md#add-libxc-support) to suppport variety + of functionals. + - `ENABLE_LIBRI=OFF`: [Enable LibRI](../advanced/install.md#add-libri-support) and its LibComm + dependency for hybrid-functional calculations. Set `LIBRI_DIR` and `LIBCOMM_DIR` to use manually + installed libraries. + - `ENABLE_JSON=OFF`: [Enable JSON output](../advanced/install.md#build-with-json-support) through + nlohmann-json. + - `ENABLE_OPENMP=ON`: Enable OpenMP support. Building ABACUS without OpenMP is not fully tested + yet. - `BUILD_TESTING=OFF`: [Build unit tests](../advanced/install.md#build-unit-tests). - - `ENABLE_GOOGLEBENCH=OFF`: [Build performance tests](../advanced/install.md#build-performance-tests) - - `ENABLE_MPI=ON`: Enable MPI parallel compilation. If set to `OFF`, a serial version of ABACUS will be compiled. It now supports both PW and LCAO. - - `ENABLE_COVERAGE=OFF`: Build ABACUS executable supporting [coverage analysis](../CONTRIBUTING.md#generating-code-coverage-report). This feature has a drastic impact on performance. - - `ENABLE_ASAN=OFF`: Build with Address Sanitizer. This feature would help detecting memory problems. - - `ENABLE_ELPA=ON`: Use ELPA library in LCAO calculations. If this value is set to OFF, ABACUS can be compiled without ELPA library. + - `ENABLE_GOOGLEBENCH=OFF`: + [Build performance tests](../advanced/install.md#build-performance-tests) + - `ENABLE_MPI=ON`: Enable MPI parallel compilation. If set to `OFF`, a serial version of ABACUS + will be compiled. It now supports both PW and LCAO. + - `ENABLE_COVERAGE=OFF`: Build ABACUS executable supporting + [coverage analysis](../CONTRIBUTING.md#generating-code-coverage-report). This feature has a + drastic impact on performance. + - `ENABLE_ASAN=OFF`: Build with Address Sanitizer. This feature would help detecting memory + problems. + - `ENABLE_ELPA=ON`: Use ELPA library in LCAO calculations. If this value is set to OFF, ABACUS can + be compiled without ELPA library. Here is an example: @@ -200,26 +276,30 @@ cmake --build build -j`nproc` cmake --install build ``` -You can change the number after `-j` on your need: set to the number of CPU cores(`nproc`) to reduce compilation time. +You can change the number after `-j` on your need: set to the number of CPU cores(`nproc`) to reduce +compilation time. ## Run ABACUS ### Load ABACUS -If ABACUS is installed into a custom directory using `CMAKE_INSTALL_PREFIX`, please add it to your environment variable `PATH` to locate the correct executable. -*(Note: `my-install-dir` should be changed to the location of your installed abacus:`/home/your-path/abacus/bin/`.)* +If ABACUS is installed into a custom directory using `CMAKE_INSTALL_PREFIX`, please add it to your +environment variable `PATH` to locate the correct executable. *(Note: `my-install-dir` should be +changed to the location of your installed abacus:`/home/your-path/abacus/bin/`.)* ```bash export PATH=/my-install-dir/:$PATH ``` -If ABACUS is installed by toolchain, there will be an environment script in the toolchain directory named as *abacus_env.sh*. You can source it to set the environment variables. +If ABACUS is installed by toolchain, there will be an environment script in the toolchain directory +named as *abacus_env.sh*. You can source it to set the environment variables. ```bash source /path/to/abacus/toolchain/abacus_env.sh ``` -If ABACUS is installed by conda, please make sure the conda environment is activated before running ABACUS. +If ABACUS is installed by conda, please make sure the conda environment is activated before running +ABACUS. ```bash conda activate abacus_env @@ -233,7 +313,8 @@ Please set OpenMP threads by setting environment variable: export OMP_NUM_THREADS=1 ``` -Enter a directory containing a `INPUT` file. Please make sure structure, pseudo potential, or orbital files indicated by `INPUT` is at the correct location. +Enter a directory containing a `INPUT` file. Please make sure structure, pseudo potential, or +orbital files indicated by `INPUT` is at the correct location. ```bash cd abacus-develop/examples/force/pw_Si2 @@ -245,8 +326,9 @@ Use 4 MPI processes to run, for example: mpirun -n 4 abacus ``` -The total thread count (i.e. OpenMP per-process thread count * MPI process count) should not exceed the number of cores in your machine. -To use 4 threads and 4 MPI processes, set the environment variable `OMP_NUM_THREADS` before running `mpirun`: +The total thread count (i.e. OpenMP per-process thread count * MPI process count) should not exceed +the number of cores in your machine. To use 4 threads and 4 MPI processes, set the environment +variable `OMP_NUM_THREADS` before running `mpirun`: ```bash OMP_NUM_THREADS=4 mpirun -n 4 abacus @@ -255,41 +337,71 @@ OMP_NUM_THREADS=4 mpirun -n 4 abacus In this case, the total thread count is 16. ```{note} -**Open MPI applies process binding by default.** This can affect hybrid MPI+OpenMP runs because the launcher does not infer the number of OpenMP threads required by each MPI rank. A binding that is appropriate for an MPI-only calculation can therefore leave each rank with too few CPUs for its OpenMP threads. - -For hybrid runs using OpenMPI, either disable binding with `--bind-to none` (recommended for common users) or explicitly allocate the required number of cores per rank, for example with `--map-by slot:PE= --bind-to core`. For example: `OMP_NUM_THREADS=6 mpirun --bind-to none -n 1 abacus`. See https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man1/mpirun.1.html#quick-summary. +**Open MPI applies process binding by default.** This can affect hybrid MPI+OpenMP runs because the +launcher does not infer the number of OpenMP threads required by each MPI rank. A binding that is +appropriate for an MPI-only calculation can therefore leave each rank with too few CPUs for its +OpenMP threads. + +For hybrid runs using OpenMPI, either disable binding with `--bind-to none` (recommended for common +users) or explicitly allocate the required number of cores per rank, for example with +`--map-by slot:PE= --bind-to core`. For example: +`OMP_NUM_THREADS=6 mpirun --bind-to none -n 1 abacus`. +See https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man1/mpirun.1.html#quick-summary. ``` -ABACUS will try to determine the number of threads used by each process if `OMP_NUM_THREADS` is not set. However, it is **required** to set `OMP_NUM_THREADS` before running `mpirun` to avoid potential performance issues. +ABACUS will try to determine the number of threads used by each process if `OMP_NUM_THREADS` is not +set. However, it is **required** to set `OMP_NUM_THREADS` before running `mpirun` to avoid potential +performance issues. Please refer to [hands-on guide](./hands_on.md) for more instructions. ```{note} -Usually a CPU has a feature named Hyper-Threading(HT). This feature enables one physical core switch fastly between two logical threads. It would benefits from I/O bound tasks: when a thread is blocked by I/O, the CPU core can work on another thread. However, it helps little on CPU bound tasks, like ABACUS and many other scientific computing softwares. **We recommend using the physical CPU core number.** To determine if HT is turned on, execute `lscpu | grep 'per core'` and see if `Thread(s) per core` is 2. +Usually a CPU has a feature named Hyper-Threading(HT). This feature enables one physical core switch +fastly between two logical threads. It would benefits from I/O bound tasks: when a thread is blocked +by I/O, the CPU core can work on another thread. However, it helps little on CPU bound tasks, like +ABACUS and many other scientific computing softwares. **We recommend using the physical CPU core +number.** To determine if HT is turned on, execute +`lscpu | grep 'per core'` and see if `Thread(s) per core` is 2. ``` ## Container Deployment -> Please note that containers target at developing and testing, but not massively parallel computing for production. Docker has a bad support to MPI, which may cause performance degradation. +> Please note that containers target at developing and testing, but not massively parallel computing +> for production. Docker has a bad support to MPI, which may cause performance degradation. -We've built a ready-for-use version of ABACUS with docker [here](https://github.com/deepmodeling/abacus-develop/pkgs/container/abacus). For a quick start: pull the image, prepare the data, run container. Instructions on using the image can be accessed in [Dockerfile](https://github.com/deepmodeling/abacus-develop/blob/develop/Dockerfile). A mirror is available by `docker pull registry.dp.tech/deepmodeling/abacus`. +We've built a ready-for-use version of ABACUS with docker +[here](https://github.com/deepmodeling/abacus-develop/pkgs/container/abacus). For a quick start: +pull the image, prepare the data, run container. Instructions on using the image can be accessed in +[Dockerfile](https://github.com/deepmodeling/abacus-develop/blob/develop/Dockerfile). A mirror is +available by `docker pull registry.dp.tech/deepmodeling/abacus`. -We also offer a pre-built docker image containing all the requirements for development. Please refer to our [Package Page](https://github.com/orgs/deepmodeling/packages?repo_name=abacus-develop). +We also offer a pre-built docker image containing all the requirements for development. Please refer +to our [Package Page](https://github.com/orgs/deepmodeling/packages?repo_name=abacus-develop). -The project is ready for VS Code development container. Please refer to [Developing inside a Container](https://code.visualstudio.com/docs/remote/containers#_quick-start-try-a-development-container). Choose `Open a Remote Window -> Clone a Repository in Container Volume` in VS Code command palette, and put the [git address](https://github.com/deepmodeling/abacus-develop.git) of `ABACUS` when prompted. +The project is ready for VS Code development container. Please refer to +[Developing inside a Container](https://code.visualstudio.com/docs/remote/containers#_quick-start-try-a-development-container). +Choose `Open a Remote Window -> Clone a Repository in Container Volume` in VS Code command palette, +and put the [git address](https://github.com/deepmodeling/abacus-develop.git) of `ABACUS` when +prompted. -For online development environment, we support [GitHub Codespaces](https://github.com/codespaces): [Create a new Codespace](https://github.com/codespaces/new?machine=basicLinux32gb&repo=334825694&ref=develop&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=SouthEastAsia) +For online development environment, we support [GitHub Codespaces](https://github.com/codespaces): +[Create a new Codespace](https://github.com/codespaces/new?machine=basicLinux32gb&repo=334825694&ref=develop&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=SouthEastAsia) -We also support [Gitpod](https://www.gitpod.io/): [Open in Gitpod](https://gitpod.io/#https://github.com/deepmodeling/abacus-develop) +We also support [Gitpod](https://www.gitpod.io/): +[Open in Gitpod](https://gitpod.io/#https://github.com/deepmodeling/abacus-develop) ## Command line options -Users can check the version of ABACUS by running the command `abacus --version`, the result will be like: +Users can check the version of ABACUS by running the command `abacus --version`, the result will be +like: + ``` ABACUS version v3.9.0.2 ``` -Users may check the correctness of the setting of parameters in the `INPUT` file by running the command `abacus --check-input`, the result will be like: +Users may check the correctness of the setting of parameters in the `INPUT` file by running the +command `abacus --check-input`, the result will be like: + ``` ABACUS v3.9.0.2 diff --git a/docs/quick_start/hands_on.md b/docs/quick_start/hands_on.md index ab280b233c7..0b18684cccd 100644 --- a/docs/quick_start/hands_on.md +++ b/docs/quick_start/hands_on.md @@ -4,7 +4,11 @@ ### A quick LCAO example -ABACUS is well known for its support of LCAO (Linear Combination of Atomic Orbital) basis set in calculating periodic condensed matter systems. It's a good choice to start from a LCAO example of self-consistent field (SCF) calculation. Here, FCC MgO has been chosen as a quick start example. The default name of a structure file in ABACUS is `STRU`. The `STRU` file for FCC MgO in a LCAO calculation is shown below: +ABACUS is well known for its support of LCAO (Linear Combination of Atomic Orbital) basis set in +calculating periodic condensed matter systems. It's a good choice to start from a LCAO example of +self-consistent field (SCF) calculation. Here, FCC MgO has been chosen as a quick start example. The +default name of a structure file in ABACUS is `STRU`. The `STRU` file for FCC MgO in a LCAO +calculation is shown below: ``` #This is the atom file containing all the information @@ -44,7 +48,9 @@ O #Name of element 0.0 0.5 0.0 0 0 0 #x,y,z, move_x, move_y, move_z ``` -Next, the `INPUT` file is required, which sets all key parameters to direct ABACUS how to calculte and what to output: +Next, the `INPUT` file is required, which sets all key parameters to direct ABACUS how to calculte +and what to output: + ``` INPUT_PARAMETERS suffix MgO @@ -56,9 +62,15 @@ basis_type lcao calculation scf # this is the key parameter telling abacus to do a scf calculation ``` -The pseudopotential files of `Mg_ONCV_PBE-1.0.upf` and `O_ONCV_PBE-1.0.upf` should be provided under the directory of `pseudo_dir` defined in `INPUT` (the default directory is "./"), and the orbital files `Mg_gga_8au_100Ry_4s2p1d.orb` and `O_gga_8au_100Ry_2s2p1d.orb` under the directory of `orbital_dir` also defined in `INPUT` (the default directory is "./"). The pseudopotential and orbital files can be downloaded from the [ABACUS website](http://abacus.ustc.edu.cn/pseudo/list.htm). +The pseudopotential files of `Mg_ONCV_PBE-1.0.upf` and `O_ONCV_PBE-1.0.upf` should be provided under +the directory of `pseudo_dir` defined in `INPUT` (the default directory is "./"), and the orbital +files `Mg_gga_8au_100Ry_4s2p1d.orb` and `O_gga_8au_100Ry_2s2p1d.orb` under the directory of +`orbital_dir` also defined in `INPUT` (the default directory is "./"). The pseudopotential and +orbital files can be downloaded from the +[ABACUS website](http://abacus.ustc.edu.cn/pseudo/list.htm). -The final mandatory input file is called `KPT`, which sets the reciprocal space k-mesh. Below is an example: +The final mandatory input file is called `KPT`, which sets the reciprocal space k-mesh. Below is an +example: ``` K_POINTS @@ -67,7 +79,8 @@ Gamma 4 4 4 0 0 0 ``` -After all the above input files have been set, one should be able to run the first quick example. The simplest way is to use the command line, e.g.: +After all the above input files have been set, one should be able to run the first quick example. +The simplest way is to use the command line, e.g.: ``` OMP_NUM_THREADS=1 mpirun -np 2 abacus @@ -131,9 +144,12 @@ If ABAUCS finishes successfully, the total energy will be output in `OUT.MgO/run ### A quick PW example -In order to run a SCF calculation with PW (Plane Wave) basis set, one has only to change the tag `basis_type` from `lcao` to `pw` in the `INPUT` file, and no longer needs to provide orbital files under `NUMERICAL_ORBITAL` in the `STRU` file. +In order to run a SCF calculation with PW (Plane Wave) basis set, one has only to change the tag +`basis_type` from `lcao` to `pw` in the `INPUT` file, and no longer needs to provide orbital files +under `NUMERICAL_ORBITAL` in the `STRU` file. The `INPUT` file follows as: + ``` INPUT_PARAMETERS suffix MgO @@ -180,7 +196,8 @@ O #Name of element 0.0 0.5 0.0 0 0 0 #x,y,z, move_x, move_y, move_z ``` -Use the same pseudopotential and `KPT` files as the above LCAO example. The final total energy will be output: +Use the same pseudopotential and `KPT` files as the above LCAO example. The final total energy will +be output: ``` -------------------------------------------- @@ -190,7 +207,10 @@ Use the same pseudopotential and `KPT` files as the above LCAO example. The fina ## Running Geometry Optimization -In order to run a full geometry optimization in ABACUS, the tag `calculation` in `INPUT` should be set to `cell-relax`. In addition, the convergence criteria for atomics force and cell stress can be set through the tags `force_thr_ev` and `stress_thr`, respectively. The maximum number of ionc steps is controlled by `relax_nmax`. +In order to run a full geometry optimization in ABACUS, the tag `calculation` in `INPUT` should be +set to `cell-relax`. In addition, the convergence criteria for atomics force and cell stress can be +set through the tags `force_thr_ev` and `stress_thr`, respectively. The maximum number of ionc steps +is controlled by `relax_nmax`. ### A quick LCAO example @@ -211,7 +231,9 @@ stress_thr 5 # the threshold of the stress convergence, in unit of kBar relax_nmax 100 # the maximal number of ionic iteration steps out_stru 1 ``` -Use the same `KPT`, `STRU`, pseudopotential, and orbital files as in the above SCF-LCAO example. The final optimized structure can be found in `STRU_FINAL` and `OUT.MgO/running_cell-relax.log`. + +Use the same `KPT`, `STRU`, pseudopotential, and orbital files as in the above SCF-LCAO example. The +final optimized structure can be found in `STRU_FINAL` and `OUT.MgO/running_cell-relax.log`. ### A quick PW example @@ -232,4 +254,5 @@ relax_nmax 100 # the maximal number of ionic iteration steps out_stru 1 ``` -Use the same `KPT`, `STRU`, and pseudopotential files as in the above SCF-PW examples. The final optimized structure can be found in `STRU_FINAL` and `STRU` with different format. +Use the same `KPT`, `STRU`, and pseudopotential files as in the above SCF-PW examples. The final +optimized structure can be found in `STRU_FINAL` and `STRU` with different format. diff --git a/docs/quick_start/input.md b/docs/quick_start/input.md index 1f0ac33c640..52cffd86bc5 100644 --- a/docs/quick_start/input.md +++ b/docs/quick_start/input.md @@ -1,10 +1,13 @@ # Brief Introduction of the Input Files -The following files are the central input files for ABACUS. Before executing the program, please make sure these files are prepared and stored in the working directory. Here we give some simple descriptions. For more details, users should consult the Advanced session. +The following files are the central input files for ABACUS. Before executing the program, please +make sure these files are prepared and stored in the working directory. Here we give some simple +descriptions. For more details, users should consult the Advanced session. ## *INPUT* -The `INPUT` file contains parameters that control the type of calculation as well as a variety of settings. +The `INPUT` file contains parameters that control the type of calculation as well as a variety of +settings. Below is an example `INPUT` file with some of the most important parameters that need to be set: @@ -20,33 +23,50 @@ calculation scf # this is the key parameter telling abacus to do a out_chg 0 # only output binary charge file for restart ``` -The parameter list always starts with key word `INPUT_PARAMETERS`. Any content before `INPUT_PARAMETERS` will be ignored. +The parameter list always starts with key word `INPUT_PARAMETERS`. Any content before +`INPUT_PARAMETERS` will be ignored. Any line starting with `#` or `/` will also be ignored. -Each parameter value is provided by specifying the name of the input variable -and then putting the value after the name, separated by one or more blank characters(space or tab). The following characters (> 150) in the same line will be neglected. +Each parameter value is provided by specifying the name of the input variable and then putting the +value after the name, separated by one or more blank characters(space or tab). The following +characters (> 150) in the same line will be neglected. -Depending on the input variable, the value may be an integer, a real number or a string. The parameters can be given in any order, but only one parameter should be given per line. +Depending on the input variable, the value may be an integer, a real number or a string. The +parameters can be given in any order, but only one parameter should be given per line. -Furthermore, if a given parameter name appeared more than once in the input file, only the last value will be taken. +Furthermore, if a given parameter name appeared more than once in the input file, only the last +value will be taken. -> **Note:** if a parameter name is not recognized by the program, the program will stop with an error message. +> **Note:** if a parameter name is not recognized by the program, the program will stop with an +> error message. In the above example, the meanings of the parameters are: -- `suffix` : the name of the system, default `ABACUS`, and output files will be in OUT.{suffix} directory. +- `suffix` : the name of the system, default `ABACUS`, and output files will be in OUT.{suffix} + directory. - `pseudo_dir` : the directory where pseudopotential files are provided. - `orbital_dir` : the directory where orbital files are provided. - `ecutwfc` : the plane-wave energy cutoff for the wave function expansion (UNIT: Rydberg). -- `scf_thr` : the threshold for the convergence of charge density (UNIT: Rydberg for PW, dimensionless for LCAO), we recommend `1e-7` for LCAO and `1e-9` for PW basis. -- `basis_type` : the type of basis set for expanding the electronic wave functions, one can set lcao or pw. +- `scf_thr` : the threshold for the convergence of charge density (UNIT: Rydberg for PW, + dimensionless for LCAO), we recommend `1e-7` for LCAO and `1e-9` for PW basis. +- `basis_type` : the type of basis set for expanding the electronic wave functions, one can set lcao + or pw. - `calculation` : the type of calculation to be performed by ABACUS -- `out_chg` : setting for output the charge density in real space grid, -1 for no output, 0 for binary output, 1 for binary and cube output. +- `out_chg` : setting for output the charge density in real space grid, -1 for no output, 0 for + binary output, 1 for binary and cube output. -For a complete list of input parameters, please consult this [instruction](../advanced/input_files/input-main.md). +For a complete list of input parameters, please consult this +[instruction](../advanced/input_files/input-main.md). -> **Note:** Users cannot change the filename "INPUT" to other names. Boolean paramerters such as `out_chg` can be set by using `True` and `False`, `1` and `0`, or `T` and `F`. It is case insensitive so that other preferences such as `true` and `false`, `TRUE` and `FALSE`, and `t` and `f` for setting boolean values are also supported. Specifically for the `out_chg`, `-1` option is also available, which means turn off the checkpoint of charge density in binary (always dumped in `OUT.{suffix}`, whose name ends with `CHARGE-DENSITY.restart`). Some parameters controlling the output also support a second option to control the output precision, e.g., `out_chg 1 8` will output the charge density on realspace grid with 8 digits after the decimal point. +> **Note:** Users cannot change the filename "INPUT" to other names. Boolean paramerters such as +> `out_chg` can be set by using `True` and `False`, `1` and `0`, or `T` and `F`. It is case +> insensitive so that other preferences such as `true` and `false`, `TRUE` and `FALSE`, and `t` and +> `f` for setting boolean values are also supported. Specifically for the `out_chg`, `-1` option is +> also available, which means turn off the checkpoint of charge density in binary (always dumped in +> `OUT.{suffix}`, whose name ends with `CHARGE-DENSITY.restart`). Some parameters controlling the +> output also support a second option to control the output precision, e.g., `out_chg 1 8` will +> output the charge density on realspace grid with 8 digits after the decimal point. ## Getting Help with Parameters @@ -99,7 +119,9 @@ Parameter lookups are case-insensitive, so `ECUTWFC`, `Ecutwfc`, and `ecutwfc` a ## *STRU* -The structure file contains structural information about the system, e.g., lattice constant, lattice vectors, and positions of the atoms within a unit cell. The positions can be given either in direct or Cartesian coordinates. +The structure file contains structural information about the system, e.g., lattice constant, lattice +vectors, and positions of the atoms within a unit cell. The positions can be given either in direct +or Cartesian coordinates. An example of the `STRU` file is given as follows : @@ -142,9 +164,14 @@ O #Name of element 0.0 0.5 0.0 0 0 0 #x,y,z, move_x, move_y, move_z ``` -> **Note:** users may choose a different name for their structure file using the keyword `stru_file`. The order of the pseudopotential file list and the numerical orbital list (if LCAO is applied) MUST be consistent with that of the atomic type given in `ATOMIC_POSITIONS`. +> **Note:** users may choose a different name for their structure file using the keyword +> `stru_file`. The order of the pseudopotential file list and the numerical orbital list (if LCAO is +> applied) MUST be consistent with that of the atomic type given in `ATOMIC_POSITIONS`. -> **Important:** When specifying atomic positions, you can use various coordinate systems (Direct, Cartesian, Cartesian_angstrom, etc.) and add optional properties like magnetization, velocity, and movement constraints. See the [detailed STRU documentation](../advanced/input_files/stru.md) for all available options and best practices. +> **Important:** When specifying atomic positions, you can use various coordinate systems (Direct, +> Cartesian, Cartesian_angstrom, etc.) and add optional properties like magnetization, velocity, and +> movement constraints. See the [detailed STRU documentation](../advanced/input_files/stru.md) for +> all available options and best practices. ## *KPT* @@ -165,12 +192,18 @@ For a more detailed description, please consult [here](../advanced/input_files/k - The pseudopotential files - Norm-conserving pseudopotentials are used in ABACUS, in the UPF file format.The filename of each elementโ€™s pseudopotential needs to be specified in the STRU file, together with the directory of the pseudopotential files unless they are already present in the working directory. + Norm-conserving pseudopotentials are used in ABACUS, in the UPF file format.The filename of each + elementโ€™s pseudopotential needs to be specified in the STRU file, together with the directory of + the pseudopotential files unless they are already present in the working directory. - More information on pseudopotentials is given [here](../advanced/pp_orb.md#pseudopotentials). + More information on pseudopotentials is given [here](../advanced/pp_orb.md#pseudopotentials). - The numerical orbital files - This part is only required in LCAO calculations. - The filename for each elementโ€™s numerical orbital basis needs to be specified in the STRU file, together with the directory of the orbital files unless they are already present in the working directory. - ABACUS provides numerical atomic basis sets of different accuracy levels for most elements commonly used. Users can download these basis sets from the [website](http://abacus.ustc.edu.cn/pseudo/list.htm). Moreover, users can generate numerical atomic orbitals by themselves, and the procedure is provided in this [short introduction](../advanced/pp_orb.md#generating-atomic-orbital-bases). + This part is only required in LCAO calculations. The filename for each elementโ€™s numerical orbital + basis needs to be specified in the STRU file, together with the directory of the orbital files + unless they are already present in the working directory. ABACUS provides numerical atomic basis + sets of different accuracy levels for most elements commonly used. Users can download these basis + sets from the [website](http://abacus.ustc.edu.cn/pseudo/list.htm). Moreover, users can generate + numerical atomic orbitals by themselves, and the procedure is provided in this + [short introduction](../advanced/pp_orb.md#generating-atomic-orbital-bases). diff --git a/docs/quick_start/output.md b/docs/quick_start/output.md index 74d2e552ac6..c30d3dfc873 100644 --- a/docs/quick_start/output.md +++ b/docs/quick_start/output.md @@ -1,37 +1,46 @@ # Brief Introduction of the Output Files -The following files are the central output files for ABACUS. After executing the program, you can obtain a log file containing the screen output, more detailed outputs are stored in the working directory `OUT.suffix` (Default one is `OUT.ABACUS`). Here we give some simple descriptions. +The following files are the central output files for ABACUS. After executing the program, you can +obtain a log file containing the screen output, more detailed outputs are stored in the working +directory `OUT.suffix` (Default one is `OUT.ABACUS`). Here we give some simple descriptions. ## *INPUT* Different from `INPUT` given by the users, `OUT.suffix/INPUT` contains all parameters in ABACUS. -> **Note:** `OUT.suffix/INPUT` contains the **actual parameters used in the calculation**, including: -> 1. **User-specified parameters** (explicitly defined in your input file or command-line arguments, overriding default parameters). -> 2. **System default parameters** (automatically applied when not explicitly provided by the user). +> **Note:** `OUT.suffix/INPUT` contains the **actual parameters used in the calculation**, +> including: +> +> 1. **User-specified parameters** (explicitly defined in your input file or command-line arguments, +> overriding default parameters). +> 1. **System default parameters** (automatically applied when not explicitly provided by the user). +This file ensures calculations can be fully reproduced, even if default values change in future +ABACUS versions. Also notice that in rare cases, a small number of parameters may be dynamically +reset to appropriate values during runtime. -This file ensures calculations can be fully reproduced, even if default values change in future ABACUS versions. -Also notice that in rare cases, a small number of parameters may be dynamically reset to appropriate values during runtime. - -For a complete list of input parameters, please consult this [instruction](../advanced/input_files/input-main.md). +For a complete list of input parameters, please consult this +[instruction](../advanced/input_files/input-main.md). ## *running_scf.log* -`running_scf.log` contains information on nearly all function calls made during the execution of ABACUS. +`running_scf.log` contains information on nearly all function calls made during the execution of +ABACUS. ## *KPT.info* -This file contains the information of all generated k-points, as well as the list of k-points actually used for calculations after considering symmetry. +This file contains the information of all generated k-points, as well as the list of k-points +actually used for calculations after considering symmetry. ## *eig.txt* -This file includes the energy levels and occupations computed for all k-points. -Note: In 3.10-LTS version, the file is named 'istate.info' +This file includes the energy levels and occupations computed for all k-points. Note: In 3.10-LTS +version, the file is named 'istate.info' ## *STRU.cif* -ABACUS generates a `.cif` format structure file based on the input file `STRU`, facilitating users to visualize with commonly used software. +ABACUS generates a `.cif` format structure file based on the input file `STRU`, facilitating users +to visualize with commonly used software. ## *warning.log* diff --git a/examples/03_spin_polarized/04_Co6Nb4Os2/README.md b/examples/03_spin_polarized/04_Co6Nb4Os2/README.md index cbf1f9eecc0..4761b289740 100644 --- a/examples/03_spin_polarized/04_Co6Nb4Os2/README.md +++ b/examples/03_spin_polarized/04_Co6Nb4Os2/README.md @@ -4,10 +4,11 @@ This example demonstrates a spin-polarized DFT calculation for the Co6Nb4Os2 com ## Special Note: Sensitivity to Smearing Parameter -This calculation is **extremely sensitive to the smearing parameter** (`smearing_sigma`). The total magnetic moment shows significant variation depending on the smearing value: +This calculation is **extremely sensitive to the smearing parameter** (`smearing_sigma`). The total +magnetic moment shows significant variation depending on the smearing value: | smearing_sigma (Ry) | Total Magnetism (ฮผB) | -|---------------------|----------------------| +| ------------------- | -------------------- | | 0.002 | ~2.20 | | 0.005 | ~1.94 | | 0.010 | ~0.60 | @@ -15,15 +16,21 @@ This calculation is **extremely sensitive to the smearing parameter** (`smearing ### Explanation -The Co6Nb4Os2 system exhibits a delicate balance between magnetic and non-magnetic states. The smearing parameter controls the width of the Gaussian smearing used for occupation numbers, which significantly affects the electronic structure near the Fermi level. For this compound: +The Co6Nb4Os2 system exhibits a delicate balance between magnetic and non-magnetic states. The +smearing parameter controls the width of the Gaussian smearing used for occupation numbers, which +significantly affects the electronic structure near the Fermi level. For this compound: -- **Small smearing values** (e.g., 0.002 Ry) preserve the magnetic ordering, resulting in a total magnetic moment of ~2.20 ฮผB +- **Small smearing values** (e.g., 0.002 Ry) preserve the magnetic ordering, resulting in a total + magnetic moment of ~2.20 ฮผB - **Increasing smearing** progressively suppresses the magnetic moment -- **Large smearing values** (e.g., 0.02 Ry) completely quench the magnetism, leading to a non-magnetic ground state +- **Large smearing values** (e.g., 0.02 Ry) completely quench the magnetism, leading to a + non-magnetic ground state ### Recommended Settings -The default `smearing_sigma` in `INPUT` is set to **0.001 Ry**, which should yield a magnetic moment close to 2.20 ฮผB. Users are advised to carefully test different smearing values when studying this system. +The default `smearing_sigma` in `INPUT` is set to **0.001 Ry**, which should yield a magnetic moment +close to 2.20 ฮผB. Users are advised to carefully test different smearing values when studying this +system. ## System Details @@ -35,23 +42,29 @@ The default `smearing_sigma` in `INPUT` is set to **0.001 Ry**, which should yie ## Files - `INPUT`: Main input file with calculation parameters -- `STRU`: Structure file with atomic positions, initial magnetic moments, and numerical atomic orbital definitions +- `STRU`: Structure file with atomic positions, initial magnetic moments, and numerical atomic + orbital definitions - `KPT`: k-point mesh definition ### Numerical Atomic Orbitals (NAO) The `STRU` file references three numerical atomic orbital files: + - `Co_gga_9au_60Ry_4s2p2d1f.orb` - `Nb_gga_9au_60Ry_4s2p2d1f.orb` - `Os_gga_9au_60Ry_4s2p2d1f.orb` The filename format encodes the following information: + - `9au`: Orbital cutoff radius (9 atomic units) - `60Ry`: Energy cutoff (60 Rydberg) -- `4s2p2d1f`: Number of orbitals per angular momentum channel (4 s-orbitals, 2 p-orbitals, 2 d-orbitals, 1 f-orbital) +- `4s2p2d1f`: Number of orbitals per angular momentum channel (4 s-orbitals, 2 p-orbitals, 2 + d-orbitals, 1 f-orbital) -The `ecutwfc` parameter in `INPUT` is set to **60** to match the energy cutoff of the orbital files, ensuring consistency in the calculation. +The `ecutwfc` parameter in `INPUT` is set to **60** to match the energy cutoff of the orbital files, +ensuring consistency in the calculation. ## Running the Calculation -Execute ABACUS in this directory to perform the spin-polarized SCF calculation. Monitor the output for the total magnetic moment in the final SCF iteration. +Execute ABACUS in this directory to perform the spin-polarized SCF calculation. Monitor the output +for the total magnetic moment in the final SCF iteration. diff --git a/examples/15_fixed_occ/README.md b/examples/15_fixed_occ/README.md index 3c7681ae2c7..e006e5c78db 100644 --- a/examples/15_fixed_occ/README.md +++ b/examples/15_fixed_occ/README.md @@ -1,22 +1,30 @@ -For a spin-polarized calculation (where `nspin=2` in the INPUT), let's say you want to excite a spin-up (spin component 1) or spin-down (spin component 2) electron from the ground state to the excited state. +For a spin-polarized calculation (where `nspin=2` in the INPUT), let's say you want to excite a +spin-up (spin component 1) or spin-down (spin component 2) electron from the ground state to the +excited state. To do this, you will need to do the following: -- Find out how many bands do you have. You can obtain that by search for `NBANDS` in the running_*.log file -- Find out how many k points do you have. Let's call that number `N_K`. -- Find out how many electrons are occupying spin components 1 and 2. Let's say there are `O_UP` electrons that occupy the spin up, `O_DN` electrons that occupy the spin down. -- Next, calculate how many states are empty in both spins: empty states in the spin up = `U_UP` where `U_UP = NBANDS - O_UP`. Same applies for `U_DN`. +- Find out how many bands do you have. You can obtain that by search for `NBANDS` in the + running\_\*.log file +- Find out how many k points do you have. Let's call that number `N_K`. +- Find out how many electrons are occupying spin components 1 and 2. Let's say there are `O_UP` + electrons that occupy the spin up, `O_DN` electrons that occupy the spin down. +- Next, calculate how many states are empty in both spins: empty states in the spin up = `U_UP` + where `U_UP = NBANDS - O_UP`. Same applies for `U_DN`. Finally, add the `ocp_set` as follows: - `ocp_set [O_UP-1]*1.0 1*0.0 1*1.0 [U_UP-1]*0.0 [O_DN]*1.0 [U_DN]*0.0 ` -Note the `` above. It means: repeat `[O_UP-1]*1.0 1*0.0 1*1.0 [U_UP-1]*0.0` for `N_K` times. +Note the `` above. It means: repeat `[O_UP-1]*1.0 1*0.0 1*1.0 [U_UP-1]*0.0` for +`N_K` times. -Let's have an example. Let's say we have 8 kpoints in both spins, 216 bands, where the spin up electrons occupy 144 bands and the spin down occupy 142 bands. Then, here are the two tags: +Let's have an example. Let's say we have 8 kpoints in both spins, 216 bands, where the spin up +electrons occupy 144 bands and the spin down occupy 142 bands. Then, here are the two tags: - `ocp_set 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 143*1.0 1*0.0 1*1.0 71*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0 142*1.0 74*0.0` I hope that helps! -More information can be found at: https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#ocp-set +More information can be found at: +https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#ocp-set diff --git a/interfaces/ASE_interface/DEVELOP.md b/interfaces/ASE_interface/DEVELOP.md index acb1f1384b4..d9154f240f2 100644 --- a/interfaces/ASE_interface/DEVELOP.md +++ b/interfaces/ASE_interface/DEVELOP.md @@ -1,6 +1,7 @@ # Developer Guide Abacuslite has the following file structure: + ``` . โ”œโ”€โ”€ __init__.py @@ -23,45 +24,46 @@ This file contains the implementation of the Atomic Simulation Environment (ASE) ## io -This directory contains the input/output (I/O) functions for extracting information from ABACUS dumped files. A summary is here: +This directory contains the input/output (I/O) functions for extracting information from ABACUS +dumped files. A summary is here: ### Long-term-support (LTS) version -|Item|Regular expression|Example| -|----|----|----| -|esolver_type|'The esolver type has been set to : (\S+)'|`The esolver type has been set to : ksdft_pw`| -|nspin|'nspin\s+=\s+(\d+)'|`nspin = 4`| -|number of bands|'NBANDS\s+=\s+(\d+)'|`NBANDS = 40`| -|number of atoms|'TOTAL ATOM NUMBER\s*=\s*(\d+)'|`TOTAL ATOM NUMBER = 2`| -|lattice constant|'lattice constant \(Angstrom\)\s*=\s*(-?\d+(\.\d+)?)'|`lattice constant (Angstrom) = 0.529177`| -|lattice vectors|'^Lattice vectors: \(Cartesian coordinate: in unit of a_0\)$'|` Lattice vectors: (Cartesian coordinate: in unit of a_0)`| -|coordinate system|'^(DIRECT\|CARTESIAN) COORDINATES'|`DIRECT COORDINATES`| -|atomic positions|'^tau[c\|d]_([A-Z][a-z]?)\d+\s+(-?\d+(\.\d+)?)\s+(-?\d+(\.\d+)?)\s+(-?\d+(\.\d+)?)*'|`taud_As1 0.2500000000 0.2500000000 0.2500000000 1.7321 0.0000000000 0.0000000000 0.0000000000`| -|eigenvalues|'\d+/\d+\s+kpoint\s+\(Cartesian\)\s+=\s+(-?\d(\.\d+)?(e-\d+)?)\s+(-?\d(\.\d+)?(e-\d+)?)\s+(-?\d(\.\d+)?(e-\d\|+)?)\s+\(\d+\s+pws\)'|` 1/1 kpoint (Cartesian) = 0.0000 0.0000 0.0000 (230 pws)`| -|atomic forces|'\s\*TOTAL\-FORCE\s\*\(eV\s*/Angstrom\)'|` TOTAL-FORCE (eV/Angstrom) `| -|total stress|'\s\*TOTAL\-STRESS\s\*\(KBAR\)'|` TOTAL-STRESS (KBAR) `| -|kpoints and weights|'\s\*(IBZ\|KPOINTS)\s+(DIRECT\|CARTESIAN)_X\s+(DIRECT\|CARTESIAN)_Y\s+(DIRECT\|CARTESIAN)_Z\s+WEIGHT(\s+ibz2bz)?'|` KPOINTS DIRECT_X DIRECT_Y DIRECT_Z WEIGHT`| -|energy|'\s*ENERGY\s+Rydberg\s+eV'|` Energy Rydberg eV `| -|total magnetism|'\s\*Total\sMagnetism\s\(uB\)(\s+x\s+y\s+z)?\s\*'|` Total Magnetism (uB) `| +| Item | Regular expression | Example | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | +| esolver_type | 'The esolver type has been set to : (\\S+)' | `The esolver type has been set to : ksdft_pw` | +| nspin | 'nspin\\s+=\\s+(\\d+)' | `nspin = 4` | +| number of bands | 'NBANDS\\s+=\\s+(\\d+)' | `NBANDS = 40` | +| number of atoms | 'TOTAL ATOM NUMBER\\s\*=\\s\*(\\d+)' | `TOTAL ATOM NUMBER = 2` | +| lattice constant | 'lattice constant (Angstrom)\\s\*=\\s\*(-?\\d+(.\\d+)?)' | `lattice constant (Angstrom) = 0.529177` | +| lattice vectors | '^Lattice vectors: (Cartesian coordinate: in unit of a_0)$' | ` Lattice vectors: (Cartesian coordinate: in unit of a_0)` | +| coordinate system | '^(DIRECT | CARTESIAN) COORDINATES' | +| atomic positions | '^tau\[c | d\]\_([A-Z][a-z]?)\\d+\\s+(-?\\d+(.\\d+)?)\\s+(-?\\d+(.\\d+)?)\\s+(-?\\d+(.\\d+)?)\*' | +| eigenvalues | '\\d+/\\d+\\s+kpoint\\s+(Cartesian)\\s+=\\s+(-?\\d(.\\d+)?(e-\\d+)?)\\s+(-?\\d(.\\d+)?(e-\\d+)?)\\s+(-?\\d(.\\d+)?(e-\\d | +)?)\\s+(\\d+\\s+pws)' | +| atomic forces | '\\s\*TOTAL-FORCE\\s\*(eV\\s\*/Angstrom)' | `TOTAL-FORCE (eV/Angstrom) ` | +| total stress | '\\s\*TOTAL-STRESS\\s\*(KBAR)' | `TOTAL-STRESS (KBAR) ` | +| kpoints and weights | '\\s\*(IBZ | KPOINTS)\\s+(DIRECT | +| energy | '\\s\*ENERGY\\s+Rydberg\\s+eV' | ` Energy Rydberg eV ` | +| total magnetism | '\\s\*Total\\sMagnetism\\s(uB)(\\s+x\\s+y\\s+z)?\\s\*' | `Total Magnetism (uB) ` | ### Latest version -|Item|Regular expression|Example|Notes| -|----|----|----|----| -|esolver_type|'#ENERGY SOLVER#\s+(\S+)'|` #ENERGY SOLVER# ksdft_pw`|| -|nspin|'nspin\s+=\s+(\d+)'|`nspin = 4`|| -|number of bands|||has been removed| -|number of atoms|'TOTAL ATOM NUMBER\s*=\s*(\d+)'|`TOTAL ATOM NUMBER = 2`|| -|lattice constant|'lattice constant \(Angstrom\)\s*=\s*(-?\d+(\.\d+)?)'|`lattice constant (Angstrom) = 0.529177`|| -|lattice vectors|'^Lattice vectors: \(Cartesian coordinate: in unit of a_0\)$'|` Lattice vectors: (Cartesian coordinate: in unit of a_0)`|| -|coordinate system|'^(DIRECT\|CARTESIAN) COORDINATES'|`DIRECT COORDINATES`|| -|atomic positions|'atom\s+x\s+y\s+z\s+magโ€˜|` atom x y z mag`|"tauc/taud" suffix has been removed, therefore the way to read the coordinates changes to find the head of the table, then read the following `number of atoms` lines. On the other hand, if the `calculation` is set to `md`, ABACUS will not dump the atomic positions to running log anymore, instead, will read from the MD_dump file| -|eigenvalues|'spin=(\d)\s+k-point=(\d+)/(\d+)\s+Cartesian=\s*(-?\d(\.\d+)?(e-\d+)?)\s+(-?\d(\.\d+)?(e-\d+)?)\s+(-?\d(\.\d\|+)?(e-\d+)?)\s+\(\d+\s+plane wave\)'| spin=1 k-point=1/1 Cartesian=0.0000000 0.0000000 0.0000000 (1837 plane wave)|eigenvalues information has been removed from the running log, the file istate.info is renamed as eig_occ.txt, where the eigenvalues are read| -|atomic forces|'#\s\*TOTAL\-FORCE\s*\(eV\s*/Angstrom\)\s\*#'|` #TOTAL-FORCE (eV/Angstrom)#`|| -|total stress|'#\s\*TOTAL\-STRESS\s*\(kbar\)\s\*#'|` #TOTAL-STRESS (kbar)# `|| -|kpoints and weights|'\s*(IBZ\|KPOINTS)\s+(DIRECT\|CARTESIAN)_X\s+(DIRECT\|CARTESIAN)_Y\s+(DIRECT\|CARTESIAN)_Z\s+WEIGHT(\s+ibz2bz)?'|` KPOINTS DIRECT_X DIRECT_Y DIRECT_Z WEIGHT`|| -|energy|'\s*ENERGY\s+Rydberg\s+eV'|` Energy Rydberg eV `|| -|total magnetism|'\s\*Total\sMagnetism\s\(uB\)(\s+x\s+y\s+z)?\s\*'|` Total Magnetism (uB) `|| +| Item | Regular expression | Example | Notes | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| esolver_type | '#ENERGY SOLVER#\\s+(\\S+)' | ` #ENERGY SOLVER# ksdft_pw` | | +| nspin | 'nspin\\s+=\\s+(\\d+)' | `nspin = 4` | | +| number of bands | | | has been removed | +| number of atoms | 'TOTAL ATOM NUMBER\\s\*=\\s\*(\\d+)' | `TOTAL ATOM NUMBER = 2` | | +| lattice constant | 'lattice constant (Angstrom)\\s\*=\\s\*(-?\\d+(.\\d+)?)' | `lattice constant (Angstrom) = 0.529177` | | +| lattice vectors | '^Lattice vectors: (Cartesian coordinate: in unit of a_0)$' | ` Lattice vectors: (Cartesian coordinate: in unit of a_0)` | | +| coordinate system | '^(DIRECT | CARTESIAN) COORDINATES' | `DIRECT COORDINATES` | +| atomic positions | 'atom\\s+x\\s+y\\s+z\\s+magโ€˜ | ` atom x y z mag` | "tauc/taud" suffix has been removed, therefore the way to read the coordinates changes to find the head of the table, then read the following `number of atoms` lines. On the other hand, if the `calculation` is set to `md`, ABACUS will not dump the atomic positions to running log anymore, instead, will read from the MD_dump file | +| eigenvalues | 'spin=(\\d)\\s+k-point=(\\d+)/(\\d+)\\s+Cartesian=\\s\*(-?\\d(.\\d+)?(e-\\d+)?)\\s+(-?\\d(.\\d+)?(e-\\d+)?)\\s+(-?\\d(.\\d | +)?(e-\\d+)?)\\s+(\\d+\\s+plane wave)' | spin=1 k-point=1/1 Cartesian=0.0000000 0.0000000 0.0000000 (1837 plane wave) | +| atomic forces | '#\\s\*TOTAL-FORCE\\s\*(eV\\s\*/Angstrom)\\s\*#' | ` #TOTAL-FORCE (eV/Angstrom)#` | | +| total stress | '#\\s\*TOTAL-STRESS\\s\*(kbar)\\s\*#' | `#TOTAL-STRESS (kbar)# ` | | +| kpoints and weights | '\\s\*(IBZ | KPOINTS)\\s+(DIRECT | CARTESIAN)\_X\\s+(DIRECT | +| energy | '\\s\*ENERGY\\s+Rydberg\\s+eV' | ` Energy Rydberg eV ` | | +| total magnetism | '\\s\*Total\\sMagnetism\\s(uB)(\\s+x\\s+y\\s+z)?\\s\*' | `Total Magnetism (uB) ` | | Please look at detailed implementations in the following files. @@ -87,4 +89,4 @@ This module contains the wrapper of k-point sampling functions and helper functi ## xtest.sh -This script can run all the unittests that programmed in all Python source files. \ No newline at end of file +This script can run all the unittests that programmed in all Python source files. diff --git a/interfaces/ASE_interface/README.md b/interfaces/ASE_interface/README.md index 543d4774836..4f506b705db 100644 --- a/interfaces/ASE_interface/README.md +++ b/interfaces/ASE_interface/README.md @@ -2,15 +2,20 @@ ## Introduction -abacuslite is a lightweight plugin for ABACUS (Atomic-orbital Based Ab-initio Computation at UStc), implementing the ASE (Atomic Simulation Environment) calculator interface. +abacuslite is a lightweight plugin for ABACUS (Atomic-orbital Based Ab-initio Computation at UStc), +implementing the ASE (Atomic Simulation Environment) calculator interface. ### Key Features - **Lightweight Design**: Implemented as a plugin, no need to modify ASE core code - **Version Compatibility**: Supports ASE versions satisfying the package requirement `ase>=3.22` -- **ASE Integration**: Uses ASE as the running platform, making ABACUS a callable calculator within it -- **Function Support**: Provides SCF-based energy, force, and stress evaluations through ASE. ASE can use these evaluations for relaxation, molecular dynamics, NEB, band-structure, and density-of-states workflows. -- **Socket Support**: `AbacusSocketIO` provides fixed-cell i-PI socket calculations, with energy always available and forces/stress enabled independently when requested. +- **ASE Integration**: Uses ASE as the running platform, making ABACUS a callable calculator within + it +- **Function Support**: Provides SCF-based energy, force, and stress evaluations through ASE. ASE + can use these evaluations for relaxation, molecular dynamics, NEB, band-structure, and + density-of-states workflows. +- **Socket Support**: `AbacusSocketIO` provides fixed-cell i-PI socket calculations, with energy + always available and forces/stress enabled independently when requested. ## Installation @@ -26,18 +31,22 @@ pip install . Please refer to the example scripts in the `examples` folder. Recommended learning path: 1. **scf.py** - Basic SCF calculation example -2. **relax.py** - Atomic position relaxation calculation -3. **cellrelax.py** - Cell parameter relaxation calculation -4. **bandstructure.py** - Band structure calculation -5. **dos.py** - Density of states calculation -6. **md.py** - Molecular dynamics simulation -7. **constraintmd.py** - Constrained molecular dynamics simulation -8. **metadynamics.py** - Metadynamics simulation -9. **neb.py** - Nudged Elastic Band (NEB) calculation -10. **soc.py** - Noncollinear spin-orbit coupling calculation -11. **socketio.py** - Fixed-cell ASE optimization with `AbacusSocketIO`, running ABACUS as an i-PI socket client - -The regular `Abacus` calculator runs one ABACUS calculation for each ASE property evaluation. ASE controls the relaxation, molecular-dynamics, and other workflow steps. The socket calculator reuses one ABACUS process for position updates, while the cell and electronic-structure settings remain fixed for that calculator instance. +1. **relax.py** - Atomic position relaxation calculation +1. **cellrelax.py** - Cell parameter relaxation calculation +1. **bandstructure.py** - Band structure calculation +1. **dos.py** - Density of states calculation +1. **md.py** - Molecular dynamics simulation +1. **constraintmd.py** - Constrained molecular dynamics simulation +1. **metadynamics.py** - Metadynamics simulation +1. **neb.py** - Nudged Elastic Band (NEB) calculation +1. **soc.py** - Noncollinear spin-orbit coupling calculation +1. **socketio.py** - Fixed-cell ASE optimization with `AbacusSocketIO`, running ABACUS as an i-PI + socket client + +The regular `Abacus` calculator runs one ABACUS calculation for each ASE property evaluation. ASE +controls the relaxation, molecular-dynamics, and other workflow steps. The socket calculator reuses +one ABACUS process for position updates, while the cell and electronic-structure settings remain +fixed for that calculator instance. ## Authors diff --git a/interfaces/ATAT_interface/Readme.md b/interfaces/ATAT_interface/Readme.md index ca53a40703d..24fee72d908 100644 --- a/interfaces/ATAT_interface/Readme.md +++ b/interfaces/ATAT_interface/Readme.md @@ -2,22 +2,31 @@ ## Introduction -`runstruct_abacus` is a lightweight interface script connecting **ATAT (Alloy Theoretic Automated Toolkit)** with **ABACUS** (Atomic-orbital Based Ab-initio Computation at UStc). It automatically converts ATAT's `str.out` structure files into ABACUS `INPUT`/`STRU` input files, runs the DFT calculation, and extracts results back into ATAT-compatible formats (`energy`, `str_relax.out`). +`runstruct_abacus` is a lightweight interface script connecting **ATAT (Alloy Theoretic Automated +Toolkit)** with **ABACUS** (Atomic-orbital Based Ab-initio Computation at UStc). It automatically +converts ATAT's `str.out` structure files into ABACUS `INPUT`/`STRU` input files, runs the DFT +calculation, and extracts results back into ATAT-compatible formats (`energy`, `str_relax.out`). ### Key Features -- **Seamless ATAT Integration**: Works within ATAT's multi-directory enumeration workflow (`1/`, `2/`, `3/`...) -- **Template-Based Input**: Uses `abacus.wrap` as a templateโ€”nearly a native ABACUS `INPUT` file with minimal script-specific annotations -- **Automatic File Discovery**: Searches `abacus.wrap` upward through parent directories (`./` โ†’ `../` โ†’ `../../`...) -- **Smart Pseudopotential/Orbital Matching**: Auto-detects files in `pseudo_dir`/`orbital_dir` by element prefix; explicit override available for ambiguous cases -- **Flexible Execution Modes**: Supports full pipeline, input-only generation, and post-calculation extraction +- **Seamless ATAT Integration**: Works within ATAT's multi-directory enumeration workflow (`1/`, + `2/`, `3/`...) +- **Template-Based Input**: Uses `abacus.wrap` as a templateโ€”nearly a native ABACUS `INPUT` file + with minimal script-specific annotations +- **Automatic File Discovery**: Searches `abacus.wrap` upward through parent directories (`./` โ†’ + `../` โ†’ `../../`...) +- **Smart Pseudopotential/Orbital Matching**: Auto-detects files in `pseudo_dir`/`orbital_dir` by + element prefix; explicit override available for ambiguous cases +- **Flexible Execution Modes**: Supports full pipeline, input-only generation, and post-calculation + extraction - **Parallel Ready**: Accepts `mpirun`/`srun` prefixes for HPC environments ---- +______________________________________________________________________ ## Installation -No installation is required. Simply place `runstruct_abacus` in your `$PATH` (or in the same directory as other ATAT `runstruct_*` scripts) and ensure it is executable: +No installation is required. Simply place `runstruct_abacus` in your `$PATH` (or in the same +directory as other ATAT `runstruct_*` scripts) and ensure it is executable: ```bash chmod +x runstruct_abacus @@ -28,7 +37,7 @@ chmod +x runstruct_abacus - ATAT toolkit (`cellcvrt`, `kmesh` etc.) must be in `$PATH` - ABACUS executable path must be set in `~/.abacus.rc` ---- +______________________________________________________________________ ## Configuration @@ -43,11 +52,13 @@ ABACUSCMD="abacus" # or "mpirun -np 4 abacus" The script will auto-generate a template if this file does not exist. ---- +______________________________________________________________________ ## Template File: `abacus.wrap` -`abacus.wrap` is **almost** a standard ABACUS `INPUT` file. The script copies nearly every line verbatim into `INPUT`, except for `species` lines which are consumed by the script to build the `STRU` file. +`abacus.wrap` is **almost** a standard ABACUS `INPUT` file. The script copies nearly every line +verbatim into `INPUT`, except for `species` lines which are consumed by the script to build the +`STRU` file. ### Minimal Example @@ -70,16 +81,17 @@ species Fe 55.845 Fe_ONCV_PBE-1.0.upf Fe_gga_8au_100Ry_2s2p2d1f.orb species [] ``` -| Field | Description | -| ---------- | ------------------------------------------------------------ | -| `Element` | Chemical symbol (e.g., `Al`, `Fe`) | -| `Mass` | Atomic mass. Use `-` to look up from the built-in table | -| `PP_File` | Pseudopotential filename. Use `-` to auto-search in `pseudo_dir` | +| Field | Description | +| ---------- | --------------------------------------------------------------------------------------- | +| `Element` | Chemical symbol (e.g., `Al`, `Fe`) | +| `Mass` | Atomic mass. Use `-` to look up from the built-in table | +| `PP_File` | Pseudopotential filename. Use `-` to auto-search in `pseudo_dir` | | `Orb_File` | Numerical orbital filename (required for LCAO). Use `-` to auto-search in `orbital_dir` | -If auto-search finds **zero** or **more than one** match for an element, the script aborts and prints a helpful message asking you to add an explicit `species` line. +If auto-search finds **zero** or **more than one** match for an element, the script aborts and +prints a helpful message asking you to add an explicit `species` line. ---- +______________________________________________________________________ ## Command Line Options @@ -89,12 +101,12 @@ runstruct_abacus [-w file] [-nr] [-ex] [-clean] [cmdprefix] ### Execution Modes -| Command | Behavior | -| ------------------------- | ------------------------------------------------------------ | -| `runstruct_abacus` | **Full pipeline**: Generate `INPUT` + `STRU` โ†’ Run ABACUS โ†’ Extract `energy`, `str_relax.out` | -| `runstruct_abacus -nr` | **No-Run**: Generate `INPUT` + `STRU` only. Useful for manual inspection or external job schedulers. | +| Command | Behavior | +| ------------------------- | ------------------------------------------------------------------------------------------------------- | +| `runstruct_abacus` | **Full pipeline**: Generate `INPUT` + `STRU` โ†’ Run ABACUS โ†’ Extract `energy`, `str_relax.out` | +| `runstruct_abacus -nr` | **No-Run**: Generate `INPUT` + `STRU` only. Useful for manual inspection or external job schedulers. | | `runstruct_abacus -ex` | **Extract-Only**: Skip generation and execution. Extract results from existing `OUT.suffix/` directory. | -| `runstruct_abacus -clean` | **Cleanup**: Delete all output files (`OUT.*/`, `running_*.log`, `energy`, `str_relax.out`) and exit. | +| `runstruct_abacus -clean` | **Cleanup**: Delete all output files (`OUT.*/`, `running_*.log`, `energy`, `str_relax.out`) and exit. | ### `cmdprefix`: Running in Parallel @@ -123,9 +135,10 @@ $CMDPREFIX $ABACUSCMD > log.out 2>&1 runstruct_abacus -w my_custom.wrap ``` -If the specified file is not found in the current directory, the script searches upward (`../`, `../../`, `../../../`) exactly like the default `abacus.wrap`. +If the specified file is not found in the current directory, the script searches upward (`../`, +`../../`, `../../../`) exactly like the default `abacus.wrap`. ---- +______________________________________________________________________ ## Workflow Example @@ -158,7 +171,7 @@ runstruct_abacus | `str_relax.out` | Relaxed structure in ATAT `str.out` format | | `log.out` | Raw ABACUS stdout/stderr | ---- +______________________________________________________________________ ## File Search Hierarchy @@ -169,9 +182,10 @@ Both `abacus.wrap` and `str.out` follow ATAT's upward-search convention: | `abacus.wrap` | `./` โ†’ `../` โ†’ `../../` โ†’ `../../../` | | `str.out` | `str_hint.out` (preferred) โ†’ `str.out` | -This allows a single `abacus.wrap` (and optionally a shared `~/.abacus.rc`) to serve an entire ATAT enumeration tree. +This allows a single `abacus.wrap` (and optionally a shared `~/.abacus.rc`) to serve an entire ATAT +enumeration tree. ---- +______________________________________________________________________ ## Authors @@ -184,4 +198,5 @@ This allows a single `abacus.wrap` (and optionally a shared `~/.abacus.rc`) to s ## Contact For issues related to the ABACUS engine itself, please visit: -- GitHub: [deepmodeling/abacus-develop](https://github.com/deepmodeling/abacus-develop) \ No newline at end of file + +- GitHub: [deepmodeling/abacus-develop](https://github.com/deepmodeling/abacus-develop) diff --git a/interfaces/DPGEN_interface/README.md b/interfaces/DPGEN_interface/README.md index 6a1a4d107fc..7c6abfa7c0f 100644 --- a/interfaces/DPGEN_interface/README.md +++ b/interfaces/DPGEN_interface/README.md @@ -1,10 +1,12 @@ # DPGEN Interface -This directory contains the interface between ABACUS and DPGEN (Deep Potential GENerator), an open-source tool for generating deep learning potentials for molecular dynamics simulations. +This directory contains the interface between ABACUS and DPGEN (Deep Potential GENerator), an +open-source tool for generating deep learning potentials for molecular dynamics simulations. ## What is DPGEN? -DPGEN is an open-source tool that automates the generation of deep learning potentials (DPLs) for molecular dynamics simulations. It is designed to: +DPGEN is an open-source tool that automates the generation of deep learning potentials (DPLs) for +molecular dynamics simulations. It is designed to: - Generate training data through ab initio calculations - Train deep learning models for potential energy surfaces @@ -12,6 +14,7 @@ DPGEN is an open-source tool that automates the generation of deep learning pote - Provide a framework for high-throughput materials simulations DPGEN is particularly useful for: + - Accelerating molecular dynamics simulations - Studying large systems that are computationally expensive with ab initio methods - Simulating long-time dynamics @@ -19,7 +22,9 @@ DPGEN is particularly useful for: ## ABACUS-DPGEN Interface -The ABACUS-DPGEN interface allows ABACUS to be used as the ab initio calculator for DPGEN. This enables DPGEN to generate training data using ABACUS's various basis sets (plane wave and LCAO) and functional choices. +The ABACUS-DPGEN interface allows ABACUS to be used as the ab initio calculator for DPGEN. This +enables DPGEN to generate training data using ABACUS's various basis sets (plane wave and LCAO) and +functional choices. ### Key Features of the Interface @@ -30,9 +35,11 @@ The ABACUS-DPGEN interface allows ABACUS to be used as the ab initio calculator ## Examples -This directory contains two examples demonstrating different use cases of the ABACUS-DPGEN interface: +This directory contains two examples demonstrating different use cases of the ABACUS-DPGEN +interface: ### 1. autotest + - **Purpose**: Demonstrates automated testing of the ABACUS-DPGEN interface - **Input Files**: - DPGEN input files @@ -40,6 +47,7 @@ This directory contains two examples demonstrating different use cases of the AB - Scripts for running the calculation ### 2. init_and_run + - **Purpose**: Demonstrates the complete workflow of initializing and running DPGEN with ABACUS - **Input Files**: - DPGEN input files @@ -50,30 +58,35 @@ This directory contains two examples demonstrating different use cases of the AB ### Prerequisites -1. **Install DPGEN**: Follow the installation instructions on the [DPGEN GitHub repository](https://github.com/deepmodeling/dpgen) -2. **Set up ABACUS**: Ensure ABACUS is compiled and accessible in your PATH -3. **Prepare input files**: Create ABACUS input files and DPGEN input files +1. **Install DPGEN**: Follow the installation instructions on the + [DPGEN GitHub repository](https://github.com/deepmodeling/dpgen) +1. **Set up ABACUS**: Ensure ABACUS is compiled and accessible in your PATH +1. **Prepare input files**: Create ABACUS input files and DPGEN input files ### Basic Workflow 1. **Prepare DPGEN input files**: + - Create `input.json` file with calculation parameters - Define the structure and configuration space - Set up the ABACUS calculator settings -2. **Run DPGEN**: +1. **Run DPGEN**: + - DPGEN will automatically generate initial configurations - It will run ABACUS calculations to generate training data - It will train deep learning models based on the data - It will validate and test the trained models -3. **Use the trained model**: +1. **Use the trained model**: + - The trained deep learning potential can be used for molecular dynamics simulations - It can be integrated with molecular dynamics packages like LAMMPS ### Important Notes -- The quality of the deep learning potential depends on the quality and diversity of the training data +- The quality of the deep learning potential depends on the quality and diversity of the training + data - Ensure that the ABACUS calculations are properly converged - Convergence tests should be performed for basis set, k-point sampling, and other parameters @@ -81,10 +94,12 @@ This directory contains two examples demonstrating different use cases of the AB - **ABACUS calculations failing**: Check that ABACUS is properly installed and accessible - **DPGEN cannot read ABACUS output**: Ensure that ABACUS is generating the necessary output files -- **Training not converging**: Consider increasing the amount of training data or adjusting the model parameters +- **Training not converging**: Consider increasing the amount of training data or adjusting the + model parameters ## References -- **DPGEN GitHub repository**: [https://github.com/deepmodeling/dpgen](https://github.com/deepmodeling/dpgen) +- **DPGEN GitHub repository**: + [https://github.com/deepmodeling/dpgen](https://github.com/deepmodeling/dpgen) - **DPGEN paper**: L. Zhang et al., *npj Comput. Mater.* **6**, 1 (2020) - **ABACUS documentation**: Refer to the ABACUS user manual for more details on input parameters diff --git a/interfaces/DPGEN_interface/init_and_run/INPUT.md b/interfaces/DPGEN_interface/init_and_run/INPUT.md index 4114899b341..cc084d738c0 100644 --- a/interfaces/DPGEN_interface/init_and_run/INPUT.md +++ b/interfaces/DPGEN_interface/init_and_run/INPUT.md @@ -1,29 +1,11 @@ -INPUT_PARAMETERS -#Parameters (1.General) -suffix ABACUS -calculation md -symmetry 1 -pseudo_dir ./ +INPUT_PARAMETERS #Parameters (1.General) suffix ABACUS calculation md symmetry 1 pseudo_dir ./ -#Parameters (2.Iteration) -ecutwfc 40 -scf_thr 1e-6 -scf_nmax 100 +#Parameters (2.Iteration) ecutwfc 40 scf_thr 1e-6 scf_nmax 100 +#Parameters (3.Basis) basis_type pw -#Parameters (3.Basis) -basis_type pw +#Parameters (4.Smearing) smearing_method gauss smearing_sigma 0.002 -#Parameters (4.Smearing) -smearing_method gauss -smearing_sigma 0.002 +#Parameters (5.Mixing) mixing_type broyden mixing_beta 0.7 -#Parameters (5.Mixing) -mixing_type broyden -mixing_beta 0.7 - -cal_stress 1 -md_nstep 3 -md_tfirst 10 -md_tfreq 0.1 -out_stru 1 +cal_stress 1 md_nstep 3 md_tfirst 10 md_tfreq 0.1 out_stru 1 diff --git a/interfaces/HefeiNAMD_interface/README.md b/interfaces/HefeiNAMD_interface/README.md index 00b7aff5aab..0e633599f9e 100644 --- a/interfaces/HefeiNAMD_interface/README.md +++ b/interfaces/HefeiNAMD_interface/README.md @@ -1,21 +1,34 @@ # Hefei-NAMD Interface -This directory contains the interface between ABACUS and Hefei-NAMD, an open-source, ab initio non-adiabatic molecular dynamics (NAMD) package designed for simulating ultrafast excited-state carrier dynamics in condensed-matter systems. +This directory contains the interface between ABACUS and Hefei-NAMD, an open-source, ab initio +non-adiabatic molecular dynamics (NAMD) package designed for simulating ultrafast excited-state +carrier dynamics in condensed-matter systems. ## What is Hefei-NAMD? -Hefei-NAMD is an open-source, ab initio non-adiabatic molecular dynamics (NAMD) package designed for simulating ultrafast excited-state carrier dynamics in condensed-matter systems (e.g., semiconductors, 2D materials, oxides, and interfaces) across real/momentum space, energy, and time domains. Developed primarily by Prof. Qijing Zheng (University of Science and Technology of China, USTC) and collaborators, it is hosted publicly on GitHub: [github.com/QijingZheng/Hefei-NAMD](https://github.com/QijingZheng/Hefei-NAMD). +Hefei-NAMD is an open-source, ab initio non-adiabatic molecular dynamics (NAMD) package designed for +simulating ultrafast excited-state carrier dynamics in condensed-matter systems (e.g., +semiconductors, 2D materials, oxides, and interfaces) across real/momentum space, energy, and time +domains. Developed primarily by Prof. Qijing Zheng (University of Science and Technology of China, +USTC) and collaborators, it is hosted publicly on GitHub: +[github.com/QijingZheng/Hefei-NAMD](https://github.com/QijingZheng/Hefei-NAMD). ### Core Methodology -- **Theoretical foundation**: Combines time-dependent density-functional theory (TDDFT) with the fewest-switches surface hopping (FSSH) algorithm and decoherence-induced surface hopping (DISH) to treat electronโ€“phonon coupling and non-adiabatic transitions between electronic states. -- **Key quantities**: Computes non-adiabatic coupling (NAC) matrices and electronโ€“phonon coupling (EPC) from first-principles wavefunctions. -- **Implementation**: Mainly written in Fortran (โ‰ˆ80%) with Python pre/post-processing tools; minimal external dependencies, easy to compile via make. +- **Theoretical foundation**: Combines time-dependent density-functional theory (TDDFT) with the + fewest-switches surface hopping (FSSH) algorithm and decoherence-induced surface hopping (DISH) to + treat electronโ€“phonon coupling and non-adiabatic transitions between electronic states. +- **Key quantities**: Computes non-adiabatic coupling (NAC) matrices and electronโ€“phonon coupling + (EPC) from first-principles wavefunctions. +- **Implementation**: Mainly written in Fortran (โ‰ˆ80%) with Python pre/post-processing tools; + minimal external dependencies, easy to compile via make. ### Key Features -- **Interfaces to major DFT codes**: Works natively with VASP and ABACUS (via abacus-namd scripts) to read MD trajectories, wavefunctions, and band structures. -- **Real- and momentum-space dynamics**: Supports carrier relaxation, recombination, hot-carrier transport, and exciton dynamics. +- **Interfaces to major DFT codes**: Works natively with VASP and ABACUS (via abacus-namd scripts) + to read MD trajectories, wavefunctions, and band structures. +- **Real- and momentum-space dynamics**: Supports carrier relaxation, recombination, hot-carrier + transport, and exciton dynamics. - **Advanced capabilities**: - Spinโ€“orbit coupling (SOC) (via NAMDwithSOC extension). - Lightโ€“matter interaction (NAMD-LMI) for photoexcitation and stimulated emission. @@ -25,40 +38,48 @@ Hefei-NAMD is an open-source, ab initio non-adiabatic molecular dynamics (NAMD) ### Workflow 1. **Geometry optimization** โ†’ ab initio MD โ†’ trajectory snapshots. -2. **DFT single-points (SCF)** โ†’ wavefunction output. -3. **NAMD simulation** โ†’ analysis of carrier lifetime, relaxation pathways, etc. +1. **DFT single-points (SCF)** โ†’ wavefunction output. +1. **NAMD simulation** โ†’ analysis of carrier lifetime, relaxation pathways, etc. ### Applications -- **Carrier relaxation/recombination**: e.g., in TiOโ‚‚, perovskites, 2D van der Waals heterostructures. +- **Carrier relaxation/recombination**: e.g., in TiOโ‚‚, perovskites, 2D van der Waals + heterostructures. - **Hot-carrier dynamics and transport** in photovoltaics and photocatalysts. - **Exciton dissociation and charge transfer** at interfaces. - **Ultrafast spectroscopy** (transient absorption, photoluminescence) interpretation. ### Availability & Use -- **Open-source**: Free under academic license; source code, manual, tutorials, and examples are fully public. -- **Citation**: Users are requested to cite core publications (e.g., Zheng et al., WIREs Comput. Mol. Sci., 2021). +- **Open-source**: Free under academic license; source code, manual, tutorials, and examples are + fully public. +- **Citation**: Users are requested to cite core publications (e.g., Zheng et al., WIREs Comput. + Mol. Sci., 2021). -In short, Hefei-NAMD is a widely used, community-driven tool for first-principles excited-state dynamics in materials science, valued for its efficiency, flexibility, and compatibility with standard DFT workflows. +In short, Hefei-NAMD is a widely used, community-driven tool for first-principles excited-state +dynamics in materials science, valued for its efficiency, flexibility, and compatibility with +standard DFT workflows. ## ABACUS-Hefei-NAMD Interface -The ABACUS-Hefei-NAMD interface allows ABACUS to generate the necessary files for Hefei-NAMD calculations, including overlap matrices, wavefunctions, and Hamiltonian matrices. +The ABACUS-Hefei-NAMD interface allows ABACUS to generate the necessary files for Hefei-NAMD +calculations, including overlap matrices, wavefunctions, and Hamiltonian matrices. ### Key Parameters for ABACUS-Hefei-NAMD Interface: - `cal_syns`: Set to 1 to calculate asynchronous overlap matrix -- `dmax`: Maximum displacement of all atoms in one step (in bohr) for calculating asynchronous overlap matrix +- `dmax`: Maximum displacement of all atoms in one step (in bohr) for calculating asynchronous + overlap matrix - `out_wfc_lcao`: Set to 1 to output wavefunction files - `out_hsk`: Set to 1 to output Hamiltonian and overlap matrix files ### Examples -The `example01` directory contains a simple example demonstrating how to set up an ABACUS calculation that generates the necessary files for Hefei-NAMD. +The `example01` directory contains a simple example demonstrating how to set up an ABACUS +calculation that generates the necessary files for Hefei-NAMD. ### How to Use the Interface 1. Set up an ABACUS calculation with the appropriate parameters for Hefei-NAMD (see examples) -2. Run ABACUS to generate the necessary output files -3. Use the generated files as input for Hefei-NAMD calculations +1. Run ABACUS to generate the necessary output files +1. Use the generated files as input for Hefei-NAMD calculations diff --git a/interfaces/PLUMED_interface/README.md b/interfaces/PLUMED_interface/README.md index 7648f715da4..fb0336533c1 100644 --- a/interfaces/PLUMED_interface/README.md +++ b/interfaces/PLUMED_interface/README.md @@ -1,68 +1,74 @@ # ABACUS + PLUMED interface -[PLUMED](https://www.plumed.org) is a library for enhanced-sampling methods -(metadynamics, umbrella sampling, ...). During an ABACUS molecular-dynamics run -it can compute collective variables and apply biasing potentials, controlled by -the `plumed` and `plumed_file` INPUT keywords. +[PLUMED](https://www.plumed.org) is a library for enhanced-sampling methods (metadynamics, umbrella +sampling, ...). During an ABACUS molecular-dynamics run it can compute collective variables and +apply biasing potentials, controlled by the `plumed` and `plumed_file` INPUT keywords. ## Building ABACUS with PLUMED Install PLUMED 2.x first, for example: - ./configure --prefix=/path/to/plumed && make -j && make install +``` +./configure --prefix=/path/to/plumed && make -j && make install +``` Then configure ABACUS with `-DENABLE_PLUMED=ON`: - cmake -B build -DENABLE_PLUMED=ON ... - cmake --build build -j +``` +cmake -B build -DENABLE_PLUMED=ON ... +cmake --build build -j +``` -The PLUMED installation is located with `pkg-config` (through the `plumed.pc` -file shipped by PLUMED); if PLUMED is installed in a non-standard prefix, add -`-DPLUMED_ROOT=/path/to/plumed` so that it can be found without pkg-config. -When ABACUS is built without `-DENABLE_PLUMED=ON`, setting `plumed` in INPUT -stops the run with an explicit error message. +The PLUMED installation is located with `pkg-config` (through the `plumed.pc` file shipped by +PLUMED); if PLUMED is installed in a non-standard prefix, add `-DPLUMED_ROOT=/path/to/plumed` so +that it can be found without pkg-config. When ABACUS is built without `-DENABLE_PLUMED=ON`, setting +`plumed` in INPUT stops the run with an explicit error message. ## Usage In the `INPUT` file: - plumed 1 # enable the PLUMED interface - plumed_file plumed.dat # PLUMED input file (default: plumed.dat) +``` +plumed 1 # enable the PLUMED interface +plumed_file plumed.dat # PLUMED input file (default: plumed.dat) +``` -The PLUMED input file defines the collective variables and the biasing -potential, e.g. for a dihedral angle: +The PLUMED input file defines the collective variables and the biasing potential, e.g. for a +dihedral angle: - UNITS LENGTH=A TIME=fs - t: TORSION ATOMS=3,1,2,7 - metad: METAD ARG=t PACE=50 HEIGHT=2.0 SIGMA=0.15 FILE=HILLS BIASFACTOR=20 TEMP=600 - PRINT ARG=t,metad.bias FILE=COLVAR STRIDE=1 +``` +UNITS LENGTH=A TIME=fs +t: TORSION ATOMS=3,1,2,7 +metad: METAD ARG=t PACE=50 HEIGHT=2.0 SIGMA=0.15 FILE=HILLS BIASFACTOR=20 TEMP=600 +PRINT ARG=t,metad.bias FILE=COLVAR STRIDE=1 +``` -ABACUS hands the atomic positions (Bohr), masses (amu), cell, potential energy -and virial over to PLUMED after every MD step, and PLUMED adds the biasing -forces in place. +ABACUS hands the atomic positions (Bohr), masses (amu), cell, potential energy and virial over to +PLUMED after every MD step, and PLUMED adds the biasing forces in place. -Note: the interface currently supports a single MPI rank only, because PLUMED -must see the whole system while ABACUS distributes the atoms of an MD run over -the ranks. OpenMP threads inside that single rank are fine, e.g. -`OMP_NUM_THREADS=32 abacus > log`. +Note: the interface currently supports a single MPI rank only, because PLUMED must see the whole +system while ABACUS distributes the atoms of an MD run over the ranks. OpenMP threads inside that +single rank are fine, e.g. `OMP_NUM_THREADS=32 abacus > log`. ## Example -`example01` runs a well-tempered metadynamics of the ethane (C2H6) H-C-C-H -torsion at 600 K (LCAO). Running ABACUS in that directory produces +`example01` runs a well-tempered metadynamics of the ethane (C2H6) H-C-C-H torsion at 600 K (LCAO). +Running ABACUS in that directory produces - - `COLVAR`: time, the torsion angle and the metadynamics bias at every MD step; - - `HILLS`: the Gaussian hills deposited by metadynamics. +- `COLVAR`: time, the torsion angle and the metadynamics bias at every MD step; +- `HILLS`: the Gaussian hills deposited by metadynamics. The free-energy surface can be reconstructed with the tools shipped with PLUMED: - plumed sum_hills --hills HILLS --mintozero --outfile fes.dat +``` +plumed sum_hills --hills HILLS --mintozero --outfile fes.dat +``` -`fes.dat` contains the torsion angle (rad) in the first column and the free -energy (kJ/mol) in the second one. +`fes.dat` contains the torsion angle (rad) in the first column and the free energy (kJ/mol) in the +second one. ## References - - PLUMED manual: - - ABACUS `plumed` / `plumed_file` keywords: - +- PLUMED manual: +- ABACUS `plumed` / `plumed_file` keywords: + diff --git a/interfaces/Phonopy_interface/README.md b/interfaces/Phonopy_interface/README.md index bf8c1f455ea..ef8fe20e8c9 100644 --- a/interfaces/Phonopy_interface/README.md +++ b/interfaces/Phonopy_interface/README.md @@ -1,10 +1,13 @@ # Phonopy Interface -This directory contains the interface between ABACUS and Phonopy, an open-source software for phonon calculations. Phonopy is widely used for calculating phonon dispersion relations, phonon density of states, and thermodynamic properties of materials. +This directory contains the interface between ABACUS and Phonopy, an open-source software for phonon +calculations. Phonopy is widely used for calculating phonon dispersion relations, phonon density of +states, and thermodynamic properties of materials. ## What is Phonopy? -Phonopy is an open-source software package for phonon calculations at harmonic and quasi-harmonic levels. It is designed to: +Phonopy is an open-source software package for phonon calculations at harmonic and quasi-harmonic +levels. It is designed to: - Calculate phonon dispersion relations - Compute phonon density of states (DOS) @@ -13,14 +16,17 @@ Phonopy is an open-source software package for phonon calculations at harmonic a - Support various first-principles calculation codes through interfaces Phonopy works by: + 1. Generating supercells with atomic displacements -2. Running force calculations for these displaced supercells -3. Fitting a force constant matrix from the calculated forces -4. Calculating phonon properties based on the force constants +1. Running force calculations for these displaced supercells +1. Fitting a force constant matrix from the calculated forces +1. Calculating phonon properties based on the force constants ## ABACUS-Phonopy Interface -The ABACUS-Phonopy interface allows ABACUS to be used as the force calculator for Phonopy. This enables users to perform phonon calculations using ABACUS's various basis sets (plane wave and LCAO) and functional choices. +The ABACUS-Phonopy interface allows ABACUS to be used as the force calculator for Phonopy. This +enables users to perform phonon calculations using ABACUS's various basis sets (plane wave and LCAO) +and functional choices. ### Key Features of the Interface @@ -31,7 +37,8 @@ The ABACUS-Phonopy interface allows ABACUS to be used as the force calculator fo ## Example -The `example01` directory contains a simple example demonstrating how to use the ABACUS-Phonopy interface to calculate phonons for aluminum (Al). +The `example01` directory contains a simple example demonstrating how to use the ABACUS-Phonopy +interface to calculate phonons for aluminum (Al). ### Example Files @@ -48,20 +55,24 @@ The `example01` directory contains a simple example demonstrating how to use the ### Prerequisites -1. **Install Phonopy**: Follow the installation instructions on the [Phonopy website](https://phonopy.github.io/phonopy/) -2. **Set up ABACUS**: Ensure ABACUS is compiled and accessible in your PATH -3. **Prepare input files**: Create INPUT, KPT, and STRU files for your system +1. **Install Phonopy**: Follow the installation instructions on the + [Phonopy website](https://phonopy.github.io/phonopy/) +1. **Set up ABACUS**: Ensure ABACUS is compiled and accessible in your PATH +1. **Prepare input files**: Create INPUT, KPT, and STRU files for your system ### Usage Notes -- For detailed instructions on using Phonopy with ABACUS, please refer to the [Phonopy documentation](https://phonopy.github.io/phonopy/) +- For detailed instructions on using Phonopy with ABACUS, please refer to the + [Phonopy documentation](https://phonopy.github.io/phonopy/) - The interface requires ABACUS to generate FORCE_ABACUS files in the OUT.ABACUS directory - Phonopy will use these force files to calculate phonon properties ## Troubleshooting -- **Force files not found**: Ensure ABACUS is generating FORCE_ABACUS files in the OUT.ABACUS directory -- **Phonopy cannot read ABACUS output**: Check that ABACUS is compiled with the necessary output options +- **Force files not found**: Ensure ABACUS is generating FORCE_ABACUS files in the OUT.ABACUS + directory +- **Phonopy cannot read ABACUS output**: Check that ABACUS is compiled with the necessary output + options - **Memory issues**: For large supercells, increase the memory allocation for ABACUS - **Convergence issues**: Ensure the SCF calculation is converged for each displaced supercell @@ -76,4 +87,5 @@ The `example01` directory contains a simple example demonstrating how to use the - The ABACUS-Phonopy interface is continuously being improved - For large systems, consider using parallel calculations to speed up the force calculations - Always check the convergence of your results with respect to supercell size and k-point sampling -- The example provided is for demonstration purposes; adjust parameters according to your specific system +- The example provided is for demonstration purposes; adjust parameters according to your specific + system diff --git a/interfaces/ShengBTE_interface/README.md b/interfaces/ShengBTE_interface/README.md index 4f2a1cb5194..41318e4b688 100644 --- a/interfaces/ShengBTE_interface/README.md +++ b/interfaces/ShengBTE_interface/README.md @@ -1,10 +1,12 @@ # ShengBTE Interface -This directory contains the interface between ABACUS and ShengBTE, an open-source code for calculating lattice thermal conductivity using the Boltzmann Transport Equation (BTE). +This directory contains the interface between ABACUS and ShengBTE, an open-source code for +calculating lattice thermal conductivity using the Boltzmann Transport Equation (BTE). ## What is ShengBTE? -ShengBTE is an open-source code that calculates lattice thermal conductivity from first principles using the Boltzmann Transport Equation (BTE). It is designed to: +ShengBTE is an open-source code that calculates lattice thermal conductivity from first principles +using the Boltzmann Transport Equation (BTE). It is designed to: - Calculate lattice thermal conductivity - Compute phonon dispersion relations @@ -13,6 +15,7 @@ ShengBTE is an open-source code that calculates lattice thermal conductivity fro - Support various first-principles calculation codes through interfaces ShengBTE is particularly useful for: + - Studying thermal transport in materials - Designing materials with specific thermal properties - Understanding phonon scattering mechanisms @@ -36,9 +39,11 @@ The ABACUS-ShengBTE interface allows ABACUS to generate the necessary files for ## Examples -This directory contains two examples demonstrating different use cases of the ABACUS-ShengBTE interface: +This directory contains two examples demonstrating different use cases of the ABACUS-ShengBTE +interface: ### 1. 01_pw + - **System**: Silicon (Si) - **Basis**: Plane wave (PW) - **Purpose**: Demonstrates ShengBTE calculation using plane wave basis set @@ -48,6 +53,7 @@ This directory contains two examples demonstrating different use cases of the AB - Scripts for running the calculation ### 2. 02_lcao + - **System**: Silicon (Si) - **Basis**: LCAO (Linear Combination of Atomic Orbitals) - **Purpose**: Demonstrates ShengBTE calculation using LCAO basis set @@ -60,23 +66,27 @@ This directory contains two examples demonstrating different use cases of the AB ### Prerequisites -1. **Install ShengBTE**: Follow the installation instructions on the [ShengBTE website](https://shengbte.org/) -2. **Set up ABACUS**: Ensure ABACUS is compiled with ShengBTE support -3. **Prepare input files**: Create ABACUS input files and ShengBTE input files +1. **Install ShengBTE**: Follow the installation instructions on the + [ShengBTE website](https://shengbte.org/) +1. **Set up ABACUS**: Ensure ABACUS is compiled with ShengBTE support +1. **Prepare input files**: Create ABACUS input files and ShengBTE input files ### Basic Workflow 1. **Run ABACUS calculations to generate force constants**: + - Calculate second-order force constants - Calculate third-order force constants - This will generate files containing the force constant information -2. **Prepare ShengBTE input files**: +1. **Prepare ShengBTE input files**: + - Create `control.f90` file with calculation parameters - Create `structure.f90` file with crystal structure information - Create `BTE.out` file with initial conditions -3. **Run ShengBTE**: +1. **Run ShengBTE**: + - Use the force constants from ABACUS as input - This will calculate the lattice thermal conductivity @@ -89,7 +99,8 @@ This directory contains two examples demonstrating different use cases of the AB ## Troubleshooting - **Force constants not found**: Ensure ABACUS is generating the necessary force constant files -- **ShengBTE cannot read ABACUS output**: Check that the force constant files are in the correct format +- **ShengBTE cannot read ABACUS output**: Check that the force constant files are in the correct + format - **Convergence issues**: Ensure the force constant calculations are properly converged ## References diff --git a/interfaces/TB2J_interface/README.md b/interfaces/TB2J_interface/README.md index 2b707d3ceb1..239d8c36fae 100755 --- a/interfaces/TB2J_interface/README.md +++ b/interfaces/TB2J_interface/README.md @@ -1,18 +1,28 @@ # TB2J Interface -This directory contains the interface between ABACUS and TB2J, an open-source Python package for the automatic computation of magnetic interactions. +This directory contains the interface between ABACUS and TB2J, an open-source Python package for the +automatic computation of magnetic interactions. ## Introduction -[TB2J](https://github.com/mailhexu/TB2J) is an open-source Python package for the automatic computation of magnetic interactions (including exchange and Dzyaloshinskii-Moriya) between atoms of magnetic crystals from density functional Hamiltonians based on Wannier functions or linear combinations of atomic orbitals. The program is based on Greenโ€™s function method with the local rigid spin rotation treated as a perturbation. The ABACUS interface has been added since TB2J version 0.8.0. +[TB2J](https://github.com/mailhexu/TB2J) is an open-source Python package for the automatic +computation of magnetic interactions (including exchange and Dzyaloshinskii-Moriya) between atoms of +magnetic crystals from density functional Hamiltonians based on Wannier functions or linear +combinations of atomic orbitals. The program is based on Greenโ€™s function method with the local +rigid spin rotation treated as a perturbation. The ABACUS interface has been added since TB2J +version 0.8.0. The Heisenberg Hamiltonian in TB2J contains three different parts, which are: -$E = -\sum_{i \neq j} \left[ J_{\text{iso}}^{ij} \vec{S}_i \cdot \vec{S}_j + \vec{S}_i J_{\text{ani}}^{ij} \vec{S}_j + \vec{D}_{ij} \cdot (\vec{S}_i \times \vec{S}_j) \right],$ +$E = -\\sum\_{i \\neq j} \\left\[ J\_{\\text{iso}}^{ij} \\vec{S}\_i \\cdot \\vec{S}\_j + \\vec{S}_i +J_{\\text{ani}}^{ij} \\vec{S}_j + \\vec{D}_{ij} \\cdot (\\vec{S}\_i \\times \\vec{S}\_j) \\right\],$ -where $J_{\text{iso}}^{ij}$ represents the isotropic exchange, $J_{\text{ani}}^{ij}$ represents the symmetric anisotropic exhcange which is a 3 $\times$ 3 tensor with $J^{\text{ani}} = J^{\text{ani,T}}$, $\vec{D}_{ij}$ represents the Dzyaloshinskii-Moriya interaction (DMI). +where $J\_{\\text{iso}}^{ij}$ represents the isotropic exchange, $J\_{\\text{ani}}^{ij}$ represents +the symmetric anisotropic exhcange which is a 3 $\\times$ 3 tensor with $J^{\\text{ani}} = +J^{\\text{ani,T}}$, $\\vec{D}\_{ij}$ represents the Dzyaloshinskii-Moriya interaction (DMI). -> **Note:** Exchange parameters conventions for other Heisenberg Hamiltonian can be found in [Conventions of Heisenberg Model](https://tb2j.readthedocs.io/en/latest/src/convention.html). +> **Note:** Exchange parameters conventions for other Heisenberg Hamiltonian can be found in +> [Conventions of Heisenberg Model](https://tb2j.readthedocs.io/en/latest/src/convention.html). For more information, see the documentation on https://tb2j.readthedocs.io/en/latest/ @@ -34,21 +44,31 @@ python setup.py install ## How to use -With the LCAO basis set, TB2J can directly take the output and compute the exchange parameters. For the PW and LCAO-in-PW basis set, the Wannier90 interace can be used instead. In this tutorial we will use LCAO. +With the LCAO basis set, TB2J can directly take the output and compute the exchange parameters. For +the PW and LCAO-in-PW basis set, the Wannier90 interace can be used instead. In this tutorial we +will use LCAO. -The `example01` directory contains a simple example demonstrating how to use the ABACUS to generate the input files required for TB2J for iron (Fe), then perform TB2J to calculate magnetic interactions. +The `example01` directory contains a simple example demonstrating how to use the ABACUS to generate +the input files required for TB2J for iron (Fe), then perform TB2J to calculate magnetic +interactions. -#### 1. Perform ABACUS calculation. - -After the key parameter `out_hsr` is set to 1, the Hamiltonian matrix $H(R)$ (in $Ry$) and overlap matrix $S(R)$ will be written into files in the directory `OUT.${suffix}` . In the INPUT, the line: +#### 1. Perform ABACUS calculation. + +After the key parameter `out_hsr` is set to 1, the Hamiltonian matrix $H(R)$ (in $Ry$) and overlap +matrix $S(R)$ will be written into files in the directory `OUT.${suffix}` . In the INPUT, the line: ``` suffix Fe ``` -specifies the suffix of the output, in this calculation, we set the path to the directory of the DFT calculation, which is the current directory (".") and the suffix to Fe. +specifies the suffix of the output, in this calculation, we set the path to the directory of the DFT +calculation, which is the current directory (".") and the suffix to Fe. -> **Note (ABACUS v3.9.0.25+):** Starting from ABACUS v3.9.0.25, the output format has changed to standard CSR format with filenames `hrs1_nao.csr`, `hrs2_nao.csr` (for nspin=2), and `sr_nao.csr`. The parameter `out_hsr` supports optional precision control: `out_hsr 1 8` (default 8 digits); the legacy spelling `out_mat_hs2` remains accepted. TB2J v0.9.0+ is required to read the new format. For older TB2J versions, please use ABACUS v3.8.x or earlier. +> **Note (ABACUS v3.9.0.25+):** Starting from ABACUS v3.9.0.25, the output format has changed to +> standard CSR format with filenames `hrs1_nao.csr`, `hrs2_nao.csr` (for nspin=2), and `sr_nao.csr`. +> The parameter `out_hsr` supports optional precision control: `out_hsr 1 8` (default 8 digits); the +> legacy spelling `out_mat_hs2` remains accepted. TB2J v0.9.0+ is required to read the new format. +> For older TB2J versions, please use ABACUS v3.8.x or earlier. #### 2. Perform TB2J calculation: @@ -56,24 +76,36 @@ specifies the suffix of the output, in this calculation, we set the path to the abacus2J.py --path . --suffix Fe --elements Fe --kmesh 7 7 7 ``` -This first reads the atomic structures from the `STRU` file, then reads the Hamiltonian and overlap matrices. It also reads the fermi energy from the `OUT.Fe/running_scf.log` file. -> **Note:** For ABACUS v3.9.0.25+, the matrices are stored in `hrs1_nao.csr`, `hrs2_nao.csr` (nspin=2), and `sr_nao.csr` files. For older versions, they are in `data-HR-*` and `data-SR-*` files. +This first reads the atomic structures from the `STRU` file, then reads the Hamiltonian and overlap +matrices. It also reads the fermi energy from the `OUT.Fe/running_scf.log` file. + +> **Note:** For ABACUS v3.9.0.25+, the matrices are stored in `hrs1_nao.csr`, `hrs2_nao.csr` +> (nspin=2), and `sr_nao.csr` files. For older versions, they are in `data-HR-*` and `data-SR-*` +> files. -With the command above, we can calculate the $J$ with a $7 \times 7 \times 7$ k-point grid. This allows for the calculation of exchange between spin pairs between $7 \times 7 \times 7$ supercell. Note: the kmesh is not dense enough for a practical calculation. For a very dense k-mesh, the `--rcut` option can be used to set the maximum distance of the magnetic interactions and thus reduce the computation cost. But be sure that the cutoff is not too small. +With the command above, we can calculate the $J$ with a $7 \\times 7 \\times 7$ k-point grid. This +allows for the calculation of exchange between spin pairs between $7 \\times 7 \\times 7$ supercell. +Note: the kmesh is not dense enough for a practical calculation. For a very dense k-mesh, the +`--rcut` option can be used to set the maximum distance of the magnetic interactions and thus reduce +the computation cost. But be sure that the cutoff is not too small. -The description of the output files in `TB2J_results` can be found in the [TB2J documentation](https://tb2j.readthedocs.io/en/latest/src/output.html). +The description of the output files in `TB2J_results` can be found in the +[TB2J documentation](https://tb2j.readthedocs.io/en/latest/src/output.html). -Several other formats of the exchange parameters are also provided in the `TB2J_results` directory , which can be used in spin dynamics code, e.g. [MULTIBINIT](https://docs.abinit.org/tutorial/spin_model/), [Vampire](https://vampire.york.ac.uk/). +Several other formats of the exchange parameters are also provided in the `TB2J_results` directory , +which can be used in spin dynamics code, e.g. +[MULTIBINIT](https://docs.abinit.org/tutorial/spin_model/), [Vampire](https://vampire.york.ac.uk/). ### Parameters of abacus2J.py -We can use the command +We can use the command ```bash abacus2J.py --help ``` -to view the parameters and the usage of them in abacus2J.py. +to view the parameters and the usage of them in abacus2J.py. ### Acknowledgments -We thanks to Xu He and Zhenxiong Shen to provide critical interface support. + +We thanks to Xu He and Zhenxiong Shen to provide critical interface support. diff --git a/interfaces/Wannier90_interface/README.md b/interfaces/Wannier90_interface/README.md index ff2ba9e71ae..e69ab7431ed 100644 --- a/interfaces/Wannier90_interface/README.md +++ b/interfaces/Wannier90_interface/README.md @@ -1,9 +1,13 @@ # A Brief Introduction to ABACUS Wannier90 Interface -This package provides a user-friendly Python interface: abacusw90 to bridge **ABACUS** (Atomic-scale Simulation Package) with **Wannier90**. It automates the workflow of generating Maximally Localized Wannier Functions (MLWFs) and tight-binding models from ABACUS calculations. + +This package provides a user-friendly Python interface: abacusw90 to bridge **ABACUS** (Atomic-scale +Simulation Package) with **Wannier90**. It automates the workflow of generating Maximally Localized +Wannier Functions (MLWFs) and tight-binding models from ABACUS calculations. ## What is Wannier90? -Wannier90 is an open-source code that calculates maximally localized Wannier functions (MLWFs) from first-principles calculations. It is designed to: +Wannier90 is an open-source code that calculates maximally localized Wannier functions (MLWFs) from +first-principles calculations. It is designed to: - Generate maximally localized Wannier functions - Calculate band structures and density of states @@ -12,6 +16,7 @@ Wannier90 is an open-source code that calculates maximally localized Wannier fun - Support various first-principles calculation codes through interfaces Wannier functions are particularly useful for: + - Electronic structure calculations - Transport properties - Spectroscopy calculations @@ -26,17 +31,22 @@ The abacusw90 package allows ABACUS to generate the necessary files for Wannier9 - `UNK*` files: Bloch wavefunctions ## Key features + - **Various Basis Sets**: Support for both plane wave (PW) and LCAO basis sets. -- **Automated Workflow**: Handles the core coupling pipeline (Steps 3-5 of the standard tutorial workflow). +- **Automated Workflow**: Handles the core coupling pipeline (Steps 3-5 of the standard tutorial + workflow). - **Input Generation**: Automatically generates `wannier90.win`, `INPUT`, `KPT`, and `STRU` files. -- **Method Support**: Supports the recommended `wannier_method = 2` for efficient overlap matrix calculation. +- **Method Support**: Supports the recommended `wannier_method = 2` for efficient overlap matrix + calculation. - **Spin-Orbit Coupling**: Full support for SOC calculations (`nspin=4`, `lspinorb=1`). ## Examples -This directory contains three examples demonstrating different use cases of the ABACUS-Wannier90 interface: +This directory contains three examples demonstrating different use cases of the ABACUS-Wannier90 +interface: ### 1. 01_lcao + - **System**: Diamond (C) - **Basis**: LCAO (Linear Combination of Atomic Orbitals) - **Purpose**: Demonstrates Wannier90 calculation using LCAO basis set @@ -50,36 +60,47 @@ This directory contains three examples demonstrating different use cases of the - `diamond.nnkp`: Wannier90 preprocessing file ### 2. 02_pw + - **System**: Diamond (C) - **Basis**: Plane wave (PW) - **Purpose**: Demonstrates Wannier90 calculation using plane wave basis set - **Input Files**: Similar to 01_lcao, but configured for plane wave basis ### 3. 03_lcao_in_pw + - **System**: Diamond (C) - **Basis**: LCAO in plane wave mode - **Purpose**: Demonstrates Wannier90 calculation using LCAO basis set in plane wave mode - **Input Files**: Similar to 01_lcao, but configured for LCAO in plane wave mode # How to Use abacusw90 + ## Installation + ```bash pip install . # Or for development pip install -e . ``` + ## Workflow Scope -This interface automates the technical coupling steps between ABACUS and Wannier90. In the context of the standard tutorial workflow, it covers the following stages: -| Step | Description | Responsibility | -| :--- | :--- | :--- | -| **Automated** | **Step 1**: ABACUS SCF Calculation | **Interface Step 0** | -| **Prerequisite** | **Step 2**: Determine Energy Windows | User provides `dis_win` parameters | -| **Automated** | **Step 3**: Generate `wannier90.win` & Run `-pp` | **Interface Step 1** | -| **Automated** | **Step 4**: ABACUS NSCF (Interface Mode) | **Interface Step 2 & 3** | -| **Automated** | **Step 5**: Wannier90 Minimization | **Interface Step 4** | -| **Post-process** | **Step 6**: WannierTools Analysis | User (Downstream tool) | + +This interface automates the technical coupling steps between ABACUS and Wannier90. In the context +of the standard tutorial workflow, it covers the following stages: + +| Step | Description | Responsibility | +| :--------------- | :----------------------------------------------- | :--------------------------------- | +| **Automated** | **Step 1**: ABACUS SCF Calculation | **Interface Step 0** | +| **Prerequisite** | **Step 2**: Determine Energy Windows | User provides `dis_win` parameters | +| **Automated** | **Step 3**: Generate `wannier90.win` & Run `-pp` | **Interface Step 1** | +| **Automated** | **Step 4**: ABACUS NSCF (Interface Mode) | **Interface Step 2 & 3** | +| **Automated** | **Step 5**: Wannier90 Minimization | **Interface Step 4** | +| **Post-process** | **Step 6**: WannierTools Analysis | User (Downstream tool) | + ## Quick Start + Here is an example of generating Wannier functions for Bi2Se3: + ```python from abacusw90 import ABACUSWannier90 # 1. Initialize @@ -115,13 +136,19 @@ job.run() ``` ## Detailed Workflow Steps + The `run()` method executes the following automated sequence: -1. **Generate Inputs & Preprocess**: Write `wannier90.win` and execute `wannier90 -pp` to generate `.nnkp`. -2. **Prepare ABACUS**: Parse `.nnkp` to generate ABACUS `KPT`, `INPUT`, and `STRU` files. Copy SCF charge densities. -3. **Run ABACUS Interface**: Execute ABACUS in NSCF mode with `towannier90=1`. This generates `mmn`, `amn`, `eig` files. -4. **Run Wannier90**: Execute `wannier90.x` to compute MLWFs and output `wannier90_hr.dat`. + +1. **Generate Inputs & Preprocess**: Write `wannier90.win` and execute `wannier90 -pp` to generate + `.nnkp`. +1. **Prepare ABACUS**: Parse `.nnkp` to generate ABACUS `KPT`, `INPUT`, and `STRU` files. Copy SCF + charge densities. +1. **Run ABACUS Interface**: Execute ABACUS in NSCF mode with `towannier90=1`. This generates `mmn`, + `amn`, `eig` files. +1. **Run Wannier90**: Execute `wannier90.x` to compute MLWFs and output `wannier90_hr.dat`. ## Requirements + - **ABACUS**: v3.0 or higher (with Wannier90 interface support). - **Wannier90**: v3.0 or higher. - **Python**: 3.8+ @@ -129,13 +156,17 @@ The `run()` method executes the following automated sequence: # Important Notes - The k-point grid in the ABACUS NSCF calculation must match the one in the Wannier90 input file -- Set `wvfn_formatted = .true.` in the Wannier90 input file to ensure compatibility with ABACUS output -- For LCAO calculations, ensure that the orbital basis set is appropriate for the Wannier functions you want to generate +- Set `wvfn_formatted = .true.` in the Wannier90 input file to ensure compatibility with ABACUS + output +- For LCAO calculations, ensure that the orbital basis set is appropriate for the Wannier functions + you want to generate # Troubleshooting -- **Files not found**: Ensure ABACUS is generating `*.amn`, `*.mmn`, and `UNK*` files in the OUT.* directory -- **Wannier90 cannot read ABACUS output**: Check that `wvfn_formatted = .true.` is set in the Wannier90 input file +- **Files not found**: Ensure ABACUS is generating `*.amn`, `*.mmn`, and `UNK*` files in the OUT.\* + directory +- **Wannier90 cannot read ABACUS output**: Check that `wvfn_formatted = .true.` is set in the + Wannier90 input file - **Convergence issues**: Ensure the SCF and NSCF calculations are properly converged # References diff --git a/interfaces/Wannier90_interface/abacusw90/README.md b/interfaces/Wannier90_interface/abacusw90/README.md index ff2ba9e71ae..e69ab7431ed 100644 --- a/interfaces/Wannier90_interface/abacusw90/README.md +++ b/interfaces/Wannier90_interface/abacusw90/README.md @@ -1,9 +1,13 @@ # A Brief Introduction to ABACUS Wannier90 Interface -This package provides a user-friendly Python interface: abacusw90 to bridge **ABACUS** (Atomic-scale Simulation Package) with **Wannier90**. It automates the workflow of generating Maximally Localized Wannier Functions (MLWFs) and tight-binding models from ABACUS calculations. + +This package provides a user-friendly Python interface: abacusw90 to bridge **ABACUS** (Atomic-scale +Simulation Package) with **Wannier90**. It automates the workflow of generating Maximally Localized +Wannier Functions (MLWFs) and tight-binding models from ABACUS calculations. ## What is Wannier90? -Wannier90 is an open-source code that calculates maximally localized Wannier functions (MLWFs) from first-principles calculations. It is designed to: +Wannier90 is an open-source code that calculates maximally localized Wannier functions (MLWFs) from +first-principles calculations. It is designed to: - Generate maximally localized Wannier functions - Calculate band structures and density of states @@ -12,6 +16,7 @@ Wannier90 is an open-source code that calculates maximally localized Wannier fun - Support various first-principles calculation codes through interfaces Wannier functions are particularly useful for: + - Electronic structure calculations - Transport properties - Spectroscopy calculations @@ -26,17 +31,22 @@ The abacusw90 package allows ABACUS to generate the necessary files for Wannier9 - `UNK*` files: Bloch wavefunctions ## Key features + - **Various Basis Sets**: Support for both plane wave (PW) and LCAO basis sets. -- **Automated Workflow**: Handles the core coupling pipeline (Steps 3-5 of the standard tutorial workflow). +- **Automated Workflow**: Handles the core coupling pipeline (Steps 3-5 of the standard tutorial + workflow). - **Input Generation**: Automatically generates `wannier90.win`, `INPUT`, `KPT`, and `STRU` files. -- **Method Support**: Supports the recommended `wannier_method = 2` for efficient overlap matrix calculation. +- **Method Support**: Supports the recommended `wannier_method = 2` for efficient overlap matrix + calculation. - **Spin-Orbit Coupling**: Full support for SOC calculations (`nspin=4`, `lspinorb=1`). ## Examples -This directory contains three examples demonstrating different use cases of the ABACUS-Wannier90 interface: +This directory contains three examples demonstrating different use cases of the ABACUS-Wannier90 +interface: ### 1. 01_lcao + - **System**: Diamond (C) - **Basis**: LCAO (Linear Combination of Atomic Orbitals) - **Purpose**: Demonstrates Wannier90 calculation using LCAO basis set @@ -50,36 +60,47 @@ This directory contains three examples demonstrating different use cases of the - `diamond.nnkp`: Wannier90 preprocessing file ### 2. 02_pw + - **System**: Diamond (C) - **Basis**: Plane wave (PW) - **Purpose**: Demonstrates Wannier90 calculation using plane wave basis set - **Input Files**: Similar to 01_lcao, but configured for plane wave basis ### 3. 03_lcao_in_pw + - **System**: Diamond (C) - **Basis**: LCAO in plane wave mode - **Purpose**: Demonstrates Wannier90 calculation using LCAO basis set in plane wave mode - **Input Files**: Similar to 01_lcao, but configured for LCAO in plane wave mode # How to Use abacusw90 + ## Installation + ```bash pip install . # Or for development pip install -e . ``` + ## Workflow Scope -This interface automates the technical coupling steps between ABACUS and Wannier90. In the context of the standard tutorial workflow, it covers the following stages: -| Step | Description | Responsibility | -| :--- | :--- | :--- | -| **Automated** | **Step 1**: ABACUS SCF Calculation | **Interface Step 0** | -| **Prerequisite** | **Step 2**: Determine Energy Windows | User provides `dis_win` parameters | -| **Automated** | **Step 3**: Generate `wannier90.win` & Run `-pp` | **Interface Step 1** | -| **Automated** | **Step 4**: ABACUS NSCF (Interface Mode) | **Interface Step 2 & 3** | -| **Automated** | **Step 5**: Wannier90 Minimization | **Interface Step 4** | -| **Post-process** | **Step 6**: WannierTools Analysis | User (Downstream tool) | + +This interface automates the technical coupling steps between ABACUS and Wannier90. In the context +of the standard tutorial workflow, it covers the following stages: + +| Step | Description | Responsibility | +| :--------------- | :----------------------------------------------- | :--------------------------------- | +| **Automated** | **Step 1**: ABACUS SCF Calculation | **Interface Step 0** | +| **Prerequisite** | **Step 2**: Determine Energy Windows | User provides `dis_win` parameters | +| **Automated** | **Step 3**: Generate `wannier90.win` & Run `-pp` | **Interface Step 1** | +| **Automated** | **Step 4**: ABACUS NSCF (Interface Mode) | **Interface Step 2 & 3** | +| **Automated** | **Step 5**: Wannier90 Minimization | **Interface Step 4** | +| **Post-process** | **Step 6**: WannierTools Analysis | User (Downstream tool) | + ## Quick Start + Here is an example of generating Wannier functions for Bi2Se3: + ```python from abacusw90 import ABACUSWannier90 # 1. Initialize @@ -115,13 +136,19 @@ job.run() ``` ## Detailed Workflow Steps + The `run()` method executes the following automated sequence: -1. **Generate Inputs & Preprocess**: Write `wannier90.win` and execute `wannier90 -pp` to generate `.nnkp`. -2. **Prepare ABACUS**: Parse `.nnkp` to generate ABACUS `KPT`, `INPUT`, and `STRU` files. Copy SCF charge densities. -3. **Run ABACUS Interface**: Execute ABACUS in NSCF mode with `towannier90=1`. This generates `mmn`, `amn`, `eig` files. -4. **Run Wannier90**: Execute `wannier90.x` to compute MLWFs and output `wannier90_hr.dat`. + +1. **Generate Inputs & Preprocess**: Write `wannier90.win` and execute `wannier90 -pp` to generate + `.nnkp`. +1. **Prepare ABACUS**: Parse `.nnkp` to generate ABACUS `KPT`, `INPUT`, and `STRU` files. Copy SCF + charge densities. +1. **Run ABACUS Interface**: Execute ABACUS in NSCF mode with `towannier90=1`. This generates `mmn`, + `amn`, `eig` files. +1. **Run Wannier90**: Execute `wannier90.x` to compute MLWFs and output `wannier90_hr.dat`. ## Requirements + - **ABACUS**: v3.0 or higher (with Wannier90 interface support). - **Wannier90**: v3.0 or higher. - **Python**: 3.8+ @@ -129,13 +156,17 @@ The `run()` method executes the following automated sequence: # Important Notes - The k-point grid in the ABACUS NSCF calculation must match the one in the Wannier90 input file -- Set `wvfn_formatted = .true.` in the Wannier90 input file to ensure compatibility with ABACUS output -- For LCAO calculations, ensure that the orbital basis set is appropriate for the Wannier functions you want to generate +- Set `wvfn_formatted = .true.` in the Wannier90 input file to ensure compatibility with ABACUS + output +- For LCAO calculations, ensure that the orbital basis set is appropriate for the Wannier functions + you want to generate # Troubleshooting -- **Files not found**: Ensure ABACUS is generating `*.amn`, `*.mmn`, and `UNK*` files in the OUT.* directory -- **Wannier90 cannot read ABACUS output**: Check that `wvfn_formatted = .true.` is set in the Wannier90 input file +- **Files not found**: Ensure ABACUS is generating `*.amn`, `*.mmn`, and `UNK*` files in the OUT.\* + directory +- **Wannier90 cannot read ABACUS output**: Check that `wvfn_formatted = .true.` is set in the + Wannier90 input file - **Convergence issues**: Ensure the SCF and NSCF calculations are properly converged # References diff --git a/python/pyabacus/CONTRIBUTING.md b/python/pyabacus/CONTRIBUTING.md index 68ff772db67..b981df4d36c 100644 --- a/python/pyabacus/CONTRIBUTING.md +++ b/python/pyabacus/CONTRIBUTING.md @@ -2,9 +2,12 @@ ## Introduction -Welcome to the `pyabacus` project! This document provides guidelines and instructions for developers who want to contribute to this project. +Welcome to the `pyabacus` project! This document provides guidelines and instructions for developers +who want to contribute to this project. -`pyabacus` is a Python interface for the ABACUS package. It provides a high-level Python API for interacting with the ABACUS library, allowing users to perform electronic structure calculations and analyze the results using Python. +`pyabacus` is a Python interface for the ABACUS package. It provides a high-level Python API for +interacting with the ABACUS library, allowing users to perform electronic structure calculations and +analyze the results using Python. @@ -18,13 +21,17 @@ Welcome to the `pyabacus` project! This document provides guidelines and instruc -**If you are new to the project**, please refer to the [README.md](./README.md) file for an overview of the project and its goals. +**If you are new to the project**, please refer to the [README.md](./README.md) file for an overview +of the project and its goals. -**If you are already familiar with the project and want to contribute**, this guide will help you understand the project structure, development process, and best practices for contributing code. +**If you are already familiar with the project and want to contribute**, this guide will help you +understand the project structure, development process, and best practices for contributing code. -**If you have any questions or need help**, feel free to reach out to the maintainers or create an issue in the repository. +**If you have any questions or need help**, feel free to reach out to the maintainers or create an +issue in the repository. -**Please feel free to contribute to this guide** by submitting a pull request with any improvements or additional information. +**Please feel free to contribute to this guide** by submitting a pull request with any improvements +or additional information. Let's get started! @@ -45,11 +52,16 @@ pyabacus/ โ””โ”€โ”€ CMakeLists.txt ``` -Our project is built using [pybind11](http://github.com/pybind/pybind11) and [scikit-build-core](https://scikit-build-core.readthedocs.io/) for facilitating the `CMake` build toolchain. So the `CMakeLists.txt` configuration is the key to thoroughly understanding the project structure. +Our project is built using [pybind11](http://github.com/pybind/pybind11) and +[scikit-build-core](https://scikit-build-core.readthedocs.io/) for facilitating the `CMake` build +toolchain. So the `CMakeLists.txt` configuration is the key to thoroughly understanding the project +structure. ### Root CMake Configuration -The `CMakeLists.txt` in root directory is the main configuration file for the pyabacus project. It sets up the project, finds necessary dependencies, configures build options, and includes subdirectories for different modules. Below is a detailed explanation of each section of the file: +The `CMakeLists.txt` in root directory is the main configuration file for the pyabacus project. It +sets up the project, finds necessary dependencies, configures build options, and includes +subdirectories for different modules. Below is a detailed explanation of each section of the file: ```cmake cmake_minimum_required(VERSION 3.15...3.26) @@ -60,14 +72,18 @@ project( VERSION ${SKBUILD_PROJECT_VERSION} LANGUAGES CXX) ``` -- This section sets the project name, version, and the programming languages used (C++ in this case). The project name and version are obtained from the `SKBUILD_PROJECT_NAME` and `SKBUILD_PROJECT_VERSION` variables, respectively. + +- This section sets the project name, version, and the programming languages used (C++ in this + case). The project name and version are obtained from the `SKBUILD_PROJECT_NAME` and + `SKBUILD_PROJECT_VERSION` variables, respectively. ```cmake # Find Python and pybind11 find_package(Python REQUIRED COMPONENTS Interpreter Development.Module) find_package(pybind11 CONFIG REQUIRED) ``` -- This section finds the required Python and pybind11 packages. + +- This section finds the required Python and pybind11 packages. ```cmake # Set source path @@ -81,7 +97,9 @@ list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/../../cmake" "${PROJECT_SOURCE_DIR}/../../cmake/modules") ``` -- This section sets various source paths and configuration options. It defines the paths to different modules and appends the custom CMake module path. + +- This section sets various source paths and configuration options. It defines the paths to + different modules and appends the custom CMake module path. ```cmake # Add math_libs @@ -126,7 +144,10 @@ else() endif() endif() ``` -- This section configures the math libraries. It checks for the presence of the Intel Math Kernel Library (MKL) and configures it if available. If MKL is not available, it falls back to using FFTW3 and LAPACK. It also configures MPI and OpenMP if enabled. + +- This section configures the math libraries. It checks for the presence of the Intel Math Kernel + Library (MKL) and configures it if available. If MKL is not available, it falls back to using + FFTW3 and LAPACK. It also configures MPI and OpenMP if enabled. ```cmake # Add include directories @@ -136,6 +157,7 @@ include_directories( ${ABACUS_SOURCE_DIR}/source_base/module_container ) ``` + - This section adds the necessary include directories for the project. ```cmake @@ -151,7 +173,9 @@ add_subdirectory(${ABACUS_SOURCE_DIR}/source_io/module_parameter ${PARAMETER_BIN set(ORB_BINARY_DIR "${PROJECT_SOURCE_DIR}/build/orb") add_subdirectory(${ABACUS_SOURCE_DIR}/source_basis/module_ao ${ORB_BINARY_DIR}) ``` -- This section sets the position-independent code flag and adds subdirectories for the base, parameter, and orb modules. It specifies the build directories for these modules. + +- This section sets the position-independent code flag and adds subdirectories for the base, + parameter, and orb modules. It specifies the build directories for these modules. ```cmake # Set RPATH @@ -161,14 +185,19 @@ execute_process( OUTPUT_STRIP_TRAILING_WHITESPACE ) ``` -- This section sets the runtime search path (RPATH) for the Python site-packages directory. It uses a Python command to get the site-packages path and stores it in the `PYTHON_SITE_PACKAGES` variable. + +- This section sets the runtime search path (RPATH) for the Python site-packages directory. It uses + a Python command to get the site-packages path and stores it in the `PYTHON_SITE_PACKAGES` + variable. ```cmake # Set package name to pyabacus set(TARGET_PACK pyabacus) set(CMAKE_INSTALL_RPATH "${PYTHON_SITE_PACKAGES}/${TARGET_PACK}") ``` -- This section sets the package name to `pyabacus` and configures the install RPATH to include the Python site-packages directory. + +- This section sets the package name to `pyabacus` and configures the install RPATH to include the + Python site-packages directory. ```cmake # Add subdirectories for submodules @@ -176,9 +205,13 @@ add_subdirectory(${PROJECT_SOURCE_DIR}/src/hsolver) add_subdirectory(${PROJECT_SOURCE_DIR}/src/ModuleBase) add_subdirectory(${PROJECT_SOURCE_DIR}/src/ModuleNAO) ``` -- This section adds subdirectories for modules. Each subdirectory contains its own `CMakeLists.txt` for further configuration. -By following this structure, the `CMakeLists.txt` file ensures that all necessary dependencies are found, configured, and included in the build process. It also sets up the project environment and includes submodules for different components of the `pyabacus` project. +- This section adds subdirectories for modules. Each subdirectory contains its own `CMakeLists.txt` + for further configuration. + +By following this structure, the `CMakeLists.txt` file ensures that all necessary dependencies are +found, configured, and included in the build process. It also sets up the project environment and +includes submodules for different components of the `pyabacus` project. ### Module CMake Configuration @@ -228,26 +261,35 @@ set_target_properties(_hsolver_pack PROPERTIES INSTALL_RPATH "$ORIGIN") install(TARGETS _hsolver_pack diagopack DESTINATION ${TARGET_PACK}/hsolver) ``` -You can refer to the `CMakeLists.txt` files in other modules for guidance on how to configure your module. +You can refer to the `CMakeLists.txt` files in other modules for guidance on how to configure your +module. ## Development Process To contribute to the `pyabacus` project, follow these steps: -1. **Check the issues**: - - Look for issues to ensure that you are not working on something that is already in progress. - - If you want to work on a new feature or bug fix, create an issue first to discuss it with the maintainers. +1. **Check the issues**: + + - Look for issues to ensure that you are not working on something that is already in progress. + - If you want to work on a new feature or bug fix, create an issue first to discuss it with the + maintainers. + +1. **Create a new folder for your module**: + + - If you want to add a new module with pure Python code, create a new folder in the + `src/pyabacus` directory. + - If you want to add a new module with C++ code, create a new folder in the `src` directory and a + corresponding directory in the `src/pyabacus` directory. -2. **Create a new folder for your module**: - - If you want to add a new module with pure Python code, create a new folder in the `src/pyabacus` directory. - - If you want to add a new module with C++ code, create a new folder in the `src` directory and a corresponding directory in the `src/pyabacus` directory. +1. **Write source code using pybind11**: -3. **Write source code using pybind11**: - Follow the structure of other modules. - Manage dependencies and installation paths in the `CMakeLists.txt` file. -3. **Modify `src/pyabacus/__init__.py`**: - - Add the name of your module to the `__submodules__` list and import the module in the `__getattr__` function. +1. **Modify `src/pyabacus/__init__.py`**: + + - Add the name of your module to the `__submodules__` list and import the module in the + `__getattr__` function. ```python from __future__ import annotations @@ -273,7 +315,8 @@ To contribute to the `pyabacus` project, follow these steps: raise AttributeError(f"module {__name__} has no attribute {attr}") ``` -4. **Create two files in `src/pyabacus/{module_name}`**: +1. **Create two files in `src/pyabacus/{module_name}`**: + - `__init__.py`: This file allows Python to recognize the folder as a module. - `_{module_name}.py`: This file is responsible for designing the Python interface (frontend). @@ -307,10 +350,14 @@ To contribute to the `pyabacus` project, follow these steps: super().bar(arg1, arg2, ...) ``` - For a class, if you do not declare the interface in the frontend, the IDE will not provide type hints and auto-completion. However, if the interface name matches the name binding in pybind11, it will be overridden. To address this, you can use the method as shown above. + For a class, if you do not declare the interface in the frontend, the IDE will not provide type + hints and auto-completion. However, if the interface name matches the name binding in pybind11, + it will be overridden. To address this, you can use the method as shown above. + +1. **Handle overloaded functions in C++**: -5. **Handle overloaded functions in C++**: - - Since Python does not support function overloading with different parameters, use the following method: + - Since Python does not support function overloading with different parameters, use the following + method: ```python @overload @@ -324,60 +371,62 @@ To contribute to the `pyabacus` project, follow these steps: **Example Python Interface**: - ```python - class diag_comm_info(_diag_comm_info): - def __init__(self, rank: int, nproc: int): - super().__init__(rank, nproc) - - @property - def rank(self) -> int: - return super().rank - - @property - def nproc(self) -> int: - return super().nproc - - class Sphbes(_Sphbes): - def __init__(self) -> None: - super().__init__() - - @overload - @staticmethod - def sphbesj(l: int, x: float) -> float: ... - @overload - @staticmethod - def sphbesj( - n: int, - r: NDArray[np.float64], - q: int, - l: int, - jl: NDArray[np.float64] - ) -> None: ... - - def sphbesj(self, *args, **kwargs): - return super().sphbesj(*args, **kwargs) - - @overload - @staticmethod - def dsphbesj(l: int, x: float) -> float: ... - @overload - @staticmethod - def dsphbesj( - n: int, - r: NDArray[np.float64], - q: int, - l: int, - djl: NDArray[np.float64] - ) -> None: ... - - def dsphbesj(self, *args, **kwargs): - return super().dsphbesj(*args, **kwargs) - - @staticmethod - def sphbes_zeros(l: int, n: int, zeros: NDArray[np.float64]) -> None: - _Sphbes.sphbes_zeros(l, n, zeros) - ``` +```python +class diag_comm_info(_diag_comm_info): + def __init__(self, rank: int, nproc: int): + super().__init__(rank, nproc) + + @property + def rank(self) -> int: + return super().rank + + @property + def nproc(self) -> int: + return super().nproc + +class Sphbes(_Sphbes): + def __init__(self) -> None: + super().__init__() + + @overload + @staticmethod + def sphbesj(l: int, x: float) -> float: ... + @overload + @staticmethod + def sphbesj( + n: int, + r: NDArray[np.float64], + q: int, + l: int, + jl: NDArray[np.float64] + ) -> None: ... + + def sphbesj(self, *args, **kwargs): + return super().sphbesj(*args, **kwargs) + + @overload + @staticmethod + def dsphbesj(l: int, x: float) -> float: ... + @overload + @staticmethod + def dsphbesj( + n: int, + r: NDArray[np.float64], + q: int, + l: int, + djl: NDArray[np.float64] + ) -> None: ... + + def dsphbesj(self, *args, **kwargs): + return super().dsphbesj(*args, **kwargs) + + @staticmethod + def sphbes_zeros(l: int, n: int, zeros: NDArray[np.float64]) -> None: + _Sphbes.sphbes_zeros(l, n, zeros) +``` ## Conclusion -By following this guide, you can effectively contribute to the `pyabacus` project. Ensure that you follow the structure and conventions outlined here to maintain consistency and readability in the codebase. Happy coding! +By following this guide, you can effectively contribute to the `pyabacus` project. Ensure that you +follow the structure and conventions outlined here to maintain consistency and readability in the +codebase. Happy coding! diff --git a/python/pyabacus/README.md b/python/pyabacus/README.md index 5634bf8cf25..651e11efdad 100644 --- a/python/pyabacus/README.md +++ b/python/pyabacus/README.md @@ -1,10 +1,14 @@ # pyabacus: a Python interface for the ABACUS package -`pyabacus` is a Python interface for the ABACUS package, which provides a high-level Python API for interacting with the `ABACUS` library. +`pyabacus` is a Python interface for the ABACUS package, which provides a high-level Python API for +interacting with the `ABACUS` library. -This project is built using [pybind11](http://github.com/pybind/pybind11) and [scikit-build-core](https://scikit-build-core.readthedocs.io/), so you can easily build the project and use it in your Python environment. +This project is built using [pybind11](http://github.com/pybind/pybind11) and +[scikit-build-core](https://scikit-build-core.readthedocs.io/), so you can easily build the project +and use it in your Python environment. Now, `pyabacus` provides the following modules: + - `io`: a module for input/output in pyabacus. - `Cell`: a module for the cell structure to bridge `ModuleNAO` in python module with users' input. - `ModuleBase`: a module for basic math functions. @@ -22,15 +26,17 @@ Now, `pyabacus` provides the following modules: ## Installation -- Create and activate a new conda env, e.g. `conda create -n myenv python=3.8 & conda activate myenv`. +- Create and activate a new conda env, e.g. + `conda create -n myenv python=3.8 & conda activate myenv`. - Clone ABACUS main repository and `cd abacus-develop/python/pyabacus`. -- Build pyabacus by `pip install -v .` or install test dependencies & build pyabacus by `pip install .[test]`. (Use `pip install -v .[test] -i https://pypi.tuna.tsinghua.edu.cn/simple` to accelerate installation process.) +- Build pyabacus by `pip install -v .` or install test dependencies & build pyabacus by + `pip install .[test]`. (Use `pip install -v .[test] -i https://pypi.tuna.tsinghua.edu.cn/simple` + to accelerate installation process.) ## CI Examples -There are examples for CI in `.github/workflows`. A simple way to produces -binary "wheels" for all platforms is illustrated in the "wheels.yml" file, -using . +There are examples for CI in `.github/workflows`. A simple way to produces binary "wheels" for all +platforms is illustrated in the "wheels.yml" file, using . Use `pytest -v` to run all the unit tests for pyabacus in the local machine. @@ -86,9 +92,9 @@ eigenvalues difference: ## License -pybind11 is provided under a BSD-style license that can be found in the LICENSE -file. By using, distributing, or contributing to this project, you agree to the -terms and conditions of this license. +pybind11 is provided under a BSD-style license that can be found in the LICENSE file. By using, +distributing, or contributing to this project, you agree to the terms and conditions of this +license. ## Test call @@ -98,5 +104,3 @@ s = m.ModuleBase.Sphbes() s.sphbesj(1, 0.0) 0.0 ``` - -[`cibuildwheel`]: https://cibuildwheel.readthedocs.io diff --git a/source/source_base/libm/README.md b/source/source_base/libm/README.md index 3b485187d8d..6a7c31b9b54 100644 --- a/source/source_base/libm/README.md +++ b/source/source_base/libm/README.md @@ -1,7 +1,9 @@ # Math fucntions source code -These math functions is ported form glibc-2.36/math (https://github.com/bminor/glibc/tree/release/2.36/master/math) +These math functions is ported form glibc-2.36/math +(https://github.com/bminor/glibc/tree/release/2.36/master/math) The new version of sin/cos/exp implementation is much faster than glibc-2.27. -In order to avoid the performance impact of different versions of glibc installed on systems and different versions of math functions provided by compilers, we choose to migrate these source codes. +In order to avoid the performance impact of different versions of glibc installed on systems and +different versions of math functions provided by compilers, we choose to migrate these source codes. diff --git a/tests/01_PW/scf_pcc_0d/README.md b/tests/01_PW/scf_pcc_0d/README.md index 2be075dd83d..3aaf0e75c5f 100644 --- a/tests/01_PW/scf_pcc_0d/README.md +++ b/tests/01_PW/scf_pcc_0d/README.md @@ -1,5 +1,5 @@ Vacuum PCC 0D regression for charged H3O with `assume_isolated pcc_0d`. -The integration harness compares total energy, ionic force magnitudes and `E_pcc` -(in eV). References use the repository pseudopotentials, `scf_thr 1e-12`, -two MPI ranks and one OpenMP thread per rank. +The integration harness compares total energy, ionic force magnitudes and `E_pcc` (in eV). +References use the repository pseudopotentials, `scf_thr 1e-12`, two MPI ranks and one OpenMP thread +per rank. diff --git a/tests/01_PW/scf_pcc_2d/README.md b/tests/01_PW/scf_pcc_2d/README.md index 635d18e9523..3845d8bca13 100644 --- a/tests/01_PW/scf_pcc_2d/README.md +++ b/tests/01_PW/scf_pcc_2d/README.md @@ -1,6 +1,6 @@ -Vacuum PCC 2D regression for a charged H3O periodic layer with -`assume_isolated pcc_2d` and open axis 2 (`pcc_2d_axis 2`). +Vacuum PCC 2D regression for a charged H3O periodic layer with `assume_isolated pcc_2d` and open +axis 2 (`pcc_2d_axis 2`). -The integration harness compares total energy, ionic force magnitudes and `E_pcc` -(in eV). References use the repository pseudopotentials, `scf_thr 1e-12`, -two MPI ranks and one OpenMP thread per rank. +The integration harness compares total energy, ionic force magnitudes and `E_pcc` (in eV). +References use the repository pseudopotentials, `scf_thr 1e-12`, two MPI ranks and one OpenMP thread +per rank. diff --git a/tests/02_NAO_Gamma/scf_pcc0d_water/README.md b/tests/02_NAO_Gamma/scf_pcc0d_water/README.md index 218f62738eb..a5309ef370d 100644 --- a/tests/02_NAO_Gamma/scf_pcc0d_water/README.md +++ b/tests/02_NAO_Gamma/scf_pcc0d_water/README.md @@ -1,7 +1,6 @@ Vacuum PCC 0D regression with `assume_isolated pcc_0d`. -The integration harness compares total energy, ionic force magnitudes and `E_pcc` -(in eV). References were generated with two MPI ranks, one OpenMP thread and -the repository pseudopotentials/orbitals. Numerical kernels have independent -analytic and finite-difference unit tests; PW neutral/charged results were also -compared against the original full PCC implementation. +The integration harness compares total energy, ionic force magnitudes and `E_pcc` (in eV). +References were generated with two MPI ranks, one OpenMP thread and the repository +pseudopotentials/orbitals. Numerical kernels have independent analytic and finite-difference unit +tests; PW neutral/charged results were also compared against the original full PCC implementation. diff --git a/tests/02_NAO_Gamma/scf_pcc2d_water/README.md b/tests/02_NAO_Gamma/scf_pcc2d_water/README.md index 7924bf4081c..ecb22c4b824 100644 --- a/tests/02_NAO_Gamma/scf_pcc2d_water/README.md +++ b/tests/02_NAO_Gamma/scf_pcc2d_water/README.md @@ -1,6 +1,5 @@ -Standalone vacuum PCC 2D regression. Compare total energy, ionic forces -and E_pcc against a two-rank reference with one OpenMP thread. The PW case -checks a charged periodic layer with open axis 2; the LCAO case checks a -neutral water layer with open axis 1. Analytic sheet/dipole, normal-force and -electronic-potential derivative tests provide independent kernel references. -The saved original PCC executable was also used for numerical comparison. +Standalone vacuum PCC 2D regression. Compare total energy, ionic forces and E_pcc against a two-rank +reference with one OpenMP thread. The PW case checks a charged periodic layer with open axis 2; the +LCAO case checks a neutral water layer with open axis 1. Analytic sheet/dipole, normal-force and +electronic-potential derivative tests provide independent kernel references. The saved original PCC +executable was also used for numerical comparison. diff --git a/tests/17_DS_DFTU/README.md b/tests/17_DS_DFTU/README.md index 02b7d309526..5435a12092f 100644 --- a/tests/17_DS_DFTU/README.md +++ b/tests/17_DS_DFTU/README.md @@ -1,106 +1,107 @@ # 17_DS_DFTU โ€” DeltaSpin & DFT+U Integration Test Suite -This directory contains integration test cases for **DeltaSpin (spin-constrained DFT)** and **DFT+U** functionality in ABACUS, -covering LCAO and PW basis sets, collinear/noncollinear spin, DFT+U, DeltaSpin, and their combinations. +This directory contains integration test cases for **DeltaSpin (spin-constrained DFT)** and +**DFT+U** functionality in ABACUS, covering LCAO and PW basis sets, collinear/noncollinear spin, +DFT+U, DeltaSpin, and their combinations. ## Test List (47 cases) ### I. LCAO Spin (01-02) -| # | Test Case | Description | -|---|------|------| -| 01 | LCAO_SPIN_S2_Z | Verify basic SCF convergence of collinear spin with LCAO basis, serves as baseline for LCAO magnetic calculations | -| 02 | LCAO_SPIN_S4_XYZ | Verify basic SCF convergence of noncollinear spin with LCAO basis, covers LCAO noncollinear calculation path | +| # | Test Case | Description | +| --- | ---------------- | ----------------------------------------------------------------------------------------------------------------- | +| 01 | LCAO_SPIN_S2_Z | Verify basic SCF convergence of collinear spin with LCAO basis, serves as baseline for LCAO magnetic calculations | +| 02 | LCAO_SPIN_S4_XYZ | Verify basic SCF convergence of noncollinear spin with LCAO basis, covers LCAO noncollinear calculation path | ### II. LCAO DFT+U (03-05) -| # | Test Case | Description | -|---|------|------| -| 03 | LCAO_DFTU_S2_Z | Verify coupling of DFT+U (U=5.0eV, l=2) with collinear spin in LCAO basis, ensures correct DFT+U occupation matrix calculation in LCAO path | -| 04 | LCAO_DFTU_S4_XY | Verify coupling of DFT+U with noncollinear spin (XY magnetization) in LCAO basis, covers nspin=4 occupation matrix calculation in LCAO path | -| 05 | LCAO_DFTU_S4_XYZ | Verify coupling of DFT+U with noncollinear spin (XYZ magnetization) in LCAO basis, covers the most complete occupation matrix scenario in LCAO path | +| # | Test Case | Description | +| --- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| 03 | LCAO_DFTU_S2_Z | Verify coupling of DFT+U (U=5.0eV, l=2) with collinear spin in LCAO basis, ensures correct DFT+U occupation matrix calculation in LCAO path | +| 04 | LCAO_DFTU_S4_XY | Verify coupling of DFT+U with noncollinear spin (XY magnetization) in LCAO basis, covers nspin=4 occupation matrix calculation in LCAO path | +| 05 | LCAO_DFTU_S4_XYZ | Verify coupling of DFT+U with noncollinear spin (XYZ magnetization) in LCAO basis, covers the most complete occupation matrix scenario in LCAO path | ### III. PW Spin (06-07) -| # | Test Case | Description | -|---|------|------| -| 06 | PW_SPIN_S2_Z | Verify basic SCF convergence of collinear spin with PW basis, serves as baseline for PW magnetic calculations | -| 07 | PW_SPIN_S4_XYZ | Verify basic SCF convergence of noncollinear spin with PW basis, covers PW noncollinear calculation path | +| # | Test Case | Description | +| --- | -------------- | ------------------------------------------------------------------------------------------------------------- | +| 06 | PW_SPIN_S2_Z | Verify basic SCF convergence of collinear spin with PW basis, serves as baseline for PW magnetic calculations | +| 07 | PW_SPIN_S4_XYZ | Verify basic SCF convergence of noncollinear spin with PW basis, covers PW noncollinear calculation path | ### IV. PW DFT+U (08-09, 11) -| # | Test Case | Description | -|---|------|------| -| 08 | PW_DFTU_S2_Z | Verify coupling of DFT+U (U=5.0eV, l=2) with collinear spin in PW basis, ensures correct DFT+U effective potential calculation in PW path | -| 09 | PW_DFTU_S4_XY | Verify coupling of DFT+U with noncollinear spin (XY magnetization) in PW basis, covers onsite projection matrix for nspin=4 in PW path | -| 11 | PW_DFTU_S2_FeO | Verify correctness of DFT+U on FeO system with PW basis, ensures DFT+U correction for Fe-3d orbitals is effective | +| # | Test Case | Description | +| --- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| 08 | PW_DFTU_S2_Z | Verify coupling of DFT+U (U=5.0eV, l=2) with collinear spin in PW basis, ensures correct DFT+U effective potential calculation in PW path | +| 09 | PW_DFTU_S4_XY | Verify coupling of DFT+U with noncollinear spin (XY magnetization) in PW basis, covers onsite projection matrix for nspin=4 in PW path | +| 11 | PW_DFTU_S2_FeO | Verify correctness of DFT+U on FeO system with PW basis, ensures DFT+U correction for Fe-3d orbitals is effective | ### V. PW DeltaSpin (12, 14-16) -| # | Test Case | Description | -|---|------|------| -| 12 | PW_DS_S2_Z | Verify coupling of DeltaSpin with collinear spin in PW basis, ensures correct DeltaSpin iterative optimization of magnetization to target values | -| 14 | PW_DS_S4_XYZ | Verify iterative optimization of noncollinear DeltaSpin under XYZ three-direction magnetization constraint, covers the most complete spin constraint scenario | -| 15 | PW_DS_S4_Z | Verify behavior of noncollinear DeltaSpin when constraining only Z-direction magnetization, ensures uniaxial constraint does not introduce unphysical XY components in noncolin=1 framework | -| 16 | PW_DS_S4_XY | Verify iterative optimization of noncollinear DeltaSpin under XY magnetization constraint with a different crystal structure, verifies generalization of noncollinear DeltaSpin XY constraint under different lattices | +| # | Test Case | Description | +| --- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 12 | PW_DS_S2_Z | Verify coupling of DeltaSpin with collinear spin in PW basis, ensures correct DeltaSpin iterative optimization of magnetization to target values | +| 14 | PW_DS_S4_XYZ | Verify iterative optimization of noncollinear DeltaSpin under XYZ three-direction magnetization constraint, covers the most complete spin constraint scenario | +| 15 | PW_DS_S4_Z | Verify behavior of noncollinear DeltaSpin when constraining only Z-direction magnetization, ensures uniaxial constraint does not introduce unphysical XY components in noncolin=1 framework | +| 16 | PW_DS_S4_XY | Verify iterative optimization of noncollinear DeltaSpin under XY magnetization constraint with a different crystal structure, verifies generalization of noncollinear DeltaSpin XY constraint under different lattices | ### VI. PW DFT+U + DeltaSpin (18-19, 21) -| # | Test Case | Description | -|---|------|------| -| 18 | PW_DFTU_DS_S2_Z | Verify coupling of DFT+U with DeltaSpin combined (collinear spin) in PW basis, ensures U correction and magnetization constraint do not conflict | -| 19 | PW_DFTU_DS_S4_XY | Verify coupling of noncollinear DFT+U+DeltaSpin combined under XY magnetization constraint, covers joint iteration of both methods in nspin=4 path | -| 21 | PW_DFTU_DS_S4_Z | Verify behavior of noncollinear DFT+U+DeltaSpin combined when constraining only Z-direction magnetization, ensures correct superposition of uniaxial constraint with DFT+U effective potential | +| # | Test Case | Description | +| --- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 18 | PW_DFTU_DS_S2_Z | Verify coupling of DFT+U with DeltaSpin combined (collinear spin) in PW basis, ensures U correction and magnetization constraint do not conflict | +| 19 | PW_DFTU_DS_S4_XY | Verify coupling of noncollinear DFT+U+DeltaSpin combined under XY magnetization constraint, covers joint iteration of both methods in nspin=4 path | +| 21 | PW_DFTU_DS_S4_Z | Verify behavior of noncollinear DFT+U+DeltaSpin combined when constraining only Z-direction magnetization, ensures correct superposition of uniaxial constraint with DFT+U effective potential | ### VII. LCAO DeltaSpin (24, 26-28) -| # | Test Case | Description | -|---|------|------| -| 24 | LCAO_DS_S2_Z | Verify coupling of DeltaSpin with collinear spin in LCAO basis, ensures correct spin constraint optimization in LCAO density matrix path | -| 26 | LCAO_DS_S4_XYZ | Verify iterative optimization of noncollinear DeltaSpin under XYZ three-direction magnetization constraint in LCAO basis, covers the most complete constraint scenario in LCAO path | -| 27 | LCAO_DS_S4_Z | Verify behavior of noncollinear DeltaSpin when constraining only Z-direction magnetization in LCAO basis, ensures correctness of uniaxial constraint in noncolin=1 framework | -| 28 | LCAO_DS_S4_XY | Verify iterative optimization of noncollinear DeltaSpin under XY magnetization constraint in LCAO basis with a different crystal structure, verifies generalization of LCAO noncollinear DeltaSpin XY constraint under different lattices | +| # | Test Case | Description | +| --- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 24 | LCAO_DS_S2_Z | Verify coupling of DeltaSpin with collinear spin in LCAO basis, ensures correct spin constraint optimization in LCAO density matrix path | +| 26 | LCAO_DS_S4_XYZ | Verify iterative optimization of noncollinear DeltaSpin under XYZ three-direction magnetization constraint in LCAO basis, covers the most complete constraint scenario in LCAO path | +| 27 | LCAO_DS_S4_Z | Verify behavior of noncollinear DeltaSpin when constraining only Z-direction magnetization in LCAO basis, ensures correctness of uniaxial constraint in noncolin=1 framework | +| 28 | LCAO_DS_S4_XY | Verify iterative optimization of noncollinear DeltaSpin under XY magnetization constraint in LCAO basis with a different crystal structure, verifies generalization of LCAO noncollinear DeltaSpin XY constraint under different lattices | ### VIII. LCAO DFT+U + DeltaSpin (30-33) -| # | Test Case | Description | -|---|------|------| -| 30 | LCAO_DFTU_DS_S2_Z | Verify coupling of DFT+U with DeltaSpin combined (collinear spin) in LCAO basis, ensures U correction and magnetization constraint do not conflict in density matrix path | -| 31 | LCAO_DFTU_DS_S4_XY | Verify coupling of noncollinear DFT+U+DeltaSpin combined under XY magnetization constraint in LCAO basis, covers joint constraint in LCAO density matrix path | -| 32 | LCAO_DFTU_DS_S4_XYZ | Verify coupling of noncollinear DFT+U+DeltaSpin combined under XYZ three-direction magnetization constraint in LCAO basis, covers the most complete joint scenario in LCAO path | -| 33 | LCAO_DFTU_DS_S4_Z | Verify behavior of noncollinear DFT+U+DeltaSpin combined when constraining only Z-direction magnetization in LCAO basis, ensures correct superposition of uniaxial constraint with DFT+U density matrix | +| # | Test Case | Description | +| --- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 30 | LCAO_DFTU_DS_S2_Z | Verify coupling of DFT+U with DeltaSpin combined (collinear spin) in LCAO basis, ensures U correction and magnetization constraint do not conflict in density matrix path | +| 31 | LCAO_DFTU_DS_S4_XY | Verify coupling of noncollinear DFT+U+DeltaSpin combined under XY magnetization constraint in LCAO basis, covers joint constraint in LCAO density matrix path | +| 32 | LCAO_DFTU_DS_S4_XYZ | Verify coupling of noncollinear DFT+U+DeltaSpin combined under XYZ three-direction magnetization constraint in LCAO basis, covers the most complete joint scenario in LCAO path | +| 33 | LCAO_DFTU_DS_S4_Z | Verify behavior of noncollinear DFT+U+DeltaSpin combined when constraining only Z-direction magnetization in LCAO basis, ensures correct superposition of uniaxial constraint with DFT+U density matrix | ### IX. PW DeltaSpin Special Parameters (36-41) -| # | Test Case | Description | -|---|------|------| -| 36 | PW_DS_S2_ReadLam_Z | Verify correctness of `nsc=1` mode (read lambda file directly without iterative optimization), ensures DeltaSpin correctly computes magnetization in non-self-consistent lambda mode | -| 37 | PW_DS_S4_ReadLam_XY | Verify `nsc=1` mode for noncollinear DeltaSpin, covers non-self-consistent lambda path under XY magnetization constraint | -| 38 | PW_DS_S2_Thr1e10_Z | Verify stability of DeltaSpin under strict convergence threshold (sc_scf_thr=1e-10), ensures iterative optimization converges to high-precision solution | -| 39 | PW_DS_S4_Thr1e10_XY | Verify stability of noncollinear DeltaSpin under strict convergence threshold (sc_scf_thr=1e-10), covers XY magnetization constraint scenario | -| 40 | PW_DS_S2_Thr10_Z | Verify behavior of DeltaSpin under loose convergence threshold (sc_scf_thr=10), tests algorithm robustness and out_alllog log output under low precision requirements | -| 41 | PW_DS_S4_Thr10_XY | Verify behavior of noncollinear DeltaSpin under loose convergence threshold (sc_scf_thr=10), covers low precision scenario with XY magnetization constraint | +| # | Test Case | Description | +| --- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 36 | PW_DS_S2_ReadLam_Z | Verify correctness of `nsc=1` mode (read lambda file directly without iterative optimization), ensures DeltaSpin correctly computes magnetization in non-self-consistent lambda mode | +| 37 | PW_DS_S4_ReadLam_XY | Verify `nsc=1` mode for noncollinear DeltaSpin, covers non-self-consistent lambda path under XY magnetization constraint | +| 38 | PW_DS_S2_Thr1e10_Z | Verify stability of DeltaSpin under strict convergence threshold (sc_scf_thr=1e-10), ensures iterative optimization converges to high-precision solution | +| 39 | PW_DS_S4_Thr1e10_XY | Verify stability of noncollinear DeltaSpin under strict convergence threshold (sc_scf_thr=1e-10), covers XY magnetization constraint scenario | +| 40 | PW_DS_S2_Thr10_Z | Verify behavior of DeltaSpin under loose convergence threshold (sc_scf_thr=10), tests algorithm robustness and out_alllog log output under low precision requirements | +| 41 | PW_DS_S4_Thr10_XY | Verify behavior of noncollinear DeltaSpin under loose convergence threshold (sc_scf_thr=10), covers low precision scenario with XY magnetization constraint | ### X. PW DFT+U + DeltaSpin Special Parameters (42-45) -| # | Test Case | Description | -|---|------|------| -| 42 | PW_DFTU_DS_S2_Thr1e10_Z | Verify iterative stability of DFT+U with DeltaSpin combined under strict convergence threshold (sc_scf_thr=1e-10), ensures convergence when both methods are coupled | -| 43 | PW_DFTU_DS_S4_Thr1e10_XY | Verify coupling stability of noncollinear DFT+U+DeltaSpin under strict convergence threshold (sc_scf_thr=1e-10), covers XY magnetization constraint | -| 44 | PW_DFTU_DS_S2_Thr10_Z | Verify behavior of DFT+U with DeltaSpin combined under loose convergence threshold (sc_scf_thr=10), tests coupled algorithm robustness under low precision requirements | -| 45 | PW_DFTU_DS_S4_Thr10_XY | Verify behavior of noncollinear DFT+U+DeltaSpin under loose convergence threshold (sc_scf_thr=10), covers low precision scenario with XY magnetization constraint | +| # | Test Case | Description | +| --- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 42 | PW_DFTU_DS_S2_Thr1e10_Z | Verify iterative stability of DFT+U with DeltaSpin combined under strict convergence threshold (sc_scf_thr=1e-10), ensures convergence when both methods are coupled | +| 43 | PW_DFTU_DS_S4_Thr1e10_XY | Verify coupling stability of noncollinear DFT+U+DeltaSpin under strict convergence threshold (sc_scf_thr=1e-10), covers XY magnetization constraint | +| 44 | PW_DFTU_DS_S2_Thr10_Z | Verify behavior of DFT+U with DeltaSpin combined under loose convergence threshold (sc_scf_thr=10), tests coupled algorithm robustness under low precision requirements | +| 45 | PW_DFTU_DS_S4_Thr10_XY | Verify behavior of noncollinear DFT+U+DeltaSpin under loose convergence threshold (sc_scf_thr=10), covers low precision scenario with XY magnetization constraint | ### XI. FeO Atom Ordering (50-51) -| # | Test Case | Description | -|---|------|------| -| 50 | FeO_O_first_Fe_second | Verify correctness of DFT+U in FeO system with O atom type first and Fe second, ensures atom type ordering does not affect DFT+U onsite projection | -| 51 | FeO_Fe_first_O_second | Verify correctness of DFT+U in FeO system with Fe atom type first and O second, compare with 50 to ensure eff_pot_pw_index indexing is independent of atom type ordering | +| # | Test Case | Description | +| --- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 50 | FeO_O_first_Fe_second | Verify correctness of DFT+U in FeO system with O atom type first and Fe second, ensures atom type ordering does not affect DFT+U onsite projection | +| 51 | FeO_Fe_first_O_second | Verify correctness of DFT+U in FeO system with Fe atom type first and O second, compare with 50 to ensure eff_pot_pw_index indexing is independent of atom type ordering | ### XII. NSCF Mode (55, 60-64) -**Note:** These test cases have been converted to use a **SCF+NSCF workflow**. -The pre-converged charge density files have been removed. To run these tests: +**Note:** These test cases have been converted to use a **SCF+NSCF workflow**. The pre-converged +charge density files have been removed. To run these tests: ```bash # Use the workflow script (runs SCF first, then NSCF) @@ -108,29 +109,30 @@ cd tests/17_DS_DFTU/55_PW_DS_NSCF_S4_XY bash ../run_scf_nscf.sh 4 ``` -| # | Test Case | Description | -|---|------|------| -| 55 | PW_DS_NSCF_S4_XY | Verify DeltaSpin functionality in non-self-consistent (nscf) calculation mode, ensures lambda constraint is applied correctly without charge update | -| 60 | PW_DFTU_DS_NSCF_Band_XY | Verify DFT+U+DeltaSpin in NSCF band structure calculation, tests band output with spin constraints on high-symmetry k-point path | -| 61 | LCAO_DS_NSCF_S4_XY | Verify LCAO DeltaSpin functionality in nscf calculation mode | -| 62 | LCAO_DFTU_NSCF_Band_XY | Verify LCAO DFT+U (without DeltaSpin) in NSCF band structure calculation; note: runs as `calculation = scf` with `scf_nmax = 1` using pre-converged charge density | -| 63 | LCAO_DFTU_DS_NSCF_Band_XY | Verify LCAO DFT+U+DeltaSpin in NSCF band structure calculation, tests band output with spin constraints | -| 64 | PW_DFTU_NSCF_Band_XY | Verify DFT+U (without DeltaSpin) in NSCF band structure calculation, tests band output with Hubbard U correction | +| # | Test Case | Description | +| --- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 55 | PW_DS_NSCF_S4_XY | Verify DeltaSpin functionality in non-self-consistent (nscf) calculation mode, ensures lambda constraint is applied correctly without charge update | +| 60 | PW_DFTU_DS_NSCF_Band_XY | Verify DFT+U+DeltaSpin in NSCF band structure calculation, tests band output with spin constraints on high-symmetry k-point path | +| 61 | LCAO_DS_NSCF_S4_XY | Verify LCAO DeltaSpin functionality in nscf calculation mode | +| 62 | LCAO_DFTU_NSCF_Band_XY | Verify LCAO DFT+U (without DeltaSpin) in NSCF band structure calculation; note: runs as `calculation = scf` with `scf_nmax = 1` using pre-converged charge density | +| 63 | LCAO_DFTU_DS_NSCF_Band_XY | Verify LCAO DFT+U+DeltaSpin in NSCF band structure calculation, tests band output with spin constraints | +| 64 | PW_DFTU_NSCF_Band_XY | Verify DFT+U (without DeltaSpin) in NSCF band structure calculation, tests band output with Hubbard U correction | **SCF+NSCF Workflow:** + 1. `scf/INPUT` โ€” SCF input (calculation=scf, init_chg=atomic, out_chg=1) -2. `scf/STRU`, `scf/KPT` โ€” SCF structure and k-points -3. `run_scf_nscf.sh` โ€” Script that runs SCF, copies charge density, then runs NSCF -4. CI tests are **disabled** for these cases (see CASES_CPU.txt) +1. `scf/STRU`, `scf/KPT` โ€” SCF structure and k-points +1. `run_scf_nscf.sh` โ€” Script that runs SCF, copies charge density, then runs NSCF +1. CI tests are **disabled** for these cases (see CASES_CPU.txt) ### XIII. sc_direction_only Constraint (56-59) -| # | Test Case | Description | -|---|------|------| -| 56 | PW_DS_S4_DirectionOnly_XY | Verify `sc_direction_only=1` mode: only magnetization direction is constrained while magnitude is free to relax, projects lambda perpendicular to target direction | -| 57 | PW_DFTU_DS_S4_DirectionOnly_XY | Verify `sc_direction_only=1` combined with DFT+U, tests direction-only constraint superposition with Hubbard U correction | -| 58 | LCAO_DS_S4_DirectionOnly_XY | Verify `sc_direction_only=1` in LCAO basis, ensures direction-only constraint works correctly in LCAO density matrix path | -| 59 | LCAO_DFTU_DS_S4_DirectionOnly_XY | Verify `sc_direction_only=1` combined with DFT+U in LCAO basis, tests full direction-only constraint in LCAO path | +| # | Test Case | Description | +| --- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 56 | PW_DS_S4_DirectionOnly_XY | Verify `sc_direction_only=1` mode: only magnetization direction is constrained while magnitude is free to relax, projects lambda perpendicular to target direction | +| 57 | PW_DFTU_DS_S4_DirectionOnly_XY | Verify `sc_direction_only=1` combined with DFT+U, tests direction-only constraint superposition with Hubbard U correction | +| 58 | LCAO_DS_S4_DirectionOnly_XY | Verify `sc_direction_only=1` in LCAO basis, ensures direction-only constraint works correctly in LCAO density matrix path | +| 59 | LCAO_DFTU_DS_S4_DirectionOnly_XY | Verify `sc_direction_only=1` combined with DFT+U in LCAO basis, tests full direction-only constraint in LCAO path | ## Running Tests @@ -146,39 +148,48 @@ bash ../../integrate/run_debug.sh "" ## CI-Disabled Tests -The following test cases are disabled in `CASES_CPU.txt` (commented out with `#`) and excluded from CI testing due to **convergence and numerical stability issues**. They can be manually unskipped for local testing by removing the `#` prefix. - -| # | Test Case | Reason | -|---|------|--------| -| 02 | LCAO_SPIN_S4_XYZ | Convergence / numerical stability | -| 04 | LCAO_DFTU_S4_XY | Convergence / numerical stability | -| 05 | LCAO_DFTU_S4_XYZ | Convergence / numerical stability | -| 24 | LCAO_DS_S2_Z | Convergence / numerical stability | -| 26 | LCAO_DS_S4_XYZ | Convergence / numerical stability | -| 27 | LCAO_DS_S4_Z | Convergence / numerical stability | -| 28 | LCAO_DS_S4_XY | Convergence / numerical stability | -| 30 | LCAO_DFTU_DS_S2_Z | Convergence / numerical stability | -| 31 | LCAO_DFTU_DS_S4_XY | Convergence / numerical stability | -| 32 | LCAO_DFTU_DS_S4_XYZ | Convergence / numerical stability | -| 33 | LCAO_DFTU_DS_S4_Z | Convergence / numerical stability | -| 44 | PW_DFTU_DS_S2_Thr10_Z | Convergence / numerical stability | -| 58 | LCAO_DS_S4_DirectionOnly_XY | Convergence / numerical stability | -| 59 | LCAO_DFTU_DS_S4_DirectionOnly_XY | Convergence / numerical stability | -| 62 | LCAO_DFTU_NSCF_Band_XY | Convergence / numerical stability; genelpa eigenvalue inconsistency across thread counts (scalapack_gvx consistent); **also disabled for SCF+NSCF workflow conversion** | -| 63 | LCAO_DFTU_DS_NSCF_Band_XY | Convergence / numerical stability; **also disabled for SCF+NSCF workflow conversion** | -| 55 | PW_DS_NSCF_S4_XY | **Disabled for SCF+NSCF workflow conversion** โ€” run manually with `run_scf_nscf.sh` | -| 60 | PW_DFTU_DS_NSCF_Band_XY | **Disabled for SCF+NSCF workflow conversion** โ€” run manually with `run_scf_nscf.sh` | -| 61 | LCAO_DS_NSCF_S4_XY | **Disabled for SCF+NSCF workflow conversion** โ€” run manually with `run_scf_nscf.sh` | -| 64 | PW_DFTU_NSCF_Band_XY | **Disabled for SCF+NSCF workflow conversion** โ€” run manually with `run_scf_nscf.sh` | +The following test cases are disabled in `CASES_CPU.txt` (commented out with `#`) and excluded from +CI testing due to **convergence and numerical stability issues**. They can be manually unskipped for +local testing by removing the `#` prefix. + +| # | Test Case | Reason | +| --- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 02 | LCAO_SPIN_S4_XYZ | Convergence / numerical stability | +| 04 | LCAO_DFTU_S4_XY | Convergence / numerical stability | +| 05 | LCAO_DFTU_S4_XYZ | Convergence / numerical stability | +| 24 | LCAO_DS_S2_Z | Convergence / numerical stability | +| 26 | LCAO_DS_S4_XYZ | Convergence / numerical stability | +| 27 | LCAO_DS_S4_Z | Convergence / numerical stability | +| 28 | LCAO_DS_S4_XY | Convergence / numerical stability | +| 30 | LCAO_DFTU_DS_S2_Z | Convergence / numerical stability | +| 31 | LCAO_DFTU_DS_S4_XY | Convergence / numerical stability | +| 32 | LCAO_DFTU_DS_S4_XYZ | Convergence / numerical stability | +| 33 | LCAO_DFTU_DS_S4_Z | Convergence / numerical stability | +| 44 | PW_DFTU_DS_S2_Thr10_Z | Convergence / numerical stability | +| 58 | LCAO_DS_S4_DirectionOnly_XY | Convergence / numerical stability | +| 59 | LCAO_DFTU_DS_S4_DirectionOnly_XY | Convergence / numerical stability | +| 62 | LCAO_DFTU_NSCF_Band_XY | Convergence / numerical stability; genelpa eigenvalue inconsistency across thread counts (scalapack_gvx consistent); **also disabled for SCF+NSCF workflow conversion** | +| 63 | LCAO_DFTU_DS_NSCF_Band_XY | Convergence / numerical stability; **also disabled for SCF+NSCF workflow conversion** | +| 55 | PW_DS_NSCF_S4_XY | **Disabled for SCF+NSCF workflow conversion** โ€” run manually with `run_scf_nscf.sh` | +| 60 | PW_DFTU_DS_NSCF_Band_XY | **Disabled for SCF+NSCF workflow conversion** โ€” run manually with `run_scf_nscf.sh` | +| 61 | LCAO_DS_NSCF_S4_XY | **Disabled for SCF+NSCF workflow conversion** โ€” run manually with `run_scf_nscf.sh` | +| 64 | PW_DFTU_NSCF_Band_XY | **Disabled for SCF+NSCF workflow conversion** โ€” run manually with `run_scf_nscf.sh` | ## Test Condition Notes -- 09 (PW DFT+U + noncollinear): Only supports **2-process MPI** execution, `result.ref` reference files provided -- The following test cases set `kpar=2` in INPUT and require at least **2 MPI processes** to run: 11, 12, 14, 15, 16, 18, 19, 21, 37, 39, 41, 43, 45 -- 62 (LCAO_DFTU_NSCF_Band_XY): Single-thread and multi-thread results are inconsistent; investigation shows HR, HK, and SK are consistent across threads, but eigenvalues from genelpa differ; switching to scalapack_gvx produces consistent results across thread counts. Note: this test is named "NSCF" but actually runs with `calculation = scf` (`scf_nmax = 1`), using pre-shipped charge density and occ_mat.txt files as initial guess +- 09 (PW DFT+U + noncollinear): Only supports **2-process MPI** execution, `result.ref` reference + files provided +- The following test cases set `kpar=2` in INPUT and require at least **2 MPI processes** to run: + 11, 12, 14, 15, 16, 18, 19, 21, 37, 39, 41, 43, 45 +- 62 (LCAO_DFTU_NSCF_Band_XY): Single-thread and multi-thread results are inconsistent; + investigation shows HR, HK, and SK are consistent across threads, but eigenvalues from genelpa + differ; switching to scalapack_gvx produces consistent results across thread counts. Note: this + test is named "NSCF" but actually runs with `calculation = scf` (`scf_nmax = 1`), using + pre-shipped charge density and occ_mat.txt files as initial guess - All NSCF tests (55, 60, 61, 62, 63, 64) have been **converted to SCF+NSCF workflow**: - Pre-converged `autotest-CHARGE-DENSITY.restart` and `occ_mat.txt` files have been removed - Each test directory contains a `scf/` subdirectory with SCF input files - Run with: `bash ../run_scf_nscf.sh [mpi_np]` - These tests are **disabled in CI** (commented out in CASES_CPU.txt) -- All LCAO basis tests use `ks_solver = genelpa`. The genelpa eigenvalue inconsistency across thread counts observed in test 62 may potentially affect other LCAO tests as well \ No newline at end of file +- All LCAO basis tests use `ks_solver = genelpa`. The genelpa eigenvalue inconsistency across thread + counts observed in test 62 may potentially affect other LCAO tests as well diff --git a/tests/README.md b/tests/README.md index d9751d47494..38a36e24cdb 100644 --- a/tests/README.md +++ b/tests/README.md @@ -5,154 +5,144 @@ The purposes for this test directory are: 1. Cover most features of ABACUS. -2. Provide an autotest script to check if the version is correct. - (Reference results are calculated by one core and saved in `result.ref`. - You can change `NUMBEROFPROCESS` in `integrate/general_info` to test with - multiple cores, and set the executable once via +1. Provide an autotest script to check if the version is correct. (Reference results are calculated + by one core and saved in `result.ref`. You can change `NUMBEROFPROCESS` in + `integrate/general_info` to test with multiple cores, and set the executable once via `export ABACUS_EXE=/path/to/abacus`.) ## Folders in this directory -| Folder | Description | -| --- | --- | -| `01_PW` | KSDFT calculations in PW basis with multiple k-point setting. | -| `02_NAO_Gamma` | KSDFT calculations in NAO basis with gamma-only k-point setting. | -| `03_NAO_multik` | KSDFT calculations in NAO basis with multiple k-point setting. | -| `04_FF` | Force fields, including Lennard-Jones potentials, Deep Potentials and Neuroevolution Potential. | -| `05_rtTDDFT` | Real-time TDDFT tests in LCAO and PW bases. | -| `06_SDFT` | Stochastic DFT tests. | -| `07_OFDFT` | Orbital-free DFT tests. | -| `08_RI` | Resolution-of-identity (RI) based tests, including hybrid functionals, LR-TDDFT, RPA and BSE. | -| `09_DeePKS` | DeePKS tests. | -| `10_others` | Other tests such as LCAO in pw. | -| `11_PW_GPU` | KSDFT calculations in PW basis with multiple k-point setting using GPU. | -| `12_NAO_Gamma_GPU` | KSDFT calculations in NAO basis with gamma-only k-point setting using GPU. | -| `13_NAO_multik_GPU` | KSDFT calculations in NAO basis with multiple k-point setting using GPU. | -| `16_SDFT_GPU` | Integrate tests for stochastic DFT running on GPU. | -| `CMakeLists.txt` | CMake file for this directory. | -| `integrate` | Stores scripts for integrate tests. | -| `libxc` | Examples related to LibXC, will be refactored soon. | -| `performance` | Examples related to performance of ABACUS, will be refactored soon. | -| `PP_ORB` | Collection of all the used pseudopotentials and numerical atomic orbitals. | -| `README.md` | This file. | +| Folder | Description | +| ------------------- | ----------------------------------------------------------------------------------------------- | +| `01_PW` | KSDFT calculations in PW basis with multiple k-point setting. | +| `02_NAO_Gamma` | KSDFT calculations in NAO basis with gamma-only k-point setting. | +| `03_NAO_multik` | KSDFT calculations in NAO basis with multiple k-point setting. | +| `04_FF` | Force fields, including Lennard-Jones potentials, Deep Potentials and Neuroevolution Potential. | +| `05_rtTDDFT` | Real-time TDDFT tests in LCAO and PW bases. | +| `06_SDFT` | Stochastic DFT tests. | +| `07_OFDFT` | Orbital-free DFT tests. | +| `08_RI` | Resolution-of-identity (RI) based tests, including hybrid functionals, LR-TDDFT, RPA and BSE. | +| `09_DeePKS` | DeePKS tests. | +| `10_others` | Other tests such as LCAO in pw. | +| `11_PW_GPU` | KSDFT calculations in PW basis with multiple k-point setting using GPU. | +| `12_NAO_Gamma_GPU` | KSDFT calculations in NAO basis with gamma-only k-point setting using GPU. | +| `13_NAO_multik_GPU` | KSDFT calculations in NAO basis with multiple k-point setting using GPU. | +| `16_SDFT_GPU` | Integrate tests for stochastic DFT running on GPU. | +| `CMakeLists.txt` | CMake file for this directory. | +| `integrate` | Stores scripts for integrate tests. | +| `libxc` | Examples related to LibXC, will be refactored soon. | +| `performance` | Examples related to performance of ABACUS, will be refactored soon. | +| `PP_ORB` | Collection of all the used pseudopotentials and numerical atomic orbitals. | +| `README.md` | This file. | ## `CASES_CPU.txt` / `CASES_GPU.txt` -Each category directory (`01_PW`, `02_NAO_Gamma`, ...) contains its own -`CASES_CPU.txt` and/or `CASES_GPU.txt`. These are plain lists of the sub-case -names (the test directories) to run, one per line: +Each category directory (`01_PW`, `02_NAO_Gamma`, ...) contains its own `CASES_CPU.txt` and/or +`CASES_GPU.txt`. These are plain lists of the sub-case names (the test directories) to run, one per +line: - `CASES_CPU.txt`: cases run on CPU builds. - `CASES_GPU.txt`: cases run on GPU builds. -`Autotest.sh` reads the list from the file given by `-f ` (default -`CASES_CPU.txt` in the current working directory) and runs each named case. -Ctest invokes `Autotest.sh` per category directory with the appropriate `-f` -file, e.g. `tests/11_PW_GPU/CMakeLists.txt` uses `-f CASES_GPU.txt`. +`Autotest.sh` reads the list from the file given by `-f ` (default `CASES_CPU.txt` in the +current working directory) and runs each named case. Ctest invokes `Autotest.sh` per category +directory with the appropriate `-f` file, e.g. `tests/11_PW_GPU/CMakeLists.txt` uses +`-f CASES_GPU.txt`. -When you add/rename a test case, add/remove its directory name in the relevant -`CASES_*.txt` of its category, otherwise it will not be picked up. +When you add/rename a test case, add/remove its directory name in the relevant `CASES_*.txt` of its +category, otherwise it will not be picked up. ## How to run tests -1. Set the ABACUS executable. The recommended way is a single environment - variable, which both `Autotest.sh` and `general_info` (via `run_check.sh`) - read: +1. Set the ABACUS executable. The recommended way is a single environment variable, which both + `Autotest.sh` and `general_info` (via `run_check.sh`) read: ```bash export ABACUS_EXE=/path/to/abacus ``` - If `ABACUS_EXE` is not set, both fall back to the bare command name - `abacus`, which the shell resolves by searching the directories listed in - `$PATH` (run `which abacus` to see what it resolves to). This PATH fallback - is what CI uses after `cmake --install`. + If `ABACUS_EXE` is not set, both fall back to the bare command name `abacus`, which the shell + resolves by searching the directories listed in `$PATH` (run `which abacus` to see what it + resolves to). This PATH fallback is what CI uses after `cmake --install`. Ways to point at a specific executable, highest priority first: a) Command-line flag (`Autotest.sh` only): - ```bash - ../integrate/Autotest.sh -a /path/to/abacus -n 4 - ``` + ```bash + ../integrate/Autotest.sh -a /path/to/abacus -n 4 + ``` - Overrides everything for that invocation. `Single_job.sh`/`run_check.sh` - do not accept `-a`. - b) Environment variable (works for `Autotest.sh` and `run_check.sh`): + Overrides everything for that invocation. `Single_job.sh`/`run_check.sh` do not accept `-a`. b) + Environment variable (works for `Autotest.sh` and `run_check.sh`): - ```bash - export ABACUS_EXE=/path/to/abacus - ``` + ```bash + export ABACUS_EXE=/path/to/abacus + ``` - Add it to `~/.bashrc` to make it persistent across sessions. - c) Local override file (`Autotest.sh` only; not tracked by git): - create `integrate/general_info.local` containing e.g. + Add it to `~/.bashrc` to make it persistent across sessions. c) Local override file + (`Autotest.sh` only; not tracked by git): create `integrate/general_info.local` containing e.g. - ```bash - abacus=/path/to/abacus - ``` + ```bash + abacus=/path/to/abacus + ``` - `Autotest.sh` sources this file at startup when it exists, so the path - survives new shells while `git status` stays clean. - d) Edit the files directly (hard-coded; do NOT commit a local absolute path): - - `integrate/Autotest.sh`: set the `abacus` variable. - - `integrate/general_info`: set `EXEC` (supports `$VAR`/`${VAR}` - placeholders, expanded by `integrate/validation_tools/run_check.sh` - from the environment). + `Autotest.sh` sources this file at startup when it exists, so the path survives new shells while + `git status` stays clean. d) Edit the files directly (hard-coded; do NOT commit a local absolute + path): - Effective priority: `-a` flag > `ABACUS_EXE` > `general_info.local` > - hard-coded value in the files > `abacus` from PATH. + - `integrate/Autotest.sh`: set the `abacus` variable. + - `integrate/general_info`: set `EXEC` (supports `$VAR`/`${VAR}` placeholders, expanded by + `integrate/validation_tools/run_check.sh` from the environment). -2. Enter each integrate test directory, and run this script for autotests: + Effective priority: `-a` flag > `ABACUS_EXE` > `general_info.local` > hard-coded value in the + files > `abacus` from PATH. + +1. Enter each integrate test directory, and run this script for autotests: ```bash ../integrate/Autotest.sh ``` -3. If you want to focus on No.xxx example, such as `101_PW_OU`: +1. If you want to focus on No.xxx example, such as `101_PW_OU`: ```bash cd 101_PW_OU ../../integrate/Single_job.sh $parameter ``` - You can choose `$parameter` among `""` (empty), `debug` or `ref`. - `ref`: generate `result.ref` file (the answer you need). + You can choose `$parameter` among `""` (empty), `debug` or `ref`. `ref`: generate `result.ref` + file (the answer you need). ## How to validate an integrate test case -Each case directory contains a checked-in `result.ref`: a list of -"key value" lines (total energy, forces, stress, matrix-compare flags, ...). -Validation means running ABACUS in the case directory, collecting the same -lines from the fresh run into `result.out`, and comparing the two: - -- The collectors live in `integrate/validation_tools/`. The entry point is - `catch_properties.sh`; it sources `props_common.sh` (shared helpers and - INPUT parsing) and the per-category modules `props_basic.sh`, `props_mat.sh`, - `props_cube.sh`, `props_ml.sh`, `props_tddft.sh` and `props_deepks.sh`. Each - module defines `run__props()` hooks; add a new kind of check by - extending the matching module (or dropping in a new `props_.sh` and - calling its hook from `catch_properties.sh`). -- `CompareFile.py` compares numerical/text output files at a given digit - tolerance; `cube_tool.py` handles real-space `.cube` integration and - wave-function fingerprints. -- `totaltimeref` is the wall time of the run. It is recorded for information - only and is expected to differ between machines. +Each case directory contains a checked-in `result.ref`: a list of "key value" lines (total energy, +forces, stress, matrix-compare flags, ...). Validation means running ABACUS in the case directory, +collecting the same lines from the fresh run into `result.out`, and comparing the two: + +- The collectors live in `integrate/validation_tools/`. The entry point is `catch_properties.sh`; it + sources `props_common.sh` (shared helpers and INPUT parsing) and the per-category modules + `props_basic.sh`, `props_mat.sh`, `props_cube.sh`, `props_ml.sh`, `props_tddft.sh` and + `props_deepks.sh`. Each module defines `run__props()` hooks; add a new kind of check by + extending the matching module (or dropping in a new `props_.sh` and calling its hook from + `catch_properties.sh`). +- `CompareFile.py` compares numerical/text output files at a given digit tolerance; `cube_tool.py` + handles real-space `.cube` integration and wave-function fingerprints. +- `totaltimeref` is the wall time of the run. It is recorded for information only and is expected to + differ between machines. Ways to validate, from a whole category down to one case: -1. Whole category (what ctest/CI do), from the category directory - (e.g. `tests/01_PW`): +1. Whole category (what ctest/CI do), from the category directory (e.g. `tests/01_PW`): ```bash bash ../integrate/Autotest.sh -n 4 ``` - `Autotest.sh` runs every case in the category's `CASES_CPU.txt`, invokes the collectors to - build `result.out`, and compares it with `result.ref` using the thresholds - at the top of `Autotest.sh` (`threshold` / `force_threshold` / - `stress_threshold` / `descriptor_threshold`; a per-case `threshold` file - can override them). Useful flags: + `Autotest.sh` runs every case in the category's `CASES_CPU.txt`, invokes the collectors to build + `result.out`, and compares it with `result.ref` using the thresholds at the top of `Autotest.sh` + (`threshold` / `force_threshold` / `stress_threshold` / `descriptor_threshold`; a per-case + `threshold` file can override them). Useful flags: - `-r `: run only cases whose name matches `` - `-f `: take the case list from `` (e.g. `CASES_GPU.txt`) @@ -167,53 +157,52 @@ Ways to validate, from a whole category down to one case: bash ../integrate/Autotest.sh -r 035_PW_15_SO ``` -2. One case by hand, from the case directory (e.g. `tests/01_PW/035_PW_15_SO`): +1. One case by hand, from the case directory (e.g. `tests/01_PW/035_PW_15_SO`): ```bash bash ../../integrate/Single_job.sh ``` - It reads `integrate/general_info` (`NUMBEROFPROCESS`, `CHECKACCURACY`, - `EXEC`), runs ABACUS, builds `result.out` through `run_check.sh` and prints - every line that disagrees with `result.ref`. With the `ref` argument it - regenerates `result.ref` instead; `debug` copies `run_check.sh` and the - whole `validation_tools/` directory into the case directory and collects + It reads `integrate/general_info` (`NUMBEROFPROCESS`, `CHECKACCURACY`, `EXEC`), runs ABACUS, + builds `result.out` through `run_check.sh` and prints every line that disagrees with + `result.ref`. With the `ref` argument it regenerates `result.ref` instead; `debug` copies + `run_check.sh` and the whole `validation_tools/` directory into the case directory and collects with that copy, so local edits to the collectors take effect. -3. Collector only (ABACUS output already exists in `OUT.autotest/`): +1. Collector only (ABACUS output already exists in `OUT.autotest/`): ```bash bash ../../integrate/validation_tools/catch_properties.sh result.out diff result.ref result.out ``` - A clean diff (apart from the `totaltimeref` line) means the case still - validates. This is the fastest check when you only changed the validation - scripts themselves. + A clean diff (apart from the `totaltimeref` line) means the case still validates. This is the + fastest check when you only changed the validation scripts themselves. ## How to modify an existing test case When merging or renaming a test case: 1. Move/rename the directory: `git mv ` -2. Update the INPUT file with new parameters (keep the original style) -3. Update the case README to describe the new test purpose -4. Update `CASES_CPU.txt` and `CASES_GPU.txt`: remove old name, add new name -5. Remove the old directory: `git rm -rf ` -6. Regenerate `result.ref`: `OMP_NUM_THREADS=1 ../../integrate/Single_job.sh ref` -7. Commit the changes +1. Update the INPUT file with new parameters (keep the original style) +1. Update the case README to describe the new test purpose +1. Update `CASES_CPU.txt` and `CASES_GPU.txt`: remove old name, add new name +1. Remove the old directory: `git rm -rf ` +1. Regenerate `result.ref`: `OMP_NUM_THREADS=1 ../../integrate/Single_job.sh ref` +1. Commit the changes -For smearing tests: insulators (e.g., H2) can accept any smearing method -without changing the result. Metals require smearing for convergence. +For smearing tests: insulators (e.g., H2) can accept any smearing method without changing the +result. Metals require smearing for convergence. Marking unimplemented features: -- If a feature is not yet implemented (e.g., a certain code path, GPU backend, - or functional lacks stress/force support), add the corresponding INPUT - parameter but comment it out with an explanation, e.g.: + +- If a feature is not yet implemented (e.g., a certain code path, GPU backend, or functional lacks + stress/force support), add the corresponding INPUT parameter but comment it out with an + explanation, e.g.: ``` #cal_stress 1 # implicit solvation stress is not implemented yet ``` - This documents the intended coverage, makes the gap visible to readers, and - lets the test be enabled later by simply uncommenting once the feature lands. + This documents the intended coverage, makes the gap visible to readers, and lets the test be + enabled later by simply uncommenting once the feature lands. diff --git a/tests/integrate/README.md b/tests/integrate/README.md index 58c6c17d1ca..ed3a4f2ec12 100644 --- a/tests/integrate/README.md +++ b/tests/integrate/README.md @@ -1,101 +1,63 @@ 1. Modify the file general_info to include the EXEC address -2. try this script for autotest: -./Autotest.sh > check.txt +1. try this script for autotest: ./Autotest.sh > check.txt -3. if you want to focus on No.xxx example, such as 101_PW_OU_PL: -cd 101_PW_OU_PL -./../run_debug.sh $parameter +1. if you want to focus on No.xxx example, such as 101_PW_OU_PL: cd 101_PW_OU_PL ./../run_debug.sh + $parameter # you can choose $parameter among "" (empty), debug or ref # 'ref': generate result.ref file -NOTES: -****Purpose for this autotest package is: -1, cover all functions and application scenarios -2, autotest script to check if the version is correct. - (reference result calculated by one core and saved in result.ref) - (user can change NUMBEROFPROCESS value in general_info to test by multi cores) -3, if there is any bug occurs, rename the bug example path to mark it please. +NOTES: \*\*\*\*Purpose for this autotest package is: 1, cover all functions and application +scenarios 2, autotest script to check if the version is correct. (reference result calculated by one +core and saved in result.ref) (user can change NUMBEROFPROCESS value in general_info to test by +multi cores) 3, if there is any bug occurs, rename the bug example path to mark it please. ####################### ABBREVIATIONS USED IN NAMING THE INTEGRATE TESTS -_PW plain wave bases -_NO numerical atoms orbitals bases -_NP expand numerical atoms orbitals in plane-wave basis - -_OU old upf pseudopotential file -_15 SG15 pseudopotential file -_VW vwr pseudopotential file -_DJ DOJO pseudopotential file - -_FD smearing method Fermi-dirac -_FX smearing method: Fixed occupations -_M2 smearing method: mp2 -_MP smearing method: Methfessel-Paxton (MP) -_MV smearing method: Marzari-Vanderbilt -_SG smearing method: Gaussian - -_SY turn on symmetry -_CG cg diagonalization method -_DA david diagonalization method - -_S1 one spin channel -_S2 two spin channels -_S4 four spin channels - -_GE genelpa diagonalization method -_HP hpseps diagonalization method -_SC scalapack diagonalization method - -_RE relax calculation -_CR cell-relax calculation -_CF calculate and output force -_CS calculate and output stress -_MD molecular dynamics -_TD real time TDDFT -_LR linear response TDDFT - -_OHK output Hamiltonian and Overlap matrices for each k point -_OHR output Hamiltonian and Overlap matrices with Bravais lattice vectors -_OB output bands file -_OD output DOS file -_OW output wave functions -_OC output charge density -_OK output kinetic energy density - -_GO gamma_only method -_KP all K-Points method - -_FM ferromagnetic nspin=2 -_AF anti-ferromagnetic nspin=2 anti initial magnetism - -_PU DFT plus U -_BS bsse - -_PL mixing_type plain mixing -_KK mixing_type kerker mixing -_PU mixing_type pulay mixing -_PK mixing_type pulay-kerker mixing -_BD mixing_type broyden mixing - -_SO spin orbit coupling (SOC) -_NB set NBANDS without default - -_XX EXX -_VD VDW (both d2 or d3) - -_MG move ions method: cg -_MF move ions method: FIRE -_MB move ions method: bfgs - -_1O first-order charge extrapolation -_2O second-order charge extrapolation - -_OF orbital free density functional theory (OFDFT) -_OP optimization method used in OFDFT -_KE kinetic energy functional used in OFDFT -_CO convergence check +\_PW plain wave bases \_NO numerical atoms orbitals bases \_NP expand numerical atoms orbitals in +plane-wave basis + +\_OU old upf pseudopotential file \_15 SG15 pseudopotential file \_VW vwr pseudopotential file \_DJ +DOJO pseudopotential file + +\_FD smearing method Fermi-dirac \_FX smearing method: Fixed occupations \_M2 smearing method: mp2 +\_MP smearing method: Methfessel-Paxton (MP) \_MV smearing method: Marzari-Vanderbilt \_SG smearing +method: Gaussian + +\_SY turn on symmetry \_CG cg diagonalization method \_DA david diagonalization method + +\_S1 one spin channel \_S2 two spin channels \_S4 four spin channels + +\_GE genelpa diagonalization method \_HP hpseps diagonalization method \_SC scalapack +diagonalization method + +\_RE relax calculation \_CR cell-relax calculation \_CF calculate and output force \_CS calculate +and output stress \_MD molecular dynamics \_TD real time TDDFT \_LR linear response TDDFT + +\_OHK output Hamiltonian and Overlap matrices for each k point \_OHR output Hamiltonian and Overlap +matrices with Bravais lattice vectors \_OB output bands file \_OD output DOS file \_OW output wave +functions \_OC output charge density \_OK output kinetic energy density + +\_GO gamma_only method \_KP all K-Points method + +\_FM ferromagnetic nspin=2 \_AF anti-ferromagnetic nspin=2 anti initial magnetism + +\_PU DFT plus U \_BS bsse + +\_PL mixing_type plain mixing \_KK mixing_type kerker mixing \_PU mixing_type pulay mixing \_PK +mixing_type pulay-kerker mixing \_BD mixing_type broyden mixing + +\_SO spin orbit coupling (SOC) \_NB set NBANDS without default + +\_XX EXX \_VD VDW (both d2 or d3) + +\_MG move ions method: cg \_MF move ions method: FIRE \_MB move ions method: bfgs + +\_1O first-order charge extrapolation \_2O second-order charge extrapolation + +\_OF orbital free density functional theory (OFDFT) \_OP optimization method used in OFDFT \_KE +kinetic energy functional used in OFDFT \_CO convergence check diff --git a/toolchain/README.md b/toolchain/README.md index 5f81fedfc5b..edefea85a70 100644 --- a/toolchain/README.md +++ b/toolchain/README.md @@ -2,7 +2,7 @@ [![Version](https://img.shields.io/badge/version-2026.1-blue.svg)](https://github.com/deepmodeling/abacus-develop/tree/develop/toolchain) [![License](https://img.shields.io/badge/license-GPL--compatible-green.svg)](#license) -[![Platform](https://img.shields.io/badge/platform-Linux-lightgrey.svg)]() +[![Platform](https://img.shields.io/badge/platform-Linux-lightgrey.svg)](<>) > **Automated dependency management and compilation toolchain for ABACUS** @@ -23,17 +23,20 @@ ## Overview -The ABACUS Toolchain is an automated build system inspired by the cp2k-toolchain that simplifies the compilation and installation of ABACUS and its dependencies. It supports both online and offline installation modes, multiple compiler toolchains, and provides a streamlined path from dependency installation to ABACUS compilation. +The ABACUS Toolchain is an automated build system inspired by the cp2k-toolchain that simplifies the +compilation and installation of ABACUS and its dependencies. It supports both online and offline +installation modes, multiple compiler toolchains, and provides a streamlined path from dependency +installation to ABACUS compilation. ### Main Developer -**[QuantumMisaka](https://github.com/QuantumMisaka)** (Zhaoqing Liu) +**[QuantumMisaka](https://github.com/QuantumMisaka)** (Zhaoqing Liu)\ *Peking University, CCME* ## Features - โœ… **Multiple Toolchain Support**: GNU, Intel OneAPI, AMD AOCC/AOCL -- โœ… **Flexible Installation**: Online/offline modes with automatic dependency resolution +- โœ… **Flexible Installation**: Online/offline modes with automatic dependency resolution - โœ… **GPU Acceleration**: CUDA support for NVIDIA GPUs with ELPA and cuSolverMP - โœ… **MPI Implementations**: OpenMPI, MPICH, Intel MPI support - โœ… **Math Libraries**: OpenBLAS, Intel MKL, AMD AOCL integration @@ -102,11 +105,17 @@ Downloads packages automatically from official sources: ./toolchain_gnu.sh # Uses system package managers and official repositories ``` -Before running the toolchain, please make sure you have loaded the related environments and set the environment variables. -- You SHOULD source or module load related environments before use toolchain method for installation, especially for *intel*, *gcc-aocl* or *aocc-aocl* toolchain! For example, `module load mkl mpi icc compiler` for loading intel-oneapi envs. -- You SHOULD keep your environments systematic, for example, you CANNOT load intel-OneAPI environments while use gcc toolchain !!! +Before running the toolchain, please make sure you have loaded the related environments and set the +environment variables. + +- You SHOULD source or module load related environments before use toolchain method for + installation, especially for *intel*, *gcc-aocl* or *aocc-aocl* toolchain! For example, + `module load mkl mpi icc compiler` for loading intel-oneapi envs. +- You SHOULD keep your environments systematic, for example, you CANNOT load intel-OneAPI + environments while use gcc toolchain !!! **Package Sources:** + - **Build Tools:** - [GCC](https://mirrors.tuna.tsinghua.edu.cn/gnu/gcc/) - GNU Compiler Collection - [CMake](https://cmake.org/download/) - Cross-platform build system @@ -129,14 +138,14 @@ Before running the toolchain, please make sure you have loaded the related envir - [Cereal](https://github.com/USCiLab/cereal) - C++ serialization library - [nlohmann-json](https://github.com/nlohmann/json) - Fast JSON parser/generator - **Reference mirror:** [CP2K static downloads](https://www.cp2k.org/static/downloads) -- Most GitHub source archives are downloaded from `codeload.github.com`. nlohmann-json uses the official `json.tar.xz` release asset. +- Most GitHub source archives are downloaded from `codeload.github.com`. nlohmann-json uses the + official `json.tar.xz` release asset. -JSON output is enabled with `-DENABLE_JSON=ON`. `ENABLE_RAPIDJSON` is no longer -supported because the JSON backend has been replaced by nlohmann-json. The -toolchain package option is `--with-json=install|system|/prefix|no`. In `system` -mode, ABACUS uses CMake's normal package search; the installation must provide -`nlohmann_jsonConfig.cmake`, not just the headers. Release archives are cached as -`build/json-.tar.xz` for offline installation. +JSON output is enabled with `-DENABLE_JSON=ON`. `ENABLE_RAPIDJSON` is no longer supported because +the JSON backend has been replaced by nlohmann-json. The toolchain package option is +`--with-json=install|system|/prefix|no`. In `system` mode, ABACUS uses CMake's normal package +search; the installation must provide `nlohmann_jsonConfig.cmake`, not just the headers. Release +archives are cached as `build/json-.tar.xz` for offline installation. ### Offline Installation @@ -155,6 +164,7 @@ mkdir build The downloading process can be facilitated via `./toolchain_gnu.sh --pack-run`. Also, for users in China, we provide a Gitee mirror repository with pre-downloaded packages: + ```bash # Clone the Gitee repository in toolchain directory git clone https://gitee.com/jamesmisaka/abacus_toolchain_build.git @@ -165,23 +175,28 @@ mv abacus_toolchain_build/* build/ ### Hybrid Installation -Mix online and offline packages as needed - the toolchain automatically detects locally available packages and downloads missing ones. +Mix online and offline packages as needed - the toolchain automatically detects locally available +packages and downloads missing ones. ## Supported Toolchains ### GNU Toolchain + - **Compilers**: System GCC (โ‰ฅ5.0) or installed GCC - **MPI**: OpenMPI or MPICH - **Math**: OpenBLAS + ScaLAPACK - **Features**: Most stable, widely compatible ### Intel Toolchain -- **Compilers**: Intel OneAPI (icx/icpx/ifx or classic icc/icpc/ifort) with system/installed GCC (โ‰ฅ5.0) + +- **Compilers**: Intel OneAPI (icx/icpx/ifx or classic icc/icpc/ifort) with system/installed GCC + (โ‰ฅ5.0) - **MPI**: Intel MPI - **Math**: Intel MKL - **Features**: Optimized performance for Intel Machine ### AMD Toolchain + - **Compilers**: AMD AOCC or system/installed GCC - **Math**: AMD AOCL (Optimized math libraries) - **Features**: AMD processor optimization (e.g., Zen3+) @@ -190,46 +205,53 @@ Mix online and offline packages as needed - the toolchain automatically detects ### Supported Packages -| Package | Version (main/alt) | Purpose | License | Default | -|---------|-------------------|---------|---------|---------| -| **Build Tools** ||||| -| CMake | 3.31.7 / 3.30.5 | Build system | BSD-3-Clause | Install | -| GCC | 13.2.0 / 11.4.0 | C/C++ compiler | GPL-3.0-or-later WITH GCC-exception-3.1 | Install | -| **MPI Libraries** ||||| -| OpenMPI | 5.0.10 / 4.1.8 | MPI implementation | BSD-3-Clause-Open-MPI | Install | -| MPICH | 5.0.1 / 4.3.2 | Alternative MPI | mpich2 (BSD-like) | Alternative | -| **Math Libraries** ||||| -| OpenBLAS | 0.3.33 / 0.3.30 | Linear algebra | BSD-3-Clause | Install | -| ScaLAPACK | 2.2.3 / 2.2.1 | Parallel linear algebra | BSD-3-Clause | Install | -| **Scientific Libraries** ||||| -| FFTW | 3.3.11 / 3.3.10 | Fast Fourier Transform | GPL-2.0-or-later | Install | -| LibXC | 7.0.0 / 6.2.2 | Exchange-correlation | MPL-2.0 | Install | -| ELPA | 2026.02.001 / 2024.05.001 | Eigenvalue solver | LGPL-3.0-only | Install | -| **Advanced Features** ||||| -| Cereal | pinned commit | C++ Serialization | BSD | Install | -| nlohmann-json | 3.12.0 | JSON parsing | MIT | Install | -| LibRI | pinned commit | EXX calculations | GPL-3.0 | Install | -| LibComm | pinned commit | EXX calculations | GPL-3.0 | Install | -| LibTorch | 2.1.2 / 1.12.1 | MLALGO support | BSD-3-Clause | Optional | -| LibNPY | 1.0.1 / 1.0.1 | NumPy I/O | MIT | Optional | -| NEP | main | Neuroevolution potential | MIT | Optional | - -Also, [Intel-oneAPI](https://www.intel.cn/content/www/cn/zh/developer/tools/oneapi/toolkits.html) and AMD [AOCC](https://www.amd.com/zh-cn/developer/aocc.html) and [AOCL](https://www.amd.com/zh-cn/developer/aocl.html) are supported in toolchain by setting them to system option, but one should install them manually by server administrator. +| Package | Version (main/alt) | Purpose | License | Default | +| ------------------------ | ------------------------- | ------------------------ | --------------------------------------- | ----------- | +| **Build Tools** | | | | | +| CMake | 3.31.7 / 3.30.5 | Build system | BSD-3-Clause | Install | +| GCC | 13.2.0 / 11.4.0 | C/C++ compiler | GPL-3.0-or-later WITH GCC-exception-3.1 | Install | +| **MPI Libraries** | | | | | +| OpenMPI | 5.0.10 / 4.1.8 | MPI implementation | BSD-3-Clause-Open-MPI | Install | +| MPICH | 5.0.1 / 4.3.2 | Alternative MPI | mpich2 (BSD-like) | Alternative | +| **Math Libraries** | | | | | +| OpenBLAS | 0.3.33 / 0.3.30 | Linear algebra | BSD-3-Clause | Install | +| ScaLAPACK | 2.2.3 / 2.2.1 | Parallel linear algebra | BSD-3-Clause | Install | +| **Scientific Libraries** | | | | | +| FFTW | 3.3.11 / 3.3.10 | Fast Fourier Transform | GPL-2.0-or-later | Install | +| LibXC | 7.0.0 / 6.2.2 | Exchange-correlation | MPL-2.0 | Install | +| ELPA | 2026.02.001 / 2024.05.001 | Eigenvalue solver | LGPL-3.0-only | Install | +| **Advanced Features** | | | | | +| Cereal | pinned commit | C++ Serialization | BSD | Install | +| nlohmann-json | 3.12.0 | JSON parsing | MIT | Install | +| LibRI | pinned commit | EXX calculations | GPL-3.0 | Install | +| LibComm | pinned commit | EXX calculations | GPL-3.0 | Install | +| LibTorch | 2.1.2 / 1.12.1 | MLALGO support | BSD-3-Clause | Optional | +| LibNPY | 1.0.1 / 1.0.1 | NumPy I/O | MIT | Optional | +| NEP | main | Neuroevolution potential | MIT | Optional | + +Also, [Intel-oneAPI](https://www.intel.cn/content/www/cn/zh/developer/tools/oneapi/toolkits.html) +and AMD [AOCC](https://www.amd.com/zh-cn/developer/aocc.html) and +[AOCL](https://www.amd.com/zh-cn/developer/aocl.html) are supported in toolchain by setting them to +system option, but one should install them manually by server administrator. ### Package Version Switching -The toolchain supports a dual-version system for most packages, providing both **main** (latest stable) and **alt** (alternative/legacy) versions. This allows users to choose between cutting-edge features and proven stability based on their specific requirements. +The toolchain supports a dual-version system for most packages, providing both **main** (latest +stable) and **alt** (alternative/legacy) versions. This allows users to choose between cutting-edge +features and proven stability based on their specific requirements. #### Version Selection Methods The `--package-version` parameter supports two flexible usage patterns: **Method 1: Multiple Independent Parameters** (Original support) + ```bash ./toolchain_gnu.sh --package-version libtorch:alt --package-version elpa:alt ``` **Method 2: Single Parameter with Multiple Key-Value Pairs** (Enhanced functionality) + ```bash ./toolchain_gnu.sh --package-version "libtorch:alt elpa:alt" ``` @@ -258,10 +280,12 @@ and other `toolchain_*.sh` scripts share the same version selection. #### Global Version Strategy - **Default Behavior**: All packages use their **main** versions unless explicitly overridden -- **Selective Override**: Use `--package-version` to specify alternative versions for specific packages -- **Consistency**: Version selections are validated against available options in `scripts/package_versions.sh` -- **Backward Compatibility**: Both usage methods are fully supported to ensure existing scripts continue to work - +- **Selective Override**: Use `--package-version` to specify alternative versions for specific + packages +- **Consistency**: Version selections are validated against available options in + `scripts/package_versions.sh` +- **Backward Compatibility**: Both usage methods are fully supported to ensure existing scripts + continue to work ### System Requirements @@ -296,12 +320,14 @@ cmake -B $BUILD_DIR \ #### Multi-GPU with ELPA 1. **Configure toolchain with CUDA:** + ```bash export CUDA_PATH=/path/to/CUDA ./toolchain_gnu.sh --enable-cuda --gpu-ver=70 # For V100 (compute capability 7.0) ``` 2. **Build with ELPA GPU support:** + ```bash cmake -B $BUILD_DIR \ -DUSE_CUDA=ON \ @@ -315,19 +341,24 @@ cuSolverMP requires NVIDIA HPC SDK. Follow these steps to build with cuSolverMP: 1. Load the NVHPC module: - - **For NVIDIA HPC SDK version < 25.9**: cuSolverMP relies on HPC-X for communication, so you need to load the `nvhpc-hpcx-cudaxx/xx.x` module. For example, with HPC SDK 25.3: + - **For NVIDIA HPC SDK version < 25.9**: cuSolverMP relies on HPC-X for communication, so you + need to load the `nvhpc-hpcx-cudaxx/xx.x` module. For example, with HPC SDK 25.3: + ```bash module use /opt/nvidia/hpc_sdk/modulefiles module load nvhpc-hpcx-cuda12/25.3 ``` - - **For NVIDIA HPC SDK version >= 25.9**: cuSolverMP uses NCCL for communication instead of HPC-X, so only the base `nvhpc/xx.x` module is needed. For example, with HPC SDK 26.1: + - **For NVIDIA HPC SDK version >= 25.9**: cuSolverMP uses NCCL for communication instead of + HPC-X, so only the base `nvhpc/xx.x` module is needed. For example, with HPC SDK 26.1: + ```bash module use /opt/nvidia/hpc_sdk/modulefiles module load nvhpc/26.1 ``` -2. Build with cuSolverMP enabled: +1. Build with cuSolverMP enabled: + ```bash cmake -B $BUILD_DIR \ -DUSE_CUDA=ON \ @@ -341,7 +372,11 @@ cmake -B $BUILD_DIR \ #### Intel OneAPI Problems -Most of the OneAPI problem arise from the newer version of Intel-OneAPI. For users who encounter OneAPI problem, one can get Intel-OneAPI in [QE-managed website](https://pranabdas.github.io/espresso/setup/hpc/#installing-intel-oneapi-libraries), and use this code to get Intel oneAPI Base Toolkit and HPC Toolkit: +Most of the OneAPI problem arise from the newer version of Intel-OneAPI. For users who encounter +OneAPI problem, one can get Intel-OneAPI in +[QE-managed website](https://pranabdas.github.io/espresso/setup/hpc/#installing-intel-oneapi-libraries), +and use this code to get Intel oneAPI Base Toolkit and HPC Toolkit: + ```shell wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/992857b9-624c-45de-9701-f6445d845359/l_BaseKit_p_2023.2.0.49397_offline.sh wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/0722521a-34b5-4c41-af3f-d5d14e88248d/l_HPCKit_p_2023.2.0.49440_offline.sh @@ -350,26 +385,41 @@ wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/0722521a-34b5-4 Related discussion here [#4976](https://github.com/deepmodeling/abacus-develop/issues/4976) **OneAPI 2025.0 Compatibility:** + - LibRI compatibility issues ([#6190](https://github.com/deepmodeling/abacus-develop/issues/6190)) -- Solution: Using the patch from Cereal and the master version of Cereal to fix the compatibility issue (included in toolchain). +- Solution: Using the patch from Cereal and the master version of Cereal to fix the compatibility + issue (included in toolchain). **ELPA on AMD servers with Intel compilers:** + ```bash # Use Intel classic compilers instead ./toolchain_intel.sh --with-intel-classic=yes ``` -Notice: `icc` and `icpc` from Intel Classic Compiler of Intel-oneAPI are not supported for 2024.0 and newer version. And Intel-OneAPI 2023.2.0 can be found in QE website. You need to download Base-toolkit for MKL and HPC-toolkit for MPi and compiler for Intel-OneAPI 2023.2.0, while in Intel-OneAPI 2024.x, only the HPC-toolkit is needed. +Notice: `icc` and `icpc` from Intel Classic Compiler of Intel-oneAPI are not supported for 2024.0 +and newer version. And Intel-OneAPI 2023.2.0 can be found in QE website. You need to download +Base-toolkit for MKL and HPC-toolkit for MPi and compiler for Intel-OneAPI 2023.2.0, while in +Intel-OneAPI 2024.x, only the HPC-toolkit is needed. #### AMD AOCC-AOCL problem -Use AOCC-AOCL to compile dependencies is permitted and usually get boosting in ABACUS efficiency. But you need to get rid of `flang` while compiling ELPA. Toolchain itself helps you make this `flang` shade in default of `aocc-aocl` toolchain, and you can manually use `flang` by setting `--with-flang=yes` in `toolchain_aocc-aocl.sh` to have a try, while toolchain helps you to bypass the possible errors in compiling ELPA with AOCC-AOCL, but the computing efficiency will be relatively lower compared to `gnu` or `gcc-aocl` toolchain. There are some issues related to the numeric instability of ABACUS compiled by AOCC-AOCL toolchain, see [#6420](https://github.com/deepmodeling/abacus-develop/issues/6420) +Use AOCC-AOCL to compile dependencies is permitted and usually get boosting in ABACUS efficiency. +But you need to get rid of `flang` while compiling ELPA. Toolchain itself helps you make this +`flang` shade in default of `aocc-aocl` toolchain, and you can manually use `flang` by setting +`--with-flang=yes` in `toolchain_aocc-aocl.sh` to have a try, while toolchain helps you to bypass +the possible errors in compiling ELPA with AOCC-AOCL, but the computing efficiency will be +relatively lower compared to `gnu` or `gcc-aocl` toolchain. There are some issues related to the +numeric instability of ABACUS compiled by AOCC-AOCL toolchain, see +[#6420](https://github.com/deepmodeling/abacus-develop/issues/6420) -The `gcc-aocl` toolchain will have no problem above for aocc-dependent aocl. However, the gcc-dependent aocl will have some package linking problem related to OpenMPI. Take it with caution. +The `gcc-aocl` toolchain will have no problem above for aocc-dependent aocl. However, the +gcc-dependent aocl will have some package linking problem related to OpenMPI. Take it with caution. #### OpenMPI Issues **Version 5 compatibility problems:** + ```bash # Use OpenMPI v4 instead ./toolchain_gnu.sh --package-version openmpi:alt @@ -378,12 +428,14 @@ The `gcc-aocl` toolchain will have no problem above for aocc-dependent aocl. How ``` **LibComm compilation with OpenMPI:** + - Fixed in toolchain 2025.2 which downlo the master branch of LibComm - Alternative: Use MPICH or Intel MPI #### Shell and Permission Issues **Line ending problems:** + ```bash ./pre_set.sh # Fixes line endings and permissions # Or manually: @@ -394,6 +446,7 @@ chmod +x *.sh #### Library Version Issues **LibTorch GLIBC errors:** + - Requires GLIBCXX_3.4.26 - Change version from 2.1.2 to 1.12.1 - Use `--package-version libtorch:alt` when calling toolchain @@ -402,16 +455,17 @@ chmod +x *.sh - Single parameter with multiple key-value pairs: `--package-version libtorch:alt elpa:alt` **DeepMD GLIBC errors:** + - Requires GCC โ‰ฅ 11.3.1 for GLIBCXX_3.4.29 - Upgrade system GCC or use newer toolchain ### Getting Help 1. **Check logs**: Look in `build/PKG_NAME/make.log` for compilation errors -2. **Reduce parallelism**: Use `NPROCS_OVERWRITE=N` environment variable to limit parallel processes -3. **System libraries**: Use `--with-PKG=system` for system-installed packages -4. **Clean installation**: Remove `install/` and `build/` directories to restart -5. **Certificate issues**: Use `DOWNLOAD_CERT_POLICY=skip` for download problems +1. **Reduce parallelism**: Use `NPROCS_OVERWRITE=N` environment variable to limit parallel processes +1. **System libraries**: Use `--with-PKG=system` for system-installed packages +1. **Clean installation**: Remove `install/` and `build/` directories to restart +1. **Certificate issues**: Use `DOWNLOAD_CERT_POLICY=skip` for download problems ## Advanced Usage @@ -460,7 +514,9 @@ export DOWNLOAD_CERT_POLICY=skip ./toolchain_gnu.sh ``` -**Smart Mode Behavior**: The default `smart` mode first attempts secure downloads with certificate verification. If this fails (e.g., due to corporate firewalls or outdated certificates), it automatically falls back to skipping certificate verification while providing clear user feedback. +**Smart Mode Behavior**: The default `smart` mode first attempts secure downloads with certificate +verification. If this fails (e.g., due to corporate firewalls or outdated certificates), it +automatically falls back to skipping certificate verification while providing clear user feedback. #### Parallel Compilation Control @@ -480,6 +536,7 @@ NPROCS_OVERWRITE=4 ./toolchain_gnu.sh --with-gcc --with-openmpi ``` **Use Cases**: + - **Resource-limited systems**: Reduce parallelism to avoid memory exhaustion - **Shared servers**: Limit resource usage to be considerate of other users - **CI/CD environments**: Match container resource limits @@ -490,7 +547,7 @@ NPROCS_OVERWRITE=4 ./toolchain_gnu.sh --with-gcc --with-openmpi The toolchain generates several setup files: - `install/setup`: Main environment setup -- `build/setup_PKG`: Individual package environments +- `build/setup_PKG`: Individual package environments - `abacus_env.sh`: ABACUS-specific environment (generated by build scripts) ## Developer Guide @@ -511,39 +568,42 @@ scripts/ ### Key Components -| File | Purpose | -|------|---------| -| `install_abacus_toolchain_new.sh` | Main orchestration script (new version) | -| `toolchain_*.sh` | Frontend scripts for specific toolchains | -| `scripts/lib/config_manager.sh` | Configuration management | -| `scripts/lib/package_manager.sh` | Package installation logic | -| `scripts/lib/user_interface.sh` | User interaction and output | -| `scripts/common_vars.sh` | Shared variables and defaults | -| `scripts/tool_kit.sh` | Utility functions and macros | -| `scripts/parse_if.py` | Parser for IF_XYZ constructs | +| File | Purpose | +| ---------------------------------- | --------------------------------------------------------------------- | +| `install_abacus_toolchain_new.sh` | Main orchestration script (new version) | +| `toolchain_*.sh` | Frontend scripts for specific toolchains | +| `scripts/lib/config_manager.sh` | Configuration management | +| `scripts/lib/package_manager.sh` | Package installation logic | +| `scripts/lib/user_interface.sh` | User interaction and output | +| `scripts/common_vars.sh` | Shared variables and defaults | +| `scripts/tool_kit.sh` | Utility functions and macros | +| `scripts/parse_if.py` | Parser for IF_XYZ constructs | | `install//install_successful` | Per-package install lock/checksum file generated by `write_checksums` | ### Script Structure Details -**Individual Package Scripts**: Each `scripts/stage*/install_PKG.sh` script is relatively independent and should: +**Individual Package Scripts**: Each `scripts/stage*/install_PKG.sh` script is relatively +independent and should: 1. **Generate setup files**: Write to both `build/setup_PKG` and `install/setup` + - `build/setup_PKG`: Variables for toolchain compilation and arch file flags - `install/setup`: Environment setup for compiling/running ABACUS -2. **Handle dependencies**: May depend on other libraries being installed with correct environment variables +1. **Handle dependencies**: May depend on other libraries being installed with correct environment + variables -3. **Use toolkit macros**: Leverage functionality from `scripts/tool_kit.sh` for common operations +1. **Use toolkit macros**: Leverage functionality from `scripts/tool_kit.sh` for common operations ### Package Installation Scripts Each `scripts/stage*/install_PKG.sh` script: 1. **Downloads** the package (if not available locally) -2. **Configures** build with appropriate flags -3. **Compiles** with error handling and logging -4. **Installs** to the toolchain directory -5. **Generates** setup files for environment configuration +1. **Configures** build with appropriate flags +1. **Compiles** with error handling and logging +1. **Installs** to the toolchain directory +1. **Generates** setup files for environment configuration ### Configuration System @@ -557,14 +617,16 @@ The `--with-PKG` options control how a package is going to be installed: - `--with-PKG=no`: Skip package installation entirely **System Search Paths**: When using `system` mode, the installation script searches in: + - `LD_LIBRARY_PATH`, `LD_RUN_PATH`, `LIBRARY_PATH` - `/usr/local/lib64`, `/usr/local/lib`, `/usr/lib64`, `/usr/lib` - For MKL libraries: `MKLROOT` environment variable **Troubleshooting System Libraries**: If `--with-PKG=system` cannot find the library: + 1. Use `module show PKG` to see module-defined paths -2. Find the root installation directory manually -3. Use `--with-PKG=/path/to/pkg` to specify exact location +1. Find the root installation directory manually +1. Use `--with-PKG=/path/to/pkg` to specify exact location #### Feature Control Options (`--enable-FEATURE`) @@ -580,15 +642,16 @@ For packages serving the same purpose, mode variables act as selectors: - `--mpi-mode=openmpi|mpich|intelmpi`: Choose MPI implementation - `--math-mode=openblas|mkl|aocl`: Choose math library -**Note**: While `--with-PKG` controls the installation method, the `PKG_MODE` variable picks which package to actually use, providing maximum flexibility. +**Note**: While `--with-PKG` controls the installation method, the `PKG_MODE` variable picks which +package to actually use, providing maximum flexibility. ### Adding New Packages 1. **Create installation script**: `scripts/stageN/install_newpkg.sh` -2. **Add to stage script**: Include in `scripts/stageN/install_stageN.sh` -3. **Update configuration**: Add options to `config_manager.sh` -4. **Add version info**: Update `scripts/package_versions.sh` -5. **Test thoroughly**: Verify with different toolchain combinations +1. **Add to stage script**: Include in `scripts/stageN/install_stageN.sh` +1. **Update configuration**: Add options to `config_manager.sh` +1. **Add version info**: Update `scripts/package_versions.sh` +1. **Test thoroughly**: Verify with different toolchain combinations ### Advanced Developer Features @@ -601,6 +664,7 @@ IF_XYZ(A | B) ``` This construct is parsed by `scripts/parse_if.py`: + - Evaluates to *A* if *XYZ* is passed as command line option - Evaluates to *B* if *XYZ* is not passed @@ -611,8 +675,9 @@ IF_XYZ(IF_ABC(flag1|flag2) | flag3) ``` This parses to: + - *flag1* if both *XYZ* and *ABC* are present -- *flag2* if only *XYZ* is present +- *flag2* if only *XYZ* is present - *flag3* if neither is present #### Portability Requirements @@ -656,7 +721,8 @@ check_gfortran_module module_name ### Best Practices - **Reuse toolkit functions**: Use macros from `scripts/tool_kit.sh` -- **Modular functionality**: Add new functionality as macros in `scripts/tool_kit.sh` rather than inline code +- **Modular functionality**: Add new functionality as macros in `scripts/tool_kit.sh` rather than + inline code - **Portable compiler flags**: Filter through `allowed_gcc_flags` and `allowed_gfortran_flags` - **Environment variables**: Use `${VAR:-default}` pattern for configurable defaults - **Lock files**: Create completion markers for resumable installation @@ -665,11 +731,15 @@ check_gfortran_module module_name ## License -The ABACUS Toolchain downloads and installs only [GPL-compatible](https://www.gnu.org/licenses/gpl-faq.html#WhatDoesCompatMean) packages. All included packages maintain their original licenses as listed in the Dependencies section above. +The ABACUS Toolchain downloads and installs only +[GPL-compatible](https://www.gnu.org/licenses/gpl-faq.html#WhatDoesCompatMean) packages. All +included packages maintain their original licenses as listed in the Dependencies section above. -**License Compatibility**: All packages use GPL-compatible licenses including BSD, MIT, LGPL, MPL-2.0, and GPL variants, ensuring seamless integration with GPL-licensed software. +**License Compatibility**: All packages use GPL-compatible licenses including BSD, MIT, LGPL, +MPL-2.0, and GPL variants, ensuring seamless integration with GPL-licensed software. -**Note**: Proprietary packages like Intel OneAPI (MKL/Compiler/MPI) and AMD AOCC/AOCL are supported but must be installed separately by the user. +**Note**: Proprietary packages like Intel OneAPI (MKL/Compiler/MPI) and AMD AOCC/AOCL are supported +but must be installed separately by the user. ## Contributing @@ -678,7 +748,7 @@ We welcome contributions to improve the ABACUS Toolchain! Here's how you can hel ### Reporting Issues 1. **Search existing issues** before creating new ones -2. **Provide detailed information**: +1. **Provide detailed information**: - Operating system and version - Compiler versions - Complete error messages and logs @@ -687,12 +757,12 @@ We welcome contributions to improve the ABACUS Toolchain! Here's how you can hel ### Contributing Code 1. **Fork the repository** and create a feature branch -2. **Follow coding standards**: +1. **Follow coding standards**: - Use consistent shell scripting style - Add comments for complex logic - Test with multiple toolchain combinations -3. **Update documentation** for new features -4. **Submit pull request** with clear description +1. **Update documentation** for new features +1. **Submit pull request** with clear description ### Development Setup @@ -708,11 +778,12 @@ cd abacus-develop/toolchain ### Areas for Contribution - ๐Ÿ”ง **New package support**: Add support for additional scientific libraries -- ๐Ÿ› **Bug fixes**: Resolve compatibility issues and installation problems +- ๐Ÿ› **Bug fixes**: Resolve compatibility issues and installation problems - ๐Ÿ“š **Documentation**: Improve guides and troubleshooting information - ๐Ÿงช **Testing**: Expand test coverage for different systems and configurations - ๐Ÿš€ **Performance**: Optimize installation speed and resource usage ---- +______________________________________________________________________ -**For questions, issues, or contributions, please visit the [ABACUS GitHub repository](https://github.com/deepmodeling/abacus-develop).** +**For questions, issues, or contributions, please visit the +[ABACUS GitHub repository](https://github.com/deepmodeling/abacus-develop).** diff --git a/tools/01_NAO_generation/SIAB/README.md b/tools/01_NAO_generation/SIAB/README.md index 89c66410103..2558474e7e1 100644 --- a/tools/01_NAO_generation/SIAB/README.md +++ b/tools/01_NAO_generation/SIAB/README.md @@ -1,14 +1,10 @@ The code is used to generate numerical atomic orbitals - The format of orbital file: -(1) First line: -Mesh number - -(2) Second line: -delta r (unit: Bohr) +(1) First line: Mesh number -(3) Type(always 0, you can ignore it), L(angular momentum), N (multizeta) -(4) wave function: psi (note, not psi*r). +(2) Second line: delta r (unit: Bohr) +(3) Type(always 0, you can ignore it), L(angular momentum), N (multizeta) (4) wave function: psi +(note, not psi\*r). diff --git a/tools/01_NAO_generation/qo/README.md b/tools/01_NAO_generation/qo/README.md index a99c1aa4921..7c81625585d 100644 --- a/tools/01_NAO_generation/qo/README.md +++ b/tools/01_NAO_generation/qo/README.md @@ -1,25 +1,54 @@ *Use Markdown render to convert this document into directly human-readable version* + # ABACUS LCAO2QO Hands-on + ## Introduction -This document is a hands-on tutorial for the ABACUS LCAO2QO tool. For basic information about QO (Quasiatomic Orbital) method, please refer to *Quasiatomic orbitals for ab initio tight-binding analysis* by *Qian et al.*: https://journals.aps.org/prb/abstract/10.1103/PhysRevB.78.245112. + +This document is a hands-on tutorial for the ABACUS LCAO2QO tool. For basic information about QO +(Quasiatomic Orbital) method, please refer to *Quasiatomic orbitals for ab initio tight-binding +analysis* by *Qian et al.*: https://journals.aps.org/prb/abstract/10.1103/PhysRevB.78.245112. + ### Basic ideas -QO is for projecting as many as possible eigenstates of a system onto a atom-centered basis set, unlike MLWFs (Maximally Localized Wannier Functions) that would produce bond-like Wannier functions for some systems. The QO is defined from an optimization problem that maximal the norm of the projection of atom-centered orbitals onto the super-plane spanned by eigenstates and constructed unoccupied states: -$\max\mathcal{L}:=\max \sum_{\mu}{\left\|\left(\sum_{n\mathbf{k}}{\hat{P}_{\psi_{n\mathbf{k}}}}+\sum_{m\mathbf{k}}{\hat{P}_{c_{m\mathbf{k}}}}\right)|A_{\mu}\rangle\right\|^2}$ -where $\hat{P}_{\psi_{n\mathbf{k}}}$ and $\hat{P}_{c_{m\mathbf{k}}}$ are the projection operators for occupied and unoccupied states, respectively. $A_{\mu}$ is the atom-centered orbital. -The former part of projection is fixed once the occupied states are determined, and the latter part is determined by selection of $Nq-Nb$ from $\sum_{m\mathbf{k}}{\hat{P}_{c_{m\mathbf{k}}}}|A_{\mu}\rangle$ states, with total number of $Nq$ and number of occupied states $Nb$. + +QO is for projecting as many as possible eigenstates of a system onto a atom-centered basis set, +unlike MLWFs (Maximally Localized Wannier Functions) that would produce bond-like Wannier functions +for some systems. The QO is defined from an optimization problem that maximal the norm of the +projection of atom-centered orbitals onto the super-plane spanned by eigenstates and constructed +unoccupied states:\ +$\\max\\mathcal{L}:=\\max +\\sum\_{\\mu}{\\left|\\left(\\sum\_{n\\mathbf{k}}{\\hat{P}_{\\psi_{n\\mathbf{k}}}}+\\sum\_{m\\mathbf{k}}{\\hat{P}_{c_{m\\mathbf{k}}}}\\right)|A\_{\\mu}\\rangle\\right|^2}$\ +where $\\hat{P}_{\\psi_{n\\mathbf{k}}}$ and $\\hat{P}_{c_{m\\mathbf{k}}}$ are the projection +operators for occupied and unoccupied states, respectively. $A\_{\\mu}$ is the atom-centered +orbital.\ +The former part of projection is fixed once the occupied states are determined, and the latter part +is determined by selection of $Nq-Nb$ from +$\\sum\_{m\\mathbf{k}}{\\hat{P}_{c_{m\\mathbf{k}}}}|A\_{\\mu}\\rangle$ states, with total number of +$Nq$ and number of occupied states $Nb$. + ### Formulation -See Github issue #3640 for details: https://github.com/deepmodeling/abacus-develop/issues/3640 + +See Github issue #3640 for details: https://github.com/deepmodeling/abacus-develop/issues/3640 + ## Prerequisites + - ABACUS - Python3 - Numpy - Scipy - Matplotlib (optional) + ## Usage + ### Basis set selection -ABACUS provides various kinds of atom-centered orbitals construction, such as hydrogen-like orbitals, exponentially decay scaled pseudowavefunctions, single zeta (not implemented, develop up to user actual needs). Select orbitals that fit most to the system you are interested in. + +ABACUS provides various kinds of atom-centered orbitals construction, such as hydrogen-like +orbitals, exponentially decay scaled pseudowavefunctions, single zeta (not implemented, develop up +to user actual needs). Select orbitals that fit most to the system you are interested in. + ### Input file of ABACUS + To run QO analysis, in ABACUS INPUT file, following keywords are needed to be set: + ```bash qo_switch 1 qo_basis hydrogen @@ -27,13 +56,27 @@ qo_strategy energy-valence qo_thr 1.0e-10 #qo_screening_coeff 0.1 ``` + - `qo_switch` is a switch to turn on QO analysis. -- `qo_basis` is the basis set selection, parameters above define the hydrogen-like orbital construction -- `qo_strategy` is the strategy to set what orbitals needed to construct. For hydrogen-like orbitals, for example if element is Cu (1s2 2s2 2p6 3s2 3p6 3d10 4s1), `energy-valence` corresponds to construct only 3p 3d and 4s orbitals, `energy-full` corresponds to construct all orbitals, `minimal-nodeless` corresponds to construct 1s, 2p, 3d and 4f orbitals, `minimal-valence` corresponds to construct 4s 4p 4d 4f orbitals. For more information about this keyword, please refer to ABACUS manual: https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#qo-strategy -- `qo_thr` is the threshold to determine the realspace tailing of orbitals, which is used to determine the cutoff radius of orbitals. Default value is 1.0e-10. -- `qo_screening_coeff`, for `qo_basis hydrogen` it controls whether use Slater screening coefficients to include many-electron effect into the orbitals. Any float number as value will turn on this feature. Default value is off. +- `qo_basis` is the basis set selection, parameters above define the hydrogen-like orbital + construction +- `qo_strategy` is the strategy to set what orbitals needed to construct. For hydrogen-like + orbitals, for example if element is Cu (1s2 2s2 2p6 3s2 3p6 3d10 4s1), `energy-valence` + corresponds to construct only 3p 3d and 4s orbitals, `energy-full` corresponds to construct all + orbitals, `minimal-nodeless` corresponds to construct 1s, 2p, 3d and 4f orbitals, + `minimal-valence` corresponds to construct 4s 4p 4d 4f orbitals. For more information about this + keyword, please refer to ABACUS manual: + https://abacus.deepmodeling.com/en/latest/advanced/input_files/input-main.html#qo-strategy +- `qo_thr` is the threshold to determine the realspace tailing of orbitals, which is used to + determine the cutoff radius of orbitals. Default value is 1.0e-10. +- `qo_screening_coeff`, for `qo_basis hydrogen` it controls whether use Slater screening + coefficients to include many-electron effect into the orbitals. Any float number as value will + turn on this feature. Default value is off. + +For some systems, pseudowavefunction works better than hydrogen-like orbitals (but not all +pseudopotential has pseudowavefunction in file, check your pseudopotential file before run). To use +pseudowavefunction as `qo_basis`, set as following: -For some systems, pseudowavefunction works better than hydrogen-like orbitals (but not all pseudopotential has pseudowavefunction in file, check your pseudopotential file before run). To use pseudowavefunction as `qo_basis`, set as following: ```bash qo_switch 1 qo_basis pswfc @@ -41,35 +84,62 @@ qo_strategy all qo_thr 1.0e-10 qo_screening_coeff 0.5 ``` -For `qo_basis pswfc`, `qo_screening_coeff` is necessary and for Si single crystal the optimal value is tested to be `0.5`. Test on this parameter should be done for different systems. A larger value will result in more localized orbitals. + +For `qo_basis pswfc`, `qo_screening_coeff` is necessary and for Si single crystal the optimal value +is tested to be `0.5`. Test on this parameter should be done for different systems. A larger value +will result in more localized orbitals. + ### Output file of ABACUS -Once the calculation is done, the output file will contain the QO analysis results. The QO analysis results are stored in `OUT.${suffix}` directory, where `${suffix}` is set in `INPUT` and default is `ABACUS`. You will find following files: + +Once the calculation is done, the output file will contain the QO analysis results. The QO analysis +results are stored in `OUT.${suffix}` directory, where `${suffix}` is set in `INPUT` and default is +`ABACUS`. You will find following files: + ```bash data-0-H ... data-0-S ... ``` -These files are Hamiltonian and overlap matrix of numerical atomic orbitals basis sets. For each kpoint a pair of these files will be generated, and different spin channels are defined as different kpoints. + +These files are Hamiltonian and overlap matrix of numerical atomic orbitals basis sets. For each +kpoint a pair of these files will be generated, and different spin channels are defined as different +kpoints. + ```bash WFC_NAO_K1.txt ... ``` -These files are eigenstates represented by numerical atomic orbital basis sets. For each kpoint a file will be generated. + +These files are eigenstates represented by numerical atomic orbital basis sets. For each kpoint a +file will be generated. + ```bash QO_ovlp_0.dat ... ``` -This file contains information of $\langle A_\mu(\mathbf{k})|\phi_\nu(\mathbf{k})\rangle$, file name indiced by kpoint. + +This file contains information of $\\langle A\_\\mu(\\mathbf{k})|\\phi\_\\nu(\\mathbf{k})\\rangle$, +file name indiced by kpoint. + ```bash QO_supercells.dat ``` -This file stores information of supercell considered when calculating two-center-integrals, will be usefull in kpoint extrapolation. + +This file stores information of supercell considered when calculating two-center-integrals, will be +usefull in kpoint extrapolation. + ```bash kpoints istate.info running_scf.log ... ``` + Basic output files of ABACUS. + ### Run `postprocess.py` -After the calculation is done, run `postprocess.py` to generate QO analysis results. The script will read the output files of ABACUS and generate the QO analysis results. Following defines an example of `postprocess.py`: + +After the calculation is done, run `postprocess.py` to generate QO analysis results. The script will +read the output files of ABACUS and generate the QO analysis results. Following defines an example +of `postprocess.py`: + ```python if __name__ == "__main__": @@ -91,7 +161,19 @@ if __name__ == "__main__": elif run_type == "unittest": unittest.main() ``` -The `production` function will read the output files of ABACUS and generate the QO analysis results. The `path` is the path to the output files of ABACUS. `nkpts` is the number of kpoints. `ib_min` and `ib_max` are the range of orbitals to be considered. `eig_thr` is the threshold to determine the eigenstates to be considered. `error_estimation_with_lcao` is a switch to turn on error estimation with LCAO. If set to `True`, the script will calculate the error estimation with LCAO. Collect information output by `production(...)` function. The `hqos_k` and `sqos_k` are the Hamiltonian and overlap matrix of QO basis sets. The `kvecs_d` is the direct coordinates of kpoints. -QO postprocess is programmed with unittest, therefore to run the script, set `run_type` to `production` and run the script (but mostly you don't need this). + +The `production` function will read the output files of ABACUS and generate the QO analysis results. +The `path` is the path to the output files of ABACUS. `nkpts` is the number of kpoints. `ib_min` and +`ib_max` are the range of orbitals to be considered. `eig_thr` is the threshold to determine the +eigenstates to be considered. `error_estimation_with_lcao` is a switch to turn on error estimation +with LCAO. If set to `True`, the script will calculate the error estimation with LCAO. Collect +information output by `production(...)` function. The `hqos_k` and `sqos_k` are the Hamiltonian and +overlap matrix of QO basis sets. The `kvecs_d` is the direct coordinates of kpoints.\ +QO postprocess is programmed with unittest, therefore to run the script, set `run_type` to +`production` and run the script (but mostly you don't need this). + ## Acknowledgement -ABACUS LCAO2QO module uses two-center-integrator module refactored by @jinzx10, who also helps in code debugging. @mohanchen, @dyzheng, @WHUweiqingzhou and @QG-phys provide suggestions on code maintainance and participate discussion in technical aspects. \ No newline at end of file + +ABACUS LCAO2QO module uses two-center-integrator module refactored by @jinzx10, who also helps in +code debugging. @mohanchen, @dyzheng, @WHUweiqingzhou and @QG-phys provide suggestions on code +maintainance and participate discussion in technical aspects. diff --git a/tools/02_postprocessing/plot-tools/README.md b/tools/02_postprocessing/plot-tools/README.md index f1bb9962cdc..9f1bee52cdf 100644 --- a/tools/02_postprocessing/plot-tools/README.md +++ b/tools/02_postprocessing/plot-tools/README.md @@ -7,16 +7,16 @@ # Plotting tool for ABACUS -- Band Structure and Fat Bands -- DOS and PDOS -- Dipole and Absorption +- Band Structure and Fat Bands +- DOS and PDOS +- Dipole and Absorption ## Requirements -- [NumPy](https://numpy.org/) -- [Matplotlib](https://matplotlib.org/) -- [lxml](https://lxml.de/) (only required for parsing the XML projected-band output) -- [setuptools](https://setuptools.pypa.io/en/latest/index.html) +- [NumPy](https://numpy.org/) +- [Matplotlib](https://matplotlib.org/) +- [lxml](https://lxml.de/) (only required for parsing the XML projected-band output) +- [setuptools](https://setuptools.pypa.io/en/latest/index.html) ## Installation @@ -30,8 +30,12 @@ python setup.py install There are two ways to use this tool: -1. Specify parameters in `band.py` (`dos.py`, `dipole.py`) directly, and then `python **.py`. And you can also import module in your own script e.g. `from abacus_plot.band import Band`. (Recommend) -2. Command-line tools are also supported in this tool. In this way, you need prepare an input file and execute some commands (see below). You can use `abacus-plot -h` to check command-line information +1. Specify parameters in `band.py` (`dos.py`, `dipole.py`) directly, and then `python **.py`. And + you can also import module in your own script e.g. `from abacus_plot.band import Band`. + (Recommend) +1. Command-line tools are also supported in this tool. In this way, you need prepare an input file + and execute some commands (see below). You can use `abacus-plot -h` to check command-line + information ### Band Structure @@ -46,20 +50,21 @@ First, prepare a file named 'config.json' in json format: } ``` -| Property | Type | Note | -| :------------: | :-------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -| _bandfile_ | `str` or `List[str]` | Bands data file output from ABACUS. 'BANDS*\*.dat' for band structure and 'PBANDS*\*' for projected band structure | -| _efermi_ | `float` or `List[float]` | Fermi level in eV | -| _energy_range_ | `list` | Range of energy in eV | -| _shift_ | `bool` | If set `'true'`, it will evaluate band gap (only for semiconductors and insulators). Default: `'false'` | -| _index_ | `List[int]` or `Dict[str, List[int]]` or `Dict[str, Dict[int, List[int]]]]` | Extract PBANDS of each atom from 'PBANDS\_\*' file e.g. [index_0, index_1...] or {index_0:[l_0, l_1, ...], ...}, [index_0:{l_0:[m_0, m_1, ...], ...}, ...] | -| _atom_index_ | `List[int]` or `Dict[str, List[int]]` or `Dict[str, Dict[int, List[int]]]]` | Extract PBANDS of each atom with same atom*index from 'PBANDS*\*' file e.g. [atom_index_0, atom_index_1...] or {atom_index_0:[l_0, l_1, ...], ...}, [atom_index_0:{l_0:[m_0, m_1, ...], ...}, ...] | -| _species_ | `List[str]` or `Dict[str, List[int]]` or `Dict[str, Dict[int, List[int]]]]` | Extract PBANDS of each atom with same species from 'PBANDS\_\*' file e.g. [elem_0, elem_1...] or {elem_0:[l_0, l_1, ...], ...}, [elem_0:{l_0:[m_0, m_1, ...], ...}, ...] | -| _kptfile_ | `str` | K-points file with `Line` mode in ABACUS format | -| _label_ | `str` or `List[str]` | Label of band structure | -| _color_ | `str` or `List[str]` | Color of band structure | - -If you want to plot band structure of `nspin=2` or compare two band structure on same k-path, you can set _bandfile_, _efermi_, _label_, _color_ in `list` type. +| Property | Type | Note | +| :------------: | :-------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| _bandfile_ | `str` or `List[str]` | Bands data file output from ABACUS. 'BANDS\*\*.dat' for band structure and 'PBANDS\*\*' for projected band structure | +| _efermi_ | `float` or `List[float]` | Fermi level in eV | +| _energy_range_ | `list` | Range of energy in eV | +| _shift_ | `bool` | If set `'true'`, it will evaluate band gap (only for semiconductors and insulators). Default: `'false'` | +| _index_ | `List[int]` or `Dict[str, List[int]]` or `Dict[str, Dict[int, List[int]]]]` | Extract PBANDS of each atom from 'PBANDS\_\*' file e.g. [index_0, index_1...] or {index_0:[l_0, l_1, ...], ...}, \[index_0:{l_0:[m_0, m_1, ...], ...}, ...\] | +| _atom_index_ | `List[int]` or `Dict[str, List[int]]` or `Dict[str, Dict[int, List[int]]]]` | Extract PBANDS of each atom with same atom*index from 'PBANDS*\*' file e.g. [atom_index_0, atom_index_1...] or {atom_index_0:[l_0, l_1, ...], ...}, \[atom_index_0:{l_0:[m_0, m_1, ...], ...}, ...\] | +| _species_ | `List[str]` or `Dict[str, List[int]]` or `Dict[str, Dict[int, List[int]]]]` | Extract PBANDS of each atom with same species from 'PBANDS\_\*' file e.g. [elem_0, elem_1...] or {elem_0:[l_0, l_1, ...], ...}, \[elem_0:{l_0:[m_0, m_1, ...], ...}, ...\] | +| _kptfile_ | `str` | K-points file with `Line` mode in ABACUS format | +| _label_ | `str` or `List[str]` | Label of band structure | +| _color_ | `str` or `List[str]` | Color of band structure | + +If you want to plot band structure of `nspin=2` or compare two band structure on same k-path, you +can set _bandfile_, _efermi_, _label_, _color_ in `list` type. The _kptfile_ should be as follows, and notes after `#` will be set as k-points label automatically. @@ -82,13 +87,15 @@ Then, use the following command to plot band structure: abacus-plot -b ``` -Then, the following command will plot projected band structure and figures output to directory `PBAND*_FIG` ($*=1$ for $nspin=1$, $*=2$ for $nspin=2$): +Then, the following command will plot projected band structure and figures output to directory +`PBAND*_FIG` ($*=1$ for $nspin=1$, $*=2$ for $nspin=2$): ```shell abacus-plot -d -p ``` -Then, the following command will output parsed partial DOS to directory `PBAND*_FILE` ($*=1$ for $nspin=1$, $*=2$ for $nspin=2$): +Then, the following command will output parsed partial DOS to directory `PBAND*_FILE` ($*=1$ for +$nspin=1$, $*=2$ for $nspin=2$): ```shell abacus-plot -d -o @@ -102,8 +109,8 @@ From this directory, run the focused DOS reader, plotting and smearing regressio MPLBACKEND=Agg PYTHONPATH=. python3 -m unittest discover -s tests -v ``` -These Python tests use the package dependencies from `setup.py` and are discovered -by `unittest`; they do not add a dependency to the C++ CMake build. +These Python tests use the package dependencies from `setup.py` and are discovered by `unittest`; +they do not add a dependency to the C++ CMake build. ### DOS @@ -126,20 +133,22 @@ First, prepare a file named 'config.json' in json format: } ``` -If you only want to plot total DOS, you can modify `pdosfile` to `tdosfile` and do not set `species` and `pdosfig`. -| Property | Type | Note | -| :------------: | :-------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -| _tdosfile_ | `str` or `List[str]` | Total DOS data file(s) output from ABACUS. For `nspin=2`, pass one spin-channel file (`doss1*` or `doss2*`; the counterpart is paired automatically), a directory containing them, or a list of both files. For `nspin=4`, ABACUS writes a single spinor-summed file | -| _pdosfile_ | `str` | Directory or path prefix containing the text PDOS files `pdoss1*` (and `pdoss2*` for spin-polarized runs), e.g. `pdoss1g1.txt`, output from ABACUS | -| _efermi_ | `float` | Fermi level in eV | -| _energy_range_ | `list` | Range of energy in eV | -| _shift_ | `bool` | If set `'true'`, it will evaluate band gap. Default: `'false'` | -| _smearing_ | `bool` | If `'true'` (default), plot the Gaussian-smeared DOS column (`dos_smear`, unit 1/eV); if `'false'`, plot the raw per-bin histogram column. The raw column is also accessible as `TDOS(...).dos` for custom smearing, e.g. with `abacus_plot.utils.gaussian_smearing`. This switch also selects the data used by the `shift=true` band-gap estimate; with the smeared column, Gaussian tails can narrow small apparent gaps, so the reported gap is a threshold-based estimate that depends on `dos_sigma` and `prec` | -| _index_ | `List[int]` or `Dict[str, List[int]]` or `Dict[str, Dict[str, List[int]]]]` | Extract PDOS of each atom e.g. [index_0, index_1...] or {index*0:[l_0, l_1, ...], ...}, [index_0:{l_0:[m_0, m_1, ...], ...}, ...] | -| \_atom_index* | `List[int]` or `Dict[str, List[int]]` or `Dict[str, Dict[str, List[int]]]]` | Extract PDOS of each atom with same atom*index e.g. [atom_index_0, atom_index_1...] or {atom_index_0:[l_0, l_1, ...], ...}, [atom_index_0:{l_0:[m_0, m_1, ...], ...}, ...] | -| \_species* | `List[str]` or `Dict[str, List[int]]` or `Dict[str, Dict[str, List[int]]]]` | Extract PDOS of each atom with same species e.g. [elem_0, elem_1...] or {elem*0:[l_0, l_1, ...], ...}, [elem_0:{l_0:[m_0, m_1, ...], ...}, ...] | -| \_tdosfig* | `str` | Output picture of total DOS | -| _pdosfig_ | `str` | Output picture of partial DOS | +If you only want to plot total DOS, you can modify `pdosfile` to `tdosfile` and do not set `species` +and `pdosfig`. + +| Property | Type | Note | +| :------------: | :-------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| _tdosfile_ | `str` or `List[str]` | Total DOS data file(s) output from ABACUS. For `nspin=2`, pass one spin-channel file (`doss1*` or `doss2*`; the counterpart is paired automatically), a directory containing them, or a list of both files. For `nspin=4`, ABACUS writes a single spinor-summed file | +| _pdosfile_ | `str` | Directory or path prefix containing the text PDOS files `pdoss1*` (and `pdoss2*` for spin-polarized runs), e.g. `pdoss1g1.txt`, output from ABACUS | +| _efermi_ | `float` | Fermi level in eV | +| _energy_range_ | `list` | Range of energy in eV | +| _shift_ | `bool` | If set `'true'`, it will evaluate band gap. Default: `'false'` | +| _smearing_ | `bool` | If `'true'` (default), plot the Gaussian-smeared DOS column (`dos_smear`, unit 1/eV); if `'false'`, plot the raw per-bin histogram column. The raw column is also accessible as `TDOS(...).dos` for custom smearing, e.g. with `abacus_plot.utils.gaussian_smearing`. This switch also selects the data used by the `shift=true` band-gap estimate; with the smeared column, Gaussian tails can narrow small apparent gaps, so the reported gap is a threshold-based estimate that depends on `dos_sigma` and `prec` | +| _index_ | `List[int]` or `Dict[str, List[int]]` or `Dict[str, Dict[str, List[int]]]]` | Extract PDOS of each atom e.g. [index_0, index_1...] or {index\*0:[l_0, l_1, ...], ...}, \[index_0:{l_0:[m_0, m_1, ...], ...}, ...\] | +| \_atom_index\* | `List[int]` or `Dict[str, List[int]]` or `Dict[str, Dict[str, List[int]]]]` | Extract PDOS of each atom with same atom\*index e.g. [atom_index_0, atom_index_1...] or {atom_index_0:[l_0, l_1, ...], ...}, \[atom_index_0:{l_0:[m_0, m_1, ...], ...}, ...\] | +| \_species\* | `List[str]` or `Dict[str, List[int]]` or `Dict[str, Dict[str, List[int]]]]` | Extract PDOS of each atom with same species e.g. [elem_0, elem_1...] or {elem\*0:[l_0, l_1, ...], ...}, \[elem_0:{l_0:[m_0, m_1, ...], ...}, ...\] | +| \_tdosfig\* | `str` | Output picture of total DOS | +| _pdosfig_ | `str` | Output picture of partial DOS | Then, the following command will plot total DOS: @@ -158,4 +167,3 @@ Then, the following command will output parsed partial DOS to directory `PDOS_FI ```shell abacus-plot -d -o ``` - diff --git a/tools/02_postprocessing/selective_dynamics/README.md b/tools/02_postprocessing/selective_dynamics/README.md index eef94a6f857..a07a71093ab 100644 --- a/tools/02_postprocessing/selective_dynamics/README.md +++ b/tools/02_postprocessing/selective_dynamics/README.md @@ -10,6 +10,7 @@ ### Setting There is a setting file named `config.yaml`: + ```yaml origin_structure: 'STRU' # the original structure selected_indices: [18, 19] # the atom index that you concerned about, start from 0 @@ -91,15 +92,19 @@ job_script: | ### Submit jobs Use the following command + ```bash python3 path_to_selective_dynamics.py --submit ``` + to generate displaced structures and submit jobs. ### Postprocess Use the following command + ```bash python3 path_to_selective_dynamics.py --post ``` + to generate `FORCE_SETS` and results of phonon calculations. diff --git a/tools/04_windows_installation/README.md b/tools/04_windows_installation/README.md index ef565821301..99a69f49032 100644 --- a/tools/04_windows_installation/README.md +++ b/tools/04_windows_installation/README.md @@ -1,78 +1,73 @@ # ABACUS Windows Installer -A lightweight one-click installer that brings ABACUS to Windows via WSL2 and -conda-forge. No C++ toolchain, no MPI build, no manual dependency juggling โ€” -run `install-abacus.bat` once and type `abacus` from any Windows terminal. +A lightweight one-click installer that brings ABACUS to Windows via WSL2 and conda-forge. No C++ +toolchain, no MPI build, no manual dependency juggling โ€” run `install-abacus.bat` once and type +`abacus` from any Windows terminal. ## How it works -ABACUS depends on a heavy Linux-native scientific stack (OpenMPI, ScaLAPACK, -ELPA, FFTW, libxc, OpenBLAS, โ€ฆ) that is painful to build natively on Windows. -Instead of porting, this installer provisions a standard Linux environment -inside WSL2 and exposes it through thin Windows launchers. +ABACUS depends on a heavy Linux-native scientific stack (OpenMPI, ScaLAPACK, ELPA, FFTW, libxc, +OpenBLAS, โ€ฆ) that is painful to build natively on Windows. Instead of porting, this installer +provisions a standard Linux environment inside WSL2 and exposes it through thin Windows launchers. The pipeline, end to end: 1. **`install-abacus.bat`** (runs on Windows, requires admin) - - Checks the Windows build (โ‰ฅ 19041) and whether WSL is installed; if not, - runs `wsl --install --no-launch` and asks the user to reboot once. + + - Checks the Windows build (โ‰ฅ 19041) and whether WSL is installed; if not, runs + `wsl --install --no-launch` and asks the user to reboot once. - Optionally enables TUNA (Tsinghua) mirrors for users in Mainland China. - - Prompts for an ABACUS version (blank = latest on conda-forge; an exact - version like `3.7.4` is pinned; a match-spec like `>=3.7,<3.8` is passed - through to conda). - - Detects the target distribution (`Ubuntu-22.04`) by querying the WSL - registry key `HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss`. This - is immune to UTF-16 parsing pitfalls and to Store appx leftovers that - can make `wsl -d -- true` falsely report success. - - Calls `wsl --install -d Ubuntu-22.04 --no-launch` if the distro is - missing, then verifies the registry entry appeared. - - Invokes `provision.sh` inside the distribution, stripping any `\r` - bytes on the fly (`sed 's/\r$//' script | bash`) so Windows line - endings don't break shell parsing. - - Writes two small launcher `.cmd` files and adds them to the user PATH - via PowerShell (avoiding `setx`'s 1024-character truncation). - -2. **`provision.sh`** (runs as root inside the WSL distribution) + - Prompts for an ABACUS version (blank = latest on conda-forge; an exact version like `3.7.4` is + pinned; a match-spec like `>=3.7,<3.8` is passed through to conda). + - Detects the target distribution (`Ubuntu-22.04`) by querying the WSL registry key + `HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss`. This is immune to UTF-16 parsing + pitfalls and to Store appx leftovers that can make `wsl -d -- true` falsely report + success. + - Calls `wsl --install -d Ubuntu-22.04 --no-launch` if the distro is missing, then verifies the + registry entry appeared. + - Invokes `provision.sh` inside the distribution, stripping any `\r` bytes on the fly + (`sed 's/\r$//' script | bash`) so Windows line endings don't break shell parsing. + - Writes two small launcher `.cmd` files and adds them to the user PATH via PowerShell (avoiding + `setx`'s 1024-character truncation). + +1. **`provision.sh`** (runs as root inside the WSL distribution) + - Optionally rewrites `/etc/apt/sources.list` to TUNA. - - `apt-get install`s a minimal set of prerequisites (curl, ca-certificates, - bzip2). - - Downloads the Miniforge installer (from GitHub or TUNA's GitHub-releases - mirror) and installs it to `/opt/abacus-miniforge`. - - `conda create -n abacus_env -c conda-forge abacus` (or the TUNA - conda-forge channel) โ€” a single package pulls in the entire scientific - runtime. conda-forge ships `abacus` for `linux-64` and `linux-aarch64`, - which is exactly what WSL2 provides. - - Writes two system-wide launchers, `/usr/local/bin/abacus` and - `/usr/local/bin/abacus-mpi`, that activate the env and exec the real - binary. Both set `OMP_NUM_THREADS=1` by default to avoid thread - oversubscription. `abacus-mpi` additionally sets OpenMPI 4/5 + PRRTE - "allow run as root" environment variables and passes - `--allow-run-as-root` to `mpirun`, so the default WSL root user can - launch parallel jobs without creating a non-root user. - -3. **Windows launchers** (`abacus.cmd`, `abacus-mpi.cmd`) + - `apt-get install`s a minimal set of prerequisites (curl, ca-certificates, bzip2). + - Downloads the Miniforge installer (from GitHub or TUNA's GitHub-releases mirror) and installs + it to `/opt/abacus-miniforge`. + - `conda create -n abacus_env -c conda-forge abacus` (or the TUNA conda-forge channel) โ€” a single + package pulls in the entire scientific runtime. conda-forge ships `abacus` for `linux-64` and + `linux-aarch64`, which is exactly what WSL2 provides. + - Writes two system-wide launchers, `/usr/local/bin/abacus` and `/usr/local/bin/abacus-mpi`, that + activate the env and exec the real binary. Both set `OMP_NUM_THREADS=1` by default to avoid + thread oversubscription. `abacus-mpi` additionally sets OpenMPI 4/5 + PRRTE "allow run as root" + environment variables and passes `--allow-run-as-root` to `mpirun`, so the default WSL root + user can launch parallel jobs without creating a non-root user. + +1. **Windows launchers** (`abacus.cmd`, `abacus-mpi.cmd`) + - Added to `%LOCALAPPDATA%\ABACUS\bin` and the user PATH. - - Each launcher sets `WSLENV=OMP_NUM_THREADS:MKL_NUM_THREADS:OPENBLAS_NUM_THREADS:...` - so thread-count overrides set on the Windows side are visible inside WSL. + - Each launcher sets `WSLENV=OMP_NUM_THREADS:MKL_NUM_THREADS:OPENBLAS_NUM_THREADS:...` so + thread-count overrides set on the Windows side are visible inside WSL. - Body is just: ``` wsl -d Ubuntu-22.04 --cd "%CD%" -- abacus %* ``` - `--cd "%CD%"` maps the current Windows directory (`C:\โ€ฆ\case`) to its - WSL path (`/mnt/c/โ€ฆ/case`), so users can `cd` into a case directory in - `cmd`/PowerShell/Terminal and just type `abacus`. - -4. **`uninstall-abacus.bat`** - - Reads `install-state.txt` (written by the installer) to learn whether - the Ubuntu-22.04 distribution was pre-existing or added by us. - - If it was added by us, prompts whether to `wsl --unregister` the entire - distribution, or to only wipe `/opt/abacus-miniforge` and the launchers. + `--cd "%CD%"` maps the current Windows directory (`C:\โ€ฆ\case`) to its WSL path + (`/mnt/c/โ€ฆ/case`), so users can `cd` into a case directory in `cmd`/PowerShell/Terminal and + just type `abacus`. + +1. **`uninstall-abacus.bat`** + + - Reads `install-state.txt` (written by the installer) to learn whether the Ubuntu-22.04 + distribution was pre-existing or added by us. + - If it was added by us, prompts whether to `wsl --unregister` the entire distribution, or to + only wipe `/opt/abacus-miniforge` and the launchers. - If it was pre-existing, only the ABACUS files inside are removed. - - Cleans Windows-side launchers and removes the bin directory from the - user PATH. - - Does **not** touch WSL itself (runtime, Windows optional features, or - other distributions). See *Uninstallation* below for how to fully - remove WSL if you want to. + - Cleans Windows-side launchers and removes the bin directory from the user PATH. + - Does **not** touch WSL itself (runtime, Windows optional features, or other distributions). See + *Uninstallation* below for how to fully remove WSL if you want to. ## Requirements @@ -80,22 +75,21 @@ The pipeline, end to end: - Administrator privileges for the first run (to enable WSL features). - Virtualization enabled in BIOS/UEFI. - ~2 GB free disk space (Ubuntu + conda env). -- Network access to GitHub and conda-forge, or to TUNA if you choose the - China mirror option. +- Network access to GitHub and conda-forge, or to TUNA if you choose the China mirror option. ## Installation 1. Clone or download this repository. -2. Right-click `install-abacus.bat` โ†’ **Run as administrator**. -3. Answer the China-mirror prompt (`y` recommended inside Mainland China). - Then pick an ABACUS version when prompted (leave blank for the latest on - conda-forge; for a pinned install, type an exact version such as `3.7.4`). -4. If this is the first time WSL is installed on the machine, the script - will ask you to reboot and run it again. -5. Wait for `[*] Provisioning ABACUS โ€ฆ` to finish (5โ€“15 minutes on first - run; most of it is the conda-forge download). -6. When you see `Installation complete!`, **open a new terminal window** - (so the updated PATH takes effect) and verify: +1. Right-click `install-abacus.bat` โ†’ **Run as administrator**. +1. Answer the China-mirror prompt (`y` recommended inside Mainland China). Then pick an ABACUS + version when prompted (leave blank for the latest on conda-forge; for a pinned install, type an + exact version such as `3.7.4`). +1. If this is the first time WSL is installed on the machine, the script will ask you to reboot and + run it again. +1. Wait for `[*] Provisioning ABACUS โ€ฆ` to finish (5โ€“15 minutes on first run; most of it is the + conda-forge download). +1. When you see `Installation complete!`, **open a new terminal window** (so the updated PATH takes + effect) and verify: ``` abacus --version ``` @@ -122,19 +116,18 @@ set OMP_NUM_THREADS=2 abacus-mpi -n 4 ``` -Set `OMP_NUM_THREADS` (and/or `MKL_NUM_THREADS`, `OPENBLAS_NUM_THREADS`) in -your Windows shell and the launcher will forward the value into WSL through -`WSLENV`. Unset, it defaults to 1 โ€” a safe choice when running pure MPI. +Set `OMP_NUM_THREADS` (and/or `MKL_NUM_THREADS`, `OPENBLAS_NUM_THREADS`) in your Windows shell and +the launcher will forward the value into WSL through `WSLENV`. Unset, it defaults to 1 โ€” a safe +choice when running pure MPI. -Interactive Linux shell (for advanced debugging, manually running -`mpirun`, inspecting logs, etc.): +Interactive Linux shell (for advanced debugging, manually running `mpirun`, inspecting logs, etc.): ``` wsl -d Ubuntu-22.04 ``` -Inside the shell you can `conda activate abacus_env` to get access to -`mpirun`, `mpiexec`, and other tools from the conda environment. +Inside the shell you can `conda activate abacus_env` to get access to `mpirun`, `mpiexec`, and other +tools from the conda environment. ## Uninstallation @@ -142,24 +135,21 @@ Inside the shell you can `conda activate abacus_env` to get access to Run `uninstall-abacus.bat`. This handles the common case: -- Removes `/opt/abacus-miniforge` and the `abacus` / `abacus-mpi` launchers - inside WSL. -- If the installer added the `Ubuntu-22.04` distribution, asks whether you - also want to `wsl --unregister` it (pick `y` to reclaim the disk space, - `n` to keep the Linux environment for other uses). -- Deletes `%LOCALAPPDATA%\ABACUS\` and removes its `bin\` directory from - your user PATH. +- Removes `/opt/abacus-miniforge` and the `abacus` / `abacus-mpi` launchers inside WSL. +- If the installer added the `Ubuntu-22.04` distribution, asks whether you also want to + `wsl --unregister` it (pick `y` to reclaim the disk space, `n` to keep the Linux environment for + other uses). +- Deletes `%LOCALAPPDATA%\ABACUS\` and removes its `bin\` directory from your user PATH. -This is enough for almost every user. WSL itself and any *other* WSL -distributions you have stay untouched โ€” important because WSL is commonly -shared with Docker Desktop, VS Code Remote, and other toolchains. +This is enough for almost every user. WSL itself and any *other* WSL distributions you have stay +untouched โ€” important because WSL is commonly shared with Docker Desktop, VS Code Remote, and other +toolchains. ### Nuclear: remove WSL itself -Only do this if you truly have no other use for WSL on this machine. -Removing WSL will break Docker Desktop, VS Code Remote-WSL, any other -Linux distros you have, and so on. Run the following in an elevated -PowerShell: +Only do this if you truly have no other use for WSL on this machine. Removing WSL will break Docker +Desktop, VS Code Remote-WSL, any other Linux distros you have, and so on. Run the following in an +elevated PowerShell: ```powershell # 1. Unregister every WSL distribution (this wipes all their files). @@ -188,19 +178,17 @@ Remove-Item "$env:UserProfile\.wslconfig" -ErrorAction SilentlyContinue Restart-Computer ``` -After the reboot `wsl.exe` no longer exists. If you also ran step 4, the -Hyper-V virtualization layer used by WSL2 is disabled. +After the reboot `wsl.exe` no longer exists. If you also ran step 4, the Hyper-V virtualization +layer used by WSL2 is disabled. -> On older Windows builds where `wsl --uninstall` is not available (WSL -> shipped via the in-box `wsl.exe` rather than the Store package), use -> `Get-AppxPackage *WindowsSubsystemForLinux* | Remove-AppxPackage` as a -> fallback for step 2. +> On older Windows builds where `wsl --uninstall` is not available (WSL shipped via the in-box +> `wsl.exe` rather than the Store package), use +> `Get-AppxPackage *WindowsSubsystemForLinux* | Remove-AppxPackage` as a fallback for step 2. ## Performance notes -- Files under `/mnt/c/...` are served through the 9P protocol and are - noticeably slower than native ext4. For heavy I/O (large SCF, MD - trajectories), run the case from inside the WSL filesystem: +- Files under `/mnt/c/...` are served through the 9P protocol and are noticeably slower than native + ext4. For heavy I/O (large SCF, MD trajectories), run the case from inside the WSL filesystem: ``` wsl -d Ubuntu-22.04 cp -r /mnt/c/path/to/case ~/case @@ -208,8 +196,8 @@ Hyper-V virtualization layer used by WSL2 is disabled. abacus ``` - The first `wsl` invocation after a boot triggers a 10โ€“30 s VM cold start. -- OpenMPI runs all ranks inside a single WSL2 VM, so there is no network - overhead between ranks โ€” you get near-native parallel performance. +- OpenMPI runs all ranks inside a single WSL2 VM, so there is no network overhead between ranks โ€” + you get near-native parallel performance. ## File layout @@ -239,20 +227,16 @@ Inside WSL (Ubuntu-22.04): ## Design choices and trade-offs -- **Why WSL2 + conda-forge instead of a native Windows build?** ABACUS's - MPI + ScaLAPACK + ELPA stack has no reliable native Windows build. Going - through WSL2 lets us reuse the Linux binaries conda-forge already ships, - turning a multi-week porting problem into a 200-line shell script. -- **Why a dedicated `Ubuntu-22.04` distribution?** conda-forge ABACUS is - built against glibc from 22.04-era Ubuntu. Using `Ubuntu` (rolling) risks - mismatches; pinning the version keeps the install reproducible. -- **Why put conda under `/opt/abacus-miniforge` rather than `/root`?** - Clean uninstall path, clear ownership, and doesn't interfere with a - user's personal conda install if they later add one inside the same - distribution. -- **Why not ship a pre-built WSL rootfs?** Would cut first-run time from - ~10 min to ~1 min, but balloons the installer from a few KB of scripts - to 300โ€“500 MB, requires CI infrastructure, and needs code signing to - avoid SmartScreen warnings. A scripted online installer is the - lowest-maintenance starting point; the pre-built rootfs path remains - open for a future v1. +- **Why WSL2 + conda-forge instead of a native Windows build?** ABACUS's MPI + ScaLAPACK + ELPA + stack has no reliable native Windows build. Going through WSL2 lets us reuse the Linux binaries + conda-forge already ships, turning a multi-week porting problem into a 200-line shell script. +- **Why a dedicated `Ubuntu-22.04` distribution?** conda-forge ABACUS is built against glibc from + 22.04-era Ubuntu. Using `Ubuntu` (rolling) risks mismatches; pinning the version keeps the install + reproducible. +- **Why put conda under `/opt/abacus-miniforge` rather than `/root`?** Clean uninstall path, clear + ownership, and doesn't interfere with a user's personal conda install if they later add one inside + the same distribution. +- **Why not ship a pre-built WSL rootfs?** Would cut first-run time from ~10 min to ~1 min, but + balloons the installer from a few KB of scripts to 300โ€“500 MB, requires CI infrastructure, and + needs code signing to avoid SmartScreen warnings. A scripted online installer is the + lowest-maintenance starting point; the pre-built rootfs path remains open for a future v1. diff --git a/tools/05_param_generation/README.md b/tools/05_param_generation/README.md index 1f8fcc0f932..df3407cbd25 100644 --- a/tools/05_param_generation/README.md +++ b/tools/05_param_generation/README.md @@ -1,13 +1,11 @@ # DFT-D3 data generator -`generate_d3_data.py` converts immutable numerical data from the pinned -s-dftd3 v1.5.0 source revision into compact C++ include files used by ABACUS. -It is a maintainer tool only: s-dftd3 and mctc-lib are not ABACUS build-time or -run-time dependencies. +`generate_d3_data.py` converts immutable numerical data from the pinned s-dftd3 v1.5.0 source +revision into compact C++ include files used by ABACUS. It is a maintainer tool only: s-dftd3 and +mctc-lib are not ABACUS build-time or run-time dependencies. -The generator verifies every input checksum before parsing it. To regenerate -or check the committed files, provide the s-dftd3 source tree and the mctc-lib -source tree used by that release: +The generator verifies every input checksum before parsing it. To regenerate or check the committed +files, provide the s-dftd3 source tree and the mctc-lib source tree used by that release: ```sh python3 tools/dftd3/generate_d3_data.py \ @@ -21,6 +19,5 @@ python3 tools/dftd3/generate_d3_data.py \ --output-root . --check ``` -Updating the numerical specification is an explicit review event: update the -pinned revision, input checksums, generated files, and s-dftd3 oracle tests in -the same change. +Updating the numerical specification is an explicit review event: update the pinned revision, input +checksums, generated files, and s-dftd3 oracle tests in the same change. diff --git a/tools/README.md b/tools/README.md index c2e081e98ca..162e781d049 100644 --- a/tools/README.md +++ b/tools/README.md @@ -72,6 +72,7 @@ python aveElecStatPot.py --help ### Windows Installation Run as administrator: + ```bash 04_windows_installation/install-abacus.bat ``` @@ -79,6 +80,7 @@ Run as administrator: ## Tool Descriptions ### 01_NAO_generation/ + - **SIAB/** - Simulated Annealing method for NAO optimization (C++) - **pytorch/** - PyTorch gradient method V1 for NAO optimization - **pytorch_dpsi/** - PyTorch gradient method V2 with dpsi calculation @@ -89,6 +91,7 @@ Run as administrator: - **examples/** - Example input files and test cases ### 02_postprocessing/ + - **rt-tddft-tools/** - Tools for real-time time-dependent density functional theory analysis - **stm/** - Tools for generating STM images from LDOS cube files - **average_pot/** - Python script to calculate and plot average electrostatic potential @@ -96,7 +99,9 @@ Run as administrator: - **plot-tools/** - Band structure, DOS, dipole and absorption plotting tools ### 03_code_analysis/ + - **generate_include_analysis.py** - Header file dependency depth analysis tool ### 04_windows_installation/ + - Windows one-click installer via WSL2 + conda-forge