airsspy.utils

General utility functions for AIRSS workflows

Module Contents

Functions

trim_stream	Select a portion of a stream, return the portion without lines matched with extra_remove keywords.
filter_out_stream	Opposite of trim_stream, only the portion outside start end is selected.
calc_kpt_tuple_recip	Calculate reciprocal-space sampling with real-space parameter.
unique	Get a list of ordered unique items.
stream_to_list	Convert a stream to a list of strings.
safe_cast_float	Safely convert a string to float with fallback value.
safe_cast_int	Safely convert a string to int with fallback value.
extract_number_from_string	Extract the first number from a string.
find_pattern_in_file	Find all lines matching a pattern in a file.
count_pattern_in_file	Count occurrences of a pattern in a file.
format_time_elapsed	Format elapsed time in human-readable format.

API

airsspy.utils.trim_stream(stream: TextIO, start: str, end: str, extra_remove: Optional[List[str]] = None) → io.StringIO

Select a portion of a stream, return the portion without lines matched with extra_remove keywords.

Args: stream: Input stream to trim start: Regular expression pattern to start recording end: Regular expression pattern to stop recording extra_remove: List of additional patterns to filter out

Returns: StringIO object containing the trimmed content

airsspy.utils.filter_out_stream(stream: TextIO, start: str, end: str) → io.StringIO

Opposite of trim_stream, only the portion outside start end is selected.

Args: stream: Input stream to filter start: Regular expression pattern to start filtering out end: Regular expression pattern to stop filtering out

Returns: StringIO object containing the filtered content

airsspy.utils.calc_kpt_tuple_recip(structure: ase.Atoms, mp_spacing: float = 0.05, rounding: str = 'up') → Tuple[int, int, int]

Calculate reciprocal-space sampling with real-space parameter.

This function calculates k-point mesh based on a real-space spacing parameter, which is more intuitive than directly specifying k-points.

Args: structure: ASE Atoms object containing the structure mp_spacing: Real-space spacing parameter in Å^-1 rounding: Rounding method - “up” for ceiling, “down” for floor with +0.5

Returns: Tuple of k-point mesh (kx, ky, kz)

Note: Uses pymatgen for reciprocal lattice calculation.

airsspy.utils.unique(items: List) → List

Get a list of ordered unique items.

Args: items: List of items to deduplicate

Returns: List containing unique items in original order

airsspy.utils.stream_to_list(stream: TextIO) → List[str]

Convert a stream to a list of strings.

Args: stream: Input stream

Returns: List of lines from the stream

airsspy.utils.safe_cast_float(value: str, default: float = 0.0) → float

Safely convert a string to float with fallback value.

Args: value: String to convert default: Default value if conversion fails

Returns: Float value or default

airsspy.utils.safe_cast_int(value: str, default: int = 0) → int

Safely convert a string to int with fallback value.

Args: value: String to convert default: Default value if conversion fails

Returns: Integer value or default

airsspy.utils.extract_number_from_string(text: str, default: float = 0.0) → float

Extract the first number from a string.

Args: text: String containing numbers default: Default value if no number found

Returns: First number found or default

airsspy.utils.find_pattern_in_file(filename: str, pattern: str, max_matches: int = 0) → List[str]

Find all lines matching a pattern in a file.

Args: filename: Path to file to search pattern: Regular expression pattern to match max_matches: Maximum number of matches to return (0 for unlimited)

Returns: List of matching lines

airsspy.utils.count_pattern_in_file(filename: str, pattern: str) → int

Count occurrences of a pattern in a file.

Args: filename: Path to file to search pattern: Regular expression pattern to match

Returns: Number of matches found

airsspy.utils.format_time_elapsed(seconds: float) → str

Format elapsed time in human-readable format.

Args: seconds: Time in seconds

Returns: Formatted time string