# ScotchPy miscellaneous

## ScotchPy’s common functions

version(as_dict=None)

  This routine returns three integers as the version number(s), either as a tuple or as a dictionary.

num_sizeof()

  This routine returns the number of bytes taken by Scotch’s internal integers.

mem_cur()

  This routine returns the current memory usage of Scotch.

mem_max()

  This routine returns the maximum memory usage of Scotch.

random_proc()

  This routine sets to procnum the number of the process that will be used to generate random numbers.

random_reset()

  This routine resets the seed of the global pseudo-random number generator used by default by the SCOTCH library.

random_seed()

  This routine sets the seed of the global pseudo-random number generator used by default by the SCOTCH library.

random_val()

  This routine returns a pseudo-random integer value between 0 and randmax-1.

## Exceptions

ScotchPy defines several exceptions.

exception LibraryError

  Typically raised when a libscotch function would return a non-zero value to signal a failure to compute.

exception CannotCoarsen

  Raised by `Graph.coarsen()` and `Graph.coarsen_match()` when no error is encountered but no further coarsening could enforce the threshold parameters. Somewhat similar to, but not a subclass of, the `StopInteration` built-in exception. Meant to be caught in a try-except structure.

## Input data format

A lot of methods in Scotchpy are specified to take any form of iterables containing integers. However, in libscotch, a lot of side-effects happen to these iterables. Whenever such side-effect is supposed to happen, it is guaranteed only with numpy arrays having the proper dtype, which is accessible as `scotchpy.common.proper_int`. Other mutable iterables such as lists or custom types may be mutated in most cases but are not guaranteed to. Furthermore, when a class is built using such iterable, no side-effect whatsoever will happen to said iterables unless they are numpy arrays of the proper dtype.

## General names rule of thumb

As Numpy is generally imported as np, Scotchpy is intended to be imported as SCOTCH. No constraint is made about that of course, but an underlying reason for it is that the name of the Scotchpy version of a C Scotch (libscotch) function can usually be found by stripping the “SCOTCH_” prefix, converting it from CamelCase to snake_case, and try and replacing some underscores with dots.

Taking SCOTCH_graphDiamPV for example, it becomes `Graph.diam_pv`. Adding the module name imported as SCOTCH, we end up with `SCOTCH.Graph.diam_pv`.

When you master that matching, most of this documentation will become superfluous.

Note that this name-resolving recipe is valid when taking the method names as attached to their respective classes. When called as instance methods, the infamous `self` implicit parameter will match the first argument of the related C function.