WallGo.freeEnergy.FreeEnergy

class FreeEnergy(effectivePotential, startingTemperature, startingPhaseLocationGuess, initialInterpolationPointCount=1000)[source]

Bases: InterpolatableFunction

Describes properties of a local effective potential minimum. This is used to keep track of a minimum with respect to the temperature. By definition, the free energy density of a phase equals the value of the effective potential in its local minimum.

Initialize a FreeEnergy object

Parameters:

  • effectivePotential (EffectivePotential) – EffectivePotential object used to compute the free energy.

  • startingTemperature (float) – Temperature at which the interpolation of the effective potential starts.

  • startingPhaseLocationGuess (Fields) – Approximate position of the phase at startingTemperature.

  • initialInterpolationPointCount (int, optional) – Initial number of points sampled for the interpolation. The default is 1000.

__init__(effectivePotential, startingTemperature, startingPhaseLocationGuess, initialInterpolationPointCount=1000)[source]

Initialize a FreeEnergy object

Parameters:

  • effectivePotential (EffectivePotential) – EffectivePotential object used to compute the free energy.

  • startingTemperature (float) – Temperature at which the interpolation of the effective potential starts.

  • startingPhaseLocationGuess (Fields) – Approximate position of the phase at startingTemperature.

  • initialInterpolationPointCount (int, optional) – Initial number of points sampled for the interpolation. The default is 1000.

Return type:

None

Methods

__init__(effectivePotential, ...[, ...])

Initialize a FreeEnergy object

constructInterpolationFromArray(...)

Constructs the interpolation table directly from arrays of temperatures, field values, and potential values, bypassing the phase tracing process.

derivative(x[, order, bUseInterpolation])

Override of InterpolatableFunction.derivative() function.

disableAdaptiveInterpolation()

Disables adaptive interpolation functionality.

enableAdaptiveInterpolation()

Enables adaptive interpolation functionality.

evaluate(x[, bUseInterpolatedValues])

Evaluate the free energy.

evaluateInterpolation(x)

Evaluates our interpolated function at input x

extendInterpolationTable(newMin, newMax, ...)

Extend our interpolation table.

hasInterpolation()

Returns true if we have an interpolation table.

interpolationRangeMax()

Get upper limit of our current interpolation table.

interpolationRangeMin()

Get lower limit of our current interpolation table.

newInterpolationTable(xMin, xMax, numberOfPoints)

Creates a new interpolation table over given range.

newInterpolationTableFromValues(x, fx[, ...])

Like initializeInterpolationTable but takes in precomputed function values 'fx'

numPoints()

How many input points in our interpolation table.

readInterpolationTable(fileToRead)

Reads precalculated values from a file and does cubic interpolation.

scheduleForInterpolation(x, fx)

Add x, f(x) pairs to our pending interpolation table update

setExtrapolationType(extrapolationTypeLower, ...)

Changes extrapolation behavior, default is NONE.

tracePhase(TMin, TMax, dT[, rTol, spinodal, ...])

Traces minimum of potential

writeInterpolationTable(outputFileName)

Write our interpolation table to file.
constructInterpolationFromArray(freeEnergyArrays, dT)[source]

Constructs the interpolation table directly from arrays of temperatures, field values, and potential values, bypassing the phase tracing process.

Parameters:

  • freeEnergyArrays (FreeEnergyArrays) – Object containing arrays of the temperature, minimum and value of the free energy.

  • dT (float) – Small step in temperature used in derivatives, used here to ensure endpoints of temperature range not exceeded when taking derivatives later.

Return type:

None

derivative(x, order=1, bUseInterpolation=True)[source]

Override of InterpolatableFunction.derivative() function. Specifies accuracy based on our internal variables and puts the results in FreeEnergyValueType format. Otherwise similar to the parent function.

Parameters:

  • x (list[float] or np.ndarray) – Points where the free energy will be evaluated.

  • bUseInterpolatedValues (bool, optional) – Whether or not to use interpolation to evaluate the function. The default is True.

  • order (int)

  • bUseInterpolation (bool)

Returns:

FreeEnergyValueType object containing the value of the free energy’s derivative and the field value that minimizes the potential.

Return type:

FreeEnergyValueType

disableAdaptiveInterpolation()

Disables adaptive interpolation functionality.

Return type:

None

enableAdaptiveInterpolation()

Enables adaptive interpolation functionality. Will clear internal work arrays.

Return type:

None

evaluate(x, bUseInterpolatedValues=True)[source]

Evaluate the free energy.

Parameters:

  • x (list[float] or np.ndarray) – Points where the free energy will be evaluated.

  • bUseInterpolatedValues (bool, optional) – Whether or not to use interpolation to evaluate the function. The default is True.

Returns:

FreeEnergyValueType object containing the value of the free energy and the field value that minimizes the potential.

Return type:

FreeEnergyValueType

evaluateInterpolation(x)

Evaluates our interpolated function at input x

Parameters:

x (list[float] | ndarray | float)

Return type:

ndarray

extendInterpolationTable(newMin, newMax, pointsMin, pointsMax)

Extend our interpolation table. NB: This will reset internally accumulated data of adaptive interpolation.

Parameters:

  • newMin (float) – New minimal value at which the interpolation starts.

  • newMax (float) – New maximal value at which the interpolation starts.

  • pointsMin (int) – Minimal number of points to use.

  • pointsMax (int) – Maximal number of points to use.

Return type:

None

hasInterpolation()

Returns true if we have an interpolation table.

Return type:

bool

interpolationRangeMax()

Get upper limit of our current interpolation table.

Return type:

float

interpolationRangeMin()

Get lower limit of our current interpolation table.

Return type:

float

newInterpolationTable(xMin, xMax, numberOfPoints)

Creates a new interpolation table over given range. This will purge any existing interpolation information.

Parameters:

  • xMin (float) – Minimal interpolation point.

  • xMax (float) – Maximal interpolation point.

  • numberOfPoints (int) – Number of points to use in the interpolation.

Return type:

None

newInterpolationTableFromValues(x, fx, derivatives=None, splineDegree=3)

Like initializeInterpolationTable but takes in precomputed function values ‘fx’

Parameters:

  • x (list[float] or np.ndarray) – Points where the function was evaluated.

  • fx (list[float | np.ndarray] or np.ndarray) – Value of the function at x.

  • derivatives (list[outputType] | None) – List containing the values of each derivative of the function at x. If None, computes the derivatives from the interpolated spline.

  • splineDegree (int)

Return type:

None

numPoints()

How many input points in our interpolation table.

Return type:

int

readInterpolationTable(fileToRead)

Reads precalculated values from a file and does cubic interpolation. Each line in the file must be of form x f(x). For vector valued functions: x f1(x) f2(x)

Parameters:

fileToRead (str) – Path of the file where the interpolation table is stored.

Return type:

None

scheduleForInterpolation(x, fx)

Add x, f(x) pairs to our pending interpolation table update

Parameters:

  • x (list[float] or np.ndarray) – Points where the function was evaluated.

  • fx (list[float | np.ndarray] or np.ndarray) – Value of the function at x.

Return type:

None

setExtrapolationType(extrapolationTypeLower, extrapolationTypeUpper)

Changes extrapolation behavior, default is NONE. See the enum class EExtrapolationType. NOTE: This will effectively prevent adaptive updates to the interpolation table. NOTE 2: Calling this function will force a rebuild of our interpolation table.

Parameters:

  • extrapolationTypeLower (EExtrapolationType) – Extrapolation type when below the interpolation range.

  • extrapolationTypeUpper (EExtrapolationType) – Extrapolation type when above the interpolation range.

Return type:

None

tracePhase(TMin, TMax, dT, rTol=1e-06, spinodal=True, paranoid=True, phaseTracerFirstStep=None, interpolationDegree=1)[source]

Traces minimum of potential

Finds the potential minimum for the range over which it exists. Takes a temperature derivative of the minimsation condition, and solves for \(\phi_i^\text{min}(T)\) as an initial value problem

\[\frac{\partial^2 V^\text{eff}}{\partial \phi_i \partial \phi_j}\bigg|_{\phi=\phi^\text{min}} \frac{\partial \phi^\text{min}_j}{\partial T} + \frac{\partial^2 V^\text{eff}}{\partial \phi_i \partial T}\bigg|_{\phi=\phi^\text{min}} = 0,\]

starting from a solution at the starting temperature. It uses scipy.integrate.solve_ivp() to solve the problem. Stops if a mass squared goes through zero.

Parameters:

  • TMin (float) – Minimal temperature at which the phase tracing will be done.

  • TMax (float) – Maximal temperature at which the phase tracing will be done.

  • dT (float) – Maximal temperature step size used by the phase tracer.

  • rTol (float, optional) – Relative tolerance of the phase tracing. The default is 1e-6.

  • spinodal (bool, optional) – If True, stop tracing if a mass squared turns negative. The default is True.

  • paranoid (bool, optional) – If True, re-solve minimum after every step. The default is True.

  • phaseTracerFirstStep (float or None, optional) – If a float, this gives the starting step size in units of the maximum step size dT. If None then uses the initial step size algorithm of scipy.integrate.solve_ivp. Default is None

  • interpolationDegree (int, optional) – Degree of the splines used in FreeEnergy to interpolate the potential and its derivatives. Default is 1.

Return type:

None

writeInterpolationTable(outputFileName)

Write our interpolation table to file.

Parameters:

outputFileName (str) – Name of the file where the interpolation table will be written.

Return type:

None