Simply put:

• Benchmark class provides the necessary infrastructure to perform the comparison of CN algorithms. When being initialized, it takes the group of test structures (or your own structures) and a list of CNBase methods (CN calculation methods) as arguments.
• Benchmark.benchmark() performs the CN calculations on the selected test structures
• Benchmark.report() provides different types of reports that summarizes the results of the benchmarking.

For example, we can compare the Effective Coordination Number (ECoN) and O'Keeffe's Voronoi CN method using a set of unique elemental crystal structures:

from materialscoord.cn_methods import TestECoN, TestVoronoiCoordFinder
from materialscoord.core import Benchmark
bm = Benchmark([TestECoN(), TestVoronoiCoordFinder()], "elemental")
bm.benchmark()
bm.report()

This is fairly simple:

1. Define a new class that is subclassed from materialscoord.core.CNBase.
2. The class must have a method named compute which takes a pymatgen Structure and site-index as input, and returns a dictionary of CNs for that site; e.g. {'O': 4.4, 'F': 2.1}.

For example:

class MyCoordinationNumberAlgorithm(CNBase):
    """
    My new algorithm
    """
    def compute(self, structure, n):
        params = self._params

        # ... here your algorithm finds CNs of site n.
        # e.g. cns = my_algorithm(structure, n, **params)

        return cns

Any parameters the algorithm needs can be passed to the class when initializing using the params keyword as a dictionary. These can later be accessed from compute method as the _params attribute of the class.

In method compute you can do whatever is necessary to interface the algorithm with MaterialsCoord. Options include:

• Simplest: Implementing the entire algorithm within the compute method.
• Recommended: Add the necessary "bulky" code to a relevant module in external_src package and import as you define compute.
• Not recommended: call or import a library/program outside of MaterialsCoord within the compute method. This is not recommended as external dependencies will restrict portability, but maybe unavoidable if the external algorithm is part of another python package, or is written in some other language such as Java. In that case compute can simply serve as a wrapper that calls and post processes the output of the external code.

If you interpret the CN environment in a structure and you want to add it to MaterialsCoord to compare against availble CN methods, you can basically add the CN numbers to the human_interpreter.yaml as a dictionary that matches the name of the structure file in test_structures or custom_set you provided (without the file extension, if it has any). For example:

Fe3O4_spinel:
    - Fe:
        Fe: 0.0
        O: 6.0
    - Fe:
        Fe: 0.0
        O: 4.0
    - O:
        Fe: 4.0
        O: 0.0

describes the CN environment in the spinel Fe3O4 spinel structure, where there are two different unique Fe sites, and one O site. Sites are given as a list. And for each site a dictionary of neighboring elements are provided. In this sub-dictionary of surroundings of a given site, we do not differentiate between sites and only list the total CN number for each chemical element (i.e. there is one Fe in each) opposite to the unique sites list (where we had two Fe sites).

Since it is not always easy to interpret the exact coordination number, MaterialsCoord will accept a range. Let's assume hypothetically we aren't sure how many Fe neighbors the O site has, but we guess it's between 3.0 and 5.0, we can write:

Fe3O4_spinel:
    - Fe:
        Fe: 0.0
        O: 6.0
    - Fe:
        Fe: 0.0
        O: 4.0
    - O:
        Fe:
            - 3.0
            - 5.0
        O: 0.0