4.3.3. Instantiation Configuration

4.3.3.1. Base

class simbricks.orchestration.instantiation.base.InstantiationEnvironment(workdir: Path, simbricksdir: Path)

repo_base(relative_path: str | None = None, must_exist: bool = True) → str

work_dir(relative_path: str | None = None, must_exist: bool = False) → str

output_base(relative_path: str | None = None, must_exist: bool = False) → str

tmp_simulation_files(relative_path: str | None = None, must_exist: bool = False) → str

img_dir(relative_path: str | None = None, must_exist: bool = False) → str

cp_dir(relative_path: str | None = None, must_exist: bool = False) → str

shm_base(relative_path: str | None = None, must_exist: bool = False) → str

proxy_dir(relative_path: str | None = None, must_exist: bool = False) → str

input_artifacts_dir(relative_path: str | None = None, must_exist: bool = False) → str

cfgtar_path(sim: sim_base.Simulator) → str

dynamic_img_path(img: disk_images.DiskImage, format: str) → str

hd_path(hd_name_or_path: str) → str

hdcopy_path(img: disk_images.DiskImage, format: str) → str

cpdir_sim(sim: sim_base.Simulator) → str

get_simulator_output_dir(sim: sim_base.Simulator) → str

get_simulator_shm_pool_path(sim: sim_base.Simulator) → str

get_simulation_output_path() → str

classmethod fromJSON(json_obj) → Self

id() → int

toJSON()

class simbricks.orchestration.instantiation.base.Instantiation(sim: sim_base.Simulation)

property command_executor: cmd_exec.CommandExecutorFactory

property fragments: list[Fragment]

get_fragment(id: int) → Fragment

toJSON() → dict

classmethod fromJSON(sim: sim_base.Simulation, json_obj: dict) → tpe.Self

get_socket(interface: Interface) → Socket | None

sim_dependencies() → SimulationDependencyGraph

property create_checkpoint: bool

Whether to use checkpoint and restore for simulators.

The most common use-case for this is accelerating host simulator startup by first running in a less accurate mode, then checkpointing the system state after boot and running simulations from there.

property restore_checkpoint: bool

property assigned_fragment: Fragment

async prepare() → None

async cleanup() → None

find_sim_by_interface(interface: sys_base.Interface) → sim_base.Simulator

find_sim_by_spec(spec: sys_base.Component) → sim_base.Simulator

create_proxy_pair(ProxyImplementation: type[Proxy], fragment_a: Fragment, fragment_b: Fragment) → ProxyPair

Create a pair of proxies for connecting two fragments. Can be invoked multiple times with the same two fragments to create multiple proxy connections between them.

get_proxy_pair(proxy: Proxy) → ProxyPair

Use given proxy to find previously created proxy pair.

id() → int

get_interface_socktype(inf: Interface) → SockType

finalize_validate() → None

This function can be invoked manually in the experiment script to validate system configuration, simulation configration, and instantiation early. Regardless, it is also always invoked before running an instantiation to do some final processing steps. To allow this, we guarantee idempotence, i.e. calling this function one or multiple times has the same effect.

4.3.3.2. Fragment

class simbricks.orchestration.instantiation.fragment.Fragment(fragment_executor_tag: str | None = None, runner_tags: set[str] | None = None)

toJSON() → dict

classmethod fromJSON(json_obj: dict, simulation: sim_base.Simulation) → tpe.Self

property cores_required: int

property memory_required: int

static merged(*fragments: Fragment) → Fragment

add_simulators(*sims: sim_base.Simulator)

add_proxies(*proxies: Proxy)

all_simulators() → set[sim_base.Simulator]

all_proxies() → set[Proxy]

find_proxy_by_interface(interface: sys_base.Interface) → proxy.Proxy | None

get_proxy_by_interface(interface: sys_base.Interface) → proxy.Proxy

Same as find_proxy_by_interface() but raises an Error if interface is not assigned to any proxy in this fragment.

get_proxy_by_id(id: int) → Proxy

interface_handled_by_proxy(interface: sys_base.Interface) → bool

id() → int

4.3.3.3. Dependency Graph

Module for building graph for determinining starting order of components like simulators and proxies that runner starts.

class simbricks.orchestration.instantiation.dependency_graph.SimulationDependencyNodeType(value)

An enumeration.

SIMULATOR = 'simulator'

Simulator in assigned fragment.

PROXY = 'proxy'

Proxy in assigned fragment.

EXTERNAL_PROXY = 'external proxy'

Proxy outside assigned fragment.

class simbricks.orchestration.instantiation.dependency_graph.SimulationDependencyNode(type: SimulationDependencyNodeType, value: Simulator | Proxy)

get_simulator() → Simulator

get_proxy() → Proxy

class simbricks.orchestration.instantiation.dependency_graph.SimulationDependencyGraph

Dict mapping from to-be-instantiated component like a simulator to its dependencies. Dependencies have to start first before the component stored as key can start. All keys are components from the assigned fragment. Mapped values can also contain components from other fragments though.

alias of dict[SimulationDependencyNode, set[SimulationDependencyNode]]

simbricks.orchestration.instantiation.dependency_graph.build_simulation_dependency_graph(inst: inst_base.Instantiation) → SimulationDependencyGraph

Build a dependency graph for the simulator and proxy starting order. The listening side of a SimBricks connection has to be started first since it creates the SHM queue.

4.3.3.4. Proxy

class simbricks.orchestration.instantiation.proxy.Proxy

toJSON() → dict

classmethod fromJSON(json_obj: dict, simulation: sim_base.Simulation) → tpe.Self

property name: str

property interfaces: list[sys_base.Interface]

abstract run_cmd(inst: inst_base.Instantiation, runner_ip: str) → str

sockets_wait(inst: inst_base.Instantiation) → set[inst_socket.Socket]

async wait_ready() → None

async read_listening_info() → None

id() → int

class simbricks.orchestration.instantiation.proxy.DummyProxy

async read_listening_info() → None

run_cmd(inst: inst_base.Instantiation, runner_ip: str) → str

classmethod fromJSON(json_obj: dict, simulation: sim_base.Simulation) → tpe.Self

id() → int

property interfaces: list[sys_base.Interface]

property name: str

sockets_wait(inst: inst_base.Instantiation) → set[inst_socket.Socket]

toJSON() → dict

async wait_ready() → None

class simbricks.orchestration.instantiation.proxy.TCPProxy

run_cmd(inst: inst_base.Instantiation, runner_ip: str) → str

classmethod fromJSON(json_obj: dict, simulation: sim_base.Simulation) → tpe.Self

id() → int

property interfaces: list[sys_base.Interface]

property name: str

async read_listening_info() → None

sockets_wait(inst: inst_base.Instantiation) → set[inst_socket.Socket]

toJSON() → dict

async wait_ready() → None

class simbricks.orchestration.instantiation.proxy.RDMAProxy

classmethod fromJSON(json_obj: dict, simulation: sim_base.Simulation) → tpe.Self

id() → int

property interfaces: list[sys_base.Interface]

property name: str

async read_listening_info() → None

abstract run_cmd(inst: inst_base.Instantiation, runner_ip: str) → str

sockets_wait(inst: inst_base.Instantiation) → set[inst_socket.Socket]

toJSON() → dict

async wait_ready() → None

class simbricks.orchestration.instantiation.proxy.ProxyPair(instantiation: inst_base.Instantiation, fragment_a: inst_fragment.Fragment, fragment_b: inst_fragment.Fragment, proxy_a: Proxy, proxy_b: Proxy)

id() → int

toJSON() → dict

classmethod fromJSON(json_obj: dict, instantiation: inst_base.Instantiation) → tpe.Self

assign_sim_channel(channel: sys_base.Channel) → None

4.3.3.5. Socket

class simbricks.orchestration.instantiation.socket.SockType(value)

An enumeration.

LISTEN = 'listen'

CONNECT = 'connect'

class simbricks.orchestration.instantiation.socket.Socket(path: str = '', ty: SockType = SockType.LISTEN)

async wait()

Wait for socket to become available.

classmethod fromJSON(json_obj) → Self

id() → int

toJSON()