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.