4.3.5. Utilities#

Shared utilities from the simbricks-utils package, most notably the Time unit enum used for latencies and synchronization periods.

4.3.5.1. Base Utilities#

class simbricks.utils.base.IdObj#

id() → int#

toJSON()#

classmethod fromJSON(json_obj) → Self#

class simbricks.utils.base.Time(*values)#

Picoseconds = 0#

Nanoseconds = 1#

Microseconds = 1000#

Milliseconds = 1000000#

Seconds = 1000000000#

conjugate()#: Returns self, the complex conjugate of any int.

bit_length()#

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6

bit_count()#

Number of ones in the binary representation of the absolute value of self.

Also known as the population count.

>>> bin(13)
'0b1101'
>>> (13).bit_count()
3

to_bytes(length=1, byteorder='big', *, signed=False)#

Return an array of bytes representing an integer.

length: Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes. Default is length 1.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value. Default is to use ‘big’.
signed: Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

classmethod from_bytes(bytes, byteorder='big', *, signed=False)#

Return the integer represented by the given array of bytes.

bytes: Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value. Default is to use ‘big’.
signed: Indicates whether two’s complement is used to represent the integer.

as_integer_ratio()#

Return a pair of integers, whose ratio is equal to the original int.

The ratio is in lowest terms and has a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)

is_integer()#: Returns True. Exists for duck type compatibility with float.is_integer.

real#: the real part of a complex number

imag#: the imaginary part of a complex number

numerator#: the numerator of a rational number in lowest terms

denominator#: the denominator of a rational number in lowest terms

simbricks.utils.base.filter_None_dict(to_filter: dict) → dict#

simbricks.utils.base.check_type(obj, expected_type) → bool#: Checks if obj has type or is a subtype of expected_type obj: an class object expected_type: a type object

simbricks.utils.base.check_types(obj, *expected_types) → bool#: Checks if obj has type or is a subtype of any of expected_types obj: an class object expected_types: list of type objects

simbricks.utils.base.has_expected_type(obj, expected_type) → None#

simbricks.utils.base.has_attribute(obj, attr: str) → None#

simbricks.utils.base.get_json_attr_top_or_none(json_obj: dict, attr: str) → Any | None#

simbricks.utils.base.has_json_attr_top(json_obj: dict, attr: str) → None#

simbricks.utils.base.get_json_attr_top(json_obj: dict, attr: str) → Any#

simbricks.utils.base.get_cls_from_type_module(type_name: str, module_name: str, required: bool) → Any#

simbricks.utils.base.get_cls_by_json(json_obj: dict, required: bool = True) → Any#

simbricks.utils.base.list_tuple_to_json(list: list | tuple) → list#

simbricks.utils.base.dict_to_json(data: dict) → dict#

simbricks.utils.base.json_array_to_list(array: list, required: bool = True) → list#

simbricks.utils.base.json_to_dict(json_obj: dict, required: bool = True) → dict#

simbricks.utils.base.enum_subs(enum_class: Type[ET], *exclude_values: ET) → list[ET]#

4.3.5.2. File Utilities#

Utility functions for operations on files and directories.

async simbricks.utils.file.await_file(path: str, delay=0.1, verbose=False, timeout=600) → None#

simbricks.utils.file.mkdir(path: str) → None#

simbricks.utils.file.rmtree(path: str) → None#

simbricks.utils.file.is_absolute_exists(path: str) → bool#

simbricks.utils.file.join_paths(base: str | PathLike[str], relative_path: str, must_exist=False) → str#

simbricks.utils.file.build_path_resolver(relative_to_conda_env: str, custom_env: str | None, relative_to_custom_env: str | None, file_relative_to_base: str) → Callable[[str | None], str]#

Build a resolver that turns an optional user-provided path into a concrete one.

Simulator objects are built on the client but run on the executor. In between they are serialized and rebuilt via fromJSON, which does not run __init__. So a path computed in __init__ reaches the executor as a literal string: an absolute path valid only on the client’s machine. Instead, keep what the user passed (usually None = “use the default”) in the serialized state and resolve it on the executor, at the point of use. This captures the rules for finding a file rather than the result of applying them, so they are evaluated wherever the resolver is called — which means: never call it on the client and store the result.

Resolution order: an explicit non-empty path is returned unchanged; otherwise the base is $custom_env[/relative_to_custom_env] if that variable is set, else $CONDA_PREFIX/relative_to_conda_env, with file_relative_to_base appended. If neither variable is set the prefix degrades to "", yielding a root-anchored path.

Parameters:

relative_to_conda_env – Install root relative to $CONDA_PREFIX.
custom_env – Environment variable that replaces the conda prefix when set on the executor.
relative_to_custom_env – Optional subdirectory appended to custom_env.
file_relative_to_base – Path of the file itself, relative to the resolved base.

Returns:

A callable taking the user-provided path (or None/"" for the default).

Example

…

def __init__(

self, simulation: sim_base.Simulation, executable: str | None = None, config: str | None = None,

):

super().__init__(: simulation=simulation, executable=”” if executable is None else executable,

) self.resolve_exe = build_path_resolver(

“opt”, “GEM5_PREFIX”, None, “gem5/build/X86/gem5”

) self.resolve_conf = build_path_resolver(

“opt”, “GEM5_PREFIX”, None, “gem5/configs/simbricks/simbricks.py”

)

…

def run_cmd(self, inst: inst_base.Instantiation) -> str:: exe = self.resolve_exe(self._executable) conf = self.resolve_conf(self._config)

…