Standard protocol for selecting and loading atoms in ABACUS tools. Invoke when developing tools that require atom indices as input or when users need to select atoms for analysis.
This skill defines the standard mechanism for selecting structure atoms and passing them between tools in the ABACUS-Agent project.
The project enforces a file-based contract for passing atom selections:
stru_basic_selector tool to generate a JSON index file.utils.atom_selection.load_selected_atoms to read the index file in Python code.When you need to select atoms for an operation (e.g., modifying properties, calculating charge difference), DO NOT manually construct lists of indices. Use the stru_basic_selector tool.
Tool: stru_basic_selector (defined in toolbox/ABACUS/stru_reader.py)
# To select top layer Fe atoms
selection_tool.call({
"structure_path": "STRU",
"element": "Fe",
"select_mode": "layer",
"layer_config": {"direction": "C", "num_layers": 1, "side": "top"}
})
# Generates: atom_selection.json containing {"selected_atoms": [1, 5, ...]}
When developing a new Python tool that requires atom indices as input:
Argument Definition: Accept a file path, not a raw list.
Args:
atom_indices_file (str): [PATH_REQUIRED] Path to the JSON file containing selected atoms (generated by stru_basic_selector).
Implementation: Use the standard utility function.
from utils.atom_selection import load_selected_atoms
def call(self, kwargs):
atom_indices_file = kwargs['args'].get('atom_indices_file')
# Standard loading (handles reading, parsing, and error checking)
# Returns: List[int] (1-based global indices)
try:
indices = load_selected_atoms(atom_indices_file, required=True)
except Exception as e:
raise RuntimeError(f"Failed to load atoms: {e}")
# Use indices...
toolbox/ABACUS/stru_reader.py (Lines ~141+)toolbox/ABACUS/utils/atom_selection.py (Lines ~6+)