.. index:: pair: namespace; topo
.. _doxid-namespacetopo:

namespace topo
==============

.. toctree::
	:hidden:

	struct_topo_FrameFingerprint.rst
	struct_topo_KeyLibrary.rst
	struct_topo_LibraryMatch.rst
	struct_topo_LocalKey.rst

Overview
~~~~~~~~




.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	
	namespace topo {

	// typedefs

	typedef std::vector<std::vector<int>> :ref:`Rows<doxid-namespacetopo_1a770ae81afc5c8c715470d90d4e3c8e6e>`;

	// structs

	struct :ref:`FrameFingerprint<doxid-structtopo_1_1_frame_fingerprint>`;
	struct :ref:`KeyLibrary<doxid-structtopo_1_1_key_library>`;
	struct :ref:`LibraryMatch<doxid-structtopo_1_1_library_match>`;
	struct :ref:`LocalKey<doxid-structtopo_1_1_local_key>`;

	// global functions

	std::vector<int> :ref:`hopNeighbourhood<doxid-namespacetopo_1ac22724ca2d62a9ecac9d20b5ab0b7182>`(const :ref:`Rows<doxid-namespacetopo_1a770ae81afc5c8c715470d90d4e3c8e6e>`& rows, int atom, int hops);
	std::uint64_t :ref:`wlHash<doxid-namespacetopo_1a3c1e2aed1633a79c2b9ac530d63c28a6>`(const std::vector<std::vector<int>>& adjacency, int root, int rounds, const std::vector<int>& colours = {});
	:ref:`LocalKey<doxid-structtopo_1_1_local_key>` :ref:`localKey<doxid-namespacetopo_1a4c926ab08f90e20ec25abcc63593821b>`(const :ref:`Rows<doxid-namespacetopo_1a770ae81afc5c8c715470d90d4e3c8e6e>`& rows, int atom, int hops, const std::vector<int>& colours = {});
	:ref:`FrameFingerprint<doxid-structtopo_1_1_frame_fingerprint>` :ref:`fingerprint<doxid-namespacetopo_1a31e36c2b000ef45e1e0370ceffcc7b07>`(const :ref:`Rows<doxid-namespacetopo_1a770ae81afc5c8c715470d90d4e3c8e6e>`& rows, int hops = 2, int maxRingSize = 7, const std::vector<int>& colours = {});
	std::string :ref:`hex<doxid-namespacetopo_1a704a6805e4842829fa83f16081405519>`(std::uint64_t value);
	void :ref:`addToLibrary<doxid-namespacetopo_1ab7a77ab1002ce0af5dda5656f84ae369>`(:ref:`KeyLibrary<doxid-structtopo_1_1_key_library>`& lib, const :ref:`FrameFingerprint<doxid-structtopo_1_1_frame_fingerprint>`& fp, const std::string& label);
	std::string :ref:`writeLibrary<doxid-namespacetopo_1a57942af5bce01d27654ba8d544195fe0>`(const :ref:`KeyLibrary<doxid-structtopo_1_1_key_library>`& lib);
	:ref:`KeyLibrary<doxid-structtopo_1_1_key_library>` :target:`readLibrary<doxid-namespacetopo_1ad78791f54d32c853345d0cffe9dcfa0b>`(const std::string& text);
	:ref:`LibraryMatch<doxid-structtopo_1_1_library_match>` :ref:`matchLibrary<doxid-namespacetopo_1a73c3376495bbd19d8f072ac21af98131>`(const :ref:`FrameFingerprint<doxid-structtopo_1_1_frame_fingerprint>`& fp, const :ref:`KeyLibrary<doxid-structtopo_1_1_key_library>`& lib);
	:ref:`LibraryMatch<doxid-structtopo_1_1_library_match>` :ref:`matchLibraries<doxid-namespacetopo_1a3fe468feddca93b3dc1bc79db0dad30e>`(const :ref:`Rows<doxid-namespacetopo_1a770ae81afc5c8c715470d90d4e3c8e6e>`& rows, const std::vector<:ref:`KeyLibrary<doxid-structtopo_1_1_key_library>`>& libs, int maxRingSize = 7, const std::vector<int>& colours = {});

	} // namespace topo
.. _details-namespacetopo:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~



Typedefs
--------

.. index:: pair: typedef; Rows
.. _doxid-namespacetopo_1a770ae81afc5c8c715470d90d4e3c8e6e:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef std::vector<std::vector<int>> Rows

Neighbour rows by index, each row leading with the atom itself, as :ref:`nneigh::neighbourListByIndex <doxid-group__nneigh_1gacf46d8c4b42f15e634ff0076ac83c012>` returns them.

Global Functions
----------------

.. index:: pair: function; hopNeighbourhood
.. _doxid-namespacetopo_1ac22724ca2d62a9ecac9d20b5ab0b7182:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	std::vector<int> hopNeighbourhood(const :ref:`Rows<doxid-namespacetopo_1a770ae81afc5c8c715470d90d4e3c8e6e>`& rows, int atom, int hops)

Atoms within ``hops`` bonds of ``atom``, the atom itself first, then in breadth-first order.

.. index:: pair: function; wlHash
.. _doxid-namespacetopo_1a3c1e2aed1633a79c2b9ac530d63c28a6:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	std::uint64_t wlHash(const std::vector<std::vector<int>>& adjacency, int root, int rounds, const std::vector<int>& colours = {})

Weisfeiler-Lehman refinement hash of a graph given by local adjacency lists; ``root`` (or -1) starts in its own colour; ``colours`` (empty or one integer per vertex, such as the atom type) seeds the initial colours.

``rounds`` refinements.

.. index:: pair: function; localKey
.. _doxid-namespacetopo_1a4c926ab08f90e20ec25abcc63593821b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`LocalKey<doxid-structtopo_1_1_local_key>` localKey(const :ref:`Rows<doxid-namespacetopo_1a770ae81afc5c8c715470d90d4e3c8e6e>`& rows, int atom, int hops, const std::vector<int>& colours = {})

Key of the rooted neighbourhood of ``atom``.

``colours`` is empty or one class per row (atom type, species); coloured vertices never match vertices of another colour.

.. index:: pair: function; fingerprint
.. _doxid-namespacetopo_1a31e36c2b000ef45e1e0370ceffcc7b07:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`FrameFingerprint<doxid-structtopo_1_1_frame_fingerprint>` fingerprint(const :ref:`Rows<doxid-namespacetopo_1a770ae81afc5c8c715470d90d4e3c8e6e>`& rows, int hops = 2, int maxRingSize = 7, const std::vector<int>& colours = {})

Keys of every atom, their histogram, the ring census up to ``maxRingSize``, and the frame key.

``colours`` as in localKey.

.. index:: pair: function; hex
.. _doxid-namespacetopo_1a704a6805e4842829fa83f16081405519:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	std::string hex(std::uint64_t value)

Hex string of a 64-bit hash.

.. index:: pair: function; addToLibrary
.. _doxid-namespacetopo_1ab7a77ab1002ce0af5dda5656f84ae369:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void addToLibrary(:ref:`KeyLibrary<doxid-structtopo_1_1_key_library>`& lib, const :ref:`FrameFingerprint<doxid-structtopo_1_1_frame_fingerprint>`& fp, const std::string& label)

Add every distinct key of ``fp`` under ``label``; a key already present under other labels carries all of them, sorted and joined by '|'.

.. index:: pair: function; writeLibrary
.. _doxid-namespacetopo_1a57942af5bce01d27654ba8d544195fe0:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	std::string writeLibrary(const :ref:`KeyLibrary<doxid-structtopo_1_1_key_library>`& lib)

Text form: a header line ``# method M hops H colours C`` (C is 0 or 1; a header without it means uncoloured), then ``key label`` lines.

.. index:: pair: function; matchLibrary
.. _doxid-namespacetopo_1a73c3376495bbd19d8f072ac21af98131:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`LibraryMatch<doxid-structtopo_1_1_library_match>` matchLibrary(const :ref:`FrameFingerprint<doxid-structtopo_1_1_frame_fingerprint>`& fp, const :ref:`KeyLibrary<doxid-structtopo_1_1_key_library>`& lib)

Look every atom key of ``fp`` up in ``lib``.

Throws std::invalid_argument when the methods, hop counts or colourings differ.

.. index:: pair: function; matchLibraries
.. _doxid-namespacetopo_1a3fe468feddca93b3dc1bc79db0dad30e:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`LibraryMatch<doxid-structtopo_1_1_library_match>` matchLibraries(const :ref:`Rows<doxid-namespacetopo_1a770ae81afc5c8c715470d90d4e3c8e6e>`& rows, const std::vector<:ref:`KeyLibrary<doxid-structtopo_1_1_key_library>`>& libs, int maxRingSize = 7, const std::vector<int>& colours = {})

Match against libraries at several depths: an atom takes the label of the deepest library that holds its key, and a molecule whose wide neighbourhood is disturbed (a defect two bonds away, a jittered dense polymorph) still gets named by its inner shells.

``depth`` records the hops that named each atom. Every library must share the method of this build and the colouring (``colours`` empty or one per row); throws std::invalid_argument otherwise, or when two libraries share a depth.