landau.phases

class landau.phases.AbstractLinePhase(name)

Bases: Phase

Base class for fixed concentration phases.

Required overloads are AbstractLinePhase.line_concentration() and AbstractLinePhase.line_free_energy().

concentration(T, dmu)

Concentration of the phase at the given state.

free_energy(T, c)

abstract property line_concentration

abstractmethod line_free_energy(T)

semigrand_potential(T, dmu)

Calculate the semigrand potential of the phase.

class landau.phases.AbstractPointDefect

Bases: ABC

abstractmethod excess_free_energy(T)

class landau.phases.AsePhase(name, fixed_concentration, thermochem, pressure=None, atoms_per_formula=1)

Bases: AbstractLinePhase

Phase wrapper for ASE’s ThermoChem classes.

Equality and hashing compare thermochem by its pickled bytes so two AsePhase instances built from equivalent inputs compare equal even though ASE’s ThermoChem defaults to identity-based equality.

atoms_per_formula divides the energy returned by thermochem so the result is per atom (landau’s convention). Use 2 for an ASE IdealGasThermo built around H₂ or O₂, 3 for CO₂, etc.; the default of 1 is correct when the ASE object already represents one atom or one per-atom formula unit (most HarmonicThermo setups, monatomic IdealGasThermo).

atoms_per_formula: int = 1

fixed_concentration: float

property line_concentration

line_free_energy(T)

pressure: float | None = None

thermochem: ThermoChem

landau.phases.ConstantPointDefect(*args, **kwargs)

class landau.phases.FastInterpolatingPhase(name, phases, add_entropy=False, maximum_extrapolation=0, concentration_range=(0.0, 1.0), interpolator=None)

Bases: SlowInterpolatingPhase

A faster, equally accurate replacement for SlowInterpolatingPhase.

Computes the same quantity – phi = min_c [ f(c) - c*dmu ] with f(c) = fe(c) - T*S(c) – but vectorised over the whole dmu array instead of one scipy.optimize.brute call per scalar.

For a fixed T the free-energy curve f(c) is evaluated once on a grid to locate the global basin (handling miscibility gaps), then the minimum is polished with a few Newton steps in the logit variable u = log(c/(1-c)). The ideal-mixing entropy contributes -T*S'(c) = kB*T*u, which is linear in u, so the polish is uniformly well conditioned from the dilute to the concentrated limit – where a plain c-space Newton step is stiff. The polish is confined to the grid cell around the basin and the lowest of {Newton result, cell edges} is kept, so a minimum sitting on a range boundary is recovered exactly and the global basin is never abandoned.

Reproduces the true minimum to ~1e-6; faster than the brute reference by two orders of magnitude on representative phases (see benchmarks/bench_fast_interpolating_phase.py).

class landau.phases.IdealSolution(name, phase1, phase2)

Bases: Phase

concentration(T, dmu)

Concentration of the phase at the given state.

phase1: AbstractLinePhase

phase2: AbstractLinePhase

semigrand_potential(T, dmu)

Calculate the semigrand potential of the phase.

class landau.phases.InterpolatingPhase(name, phases, num_coeffs=None, add_entropy=False, num_samples=100, maximum_extrapolation=0)

Bases: Phase

A Version of RegularSolutionPhase that does not depend on terminals. FIXME: These two classes should be unified.

add_entropy: bool = False

check_concentration_interpolation(T=1000, samples=50, plot_excess=False, plot_error=False)

Plot free energies of an interpolating phase and its underlying line phases to visually assess fit quality.

Parameters:

• T (float) – at which temperature to check interpolation

• samples (int) – number of sampling points for plot

• plot_excess (bool) – if True, subtract free energy at concentration range endpoints for legibility

• plot_error (bool) – if True, plot only the interpolation error at the samples instead of the free energies

check_interpolation(T=1000, samples=50)

concentration(T, dmu)

Concentration of the phase at the given state.

free_energy(T, c)

maximum_extrapolation: float = 0

num_coeffs: int = None

num_samples: int = 100

phases: Iterable[AbstractLinePhase]

semigrand_potential(T, dmu)

Calculate the semigrand potential of the phase.

class landau.phases.LinePhase(name, fixed_concentration, line_energy, line_entropy=0)

Bases: AbstractLinePhase

Simple phase with a fixed concentration and temperature independent entropy.

fixed_concentration: float

property line_concentration

line_energy: float

line_entropy: float = 0

line_free_energy(T)

class landau.phases.Phase(name)

Bases: ABC

Represents a phase in a binary phase diagram.

abstractmethod concentration(T, dmu)

Concentration of the phase at the given state.

name: str

abstractmethod semigrand_potential(T, dmu)

Calculate the semigrand potential of the phase.

landau.phases.PointDefectSublattice(*args, **kwargs)

landau.phases.PointDefectedPhase(*args, **kwargs)

class landau.phases.RegularSolution(name, phases, num_coeffs=4, add_entropy=False)

Bases: Phase

A regular solution model phase that interpolates through a given set of line phases using Redlich-Kister polynomials.

add_entropy: bool = False

If False, assume that the free energies of the line phases already include configurational mixing entropy. If True add ideal mixing entropy.

check_concentration_interpolation(T=1000, samples=50, plot_excess=False, plot_error=False)

Plot free energies of an interpolating phase and its underlying line phases to visually assess fit quality.

Parameters:

• T (float) – at which temperature to check interpolation

• samples (int) – number of sampling points for plot

• plot_excess (bool) – if True, subtract free energy at concentration range endpoints for legibility

• plot_error (bool) – if True, plot only the interpolation error at the samples instead of the free energies

check_interpolation(T=1000, samples=50)

concentration(T, dmu)

Concentration of the phase at the given state.

excess_free_energy(T, c)

free_energy(T, c)

num_coeffs: int = 4

Number of Redlich-Kister coefficients for the mixing “enthalpy”; restricted to number of phases - 2.

phases: Iterable[AbstractLinePhase]

Line phases to interpolate, must include the terminals.

semigrand_potential(T, dmu, plot=False, raw=False)

Calculate the semigrand potential of the phase.

class landau.phases.SlowInterpolatingPhase(name, phases, add_entropy=False, maximum_extrapolation=0, concentration_range=(0.0, 1.0), interpolator=None)

Bases: Phase

A slower version of RegularSolutionPhase that does not depend on terminals. FIXME: These two classes should be unified.

add_entropy: bool = False

check_concentration_interpolation(T=1000, samples=50, plot_excess=False, plot_error=False)

Plot free energies of an interpolating phase and its underlying line phases to visually assess fit quality.

Parameters:

• T (float) – at which temperature to check interpolation

• samples (int) – number of sampling points for plot

• plot_excess (bool) – if True, subtract free energy at concentration range endpoints for legibility

• plot_error (bool) – if True, plot only the interpolation error at the samples instead of the free energies

• concentration_range (tuple of float) – min/max concentration range

check_interpolation(T=1000, samples=50)

concentration(T, dmu)

Concentration of the phase at the given state.

concentration_range: tuple[float, float] = (0.0, 1.0)

free_energy(T, c)

interpolator: ConcentrationInterpolator | None = None

maximum_extrapolation: float = 0

phases: Iterable[AbstractLinePhase]

semigrand_potential(T, dmu)

Calculate the semigrand potential of the phase.

class landau.phases.Surface2DInterpolatingPhase(name, phases, add_entropy=False, maximum_extrapolation=0, concentration_range=(0.0, 1.0), interpolator=None, surface_interpolator=None, num_temperature_samples=40, temperature_range=None)

Bases: FastInterpolatingPhase

FastInterpolatingPhase backed by a fitted 2-D free-energy surface.

Unlike the parent’s _get_interpolation() — which fits a fresh 1-D curve f(c) at each temperature from the line phases’ free energies — this class fits a single surface f(T, c) once via surface_interpolator.fit() and returns fixed-T slices via FittedSurface.slice_at(T). The inherited logit-Newton solver and the full semigrand/concentration API from FastInterpolatingPhase are reused unchanged.

Training data: each line phase is sampled at num_temperature_samples evenly spaced temperatures over temperature_range (or the union of the phases’ own sampled ranges). The entropy-removed free energy H = f + T·S(c) is passed to the interpolator when add_entropy=False (the usual case with calphy data).

Parameters:

• surface_interpolator (Optional[SurfaceInterpolator]) – A SurfaceInterpolator that fits the 2-D surface from flat (T, c, H) arrays and returns a FittedSurface. Required — there is no default; omitting it raises TypeError at construction time.

• num_temperature_samples (int) – Number of T values sampled per line phase for the training set.

• temperature_range (Optional[tuple]) – (Tmin, Tmax) span used for training. Should cover the full solve grid; defaults to the union of the line phases’ own sampled temperature ranges.

num_temperature_samples: int = 40

surface_interpolator: SurfaceInterpolator | None = None

temperature_range: tuple | None = None

class landau.phases.TemperatureDependentLinePhase(name, fixed_concentration, temperatures, free_energies, interpolator=SGTE(nparam=3))

Bases: AbstractLinePhase

” Simple phase with a fixed concentration and temperature dependent free energy.

check_interpolation(Tl=0.9, Tu=1.1, samples=50, plot_error=False)

Plot the temperature interpolation against its samples to visually assess fit quality.

Parameters:

• Tl (float) – lower edge of the plotted range as a fraction of the minimum sampled temperature

• Tu (float) – upper edge of the plotted range as a fraction of the maximum sampled temperature

• samples (int) – number of points along the interpolated curve

• plot_error (bool) – if True, plot only the interpolation error at the samples instead of the free energies

fixed_concentration: float

The fixed concentration of the phase

free_energies: Iterable[float]

Sampled free energy of the phase has been computed.

interpolator: TemperatureInterpolator = SGTE(nparam=3)

How to interpolate to arbitrary temperatures from the samples.

property line_concentration

line_free_energy(T)

temperatures: Iterable[float]

Temperatures at which the free energy of the phase has been sampled.