doc:2025.1 spec updates (#613)

* doc:2025.1 spec updates

* Update source/elements/oneCCL/source/spec/collective_operations.rst

Co-authored-by: Robert Cohn <[email protected]>

* fix formatting errors

---------

Co-authored-by: Robert Cohn <[email protected]>
Co-authored-by: Cohn, Robert S <[email protected]>

Author: ranukund

source/elements/oneCCL/source/conf.py

@@ -16,12 +16,13 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+#
 import os
 import sys
-sys.path.insert(0, os.path.abspath(os.path.join('..','..','..','conf')))
-# element_conf needs to import this conf
-sys.path.insert(0, os.path.abspath('.'))
+from os.path import join
 
 project = 'oneCCL'
 
-from element_conf import *
+repo_root = join('..', '..', '..', '..')
+exec(open(join(repo_root, 'source', 'conf', 'common_conf.py')).read())
+exec(open(join(repo_root, 'source', 'conf', 'element_conf.py')).read())

source/elements/oneCCL/source/spec/collective_operations.rst

@@ -8,6 +8,7 @@ Collective Operations
 
 oneCCL specification defines the following collective communication operations:
 
+- `Allgather`_
 - `Allgatherv`_
 - `Allreduce`_
 - `Alltoallv`_
@@ -39,6 +40,66 @@ The communication operation may accept attribute object. If that parameter is mi
 
 If the arguments provided to a communication operation call do not comply to the requirements of the operation, the behavior is undefined unless it is specified otherwise.
 
+
+.. _Allgather:
+
+Allgather
+*********
+
+Allgather is a collective communication operation that collects the ``send_count`` elements from all the ranks within the communicator and places the results into ``recv_buf``, in such a way that data from rank ``i`` can be found at offset rank ``i * count``. The resulting data in the output ``recv_buf`` buffer is the same for each rank. 
+
+
+Allgather is in place when ``sendbuff == recvbuff + rank * send_count``. 
+
+.. code:: cpp
+
+     template<class BufferType> 
+     event ccl::allgather(const BufferType* send_buf, 
+                          BufferType* recv_buf, 
+                          size_t send_count, 
+                          const communicator& comm, 
+                          const stream& stream, 
+                          const allgather_attr& attr = default_allgather_attr, 
+                          const vector_class<event>& deps = {}); 
+
+     event ccl::allgather(const void* send_buf, 
+                          void* recv_buf, 
+                          size_t send_count, 
+                          datatype dtype,  
+                          const communicator& comm, 
+                          const stream& stream, 
+                          const allgather_attr& attr = default_allgather_attr, 
+                          const vector_class<event>& deps = {}); 
+
+
+
+send_buf 
+    The buffer with send_count elements of BufferType that stores local data to be gathered 
+
+recv_buf [out] 
+    The buffer to store gathered result of BufferTuype, must be large enough to hold values from all ranks, i.e., size should be equal do BufferType * send_count 
+
+send_count 
+    The number of elements of type BufferType in send_buf 
+
+dtype 
+    The datatype of elements in send_buf and recv_buf must be skipped if BufferType can be inferred otherwise must be passed explicitly 
+
+comm 
+    The communicator that defines a group of ranks for the operation 
+
+stream 
+    The stream associated with the operation  
+
+attr 
+    Optional attributes to customize the operation 
+
+deps 
+    An optional vector of the events that the operation should depend on 
+
+return event 
+    An object to track the progress of the operation 
+
 .. _Allgatherv:
 
 Allgatherv
@@ -250,50 +311,53 @@ return ``event``
 Broadcast
 *********
 
-Broadcast is a collective communication operation that broadcasts data
-from one rank of communicator (denoted as root) to all other ranks.
+Broadcast is a collective communication operation that broadcasts data from one rank of communicator (denoted as root) to all other ranks.
 
-.. code:: cpp
+Broadcast is in-place if send_buf == recv_buf 
 
-    template <class BufferType>
-    event ccl::broadcast(BufferType* buf,
-                         size_t count,
-                         int root,
-                         const communicator& comm,
-                         const stream& stream,
-                         const broadcast_attr& attr = default_broadcast_attr,
-                         const vector_class<event>& deps = {});
+.. code:: cpp
 
-    event ccl::broadcast(void* buf,
-                         size_t count,
-                         datatype dtype,
-                         int root,
-                         const communicator& comm,
-                         const stream& stream,
-                         const broadcast_attr& attr = default_broadcast_attr,
-                         const vector_class<event>& deps = {});
+    template <class BufferType> 
+    event ccl::broadcast(BufferType*send_buf, 
+                         BufferType*recv_buf, 
+                         size_t count, 
+                         int root, 
+                         const communicator& comm, 
+                         const stream& stream, 
+                         const broadcast_attr& attr = default_broadcast_attr, 
+                         const vector_class<event>& deps = {}); 
+ 
+     event ccl::broadcast(void* send_buf, 
+                          void* recv_buf 
+                          size_t count, 
+                          datatype dtype, 
+                          int root, 
+                          const communicator& comm, 
+                          const stream& stream, 
+                          const broadcast_attr& attr = default_broadcast_attr, 
+                          const vector_class<event>& deps = {}); 
+ 
 
-buf [in,out]
-    | the buffer with ``count`` elements of ``BufferType``
-    | serves as ``send_buf`` for root and as ``recv_buf`` for other ranks
+send_buf [in,out]
+    The buffer with ``count`` elements of ``BufferType`` serves as ``send_buf`` for root and as ``recv_buf`` for other ranks
 count
-    the number of elements of type ``BufferType`` in ``buf``
+    The number of elements of type ``BufferType`` in ``buf``
 root
-    the rank that broadcasts ``buf``
+    The rank that broadcasts ``buf``
 dtype
-    | the datatype of elements in ``buf``
-    | must be skipped if ``BufferType`` can be inferred
-    | otherwise must be passed explicitly
+     The datatype of elements in ``buf``
+     | must be skipped if ``BufferType`` can be inferred
+     | otherwise must be passed explicitly
 comm
-    the communicator that defines a group of ranks for the operation
+    The communicator that defines a group of ranks for the operation
 stream
-    the stream associated with the operation
+    The stream associated with the operation
 attr
-    optional attributes to customize the operation
+    Optional attributes to customize the operation
 deps
-    an optional vector of the events that the operation should depend on
+    An optional vector of the events that the operation should depend on
 return ``event``
-    an object to track the progress of the operation
+    An object to track the progress of the operation
 
 
 .. _Reduce:

source/elements/oneCCL/source/spec/group_calls.rst

@@ -0,0 +1,33 @@
+.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+============
+Group Calls
+============
+
+oneCCL specification defines the following group calls: 
+
+* group_start() 
+* group_end() 
+
+
+Group calls serve to merge multiple calls into a single group operation. These operations are initiated and finalized using primary functions: group_start() and group_end(). 
+
+Group_start 
+***********
+
+void CCL_API group_start(); 
+
+group_start() starts a group call. group_start() can be used to initiate a group call operation to indicate that successive operations should not get blocked due to CPU synchronization.  
+
+Group_end 
+*********
+
+void CCL_API group_end(); 
+
+group_end() ends a group call. The group_end() call returns when all the operations between group_start() and group_end() have been enqueued for execution, but not necessarily completed. 
+
+
+Note: Currently group calls are supported for point-to-point and collective operations.  
+

source/elements/oneCCL/source/spec/main_objects.rst

@@ -290,6 +290,38 @@ return ``context``
     See also: :doc:`collective_operations`
 
 
+
+.. _Split_communicator:
+
+SPLIT-COMMUNICATOR
+******************
+
+The communicator provides methods to create one or more new communicators from an existing communicator. The new sub-communicators are created based on user-supplied color and key. Each newly formed sub-communicator includes only the ranks that provided the same color. Within each sub-communicator, ranks are reordered by the ascending key. This call is collective over all ranks in the communicator. 
+
+.. code:: cpp
+
+    communicator split_communicator(const communicator& comm, int color, int key); 
+
+``comm``
+   An existing communicator handle.
+
+``color``
+    A value that defines which ranks will belong to the new sub-communicator. Ranks providing the same color are part of the same sub-communicator.  
+
+``key``
+    Used to order the ranks within each sub-communicator. Ranks in the resulting communicator are sorted by the ascending key. 
+
+ 
+
+Return Value 
+
+``communicator``
+    The handle to the new sub-communicator  
+
+ 
+
+
+
 .. _Stream:
 
 Stream

source/elements/oneCCL/source/spec/operations.rst

@@ -16,3 +16,4 @@ This section covers communication operations defined by oneCCL specification.
    collective_operations.rst
    operation_attributes.rst
    operation_progress.rst
+   group_calls.rst

source/elements/oneCCL/source/spec/reductions.rst

@@ -16,6 +16,7 @@ oneCCL specification defines the following reduction operations for :ref:`Allred
         prod   = /* unspecified */,
         min    = /* unspecified */,
         max    = /* unspecified */,
+        avg    = /* unspecified */,  
         custom = /* unspecified */
     };
 
@@ -27,6 +28,8 @@ reduction::min
     elementwise min
 reduction::max
     elementwise max
+reduction::avg
+    arithmethic average
 reduction::custom
     | specify user-defined reduction operation
     | the actual reduction function must be passed through ``reduction_fn`` operation attribute