create_group

Applicability

Product	Supported
Atlas 350 Accelerator Card	√
Atlas A3 training product/Atlas A3 inference product	√
Atlas A2 training product/Atlas A2 inference product	√
Atlas 200I/500 A2 inference product	☓
Atlas inference product	√
Atlas training product	√

For Atlas A2 training product/Atlas A2 inference product, only the Atlas 800T A2 training server, Atlas 900 A2 PoD cluster basic unit, and Atlas 200T A2 Box16 heterogeneous subrack are supported.

For the Atlas inference products, only the Atlas 300I Duo inference card is supported.

Function

Creates a custom group for collective communication.

If a custom group is created without calling this API, all devices involved in cluster training are created as a global hccl_world_group by default.

group indicates the process group that participates in collective communication.

hccl_world_group: default global group (created by HCCL automatically), including all ranks that participate in collective communication.
Custom groups: a subset of process groups contained in hccl_world_group.

Prototype

def create_group(group, rank_num, rank_ids)

Parameters

Parameter	Input/Output	Description
group	Input	A string containing a maximum of 128 bytes, including the end character. The group name specifies the identifier of a collective communication group. It cannot be the default global group name hccl_world_group. Otherwise, the group fails to be created.
rank_num	Input	An int. Number of ranks in a group. The maximum value is 32768.
rank_ids	Input	A list. List of world_rank_ids that form the group. Different types of boards have different restrictions. For the Atlas training product: In single-server scenarios, rank_ids must meet the following requirements: The number of ranks must be 1, 2, 4, or 8. Devices 0-3 and devices 4-7 form two networks respectively. If the number of ranks is 2 or 4, AI processors selected must belong to the same cluster. In the server cluster scenario, rank_ids must meet the following requirements: The number of ranks selected for each server must be the same (the number must be 1, 2, 4, or 8). When the number of ranks for each server is 2 or 4, AI processors selected must belong to the same cluster. That is, the remainders of rank IDs divided by 8 are all less than 4, or all greater than or equal to 4. Example: Assume that a group is created for three servers. The rank IDs of the three servers are as follows: {0,1,2,3,4,5,6,7} {8,9,10,11,12,13,14,15} {16,17,18,19,20,21,22,23} rank_ids that meets the requirement may be: rank_ids=[1,9,17] rank_ids=[1,2,9,10,17,18] rank_ids=[4,5,6,7,12,13,14,15,20,21,22,23] Atlas A2 training product/Atlas A2 inference product: In single-server scenarios, no requirements exist on rank_ids. In server cluster scenarios, rank_ids must meet the following requirements: It is recommended that the same number of ranks be selected for each server (there is no requirement on the size of ranks) and the positions of the ranks selected for each server be the same (that is, the rank IDs have the same modulo 8). If the number of ranks selected for each server is different, the performance deteriorates. Example: Assume that a group is created for three servers. The rank IDs of the three servers are as follows: {0,1,2,3,4,5,6,7} {8,9,10,11,12,13,14,15} {16,17,18,19,20,21,22,23} rank_ids that meets the requirement may be: rank_ids=[1,9,17] rank_ids=[1,2,9,10,17,18] rank_ids=[4,5,6,7,12,13,14,15,20,21,22,23] Atlas A3 training product/Atlas A3 inference product: It is recommended that each SuperPoD have the same number of servers and each server have the same number of ranks. Otherwise, the performance degrades. Atlas 300I Duo Inference Card: Only single-server scenarios are supported, and there is no restriction on rank_ids. Supplementary notes: It is recommended that rank_ids be sorted based on the physical connection sequence of devices, that is, devices that are physically close to each other are arranged together. For example, if device_ip is set in ascending order based on the physical connection sequence, you are advised to set rank_ids in ascending order.

Parameter

Input/Output

Description

group

Input

A string containing a maximum of 128 bytes, including the end character.

The group name specifies the identifier of a collective communication group. It cannot be the default global group name hccl_world_group. Otherwise, the group fails to be created.

rank_num

Input

An int.

Number of ranks in a group.

The maximum value is 32768.

rank_ids

Input

A list.

List of world_rank_ids that form the group.

Different types of boards have different restrictions.

For the Atlas training product:

In single-server scenarios, rank_ids must meet the following requirements:
The number of ranks must be 1, 2, 4, or 8. Devices 0-3 and devices 4-7 form two networks respectively. If the number of ranks is 2 or 4, AI processors selected must belong to the same cluster.
In the server cluster scenario, rank_ids must meet the following requirements:
- The number of ranks selected for each server must be the same (the number must be 1, 2, 4, or 8).
- When the number of ranks for each server is 2 or 4, AI processors selected must belong to the same cluster. That is, the remainders of rank IDs divided by 8 are all less than 4, or all greater than or equal to 4.
Example:

Assume that a group is created for three servers. The rank IDs of the three servers are as follows:

{0,1,2,3,4,5,6,7}

{8,9,10,11,12,13,14,15}

{16,17,18,19,20,21,22,23}

rank_ids that meets the requirement may be:

rank_ids=[1,9,17]

rank_ids=[1,2,9,10,17,18]

rank_ids=[4,5,6,7,12,13,14,15,20,21,22,23]

Atlas A2 training product/Atlas A2 inference product:

In single-server scenarios, no requirements exist on rank_ids.
In server cluster scenarios, rank_ids must meet the following requirements:
It is recommended that the same number of ranks be selected for each server (there is no requirement on the size of ranks) and the positions of the ranks selected for each server be the same (that is, the rank IDs have the same modulo 8). If the number of ranks selected for each server is different, the performance deteriorates.

Example:

Assume that a group is created for three servers. The rank IDs of the three servers are as follows:

{0,1,2,3,4,5,6,7}

{8,9,10,11,12,13,14,15}

{16,17,18,19,20,21,22,23}

rank_ids that meets the requirement may be:

rank_ids=[1,9,17]

rank_ids=[1,2,9,10,17,18]

rank_ids=[4,5,6,7,12,13,14,15,20,21,22,23]

Atlas A3 training product/Atlas A3 inference product: It is recommended that each SuperPoD have the same number of servers and each server have the same number of ranks. Otherwise, the performance degrades.

Atlas 300I Duo Inference Card: Only single-server scenarios are supported, and there is no restriction on rank_ids.

Supplementary notes:

It is recommended that rank_ids be sorted based on the physical connection sequence of devices, that is, devices that are physically close to each other are arranged together. For example, if device_ip is set in ascending order based on the physical connection sequence, you are advised to set rank_ids in ascending order.

Returns

None

Constraints

This API must be called after the initialization of collective communication is complete.
The caller rank must be within the range defined by the group argument passed to this API call. Otherwise, the API call fails.

Call Example

from hccl.manage.api import create_group
create_group("myGroup", 4, [0, 1, 2, 3])

Parent topic: hccl.manage.api