Inverse temperature expansion of macrostate distribution (lnpi)

This is used to extrapolate, in inverse temperature \(\beta = (k_{\rm B} T)^{-1}\), the macrostate distribution function \(\ln\Pi\) from transition matrix Monte Carlo simulations.

See Macrostate distribution extrapolation for example usage.

Classes:

lnPi_func_central(beta)	Special case of u_func_central.
lnPi_func_raw(beta)	Raw moments version.
lnPiDataCallback(lnPi0, mu, dims_n, dims_comp)	Class to handle metadata callbacks for lnPi data.

Functions:

factory_derivatives([name, n, d, xalpha, ...])	Expansion for ln(Pi/Pi_0) (ignore bad parts of stuff).
factory_extrapmodel_lnPi(beta, data, *[, ...])	Factory function to create Extrapolation model for beta expansion.

class thermoextrap.lnpi.lnPi_func_central(beta)

Bases: SymFuncBase

Special case of u_func_central.

For lnPi, have:

\[ \begin{align}\begin{aligned}\newcommand{\ave}[1]{\langle #1 \rangle}\\(\ln \Pi)' = \frac{d \ln \Pi}{d \beta} = \mu N - \ave{u} + \ave{u - \mu N}_{\rm GC}\end{aligned}\end{align} \]

where \(\ave{}\) and \(\ave{}_{\rm GC}\) are the canonical and grand canonical (GC) ensemble averages. We ignore the GC average term, as it does not depend on N. Note that this is not necessarily the case for molecular systems. So, the first derivative of this function is thermoextrap.beta.u_func_central(). We consider only a correction of the form:

\[(\ln\Pi)_{\text{energy}} = \ln\Pi - \beta \mu N = \ln Q - \ln \Xi\]

where \(Q\text{ and }\Xi\) are the canonical and GC partition functions, respectively. thus,

\[\begin{split}\begin{align*} (\ln\Pi)_{\text{energy}}' &= - U \\ (\ln\Pi)_{\text{energy}}'' &= -U' \\ &\,\,\vdots \end{align*}\end{split}\]

Methods:

deriv_args()	Symbol arguments of function.
fdiff([argindex])	Derivative of function.
eval(beta)	Evaluate function.

classmethod deriv_args()

Symbol arguments of function.

This is used by Data class to create a ‘lambdfied’ callable function.

See also

sympy.utilities.lambdify.lambdify

fdiff(argindex=1)

Derivative of function. This will be used by thermoextrap.models.SymDerivBase.

classmethod eval(beta)

Evaluate function.

We use the convention of passing in beta=’None’ to evaluate the function to an indexed variable.

class thermoextrap.lnpi.lnPi_func_raw(beta)

Bases: SymFuncBase

Raw moments version.

Methods:

deriv_args()	Symbol arguments of function.
fdiff([argindex])	Derivative of function.
eval(beta)	Evaluate function.

classmethod deriv_args()

Symbol arguments of function.

This is used by Data class to create a ‘lambdfied’ callable function.

See also

sympy.utilities.lambdify.lambdify

fdiff(argindex=1)

Derivative of function. This will be used by thermoextrap.models.SymDerivBase.

classmethod eval(beta)

Evaluate function.

We use the convention of passing in beta=’None’ to evaluate the function to an indexed variable.

thermoextrap.lnpi.factory_derivatives(name='lnPi', n=None, d=None, xalpha=False, central=False, expand=True, post_func=None)

Expansion for ln(Pi/Pi_0) (ignore bad parts of stuff).

Parameters:

• name (str, default 'lnPi') – If name is ‘lnPi’, then get derivatives of lnPi. Otherwise, get derivative object for general X.

• n (int) – Order of moment.

• d (int) – Order of derivative of x.

• xalpha (bool, default False) – Flag whether u depends on variable alpha.

• central (bool) – If True, Use central moments. Otherwise, use raw moments.

• expand (bool) – If True, apply expand()

• post_func (str or callable()) – Transformation of base function. For example, post_fuc = -sympy.log is equivalent to passing minus_log=True If a string, then apply the following standard functions

  • minus_log : post_func = -sympy.log

  • pow_i : post_func = lambda f: pow(f, i). E.g., pow_2 => pow(f, 2)

Returns:

Derivatives

See also

thermoextrap.beta.factory_derivatives

class thermoextrap.lnpi.lnPiDataCallback(lnPi0, mu, dims_n, dims_comp, ncoords=_Nothing.NOTHING, allow_resample=False)

Bases: DataCallbackABC

Class to handle metadata callbacks for lnPi data.

Parameters:

• lnPi0 (DataArray) – Reference value of lnPi.

• mu (DataArray) – Value of chemical potential. Must have dimension dims_comp.

• dims_n (hashable or sequence of hashable) – Dimension(s) for number of particle(s). That is, the dimensions of lnPi0 corresponding to particle number.

• dims_comp (hashable) – Dimension corresponding to components.

• ncoords (DataArray, optional) – Count of number of particles for given particle number (vector) and component. Must have dimensions dims_comp and dims_n.

• allow_resample (bool, default False) – If True, allow simplified resampling of lnPi0 data.

Attributes:

lnPi0	lnPi data
mu	Chemical potential
dims_n	Dimensions for particle number
dims_comp	Dimensions for component
ncoords	Particle number coordinates
allow_resample	Flag to allow/disallow resampling of lnPi0.
mudotN	Dot product of self.mu and self.ncoords, reduces along self.dims_comp.

Methods:

check(data)	Perform any consistency checks between self and data.
resample(data[, meta_kws])	Resample lnPi0 data.
derivs_args(data, derivs_args)	Adjust derivs args from data class.

lnPi0

lnPi data

mu

Chemical potential

dims_n

Dimensions for particle number

dims_comp

Dimensions for component

ncoords

Particle number coordinates

allow_resample

Flag to allow/disallow resampling of lnPi0.

check(data)

Perform any consistency checks between self and data.

mudotN

Dot product of self.mu and self.ncoords, reduces along self.dims_comp.

resample(data, meta_kws=None, **kws)

Resample lnPi0 data.

derivs_args(data, derivs_args)

Adjust derivs args from data class.

should return a tuple

thermoextrap.lnpi.factory_extrapmodel_lnPi(beta, data, *, central=None, order=None, alpha_name='beta', derivatives=None, post_func=None, derivatives_kws=None)

Factory function to create Extrapolation model for beta expansion.

Parameters:

• beta (float) – reference value of inverse temperature

• data (object) – Data object. Should include lnPiDataCallback object as well

• order (int, optional) – maximum order. If not specified, default to data.order + 1

• central (bool) – If True, Use central moments. Otherwise, use raw moments.

• post_func (str or callable()) – Transformation of base function. For example, post_fuc = -sympy.log is equivalent to passing minus_log=True If a string, then apply the following standard functions

  • minus_log : post_func = -sympy.log

  • pow_i : post_func = lambda f: pow(f, i). E.g., pow_2 => pow(f, 2)

• alpha_name (str, default 'beta') – name of expansion parameter

• derivatives (thermoextrap.models.Derivatives, optional) – Derivatives object. If not passed, construct derivatives using thermoextrap.lnpi.factory_derivatives().

• derivates_kws (mapping, optional) – Optional parameters to thermoextrap.lnpi.factory_derivatives().

Returns:

extrapmodel (ExtrapModel)

See also

thermoextrap.lnpi.factory_derivatives, ExtrapModel