Bond Lattice Parameter¶

BondLatticeParameter ¶

BondLatticeParameter(
    structure: Literal["fcc", "bcc", "hcp"],
    elements: Sequence[str],
    initial_a: dict[str, float] | None = None,
    initial_ca: dict[str, float] | None = None,
    calculator: BaseCalculator | None = None,
)

Bond-based lattice parameter model for FCC, BCC, or HCP alloy systems.

Predicts lattice parameters from pairwise bond lengths obtained via ML potential relaxations, following Tandoc et al. (Materialia 2025).

Two ways to create:

model = BondLatticeParameter("fcc", ["Co", "Cr", "Fe", "Ni"])
result = model.calculate()   # runs relaxations
a = model.predict({"Co": 0.25, "Cr": 0.25, "Fe": 0.25, "Ni": 0.25})

model = BondLatticeParameter.from_csv("fcc", "fcc_bond_model.csv")
a = model.predict({"Co": 0.25, "Cr": 0.25, "Fe": 0.25, "Ni": 0.25})

Initialize with crystal structure type, element system, and optional calculator.

Parameters:

Name	Type	Description	Default
`structure`	`Literal['fcc', 'bcc', 'hcp']`	Crystal structure type.	required
`elements`	`Sequence[str]`	Element symbols defining the alloy system.	required
`initial_a`	`dict[str, float] \| None`	Lattice parameter guesses per element. Falls back to built-in defaults for missing entries. Defaults to None.	`None`
`initial_ca`	`dict[str, float] \| None`	c/a ratios per element for HCP. Falls back to built-in defaults (ideal c/a = 1.633 for non-native HCP elements). Ignored for FCC/BCC. Defaults to None.	`None`
`calculator`	`BaseCalculator \| None`	Pre-configured calculator for relaxations. Defaults to None.	`None`

calculator `property` ¶

calculator: BaseCalculator

Returns the calculator instance used for relaxations.

If the calculator instance is not already initialized, this method returns the default calculator. In either case, fix_symmetry and relax_cell are forced to True, since this method requires a relaxed cell and preserved crystal symmetry to extract physically meaningful bond lengths.

Returns:

Name	Type	Description
`BaseCalculator`	`BaseCalculator`	The calculator object used for relaxations.

from_csv `classmethod` ¶

from_csv(
    structure: Literal["fcc", "bcc", "hcp"],
    path: str | Path = "bond_model.csv",
) -> BondLatticeParameter

Create a prediction-only model from a symmetric bond-length matrix CSV.

Format ,Co,Cr,Fe,... Co,2.5036,2.5512,2.4988,... Cr,2.5512,2.6021,... ...

For FCC, pure lattice parameters are recovered as a_i = d_ii * sqrt(2). For BCC, pure lattice parameters are recovered as a_i = d_ii * 2 / sqrt(3). For HCP, pure lattice parameters are recovered as a_i = d_ii (exact for ideal c/a).

calculate ¶

calculate() -> dict[str, dict]

Run all relaxations (pure + binary cells) and populate the bond table.

Returns:

Type	Description
`dict[str, dict]`	dict[str, dict]: Dictionary with keys: - `bonds`: Mapping of `(el_i, el_j)` pairs to FNN bond lengths. - `a_pure`: Mapping of element symbols to relaxed pure lattice parameters.

predict ¶

predict(composition: dict[str, float]) -> float

Predict alloy lattice parameter from the bond table.

FCC: a_bar = sqrt(2) * sum_ij x_i x_j d_ij. BCC: a_bar = (2/sqrt(3)) * sum_ij x_i x_j d_ij. HCP: a_bar = sum_ij x_i x_j d_ij (exact for ideal c/a).

Parameters:

Name	Type	Description	Default
`composition`	`dict[str, float]`	Mapping of element symbols to mole fractions.	required

Returns:

Name	Type	Description
`float`	`float`	Predicted lattice parameter in Angstroms.

Raises:

Type	Description
`ValueError`	If `calculate()` has not been called and no bond data is available.

vegard ¶

vegard(composition: dict[str, float]) -> float

Vegard's law estimate: a_bar = sum_i x_i a_i.

Parameters:

Name	Type	Description	Default
`composition`	`dict[str, float]`	Mapping of element symbols to mole fractions.	required

Returns:

Name	Type	Description
`float`	`float`	Vegard's law lattice parameter in Angstroms.

Raises:

Type	Description
`ValueError`	If `calculate()` has not been called and no bond data is available.

Bond Lattice Parameter¶