mahautils.multics.SimResults

class mahautils.multics.SimResults(path: str | Path | None = None, unit_converter: UnitConverter | None = None)

Bases: MahaMulticsConfigFile

An object representing a Maha Multics simulation results file

The Maha Multics software uses simulation results files to configure which simulation results will be generated and to store the results. This class is capable of parsing such files and providing an interface through which users can interact with and manipulate data in the file.

Attributes

compile_options	A dictionary containing options with which the Maha Multics software was compiled
maha_multics_commit	The Git commit hash of the Maha Multics software with which the simulation was compiled
maha_multics_version	The version of the Maha Multics software with which the simulation was compiled
num_time_steps	The number of time steps in the data array of the simulation results file
sim_version	The simulation version of the main.cpp file which was used to generate the data in the simulation results file
title	A title describing the contents of the simulation results file
variables	A tuple containing all variable names listed in the simulation results file

Methods

__init__([path, unit_converter])	Creates an object that can read and write Maha Multics simulation results files
append(key, required, units[, data, ...])	Adds a variable to the simulation results file
clear()	Removes all data stored in this object
clear_data([regex_pattern])	Removes simulation results data for any variable(s) with names matching a given regex pattern
get_data(key, units)	Extracts simulation results data by variable name
get_description(key)	Returns the description (if assigned) of a variable in the simulation results file
get_group(key)	Returns the name of the group (if assigned) of a variable in the simulation results file
get_required(key)	Returns whether a variable in the simulation results file is specified as "required"
get_units(key)	Returns the "raw" units in which data in the simulation results file are stored
list_groups()	Returns a tuple containing all variable groups in the simulation results file
parse()	Parses the file content in the contents list and populates attributes (such as title) with extracted data
remove(key)	Removes a simulation results variable
search(keyword[, search_fields, ...])	Searches the simulation results file for a given search term
set_data(key, data[, units])	Adds or replaces simulation results data by variable name
set_description(key, description)	Adds or modifies the description of a variable in the simulation results file
set_group(key, group)	Sets or modifies the name of the group of a variable in the simulation results file
set_required(key, required)	Modifies whether a variable in the simulation results file is specified as "required"
set_units(key, units[, action_if_data_present])	Modifies the units of a variable in the simulation results file
update_contents([add_sim_data, indent, padding])	Updates the contents list based on object attributes

Inherited Attributes

comment_chars	A tuple of all characters considered to denote comments
contents	A reference to a list containing the (potentially modified) file content of each line of the file
hashes	A copy of the dictionary containing any file hashes previously computed for the file specified by the path attribute
line_ending	The character(s) used to denote the end of lines in the text file
path	Path describing the location of the file on the disk
raw_contents	A copy of the raw file content
trailing_newline	Whether the original file had a newline at the end of the file
unit_converter	The unit converter used to convert the units of quantities stored in the file

Inherited Methods

clean_contents([remove_comments, ...])	Clean contents in-place
clear_file_hashes()	Clears any stored file hashes
compute_file_hashes([hash_functions, store])	Computes hashes of the file specified by the path attribute
extract_section_by_keyword(section_label, ...)	Extracts a section from the contents list of file lines
has_changed()	Returns whether the file specified by the path attribute has changed since the last time file hashes were computed
overwrite([prologue, epilogue, line_ending])	Write data in contents to the file specified by path
read([path, parse])	Read file from disk
set_contents(contents, trailing_newline[, ...])	Add data to the contents list
set_read_metadata([path])	Configures metadata related to file to be read from disk
store_file_hashes([hash_functions])	Computes and stores hashes of the file specified by the path attribute
track_new_file(path[, hash_functions])	Shortcut for simultaneously modifying the path attribute and storing file hashes
write(output_file[, write_mode, ...])	Write file to disk

__init__(path: str | Path | None = None, unit_converter: UnitConverter | None = None) → None

Creates an object that can read and write Maha Multics simulation results files

Creates an instance of the SimResults class and optionally reads and parses a specified Maha Multics simulation results file.

Parameters:

• path (str or pathlib.Path, optional) – The path and filename of the simulation results file to read and parse (default is None). If set to None, no file is read

• unit_converter (pyxx.units.UnitConverter, optional) – A pyxx.units.UnitConverter instance which will be used to convert units of quantities stored in the simulation results file (default is None). If set to None, the MahaMulticsUnitConverter unit converter will be used to perform unit conversions

property trailing_newline: bool

Whether the original file had a newline at the end of the file

property compile_options: Dict[str, str]

A dictionary containing options with which the Maha Multics software was compiled

Note that this dictionary is returned by reference, so modifying the returned value will modify the object attribute.

property maha_multics_commit: str | None

The Git commit hash of the Maha Multics software with which the simulation was compiled

property maha_multics_version: str | None

The version of the Maha Multics software with which the simulation was compiled

property num_time_steps: int

The number of time steps in the data array of the simulation results file

property sim_version: str | None

The simulation version of the main.cpp file which was used to generate the data in the simulation results file

property title: str | None

A title describing the contents of the simulation results file

property variables: Tuple[str, ...]

A tuple containing all variable names listed in the simulation results file

This property contains all variables listed in the “printDict” section of the simulation results file. There may or may not be simulation results data available for any given variable.

append(key: str, required: bool, units: str, data: ndarray | List[float] | Tuple[float, ...] | None = None, description: str | None = None, group: str | None = None) → None

Adds a variable to the simulation results file

Adds a new variable to the simulation results file, placing it at the end of the variables list.

Parameters:

• key (str) – A unique name to identify the variable

• required (bool) – Whether the simulation results variable is required to be outputted by Maha Multics

• units (str) – The units of the variable’s data

• data (np.ndarray or list or tuple, optional) – If desired, a 1D array consisting of the simulation results data for the variable can be provided (default is None)

• description (str, optional) – An optional description of the simulation results variable (default is None)

• group (str, optional) – An optional group to which the variable belongs (default is None)

Raises:

SimResultsOverwriteError – If a variable key already exists in the simulation results file

clear() → None

Removes all data stored in this object

clear_data(regex_pattern: str = '.+') → List[str]

Removes simulation results data for any variable(s) with names matching a given regex pattern

Parameters:

regex_pattern (str, optional) – Any variables in variables matching this regex pattern will have existing simulation results data deleted (default is '.+', which matches all variable names)

Returns:

A list containing the variable names whose data were deleted

Return type:

list

get_data(key: str, units: str) → ndarray

Extracts simulation results data by variable name

Extracts data corresponding to a specific simulation results variable and returns it as a NumPy array with user-specified units, performing a unit conversion if necessary.

Parameters:

• key (str) – The name of the variable whose data to extract

• units (str) – The units in which the simulation results data should be returned

Returns:

A NumPy array containing the simulation results data for variable key, in units of units

Return type:

np.ndarray

clean_contents(remove_comments: bool = False, skip_full_line_comments: bool = False, strip: bool = False, concat_lines: bool = False, remove_blank_lines: bool = False) → None

Clean contents in-place

Cleans contents (removing comments, blank lines, etc.) based on user-defined rules. Modifications are made in-place (i.e., the resulting content is stored in contents).

Parameters:

• remove_comments (bool, optional) – Whether to remove comments from file (default is True)

• skip_full_line_comments (bool, optional) – Whether to skip removing comments where the comment is the only text on a line. Only applies if remove_comments is True (default is False)

• strip (bool, optional) – Whether to strip leading and trailing whitespace from each line (default is True)

• concat_lines (bool, optional) – Whether to concatenate lines ending with a backslash with the following line (default is True)

• remove_blank_lines (bool, optional) – Whether to remove lines that contain no content after other cleaning operations have completed (default is True)

clear_file_hashes() → None

Clears any stored file hashes

property comment_chars: Tuple[str, ...] | None

A tuple of all characters considered to denote comments

compute_file_hashes(hash_functions: tuple | str = ('md5', 'sha256'), store: bool = False) → Dict[str, str]

Computes hashes of the file specified by the path attribute

Computes and returns the hashes of the file specified by the path attribute, with the option to populate the hashes dictionary with their values.

Parameters:

• hash_functions (tuple or str, optional) – Tuple of strings (or individual string) specifying which hash(es) to compute. Any hash functions supported by hashlib can be used. Default is ('md5', 'sha256')

• store (bool, optional) – Whether to store the computed hashes in the hashes dictionary (default is False)

Returns:

A dictionary containing the file hashes specified by hash_functions

Return type:

dict

See also

pyxx.files.compute_file_hash

Function used to compute file hashes

Notes

Prior to calling this method, the path attribute must be defined. To simultaneously set the path attribute and store file hashes, use track_new_file().

property contents: List[str]

A reference to a list containing the (potentially modified) file content of each line of the file

Warning

This attribute returns the list by reference. This means that if you set a variable equal to this reference, then editing this variable will edit the contents attribute (e.g., if you set my_content = MyTextFile.contents, then editing my_content will change the content stored in MyTextFile).

Notes

If trying to set the contents attribute, do not try to set this attribute directly (i.e., don’t use code similar to MyTextFile.contents = ['line1', 'line2', 'line3']). Instead, use the set_contents() method, as it offers greater control over whether the contents are passed by reference or value.

extract_section_by_keyword(section_label: str, begin_regex: str, end_regex: str, section_line_regex: str = '(.*)', max_sections: int | None = None, begin_idx: int = 0, allow_comment_lines: bool = True) → Tuple[List[Match], List[Tuple[str, ...]], int, int]

Extracts a section from the contents list of file lines

Many Maha Multics configuration files contain sections with certain types of data, where the section begins following a formatted section marker and ends at another marker (both with unique, identifiable regex patterns). This method extracts the data from such a section. If multiple sections are found, the data in all sections is merged, unless specified otherwise by setting max_sections.

Parameters:

• section_label (str) – A descriptive name identifying the section. This is not used in parsing the file; it is only used to customize error messages and make them more descriptive

• begin_regex (str) – The regex pattern which marks the beginning of the section

• end_regex (str) – The regex pattern which marks the end of the section

• section_line_regex (str, optional) – If provided, this regex pattern must be matched by all lines inside the section (default is '(.*)', which matches any text)

• max_sections (int, optional) – The maximum number of sections to extract; that is, only the first max_sections encountered will be extracted and returned (default is None, which extracts all sections)

• begin_idx (int, optional) – The index (in the contents list) at which to begin to search for and extract data from sections (default is 0)

• allow_comment_lines (bool, optional) – If True, any lines within the section that do not match section_line_regex but begin with any of the characters in comment_chars will be outputted (part of the second output of the method); if False, any lines within the section that do not match section_line_regex will result in an error being thrown (default is True)

Returns:

• list – A list of re.Match objects containing the matches for the regex pattern section_line_regex for all lines in the section(s)

• list – A list (of the same length as the first argument returned) of tuples of strings. For each re.Match object, the corresponding item in this list contains a tuple with any full-line comments preceding the matched line

• int – The index of contents of the next line immediately following the line on which end_regex was found

• int – The number of sections that were extracted from the contents list

get_description(key: str) → str | None

Returns the description (if assigned) of a variable in the simulation results file

Parameters:

key (str) – The name of the variable whose description to retrieve

Returns:

A string containing the description of the simulation results variable, or None if no description is available

Return type:

str or None

has_changed() → bool

Returns whether the file specified by the path attribute has changed since the last time file hashes were computed

Returns:

Whether file has changed since the last time file hashes were computed

Return type:

bool

property hashes: Dict[str, str]

A copy of the dictionary containing any file hashes previously computed for the file specified by the path attribute

property line_ending: str | Tuple[str, ...]

The character(s) used to denote the end of lines in the text file

This property only applies to files that were read using the read() method. After reading a file, this property stores the line ending(s) used in the file. Lines in text files can be terminated with '\n' (LF), '\r\n' (CRLF), '\r', or a combination of these characters (potentially with different line endings on different lines).

After reading a file, this property stores either a string containing the line endings on every line of the file, or a tuple containing all line endings encountered throughout the file.

overwrite(prologue: str = '', epilogue: str | None = None, line_ending: str = '\n') → None

Write data in contents to the file specified by path

Writes the lines of content in the contents attribute to the (previously-defined) file specified by the path attribute, suppressing warnings before overwriting the file. This is useful for cases when the file contents are manually populated and it is desired to “dump” them to a file. This method is also useful if a file’s contents need to be updated periodically based on the results of another process.

Parameters:

• prologue (str, optional) – Content written at beginning of file (default is '')

• epilogue (str, optional) – Content written at end of file (default is to use the value of the line_ending argument if trailing_newline is True and '' otherwise)

• line_ending (str, optional) – String written at the end of each line when writing file content (default is '\n')

property path: Path | None

Path describing the location of the file on the disk

Assigning a value to this attribute (regardless whether it matches the current value or is a different path) will save the value as a pathlib.Path and will automatically clear any saved file hashes.

property raw_contents: List[str] | None

A copy of the raw file content

If the file was read using the read() method, this attribute stores the original, unaltered contents of each line of the input file, and it returns a copy of this list of lines. If the file was not read with the read() method, this attribute stores a value of None.

read(path: str | Path | None = None, parse: bool = True) → None

Read file from disk

Calling this method reads the file specified by the path attribute from the disk, populating contents and raw_contents. Additionally, the file hashes stored in the hashes attribute are updated (to make it easier to check if the file has been modified later).

Parameters:

• path (str or pathlib.Path, optional) – Location of the text file in the file system (default is None)

• parse (bool, optional) – Whether to call the parse() method after reading the file (default is True)

set_contents(contents: List[str], trailing_newline: bool, pass_by_reference: bool = False) → None

Add data to the contents list

Allows users to manually fill the contents list with user-defined content. The input list must be a list of strings, and the user can optionally choose whether to pass the input by reference or value.

Parameters:

• contents (list) – List of strings which are to be assigned to the contents list

• trailing_newline (bool) – Whether the contents being added represent a file with a trailing newline (because the file wasn’t read, the object has no way to determine whether the file has a trailing newline, so users must provide this information)

• pass_by_reference (bool, optional) – Whether to pass the contents argument by reference (default is False)

Notes

If passing contents by reference, this means that if subsequent changes are made to the original contents object, they will be reflected in the contents attribute. If passing by value, then a copy of the contents argument will be made, so changing the object outside the class instance will not affect the contents attribute.

set_read_metadata(path: str | Path | None = None) → None

Configures metadata related to file to be read from disk

This method performs several pre-processing steps to prepare to read a file from the disk:

1. Sets the path attribute. If the path argument was provided, the attribute is set to this value; otherwise, the existing value stored in the path attribute is used (or an error is thrown if not defined).

2. Verifies that the file specified by the path attribute exists.

3. Stores the hashes for the file.

It is advised that this method be called prior to reading any file.

Parameters:

path (str or pathlib.Path, optional) – Location of the file in the file system (default is None)

Raises:

• AttributeError – If the both the path argument and the existing path attribute are None

• FileNotFoundError – If the file specified by path (after completing Step 1 above) does not exist

store_file_hashes(hash_functions: tuple | str = ('md5', 'sha256')) → None

Computes and stores hashes of the file specified by the path attribute

Computes given hashes of the file specified by the path attribute and populates the hashes dictionary with their values.

Parameters:

hash_functions (tuple or str, optional) – Tuple of strings (or individual string) specifying which hash(es) to compute. Any hash functions supported by hashlib can be used. Default is ('md5', 'sha256')

See also

pyxx.files.compute_file_hash

Function used to compute file hashes

track_new_file

Use this method if you want to store file hashes but the path attribute isn’t yet defined

Notes

Prior to calling this method, the path attribute must be defined. To simultaneously set the path attribute and store file hashes, use track_new_file().

track_new_file(path: str | Path, hash_functions: tuple | str = ('md5', 'sha256')) → None

Shortcut for simultaneously modifying the path attribute and storing file hashes

This method functions as a “shortcut,” both modifying the path attribute and storing an optionally user-specified list of file hashes in the hashes attribute. The intention of this method is that if a File instance is tracking a given file, and user wants to switch to tracking another file, this provides a convenient way to do so with a single line of code.

Parameters:

• file (str or pathlib.Path) – File that the object is to represent

• hash_functions (tuple or str, optional) – Tuple of strings (or individual string) specifying which hash(es) to compute. Any hash functions supported by hashlib can be used. Default is ('md5', 'sha256')

See also

pyxx.files.compute_file_hash

Function used to compute file hashes

property unit_converter: UnitConverter

The unit converter used to convert the units of quantities stored in the file

write(output_file: str | Path, write_mode: str = 'w', warn_before_overwrite: bool = True, prologue: str = '', epilogue: str | None = None, line_ending: str = '\n', update_contents: bool = True) → None

Write file to disk

Calling this method writes the file contents stored in contents to the disk.

Parameters:

• output_file (str or pathlib.Path) – Output file to which to write content

• write_mode (str, optional) – Any mode (such as 'w' or 'a') for the built-in open() function for writing files (default is 'w')

• warn_before_overwrite (bool, optional) – Whether to throw an error if output_file already exists (default is True)

• prologue (str, optional) – Content written at beginning of file (default is '')

• epilogue (str, optional) – Content written at end of file (default is to use the value of the line_ending argument if trailing_newline is True and '' otherwise)

• line_ending (str, optional) – String written at the end of each line when writing file content (default is '\n')

• update_contents (bool, optional) – Whether to call the update_contents() method before writing the file (default is True)

get_group(key: str) → str | None

Returns the name of the group (if assigned) of a variable in the simulation results file

Parameters:

key (str) – The name of the variable whose group to retrieve

Returns:

A string containing the name of the group of the simulation results variable, or None if no group has been assigned

Return type:

str or None

get_required(key: str) → bool

Returns whether a variable in the simulation results file is specified as “required”

Variables specified as “required” indicates to the Maha Multics software that the simulation should exit with error if unable to output these values.

Parameters:

key (str) – The name of the variable whose data to extract

Returns:

Whether the variable specified by key is marked as “required” in the simulation results file

Return type:

bool

get_units(key: str) → str

Returns the “raw” units in which data in the simulation results file are stored

When extracting data with get_data(), the units can be converted to any valid unit; however, the data in SimResults objects is internally stored with a particular set of units. This method returns these units of the internally stored data.

Parameters:

key (str) – The name of the variable whose units to return

Returns:

The internally stored units of data in the simulation results file

Return type:

str

list_groups() → Tuple[str, ...]

Returns a tuple containing all variable groups in the simulation results file

Returns:

A tuple of strings, where each string is a variable group in the simulation results file

Return type:

tuple

parse() → None

Parses the file content in the contents list and populates attributes (such as title) with extracted data

This method parses the data in contents, extracting configuration and simulation results data and storing it in this object’s attributes for easier reading and editing.

remove(key: str) → None

Removes a simulation results variable

Removes a variable and any associated data from the simulation results file.

Parameters:

key (str) – The name of the variable to remove

search(keyword: str, search_fields: str | Tuple[str, ...] | List[str] = ('keys', 'description', 'group', 'units'), case_sensitive: bool = False, show_data: bool = False, print_results: bool = True, return_results: bool = False) → Tuple[str, ...] | None

Searches the simulation results file for a given search term

This method can be useful for finding data, particularly in a large simulation results file. It performs a relatively basic search, checking to see if a given term keyword is in any of the specified search fields. The exact keyword must be found to register a match; similar terms are not considered a match. To match any string, set keyword to ''.

Parameters:

• keyword (str) – The term to search for

• search_fields (str or tuple or list, optional) – One or more simulation results variable attributes in which to search for keyword (default is to search all possible attributes, ('keys', 'description', 'group', 'units'))

• case_sensitive (bool, optional) – Whether to perform a case-sensitive search (default is False)

• show_data (bool, optional) – Whether to print simulation results data, if available, for each variable (default is False). Setting this to True can considerably increase output verbosity

• print_results (bool, optional) – Whether to display results to the terminal (default is True)

• return_results (bool, optional) – Whether to return a tuple of strings containing the simulation results variable keys for all search matches (default is False)

Returns:

A tuple of strings containing all simulation results variable keys (i.e., selected from variables) for which search matches were registered. Only returned if return_results is True

Return type:

tuple

set_data(key: str, data: ndarray | List[float] | Tuple[float, ...] | None, units: str | None = None) → None

Adds or replaces simulation results data by variable name

Parameters:

• key (str) – The name of the variable whose data to store

• data (np.ndarray or list or tuple) – A 1D array containing the data (in units of units) to store

• units (str) – The units in which the simulation results data should be stored

set_description(key: str, description: str | None) → None

Adds or modifies the description of a variable in the simulation results file

Parameters:

• key (str) – The name of the variable whose description to retrieve

• description (str or None) – The description of the simulation results variable, or None to remove the description

set_group(key: str, group: str | None) → None

Sets or modifies the name of the group of a variable in the simulation results file

Parameters:

• key (str) – The name of the variable whose group to retrieve

• description (str or None) – The group name of the simulation results variable, or None to remove the group name

set_required(key: str, required: bool) → None

Modifies whether a variable in the simulation results file is specified as “required”

Variables specified as “required” indicates to the Maha Multics software that the simulation should exit with error if unable to output these values.

Parameters:

• key (str) – The name of the variable whose data to extract

• required (bool) – Whether the variable specified by key is marked as “required” in the simulation results file

set_units(key: str, units: str, action_if_data_present: str = 'error') → None

Modifies the units of a variable in the simulation results file

Parameters:

• key (str) – The name of the variable whose units to modify

• units (str) – The units to assign to variable key

• action_if_data_present (str, optional) – The action that should be taken if simulation results data for key are already present in the simulation results file (default is 'error'). See “Notes” section for additional information

Notes

In the case that simulation results data for key already exist, it is not obvious how this case should be handled: should the data also be converted to the new units, or should only the units be changed?

MahaUtils provides three options to handle this case:

1. 'error': If simulation results data are present, throw an error

2. 'convert_data': If simulation results data are present, convert it to the units given by the units argument (e.g., \(3\ m\) would become \(0.003\ mm\))

3. 'keep_data_values': If simulation results data are present, keep the same values of the data but change the units (e.g., \(3\ m\) would become \(3\ mm\))

update_contents(add_sim_data: bool = True, indent: int = 4, padding: int = 4) → None

Updates the contents list based on object attributes

This method synchronizes the contents list with the data stored in the SimResults attributes (title, variables added by append(), etc.). This step should generally be performed prior to calling write(), as writing a file directly saves the data in contents to disk.

Parameters:

• add_sim_data (bool, optional) – Whether to add simulation results data to the end of contents (default is True)

• indent (int, optional) – The number of spaces to use for indentation in the file (default is 4)

• padding (int, optional) – The number of spaces to place between simulation results variable names and the units in the printDict section of the simulation results file (default is 4)