dubfi.linalg.segments
=====================

.. py:module:: dubfi.linalg.segments

.. autoapi-nested-parse::

   Segments for distributing vector space to worker processes.

   .. codeauthor:: Valentin Bruch, DWD <valentin.bruch@dwd.de>
   .. versionadded:: 0.1.0 (initial release)



Classes
-------

.. autoapisummary::

   dubfi.linalg.segments.AbstractSegment
   dubfi.linalg.segments.ContiguousSegment
   dubfi.linalg.segments.IndexedSegment
   dubfi.linalg.segments.Segments


Module Contents
---------------

.. py:class:: AbstractSegment

   Bases: :py:obj:`abc.ABC`


   Generic segments defining how a vector space is distributed to worker processes.

   Segments define how a data is distributed to worker processes.

   Consider data sharing a long dimension y and operations that
   are (approximately) local on y. Then y can be split and the
   data can be distributed to multiple processes, each containing
   one segment of y and some buffer. AbstractSegment contains the
   information required for selecting buffered and unbuffered
   data for one process.


   .. py:property:: buffered_size
      :type: int

      :abstractmethod:


      Segment size including buffer.


   .. py:property:: seg_size
      :type: int


      Size of data excluding buffer.


   .. py:method:: selbuffered_impl(data, axes)
      :abstractmethod:


      Given full data (parent), return the buffered segment (child).

      This method should be re-implemented by inheriting classes.



   .. py:method:: selbuffered(data, axes=(-1, ))

      Given full data (parent), return the buffered segment (child).



   .. py:method:: selunbuffered_impl(data, axes)
      :abstractmethod:


      Given full data (parent), return the unbuffered segment (child).

      This method should be re-implemented by inheriting classes.



   .. py:method:: selunbuffered(data, axes=(-1, ))

      Given full data (parent), return the unbuffered segment (child).



   .. py:method:: into(target, source, axes=(-1, ))
      :abstractmethod:


      Write segment from source (child) into target (parent).



   .. py:method:: addto(target, source, axes=(-1, ))
      :abstractmethod:


      Add segment from source (child) to target (parent).



.. py:class:: ContiguousSegment(buffer_start, data_start, data_end, buffer_end, parent_size)

   Bases: :py:obj:`AbstractSegment`


   Segment of contiguous data in the full vector space.

   Segment of contiguous data.

   In this segment, buffered data form a contiguous slice of the
   parent array. The unbuffered data are a contiguous slice of
   the buffered data.


   .. py:property:: buffered_size
      :type: int


      Segment size including buffer.


   .. py:method:: selbuffered_impl(data, axes)

      Given full data (parent), return the buffered segment (child).



   .. py:method:: selunbuffered_impl(data, axes)

      Given full data (parent), return the unbuffered segment (child).



   .. py:method:: into(target, source, axes=(-1, ))

      Write segment from source (child) into target (parent).



   .. py:method:: addto(target, source, axes=(-1, ))

      Add segment from source (child) to target (parent).



.. py:class:: IndexedSegment(buffer_idcs, start_idx, end_idx, parent_size)

   Bases: :py:obj:`AbstractSegment`


   Index-based segment selecting parts of the full vector space.

   Segment of arbitrary indexed data.

   This provides a generic segment of non-contiguous data. The
   buffered data are defined by an array of indices of the parent
   data. Unbuffered data are defined by a contiguous slice of these
   indices. This allows for arbitrary selection of buffered and
   unbuffered data.


   .. py:property:: buffered_size
      :type: int


      Segment size including buffer.


   .. py:method:: selbuffered_impl(data, axes)

      Given full data (parent), return the buffered segment (child).



   .. py:method:: selunbuffered_impl(data, axes)

      Given full data (parent), return the unbuffered segment (child).



   .. py:method:: into(target, source, axes=(-1, ))

      Write segment from source (child) into target (parent).



   .. py:method:: addto(target, source, axes=(-1, ))

      Add segment from source (child) to target (parent).



.. py:class:: Segments(size)

   Sequence of segments that shall jointly provide complete coverage of the full vector space.

   Sequence of AbstractSegments.


   .. py:method:: fromlist(segments)
      :classmethod:


      Create from a list of AbstractSegments.

      Assert that all segments are compatible and jointly complete.



   .. py:method:: add(seg)

      Add segment to segment list after checking that it is compatible.



   .. py:property:: number
      :type: int


      Number of segments in self.


   .. py:method:: __getitem__(idx)

      Get segment by index.



   .. py:method:: __iter__()

      Iterate over segments.



   .. py:method:: is_complete()

      Check whether segments are complete.