matcalc._order module

Monte Carlo ordering of disordered structures.

class OrderCalc(calculator: Calculator | str, *, nsteps: int = 1000, temperature: float = 1000.0, seed: int | None = None, patience: int | None = None, n_init: int = 1, n_lowest: int = 1, n_jobs: int | None = None, relax_structure: bool = False, relax_calc_kwargs: dict | None = None)[source]

Bases: PropCalc

Order a disordered structure with Metropolis Monte Carlo.

Given a structure with fractional site occupancies, OrderCalc builds a random ordering whose species counts are commensurate with the input occupancies (partial occupancy summing to < 1 is treated as vacancies), evaluates its total energy with the supplied PES calculator, then performs nsteps of Monte Carlo in which the species occupying two disordered sites are swapped. Each proposal is accepted with the standard Metropolis criterion min(1, exp(-ΔE / (kB·T))). Swaps exchange species between sites, so the overall composition is conserved throughout.

Several independent chains can be launched from different random starts (n_init) and run in parallel (n_jobs); a chain stops early once its best energy has not improved for patience consecutive steps. The n_lowest lowest-energy distinct orderings found across all chains are returned, with the overall best as final_structure.

calculator[source]

ASE calculator (or universal model name) for energies.

nsteps[source]

Maximum number of Monte Carlo swap proposals per chain.

temperature[source]

Monte Carlo temperature (K).

seed[source]

Base seed for the random number generator (None for nondeterministic).

patience[source]

Stop a chain early if the best energy has not improved for this many consecutive steps (None disables early stopping).

n_init[source]

Number of independent Monte Carlo chains (random initializations).

n_lowest[source]

Number of lowest-energy distinct orderings to return.

n_jobs[source]

Worker count for running chains in parallel.

relax_structure[source]

Relax the best ordering before returning it.

relax_calc_kwargs[source]

Optional kwargs forwarded to RelaxCalc.

Parameters:

  • calculator – ASE calculator or universal model name string.

  • nsteps – Maximum number of Monte Carlo swap proposals per chain.

  • temperature – Monte Carlo temperature in K. Must be >= 0; at 0 K only downhill (non-positive ΔE) swaps are accepted.

  • seed – Base seed for the random number generator. None gives a nondeterministic run; when set, chain k uses seed + k so runs are reproducible.

  • patience – Stop a chain early once its best (lowest) energy has not improved for patience consecutive steps. None (default) runs the full nsteps. Must be a positive integer when set.

  • n_init – Number of independent Monte Carlo chains launched from different random initial orderings. Must be >= 1.

  • n_lowest – Number of lowest-energy distinct orderings to return. Must be >= 1.

  • n_jobs – Number of joblib workers for running chains in parallel. None uses the joblib default; only relevant when n_init > 1.

  • relax_structure – Relax the lowest-energy ordering before returning.

  • relax_calc_kwargs – Optional kwargs forwarded to RelaxCalc when relax_structure is True.

Raises:

ValueError – If temperature is negative, n_init < 1, n_lowest < 1, or patience is set but not a positive int.

_abc_impl = <_abc._abc_data object>[source]
_initial_tokens(structure: Structure, disordered_indices: list[int], rng: random.Random, tol: float = 0.0001) → list[Species | Element | DummySpecies | None][source]

Build a randomly shuffled species assignment for the disordered sites.

Parameters:

  • structure – The disordered input structure.

  • disordered_indices – Indices of the sites with partial occupancy.

  • rng – Random number generator used to shuffle the assignment.

  • tol – Tolerance for rounding species amounts to integer counts.

Returns:

A list (one entry per disordered site) of the species to place at that site, or None for a vacancy.

Raises:

ValueError – If the total occupancy over the disordered sites is not commensurate with an integer number of atoms (within tol).

_make_structure(structure: Structure, disordered_indices: list[int], tokens: list[Species | Element | DummySpecies | None] | Tokens) → Structure[source]

Construct an ordered structure from a species assignment.

Parameters:

  • structure – The disordered input structure.

  • disordered_indices – Indices of the sites with partial occupancy.

  • tokens – Species (or None for a vacancy) to place at each disordered site, aligned with disordered_indices.

Returns:

An ordered Structure; ordered sites are untouched and vacancies are removed.

_run_chain(structure: Structure, disordered_indices: list[int], seed: int | None) → dict[str, Any][source]

Run a single Monte Carlo chain.

Parameters:

  • structure – The disordered input structure.

  • disordered_indices – Indices of the sites with partial occupancy.

  • seed – Seed for this chain’s random number generator.

Returns:

Dict with best_energy (eV), energies (the accepted-energy trajectory), acceptance_ratio, steps_run (steps actually taken before early stopping), and candidates (the chain’s n_lowest lowest-energy distinct orderings as {Tokens: energy}).

Raises:

ValueError – If the disordered sites hold only a single species, so no swap can change the ordering.

calc(structure: Structure | Atoms | dict[str, Any]) → dict[str, Any][source]
Parameters:

structure – A disordered pymatgen Structure (or a dict carrying one under final_structure / structure).

Returns:

Dict with final_structure (the lowest-energy ordering, optionally relaxed), energy (eV, its total energy), lowest_structures (the n_lowest lowest-energy distinct orderings, ascending) and lowest_energies (eV, aligned with them), energies (eV, the accepted-energy trajectory of the chain that found the best ordering), acceptance_ratio for that chain, _units, plus any relaxation keys when relax_structure is True.

Raises:

ValueError – If the input structure is already fully ordered, or has fewer than two distinct species to swap among its disordered sites.