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

Check the MPI rank

Returns:

MPI rank

Return type:

int

geos.xml_tools.main.format_geosx_arguments(compiled_name, unknown_args)

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

MPI aware xml preprocesing

geos.xml_tools.main.preprocess_serial()

Entry point for the geosx_xml_tools console script

geos.xml_tools.main.wait_for_file_write_rank_0(target_file_argument=0, max_wait_time=100, max_startup_delay=1)

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)

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='', suffix='.xml')

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, fname, includeCount, maxInclude=100)

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, targetNode, level)

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, outputFile='', schema='', verbose=0, parameter_override=[], keep_parameters=True, keep_includes=True)

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, schema, verbose)

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, ka, attribute_value)

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, indent_size=2, indent_style=False, block_separation_max_depth=2, alphebitize_attributes=False, close_style=False, namespace=False)

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, node, level, indent='  ', block_separation_max_depth=2, modify_attribute_indent=False, sort_attributes=False, close_tag_newline=False, include_namespace=False)

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

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.

Initialize the class by creating an instance of the dict regex handler, building units.

buildUnits()

Build the unit definitions.

regexHandler(match)

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.

Initialize the handler with an empty target list. The key/value pairs of self.target indicate which values to look for and the values they will replace with.

geos.xml_tools.regex_tools.SymbolicMathRegexHandler(match)

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, node, whitelist=['component'])

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, fname)

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

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)

Test for xml redundancy

Parameters:

geosx_root (str) – GEOSX root directory

geos.xml_tools.attribute_coverage.collect_xml_attributes(xml_types, fname, folder)

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, node, folder)

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

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)

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, node, xsd='{http://www.w3.org/2001/XMLSchema}', recursive_types=['PeriodicEvent', 'SoloEvent', 'HaltEvent'], folders=['src', 'examples'])

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, output_name)

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, fname)

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, node, folders=['src', 'examples'])

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, property_files)

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, properties, axes_names=['x', 'y', 'z', 't'], string_format='%1.5e')

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

Table read / write example.