# Mapping and Ordering

## The Mapping class

class Mapping(*args)

  The Mapping constructor calls libscotch’s `mapAlloc` function. Any argument is conveyed to the `init()` method. If there are no arguments, the `init()` method is not called.

  `first` being the argument given to the `init()` method, the following `func` methods all proxy to `first.map_func(self, *args)`, except for `re_compute()` and `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 `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 :

  init(first, mapp, arch, parttab)

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

  Parameters:

    - first (`Graph`) – The first argument is the object to be mapped.

    - mapp (`Mapping`) – The mapping to be initialized.

    - arch (`Arch`) – The architecture to be used for mapping.

    - parttab (A numpy array) – The partition table.

  graph.map_exit(mapp)

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

  Parameters:

    mapp (A `Mapping`) – The mapping to be freed.

  graph.map_compute(mapp, strat)

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

  Parameters:

    - mapping (`Mapping`) – The mapping to be computed.

    - strat (`Strat`) – Strategy to be used for the mapping .

  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.

  Parameters:

    - mapping (`Mapping`) – The mapping to be computed.

    - strat (`Strat`) – Strategy to be used for the mapping.

  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`.

  Parameters:

    - mapping (`Mapping`) – The mapping to be computed.

    - mapo (Any kind of iterable or a numpy array) – The already computed mapping array used to account for migration costs.

    - emraval (Floating-point number) – Individual migration cost.

    - vmlotab (Any kind of iterable or a numpy array) – Vertex migration cost array.

    - strat (`Strat`) – Strategy to be used for the mapping.

  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`.

  Parameters:

    - mapping (`Mapping`) – The mapping to be computed.

    - mapo (Any kind of iterable or a numpy array) – The already computed mapping array used to account for migration costs.

    - emraval (Floating-point number) – Individual migration cost.

    - vmlotab (Any kind of iterable or a numpy array) – Vertex migration cost array.

    - strat (`Strat`) – Strategy to be used for the mapping.

  graph.map_save(stream)

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

  Parameters:

    - mapping (`Mapping`) – The mapping to be saved.

    - 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"`)) – Input file or stream to write to.

  graph.map_load(stream)

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

  Parameters:

    - mapping (`Mapping`) – The mapping to be loaded.

    - 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"`)) – Input file or stream to read from.

  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.

  Parameters:

    - mapping (`Mapping`) – The mapping to be viewed.

    - 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"`)) – Input file or stream to write to.

map_alloc()

  Recreates the `mapAlloc` function, returning a non-initialized `Mapping` instance. It will need the `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 `init()` method. If there are no arguments, the `init()` method is not called.

  `first` being the argument given to the `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 `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 :

  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 `Mapping` instance. `first.map_init(ordering, permtab=None, peritab=None, cblknbr=None, rangtab=None, treetab=None)` can also be called directly.

  Parameters:

    - first (`Graph`) – The first argument is the object to be ordered.

    - ordering (`Ordering`) – Ordering to be initialized.

    - permtab (Any kind of iterable or a numpy array) – Array holding the permutation of the reordered matrix. If given, the values of the returned array are copied in this one. (Optional)

    - peritab (Any kind of iterable or a numpy array) – Inverse permutation of the reordered matrix. If given, the values of the returned array are copied in this one. (Optional)

    - cblknbr (Integer) – Number of column blocks in the block ordering. If given, the value is copied in this one. (Optional)

    - rangtab (Any kind of iterable or a numpy array) – Array of ranges for the column blocks. If given, the values of the returned array are copied in this one. (Optional)

    - treetab (Any kind of iterable or a numpy array) – 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)

  graph.order_exit(ordering)

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

  Parameters:

    ordering (`Ordering`) – The ordering to be freed.

  graph.order_check(ordering)

    This routine checks the consistency of the ordering instance.

  Parameters:

    ordering (`Ordering`) – Ordering to be checked.

  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`.

  Parameters:

    - ordering (`Ordering`) – The ordering to be computed.

    - strat (`Strat`) – Strategy to be used for the ordering.

  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.

  Parameters:

    - ordering (`Ordering`) – Ordering to be computed.

    - listtab (Any kind of iterable or a numpy array) – The list of vertices to keep in the induced subgraph.

    - strat (`Strat`) – Strategy to be used for the ordering.

  graph.order_load(ordering, stream)

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

  Parameters:

    - ordering (`Ordering`) – Ordering to be loaded.

    - 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"`)) – Input file or stream to read from.

  graph.order_save(ordering, stream)

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

  Parameters:

    - ordering (`Ordering`) – Ordering to be saved.

    - 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"`)) – Input file or stream to write to.

  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.

  Parameters:

    - ordering (`Ordering`) – Ordering to be saved.

    - 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"`)) – Input file or stream to write to.

  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.

  Parameters:

    - ordering (`Ordering`) – Ordering to be saved.

    - 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"`)) – Input file or stream to write to.

order_alloc()

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