========================
Mapping and Ordering
========================

The Mapping class
#################



.. class:: Mapping(*args)

    The Mapping constructor calls libscotch's ``mapAlloc`` function. Any
    argument is conveyed to the :meth:`~Mapping.init` method. If there are no
    arguments, the :meth:`~Mapping.init` method is not called.

    ``first`` being the argument given to the :meth:`~Mapping.init` method, the
    following ``func`` methods all proxy to ``first.map_func(self, *args)``,
    except for :meth:`~Mapping.re_compute` and :meth:`~Mapping.re_fixed_compute`
    which proxy the ``remap_compute`` and ``remap_fixed_compute`` methods,
    respectively.
    For now ``first`` is always a :class: `Graph` instance, can be used to factorize :class:`Mesh` routines later on.
    We will define the methods in the way in which they are called, using a graph :class: `Graph` instance as the calling object :

    |

    .. method:: init(first,mapp, arch, parttab)

        Calls ``first.map_init(first, mapp, arch, parttab)``, ``self`` being the
        :class:`Mapping` instance. ``first.map_init(first, mapp, arch, parttab)`` can also be called directly.


    :param first: The first argument is the object to be mapped.
    :type first: :class:`Graph`
    :param mapp: The mapping to be initialized.
    :type mapp: :class:`Mapping`
    :param arch: The architecture to be used for mapping.
    :type arch: :class:`Arch`
    :param parttab: The partition table.
    :type parttab: A numpy array

    |

    .. method:: graph.map_exit(mapp)

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

    :param mapp: The mapping to be freed.
    :type mapp: A :class:`Mapping`

    |

    .. method:: graph.map_compute(mapp, strat)

        This routine computes a mapping of the API mapping structure ``mapping`` with
        respect to the given strategy ``strat`` .

    :param mapping: The mapping to be computed.
    :type mapping: :class:`Mapping`
    :param strat: Strategy to be used for the mapping .
    :type strat: :class:`Strat`


    |

    .. method:: graph.map_fixed_compute(mapp, start)


        This routine computes a mapping with fixed vertices of the API mapping
        structure with respect to the given strategy.

    :param mapping: The mapping to be computed.
    :type mapping: :class:`Mapping`
    :param strat: Strategy to be used for the mapping.
    :type strat: :class:`Strat`


    |

    .. method:: graph.remap_compute(mapp, mapo, emrval, vmlotab, start)

        This routine computes a remapping of the API mapping structure ``mapping`` with
        respect to the given strategy ``strat``.

    :param mapping: The mapping to be computed.
    :type mapping: :class:`Mapping`
    :param mapo: The already computed mapping array used to account for migration costs.
    :type mapo: Any kind of iterable or a numpy array
    :param emraval: Individual migration cost.
    :type emraval: Floating-point number
    :param vmlotab: Vertex migration cost array.
    :type vmlotab: Any kind of iterable or a numpy array
    :param strat: Strategy to be used for the mapping.
    :type strat: :class:`Strat`


    |

    .. method:: graph.remap_fixed_compute(mapp, mapo, emrval, vmlotab, start)

        This routine computes a remapping with fixed vertices of the API mapping
        structure ``mapping`` with respect to the given strategy ``strat``.

    :param mapping: The mapping to be computed.
    :type mapping: :class:`Mapping`
    :param mapo: The already computed mapping array used to account for migration costs.
    :type mapo: Any kind of iterable or a numpy array
    :param emraval: Individual migration cost.
    :type emraval: Floating-point number
    :param vmlotab: Vertex migration cost array.
    :type vmlotab: Any kind of iterable or a numpy array
    :param strat: Strategy to be used for the mapping.
    :type strat: :class:`Strat`

    |

    .. method:: graph.map_save(stream)

        This routine saves the contents of the given user mapping ``mapping`` to the given
        stream ``stream``.

    :param mapping: The mapping to be saved.
    :type mapping: :class:`Mapping`
    :param stream: Input file or stream to write to.
    :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:: graph.map_load(stream)

        This routine loads the contents of the given user mapping ``mapping`` from the given
        stream  ``stream``.

    :param mapping: The mapping to be loaded.
    :type mapping: :class:`Mapping`
    :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:: graph.map_view(*args)

        This routine writes mapping statistics (load of target processors, number of neigh-
        boring domains, average dilation and expansion, edge cut size, distribution of
        edge dilations) to the given stream.

    :param mapping: The mapping to be viewed.
    :type mapping: :class:`Mapping`
    :param stream: Input file or stream to write to.
    :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"``)


    |

.. function:: map_alloc()

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



The Ordering class
##################

.. class:: Ordering(*args)

    The Ordering constructor calls libscotch's ``orderAlloc`` function. Any
    argument is conveyed to the :meth:`~Ordering.init` method. If there are no
    arguments, the :meth:`~Ordering.init` method is not called.

    ``first`` being the argument given to the :meth:`~Ordering.init` method, the
    following ``func`` methods all proxy to ``first.map_func(self, *args)``.
    For now ``first`` is always a :class: `Graph` instance, can be used to factorize :class:`Mesh` routines later on.
    We will define the methods in the way in which they are called, using a graph :class: `Graph` instance as the calling object :


    .. method:: init(first, ordering, permtab=None, peritab=None, cblknbr=None, rangtab=None, treetab=None)


        Calls ``first.map_init(ordering, permtab=None, peritab=None, cblknbr=None, rangtab=None, treetab=None)``, ``self`` being the
        :class:`Mapping` instance. ``first.map_init(ordering, permtab=None, peritab=None, cblknbr=None, rangtab=None, treetab=None)`` can also be called directly.

    :param first: The first argument is the object to be ordered.
    :type first: :class:`Graph`
    :param ordering: Ordering to be initialized.
    :type ordering: :class:`Ordering`
    :param permtab: Array holding the permutation of the reordered matrix. If given, the values of the returned array are copied in this one. (**Optional**)
    :type permtab: Any kind of iterable or a numpy array
    :param peritab: Inverse permutation of the reordered matrix. If given, the values of the returned array are copied in this one. (**Optional**)
    :type peritab: Any kind of iterable or a numpy array
    :param cblknbr: Number of column blocks in the block ordering. If given, the value is copied in this one. (**Optional**)
    :type cblknbr: Integer
    :param rangtab: Array of ranges for the column blocks. If given, the values of the returned array are copied in this one. (**Optional**)
    :type rangtab: Any kind of iterable or a numpy array
    :param treetab: Array of ascendants of permuted column blocks in the separators tree. If given, the values of the returned array are copied in this one. (**Optional**)
    :type treetab: Any kind of iterable or a numpy array

    |

    .. method:: graph.order_exit(ordering)

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

    :param ordering: The ordering to be freed.
    :type ordering: :class:`Ordering`

    |

    .. method:: graph.order_check(ordering)

        This routine checks the consistency of the ordering instance.

    :param ordering: Ordering to be checked.
    :type ordering: :class:`Ordering`

    |

    .. method:: graph.order_compute(ordering, strat)

        This routine computes a block ordering of the graph itself with
        respect to the given strategy ``strat``. Stores the result in the
        given ordering instance ``ordering``.

    :param ordering: The ordering to be computed.
    :type ordering: :class:`Ordering`
    :param strat: Strategy to be used for the ordering.
    :type strat: :class:`Strat`

    |

    .. method:: graph.order_compute_list(ordering, listtab, strat)

        This routine computes a block ordering of the graph itself with respect to the given strategy ``strat``. Stores the result in the given ordering instance ``ordering``.
        The induced subgraph is described by means of a vertex list: listnbr holds the number of vertices to keep in the induced subgraph, the indices of which are given, in any order, in the ``listtab`` array.

    :param ordering: Ordering to be computed.
    :type ordering: :class:`Ordering`
    :param listtab: The list of vertices to keep in the induced subgraph.
    :type listtab: Any kind of iterable or a numpy array
    :param strat: Strategy to be used for the ordering.
    :type strat: :class:`Strat`

    |

    .. method:: graph.order_load(ordering, stream)

        This routine loads the contents of the given ordering instance ``ordering`` from the given stream ``stream``.

    :param ordering: Ordering to be loaded.
    :type ordering: :class:`Ordering`
    :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:: graph.order_save(ordering, stream)

        This routine saves the contents of the given ordering instance ``ordering`` to the given stream ``stream``.

    :param ordering: Ordering to be saved.
    :type ordering: :class:`Ordering`
    :param stream: Input file or stream to write to.
    :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:: graph.order_save_map(ordering, stream)

        This routine saves the contents of the given ordering instance ``ordering`` to the given stream ``stream`` in the Scotch mapping format.

    :param ordering: Ordering to be saved.
    :type ordering: :class:`Ordering`
    :param stream: Input file or stream to write to.
    :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:: graph.order_save_tree(ordering, stream)

        This routine saves the contents of the given ordering instance ``ordering`` to the given stream ``stream`` in the tree output format format.

    :param ordering: Ordering to be saved.
    :type ordering: :class:`Ordering`
    :param stream: Input file or stream to write to.
    :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"``)

    |

.. function:: order_alloc()

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