====================================
Geometries in ScotchPy
====================================

Geometries are implemented in ScotchPy with the Geom class.

The Geom class
#################



.. class:: Geom()

    The Geom constructor itself calls libscotch's ``geomAlloc`` function.
    This object doesn't need to be initialized.

    |

    .. method:: init()

        This routine initializes the fields of the Geom object instance.
        Called by a class constructor when ``init=True`` (by default).
        Mandatory before calling geom routines or after calling :meth:`~Geom.exit` in order to re-use the same Geom instance.

        |

    .. method:: exit()

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

        |

    .. method:: free()

        This routine frees the geometry data. Can be called after the geometry is no longer needed.
        Calls :meth:`~Geom.exit` and :meth:`~Geom.init` to reinitialize the object.

        |

    .. method:: data(as_dict=False)

        This routine returns the data of the geometry.
        :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: Values in this order: ``dimnnbr``, ``geomtab``.
        :rtype: Tuple or Dict

        |

    **The following routines, which need to be called from a :class:`Graph` (or a :class:`Mesh` if specified) object are relayed to the Geom class but not present in the class itself:**

        |

    .. method:: geom_load_chac(geom, grafstream, geomstream, string)

        This routine loads the geometry of the graph from the given file or stream in the Chaco graph format.

        :param geom: The geometry to be loaded.
        :type geom: :class:`~Geom`
        :param grafstream: Input file or stream to read from.
        :type grafstream: 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 geomstream: Input file or stream to read from.
        :type geomstream: 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 string: The string to be used.
        :type string: String

        |

    .. method:: geom_load_habo(geom, grafstream/meshstream, geomstream, string)

        This routine loads the geometry of the graph or the mesh from the given file or stream in the Harwell-Boeing square assembled matrix format.

        :param geom: The geometry to be loaded.
        :type geom: :class:`~Geom`
        :param grafstream: Input file or stream to read from.
        :type grafstream: 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 geomstream: Input file or stream to read from.
        :type geomstream: 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 string: The string to be used.
        :type string: String

        |

    .. method:: geom_load_scot(geom, grafstream/meshstream, geomstream, string)

        This routine loads the geometry of the graph or the mesh from the given file or stream in the Scotch graph/mesh and geometry formats.

        :param geom: The geometry to be loaded.
        :type geom: :class:`~Geom`
        :param grafstream: Input file or stream to read from.
        :type grafstream: 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 geomstream: Input file or stream to read from.
        :type geomstream: 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 string: The string to be used.
        :type string: String

        |

    .. method:: geom_save_chac(geom, grafstream, geomstream, string)

        This routine saves the geometry of the graph to the given file or stream in the Chaco graph format.

        :param geom: The geometry to be saved.
        :type geom: :class:`~Geom`
        :param grafstream: Input file or stream to write to.
        :type grafstream: 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 geomstream: Input file or stream to write to.
        :type geomstream: 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 string: The string to be used.
        :type string: String

        |

    .. method:: geom_save_scot(geom, grafstream/meshstream, geomstream, string)

        This routine saves the geometry of the graph or the mesh to the given file or stream in the Scotch graph/mesh and geometry formats.

        :param geom: The geometry to be saved.
        :type geom: :class:`~Geom`
        :param grafstream: Input file or stream to write to.
        :type grafstream: 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 geomstream: Input file or stream to write to.
        :type geomstream: 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 string: The string to be used.
        :type string: String

        |
.. function:: geom_alloc()

    This routine allocates a new geometry object and returns it.
    :returns: The new geometry object.
    :rtype: :class:`~Geom`
