====================================
Architecture in ScotchPy
====================================

Architectures are implemented in ScotchPy with the Arch class.

The Arch class
###############



.. class:: Arch(init=True)

  The graph constructor itself calls libscotch's ``archAlloc`` function, and
  usually ``archInit`` is called too.


  :param init:
    If True, the architecture allocation is followed by the init.
    If not, the :meth:`~Arch.init` method needs to be called before
    :meth:`~Arch.build/build0`, :meth:`~Arch.build2` or :meth:`~Arch.load`.

  |

  .. method:: init()

    This routine is included in a class call with ``init=True``.
    Mandatory before calling either :meth:`~Arch.build` or
    :meth:`~Arch.load`, or after calling :meth:`~Arch.exit`.

  |

  .. method:: exit()

    This routine cleans-up all fields of the instance. Is the opposite of the :meth:`~Arch.init` routine.
    Called automatically when the object is destroyed.
    Calling explicitly this method is only required when an :meth:`~Arch.init` call follows.

  |

  .. method:: load(stream)

    This routine builds the architecture from the data included in the given file or stream.

    :param stream: Input file or stream to read from.
    :type stream: Either a file object (result of an ``open()``, don't forget to close
          it) or a filename, as a string or as a bytes object (such as
          ``b"file/name"``).

  |

  .. method:: save(stream)

    This routine saves the architecture to the given file or stream in the form of a text string.

    :param stream: Input file or stream to read from.
    :type stream: Either a file object (result of an ``open()``, don't forget to close
          it) or a filename, as a string or as a bytes object (such as
          ``b"file/name"``).

  |

  .. method:: name()

    This routine gives the name of the architecture.

    :returns: The name of the architecture.
    :rtype: String

  |

  .. method:: size()

    This routine gives the size of the architecture.

    :returns: The size of the architecture.
    :rtype: Integer

  |

  .. method:: build/build0 (graf, listtab, strat)

    These two routines (as of now) fill the contents of the given opaque target structure
    with the data provided by the user. The source graph provided on input is
    turned into the ``deco 1``  decomposition-defined target architecture.

    :param graf: The source graph.
    :type graf: :class:`Graph`
    :param listtab: Restricts the vertices to be considered for the architecture.
    :type listtab: Numpy array or list of integers
    :param strat: Bi-partitioning strategy to be used.
    :type strat: a :class:`Strat` instance

  |

  .. method:: build2(graf, listtab)

    This routines fill the contents of the given opaque target structure
    with the data provided by the user. The source graph provided on input is
    turned into the ``deco 1`` decomposition-defined target architecture.

    :param graf: The source graph.
    :type graf: :class:`Graph`
    :param listtab: Restricts the vertices to be considered for the architecture.
    :type listtab: Numpy array or list of integers

  |

  .. method:: cmplt(vertnbr)

    This routine fills the contents of the given opaque target structure with
    the description of a complete graph architecture with ``vertnbr`` processors.

    :param vertnbr: Number of processors that can be used as input.
    :type vertnbr: Integer

  |

  .. method:: cmpltw(velotab)

    This routine fills the contents of the given opaque target structure with the
    description of a weighted graph architecture with length of ``velotab`` processors.

    :param velotab: Array of processor weights.
    :type velotab: Numpy array or list of integers

  |

  .. method:: hcub(hdimval)

    This routine fills the contents of the given opaque target structure with the
    description of a hypercube graph architecture of dimension ``hdimval``.

    :param hdimval: Dimension of the hypercube.
    :type hdimval: Integer

  |

  .. method:: ltLeaf(sizetab, linktab, permtab)

    This routine fills the contents of the given opaque target structure with the
    description of a labeled tree-shaped, hierarchical graph architecture.

    :param sizetab: Array of numbers of childs at level (i+1) for each node at level i.
    :type sizetab: Numpy array or list of integers
    :param linktab: Array of costs of communication between processors the first of which belongs to this level i.
    :type linktab: A1ny iterable of integers
    :param permtab: Numpy array or list of integers
    :type permtab: Numpy array or list of integers

  |

  .. method:: mesh(*args)

    This routine is generalized version of :meth:`~Arch.mesh2`, :meth:`~Arch.mesh3` and :meth:`~Arch.meshX`  - it's almost :meth:`~Arch.meshX`, but the integers don't
    have to be wrapped in an iterable and must be given ore after the other.

    :param args: Number of processors in each dimension.
    :type args: Numpy array or list of integers

    |

  .. method:: mesh2(xdimval, ydimval)

    This routine fills the contents of the given opaque target structure with the description of a 2D mesh architecture
    with ``xdimval`` X ``ydimval`` processors.

    :param xdimval: Number of processors in the X dimension.
    :type xdimval: Integer
    :param ydimval: Number of processors in the Y dimension.
    :type ydimval: Integer

    |

  .. method:: mesh3(xdimval, ydimval, zdimval)

    This routine fills the contents of the given opaque target structure with the description of a 3D mesh architecture
    with ``xdimval`` X ``ydimval`` X ``zdimval`` processors.

    :param xdimval: Number of processors in the X dimension.
    :type xdimval: Integer
    :param ydimval: Number of processors in the Y dimension.
    :type ydimval: Integer
    :param zdimval: Number of processors in the Z dimension.
    :type zdimval: Integer

  |

  .. method:: meshX(dimntab)

    This routine fills the contents of the given opaque target structure with the description of a mesh architecture
    with length of ``dimntab``- dimension and the product of all elements of ``dimntab`` processors.

    :param dimntab: Array of numbers of processors in each dimension.
    :type dimntab: Numpy array or list of integers

  |

  .. method:: sub(orgarch, vnumtab)

    This routine fills the contents of the given opaque target structure with the description of a subset of
    the ``orgarch`` architecture, restricted to the ``vertnbr`` processors which are listed in ``vnumtab``.

    :param orgarch: Original architecture.
    :type orgarch: :class:`Arch`
    :param vnumtab: Array with processor ranks to be included in the sub-architecture.
    :type vnumtab: Numpy array or list of integers

  |

  .. method:: tLeaf(sizetab, linktab)

    This routine fills the contents of the given opaque target structure with the description of a tree-shaped,
    hierarchical graph architecture with the sum of all of ``sizetab`` processors.


    :param sizetab: Array of numbers of childs at level (i+1) for each node at level i.
    :type sizetab: Numpy array or list of integers
    :param linktab: Array of costs of communication between processors the first of which belongs to this level i.
    :type linktab: Numpy array or list of integers

  |

  .. method:: torus(*args)

    This routine is generalized version of :meth:`~Arch.torus2`, :meth:`~Arch.torus3` and :meth:`~Arch.torusX`  - it's almost :meth:`~Arch.torusX`, but the integers don't
    have to be wrapped in an iterable and must be given ore after the other.

    :param args: Number of processors in each dimension.
    :type args: Numpy array or list of integers

  |

  .. method:: torus2(xdimval, ydimval)

    This routine fills the contents of the given opaque target structure with the description of a 2D torus architecture
    with ``xdimval`` X ``ydimval`` processors.

    :param xdimval: Number of processors in the X dimension.
    :type xdimval: Integer
    :param ydimval: Number of processors in the Y dimension.
    :type ydimval: Integer

  |

  .. method:: torus3(xdimval, ydimval, zdimval)

    This routine fills the contents of the given opaque target structure with the description of a 3D torus architecture
    with ``xdimval`` X ``ydimval`` X ``zdimval`` processors.

    :param xdimval: Number of processors in the X dimension.
    :type xdimval: Integer
    :param ydimval: Number of processors in the Y dimension.
    :type ydimval: Integer
    :param zdimval: Number of processors in the Z dimension.
    :type zdimval: Integer

  |

  .. method:: torusX(dimntab)

    This routine fills the contents of the given opaque target structure with the description of a torus architecture
    with length of ``dimntab``- dimension and the product of all elements of ``dimntab`` processors.

    :param dimntab: Array of numbers of processors in each dimension.
    :type dimntab: Numpy array or list of integers

  |

  .. method:: vhcub():

    This routine fills the contents of the given opaque target structure with the description of a 'variable-sized' hypercube architecture.

  |

  .. method:: vcmplt():

      This routine fills the contents of the given opaque target structure with the description of a 'variable-sized' complete graph architecture.

  |

**Various functions are defined as wrappers of Arch operations:**

  |

.. function:: arch_alloc()

    Recreates the ``archAlloc`` function, returning a non-initialized
    :class:`Arch` instance. It will need the :meth:`~Arch.init` method to be
    called before the instance be built or loaded upon.
