Prepare NEB Fitting Inputs

For a first pass through the workflow, start with the beginner page Local Environments And NEB Data. This page gives lower-level details for NEBDataLoader.

Use NEBDataLoader when you have NEB barriers for a list of structures and want to fit a LocalClusterExpansion.

The loader does three things:

  1. maps each NEB structure onto the reference local lattice,

  2. computes the LCE correlation matrix,

  3. writes the text files consumed by LocalClusterExpansion.fit(...).

Minimal Workflow

from kmcpy.io.neb import NEBDataLoader
from kmcpy.models.local_cluster_expansion import LocalClusterExpansion
from kmcpy.structure.local_lattice_structure import LocalLatticeStructure

model = LocalClusterExpansion.from_file("lce.json")

reference = LocalLatticeStructure(
    template_structure=reference_structure,
    center=0,
    cutoff=4.0,
    site_mapping={
        "Na": ["Na", "X"],
        "Zr": "Zr",
        "Si": ["Si", "P"],
        "O": "O",
    },
    basis_type="chebyshev",
)

loader = NEBDataLoader.from_structures(
    ["neb_0001.cif", "neb_0002.cif"],
    [120.5, 140.1],
    model=model,
    reference_local_lattice_structure=reference,
)

fit_inputs = loader.write_fitting_inputs("fit_data", weight=1.0)

model_params, y_pred, y_true = model.fit(
    alpha=1.5,
    max_iter=1_000_000,
    **fit_inputs,
)

The barrier values above are in meV.

When The Reference Can Be Omitted

If the model was built in memory with LocalClusterExpansion.build(...), the reference local lattice is already attached to the model:

model = LocalClusterExpansion()
model.build(reference, cutoff_cluster=[4.0, 4.0, 4.0])

loader = NEBDataLoader.from_structures(
    structure_files,
    barriers_mev,
    model=model,
)

If you load a model file and the local lattice is not attached, pass reference_local_lattice_structure explicitly.

Occupation And Basis Convention

With basis_type="chebyshev", kMCpy stores occupations as discrete state indices. For example:

site_mapping = {"Na": ["Na", "X"]}

uses:

Na = 0
X  = 1

For more than two allowed states:

site_mapping = {"Al": ["Al", "X", "Mg", "Si"]}

kMCpy stores:

Al = 0
X  = 1
Mg = 2
Si = 3

A site with q allowed states contributes q - 1 non-constant Chebyshev basis functions to decorated LCE cluster features.

Output Files

write_fitting_inputs(...) returns paths suitable for model.fit(...), such as correlation, target barrier, and weight files. Keep these files with the model and fitted parameter output so the fitting dataset is reproducible.

Checklist

  • Barrier targets should be in meV.

  • The reference local lattice must match the LCE local site order.

  • The structure files must map cleanly onto the reference lattice.

  • Use the same basis_type and site_mapping used to build the model.

  • Keep generated fitting inputs and fitted parameters together.