# Meshes in ScotchPy

Graphs are implemented in ScotchPy with the Mesh class.

## The Mesh class

class Mesh(init=True)

  The mesh constructor itself calls libscotch’s `meshAlloc` function, and usually `meshInit` is called too.

  Parameters:

    init – If True, the mesh allocation is followed by the init. If not, the `init()` method needs to be called before `build()` or `load()`.

  The mesh object stores the arguments given to the `build()` method as integers and numpy arrays. They are accessible even when the mesh has been constructed with `load()`. They default to None if the argument was not given.

  init()

    This routine Initializes the fields of the Mesh object instance. Called by a class constructor when `init=True` (by default). Mandatory before calling either `build()` or `load()`, or after calling `exit()` in order to re-use the same Mesh instance.

  exit()

    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.

  build(velmbas=None, vnodbas=None, velmnbr=None, vnodnbr=None, verttab=None, vendtab=None, velotab=None, vnlotab=None, vlbltab=None, edgenbr=None, edgetab=None)

    This routine builds the mesh itself using the given values. Arguments should be given as ints and ideally numpy arrays of ints, although any iterable would work. Mutating these arrays is not recommended as it may cause runtime errors while Scotch handles them.

    Some arguments may be omitted, but :

      - `velmbas` and `vnodbas` must be given .

      - if `vnlotab` has no size, `velmbas`, `velmnbr` and

          `edgenbr` must be given.

    Parameters:

      - velmbas (Integer) – Base value for mesh vertex indices.

      - vnodbas (Integer) – Base value for mesh node indices.

      - velmnbr (Integer) – Number of mesh vertices.

      - vnodnbr (Integer) – Number of mesh nodes.

      - verttab (Any iterable of integers ideally numpy array) – Adjacency index array (Required).

      - vendtab (Any iterable of integers ideally numpy array) – Adjacency end index array of size vertnbr if disjoint from verttab (Optional).

      - velotab (Any iterable of integers ideally numpy array) – Vertex load array of size vertnbr (Optional).

      - vlbltab (Any iterable of integers ideally numpy array) – Vertex label array of size vertnbr (Optional).

      - edgenbr (Integer) – Number of arcs (which is twice the number of edges).

      - edgetab (Any iterable of integers ideally numpy array) – Adjacency array of size edgenbr (more if not compact) (Required).

      - edlotab (Any iterable of integers ideally numpy array) – Arc load array of size edgenbr (Optional).

  load(stream, baseval=-1)

    This routine builds the mesh with `build()` from data included in the given file or stream.

    Parameters:

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

      - baseval (Integer) – The mesh base value for index arrays(0 or 1), takes the baseval value from the `stream` data if -1.

  The following routines can’t be called before the mesh is properly built either with :meth:`~Mesh.build` or with :meth:`~Mesh.load`:

  save(stream)

    This routine saves the mesh to the given file or stream in the Scotch mesh format.

    Parameters:

      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.

  check()

    Runs a self-test to check data consistency after the `build()` or `load()` method is called, raises a `LibraryError` if not.

  data(as_dict=None)

    This routine returns the values taken by the `build()` method. The arrays are returned as numpy arrays.

    Parameters:

      as_dict (Boolean) – If True, the requested data is returned as a dict. If not, it is returned as a 13-element tuple.

    Returns:

      Values in this order: (`velmbas`, `vnodbas`, `velmnbr`, `vnodnbr`, `verttab`, `vendtab`, `velotab`, `vnlotab`, `vlbltab`, `edgenbr`, `edgetab`, `edlotab`, `degrnbr`). (Not sure about the last one)

    Return type:

      Tuple or Dict

  size(as_dict=None)

    This routine returns the values of `velmnbr`, `vnodnbr` and `edgenbr` taken by the `build()` method.

    Parameters:

      as_dict (Boolean) – If True, the requested data is returned as a dict. If not, it is returned as a 3-element tuple.

    Returns:

      The values of `velmnbr`, `vnodnbr` and `edgenbr`.

    Return type:

      Tuple or Dict

  graph(graf)

    This routine builds a graph from the mesh itself.

    Parameters:

      graf (`Graph`) – Graph to be built.

  graph_dual(graf, ncomval)

    This routine builds the dual graph of the mesh itself.

    Parameters:

      - graf (`Graph`) – Graph to be built.

      - ncomval (Integer) – Number of components in the mesh.

  stat(as_dict=None)

    This routine gives various stats about the mesh:

    - `vnlomin`, `vnlomax`, `vnlosum`, `vnloavg`, `vnloadl` are the minimum node vertex load, the maximum node vertex load, the sum of all node vertex loads, the average node vertex load and the variance of the node vertex degrees, respectively.

    - `edegmin`, `edegmax`, `edegavg`, `edegdlt` are the minimum element vertex degree, the maximum element vertex degree, the average element vertex degree and the variance of the element vertex degrees, respectively.

    - `ndegmin`, `ndegmax`, `ndegavg`, `ndegdlt` are the minimum node vertex degree, the maximum node vertex degree, the average node vertex degree and the variance of the node vertex degrees, respectively.

    Parameters:

      as_dict (Boolean) – If True, the requested data is returned as a dict. If not, it is returned as a 13-element tuple.

    Returns:

      various stats about the mesh, in this specific order :(`vnlomin`, `vnlomax`, `vnlosum`, `vnloavg`, `vnloadl`, `edegmin`, `edegmax`, `edegavg`, `edegdlt`, `ndegmin`, `ndegmax`, `ndegavg`, `ndegdlt`).

    Return type:

      Tuple or Dict

  order(strat=Strat(init=True), permtab=None, peritab=None, cblknbr=None, rangtab=None, treetab=None)

    This routine computes a block ordering of the unknowns of the symmetric sparse matrix the adjacency structure, which is represented by the mesh itself.

  Parameters:

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

    - 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)

  order_init(ordering, permtab=None, peritab=None, cblknbr=None, rangtab=None, treetab=None)

    This routine initializes an ordering structure with respect to the mesh itself. If called using `Ordering`’s constructor however, nothing is returned.

  Parameters:

    - 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)

  order_exit(ordering)

    This routine frees an ordering instance.

  Parameters:

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

  order_check(ordering)

    This routine checks the consistency of the ordering instance.

  Parameters:

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

  order_compute(ordering, strat)

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

  Parameters:

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

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

  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.

  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.

  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.

mesh_alloc()

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

build_mesh(*args, **kwargs)

  Returns a properly built mesh instance. Positional and keyword arguments need to be given in the same fashion as `Mesh.build()` takes them.

load_mesh(*args, **kwargs)

  Returns a mesh instance loaded from the given file or stream. Positional arguments need to be given in the same fashion as `Mesh.load()` takes them.