=====================================
ScotchPy miscellaneous
=====================================

ScotchPy's common functions
###########################

.. function:: version(as_dict=None)

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

.. function:: num_sizeof()

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

.. function:: mem_cur()

    This routine returns the current memory usage of Scotch.

.. function:: mem_max()

    This routine returns the maximum memory usage of Scotch.

.. function:: random_proc()

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

.. function:: random_reset()

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

.. function:: random_seed()

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

.. function:: 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 :meth:`Graph.coarsen` and :meth:`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.

.. Options
.. #######
..
.. The ``options`` submodule defines several variables tuning ScotchPy's beavior.
..
.. .. data:: return_as_dict
..
..     Defines the default value of the ``as_dict`` argument of functions or
..     methods such as :func:`version` or :meth:`Graph.data`. It defaults to True.
