|
| 1 | +# ATAT-ABACUS Interface |
| 2 | + |
| 3 | +## Introduction |
| 4 | + |
| 5 | +`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`). |
| 6 | + |
| 7 | +### Key Features |
| 8 | + |
| 9 | +- **Seamless ATAT Integration**: Works within ATAT's multi-directory enumeration workflow (`1/`, `2/`, `3/`...) |
| 10 | +- **Template-Based Input**: Uses `abacus.wrap` as a template—nearly a native ABACUS `INPUT` file with minimal script-specific annotations |
| 11 | +- **Automatic File Discovery**: Searches `abacus.wrap` upward through parent directories (`./` → `../` → `../../`...) |
| 12 | +- **Smart Pseudopotential/Orbital Matching**: Auto-detects files in `pseudo_dir`/`orbital_dir` by element prefix; explicit override available for ambiguous cases |
| 13 | +- **Flexible Execution Modes**: Supports full pipeline, input-only generation, and post-calculation extraction |
| 14 | +- **Parallel Ready**: Accepts `mpirun`/`srun` prefixes for HPC environments |
| 15 | + |
| 16 | +--- |
| 17 | + |
| 18 | +## Installation |
| 19 | + |
| 20 | +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: |
| 21 | + |
| 22 | +```bash |
| 23 | +chmod +x runstruct_abacus |
| 24 | +``` |
| 25 | + |
| 26 | +### Dependencies |
| 27 | + |
| 28 | +- ATAT toolkit (`cellcvrt`, `kmesh` etc.) must be in `$PATH` |
| 29 | +- ABACUS executable path must be set in `~/.abacus.rc` |
| 30 | + |
| 31 | +--- |
| 32 | + |
| 33 | +## Configuration |
| 34 | + |
| 35 | +### `~/.abacus.rc` |
| 36 | + |
| 37 | +Create this file in your home directory to tell the interface where ABACUS lives: |
| 38 | + |
| 39 | +```bash |
| 40 | +#!/bin/bash |
| 41 | +ABACUSCMD="abacus" # or "mpirun -np 4 abacus" |
| 42 | +``` |
| 43 | + |
| 44 | +The script will auto-generate a template if this file does not exist. |
| 45 | + |
| 46 | +--- |
| 47 | + |
| 48 | +## Template File: `abacus.wrap` |
| 49 | + |
| 50 | +`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. |
| 51 | + |
| 52 | +### Minimal Example |
| 53 | + |
| 54 | +```bash |
| 55 | +INPUT_PARAMETERS |
| 56 | +calculation vc-relax |
| 57 | +ecutwfc 50 |
| 58 | +basis_type lcao |
| 59 | +kspacing 0.15 |
| 60 | +pseudo_dir /path/to/pseudopotentials |
| 61 | +orbital_dir /path/to/numerical_orbitals |
| 62 | + |
| 63 | +species Al 26.982 Al_ONCV_PBE-1.0.upf Al_gga_7au_60Ry_2s2p1d.orb |
| 64 | +species Fe 55.845 Fe_ONCV_PBE-1.0.upf Fe_gga_8au_100Ry_2s2p2d1f.orb |
| 65 | +``` |
| 66 | + |
| 67 | +### `species` Syntax |
| 68 | + |
| 69 | +```bash |
| 70 | +species <Element> <Mass> <PP_File> [<Orb_File>] |
| 71 | +``` |
| 72 | + |
| 73 | +| Field | Description | |
| 74 | +| ---------- | ------------------------------------------------------------ | |
| 75 | +| `Element` | Chemical symbol (e.g., `Al`, `Fe`) | |
| 76 | +| `Mass` | Atomic mass. Use `-` to look up from the built-in table | |
| 77 | +| `PP_File` | Pseudopotential filename. Use `-` to auto-search in `pseudo_dir` | |
| 78 | +| `Orb_File` | Numerical orbital filename (required for LCAO). Use `-` to auto-search in `orbital_dir` | |
| 79 | + |
| 80 | +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. |
| 81 | + |
| 82 | +--- |
| 83 | + |
| 84 | +## Command Line Options |
| 85 | + |
| 86 | +```bash |
| 87 | +runstruct_abacus [-w file] [-nr] [-ex] [-clean] [cmdprefix] |
| 88 | +``` |
| 89 | + |
| 90 | +### Execution Modes |
| 91 | + |
| 92 | +| Command | Behavior | |
| 93 | +| ------------------------- | ------------------------------------------------------------ | |
| 94 | +| `runstruct_abacus` | **Full pipeline**: Generate `INPUT` + `STRU` → Run ABACUS → Extract `energy`, `str_relax.out` | |
| 95 | +| `runstruct_abacus -nr` | **No-Run**: Generate `INPUT` + `STRU` only. Useful for manual inspection or external job schedulers. | |
| 96 | +| `runstruct_abacus -ex` | **Extract-Only**: Skip generation and execution. Extract results from existing `OUT.suffix/` directory. | |
| 97 | +| `runstruct_abacus -clean` | **Cleanup**: Delete all output files (`OUT.*/`, `running_*.log`, `energy`, `str_relax.out`) and exit. | |
| 98 | + |
| 99 | +### `cmdprefix`: Running in Parallel |
| 100 | + |
| 101 | +The optional `cmdprefix` argument lets you prepend any launch command—most commonly MPI wrappers: |
| 102 | + |
| 103 | +```bash |
| 104 | +# Run with 4 MPI ranks |
| 105 | +runstruct_abacus "mpirun -np 4" |
| 106 | + |
| 107 | +# Run with srun (SLURM) |
| 108 | +runstruct_abacus "srun -n 8" |
| 109 | + |
| 110 | +# Run on a specific node (similar to Abinit's node-prefix syntax) |
| 111 | +runstruct_abacus "ssh node02 mpirun -np 16" |
| 112 | +``` |
| 113 | + |
| 114 | +The prefix is inserted directly before `$ABACUSCMD`: |
| 115 | + |
| 116 | +```bash |
| 117 | +$CMDPREFIX $ABACUSCMD > log.out 2>&1 |
| 118 | +``` |
| 119 | + |
| 120 | +### `-w`: Custom Wrap File |
| 121 | + |
| 122 | +```bash |
| 123 | +runstruct_abacus -w my_custom.wrap |
| 124 | +``` |
| 125 | + |
| 126 | +If the specified file is not found in the current directory, the script searches upward (`../`, `../../`, `../../../`) exactly like the default `abacus.wrap`. |
| 127 | + |
| 128 | +--- |
| 129 | + |
| 130 | +## Workflow Example |
| 131 | + |
| 132 | +### Standard ATAT Workflow |
| 133 | + |
| 134 | +```bash |
| 135 | +# Inside a numbered ATAT subdirectory, e.g., 1/, 2/, ... |
| 136 | +cd 1/ |
| 137 | + |
| 138 | +# 1. Generate inputs and run |
| 139 | +runstruct_abacus |
| 140 | + |
| 141 | +# 2. Or generate only, then submit to cluster manually |
| 142 | +runstruct_abacus -nr |
| 143 | +# ... user submits job via qsub/sbatch ... |
| 144 | +runstruct_abacus -ex # extract after job finishes |
| 145 | + |
| 146 | +# 3. Clean and restart if needed |
| 147 | +runstruct_abacus -clean |
| 148 | +runstruct_abacus |
| 149 | +``` |
| 150 | + |
| 151 | +### Output Files |
| 152 | + |
| 153 | +| File | Description | |
| 154 | +| --------------- | ------------------------------------------------------- | |
| 155 | +| `INPUT` | ABACUS control parameters (filtered from `abacus.wrap`) | |
| 156 | +| `STRU` | ABACUS structure file (lattice, species, coordinates) | |
| 157 | +| `energy` | Final total energy in **eV** (ATAT standard unit) | |
| 158 | +| `str_relax.out` | Relaxed structure in ATAT `str.out` format | |
| 159 | +| `log.out` | Raw ABACUS stdout/stderr | |
| 160 | + |
| 161 | +--- |
| 162 | + |
| 163 | +## File Search Hierarchy |
| 164 | + |
| 165 | +Both `abacus.wrap` and `str.out` follow ATAT's upward-search convention: |
| 166 | + |
| 167 | +| File | Search Order | |
| 168 | +| ------------- | -------------------------------------- | |
| 169 | +| `abacus.wrap` | `./` → `../` → `../../` → `../../../` | |
| 170 | +| `str.out` | `str_hint.out` (preferred) → `str.out` | |
| 171 | + |
| 172 | +This allows a single `abacus.wrap` (and optionally a shared `~/.abacus.rc`) to serve an entire ATAT enumeration tree. |
| 173 | + |
| 174 | +--- |
| 175 | + |
| 176 | +## Authors |
| 177 | + |
| 178 | +- Shengjun Chen (陈胜君) @ Peking University |
| 179 | + |
| 180 | +## License |
| 181 | + |
| 182 | +[Fill in according to your project license] |
| 183 | + |
| 184 | +## Contact |
| 185 | + |
| 186 | +For issues related to the ABACUS engine itself, please visit: |
| 187 | +- GitHub: [deepmodeling/abacus-develop](https://github.com/deepmodeling/abacus-develop) |
0 commit comments