Ogs input file syntax

Hello there,

i have two questions regarding the ogs6 input file syntax:

  1. On your website Project file syntax (opengeosys.org) it reads that the .prj files are xml documents, there is a list of keywords, a example how to include other files but there is in fact (at least as far i could see) no complete description of your input file syntax.

→ What is the minimal set of madatory instructions for each process to get a valid result in return?

→ What are the optional parameter and their default values per process?

I could not find any of these informations and picking them one by one out of the multiple benchmark examples is cumbersome in my regard.

  1. Why is there no proper use of XML attributes?

Example 1:

...
<processes>
 <process>
  <name>THERMO_HYDRO_MECHANICS</name>
    <type>THERMO_HYDRO_MECHANICS</type>
    <integration_order>4</integration_order>
    <dimension>2</dimension>
    ...

I think a better human-readable xml file would be:

...
<processes>
 <process name="THERMO_HYDRO_MECHANICS" type="THERMO_HYDRO_MECHANICS"
integration_order="4" dimension="2">
    ...

Example 2:

...
<phases>
 <phase>
  <type>AqueousLiquid</type>
   <properties>
    <property>
     <name>specific_heat_capacity</name>
     <type>Constant</type>
     <value>4280.0</value>
    </property>
   <property>
  <name>thermal_conductivity</name>
   <type>Constant</type>
   <value>0.6</value>
 </property>
<property>
...

alternatively:

...
<phases>
 <phase type="AqueousLiquid">
  <properties>
   <property name="specific_heat_capacity" type="Constant">4280.0</property>
   <property name="thermal_conductivity" type="Constant">0.6</property>
...

Sometimes XML Elements seems to be ambigious
In a benchmark (square_1e2_lin.prj) i could find

...
<process_variables>
 <displacement>displacement</displacement>
 <pressure>pressure</pressure>
 <temperature>temperature</temperature>
</process_variables>
...

at Project file syntax (opengeosys.org) it is written

...
<process_variables>
 <process_variable>pressure</process_variable>
</process_variables>
...

My suggestion would be something like

...
<process_variables>
 <variable type="displacement" name="displ1" />
 <variable type="pressure" name="pres1" />
 <variable type="temperature" name="temp1" />
</process_variables>
...

I think proper use of XML attributes (Pair(name,value)) would greatly simplify reading and writing ogs6 input files, as they could mostly share the same names (type, name,…).
Futhermore I think it would help to define and describe some standard xml elements which are needed to create a valid prj-file (if not already available).
Just my two cents…

Best, Max

Hi Max,

I like your suggestions. The reasons for the current structure are mostly historical.

For the first question the answer is: it depends; different processes require different set of xml elements, same for most other items like parameters and properties. There is an overview on the doxygen page for most things.

Suggested use of attributes for the Constant type properties looks good. How would you write a van Genuchten capillary pressure saturation property using attributes? Taken from this example:

                <property>
                    <name>saturation</name>
                    <type>SaturationVanGenuchten</type>
                    <residual_liquid_saturation>0.0</residual_liquid_saturation>
                    <residual_gas_saturation>0.0</residual_gas_saturation>
                    <exponent>0.4</exponent>
                    <p_b>42e6</p_b>
                </property>

Given time, we are working on an xsd file, but progress is slow. Our project file structure requires, unfortunately, xsd-1.1 if not schematron to be used.

– d

Hi,

that i understand, I think your format works in general, but maybe could be improved in terms of readibility and stringency of abstraction easily, if you ever work on it anyway.

Regarding your question: it depends on the desired abstraction; either you nest the property elements or use a value element:

<property name="saturation" type="SaturationVanGenuchten">
  <property name="residual_liquid_saturation" type="Constant">0.0</property>
  <property name="residual_liquid_saturation" type="Constant">0.0</property>
  <property name="exponent" type="Constant">0.4</property>
  <property name="p_b" type="Constant">42e6</property>
</property>

or

<property name="saturation" type="SaturationVanGenuchten">
  <value name="residual_liquid_saturation" type="Constant">0.0</value>
  <value name="residual_liquid_saturation" type="Constant">0.0</value>
  <value  name="exponent" type="Constant">0.4</value>
  <value name="p_b" type="Constant">42e6</value>
</property>

I like the former attempt. I think it’s a nice abstraction that each property has to have the mandatory attributes “name” and “type” at least.
If type is “Constant” or “Domain” the value of the xml element would be a number or a file, respectively, if the type is something else like “SaturationVanGenuchten” the value of the element could be properties again, specifying the parent property.
Btw: I think wrappers like the “properties” element, enclosing a set of “property” elements are unnecessary in general.

Best, Max

I appreciate your input. At some point there will be a breaking change for the input file formats.

One more question, what do you think about the following structure?

<properties>
   <Constant name="saturation">
      <value>0.5</value>
   </Constant>
   <SaturationVanGenuchten name="saturation">
      <residual_liquid_saturation>0.0</residual_liquid_saturation>
      <residual_gas_saturation>0.0</residual_gas_saturation>
      <exponent>0.4</exponent>
      <p_b>42e6</p_b>
   </SaturationVanGenuchten>
</properties>

My point is to emphasize the different types related to the internal representation/use in the code.

– d

I’m afraid I don’t think that this is a good idea. The set of tags should be as small as possible and should just be expanded if absolutely necessary.

As an example think of the vtu-xml-files, which are supported by ogs:
Here tags are things like “Celldata”, “Dataarray”, etc and things like “MaterialID”, “connectivity” are further specifying the tags.

Your tag “Constant”, in my understandig of xml-styling, is clearly an attribute further specifying the format of a following value. Your choice is ambigious to me as i would not know if it is more logical to write

<properties>
   <value name="saturation">
      <Constant>0.5</Constant>
   </value>
....
</properties>

or the other way around, which you chose. This propblem is not present in my attempt.

There is a lag of that generality in your approach, since you have to define new tags each time a new property like “SaturationVanGenuchten” is introduced, which means you have to expand your xml-interface in ogs as well.

I think it would be way more elegant to subsume all those things like “specific_heat_capacity”, “SaturationVanGenuchten” etc under a single tag describing what they are: properties; and, consequentely, use the attributes to further specify each property.

This also renders the implementation of a general interface supporting for arbitrary properties much easier. As long as tags don’t change such an interface can remain unchanged forever and as long as the naming of the attributes are the same in code and in the input files, the constructors can be called fully automatically.

P.S.: I looked it up to be able to specify: In this case the CreateProperty.cpp and all of the CreateSaturationVanGenuchten.cpp and similar classes for creating properties can be replaced solely by clever abstraction.

Thank you! I didn’t see the xml this more generic way. Like the idea with common constructors too. When time comes to change the input files we will consider your suggestions.

Glad I could help. I think xml lends itself perfectly for automatic reading/writing of run-time objects from/to human-readable data-files. The natural extension of that idea is JSON, where there is no more need for parsing as JSON-files can be interpreted directly as Javascript objects.