Work plan for input file stabilisation

Hello, this issue propose a way to stabilize input files for GEOSX. It follows discussion https://github.com/GEOSX/GEOSX/discussions/1911. Open for comments.

STEP 0: Share the action plan with partners.

STEP 1: Improving travis.

Resources : developers
Done in https://github.com/GEOS-DEV/GEOS/pull/2850

If we define an API, we have to be able to make sure that we don't break it.
For that, let's start by being able to play the built-in tests on travis (maybe on 2 CPUs only).

• Create a dedicated travis stage, launched after the builds.
• To get a compiled version of geosx, we can
  • Deploy a geosx docker.
  • Use the already existing automatic deployment. Probably a good idea.
• Play the integrated tests in the CI. But be careful because:
  • We need to clone the integratedTests repository
    • It's git-lfs (clone + data limitations)
    • It is private so we have to set up authentication.
  • What are the implications for our validation of always-up-to-date submodules?

The benefit is immediate even without the API. Validating GEOSX on our integrated tests from travis, without waiting for the nightly build, would be useful.

STEP 2: Definition of version 0 of the API (not the implementation, simply the API).

Resources: mainly users.
Can be done in parallel with STEP 1.

• Definition of functionalities validated for production.
• Definition of the use of experimental features.
  • Will we allow it?
  • What would be the mechanisms to activate experimental features?
• Workshop with users, comparison with other simulators.
• Choose a file format (yaml, toml, other?)
  • Check parsing solutions.

STEP 3: API implementation.

Resources: developers.
Even if we can start after STEP 1, it is probably better to have finished STEP 2.

• Make a choice of architecture: should the process be in C++ in geosx. Or should we implement a converter (in python) outside of geosx? Should this result in a new file? Could we pipe the yaml into geosx such that we have a single source of truth?
• If C++ gets chosen, put the parsing library into the TPL.
  • Check the availability of an LLNL/spack package. Otherwise it will have to be implemented.
• Implement some (integrated?) tests on the API.
  • Replicate some xml tests to keep the same reference files?
• Work on regions and any other subjects alike. (The idea is not to tolerate inaccuracies in the API.)
  • Remove sub*Regions from XML interface? Is it necessary not to see them in the API? Most probably but not certain.
• Implement the API.
  • Think about API version management in GEOSX? How should GEOSX handle multiple APIs at the same time (not necessarily useful as it's normally stable).
  • Think about the CLI.
  • Think about the validation of the input.
  • Keep the possibility to output the converted XML (for experts and support).
  • Will we allow default parameters?
  • ...
• Play API tests in travis.

STEP 4: Long-term API documentation.

Resources: developers + users.
After STEP 2.

Construction of a “documentation” of the API (stricto sensu, we must be able to work on the subject from the end of STEP 2).

• Which format to use? Swagger is classic for webservices APIs that use json or yaml. Swagger which should also allow automatic validations and completion. Is it relevant?
• Management of the publication (on readthedocs?) of the API documentation?
• More end user oriented documentation is to build as well. (Tutorials, etc.)

STEP 5: Only now developing a smart GUI makes sense 😇

@jeannepellerin @herve-gross

Start with discussion 1911 and the completed Travis/integratedTests work described in STEP 1. Review the unresolved API, input-format, parsing, testing, CLI, and documentation items across STEPS 2–4; the issue has no single implementation entry point or defined completion criterion.