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:
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?
relax_methodis currently defined as aVector of stringso that it can represent both an optimization algorithm and an optional variant: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:
Consider normalizing
relax_methodto a single scalar option and deprecating all two-token forms:cgcgcg 2cg(deprecated alias)cg 1cg_nested(deprecated alias)bfgsbfgsbfgs 2bfgs(deprecated alias)bfgs 1bfgs_traditional(deprecated alias)cg_bfgscg_bfgsThe names
cg_nestedandbfgs_traditionalare 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:
cg 1selects the nested CG implementation, whilecgandcg 2select the recommended simultaneous implementation. The nested implementation would remain available through a descriptive scalar value such ascg_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:
Vector of stringto a scalar string option.relax_method[0]andrelax_method[1]with named checks or a typed internal representation.Open questions: