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

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