Project file structure

The main input taken by OpenGeoSys is path to project file. This file has a “.prj” extension and describes all aspects of the simulation that OpenGeoSys is expected to execute.

The syntax of the project file follows the syntax of a typical xml file and can be edited with any editor capable of working with this kind of files.

The structure of the project file is relatively flexible: as long as the semantics of the file are intact, the main blocks can be provided in any order.

Depending on what the simulation is about, the content of project file will differ. However, there are some basic minimum requirement that have to be fulfilled.

This page is not a complete description of XML standard. It only provides enough information to interact with and understand OpenGeoSys "*.prj" files. More details can be found here: XML Standard.

The XML files structure follows an abstract idea of a tree: from roots to leaves. The main tag within any XML file is called root. In OpenGeoSys project files the root tag looks like this: <OpenGeoSysProject> </OpenGeoSysProject>. Between opening and closing tags all the project relevant information is contained. Everything between those tags follows a hierarchical structure. There will be thematic blocks that cover specific aspects of the simulation. They define for example mesh files, or process used in the simulation. Following snippet shows a small structure containing those two (for now empty) blocks:



The blocks <mesh> </mesh> and <processes> </processes> are at the same “level” indicated by the indent. Those are the child elements of the root <OpenGeoSysProject>, which is their parent element. As they are on the same level, they can be described as siblings. This hierarchy is recursive. This means, that each of the child elements can have it’s own child elements and be parent to them (think of family structure: grandparents -> parent -> children -> grandchildren).

In following snippet you can see a <processes> </processes> element containing child element <processes> </processes>, which again contains two child elements: <name> </name> and <type> </type>:


This snippet can be understood in more human readable way as follows:

In this project file used by OpeGeoSys there is one instance of processes, which is called SteadyStateDiffusion and is implemented in OpenGeoSys as type STEADY_STATE_DIFFUSION.


If a value is set between < and >, beside the tag, it is called attribute. For example:

<planet satellite_name="Moon">

Entity “planet” has attribute “satellite_name” set to “Moon”.

In project files, attributes are used in some blocks to distinguished between multiple instances of the same entity. For example media are identified by their attribute “id”:

<medium id="0">

and processes in time loop by the “ref” attribute:

<process ref="SteadyStateDiffusion">


If you want to switch between two version of a certain part of the project file, two values etc, but without need to remove those fragments completely from the file, you can comment them out:

<!--value>this value will be comment out and ignored by OpenGeoSys</value-->
<value>this value will be read and used by OpenGeoSys</value>

Comments cannot be nested. If you try to comment out a block that already contains a commented section - it will result in an error.

More information

More details on what blocks are required/available in the project file and what can they contain, please see: Project file over view.

File encoding

In order to ensure correct encoding, it is a good practice to add following line at the beginning of the project file:

<?xml version="1.0" encoding="ISO-8859-1"?>

This article was written by Feliks Kiszkurno. If you are missing something or you find an error please let us know.
Generated with Hugo 0.101.0 in CI job 303998 | Last revision: February 28, 2023
Commit: [pre-commit] Added black check on markdown notebooks. efed3632  | Edit this page on