High-level components over FieldSpecification (e.g. PermeabilitySpecification) and there direction

[kdrienCG]

Hi,

I'm opening this discussion to have a central place to discuss about the PermeabilitySpecification (from PR #4019) and future components like it.
The goal is to have a clear view of what is desired and what is not regarding the direction proposed with those components, and to provide a place where you can express concerns or ask questions about the direction or its implementation.

Here is what is proposed and the goals with this direction:
The objective is to add "high-level" field specification components to improve the experience for both the users and developers.

These components would provide several benefits that are difficult (or impossible) to achieve with the current FieldSpecification:

• Expose only the relevant XML attributes to the user for the specific fieldName targeted by the component.

• Provide a proper documentation for the specialized field specification. This would benefit from the already existing (auto-)generated documentation (and future improvements, see feat: add limits to input attributes #4063 that adds documentation for possibles ranges of values accepted by a Wrapper), as well as dedicated written explanations. Because only relevant attributes are present, it will remove any "non-relevant" attributes from needing to be explained to the user.

• Establish a standard way to document user-facing fields. Currently, when a developer adds a field he should not forget to document if it is usable by the user, and there is no dedicated places or list for a user to find which fields are available, except from the examples. We want to provide a standard way to expose public ones and keep internal ones hidden. For example, a user might be tempted to use the initialPressure field name present in GEOS, but he shouldn't because it is auto-filled by the pressure field, he should instead use pressure with initialCondition=1 for this.

  Note that in the pressure example, the field name pressure could be inferred in a PressureSpecification component and the only way to define an initial pressure for the user would be to toggle initialCondition

• Provide specialized validation for each specification, warning the user when entering incoherent values. This could be done directly in the data classes (via postInputInitialization() for example), making those classes responsible for the correctness of the values they own, and reducing the validation made by other. Those validations could easily point the user to the correct line and character position in the XML where the incoherent value is. Also, because the specialized field specification knows which field it targets, we would be able to validate values in meshes.

• Hide implementation details from those interfaces. Since implementations are likely to evolve, exposing these details in user files risks breaking them when changes occur. These interfaces should represent user intent in an implementation agnostic way, as much as possible.

We propose to implement those interfaces as lightweight Group classes, as the Group supports all of this: it gives developers a single place to document, validate, and optionally process user input.

The flexibility offered by FieldSpecification is not affected. The goal is not to remove it, but to provide a safer default alternative for common use cases, while still keeping FieldSpecification available for advanced user, scenarios that require explicit data access and testing cases. Specialized components are built on top of it to ensure testing and support.

Other specialized field specifications will follow. For example, component fractions with constraints such as sum = 1.0, implemented by creating multiple FieldSpecification entries under the hood.