=======================
Partitioning Strategies
=======================

The Strat class
###############
.. class:: Strat(init=True)

    The strategy constructor itself calls libscotch's ``stratAlloc`` function, and
    usually ``stratInit`` is called too.

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

   |

    .. method:: init()

        This routine Initializes the fields of the :class:`Strat` object instance.
        Called by a class constructor when ``init=True`` (by default).
        Mandatory before calling any routine.

    |

    .. method:: exit()

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

    |

    .. method:: save(stream)

        This routine saves the strategy to the given file or stream in the form of a text string.

    :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:: graph_cluster_build(flagval, pwgtmax, densmin, bbalval)

        This routine provides predefined clustering strategies. The strategy can only be used as a mapping strategy.

    :param flagval: The type of clustering strategy to use.
    :type flagval: Integer
    :param pwgtmax: The maximum cluster vertex weight.
    :type pwgtmax: Integer
    :param densmin: The minimum edge density.
    :type densmin: Float
    :param bbalval: The bipartition imbalance ratio.
    :type bbalval: Float

    |

    .. method:: graph_map_build(flagval, partnbr, balrat)

        This routine fills the strategy with predefined mapping strategies. The strategy can only be used as a mapping strategy.

    :param flagval: The type of mapping strategy to use.
    :type flagval: Integer
    :param partnbr: The number of parts to map to.
    :type partnbr: Integer
    :param balrat: The bipartition imbalance ratio.
    :type balrat: Float

    |

    .. method:: graph_part_ovl_build(flagval, partnbr, balrat)

        This routine provides predefined overlap partitioning strategies. The strategy can only be used as a partitioning with overlap strategy.

    :param flagval: The type of overlap partitioning strategy to use.
    :type flagval: Integer
    :param partnbr: The number of parts to partition into.
    :type partnbr: Integer
    :param balrat: The bipartition imbalance ratio.
    :type balrat: Float

    |

    .. method:: graph_order_build(flagval, lvlnbr, balrat)

        This routine provides predefined ordering strategies. The strategy can only be used as a graph ordering strategy.

    :param flagval: The type of ordering strategy to use.
    :type flagval: Integer
    :param lvlnbr: The number of levels to use (When the ``SCOTCH_STRATLEVELMIN`` or ``SCOTCH_STRATLEVELMAX`` or flag is set, the value of ``lvlnbr`` is not ignored.)
    :type lvlnbr: Integer
    :param balrat: The bipartition imbalance ratio.
    :type balrat: Float

    |

    .. method:: mesh_order_build(flagval, balrat)

        This routine provides predefined ordering strategies. The strategy can only be used as a mesh ordering strategy.

    :param flagval: The type of ordering strategy to use.
    :type flagval: Integer
    :param balrat: The bipartition imbalance ratio.
    :type balrat: Float

    |


    .. method:: dgraph_cluster_build(flagval, pwgtmax, densmin, bbalval)

        This routine fills the strategy with predefined clustering strategies. The strategy can only be used as a distributed mapping strategy.

    :param flagval: The type of clustering strategy to use.
    :type flagval: Integer
    :param pwgtmax: The maximum cluster vertex weight.
    :type pwgtmax: Integer
    :param densmin: The minimum edge density.
    :type densmin: Float
    :param bbalval: The bipartition imbalance ratio.
    :type bbalval: Float

    |

    .. method:: dgraph_map(string)

            This routine parses the given distributed mapping strategy. The strategy can only be used as a distributed mapping strategy.

    :param string: The distributed mapping strategy.
    :type string: String

    |

    .. method:: dgraph_map_build(flagval, procnbr, partnbr, balrat)

            This routine fills the strategy with the parameters of a default mapping strategy and the given parameters.

    :param flagval: The type of distributed mapping strategy to use.
    :type flagval: Integer
    :param procnbr: The number of processors to map to.
    :type procnbr: Integer
    :param partnbr: The number of parts to map to.
    :type partnbr: Integer
    :param balrat: The bipartition imbalance ratio.
    :type balrat: Float

    |

    .. method:: dgraph_order(string)

            This routine parses the given distributed ordering strategy. The strategy can only be used as a distributed ordering strategy.

    :param string: The distributed ordering strategy.
    :type string: String

    |

    .. method:: dgraph_order_build(flagval, procnbr, levlnbr, balrat)

            This routine fills the strategy with the parameters of a default ordering strategy and the given parameters.

    :param flagval: The type of distributed ordering strategy to use.
    :type flagval: Integer
    :param procnbr: The number of processors to map to.
    :type procnbr: Integer
    :param levlnbr: The number of levels to use.

    .. method:: graph_bipart(string)

        This routine parses the given bipartitioning strategy. The strategy can only be used as a graph bipartitioning strategy.

    :param string: The graph bipartitioning strategy.
    :type string: String

    |

    .. method:: graph_map(string)

        This routine parses the given mapping strategy. The strategy can only be used as a mapping strategy.

    :param string: The mapping strategy.
    :type string: String

    |

    .. method:: graph_part_ovl(string)

        This routine parses the given partitioning strategy. The strategy can only be used as a partitioning with overlap strategy.

    :param string: The partitioning strategy.
    :type string: String

    |

    .. method:: graph_order(string)

        This routine parses the given graph ordering strategy. The strategy can only be used as a graph ordering strategy.

    :param string: The graph ordering strategy.
    :type string: String

    |

    .. method:: mesh_order(string)

        This routine parses the given mesh ordering strategy. The strategy can only be used as a mesh ordering strategy.

    :param string: The mesh ordering strategy.
    :type string: String

    |

.. function:: strat_alloc()

    This routine ecreates the ``stratAlloc`` function, returning a non-initialized
    :class:`Strat` instance. It will need the :meth:`~Strat.init` method to be
    called before the instance be built or loaded upon.

    |

.. function:: graph_part(graph, partnbr, strat, parttab=None)

    This routine computes a partition of the graph, with respect to the given
    strategy.

    :param graph: The graph to partition.
    :type graph: :class:`Graph`
    :param partnbr: The number of parts to partition into.
    :type partnbr: Integer
    :param strat: The partitioning strategy.
    :type strat: :class:`Strat`
    :param parttab: The partition array.
    :type parttab: :class:`numpy.ndarray`

    |

.. function:: graph_part_fixed(graph, partnbr, strat, parttab=None)

    This routine computes a partition of the graph, with respect to the given
    strategy and the fixed vertices in ``maptab``.

    :param graph: The graph to partition.
    :type graph: :class:`Graph`
    :param partnbr: The number of parts to partition into.
    :type partnbr: Integer
    :param strat: The partitioning strategy.
    :type strat: :class:`Strat`
    :param parttab: The partition array.
    :type parttab: :class:`numpy.ndarray`

    |

.. function:: graph_part_ovl(graph, partnbr, strat, parttab=None)

    This routine computes a partition with overlap of the graph, with respect to
    the given strategy and the fixed vertices in ``maptab``.

    :param graph: The graph to partition.
    :type graph: :class:`Graph`
    :param partnbr: The number of parts to partition into.
    :type partnbr: Integer
    :param strat: The partitioning strategy.
    :type strat: :class:`Strat`
    :param parttab: The partition array.
    :type parttab: :class:`numpy.ndarray`

Further documentation about these three ``graph_part*`` functions can be found
in :meth:`Graph.part`, :meth:`Graph.part_fixed` and :meth:`Graph.part_ovl`.
