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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions