GEOS XML Tools

The geos-xml-tools python package adds a set of advanced features to the GEOS xml format: units, parameters, and symbolic expressions. See Python Tools Setup for details on setup instructions, and Advanced XML Features for a detailed description of the input format. The available console scripts for this package and its API are described below.

convert_abaqus

Convert an abaqus format mesh file to gmsh or vtk format.

usage: preprocess_xml [-h] [-i INPUT] [-c COMPILED_NAME] [-s SCHEMA]
                      [-v VERBOSE] [-p PARAMETERS [PARAMETERS ...]]

Named Arguments

-i, --input

Input file name (multiple allowed)

-c, --compiled-name

Compiled xml file name (otherwise, it is randomly genrated)

Default: ''

-s, --schema

GEOSX schema to use for validation

Default: ''

-v, --verbose

Verbosity of outputs

Default: 0

-p, --parameters

Parameter overrides (name value, multiple allowed)

Default: []

format_xml

Formats an xml file.

usage: format_xml [-h] [-i INDENT] [-s STYLE] [-d DEPTH] [-a ALPHEBITIZE]
                  [-c CLOSE] [-n NAMESPACE]
                  input

Positional Arguments

input

Input file name

Named Arguments

-i, --indent

Indent size

Default: 2

-s, --style

Indent style

Default: 0

-d, --depth

Block separation depth

Default: 2

-a, --alphebitize

Alphebetize attributes

Default: 0

-c, --close

Close tag style

Default: 0

-n, --namespace

Include namespace

Default: 0

check_xml_attribute_coverage

Checks xml attribute coverage for files in the GEOS repository.

usage: check_xml_attribute_coverage [-h] [-r ROOT] [-o OUTPUT]

Named Arguments

-r, --root

GEOSX root

Default: ''

-o, --output

Output file name

Default: 'attribute_test.xml'

check_xml_redundancy

Checks for redundant attribute definitions in an xml file, such as those that duplicate the default value.

usage: check_xml_redundancy [-h] [-r ROOT]

Named Arguments

-r, --root

GEOSX root

Default: ''

API

Command line tools for geosx_xml_tools

geos.xml_tools.main.check_mpi_rank() int

Check the MPI rank

Returns:

MPI rank

Return type:

int

geos.xml_tools.main.format_geosx_arguments(compiled_name: str, unknown_args: Iterable[str]) Iterable[str]

Format GEOSX arguments

Parameters:
  • compiled_name (str) – Name of the compiled xml file

  • unknown_args (list) – List of unprocessed arguments

Returns:

List of arguments to pass to GEOSX

Return type:

list

geos.xml_tools.main.preprocess_parallel() Iterable[str]

MPI aware xml preprocesing

geos.xml_tools.main.preprocess_serial() None

Entry point for the geosx_xml_tools console script

geos.xml_tools.main.wait_for_file_write_rank_0(target_file_argument: int | str = 0, max_wait_time: float = 100, max_startup_delay: float = 1) Callable[[Callable[[...], Any]], Callable[[...], Any]]

Constructor for a function decorator that waits for a target file to be written on rank 0

Parameters:
  • target_file_argument (int, str) – Index or keyword of the filename argument in the decorated function

  • max_wait_time (float) – Maximum amount of time to wait (seconds)

  • max_startup_delay (float) – Maximum delay allowed for thread startup (seconds)

Returns:

Wrapped function

Tools for processing xml files in GEOSX

geos.xml_tools.xml_processor.apply_regex_to_node(node: lxml.etree.Element) None

Apply regexes that handle parameters, units, and symbolic math to each xml attribute in the structure.

Parameters:

node (lxml.etree.Element) – The target node in the xml structure.

geos.xml_tools.xml_processor.generate_random_name(prefix: str = '', suffix: str = '.xml') str

If the target name is not specified, generate a random name for the compiled xml

Parameters:
  • prefix (str) – The file prefix (default = ‘’).

  • suffix (str) – The file suffix (default = ‘.xml’)

Returns:

Random file name

Return type:

str

geos.xml_tools.xml_processor.merge_included_xml_files(root: lxml.etree.Element, fname: str, includeCount: int, maxInclude: int = 100) None

Recursively merge included files into the current structure.

Parameters:
  • root (lxml.etree.Element) – The root node of the base xml structure.

  • fname (str) – The name of the target xml file to merge.

  • includeCount (int) – The current recursion depth.

  • maxInclude (int) – The maximum number of xml files to include (default = 100)

geos.xml_tools.xml_processor.merge_xml_nodes(existingNode: lxml.etree.Element, targetNode: lxml.etree.Element, level: int) None

Merge nodes in an included file into the current structure level by level.

Parameters:
  • existingNode (lxml.etree.Element) – The current node in the base xml structure.

  • targetNode (lxml.etree.Element) – The node to insert.

  • level (int) – The xml file depth.

geos.xml_tools.xml_processor.process(inputFiles: Iterable[str], outputFile: str = '', schema: str = '', verbose: int = 0, parameter_override: List[Tuple[str, str]] = [], keep_parameters: bool = True, keep_includes: bool = True) str

Process an xml file

Parameters:
  • inputFiles (list) – Input file names.

  • outputFile (str) – Output file name (if not specified, then generate randomly).

  • schema (str) – Schema file name to validate the final xml (if not specified, then do not validate).

  • verbose (int) – Verbosity level.

  • parameter_override (list) – Parameter value overrides

  • keep_parameters (bool) – If True, then keep parameters in the compiled file (default = True)

  • keep_includes (bool) – If True, then keep includes in the compiled file (default = True)

Returns:

Output file name

Return type:

str

geos.xml_tools.xml_processor.validate_xml(fname: str, schema: str, verbose: int) None

Validate an xml file, and parse the warnings.

Parameters:
  • fname (str) – Target xml file name.

  • schema (str) – Schema file name.

  • verbose (int) – Verbosity level.

geos.xml_tools.xml_formatter.format_attribute(attribute_indent: str, ka: str, attribute_value: str) str

Format xml attribute strings

Parameters:
  • attribute_indent (str) – Attribute indent string

  • ka (str) – Attribute name

  • attribute_value (str) – Attribute value

Returns:

Formatted attribute value

Return type:

str

geos.xml_tools.xml_formatter.format_file(input_fname: str, indent_size: int = 2, indent_style: bool = False, block_separation_max_depth: int = 2, alphebitize_attributes: bool = False, close_style: bool = False, namespace: bool = False) None

Script to format xml files

Parameters:
  • input_fname (str) – Input file name

  • indent_size (int) – Indent size

  • indent_style (bool) – Style of indentation (0=fixed, 1=hanging)

  • block_separation_max_depth (int) – Max depth to separate xml blocks

  • alphebitize_attributes (bool) – Alphebitize attributes

  • close_style (bool) – Style of close tag (0=same line, 1=new line)

  • namespace (bool) – Insert this namespace in the xml description

geos.xml_tools.xml_formatter.format_xml_level(output: TextIO, node: lxml.etree.Element, level: int, indent: str = '  ', block_separation_max_depth: int = 2, modify_attribute_indent: bool = False, sort_attributes: bool = False, close_tag_newline: bool = False, include_namespace: bool = False) None

Iteratively format the xml file

Parameters:
  • output (file) – the output text file handle

  • node (lxml.etree.Element) – the current xml element

  • level (int) – the xml depth

  • indent (str) – the xml indent style

  • block_separation_max_depth (int) – the maximum depth to separate adjacent elements

  • modify_attribute_indent (bool) – option to have flexible attribute indentation

  • sort_attributes (bool) – option to sort attributes alphabetically

  • close_tag_newline (bool) – option to place close tag on a separate line

  • include_namespace (bool) – option to include the xml namespace in the output

geos.xml_tools.xml_formatter.main() None

Script to format xml files

Parameters:
  • input (str) – Input file name

  • -i/--indent (int) – Indent size

  • -s/--style (int) – Indent style

  • -d/--depth (int) – Block separation depth

  • -a/--alphebitize (int) – Alphebitize attributes

  • -c/--close (int) – Close tag style

  • -n/--namespace (int) – Include namespace

Tools for managing units in GEOSX

class geos.xml_tools.unit_manager.UnitManager

This class is used to manage unit definitions.

buildUnits() None

Build the unit definitions.

regexHandler(match: Match) str

Split the matched string into a scale and unit definition.

Parameters:

match (re.match) – The matching string from the regex.

Returns:

The string with evaluated unit definitions

Return type:

str

Tools for managing regular expressions in geosx_xml_tools

class geos.xml_tools.regex_tools.DictRegexHandler

This class is used to substitute matched values with those stored in a dict.

geos.xml_tools.regex_tools.SymbolicMathRegexHandler(match: Match) str

Evaluate symbolic expressions that are identified using the regex_tools.patterns[‘symbolic’].

Parameters:

match (re.match) – A matching string identified by the regex.

geos.xml_tools.xml_redundancy_check.check_redundancy_level(local_schema: Dict[str, Any], node: lxml.etree.Element, whitelist: Iterable[str] = ['component']) int

Check xml redundancy at the current level

Parameters:
  • local_schema (dict) – Schema definitions

  • node (lxml.etree.Element) – current xml node

  • whitelist (list) – always match nodes containing these attributes

Returns:

Number of required attributes in the node and its children

Return type:

int

geos.xml_tools.xml_redundancy_check.check_xml_redundancy(schema: Dict[str, Any], fname: str) None

Check redundancy in an xml file

Parameters:
  • schema (dict) – Schema definitions

  • fname (str) – Name of the target file

geos.xml_tools.xml_redundancy_check.main() None

Entry point for the xml attribute usage test script

Parameters:

-r/--root (str) – GEOSX root directory

geos.xml_tools.xml_redundancy_check.process_xml_files(geosx_root: str) None

Test for xml redundancy

Parameters:

geosx_root (str) – GEOSX root directory

geos.xml_tools.attribute_coverage.collect_xml_attributes(xml_types: Dict[str, Dict[str, Any]], fname: str, folder: str) None

Collect xml attribute usage in a file

Parameters:
  • xml_types (dict) – dictionary containing attribute usage

  • fname (str) – name of the target file

  • folder (str) – the source folder for the current file

geos.xml_tools.attribute_coverage.collect_xml_attributes_level(local_types: Dict[str, Dict[str, Any]], node: lxml.etree.Element, folder: str) None

Collect xml attribute usage at the current level

Parameters:
  • local_types (dict) – dictionary containing attribute usage

  • node (lxml.etree.Element) – current xml node

  • folder (str) – the source folder for the current file

geos.xml_tools.attribute_coverage.main() None

Entry point for the xml attribute usage test script

Parameters:
  • -r/--root (str) – GEOSX root directory

  • -o/--output (str) – output file name

geos.xml_tools.attribute_coverage.parse_schema(fname: str) Dict[str, Dict[str, Any]]

Parse the schema file into the xml attribute usage dict

Parameters:

fname (str) – schema name

Returns:

Dictionary of attributes and children for the entire schema

Return type:

dict

geos.xml_tools.attribute_coverage.parse_schema_element(root: lxml.etree.Element, node: lxml.etree.Element, xsd: str = '{http://www.w3.org/2001/XMLSchema}', recursive_types: Iterable[str] = ['PeriodicEvent', 'SoloEvent', 'HaltEvent'], folders: Iterable[str] = ['src', 'examples']) Dict[str, Dict[str, Any]]

Parse the xml schema at the current level

Parameters:
  • root (lxml.etree.Element) – the root schema node

  • node (lxml.etree.Element) – current schema node

  • xsd (str) – the file namespace

  • recursive_types (list) – node tags that allow recursive nesting

  • folders (list) – folders to sort xml attribute usage into

Returns:

Dictionary of attributes and children for the current node

Return type:

dict

geos.xml_tools.attribute_coverage.process_xml_files(geosx_root: str, output_name: str) None

Test for xml attribute usage

Parameters:
  • geosx_root (str) – GEOSX root directory

  • output_name (str) – output file name

geos.xml_tools.attribute_coverage.write_attribute_usage_xml(xml_types: Dict[str, Dict[str, Any]], fname: str) None

Write xml attribute usage file

Parameters:
  • xml_types (dict) – dictionary containing attribute usage by xml type

  • fname (str) – output file name

geos.xml_tools.attribute_coverage.write_attribute_usage_xml_level(local_types: Dict[str, Dict[str, Any]], node: lxml.etree.Element, folders: Iterable[str] = ['src', 'examples']) None

Write xml attribute usage file at a given level

Parameters:
  • local_types (dict) – dict containing attribute usage at the current level

  • node (lxml.etree.Element) – current xml node

Tools for reading/writing GEOSX ascii tables

geos.xml_tools.table_generator.read_GEOS_table(axes_files: Iterable[str], property_files: Iterable[str]) Tuple[Iterable[ndarray], Dict[str, ndarray]]

Read an GEOS-compatible ascii table.

Parameters:
  • axes_files (list) – List of the axes file names in order.

  • property_files (list) – List of property file names

Returns:

List of axis definitions, dict of property values

Return type:

tuple

geos.xml_tools.table_generator.write_GEOS_table(axes_values: Iterable[ndarray], properties: Dict[str, ndarray], axes_names: Iterable[str] = ['x', 'y', 'z', 't'], string_format: str = '%1.5e') None

Write an GEOS-compatible ascii table.

Parameters:
  • axes_values (list) – List of arrays containing the coordinates for each axis of the table.

  • properties (dict) – Dict of arrays with dimensionality/size defined by the axes_values

  • axes_names (list) – Names for each axis (default = [‘x’, ‘y’, ‘z’, ‘t’])

  • string_format (str) – Format for output values (default = %1.5e)

geos.xml_tools.table_generator.write_read_GEOS_table_example() None

Table read / write example.