Structured INPUT availability

Structured INPUT availability#

Purpose#

Input item availability metadata describes when an INPUT parameter is applicable. It is used by documentation and tooling; it does not reject or alter a user’s INPUT based on this condition. Runtime diagnostics, if added, must define how explicitly supplied parameters whose conditions are false are handled.

Invariants#

  • The C++ Input_Item registration is the source of truth. YAML and Markdown are generated artifacts.

  • Every non-empty registration is canonical. set_availability() rejects syntax errors and non-canonical spelling.

  • The AST is the stored representation; the exported string is serialized from it, so the two forms cannot diverge.

  • Every expression is a complete, independently evaluable predicate. It must include enclosing requirements rather than inheriting them implicitly from a referenced parameter.

  • After all INPUT items are registered, every referenced label, operator and literal is checked against machine-readable parameter type information.

Grammar and meaning#

expression := condition | compound
compound := operand " and " operand (" and " operand)*
          | operand " or " operand (" or " operand)*
operand := condition | "(" compound ")"
condition := parameter comparison value
           | parameter " in [" value ", " value (", " value)* "]"
           | parameter " contains " value
comparison := "==" | "!=" | ">" | ">=" | "<" | "<="
value := bare-value | '"' quote-required-value '"'

The grammar describes the canonical form of a non-empty expression. A compound expression contains only one kind of Boolean operator. When a compound expression is used as an operand of another compound expression, it must be parenthesized, even when operator precedence would make the grouping unambiguous. A single condition must not be parenthesized. For example, (basis_type==pw and calculation==scf) or esolver_type==sdft is canonical, while basis_type==pw and calculation==scf or esolver_type==sdft and (basis_type==pw) are not.

Canonical formatting is required: comparison operators have no surrounding spaces; and, or, in, and contains have one space on each side; and list items are separated by a comma followed by one space. For example, mode in [a, b] is valid, while mode in [a,b] is rejected. Leading or trailing whitespace is not allowed, and a comma is not an alternative spelling of and. The parser accepts only the spelling produced by the AST serializer, so forms such as basis_type == pw and basis_type==pw,calculation==scf are also rejected.

bare-value is a non-empty value containing no whitespace or any of ()[],=<>!. A value containing at least one of those characters must use the non-empty double-quoted form, and a value that does not require quotes must not use them. Thus basis_type==pw and relax_method=="cg 2" are canonical, while basis_type=="pw" is not. == compares one complete value. Two or more alternatives use in [...], while parameter contains value tests whether a vector contains one element, such as td_ttype contains 0. / is an ordinary value character, not another spelling of membership. Ordered comparisons require a numeric scalar.

A path that references a parameter must imply that parameter’s availability. Every and operand is required, while satisfying either branch of an or is sufficient. Repeated and or or groups are order-independent. Different leaf conditions are not related; for example, mode==a does not satisfy mode in [a, b].

Examples:

item.set_availability("basis_type==pw");
item.set_availability("vdw_method in [d2, d3_0]");
item.set_availability("td_ttype contains 2");
item.set_availability("esolver_type==sdft and method_sto==2");

Registration and validation workflow#

  1. Parse and require canonical spelling in set_availability().

  2. Finish registering all Input_Item objects.

  3. Validate referenced parameter names, operator compatibility, literal values, and that every referenced parameter carries its own enclosing requirements on the referencing path.

  4. Serialize the AST into docs/parameters.yaml.

  5. Generate docs/advanced/input_files/input-main.md from that YAML.

Runtime evaluation is outside this metadata contract. Any implementation must define evaluation timing, treatment of defaults and reset values, and warning behavior for explicitly supplied parameters.