mahautils.multics.PolygonFile

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

Bases: MahaMulticsConfigFile

An object representing a Maha Multics polygon file

The Maha Multics software uses polygon files to store geometry used for setting boundary conditions when running fluid simulations. This class is capable of parsing such files and providing an interface through which users can interact with and manipulate data in the file (through the polygon_data attribute).

Note

The data structure in PolygonFile objects largely mirrors the content of Maha Multics polygon files, although there are a few differences (for which descriptive error messages are displayed). For more information about the format of these files, refer to the Polygon File Format page.

Attributes

num_time_steps	The number of time steps in the polygon file
polygon_data	A reference to the dictionary containing the polygon data in the file
polygon_data_readonly	A copy of the dictionary containing the polygon data in the file
polygon_merge_method	The method used to combine disjoint polygons
time_extrap_method	The method used to handle time values outside the defined time range
time_units	The units in which "time" values are stored in the polygon file
time_values	The values of "time" defined in the polygon file

Methods

__init__([path, unit_converter])	Creates an object to represent Maha Multics configuration files
filter_times(interval[, tolerance])	Reduces the number of time steps in a polygon file
parse()	Parses the file content in the contents list and populates attributes (such as the dictionary returned by polygon_data) with extracted data
plot([delay, show, return_fig])	Generates an animated plot showing the geometry in the polygon file
time_step([units])	Returns the time step for the polygon file
update_contents()	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 to represent Maha Multics configuration files

Creates an instance of the MahaMulticsConfigFile class, including configuring file comments to be represented by the # character.

Parameters:

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

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

property trailing_newline: bool

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

property num_time_steps: int

The number of time steps in the polygon file

property polygon_data: Dictionary[float, Layer]

A reference to the dictionary containing the polygon data in the file

This method returns a mahautils.utils.Dictionary instance containing the polygon data in the file. The keys are the time values defined in the file (with units given by time_units) and the values are Layer instances containing the polygons corresponding to each time step. This dictionary can be directly edited to modify the polygon file (adding new time steps, removing time steps, changing polygon properties, etc.).

Important

The dictionary is returned by reference, so editing the returned dictionary will directly edit data in the PolygonFile instance.

Notes

This property can only be accessed if polygon_merge_method, time_extrap_method, and time_units are all defined (even for polygon files with a single time step, since additional time steps may be added by modifying the polygon data dictionary). This ensures consistency of the data stored in the PolygonFile object. To access the polygon data before setting these properties, use polygon_data_readonly.

Any of the methods for adding or removing data provided by mahautils.utils.Dictionary can be used to modify polygon data. For instance, to insert a new time step prior to an existing time, simply use mahautils.utils.Dictionary.insert_before(). This is why there is no “add polygon” method – accessing the dictionary methods provides greater flexibility.

property polygon_data_readonly: Dictionary[float, Layer]

A copy of the dictionary containing the polygon data in the file

This method returns a mahautils.utils.Dictionary instance containing the polygon data in the file. The keys are the time values defined in the file (with units given by time_units) and the values are Layer instances containing the polygons corresponding to each time step.

Important

The dictionary is returned by copy, so editing the returned dictionary will not directly edit data in the PolygonFile instance.

Notes

Unlike polygon_data, this method does not require the polygon_merge_method, time_extrap_method, and time_units properties to be defined defined.

property polygon_merge_method: int

The method used to combine disjoint polygons

This attribute represents the method for combining multiple disjoint polygons and is applied for all time steps (a limitation hard-coded in the Maha Multics software).

For more information and a list of permissible values for the, polygon_merge_method property refer to the Polygon File Format page.

property time_extrap_method: int

The method used to handle time values outside the defined time range

This property defines how the Maha Multics software will handle time values outside the range given by time_values.

For more information and a list of permissible values for the, time_extrap_method property refer to the Polygon File Format page.

property time_units: str

The units in which “time” values are stored in the polygon file

Note that the term “time” is used loosely for polygon files, and “time” may also be given in terms of quantities such as shaft rotation angle. For more information, refer to the Polygon File Format page.

property time_values: List[float]

The values of “time” defined in the polygon file

This method returns a copy of the list of time values, so modifying the returned list will not affect the time values stored in the polygon file. The time values are returned with units given by time_units.

filter_times(interval: float, tolerance: float = 1e-12) → None

Reduces the number of time steps in a polygon file

Prunes time steps from a polygon file at user-specified intervals. This can be useful, for instance, if you have a polygon file with a time step of 0.01 seconds and you want to increase the time step to 0.1 seconds.

Parameters:

• interval (float) – The spacing at which to keep time steps, in units of time_units

• tolerance (float, optional) – The allowable difference between retained time steps and intervals of size interval (default is 1e-12)

Notes

Time steps are kept if they fall within a distance of tolerance of {..., -2*interval, -interval, 0, interval, 2*interval, ...}

parse() → None

Parses the file content in the contents list and populates attributes (such as the dictionary returned by polygon_data) with extracted data

This method parses the data in contents, checking for polygon file format errors and extracting data on individual polygons for easier reading and modification.

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

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.

plot(delay: float = 100, show: bool = True, return_fig: bool = False) → Figure | None

Generates an animated plot showing the geometry in the polygon file

Polygons in the file are illustrated as filled, solid shapes, and construction geometry is illustrated as dotted outlines.

Parameters:

• delay (float, optional) – The delay (in milliseconds) between each frame when animating the plot (default is 100)

• show (bool, optional) – Whether to open the figure in a browser (default is True)

• return_fig (bool, optional) – Whether to return the figure (default is False)

Returns:

An animated Plotly figure depicting the polygon file. Returned if and only if return_fig is True

Return type:

go.Figure

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)

time_step(units: str | None = None) → float

Returns the time step for the polygon file

Verifies that the polygon file has a constant, positive time step between successive values in time_values and returns this time step. If the polygon file has only a single time step, 0 is returned.

Parameters:

units (str, optional) – The units in which the time step should be returned. Required to be provided if the polygon file has more than one time step, but optional otherwise (default is None)

Returns:

The time step between successive values in time_values, or 0 for polygon files with a single time step

Return type:

float

Raises:

PolygonFileFormatError – If the polygon file has multiple time values but the time step between them is not consistent

Notes

The term “time” is used loosely for polygon files, and “time” may also be given in terms of quantities such as shaft rotation angle. For more information, refer to the Polygon File Format page.

update_contents() → None

Updates the contents list based on object attributes

This method synchronizes the contents list with the data stored in the PolygonFile attributes. This step should generally be performed prior to calling write(), as writing a file directly saves the data in contents to disk.

Construction polygons are not added to the contents list.