[EPIC] TTE code sharing and new python packages organization proposal

What is the requested feature?

Various Python tools were developed by TotalEnergies to visualize and process GEOS inputs/outputs. These codes may however benefit to the whole GEOS community (e.g., #50) and can be shared. Some common needs (e.g., #16) may also be addressed once instead of multiple times. To this end, this epic aims to share in the GEOS repository TotalEnergies Python tools and reorganize/refactor python projects to merge duplicated codes.

Is your request related to a specific problem?

• Need to share TotalEnergies Python tools that will benefit to the whole GEOS community,
• Reorganized and refactor python projects, to avoid duplicated codes and improve dependency management (cf. proposed organisation)

Describe the solution you'd like

We propose first to integrate TotalEnergies code to geosPythonPackages as they currently are, then a refactoring of the whole project to merge duplicated codes and update package dependencies.

The proposed organisation is the following, as described in the attached document:

• Data structures and processing packages:
  • geos-ats:
  • hdf5-wrapper:
  • geos-xml-tools: reader, writer, split or merge tools, check tools for geos-xml file.
  • geos-mesh: IO, statistics, procesing tools of meshes based on vtk data structure.
  • geomechanics: Data structures and geomechanical properties calculation functions
• API packages:
  • xml-vtk: Convert geos-xml to vtk objects and conversely.
  • geos-prop: Pre-procssing tools as vtk filters including mesh-doctor features
  • geos-posp: Post-processing tools as vtk filters including geos output mesh cleaning and new properties calculation filters
• Script packages:
  • geos-timehistory: plot time serie curves from geos hdf5 (and csv) files
  • geos-xml-viewer: Input object visualization tool from geos-xml based on pyvista
  • mesh-doctor: pre-processing scripts
  • geos-trame: xml interactive viewer and editor
• Paraview (PV) plugins:
  • geos-pv: paraview plugins to wrap API packages

The proposed new organisation aims at splitting processing packages from user-interface packages (i.e., script or IHM-based packages). This organisation was initially proposed by @untereiner who applied it to packages hdf5-wrapper (processing) and geos-timehistory (script).

Advantages are:

• to use same processing modules in multiple user-interface packages
• avoiding duplicated codes and easing code maintenance
• better management of package dependencies

For instance, PR #16 deals with the need to use mesh-doctor tools through Paraview in addition of current scripts. This need requires to either duplicate code or introduce a dependency of Paraview to the whole geos-mesh package, resulting in introducing a dependency of Paraview plugins to pyvista. It is not recommended since Paraview and pyvista are both user-interface modules (the former through an IHM, the latter through APIs) with similar functionalities. The integration of TotalEnergies code into geosPythonPackages will raise similar issues.

Proposed roadmap

1. TotalEnergies code sharing:

• #56
• #58
• #59
• #63
• #69
• #104
• #106
• #125
• #136
• #135
• #92
• Move GeosBlockExtractor to geos-processing (#142)
• Move GeosBlockMerge to geos-processing (#163)
• #131
• #139
• #173
• #174
• #70
• #166
• Integration of Makutu code (#47 and #52)
• Add TotalEnergies existing mesh statistic code to geos-mesh package (#95)
• #61

2. #80 :

• Create vtk filter for mesh-doctor generate_global_ids in geos-mesh
• Create vtk filter for mesh-doctor collocated_nodes in geos-mesh
• Create vtk filter for mesh-doctor element_volumes in geos-mesh
• Create vtk filter for mesh-doctor fix_elements_orderings in geos-mesh
• Create vtk filter for mesh-doctor generate_fractures in geos-mesh
• Create vtk filter for mesh-doctor non_conformal in geos-mesh
• Create vtk filter for mesh-doctor self_intersecting_elements in geos-mesh
• Create vtk filter for mesh-doctor supported_elements in geos-mesh
• Create mesh-doctor package and update with vtk filters
• Create Paraview plugins for mesh-doctor vtk filters (#16)
• #51 and merge with TotalEnergies codes

3. geos-xml-tools refactoring

• Gather python codes that process GEOS xml files from geos-xml-tools, geos-xml-viewer, geos-trame (#76)
• Create xml-vtk package with xml-vtk conversion vtk filters
• Refactor geos-xml-viewer to update with xml-vtk package
• Refactor geos-trame to update with xml-vtk package
• (Optional) Create Paraview plugins for xml-vtk filters
• #25

PythonPackagesProposal.pdf
updatePythonPackagesProposal_09042025.pdf