GEOSX XML Tools¶

The geosx_xml_tools python package adds a set of advanced features to the GEOSX 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 GEOSX 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: Union[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: <sphinx.ext.autodoc.importer._MockObject object at 0x7f399beb6a50>) → 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: <sphinx.ext.autodoc.importer._MockObject object at 0x7f399beb6a50>, 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: <sphinx.ext.autodoc.importer._MockObject object at 0x7f399beb6a50>, targetNode: <sphinx.ext.autodoc.importer._MockObject object at 0x7f399beb6a50>, 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: <sphinx.ext.autodoc.importer._MockObject object at 0x7f399bf2a490>, 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: re.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: re.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: <sphinx.ext.autodoc.importer._MockObject object at 0x7f3995a7b950>, 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: <sphinx.ext.autodoc.importer._MockObject object at 0x7f39a178ba10>, 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: <sphinx.ext.autodoc.importer._MockObject object at 0x7f39a178ba10>, node: <sphinx.ext.autodoc.importer._MockObject object at 0x7f39a178ba10>, 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: <sphinx.ext.autodoc.importer._MockObject object at 0x7f39a178ba10>, 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[numpy.ndarray], Dict[str, numpy.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[numpy.ndarray], properties: Dict[str, numpy.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.