landau.phases¶
- class landau.phases.AbstractLinePhase(name)[source]¶
Bases:
PhaseBase class for fixed concentration phases.
Required overloads are
AbstractLinePhase.line_concentration()andAbstractLinePhase.line_free_energy().- free_energy(T, c)[source]¶
The line free energy at every
c: broadcast againstc, which it does not depend on.
- abstract property line_concentration¶
- class landau.phases.AsePhase(name, fixed_concentration, thermochem, pressure=None, atoms_per_formula=1)[source]¶
Bases:
AbstractLinePhasePhase wrapper for ASE’s ThermoChem classes.
Equality and hashing compare
thermochemby its pickled bytes so twoAsePhaseinstances built from equivalent inputs compare equal even though ASE’sThermoChemdefaults to identity-based equality.atoms_per_formuladivides the energy returned bythermochemso the result is per atom (landau’s convention). Use 2 for an ASEIdealGasThermobuilt 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 (mostHarmonicThermosetups, monatomicIdealGasThermo).- atoms_per_formula: int = 1¶
- fixed_concentration: float¶
- property line_concentration¶
- pressure: float | None = None¶
- thermochem: ThermoChem¶
- class landau.phases.FastInterpolatingPhase(name, phases, add_entropy=False, maximum_extrapolation=0, concentration_range=(0.0, 1.0), interpolator=None)[source]¶
Bases:
SlowInterpolatingPhaseA faster, equally accurate replacement for
SlowInterpolatingPhase.Computes the same quantity –
phi = min_c [ f(c) - c*dmu ]withf(c) = fe(c) - T*S(c)– but vectorised over the wholedmuarray instead of onescipy.optimize.brutecall per scalar.For a fixed
Tthe free-energy curvef(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 variableu = log(c/(1-c)). The ideal-mixing entropy contributes-T*S'(c) = kB*T*u, which is linear inu, so the polish is uniformly well conditioned from the dilute to the concentrated limit – where a plainc-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
brutereference by two orders of magnitude on representative phases (seebenchmarks/bench_fast_interpolating_phase.py).
- class landau.phases.IdealSolution(name, phase1, phase2)[source]¶
Bases:
Phase- free_energy(T, c)[source]¶
Linear interpolation of the terminal free energies minus the ideal mixing term,
T * S(c).
- phase1: AbstractLinePhase¶
- phase2: AbstractLinePhase¶
- class landau.phases.InterpolatingPhase(name, phases, num_coeffs=None, add_entropy=False, num_samples=100, maximum_extrapolation=0)[source]¶
Bases:
PhaseA Version of RegularSolutionPhase that does not depend on terminals. FIXME: These two classes should be unified.
Deprecated since version Use:
FastInterpolatingPhaseinstead; removal in 2.0.- add_entropy: bool = False¶
- check_concentration_interpolation(T=1000, samples=50, plot_excess=False, plot_error=False)[source]¶
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
- maximum_extrapolation: float = 0¶
- num_coeffs: int = None¶
- num_samples: int = 100¶
- phases: Iterable[AbstractLinePhase]¶
- class landau.phases.LinePhase(name, fixed_concentration, line_energy, line_entropy=0)[source]¶
Bases:
AbstractLinePhaseSimple phase with a fixed concentration and temperature independent entropy.
- fixed_concentration: float¶
- property line_concentration¶
- line_energy: float¶
- line_entropy: float = 0¶
- class landau.phases.Phase(name)[source]¶
Bases:
ABCRepresents a phase in a binary phase diagram.
- name: str¶
- class landau.phases.PhonopyQuasiHarmonicPhase(name, fixed_concentration, thermal_properties, volumes, energies, atoms_per_cell, atoms_per_primitive_cell, eos=PolyFit(nparam=8, regularizer_strength=1e-08, enforce_curvature=False), min_frequency=-0.05, extrapolate=False)[source]¶
Bases:
AbstractLinePhaseA fixed-concentration phase whose free energy is evaluated from phonon spectra.
Give one phonopy
ThermalPropertiesper sampled volume, together with the volume and static energy of the cell each was computed for, or build the phase from livePhonopyobjects withfrom_phonopy(). At every requested temperature the free energy of each volume comes from phonopy’s mode sum, an equation of state is fitted through the results and its minimum is returned – one number per temperature, computed rather than interpolated, at any temperature the caller asks for.Compared with sampling the same calculation onto a grid and handing that to
TemperatureDependentLinePhase, this removes both the grid and the fit. On quasi-harmonic data the defaultSGTE(3)leaves residuals of several meV/atom (issue #427), and a shallow solid-solid transition converts one meV/atom into tens of kelvin.Statistics (
classical), the mode cutoff (cutoff_frequency) and the sampling mesh are the caller’s, fixed when they ranrun_thermal_properties(); this class does not second-guess them. It does resettemperatureson those objects and re-run()them – once at construction and again at every temperature asked of the phase – so theThermalPropertieshanded over are left holding whatever temperature was evaluated last. Pass copies if the caller still needs their own results.Primitive vs unit cell.
volumesandenergiesdescribe whatever cell was actually relaxed, while phonopy normalises a free energy per primitive cell. These differ whenever the unit cell is not primitive – phonopy’sprimitive_matrix="auto"reduces a cubic fcc cell by 4 and hcp/bcc by 2 – and pairing them without converting silently rescales every vibrational free energy by that factor. Both counts are therefore required and each part is normalised by its own before they are added.Two ways a quasi-harmonic fit degrades without saying so, and what happens here:
Dynamically unstable volumes. Imaginary modes are dropped by the mode sum rather than raised on, so a volume with unstable branches still returns a smooth, plausible free energy that then corrupts the equation-of-state fit every other volume feeds. Volumes whose lowest mode falls below
min_frequencyare excluded and reported throughlowest_frequencies, with aDynamicalInstabilityWarningat construction. See_lowest_frequency()for how that mode is recovered from aThermalProperties, which does not expose it.Past the sampled volumes the minimisation is constrained, not extrapolated. Once thermal expansion carries the free-energy minimum above the largest volume sampled, the equation of state would have to extrapolate to reach it, and its error there is not bounded by anything the fit knows. So the volume is clamped to the nearest sampled end and the free energy reported there – the minimum over the volumes that were actually calculated – with an
EosExtrapolationWarningsaying so. The constrained and unconstrained minima coincide at the crossing, so the reported curve is continuous; above it the phase understates the expansion and therefore overstates the free energy.max_temperature()reports where that starts andcheck_equation_of_state()shows it; sampling wider volumes is the only way to push it up, andextrapolatefollows the fit out instead.- atoms_per_primitive_cell: int¶
Number of atoms in the primitive cell the phonons were computed on; phonopy reports a free energy per primitive cell.
- check_equation_of_state(T=300.0, samples=100, margin=0.05, plot_error=False)[source]¶
Plot the volume minimisation at one temperature, to see what it is doing.
Draws three things on the current axes (or, with
plot_error, how far the fit misses each sampled volume): the free energy of every sampled volume, the equation of state fitted through them, and the minimumline_free_energy()reports. They have to agree for the reported number to mean anything, and once the minimum has left the sampled volumes the marker sits pinned to the edge of the shaded range while the curve keeps falling past it – which is exactly the extrapolation being declined.- Parameters:
T (float) – temperature in K
samples (int) – number of points along the plotted curve
margin (float) – fraction of the sampled span to extend the curve past each end, so a minimum just outside the data is still visible
plot_error (bool) – if True, plot the residual of each sampled volume against the fitted equation of state instead of the free energies themselves. This is the second approximation underneath the reported free energy, so the residual is what says whether the fit has run out of freedom to follow the data – on the scale that matters, meV/atom. A systematic sign pattern rather than scatter means shape the fit cannot take
- energies: tuple¶
Static (electronic) energy of that same cell, in eV.
- property energies_per_atom¶
energiesdivided byatoms_per_cell, in the order given.
- eos: str | Interpolator = PolyFit(nparam=8, regularizer_strength=1e-08, enforce_curvature=False)¶
How to fit
F(V)before minimising it over volume.Either one of landau’s own interpolators, fitted through the sampled volumes, or one of the closed-form equations of state
"vinet","birch_murnaghan"or"murnaghan"passed tophonopy.qha.eos.get_eos().This fit is a second approximation underneath the temperature interpolation the class removes, and the closed forms are not accurate enough for it to be ignored: measured on fcc Cu over nine volumes (
benchmarks/qha_eos_forms.py),"vinet"leaves 4.3 meV/atom at 1200 K and"birch_murnaghan"3.0, against 0.1 for the default here. All three closed forms carry four parameters, so on a wide volume set they run out of freedom long before the data runs out of shape.The parameter count is capped at one fewer than there are stable volumes, since a polynomial through as many points as it has coefficients interpolates exactly and its minimum stops meaning anything; with the four volumes this class needs at minimum it is a cubic. The cap covers an interpolator that picks its own count as well, applied once it has picked:
PolyFit("auto")selects under an L1 penalty on a degree-ten basis, which is underdetermined at these sample counts and comes back with roughly as many parameters as there are volumes.A fixed count rather than a selected one because the selection would be made per temperature, and it moves: on the nine-volume fcc Cu set it flips between six and eight parameters several times over 114-122 K, each flip a step of tens of microelectronvolts per atom in
F(T)and a few times 1e-3 cubic Angstrom inV(T)where nothing physical happens – against under two microelectronvolts of genuine variation across the same window (benchmarks/qha_eos_forms.py). Steps in the reported free energy are the one thingline_free_energy()must not invent, sincecalc_phase_diagramreads them as transitions.An interpolator is fitted in a centred, scaled volume coordinate and its minimum is located inside the sampled range only – a polynomial has no useful behaviour outside its data – so
extrapolateis incompatible with one.
- eos_parameters(T)[source]¶
Equation-of-state parameters at one temperature.
Fits
self.eosthrough the per-atom free energies ofsampled_volumes.- Parameters:
T (float) – temperature in K
- Returns:
(E_0, B_0, B'_0, V_0)– the minimum free energy in eV per atom, the bulk modulus in eV per cubic Angstrom, its pressure derivative, and the equilibrium volume in cubic Angstrom per atom. The last is+-infwhen the fit has no minimum inside the sampled volumes, saying which way it lies, and the other three are NaN there and when the fit fails outright.- Return type:
tuple of float
- equilibrium_volume(T)[source]¶
Volume per atom in cubic Angstrom that minimises the free energy.
- Parameters:
T (float or array of float) – temperature in K
- Returns:
clamped to the sampled range, with a warning, once the free-energy minimum leaves it; NaN wherever the fit failed
- Return type:
float or array of float
- extrapolate: bool = False¶
What to do once the free-energy minimum leaves the sampled volumes. The default clamps the volume to the nearest sampled end and reports the free energy there – a minimisation constrained to the volumes actually calculated.
Trueinstead returns the unconstrained minimum of the equation of state, which is extrapolating to reach it: smoother and further from anything that was computed. Either way theEosExtrapolationWarningfires.
- fixed_concentration: float¶
The fixed concentration of the phase.
- classmethod from_phonopy(name, fixed_concentration, phonopys, energies, **kwargs)[source]¶
Build a phase from live
Phonopyobjects, one per volume.Each object must already carry thermal properties, i.e. the caller has run
run_thermal_properties()and so has chosen the mesh, the statistics and the mode cutoff. The volume, both atom counts and the lowest sampled frequency are read off the objects.- Parameters:
name (str) – name of the phase
fixed_concentration (float) – concentration of the phase
phonopys (iterable of phonopy.Phonopy) – one per sampled volume
energies (iterable of float) – static energy of each object’s unit cell, in eV
**kwargs – forwarded to the constructor (
eos,min_frequency, …)
- Returns:
PhonopyQuasiHarmonicPhase
- helmholtz_free_energies(T)[source]¶
Free energy per atom of each of
sampled_volumes, in eV, at one temperature.Helmholtz because these are at fixed volume, one per sampled volume: this is the
F(V, T)curve thatline_free_energy()minimises over. Static plus vibrational, each normalised by its own atom count. The vibrational part is phonopy’s own mode sum, obtained by resetting the temperature on the storedThermalPropertiesand running it again.- Parameters:
T (float) – temperature in K, non-negative
- Returns:
one free energy per stable volume, ascending in volume
- Return type:
numpy.ndarray
- property line_concentration¶
- line_free_energy(T)[source]¶
Free energy per atom in eV, minimised over volume.
- Parameters:
T (float or array of float) – temperature in K
- Returns:
NaN wherever the equation-of-state fit failed; taken at the nearest sampled volume, with a warning, once the minimum leaves the sampled range
- Return type:
float or array of float
- property lowest_frequencies¶
Lowest mode of each sampled volume, in THz, in the order given.
Negative where a volume carries an imaginary branch; those below
min_frequencyare the ones excluded from the fit.
- max_temperature(upper=5000.0, tolerance=1.0)[source]¶
Highest temperature at which the equation of state still interpolates.
Above this the free energy is still returned, but the free-energy minimum has left the sampled range and the volume is clamped to the nearest end instead.
Thermal expansion is monotonic in temperature for a stable solid, so the equilibrium volume leaves the sampled range once and does not come back; this bisects for that crossing.
- Parameters:
upper (float) – temperature in K to bracket the search from above; returned unchanged if the fit still interpolates there
tolerance (float) – bracket width in K at which to stop
- Returns:
the ceiling in K, or NaN if the fit already extrapolates at
T = 0- Return type:
float
- min_frequency: float = -0.05¶
Volumes whose lowest mode falls below this, in THz, are treated as dynamically unstable and excluded from the fit. Slightly negative rather than zero because the acoustic branches at Gamma are numerically noisy in both directions.
- property sampled_volumes¶
Volumes per atom the equation of state is fitted through, ascending.
- thermal_properties: tuple¶
One phonopy
ThermalPropertiesper sampled volume, already run byrun_thermal_properties(). At least four dynamically stable ones are needed to fit the four equation-of-state parameters.
- property volumes_per_atom¶
volumesdivided byatoms_per_cell, in the order given.
- class landau.phases.RegularSolution(name, phases, num_coeffs=4, add_entropy=False)[source]¶
Bases:
PhaseA regular solution model phase that interpolates through a given set of line phases using Redlich-Kister polynomials.
Deprecated since version Use:
FastInterpolatingPhase(name, phases, interpolator=RedlichKister(num_coeffs))instead; removal in 2.0.- 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)[source]¶
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
- 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.
- class landau.phases.SlowInterpolatingPhase(name, phases, add_entropy=False, maximum_extrapolation=0, concentration_range=(0.0, 1.0), interpolator=None)[source]¶
Bases:
PhaseA 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)[source]¶
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
- concentration_range: tuple[float, float] = (0.0, 1.0)¶
- interpolator: Optional[ConcentrationInterpolator] = None¶
- maximum_extrapolation: float = 0¶
- phases: Iterable[AbstractLinePhase]¶
- 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)[source]¶
Bases:
FastInterpolatingPhaseFastInterpolatingPhase 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 viasurface_interpolator.fit()and returns fixed-T slices viaFittedSurface.slice_at(T). The inherited logit-Newton solver and the full semigrand/concentration API fromFastInterpolatingPhaseare reused unchanged.Training data: each line phase is sampled at
num_temperature_samplesevenly spaced temperatures overtemperature_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 whenadd_entropy=False(the usual case with calphy data).- Parameters:
surface_interpolator (
Optional[SurfaceInterpolator]) – ASurfaceInterpolatorthat fits the 2-D surface from flat (T, c, H) arrays and returns aFittedSurface. Required — there is no default; omitting it raisesTypeErrorat 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: Optional[SurfaceInterpolator] = None¶
- temperature_range: Optional[tuple] = None¶
- class landau.phases.TemperatureDependentLinePhase(name, fixed_concentration, temperatures, free_energies, interpolator=SGTE(nparam=3))[source]¶
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)[source]¶
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¶
- temperatures: Iterable[float]¶
Temperatures at which the free energy of the phase has been sampled.
landau.phases.pointdefects¶
- class landau.phases.pointdefects.AbstractPointDefectSublattice(name, sublattice, sublattice_fraction, defects)[source]¶
Bases:
ABCGroups together point defects that live on the same sublattice within a host structure and turns their excess potentials into the sublattice’s contribution to the semi-grand potential and concentration.
The per-site partition variables \(z_i = e^{-\beta[\phi_i]}\) are shared machinery; concrete subclasses differ only in how those are combined, via two hooks evaluated on \(s = \sum_i z_i\):
_site_log_partition()returns \(L(s)\) with the per-site semi-grand potential \(-k_B T\, L(s)\);_site_normalization()returns the denominator \(D(s)\) of the defect site fraction \(x_i = z_i / D(s)\).
The two are not independent: \(c = -\partial\phi/\partial(\Delta\mu)\) forces \(D(s) = 1 / L'(s)\), so a subclass must keep them consistent.
- defects: list[AbstractPointDefect]¶
- name: str¶
- sublattice: int¶
- sublattice_fraction: float¶
- class landau.phases.pointdefects.CappedPointDefectSublattice(name, sublattice, sublattice_fraction, defects, max_site_fraction)[source]¶
Bases:
AbstractPointDefectSublatticePoint defect sublattice whose total defect site fraction is capped at
max_site_fraction\(m\).A sublattice of \(N\) sites holds at most \(mN\) defects of all types together. A configuration with defects of types \(i_1, \dots, i_n\) on \(n\) distinct sites has weight \(\prod_k z_{i_k}\), with \(z_i = e^{-\beta[\phi_i]}\); summing over the \(\binom{N}{n}\) choices of sites and the types on each gives \(\binom{N}{n} s^n\) with \(s = \sum_i z_i\), so the sublattice partition function is
\[Z_N(s) = \sum_{n=0}^{\lfloor mN \rfloor} \binom{N}{n} s^n .\]Without the cap the sum runs to \(N\) and gives the exact \((1 + s)^N\). In the thermodynamic limit the sum is dominated by its largest term, so per site
\[L(s) = \lim_{N \to \infty} \frac{1}{N} \ln Z_N(s) = \max_{0 \le x \le m} \left[ H(x) + x \ln s \right],\]with \(H(x) = -x \ln x - (1 - x) \ln(1 - x)\). The unconstrained maximum \(x = s / (1 + s)\) is reachable up to \(s^* = m / (1 - m)\); beyond it the maximum sits at \(x = m\):
\[\begin{split}L(s) = \begin{cases} \ln(1 + s) & s \le s^* \\ H(m) + m \ln s & s > s^* \end{cases} \qquad D(s) = \begin{cases} 1 + s & s \le s^* \\ s / m & s > s^* \end{cases}\end{split}\]Below \(s^*\) this is
PointDefectSublattice; above it the sublattice is a line phase at total defect site fraction \(m\), which is split among the defects in proportion to their weights, \(x_i = z_i m / s\). \(L\) and \(L'\) are continuous at \(s^*\), \(L''\) is not, so the concentration is continuous but \(\partial c / \partial(\Delta\mu)\) jumps there. Since \(L\) is the maximum of \(H(x) + x \ln s\) over the restricted range \(x \le m\), it never exceeds the exact \(\ln(1 + s)\): the capped semi-grand potential is never below the exact one.- max_site_fraction: float¶
- class landau.phases.pointdefects.ConstantPointDefect(name, excess_energy, excess_entropy, excess_solutes)[source]¶
Bases:
AbstractPointDefectA point defect that adds a contribution to the free energy of a host lattice.
Excess energy and entropy are assumed to be
- excess_energy: float¶
- excess_entropy: float¶
- excess_solutes: float¶
- name: str¶
- class landau.phases.pointdefects.LowTemperatureExpansionSublattice(name, sublattice, sublattice_fraction, defects)[source]¶
Bases:
AbstractPointDefectSublatticePoint defect sublattice in the low-temperature (dilute) limit.
The leading term of the low-temperature expansion of
PointDefectSublatticereplaces \(\ln(1 + \sum_i z_i)\) with \(\sum_i z_i\) and drops the site-competition denominator, leaving the defect site fractions \(x_i = z_i\) independent and unnormalised. This is accurate while the defects are dilute (\(z_i \ll 1\), i.e. formation energies large compared to \(k_B T\)) and lets each defect be treated as an isolated, non-interacting excitation; away from that limit the populations are no longer bounded by site competition and the exact form should be used.
- class landau.phases.pointdefects.PointDefectSublattice(name, sublattice, sublattice_fraction, defects)[source]¶
Bases:
AbstractPointDefectSublatticeExact point defect sublattice with site competition.
Evaluates the full semi-grand potential per site, \(-k_B T \ln(1 + \sum_i z_i)\) with \(z_i = e^{-\beta[\phi_i]}\). The denominator \(1 + \sum_i z_i\) encodes site competition (one site holds one defect, so the site fractions \(x_i = z_i / (1 + \sum_{i'} z_{i'})\) obey \(\sum_i x_i \le 1\)).
- class landau.phases.pointdefects.PointDefectedPhase(name, line_phase, sublattices)[source]¶
Bases:
PhasePhase that combines any host phase and any number of point defects in it.
- line_phase: AbstractLinePhase¶
Underlying phase object of the host lattice.
- site_fractions(T, dmu)[source]¶
Defect site fractions \(x_i = z_i / D(s)\) on every sublattice.
Returns
{sublattice name: {defect name: x_i}}; each \(x_i\) is per site of its sublattice (multiply bysublattice_fractionfor per atom), with the shape ofTanddmubroadcast together. The values come from each sublattice’s own model and are not affected by the concentration clamp, so forLowTemperatureExpansionSublatticethey can exceed 1.
- sublattices: list[AbstractPointDefectSublattice]¶
Sublattices and their point defects.
landau.phases.quasiharmonic¶
Quasi-harmonic line phases evaluated directly from phonon thermal properties.
The free energy is computed, not fitted: PhonopyQuasiHarmonicPhase holds one
phonopy ThermalProperties per sampled volume
and evaluates
on demand at any temperature. Both steps are cheap – the vibrational part is a sum over modes, the minimisation an equation-of-state fit through the sampled volumes – so there is no temperature grid to choose and no interpolator to fit.
Nothing here recomputes a mode sum. ThermalProperties.temperatures is a plain
setter and run() recomputes, so the phase resets the temperature on the caller’s own
object and reads the result back; the statistics, the cutoff convention and the physical
constants are phonopy’s, chosen by the caller when they ran
run_thermal_properties().
- exception landau.phases.quasiharmonic.DynamicalInstabilityWarning[source]¶
Bases:
UserWarningA sampled volume carries imaginary modes and was dropped from the fit.
- exception landau.phases.quasiharmonic.EosExtrapolationWarning[source]¶
Bases:
UserWarningThermal expansion carried the equilibrium volume outside the sampled range.
- class landau.phases.quasiharmonic.PhonopyQuasiHarmonicPhase(name, fixed_concentration, thermal_properties, volumes, energies, atoms_per_cell, atoms_per_primitive_cell, eos=PolyFit(nparam=8, regularizer_strength=1e-08, enforce_curvature=False), min_frequency=-0.05, extrapolate=False)[source]¶
Bases:
AbstractLinePhaseA fixed-concentration phase whose free energy is evaluated from phonon spectra.
Give one phonopy
ThermalPropertiesper sampled volume, together with the volume and static energy of the cell each was computed for, or build the phase from livePhonopyobjects withfrom_phonopy(). At every requested temperature the free energy of each volume comes from phonopy’s mode sum, an equation of state is fitted through the results and its minimum is returned – one number per temperature, computed rather than interpolated, at any temperature the caller asks for.Compared with sampling the same calculation onto a grid and handing that to
TemperatureDependentLinePhase, this removes both the grid and the fit. On quasi-harmonic data the defaultSGTE(3)leaves residuals of several meV/atom (issue #427), and a shallow solid-solid transition converts one meV/atom into tens of kelvin.Statistics (
classical), the mode cutoff (cutoff_frequency) and the sampling mesh are the caller’s, fixed when they ranrun_thermal_properties(); this class does not second-guess them. It does resettemperatureson those objects and re-run()them – once at construction and again at every temperature asked of the phase – so theThermalPropertieshanded over are left holding whatever temperature was evaluated last. Pass copies if the caller still needs their own results.Primitive vs unit cell.
volumesandenergiesdescribe whatever cell was actually relaxed, while phonopy normalises a free energy per primitive cell. These differ whenever the unit cell is not primitive – phonopy’sprimitive_matrix="auto"reduces a cubic fcc cell by 4 and hcp/bcc by 2 – and pairing them without converting silently rescales every vibrational free energy by that factor. Both counts are therefore required and each part is normalised by its own before they are added.Two ways a quasi-harmonic fit degrades without saying so, and what happens here:
Dynamically unstable volumes. Imaginary modes are dropped by the mode sum rather than raised on, so a volume with unstable branches still returns a smooth, plausible free energy that then corrupts the equation-of-state fit every other volume feeds. Volumes whose lowest mode falls below
min_frequencyare excluded and reported throughlowest_frequencies, with aDynamicalInstabilityWarningat construction. See_lowest_frequency()for how that mode is recovered from aThermalProperties, which does not expose it.Past the sampled volumes the minimisation is constrained, not extrapolated. Once thermal expansion carries the free-energy minimum above the largest volume sampled, the equation of state would have to extrapolate to reach it, and its error there is not bounded by anything the fit knows. So the volume is clamped to the nearest sampled end and the free energy reported there – the minimum over the volumes that were actually calculated – with an
EosExtrapolationWarningsaying so. The constrained and unconstrained minima coincide at the crossing, so the reported curve is continuous; above it the phase understates the expansion and therefore overstates the free energy.max_temperature()reports where that starts andcheck_equation_of_state()shows it; sampling wider volumes is the only way to push it up, andextrapolatefollows the fit out instead.- atoms_per_primitive_cell: int¶
Number of atoms in the primitive cell the phonons were computed on; phonopy reports a free energy per primitive cell.
- check_equation_of_state(T=300.0, samples=100, margin=0.05, plot_error=False)[source]¶
Plot the volume minimisation at one temperature, to see what it is doing.
Draws three things on the current axes (or, with
plot_error, how far the fit misses each sampled volume): the free energy of every sampled volume, the equation of state fitted through them, and the minimumline_free_energy()reports. They have to agree for the reported number to mean anything, and once the minimum has left the sampled volumes the marker sits pinned to the edge of the shaded range while the curve keeps falling past it – which is exactly the extrapolation being declined.- Parameters:
T (float) – temperature in K
samples (int) – number of points along the plotted curve
margin (float) – fraction of the sampled span to extend the curve past each end, so a minimum just outside the data is still visible
plot_error (bool) – if True, plot the residual of each sampled volume against the fitted equation of state instead of the free energies themselves. This is the second approximation underneath the reported free energy, so the residual is what says whether the fit has run out of freedom to follow the data – on the scale that matters, meV/atom. A systematic sign pattern rather than scatter means shape the fit cannot take
- energies: tuple¶
Static (electronic) energy of that same cell, in eV.
- property energies_per_atom¶
energiesdivided byatoms_per_cell, in the order given.
- eos: str | Interpolator = PolyFit(nparam=8, regularizer_strength=1e-08, enforce_curvature=False)¶
How to fit
F(V)before minimising it over volume.Either one of landau’s own interpolators, fitted through the sampled volumes, or one of the closed-form equations of state
"vinet","birch_murnaghan"or"murnaghan"passed tophonopy.qha.eos.get_eos().This fit is a second approximation underneath the temperature interpolation the class removes, and the closed forms are not accurate enough for it to be ignored: measured on fcc Cu over nine volumes (
benchmarks/qha_eos_forms.py),"vinet"leaves 4.3 meV/atom at 1200 K and"birch_murnaghan"3.0, against 0.1 for the default here. All three closed forms carry four parameters, so on a wide volume set they run out of freedom long before the data runs out of shape.The parameter count is capped at one fewer than there are stable volumes, since a polynomial through as many points as it has coefficients interpolates exactly and its minimum stops meaning anything; with the four volumes this class needs at minimum it is a cubic. The cap covers an interpolator that picks its own count as well, applied once it has picked:
PolyFit("auto")selects under an L1 penalty on a degree-ten basis, which is underdetermined at these sample counts and comes back with roughly as many parameters as there are volumes.A fixed count rather than a selected one because the selection would be made per temperature, and it moves: on the nine-volume fcc Cu set it flips between six and eight parameters several times over 114-122 K, each flip a step of tens of microelectronvolts per atom in
F(T)and a few times 1e-3 cubic Angstrom inV(T)where nothing physical happens – against under two microelectronvolts of genuine variation across the same window (benchmarks/qha_eos_forms.py). Steps in the reported free energy are the one thingline_free_energy()must not invent, sincecalc_phase_diagramreads them as transitions.An interpolator is fitted in a centred, scaled volume coordinate and its minimum is located inside the sampled range only – a polynomial has no useful behaviour outside its data – so
extrapolateis incompatible with one.
- eos_parameters(T)[source]¶
Equation-of-state parameters at one temperature.
Fits
self.eosthrough the per-atom free energies ofsampled_volumes.- Parameters:
T (float) – temperature in K
- Returns:
(E_0, B_0, B'_0, V_0)– the minimum free energy in eV per atom, the bulk modulus in eV per cubic Angstrom, its pressure derivative, and the equilibrium volume in cubic Angstrom per atom. The last is+-infwhen the fit has no minimum inside the sampled volumes, saying which way it lies, and the other three are NaN there and when the fit fails outright.- Return type:
tuple of float
- equilibrium_volume(T)[source]¶
Volume per atom in cubic Angstrom that minimises the free energy.
- Parameters:
T (float or array of float) – temperature in K
- Returns:
clamped to the sampled range, with a warning, once the free-energy minimum leaves it; NaN wherever the fit failed
- Return type:
float or array of float
- extrapolate: bool = False¶
What to do once the free-energy minimum leaves the sampled volumes. The default clamps the volume to the nearest sampled end and reports the free energy there – a minimisation constrained to the volumes actually calculated.
Trueinstead returns the unconstrained minimum of the equation of state, which is extrapolating to reach it: smoother and further from anything that was computed. Either way theEosExtrapolationWarningfires.
- fixed_concentration: float¶
The fixed concentration of the phase.
- classmethod from_phonopy(name, fixed_concentration, phonopys, energies, **kwargs)[source]¶
Build a phase from live
Phonopyobjects, one per volume.Each object must already carry thermal properties, i.e. the caller has run
run_thermal_properties()and so has chosen the mesh, the statistics and the mode cutoff. The volume, both atom counts and the lowest sampled frequency are read off the objects.- Parameters:
name (str) – name of the phase
fixed_concentration (float) – concentration of the phase
phonopys (iterable of phonopy.Phonopy) – one per sampled volume
energies (iterable of float) – static energy of each object’s unit cell, in eV
**kwargs – forwarded to the constructor (
eos,min_frequency, …)
- Returns:
PhonopyQuasiHarmonicPhase
- helmholtz_free_energies(T)[source]¶
Free energy per atom of each of
sampled_volumes, in eV, at one temperature.Helmholtz because these are at fixed volume, one per sampled volume: this is the
F(V, T)curve thatline_free_energy()minimises over. Static plus vibrational, each normalised by its own atom count. The vibrational part is phonopy’s own mode sum, obtained by resetting the temperature on the storedThermalPropertiesand running it again.- Parameters:
T (float) – temperature in K, non-negative
- Returns:
one free energy per stable volume, ascending in volume
- Return type:
numpy.ndarray
- property line_concentration¶
- line_free_energy(T)[source]¶
Free energy per atom in eV, minimised over volume.
- Parameters:
T (float or array of float) – temperature in K
- Returns:
NaN wherever the equation-of-state fit failed; taken at the nearest sampled volume, with a warning, once the minimum leaves the sampled range
- Return type:
float or array of float
- property lowest_frequencies¶
Lowest mode of each sampled volume, in THz, in the order given.
Negative where a volume carries an imaginary branch; those below
min_frequencyare the ones excluded from the fit.
- max_temperature(upper=5000.0, tolerance=1.0)[source]¶
Highest temperature at which the equation of state still interpolates.
Above this the free energy is still returned, but the free-energy minimum has left the sampled range and the volume is clamped to the nearest end instead.
Thermal expansion is monotonic in temperature for a stable solid, so the equilibrium volume leaves the sampled range once and does not come back; this bisects for that crossing.
- Parameters:
upper (float) – temperature in K to bracket the search from above; returned unchanged if the fit still interpolates there
tolerance (float) – bracket width in K at which to stop
- Returns:
the ceiling in K, or NaN if the fit already extrapolates at
T = 0- Return type:
float
- min_frequency: float = -0.05¶
Volumes whose lowest mode falls below this, in THz, are treated as dynamically unstable and excluded from the fit. Slightly negative rather than zero because the acoustic branches at Gamma are numerically noisy in both directions.
- property sampled_volumes¶
Volumes per atom the equation of state is fitted through, ascending.
- thermal_properties: tuple¶
One phonopy
ThermalPropertiesper sampled volume, already run byrun_thermal_properties(). At least four dynamically stable ones are needed to fit the four equation-of-state parameters.
- property volumes_per_atom¶
volumesdivided byatoms_per_cell, in the order given.