====================================
Graphs in ScotchPy
====================================

Graphs are implemented in ScotchPy with the Graph class.

The Graph class
###############



.. class:: Graph(init=True)

    The graph constructor itself calls libscotch's ``graphAlloc`` function, and
    usually ``graphInit`` is called too.

    :param init:
        If True, the graph allocation is followed by the init.
        If not, the :meth:`~Graph.init` method needs to be called before
        :meth:`~Graph.build` or :meth:`~Graph.load`.

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

    |

    .. method:: init()

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

    |

    .. method:: exit()

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

    |

    .. method:: free()

        This routine resets the instance fields so that it can hold a new Graph topology.
        Is equivalent to calling :meth:`~Graph.exit` and :meth:`~Graph.init` successively.

    |

    .. method:: build(baseval=None, vertnbr=None, verttab=None, vendtab=None, velotab=None, vlbltab=None, edgenbr=None, edgetab=None, edlotab=None)

        This routine builds the graph 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 :
            - ``baseval`` must be given if the graph is not compact.
            - if ``verttab`` has no size, ``baseval``, ``vertnbr`` and
              ``edgenbr`` must be given.

        :param baseval: Graph base value for index arrays.
        :type baseval: Integer
        :param vertnbr: Number of vertices.
        :type vertnbr: Integer
        :param verttab: Adjacency index array (**Required**).
        :type verttab: Any iterable of integers ideally numpy array
        :param vendtab: Adjacency end index array of size vertnbr if disjoint from verttab (**Optional**).
        :type vendtab: Any iterable of integers ideally numpy array
        :param velotab: Vertex load array of size vertnbr (**Optional**).
        :type velotab: Any iterable of integers ideally numpy array
        :param vlbltab: Vertex label array of size vertnbr (**Optional**).
        :type vlbltab: Any iterable of integers ideally numpy array
        :param edgenbr: Number of arcs (*which is twice the number of edges*).
        :type edgenbr: Integer
        :param edgetab: Adjacency array of size edgenbr (*more if not compact*) (**Required**).
        :type edgetab: Any iterable of integers ideally numpy array
        :param edlotab: Arc load array of size edgenbr (**Optional**).
        :type edlotab: Any iterable of integers ideally numpy array

    |

    .. method:: build_from_csgraph(csg)

        This routine builds the graph ``csg`` using :meth:`~Graph.build`.

        :param csg: A scipy.csgraph matrix.
        :type csg: scipy.sparse.csr_matrix

    |

    .. method:: load(stream, baseval=-1, flagval=0)

        This routine builds the graph with :meth:`~Graph.build` from data included in the given file or stream.

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

        :param baseval: The graph base value for index arrays(0 or 1),
                        takes the baseval value from the ``stream`` data if -1.
        :type baseval: Integer
        :param flagval: The flagval value is a combination of the following integer values,
                        that may be added or bitwise-ored:

                        - ``0`` : Keep vertex and edge weights if they are present in the stream data.
                        - ``1`` : Remove vertex weights. The graph read will have all of its vertex weights set to one, regardless of what is specified in the stream data.
                        - ``2`` : Remove edge weights. The graph read will have all of its edge weights set to one, regardless of what is specified in the stream data.

        :type flagval: Integer

    |

    **The following routines can't be called before the graph is properly built either with
    Graph.build or with Graph.load:**

    |

    .. method:: base(baseval)

        This routine re-sets the baseval value and modifies the stored arrays to maintain data consistency.

        :param baseval: Graph base value for index arrays.
        :type baseval: Integer
        :returns: Former baseval value.
        :rtype: Integer

    |

    .. method:: save(stream)

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

        :param stream: input file or stream to read from.
        :type 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"``)

    |

    .. method:: check()

        Runs a self-test to check data consistency after the
        :meth:`~Graph.build` or :meth:`~Graph.load` method is called, raises a :class:`LibraryError` if not.

    |

    .. method:: data(as_dict=None)

        This routine returns the values taken by the :meth:`~Graph.build` method. The arrays
        are returned as numpy arrays.

        :param as_dict:
            If True, the requested data is returned as a dict.
            If not, it is returned as a 9-element tuple.
        :type as_dict: Boolean
        :returns: Values in this order: (``baseval``, ``vertnbr``,
            ``verttab``, ``vendtab``, ``velotab``, ``vlbltab``, ``edgenbr``,
            ``edgetab``, ``edlotab``) .
        :rtype: Tuple or Dict

    |

    .. method:: size(as_dict=None)

        This routine returns the values of ``edgenbr`` and ``vertnbr`` taken by the :meth:`~Graph.build` method.

        :param as_dict:
            If True, the requested data is returned as a dict.
            If not, it is returned as a 2-element tuple.
        :type as_dict: Boolean
        :returns: The values of ``edgenbr`` and ``vertnbr``.
        :rtype: Tuple or Dict

    |

    .. method:: diam_pv()

        This routine computes the the edge-weighted (pseudo) diameter of the graph and returns it.

        :returns: The graph's diameter.
        :rtype: Integer

    |

    .. method:: stat(as_dict=None)

        This routine gives various stats about the graph:

        - ``velomin``, ``velomax``, ``velosum``, ``veloavg``, ``velodlt``, are the minimum vertex load, the maximum vertex load, the sum of all vertex loads, the average vertex load and the variance of the vertex degrees, respectively.

        - ``degrmin``, ``degrmax``, ``degravg``, ``degrdlt``, are the minimum vertex degree, the maximum vertex degree, the average vertex degree and the variance of the vertex degrees, respectively.

        - ``edlomin``, ``edlomax``, ``edlosum``, ``edloavg``, ``edlodlt`` are the minimum edge load, the maximum edge load, the sum of all edge loads, the average edge load and the variance of the edge loads, respectively.


        :param as_dict:
            If True, the requested data is returned as a dict.
            If not, it is returned as a 14-element tuple.
        :type as_dict: Boolean
        :returns: various stats about the graph, in this specific order :(``velomin``, ``velomax``, ``velosum``, ``veloavg``,
            ``velodlt``, ``degrmin``, ``degrmax``, ``degravg``, ``degrdlt``,
            ``edlomin``, ``edlomax``, ``edlosum``, ``edloavg``, ``edlodlt``).
        :rtype: Tuple or Dict

    |

    .. method:: color(colotab=None, flagval=0)

        This routine creates a color array for the given graph.
        To get the ``colonum`` value, the built-in ``max``
        function can be called on colortab.

        :param colotab:
            If given as a list or numpy array of
            integers, it is updated with the returned values.
        :type colotab: Any iterable of integers ideally numpy array
        :param flagval:
            Defaults to 0, not used for now.
        :type flagval: Integer


    |

    .. method:: tab_save(stream, parttab=None)

        This routine saves the partition array ``parttab`` to the given file or stream in the Scotch mapping format.

        :param stream: Input file or stream to write to.
        :type 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"``)
        :param parttab: The partition array. If given as a list or numpy array of
            integers, it is updated with the returned values.
        :type parttab: Any kind of iterable or a numpy array

    |

    .. method:: tab_load(stream, parttab=None)

        This routine loads the partition array ``parttab`` from the given file or stream.

        :param stream: Input file or stream to read from.
        :type 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"``)
        :param parttab: The partition array. If given as a list or numpy array of
            integers, it is updated with the returned values.
        :type parttab: Any kind of iterable or a numpy array

    |

    .. method:: part(partnbr, strat=Strat(init=True), parttab=None)

        This routine computes an edge-separated partition ,into ``partnbr`` parts, of the graph itself,
        with respect to the given strategy.

    :param partnbr: The number of parts.
    :type partnbr: Integer
    :param strat: A :class:`Strat` instance to be used for the partitioning.
    :type strat: Strat
    :param parttab: The partition array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type parttab: Any kind of iterable or a numpy array

    |

    .. method:: part_fixed(partnbr, strat=Strat(init=True), parttab=None)

        This routine computes a edge-separated partition, into ``partnbr`` parts, of the graph itself,
        with respect to the given strategy and the fixed vertices in ``maptab``.

    :param partnbr: The number of parts.
    :type partnbr: Integer
    :param strat: Strategy to be used for the partitioning.
    :type strat: :class:`Strat`
    :param parttab: The partition array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type parttab: Any kind of iterable or a numpy array

    |

    .. method:: part_ovl(partnbr, strat=Strat(init=True), parttab=None)

        This routine computes an overlapped vertex-separated partition, into ``partnbr`` parts, of the graph itself, with
        respect to the given strategy and the fixed vertices in ``maptab``.

    :param partnbr: The number of parts.
    :type partnbr: Integer
    :param strat: Strategy to be used for the partitioning.
    :type strat: :class:`Strat`
    :param parttab: The partition array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type parttab: Any kind of iterable or a numpy array


    |

    .. method:: induce_list(vnumnbr, vnumtab, indgraf)

        This routine computes the induced graph of the graph itself, with respect to the given vertex list.

    :param vnumnbr: The number of vertices in the list.
    :type vnumnbr: Integer
    :param vnumtab: The vertex list.
    :type vnumtab: Any kind of iterable or a numpy array
    :param indgraf: The induced subgraph.
    :type indgraf: :class:`Graph`

    |

    .. method:: induce_part(vnumnbr, vnumtab, partval, indgraf)

        This routine computes the induced graph of the graph itself, with respect to the given vertex list and the given partition.

    :param vnumnbr: The number of vertices in the list.
    :type vnumnbr: Integer
    :param vnumtab: The vertex list.
    :type vnumtab: Any kind of iterable or a numpy array
    :param partval: The partition array.
    :type partval: Any kind of iterable or a numpy array
    :param indgraf: The induced subgraph.
    :type indgraf: :class:`Graph`

    |

    .. method:: repart(partnbr, parotab, emraval, vmlotab, strat=Strat(init=True), parttab=None)

        This routine computes an edge-separated repartition , into ``partnbr`` parts, of the graph itself,
        based on the old partition array ``parotab`` , with respect to the given strategy ``strat`` .

    :param partnbr: The number of parts.
    :type partnbr: Integer
    :param parotab: The old partition array.
    :type parotab: Any kind of iterable or a numpy array
    :param emraval: Individual migration cost.
    :type emraval: Floating-point number
    :param vmlotab: Vertex migration cost array.
    :type vmlotab: Any kind of iterable or a numpy array
    :param strat: Strategy to be used for the partitioning.
    :type strat: :class:`Strat`
    :param parttab: The partition array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type parttab: Any kind of iterable or a numpy array

    |

    .. method:: repart_fixed(partnbr, parotab, emraval, vmlotab, strat=Strat(init=True), parttab=None)

        This routine computes an edge-separated repartition , into ``partnbr`` parts, of the graph itself,
        based on the old partition array ``parotab`` , with respect to the given strategy ``strat`` and the fixed vertices in ``maptab``.

    :param partnbr: The number of parts.
    :type partnbr: Integer
    :param parotab: The old partition array.
    :type parotab: Any kind of iterable or a numpy array
    :param emraval: Individual migration cost.
    :type emraval: Floating-point number
    :param vmlotab: Vertex migration cost array.
    :type vmlotab: Any kind of iterable or a numpy array
    :param strat: Strategy to be used for the partitioning.
    :type strat: :class:`Strat`
    :param parttab: The partition array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type parttab: Any kind of iterable or a numpy array

    |

    .. method:: map(arch, strat=Strat(init=True), parttab=None)

        This routine computes a mapping of the given graph itself onto the given target architecture ``arch`` , with respect to the given strategy ``strat``.

    :param arch: The target architecture.
    :type arch: :class:`Arch`
    :param strat: Strategy to be used for the mapping.
    :type strat: :class:`Strat`
    :param parttab: The partition array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type parttab: Any kind of iterable or a numpy array

    |

    .. method:: map_fixed(arch, strat=Strat(init=True), parttab=None)

        This routine computes a mapping of the given graph itself onto the given target architecture ``arch`` , with respect to the given strategy ``strat`` and fixed vertices in maptab.

    :param arch: The target architecture.
    :type arch: :class:`Arch`
    :param strat: Strategy to be used for the mapping.
    :type strat: :class:`Strat`
    :param parttab: The partition array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type parttab: Any kind of iterable or a numpy array

    |

    .. method:: remap(arch, parotab, emraval, vmlotab, strat=Strat(init=True), parttab=None)

        This routine computes a remapping of the graph itself onto the given target architecture ``arch`` , based on the old partition array ``parotab``, with respect to the given strategy ``strat``.

    :param arch: The target architecture.
    :type arch: :class:`Arch`
    :param parotab: The old mapping array.
    :type parotab: Any kind of iterable or a numpy array
    :param emraval: Individual migration cost.
    :type emraval: Floating-point number
    :param vmlotab: Vertex migration cost array.
    :type vmlotab: Any kind of iterable or a numpy array
    :param strat: Strategy to be used for the mapping.
    :type strat: :class:`Strat`
    :param parttab: The partition array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type parttab: Any kind of iterable or a numpy array


    |

    .. method:: remap_fixed(arch, parotab, emraval, vmlotab, strat=Strat(init=True), parttab=None)

        This routine computes a remapping of the graph itself onto the given target architecture ``arch`` , based on the old partition array ``parotab``, with respect to the given strategy ``strat`` and the fixed vertices in maptab.

    :param arch: The target architecture.
    :type arch: :class:`Arch`
    :param parotab: The old mapping array.
    :type parotab: Any kind of iterable or a numpy array
    :param emraval: Individual migration cost.
    :type emraval: Floating-point number
    :param vmlotab: Vertex migration cost array.
    :type vmlotab: Any kind of iterable or a numpy array
    :param strat: Strategy to be used for the mapping.
    :type strat: :class:`Strat`
    :param parttab: The partition array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type parttab: Any kind of iterable or a numpy array

    |

    .. method:: map_init(mapping, arch, parttab=None)

        This routine initializes an API opaque mapping with respect to the graph itself and the locations of output parameters.

    :param mapping: The mapping to be initialized.
    :type mapping: :class:`Mapping`
    :param arch: The target architecture.
    :type arch: :class:`Arch`
    :param parttab: The partition array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type parttab: Any kind of iterable or a numpy array

    |

    .. method:: map_exit(mapping)

        This routine frees an API mapping instance.

    :param mapping: The mapping to be freed.
    :type mapping: :class:`Mapping`

    |

    .. method:: map_compute(mapping, strat)

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

    :param mapping: The mapping to be computed.
    :type mapping: :class:`Mapping`
    :param strat: Strategy to be used for the mapping .
    :type strat: :class:`Strat`

    |

    .. method:: map_fixed_compute(mapping, strat)

        This routine computes a mapping with fixed vertices of the API mapping
        structure with respect to the given strategy.

    :param mapping: The mapping to be computed.
    :type mapping: :class:`Mapping`
    :param strat: Strategy to be used for the mapping.
    :type strat: :class:`Strat`

    |

    .. method:: remap_compute(mapping, mapo, emraval, vmlotab, strat)

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

    :param mapping: The mapping to be computed.
    :type mapping: :class:`Mapping`
    :param mapo: The already computed mapping array used to account for migration costs.
    :type mapo: Any kind of iterable or a numpy array
    :param emraval: Individual migration cost.
    :type emraval: Floating-point number
    :param vmlotab: Vertex migration cost array.
    :type vmlotab: Any kind of iterable or a numpy array
    :param strat: Strategy to be used for the mapping.
    :type strat: :class:`Strat`

    |

    .. method:: remap_fixed_compute(mapping, mapo, emraval, vmlotab, strat)

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

    :param mapping: The mapping to be computed.
    :type mapping: :class:`Mapping`
    :param mapo: The already computed mapping array used to account for migration costs.
    :type mapo: Any kind of iterable or a numpy array
    :param emraval: Individual migration cost.
    :type emraval: Floating-point number
    :param vmlotab: Vertex migration cost array.
    :type vmlotab: Any kind of iterable or a numpy array
    :param strat: Strategy to be used for the mapping.
    :type strat: :class:`Strat`

    |

    .. method:: map_load(mapping, stream)

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

    :param mapping: The mapping to be loaded.
    :type mapping: :class:`Mapping`
    :param stream: Input file or stream to read from.
    :type 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"``)

    |

    .. method:: map_save(mapping, stream)

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

    :param mapping: The mapping to be saved.
    :type mapping: :class:`Mapping`
    :param stream: Input file or stream to write to.
    :type 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"``)

    |

    .. method:: map_view(mapping, stream)

        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.

    :param mapping: The mapping to be viewed.
    :type mapping: :class:`Mapping`
    :param stream: Input file or stream to write to.
    :type 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"``)

    |

    .. method:: 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 graph itself.


    :param strat: Strategy to be used for the ordering.
    :type strat: :class:`Strat`
    :param permtab: Array holding the permutation of the reordered matrix. If given, the values of the returned array are copied in this one.
    :type permtab: Any kind of iterable or a numpy array
    :param peritab: Inverse permutation of the reordered matrix. If given, the values of the returned array are copied in this one.
    :type peritab: Any kind of iterable or a numpy array
    :param cblknbr: Number of column blocks in the block ordering. If given, the value is copied in this one.
    :type cblknbr: integer
    :param rangtab: Array of ranges for the column blocks. If given, the values of the returned array are copied in this one.
    :type rangtab: Any kind of iterable or a numpy array
    :param treetab: Array of ascendants of permuted column blocks in the separators tree. If given, the values of the returned array are copied in this one.
    :type treetab: Any kind of iterable or a numpy array

    |

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

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

    :param ordering: Ordering to be initialized.
    :type ordering: :class:`Ordering`
    :param permtab: Array holding the permutation of the reordered matrix. If given, the values of the returned array are copied in this one.
    :type permtab: Any kind of iterable or a numpy array
    :param peritab: Inverse permutation of the reordered matrix. If given, the values of the returned array are copied in this one.
    :type peritab: Any kind of iterable or a numpy array
    :param cblknbr: Number of column blocks in the block ordering. If given, the value is copied in this one.
    :type cblknbr: Integer
    :param rangtab: Array of ranges for the column blocks. If given, the values of the returned array are copied in this one.
    :type rangtab: Any kind of iterable or a numpy array
    :param treetab: Array of ascendants of permuted column blocks in the separators tree. If given, the values of the returned array are copied in this one.
    :type treetab: Any kind of iterable or a numpy array

    |

    .. method:: order_exit(ordering)

        This routine frees an ordering instance.

    :param ordering: Ordering to be freed.
    :type ordering: :class:`Ordering`

    |

    .. method:: order_check(ordering)

        This routine checks the consistency of the ordering instance.

    :param ordering: Ordering to be checked.
    :type ordering: :class:`Ordering`

    |

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

    :param ordering: Ordering to be computed.
    :type ordering: :class:`Ordering`
    :param strat: Strategy to be used for the ordering.
    :type strat: :class:`Strat`

    |

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

    :param ordering: Ordering to be computed.
    :type ordering: :class:`Ordering`
    :param listtab: The list of vertices to keep in the induced subgraph.
    :type listtab: Any kind of iterable or a numpy array
    :param strat: Strategy to be used for the ordering.
    :type strat: :class:`Strat`

    |

    .. method:: order_load(ordering, stream)

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

    :param ordering: Ordering to be loaded.
    :type ordering: :class:`Ordering`
    :param stream: Input file or stream to read from.
    :type 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"``)


    |

    .. method:: order_save(ordering, stream)

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

    :param ordering: Ordering to be saved.
    :type ordering: :class:`Ordering`
    :param stream: Input file or stream to write to.
    :type 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"``)

    |

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

    :param ordering: Ordering to be saved.
    :type ordering: :class:`Ordering`
    :param stream: Input file or stream to write to.
    :type 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"``)

    |

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

    :param ordering: Ordering to be saved.
    :type ordering: :class:`Ordering`
    :param stream: Input file or stream to write to.
    :type 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"``)

    |

    .. method:: coarsen(coarvertnbr, coarrat, flagval, coargraf, coarmulttab=None)

        This routine coarsens the graph itself with respect to the given parameters.
        The coarsened graph is created only if it comprises more than ``coarvertnbr`` vertices, or if the coarsening ratio is lower than ``coarrat``.
        Valid coarsening ratio values range from 0.5 (in the case of a perfect matching) to 1.0 (if no vertex could be coarsened). Classical threshold values range from 0.7 to 0.8.
        Raises :class:`CannotCoarsen` if not because of threshold parameters,
        raises :class:`LibraryError` otherwise.

    :param coarvertnbr: Number of vertices in the coarsened graph.
    :type coarvertnbr: Integer
    :param coarrat: Coarsening ratio.
    :type coarrat: Floating-point number
    :param flagval: The flagval flag specifies the type of coarsening
    :type flagval: Integer
    :param coargraf: Another :class:`Graph` instance, which gets modified.
    :type coargraf: :class:`Graph`
    :param coarmulttab: The vertex-to-vertex multiplicity array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type coarmulttab: Any kind of iterable or a numpy array


    |

    .. method:: coarsen_match(coarvertnbr, coarrat, flagval, finematetab=None)

        The routine fills the ``finematetab`` array with a matching of the vertices of the graph itself.
        The matching is computed so as to minimize the sum of the weights of the matched edges.
        The matching is computed only if it comprises more than ``coarvertnbr`` vertices, or if the coarsening ratio is lower than ``coarrat``.
        Valid coarsening ratio values range from 0.5 (in the case of a perfect matching) to 1.0 (if no vertex could be coarsened). Classical threshold values range from 0.7 to 0.8.
        Raises :class:`CannotCoarsen` if not because of threshold parameters,
        raises :class:`LibraryError` otherwise.

    :param coarvertnbr: Number of vertices in the coarsened graph.
    :type coarvertnbr: Integer
    :param coarrat: Coarsening ratio.
    :type coarrat: Floating-point number
    :param flagval: The flagval flag specifies the type of coarsening
    :type flagval: Integer
    :param finematetab: The matching array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type finematetab: Any kind of iterable or a numpy array
    :returns: The number of matched vertices.
    :rtype: Integer

    |

    .. method:: coarsen_build(coarvertnbr, finematetab, coargraf, coarmulttab=None)

        This routine builds the coarsened graph itself with respect to the given parameters.


    :param coarvertnbr: Number of vertices in the coarsened graph.
    :type coarvertnbr: Integer
    :param finematetab: The matching array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type finematetab: Any kind of iterable or a numpy array
    :param coargraf: Another :class:`Graph` instance, which gets modified.
    :type coargraf: :class:`Graph`
    :param coarmulttab: The vertex-to-vertex multiplicity array. If given as a list or numpy array of
            integers, it is updated with the returned values.
    :type coarmulttab: Any kind of iterable or a numpy array


**Various functions are defined as wrappers of Graph operations:**

    |

.. function:: graph_alloc()

    Recreates the ``graphAlloc`` function, returning a non-initialized
    :class:`Graph` instance. It will need the :meth:`~Graph.init` method to be
    called before the instance be built or loaded upon.

    |

.. function:: build_graph(*args, **kwargs)

    Returns a properly built graph instance. Positional and keyword arguments
    need to be given in the same fashion as :meth:`Graph.build` takes them.

    |

.. function:: build_graph_from_csgraph(*args, **kwargs)

    Returns a graph instance built from the given scipy.csgraph matrix.
    Positional and keyword arguments need to be given in the same fashion as
    :meth:`Graph.build_from_csgraph` takes them.

    |

.. function:: load_graph(*args, **kwargs)

    Returns a graph instance loaded from the given file or stream. Positional
    arguments need to be given in the same fashion as :meth:`Graph.load` takes
    them.

    |

There is no explicit equivalent to Scotch's ``memFree`` function, since its call
is included in the class destructor. To delete the ``graf`` variable and free
the related graph structure before the local scope expires, simply use::

    del graf

However, due to how Python's garbage-collector works, the ``memFree`` function
may not be called immediately.

Good practices
##############

All in all, the Python and ScotchPy good practices tend not to use the
:meth:`~Graph.init` and :meth:`~Graph.exit` methods and the :class:`Graph`
constructor. They return unfinished and *per se* unusable objects, since they
are included for compatibility with the C version of Scotch. The use of the
:func:`build_graph`, :func:`build_graph_from_csgraph` or :func:`load_graph`
functions is therefore advised.