A stable input file for end-users?

[TotoGaz]

Hello there!

I've just posted PR #1910, which is not for merge but is here as a proof of concept (the code is 🙈).

• The goal is to propose a stable input file format to our end-users for a subset of GEOSX.
• We can decide what we want to support "in production" and what we do not want to (we can even add some experimental: true options).
• The goals is not to impose it to our experts who will still benefit from the current situation.

What is done is quite straightforward as explained by the diagram

graph TD
    EU[End user] --> YAML[YAML input]
    YAML -- analyse & transform --> XMLTREE[Parsed XML tree]
    RU[Researcher] --> XML[XML input]
    XML -- parse --> XMLTREE
    XMLTREE --> Simulators

The idea is that the end user builds its input file in a way which is somehow unrelated to the GEOSX current xmls, but really related to what he wants to achieve.
Then a module of GEOSX understands the needs and builds the appropriate tree representation. (Basically what this PR poorly does admittedly).
This "on-the-fly" tree representation can by design be on sync with GEOSX because shipped inside of GEOSX 🤷
(Who writes and maintains such a module is another discussion.)

For instance, I’ve been able to hack (there is some hard code) and run the following Laplace simulation.

version: 0.1

simulation:
  solvers:
    - type: Laplace
      time_integration_option: steady_state
      field_name: temperature
      linear_solver_parameters:
        - direct_parallel: false
  max_time: 2.
  FEM:
    order: 1

mesh:
  - type: generated
    element_type: [ C3D8 ]
    x_range: [ 0, 1 ]
    y_range: [ 0, 1 ]
    z_range: [ 0, 1 ]
    nx: [ 10 ]
    ny: [ 10 ]
    nz: [ 10 ]
    cell_blocks: [ cb1 ]
  - type: box
    name: source
    point_min: [ -0.01, -0.01, -0.01 ]
    point_max: [ 0.01,  1.01,  1.01 ]
  - type: box
    name: sink
    point_min: [ 0.99, -0.01, -0.01 ]
    point_max: [ 1.01,  1.01,  1.01 ]

regions:
  - type: cells
    cell_blocks: [ cb1 ]

sources_and_sinks:
  - field: temperature
    function: Dirichlet
    location: nodes/source
  - field: temperature
    value: 0.
    location: nodes/sink

functions:
  - name: Dirichlet
    type: table
    variables: [ time ]
    coordinates: [ 0.0, 1.0, 2.0 ]
    values: [ 0.0, 3.e2, 4.e3 ]

outputs:
  - type: vtk
    period: 1.
  - type: silo
    period: 1.
    parallel_threads: 32
  - type: restart
    exact_timestep: false
    period: 1.

Note that the tedious and unnecessary definitions of (some) names and events have been handled automatically by GEOSX. And when there is just one name (e.g. for regions or FEM), then it was possible to deduce it (I’m not sure it’s a good idea, but it’s possible).

Also I've tried to provide more colorful sections.
This surely is a wasted attempt, but it may generate ideas.

At some moment, if an existing options is required but not production grade, we can intercept it and tell the user (e.g. kill the simulation unless the --caution-thin-ice options is entered explicitly 🤣 )

Another example could be the way we do TimeHistory.

<Tasks>
  <PackCollection
    name="apertureCollection”
    objectPath="ElementRegions/Fracture/faceElementSubRegion”
    fieldName="elementAperture"/>
</Tasks>

<Outputs>
  <TimeHistory
    name="timeHistoryOutput”
    sources="{/Tasks/apertureCollection}”
    filename="aperture_history" />
</Outputs> 


<Events>
  <PeriodicEvent
    name="timeHistoryOutput”
    targetExactTimestep="0”
    target="/Outputs/timeHistoryOutput"/>
</Events>

while the meaningful information is

collections:
  - region: regions/fracture/faces # user friendly name
    field: element_aperture

    file_name: aperture_history
    target_exact_timestep: false

(I know that there are options that can be added here and there, but they can also be added in the yaml).

I personally strongly believe that it’s more valuable to work on this module, in order to define stable inputs and only after provide GUI/IDE over something stable. This looks like the right order to me.

Any comments?

[cssherman]

@TotoGaz - This is interesting, thanks for putting it together! A couple of initial thoughts:

1. I like the idea of making 'low-information' inputs optional. Given some restructuring, I expect that we could do this directly in the xml format and provide the shortcut to all users. In the case of events, if we moved the maxTime/maxCycle attributes to problem and had an optional parameter to set the application frequency on ExecutableGroup, we could populate the events block given some simple rules. And as you pointed out, timehistory is another prime target for this.
2. How would you want to handle coupled solvers? Would you expect the user to only input the primary solver, and then require the translator to figure out which child solvers to populate and link? Or do you think that we should list all of the solvers, but only add the first or last to the event queue?
3. Maintainability is an obvious concern, especially for more complicated models. Is there a scalable way to prevent developers from needing to write duplicate code for inputs? Perhaps the translator could iterate over the registered objects on a group and look for them in the yaml?
4. How do you expect a user would go about modifying a yaml input file? Would they be simply modifying template, relying on some yet-to-be developed documentation, or relying on some implicit relationship with the xml?
5. With regards to the GUI under development, I would hope that we produce something that would be useful for a variety of users, and not just lower-level users. Something that I've been considering is incorporating a flag to registered attributes that would indicate the user expertise level (basic, advanced, expert, etc.). This could flexibly limit the degree of information presented to the user (inspired by how the Prusa Slicer handles options). Would this concept be applicable/useful for the yaml input?

[TotoGaz]

1. ... I expect that we could do this directly in the xml format and provide the shortcut to all users...

We can surely do the same for all users and file formats, but do we want to?
Would that fit well in our one-to-one structure to add “tricks”?

2. How would you want to handle coupled solvers?...

Actually I do not know. But that gives me the opportunity to mention that I expect the construction of the new file format quite challenging (and interesting).
Those two file formats would really have different mindsets: xml is more “how”, yaml is more “what”.
@francoishamon do you have any idea based on your XP with our reservoir engineers?
Do we want to give complete customization?
I don’t know.

3. Maintainability is an obvious concern...

Yes, there is a maintenance issue. But this maintenance is to be weighed as a whole.
We need to include the hours spent by users dealing with complicated and moving input files…
The issues open on github for this or that parameter. Time spent on the phone…
I think that putting some code at this location offers the greatest benefit for the reasons I mentioned in the original post.

I’m convinced that this part of the code can de tedious, that it will require some "team" to maintain some code (or some tables of parameters) to perform the proper translation.
But it’s still eventually better than exposing internals to the end user.

About iterating over registered groups, I’m not sure this is what we want.
yaml must be controlled. Any automatic process may let any modification pop through.
Also, we may not always have a one to one bindings: like any translation, you may need multiple words to translate one concept!

4. How do you expect a user would go about modifying a yaml input file? ...

I did think about this too much, but I guess that users take a tutorial or an integrated test and modify it for their needs.
That’s what I had im mind.
I did not have in mind to rely on xml since I’d prefer those two worlds to be as separated as possible.

5. ... expertise level (basic, advanced, expert, etc.)...

My goal with this new file format is also to be able to distinguish between production grade for which industrial partners need a strong support, and research.
I totally into a process that would allow to access experimental features, as long as it’s explicitly validated by the user.
Now, I could not find in the “Prusa Slicer”, but let’s get inspired.

[klevzoff]

@TotoGaz @cssherman would you agree that this translation layer would be easier to implement in Python than in C++? Perhaps it could be part of the preprocessing workflow, and would benefit simultaneously from other preprocessor features (parameters, units, symbolic math) so long as they are syntactically compatible with YAML?

[TotoGaz]

I’ve been thinking about using python instead of C++ too.
And surprisingly, I’m not so convinced that this gets easier in python.

Because using the C++ json lib, it’s really easy to bind json nodes into the appropriate C++ class or struct.
So very fast you get your containers of real C++ classes you’ll be working on.
You’ll get something statically readable, which always helps. (And with modern c++, this kind of code can even be quite smooth to read and write).

In python, nothing looks more than a dict or a key than another dict or key.
And you always struggle to know which type you manipulate.
An insertion in a xml node looks like the same than the insertion into a json node…
And for this kind of key/value maze, you can get lost easily…

But I know that we could do some type hints in python now. To be investigated.

Things that decided me into C++ is that indeed no pre-processing/workflow is needed.
If we build a pre-processing strategy, how can we be sure that the engineer won’t use a wrong version of the generated file? That they won’t forget to call the translator again?
That the generated file can be written on disk? Maybe you have the permissions to read, not to write? Maybe you're out of quota. It's easy to fix when you know about it. But in my world this ends up to the support team.
The failure modes are legion and I’m sure half of them will happen in less than 3 months. And support's phone will ring.

Not to mention that it means that we would have to deploy those two tools consistently and that users will need to use consistent versions.

Plus I would have to deploy a python tool and all it’s dependencies in some "proxyfied" env.
Surely possible, but if I could avoid this :)

Another point is that I imagined that having the translator and the solvers in the same location/language could help at making them consistent. But it’s maybe just a feeling.

We could also imagine that the preprocessor would flush the output a linux pipe and that geosx would read the input from stdin?
Or the preprocessor will wrap the geosx call, but that's surely complicated to deal with all the cases (mpirun? srun? env?...)

On the other side, all the features symbolic stuff, units, can be really helpful in the long term, so this is to be weighed.

EDIT: And of course, it's possible to make geosx output the generated xml tree as well.

[cssherman]

I'm obviously biased towards python, but I see the advantages of both. I think that developers could find it less intimidating to build an xml document compared to properly initializing objects in GEOSX. On the other hand, having the translator in the code could help with certain types of refactoring that could happen in the future.

In terms of deployment, I expect that we could use a similar approach to the geosx_xml_tools package. Aside from the odd issue with the system python that one of our users ran into (which we probably shouldn't be using anyway as that can cause bad side-effects), the build process hasn't been an issue. As long as the user doesn't try to install the tool in a separate environment, the tool should be in sync with the version of GEOSX. Also, the current version of the geosx_preprocessed wrapper script seems to be working well with the run systems I've tested.

As far as writing the equivalent xml file to disk is concerned, I believe that this should be the default behavior. In addition to providing a useful record for debugging, it would allow us to cross-check the record against the xml schema. If we are concerned about write permissions, then we could place the file in the geosx output directory. If the user has permission and/or quota errors there, then they would have much bigger problems to worry about.

If we wanted to adapt the existing parameter, symbolic expression, and unit handling tools, they are each regex handlers that are applied to the xml attributes. We could easily apply these to another structured format.

[cssherman]

Another thought: what are your thoughts on including external files in the new format? Does that increase the complexity too much for a typical user?

[TotoGaz]

I think that developers could find it less intimidating to build an xml document compared to properly initializing objects in GEOSX.

I'm not sure to fully understand the comments about this. xml input remains unchanged?...

In terms of deployment, I expect that we could use a similar approach to the geosx_xml_tools package.

Actually I do not know which approach is yours, but for my company, if geosx_xml_tools it's more some kind of Hail Mary pass than something under control. It's most probably not working because it's another complete environment to deal with.
Currently the C++ env is controlled. The python env is not properly considered.

Deploying geosx_xml_tools imposes to define the version of python, where to install the dependencies... Those kinds of funny stuff. And being sure that the users do nothing fancy with python is complicated (with python everybody thinks it's OK, so everybody's playing the fool).

As long as the user doesn't try to install the tool in a separate environment, the tool should be in sync with the version of GEOSX. Also, the current version of the geosx_preprocessed wrapper script seems to be working well with the run systems I've tested.

Oh yes, we can make it work for sure.

If we are concerned about write permissions, then we could place the file in the geosx output directory. If the user has permission and/or quota errors there, then they would have much bigger problems to worry about.

Yes this is a solution for the tmp output file.
That does not solve the forgetful discrepancies between xml and yaml or the potentially dangerous overwriting of input files, input/output traceabilities... which are inherent to any workflow pattern.

My opinion is that everywhere you open a breach (like a workflow would do), then it can break. And it will.
So we should be sure that there is a meaningful to let it happen.

If we wanted to adapt the existing parameter, symbolic expression, and unit handling tools, they are each regex handlers that are applied to the xml attributes. We could easily apply these to another structured format.

unit handling can be addressed in any language quite conveniently for sure. Maybe easier in python though.
While the symbolic expression seems complicated to achieve in c++.

Another thought: what are your thoughts on including external files in the new format? Does that increase the complexity too much for a typical user?

I do not have any specific thinking about this.
I think that yaml does not grant standard feature for this so having an include keyword like we do have in xml looks fine.
But this is a feature that a typical user can manage. And if he cannot, this also the kind of feature he's free not to use.

[untereiner]

Would it be worth having a fully typed configuration language like dhall ? (instead of yaml)