ogstools.ogs6py.project module#

ogs6py is a python-API for the OpenGeoSys finite element software. Its main functionalities include creating and altering OGS6 input files as well as executing OGS.

class ogstools.ogs6py.project.Project[source]#

Bases: StorageBase

Class for handling an OGS6 project.

In this class everything for an OGS6 project can be specified.

Create a new Project instance.

Parameters:

  • input_file (str | Path | None) – Filename of the input project file

  • output_file (str | Path | None) – Filename of the output project file

  • output_dir (str | Path) – Directory of the simulation output

  • logfile (str | Path) – Filename into which the log is written

  • xml_string (str | None) – String containing the XML tree

  • verbose (bool) – If True, show verbose output

Optional Keyword Arguments:
  • OMP_NUM_THREADS: int, sets the environment variable before OGS

    execution to restrict number of OMP Threads

  • OGS_ASM_THREADS: int, sets the environment variable before OGS

    execution to restrict number of OMP Threads

__init__(input_file=None, output_file=None, output_dir=Path(), logfile='out.log', verbose=False, xml_string=None, id=None, **kwargs)[source]#

Create a new Project instance.

Parameters:

  • input_file (str | Path | None) – Filename of the input project file

  • output_file (str | Path | None) – Filename of the output project file

  • output_dir (str | Path) – Directory of the simulation output

  • logfile (str | Path) – Filename into which the log is written

  • xml_string (str | None) – String containing the XML tree

  • verbose (bool) – If True, show verbose output

Optional Keyword Arguments:
  • OMP_NUM_THREADS: int, sets the environment variable before OGS

    execution to restrict number of OMP Threads

  • OGS_ASM_THREADS: int, sets the environment variable before OGS

    execution to restrict number of OMP Threads

property prjfile: Path#

Get the path to the project file, following the current target.

classmethod from_folder(folder)[source]#

Load Project from a folder containing a default.prj file.

Parameters:

folder (Path | str) – Path to the project folder.

Return type:

Self

Returns:

A Project instance loaded from the folder.

classmethod from_id(project_id)[source]#

Load Project from the user storage path using its ID. StorageBase.Userpath must be set.

Parameters:

project_id (str) – The unique ID of the Project to load.

Return type:

Self

Returns:

A Project instance restored from disk.

dependencies(include_meshes=True, include_python_file=True, include_xml_includes=True)[source]#
Return type:

list[Path]

static dependencies_of_file(input_file, mesh_dir=None, check=False, include_meshes=True, include_python_file=True, include_xml_includes=True)[source]#

Searches a (partial) project file for included files (e.g. xml snippets, meshes (vtu,gml), python scripts) Can be used before constructing a Project object (static function).

Parameters:

  • input_file (str | Path) – Path to the prj-file

  • mesh_dir (str | Path | None) – Optional directory used to resolve referenced mesh files. If omitted, mesh paths is interpreted to be in same folder as input_file.

  • check (bool) – If True, assert that all collected files exist on disk

Return type:

list[Path]

Returns:

A list of dependency file paths (order-preserving, de-duplicated).

Raises:

AssertionError – If check=True and at least one referenced file is missing.

add_element(parent_xpath='./', tag=None, text=None, attrib_list=None, attrib_value_list=None)[source]#

General method to add an Entry.

An element is a single tag containing ‘text’, attributes and anttribute values.

Parameters:

  • parent_xpath (str) – XPath of the parent tag

  • tag (str | None) – tag name

  • text (str | int | float | None) – content

  • attrib_list (list[str] | None) – list of attribute keywords

  • attrib_value_list (list[str] | None) – list of values of the attribute keywords

Return type:

None

add_include(parent_xpath='./', file='')[source]#

Add include element.

Parameters:

  • parent_xpath (str) – XPath of the parent tag

  • file (str) – file name

Return type:

None

add_block(blocktag, block_attrib=None, parent_xpath='./', taglist=None, textlist=None)[source]#

General method to add a Block.

A block consists of an enclosing tag containing a number of subtags retaining a key-value structure.

Parameters:

  • blocktag (str) – name of the enclosing tag

  • block_attrib (Any | None) – attributes belonging to the blocktag

  • parent_xpath (str) – XPath of the parent tag

  • taglist (list[str] | None) – list of strings containing the keys

  • textlist (list[Any] | None) – list retaining the corresponding values

Return type:

None

deactivate_property(name, mediumid=0, phase=None)[source]#

Replaces MPL properties by a comment.

Parameters:

  • mediumid (int) – id of the medium

  • phase (str | None) – name of the phase

  • name (str) – property name

Return type:

None

deactivate_parameter(name)[source]#

Replaces parameters by a comment.

Parameters:

name (str) – property name

Return type:

None

remove_element(xpath, tag=None, text=None)[source]#

Removes an element.

Parameters:
Return type:

None

replace_text(value, xpath='.', occurrence=-1)[source]#

General method for replacing text between opening and closing tags.

Parameters:

  • value (str | int | float) – Text

  • xpath (str) – XPath of the tag

  • occurrence (int) – Easy way to address nonunique XPath addresses by their occurrence from the top of the XML file

Return type:

None

replace_block_by_include(xpath='./', filename='include.xml', occurrence=0)[source]#

General method for replacing a block by an include.

Parameters:

  • xpath (str) – XPath of the tag

  • filename (str) – name of the include file

  • occurrence (int) – Addresses nonunique XPath by their occurrence

Return type:

None

replace_mesh(oldmesh, newmesh)[source]#

Method to replace meshes.

Parameters:
Return type:

None

replace_parameter(name='', parametertype='', taglist=None, textlist=None)[source]#

Replacing parametertypes and values.

Parameters:

  • name (str) – parametername

  • parametertype (str) – parametertype

  • taglist (list[str] | None) – list of tags needed for parameter spec

  • textlist (list[str] | None) – values of parameter

Return type:

None

replace_parameter_value(name='', value=0, valuetag='value')[source]#

Replacing parameter values.

Parameters:

  • name (str) – parametername

  • value (int | float | str) – value

  • parametertype – parameter type

  • valuetag (str) – name of the tag containing the value, e.g., values

Return type:

None

replace_phase_property_value(mediumid=0, phase='AqueousLiquid', component=None, name='', value=0, propertytype='Constant', valuetag='value')[source]#

Replaces properties in medium phases.

Parameters:

  • mediumid (int) – id of the medium

  • phase (str) – name of the phase

  • component (str | None) – name of the component

  • name (str) – property name

  • value (int | float | str) – value

  • propertytype (str) – type of the property

  • valuetag (str) – name of the tag containing the value, e.g., values

Return type:

None

replace_medium_property_value(mediumid=0, name='', value=0, propertytype='Constant', valuetag='value')[source]#

Replaces properties in medium (not belonging to any phase).

Parameters:

  • mediumid (int) – id of the medium

  • name (str) – property name

  • value (int | float | str) – value

  • propertytype (str) – type of the property

  • valuetag (str) – name of the tag containing the value, e.g., values

Return type:

None

set(**args)[source]#

Sets directly a uniquely defined property. List of properties is given in the dictionary below.

Return type:

None

meshseries_file()[source]#
Return type:

Path

run_model(logfile=Path('out.log'), path=None, args=None, container_path=None, wrapper=None, write_logs=True, background=False)[source]#

Command to run OGS.

Runs OGS with the project file specified as output_file.

Parameters:

  • logfile (Path | None) – Name of the file to write STDOUT of ogs

  • path (Path | None) – Path of the directory in which the ogs executable can be found. If container_path is given: Path to the directory in which the Apptainer executable can be found.

  • args (Any | None) – additional arguments for the ogs executable

  • container_path (Path | str | None) – Path of the OGS container file.

  • wrapper (Any | None) – add a wrapper command. E.g. mpirun

  • write_logs (bool) – set False to omit logging

  • write_prj_to_pvd – write the prj file as a comment in the pvd

  • background (bool) – Run the simulation in a background process

Return type:

Popen

write_input(prjfile_path=None, keep_includes=False)[source]#

Writes the projectfile to disk.

Parameters:

  • prjfile_path (None | Path | str) – Path to write the project file to. If not specified, the initialised path is used.

  • keep_includes (bool)

Return type:

None

save(target=None, overwrite=None, dry_run=False, archive=False, keep_includes=False, id=None)[source]#

Saves the project file and referenced files (except meshes)

Parameters:

  • target (Path | str | None) – Optional path to the project folder. If None, a temporary folder will be used.

  • overwrite (bool | None) – If True, existing prj file(s) will be overwritten. If False, an error is raised if any file already exists.

  • dry_run (bool) – If True: Writes no files, but returns the list of files expected to be created If False: Writes files and returns the list of created files.

  • archive (bool) – If True: The folder specified by path contains no symlinks. It copies all referenced data (which might take time and space).

  • id (str | None) – Optional identifier. Mutually exclusive with target.

Return type:

list[Path]

Returns:

A list of Paths pointing to the saved prj file(s)

property_dataframe(mediamapping=None)[source]#

Returns a dataframe containing most properties defined in the Material Property (MPL) section of the input file.

Parameters:

mediamapping (dict[int, str] | None)

Return type:

DataFrame

write_property_latextable(latexfile=Path('property_dataframe.tex'), mediamapping=None, float_format='{:.2e}')[source]#

Write material properties to disc as latex table.

Parameters:
Return type:

None

set_media(media_set)[source]#

Public API: import MediaSet into this Project.

Return type:

None

meshpaths(mesh_dir=None)[source]#

Returns the filepaths to the given meshes in the Project.

This does not include meshes defined via a .gml file.

Parameters:

mesh_dir (Path | None) – Path to the meshes directory (default: input dir)

Return type:

list[Path]

param_value_expression(param_name)[source]#

Return the text of the parameter value/s or expression.

Parameters:

param_name (str) – Name of the parameter whose value is returned.

Return type:

str

constraints()[source]#

Creates a dict of boundary conditions and source terms.

Structured in the following way: {meshname: {process_variable_name: [constraint_data]}}

Return type:

dict[str, dict[str, list]]

constraints_labels()[source]#

Formatted information about boundary conditions and source terms.

Return type:

dict[str, str]

Returns:

Formatted str of constraints per meshname.

Example output:

{
    "domain": "domain:\n  $T$=-8./3600*t+277.15\n  $p$=0",
    "bottom": "bottom:\n  $u$$_y$=0",
    "left": "left:\n  $u$$_x$=0",
}