Feature request: Support global environment variables for pseudopotential and orbital directories

[KylinGuo]

Background

In current ABACUS workflows, users must explicitly specify pseudo_dir and orbital_dir in every input file. This leads to several practical issues:

1. Repetitive input files

The same directory paths are duplicated across many calculations.

2. Poor portability

Input files become machine-specific (e.g. local workstation vs. HPC cluster).

3. Fragility

If pseudo_dir or orbital_dir is incorrectly specified (typo, moved directory, symbolic link failure), the calculation fails immediately, even though valid default paths may exist.

Introducing global environment variables would:

• Simplify input files
• Improve robustness
• Align ABACUS with common practices in other DFT codes

Describe the solution you'd like

Summary

I would like to propose adding support for two global environment variables in ABACUS:

• ABACUS_PP_PATH → default (and fallback) for pseudo_dir
• ABACUS_ORBITAL_PATH → default (and fallback) for orbital_dir

These variables would provide robust default search paths for pseudopotential and numerical orbital files, similar to how Quantum ESPRESSO uses ${ESPRESSO_PSEUDO} as the default value of pseudo_dir.

Proposed behavior

New environment variables

• ABACUS_PP_PATH: directory containing pseudopotential files
• ABACUS_ORBITAL_PATH: directory containing numerical orbital files

Resolution logic (recommended)

For each directory, ABACUS would resolve paths in the following order:

1. User-defined value in input file

• pseudo_dir
• orbital_dir

2. Environment variable fallback

• ABACUS_PP_PATH
• ABACUS_ORBITAL_PATH

3. Error

• If neither is defined or accessible, raise a clear error message

This fallback behavior ensures that even if the user-defined directory does not work, a valid environment-level default can still be used.

This proposal mirrors that well-established design, while keeping ABACUS-specific variable names that are:

• Explicit (ABACUS_*)
• Unambiguous
• Unlikely to conflict with other DFT codes

Task list only for developers

• Notice possible changes of behavior
• Explain the changes of codes in core modules of ESolver, HSolver, ElecState, Hamilt, Operator or Psi

Notice Possible Changes of Behavior (Reminder only for developers)

No response

Notice any changes of core modules (Reminder only for developers)

No response

Notice Possible Changes of Core Modules (Reminder only for developers)

No response

Additional Context

No response

Task list for Issue attackers (only for developers)

• Review and understand the proposed feature and its importance.
• Research on the existing solutions and relevant research articles/resources.
• Discuss with the team to evaluate the feasibility of implementing the feature.
• Create a design document outlining the proposed solution and implementation details.
• Get feedback from the team on the design document.
• Develop the feature following the agreed design.
• Write unit tests and integration tests for the feature.
• Update the documentation to include the new feature.
• Perform code review and address any issues.
• Merge the feature into the main branch.
• Monitor for any issues or bugs reported by users after the feature is released.
• Address any issues or bugs reported by users and continuously improve the feature.

[QuantumMisaka]

I consider this is a good idea, since ASE-ABACUS and abacus-test also use ABACUS_PP_PATH and ABACUS_ORB_PATH as environment variable for PP and ORB.