Modularizing project files

Project files .prj have to be valid XML documents. For information of specific tags see our Doxygen-documentation.

Two methods allow you to modularize your project files and avoid repetition:

Option 1: Include XML-content from other files

The <include file="other_file.xml" />-tag allows to include the content of another XML into the current project file.

Limitation: Only one child include-element per (regular) XML-element is allowed.

Example

Tests/Data/Elliptic/circle_radius_1/circle_1e1_axi.prj:

    <processes>
        <include file="../cube_1x1x1_SteadyStateDiffusion/SteadyStateDiffusion.xml"/>
    </processes>

Tests/Data/Elliptic/cube_1x1x1_SteadyStateDiffusion/SteadyStateDiffusion.xml:

<process>
    <name>SteadyStateDiffusion</name>
    <type>STEADY_STATE_DIFFUSION</type>
    <integration_order>2</integration_order>
    <process_variables>
        <process_variable>pressure</process_variable>
    </process_variables>
    <secondary_variables>
        <secondary_variable internal_name="darcy_velocity" output_name="v"/>
    </secondary_variables>
</process>

Note on file encoding

Please do not use UTF-8 with BOM-encoding! The BOM-marker from the included file will be included somewhere in the middle of the final prj-file and this will cause OGS’ ConfigTree to crash. In a text editor you typically can convert a file to other encodings. Please also check your text editor for default encodings on creating new files. In general UTF-8 or ISO 8859-1 should be fine.

Option 2: Apply patch files to the project file

Patch files contain <replace>, <add> and <remove>-elements with XPath-selectors to modify a specific part of the project file (in-memory during run-time):

Tests/Data/Elliptic/square_1x1_SteadyStateDiffusion/square_neumann.xml:

<?xml version="1.0" encoding="ISO-8859-1"?>
<OpenGeoSysProjectDiff>
    <add sel="/*/time_loop/output/prefix/text()" pos="after">_neumann</add>
    <replace sel="/*/parameters/parameter[2]/name/text()">p_neumann</replace>
    <replace sel="/*/parameters/parameter[3]/name/text()">p_Dirichlet</replace>
    <replace sel="/*/parameters/parameter[3]/value/text()">1</replace>
    <replace sel="/*/process_variables/process_variable/boundary_conditions/boundary_condition[1]/parameter/text()">p_Dirichlet</replace>
    <replace sel="/*/process_variables/process_variable/boundary_conditions/boundary_condition[2]/type/text()">Neumann</replace>
    <replace sel="/*/process_variables/process_variable/boundary_conditions/boundary_condition[2]/parameter/text()">p_neumann</replace>
    <add sel="/*/process_variables/process_variable/boundary_conditions/boundary_condition[1]" pos="after">
        <boundary_condition>
            <geometrical_set>square_1x1_geometry</geometrical_set>
            <geometry>bottom</geometry>
            <type>Dirichlet</type>
            <parameter>p_Dirichlet</parameter>
        </boundary_condition>
    </add>
</OpenGeoSysProjectDiff>

For more examples see this page on the XML Patch Operations Framework.

Option 2a: Supply patch file(s) additionally to the prj-file

ogs -p path/to/square_1e0_neumann.xml [other/optional/patch_file.xml] path/to/square_1e0.prj

Supplied patch files are applied in the given order.

Option 2b: Use a patch file directly

If the patch file specifies a base_file:

Tests/Data/Elliptic/cube_1x1x1_SteadyStateDiffusion/cube_1e1.xml:

<?xml version="1.0" encoding="ISO-8859-1"?>
<OpenGeoSysProjectDiff base_file="cube_1e0.prj">
    <replace sel="/*/mesh/text()">cube_1x1x1_hex_1e1.vtu</replace>
    <replace sel="/*/time_loop/output/prefix/text()">cube_1e1</replace>
</OpenGeoSysProjectDiff>

you can just pass this patch file:

ogs path/to/cube_1e1.xml

In this case you have just one patch file.

Combination of include and patch method

When both methods are combined the logical order is the following:

Apply patches
Insert includes
Apply patches marked with after_includes="true"-attribute only.

Example:

<?xml version="1.0" encoding="ISO-8859-1"?>
<OpenGeoSysProjectDiff base_file="cube_1e0.prj">
    <!-- The first line is run before the includes: -->
    <replace sel="/*/mesh/text()">cube_1x1x1_hex_1e1.vtu</replace>
    <!-- The following is evaluated after the includes are run: -->
    <replace sel="/*/time_loop/output/prefix/text()" after_includes="true">cube_1e1</replace>
</OpenGeoSysProjectDiff>

Check project file syntax with `xmllint`

You can check the formatting with the xmllint-tool:

xmllint --noout myproj.prj

Installation of `xmllint`

We recommend to install via Chocolatey:

choco install xsltproc

Alternative installation

Another method is to use the Windows Subsystem for Linux where you can simply install Linux packages:

sudo apt-get install libxml2-utils

sudo apt-get install libxml2-utils

xmllint is part of the Homebrew xmlstarlet package:

brew install xmlstarlet

This article was written by Lars Bilke. If you are missing something or you find an error please let us know.
Generated with Hugo 0.122.0 in CI job 504124 | Last revision: November 12, 2024
Commit: [BL/MPI] Use MPI_COMM_WORLD in reduceMin 4aae83e | Edit this page on