dragon.infrastructure.facts

Specified constants and names used in the Dragon runtime.

Module Attributes

`GS_INPUT_CUID`	Input channel unique ID for Global Services head
`LAUNCHER_PUID`	Unique process ID for head user process started by the launcher
`GS_PUID`	Unique process ID given for the global services process
`FIRST_PUID`	The first PUID for user applications launched by local services
`BASE_EXTERNAL_PUID`	Starting value of the PUID namespace reserved for externally attached processes.
`EXTERNAL_PUID_BLOCK_SIZE`	Number of external process identities assigned to each node for one runtime.
`FIRST_TRANSPORT_PUID`	Base index used by the transport services for the unique process ID (puid)
`RANGE_TRANSPORT_PUID`	Range of the unique process ID's for the transport services
`BASE_PMOD_LAUNCH_CUID`	Starting value for PMOD launch Channel ID (cuid) that communicates with the client pmod at process launch
`RANGE_PMOD_LAUNCH_CUID`	Range for the PMOD launch channel ID's (cuid) that communicates with the client pmod at process launch
`BASE_USER_MANAGED_CUID`	Starting value of a reserved range of cuids that can be managed by a user
`RANGE_USER_MANAGED_CUID`	Range for the user managed cuids
`BASE_TA_CUID`	Starting value of the local transport agent channel unique ID (cuid)
`RANGE_TA_CUID`	Range for the local transport agent channel ID's (cuid)
`BASE_BE_FE_CUID`	Starting value for the backend channel ID (cuid) that communicates with the frontend
`RANGE_BE_FE_CUID`	Range for the backend channel ID's (cuid) that communicate with the frontend
`BASE_BE_CUID`	Starting value for the local launcher backend channel unique ID (cuid)
`RANGE_BE_CUID`	Range for the local launcher backend channel ID's (cuid)
`BASE_GW_CUID`	Starting value for the gateway channel unique ID (cuid)
`RANGE_GW_CUID`	Range for the gateway channel ID's (cuid)
`BASE_LOG_CUID`	Base value for the logging channel ID (cuid)
`RANGE_LOG_CUID`	Range for the logging channel ID's (cuid)
`BASE_BE_GW_CUID`	Starting value for the backend channel ID (cuid) of the infrastructure transport gateway channel
`RANGE_BE_GW_CUID`	Range for the backend channel ID's (cuid) of the infrastructure transport gateway channel
`BASE_BE_LOCAL_CUID`	Starting value for the backend channel ID (cuid) that communicates with its transport agent
`RANGE_BE_LOCAL_CUID`	Range for the backend channel ID's (cuid) that communicate with its transport agent
`LS_CUID_POW`	Starting value of the local services channel unique ID (cuid)
`RANGE_LS_CUID`	Range for the local services channel ID's (cuid)
`FIRST_CUID`	Starting value of the User created channel ID (cuid)
`ATTACH_INFO_FILENAME`	Filename written under attach_runtime_dir() at startup
`ATTACH_RUNTIME_DIR_NAME_TEMPLATE`	Name of the per-user attach-info directory created under tempfile.gettempdir(); the C side (src/lib/ext_attach.cpp) duplicates this and uses dragon_gettempdir()
`ATTACH_DIR_ENV`	Environment variable that overrides the attach-info directory (writer, readers, and cleanup)
`ATTACH_INFO_KVS_KEY`	Well-known key in the Local Services key-value store holding the attach-info JSON.
`CTRL_EVENT_KVS_KEY`	Well-known key in the Local Services key-value store holding the serialized ctrl_event for the runtime head process.
`DRAGON_ATTACH_TOKEN_ENV`	Environment variable holding the attach auth token.
`BASE_ATTACH_TEMP_CUID`	Starting value of the temporary reply channel CUIDs used during co-located process attach.
`RANGE_ATTACH_TEMP_CUID`	Number of distinct temporary attach CUIDs available (one per concurrent PID)
`FIRST_LS_MANAGED_MUID`	First MUID managed by Local Services.
`RANGE_LS_MUIDS_PER_NODE`	Number of MUIDs possible allowable for each Local Services The difference between FIRST_LS_MANAGED_MUID and FIRST_BE_MUID is 2**59 (i.e. FIRST_LS_MANAGED_MUID).
`FIRST_BE_MUID`	First backend pool ID (MUID) needed for the overlay network transport
`RANGE_BE_MUID`	Range of the backend pool ID's (MUID) needed for the overlay network transport
`FE_OVERLAY_TRANSPORT_AGENT_MUID`	Pool for the frontend overlay network transport agent
`FIRST_LOGGING_MUID`	First Logging MUID
`FIRST_DEFAULT_MUID`	First MUID of Default Pools.
`FIRST_MUID`	User Pool MUID starting value.
`FIRST_GUID`	Starting value for the Group of resources (guid)
`FRONTEND_HOSTID`	Frontend's magic host ID
`LOCAL_LAUNCH_TIMEOUT`	Timeout for launch of the runtime.

Functions

`attach_runtime_dir`()	Return `DRAGON_ATTACH_DIR` if set, otherwise `default_attach_runtime_dir()`.
`attach_temp_cuid_from_pid`(pid)	Return a deterministic temporary CUID for the given OS process ID.
`be_fe_cuid_from_hostid`(host_id)	Return the unique backend Channel ID that communicates with the fronted, based on the host id
`be_gw_cuid_from_hostid`(host_id)	Return the unique backend channel ID of the overlay network transport gateway channel, based on the host id
`be_local_cuid_in_from_hostid`(host_id)	Return the unique channel ID based on host id, for a backend channel that acts as an inbound initializer for its communication with transport agent
`be_local_cuid_out_from_hostid`(host_id)	Return the unique channel ID based on host id, for a backend channel that acts as an outbound initializer for its communication with transport agent
`be_pool_muid_from_hostid`(host_id)	Return the backend memory pool unique ID based on the host index
`default_attach_runtime_dir`()	Return this user's attach-info directory under `tempfile.gettempdir()`.
`default_pool_muid_from_index`(index)	Return the unique managed memory pool ID of the default user pool from the node index.
`env_name`(parameter_name)
`external_puid_bounds`(node_index)	Return the half-open external PUID interval assigned to a node.
`external_puid_node_index`(puid)	Return the node owning an external PUID, rejecting non-members.
`get_port`(min_port, port_range)
`gw_cuid_from_index`(index, num_gw_channels)	Return the unique Channel ID of the first gateway channel from the local node index
`index_from_default_pool_muid`(m_uid)	Return the unique node index from the default pool id.
`index_from_infrastructure_pool_muid`(m_uid)	Return the node index from the unique managed memory pool ID of the default infrastructure pool.
`index_from_localservices_cuid`(cuid)	Retun the local node index from the `c_uid` of local services.
`infrastructure_pool_muid_from_index`(index)	Return the unique managed memory pool ID of the default infrastructure pool from the node index.
`is_default_pool`(m_uid)	Check if the given `m_uid` is a default `m_uid`.
`is_external_puid`(puid)	Return whether puid belongs to the external-only PUID namespace.
`is_pre_defined_pool`(m_uid)	Return if the pool corresponding to the given `m_uid` is pre-defined by the runtime.
`is_transport_puid`(puid)	Check whether a puid is associated with a transport agent
`launcher_cuid_from_index`(index)	Get the unique Channel ID of the local Launcher backend from the node index.
`lazy_import`(name)	Lazily imports a module so the module isn't loaded into memory unless it's executed
`local_pool_first_muid`(index)	Return the first muid for local services managed pools given the node index
`localservices_cuid_from_index`(index)	Get the unique Channel ID of local services from the node index.
`logging_pool_muid_from_index`(index)	Return the unique managed memory pool ID of the default logging pool from the node index.
`pmod_launch_cuid_from_jobinfo`(host_id, ...)	Return the unique channel ID based on host id, for a channel that initializes a client PMI process with its required pmod data.
`port_check`(ip_port)
`runtime_pool_name`(suffix[, extra, host_id])
`transport_cuid_from_index`(index)	Get the unique Channel ID of the local transport agent from the nodex index.
`transport_puid_from_index`(index)	Get the unique process ID from the node index.
`validate_external_puid_block_size`(block_size)	Validate an external PUID block size against the public integer range.

Classes

`HighSpeedTransportBackends`	Enumerated list of supported high-speed transport backends
`PMIBackend`	Supported backends for launching MPI applications with ProcessGroup
`TransportAgentOptions`	Enumerated list of supported transport agents

env_name(parameter_name: str) → str[source]

GS_INPUT_CUID = 2: Input channel unique ID for Global Services head

LAUNCHER_PUID = 0: Unique process ID for head user process started by the launcher

GS_PUID = 1: Unique process ID given for the global services process

FIRST_PUID = 4294967296: The first PUID for user applications launched by local services

BASE_EXTERNAL_PUID = 281474976710656: Starting value of the PUID namespace reserved for externally attached processes. External PUIDs are handed out by LocalServices from this initial puid and with the block size below. This may not be enough space for all nodes in extremely large deployments. In such cases, adjustments to the FIRST_PUID and the BASE_EXTERNAL_PUID may need to be made.

EXTERNAL_PUID_BLOCK_SIZE = 512: Number of external process identities assigned to each node for one runtime.

validate_external_puid_block_size(block_size: int) → int[source]: Validate an external PUID block size against the public integer range.

external_puid_bounds(node_index: int) → tuple[int, int][source]: Return the half-open external PUID interval assigned to a node.

is_external_puid(puid: int) → bool[source]: Return whether puid belongs to the external-only PUID namespace.

external_puid_node_index(puid: int) → int[source]: Return the node owning an external PUID, rejecting non-members.

FIRST_TRANSPORT_PUID = 256: Base index used by the transport services for the unique process ID (puid)

RANGE_TRANSPORT_PUID = 4294967040: Range of the unique process ID’s for the transport services

BASE_PMOD_LAUNCH_CUID = 18014398509481984: Starting value for PMOD launch Channel ID (cuid) that communicates with the client pmod at process launch

RANGE_PMOD_LAUNCH_CUID = 18014398509481984: Range for the PMOD launch channel ID’s (cuid) that communicates with the client pmod at process launch

BASE_USER_MANAGED_CUID = 18014398509481984: Starting value of a reserved range of cuids that can be managed by a user

RANGE_USER_MANAGED_CUID = 18014398509481984: Range for the user managed cuids

BASE_TA_CUID = 36028797018963968: Starting value of the local transport agent channel unique ID (cuid)

RANGE_TA_CUID = 36028797018963968: Range for the local transport agent channel ID’s (cuid)

BASE_BE_FE_CUID = 72057594037927936: Starting value for the backend channel ID (cuid) that communicates with the frontend

RANGE_BE_FE_CUID = 72057594037927936: Range for the backend channel ID’s (cuid) that communicate with the frontend

BASE_BE_CUID = 144115188075855872: Starting value for the local launcher backend channel unique ID (cuid)

RANGE_BE_CUID = 144115188075855872: Range for the local launcher backend channel ID’s (cuid)

BASE_GW_CUID = 288230376151711744: Starting value for the gateway channel unique ID (cuid)

RANGE_GW_CUID = 288230376151711744: Range for the gateway channel ID’s (cuid)

BASE_LOG_CUID = 576460752303423488: Base value for the logging channel ID (cuid)

RANGE_LOG_CUID = 576460752303423488: Range for the logging channel ID’s (cuid)

BASE_BE_GW_CUID = 1152921504606846976: Starting value for the backend channel ID (cuid) of the infrastructure transport gateway channel

RANGE_BE_GW_CUID = 1152921504606846976: Range for the backend channel ID’s (cuid) of the infrastructure transport gateway channel

BASE_BE_LOCAL_CUID = 2305843009213693952: Starting value for the backend channel ID (cuid) that communicates with its transport agent

RANGE_BE_LOCAL_CUID = 2305843009213693952: Range for the backend channel ID’s (cuid) that communicate with its transport agent

LS_CUID_POW = 62: Starting value of the local services channel unique ID (cuid)

RANGE_LS_CUID = 4611686018427387904: Range for the local services channel ID’s (cuid)

FIRST_CUID = 9223372036854775808: Starting value of the User created channel ID (cuid)

ATTACH_INFO_FILENAME = 'attach_info.txt': Filename written under attach_runtime_dir() at startup

ATTACH_RUNTIME_DIR_NAME_TEMPLATE = 'dragon_{uid}': Name of the per-user attach-info directory created under tempfile.gettempdir(); the C side (src/lib/ext_attach.cpp) duplicates this and uses dragon_gettempdir()

ATTACH_DIR_ENV = 'DRAGON_ATTACH_DIR': Environment variable that overrides the attach-info directory (writer, readers, and cleanup)

default_attach_runtime_dir() → str[source]: Return this user’s attach-info directory under tempfile.gettempdir().

attach_runtime_dir() → str[source]: Return DRAGON_ATTACH_DIR if set, otherwise default_attach_runtime_dir().

ATTACH_INFO_KVS_KEY = 'dragon_attach_info': Well-known key in the Local Services key-value store holding the attach-info JSON. Local Services populates this at startup (single-node mode) so that managed processes can retrieve attach metadata via dragon.utils.get_local_kv() instead of reading a file.

CTRL_EVENT_KVS_KEY = 'dragon_ctrl_event': Well-known key in the Local Services key-value store holding the serialized ctrl_event for the runtime head process. Written by every LS node when GS broadcasts a LSStoreCtrlEvent message so that any attached process can retrieve and set it via dragon.utils.get_local_kv().

DRAGON_ATTACH_TOKEN_ENV = 'DRAGON_ATTACH_TOKEN': Environment variable holding the attach auth token. Used both to hand the token to the multi-node Global Services subprocess and as the fallback token source for dragon.attach() when no token argument is supplied.

BASE_ATTACH_TEMP_CUID = 9007199254740992: Starting value of the temporary reply channel CUIDs used during co-located process attach. The range 2**53 .. 2**53 + 2**20 - 1 is free; defined infrastructure ranges start at 2**54.

RANGE_ATTACH_TEMP_CUID = 1048576: Number of distinct temporary attach CUIDs available (one per concurrent PID)

attach_temp_cuid_from_pid(pid: int) → int[source]

Return a deterministic temporary CUID for the given OS process ID.

The result lies in [BASE_ATTACH_TEMP_CUID, BASE_ATTACH_TEMP_CUID + RANGE_ATTACH_TEMP_CUID).

FIRST_LS_MANAGED_MUID = 576460752303423488: First MUID managed by Local Services.

RANGE_LS_MUIDS_PER_NODE = 34359738368: Number of MUIDs possible allowable for each Local Services The difference between FIRST_LS_MANAGED_MUID and FIRST_BE_MUID is 2**59 (i.e. FIRST_LS_MANAGED_MUID). So we can take FIRST_LS_MANAGED_MUID and divide by max nodes to get the range provided by each node.

FIRST_BE_MUID = 1152921504606846976: First backend pool ID (MUID) needed for the overlay network transport

RANGE_BE_MUID = 1152921504606846976: Range of the backend pool ID’s (MUID) needed for the overlay network transport

FE_OVERLAY_TRANSPORT_AGENT_MUID = 1152921504606846975: Pool for the frontend overlay network transport agent

FIRST_LOGGING_MUID = 2305843009213693952: First Logging MUID

FIRST_DEFAULT_MUID = 4611686018427387904: First MUID of Default Pools.

FIRST_MUID = 9223372036854775808: User Pool MUID starting value.

FIRST_GUID = 9223372036854775808: Starting value for the Group of resources (guid)

FRONTEND_HOSTID = 1: Frontend’s magic host ID

LOCAL_LAUNCH_TIMEOUT = 60: Timeout for launch of the runtime. Local for node-local comms. Remote for transport agent enabled.

runtime_pool_name(suffix: str, extra: str = '', *, host_id=None) → str[source]

is_transport_puid(puid) → bool[source]

Check whether a puid is associated with a transport agent

Parameters:: puid (int) – puid of a process
Returns:: Whether the puid is associated with pre-defined puid value
Type:: bool

transport_puid_from_index(index) → int[source]

Get the unique process ID from the node index. Otherwise, throw an AssertionError

Parameters:: index (int) – node index
Returns:: p_uid of the local transport
Return type:: int

launcher_cuid_from_index(index: int) → int[source]

Get the unique Channel ID of the local Launcher backend from the node index.

Parameters:: index (int) – local node index.
Returns:: c_uid of the Launcher backend
Return type:: int

transport_cuid_from_index(index: int) → int[source]

Get the unique Channel ID of the local transport agent from the nodex index.

Parameters:: index (int) – local node index
Returns:: c_uid of the local transport agent
Return type:: int

localservices_cuid_from_index(index: int) → int[source]

Get the unique Channel ID of local services from the node index.

Parameters:: index (int) – Local node index
Returns:: c_uid of the Local Services
Return type:: int

gw_cuid_from_index(index: int, num_gw_channels: int) → int[source]

Return the unique Channel ID of the first gateway channel from the local node index

Parameters:

index (int) – local node index
num_gw_channels (int) – number of gateway channels

Returns:

c_uid of first gateway channel

Return type:

int

be_gw_cuid_from_hostid(host_id)[source]

Return the unique backend channel ID of the overlay network transport gateway channel, based on the host id

Parameters:: host_id (int) – host id
Returns:: c_uid of backend transport gateway channel
Return type:: int

be_fe_cuid_from_hostid(host_id)[source]

Return the unique backend Channel ID that communicates with the fronted, based on the host id

Parameters:: host_id (int) – host id
Returns:: c_uid of backend channel that communicates with fronted
Return type:: int

be_local_cuid_in_from_hostid(host_id)[source]

Return the unique channel ID based on host id, for a backend channel that acts as an inbound initializer for its communication with transport agent

Parameters:: host_id (int) – host id
Returns:: c_uid of backend inbound channel that communicates with transport agent
Return type:: int

be_local_cuid_out_from_hostid(host_id)[source]

Return the unique channel ID based on host id, for a backend channel that acts as an outbound initializer for its communication with transport agent

Parameters:: host_id (int) – host id
Returns:: c_uid of backend outbound channel that communicates with transport agent
Return type:: int

pmod_launch_cuid_from_jobinfo(host_id, job_id, lrank)[source]

Return the unique channel ID based on host id, for a channel that initializes a client PMI process with its required pmod data.

Parameters:: host_id (int) – host id
Returns:: c_uid of backend outbound channel that communicates with transport agent
Return type:: int

default_pool_muid_from_index(index: int) → int[source]

Return the unique managed memory pool ID of the default user pool from the node index.

Parameters:: index (int) – index of this node
Returns:: m_uid of user pool
Return type:: int

logging_pool_muid_from_index(index: int) → int[source]

Return the unique managed memory pool ID of the default logging pool from the node index.

Parameters:: index (int) – index of this node
Returns:: m_uid of logging pool
Return type:: int

infrastructure_pool_muid_from_index(index: int) → int[source]

Return the unique managed memory pool ID of the default infrastructure pool from the node index.

Parameters:: index (int) – index of this node
Returns:: m_uid of the infrastructure pool
Return type:: int

local_pool_first_muid(index: int) → int[source]

Return the first muid for local services managed pools given the node index: provided. Each local services uses this to begin allocating muids starting at a specfic integer.

Parameters:: index (int) – index of this node
Returns:: m_uid of the infrastructure pool
Return type:: int

index_from_infrastructure_pool_muid(m_uid: int) → int[source]

Return the node index from the unique managed memory pool ID of the default infrastructure pool.

Parameters:: m_uid – m_uid of the infrastructure pool
Returns:: unique node index of this node
Return type:: int

be_pool_muid_from_hostid(host_id)[source]

Return the backend memory pool unique ID based on the host index

Parameters:: host_id – host id
Returns:: unique ID of the backend memory pool
Return type:: int

is_pre_defined_pool(m_uid: int) → bool[source]

Return if the pool corresponding to the given m_uid is pre-defined by the runtime.

Parameters:: m_uid (int) – uid to check
Returns:: True if the m_uid is predefined, otherwise throw an AssertionError.
Return type:: bool

index_from_localservices_cuid(cuid: int) → int[source]

Retun the local node index from the c_uid of local services.

Parameters:: cuid (int) – unique channel id of the local services
Returns:: Unique local node index.
Return type:: int

is_default_pool(m_uid: int) → bool[source]

Check if the given m_uid is a default m_uid. Otherwise throw an AssertionError.

Parameters:: m_uid (int) – uid to check
Returns:: True
Return type:: bool

index_from_default_pool_muid(m_uid: int) → int[source]

Return the unique node index from the default pool id.

Parameters:: m_uid (int) – A default pool id.
Returns:: node index
Return type:: int

class TransportAgentOptions[source]

Bases: Enum

Enumerated list of supported transport agents

HSTA = 'hsta'

TCP = 'tcp'

DRAGON_CONFIG = 'configured'

static from_str(s)[source]

Obtain enum value from TransportAgentOptions string

Parameters:: s (str) – string representation of enumerated TransportAgentOptions
Returns:: name of an available transport agent
Return type:: TransportAgentOptions

class HighSpeedTransportBackends[source]

Bases: str, Enum

Enumerated list of supported high-speed transport backends

UCX = 'ucx'

OFI = 'ofi'

static from_str(s)[source]

Obtain enum value from HighSpeedTransportBackends string

Parameters:: s (str) – string representation of enumerated HighSpeedTransportBackends
Returns:: name of the available high-speed transport backend
Return type:: HighSpeedTransportBackends
Raises:: ValueError

class PMIBackend[source]

Bases: str, Enum

Supported backends for launching MPI applications with ProcessGroup

CRAY = 'cray'

PMIX = 'pmix'

static from_str(s)[source]

port_check(ip_port)[source]

get_port(min_port, port_range)[source]

lazy_import(name)[source]

Lazily imports a module so the module isn’t loaded into memory unless it’s executed

Parameters:: name (str) – name of module to be imported
Returns:: the imported module
Return type:: module