GEOS XML Tools

The geosx_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

geosx_xml_tools.main.check_mpi_rank() → int

Check the MPI rank

Returns:: MPI rank
Return type:: int

geosx_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

geosx_xml_tools.main.preprocess_parallel() → Iterable[str]: MPI aware xml preprocesing

geosx_xml_tools.main.preprocess_serial() → None: Entry point for the geosx_xml_tools console script

geosx_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

geosx_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.

geosx_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

geosx_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)

geosx_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.

geosx_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

geosx_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.

geosx_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

geosx_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

geosx_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

geosx_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 geosx_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 geosx_xml_tools.regex_tools.DictRegexHandler: This class is used to substitute matched values with those stored in a dict.

geosx_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.

geosx_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

geosx_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

geosx_xml_tools.xml_redundancy_check.main() → None

Entry point for the xml attribute usage test script

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

geosx_xml_tools.xml_redundancy_check.process_xml_files(geosx_root: str) → None

Test for xml redundancy

Parameters:: geosx_root (str) – GEOSX root directory

geosx_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

geosx_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

geosx_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

geosx_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

geosx_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

geosx_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

geosx_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

geosx_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

geosx_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

geosx_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)

geosx_xml_tools.table_generator.write_read_GEOS_table_example() → None: Table read / write example.