Skip to content

Normalize relax_method as a scalar option and deprecate two-token values #7822

Description

@Stardust0831

relax_method is currently defined as a Vector of string so that it can represent both an optimization algorithm and an optional variant:

relax_method cg 1
relax_method cg 2
relax_method bfgs 1
relax_method bfgs 2

However, this value is not a general-purpose vector. The first element selects an algorithm, the second selects a variant of that algorithm, the two positions have different meanings, and the length is limited to two. Modeling it as a string vector therefore makes its type, runtime access, and availability expressions less clear. For example:

relax_method=="cg 2"

Consider normalizing relax_method to a single scalar option and deprecating all two-token forms:

Current input Canonical scalar value
cg cg
cg 2 cg (deprecated alias)
cg 1 cg_nested (deprecated alias)
bfgs bfgs
bfgs 2 bfgs (deprecated alias)
bfgs 1 bfgs_traditional (deprecated alias)
cg_bfgs cg_bfgs

The names cg_nested and bfgs_traditional are only suggestions and can be discussed further. Descriptive scalar names would be easier to understand than numbered two-token values.

Availability expressions could then use ordinary scalar comparisons:

relax_method==cg
relax_method==cg_nested
relax_method==bfgs_traditional

cg 1 selects the nested CG implementation, while cg and cg 2 select the recommended simultaneous implementation. The nested implementation would remain available through a descriptive scalar value such as cg_nested; only the two-token spelling would be deprecated.

During a transition period, all existing two-token forms could remain accepted with deprecation warnings and be converted to their canonical scalar values during input parsing.

The change would likely include:

  • Changing the parameter metadata from Vector of string to a scalar string option.
  • Normalizing current inputs and compatibility aliases during parsing.
  • Adding deprecation warnings for all two-token forms.
  • Replacing runtime access through relax_method[0] and relax_method[1] with named checks or a typed internal representation.
  • Updating availability expressions, parameter documentation, and tests.
  • Preserving the behavior of all existing relaxation algorithms.

Open questions:

  • What should the final variant names be?
  • How long should the compatibility period for the two-token aliases be?
  • Should the internal representation be a canonical string, an enum, or a small typed structure?

Metadata

Metadata

Assignees

No one assigned

    Labels

    Input&OutputSuitable for coders without knowing too many DFT details

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions