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.InputArtifactSource#

Object needing local files on the machine running the simulation.

abstractmethod input_artifact_files() → list[str]#

Paths of the local files needed, relative to where the script defining them runs.

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.require_exec(exe: str, hint: str | None = None) → str#

Check an external tool is on PATH, so a missing one is reported by name.

For tools that cannot be package dependencies – anything not packaged for conda – where this being installed says nothing about them being available. @hint says what needs the tool and where it comes from.

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.remove_matching(directory: Path, pattern: str) → None#

Delete the files in directory whose name matches pattern.

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)

…