Ensemble averages (ensembles)

Classes:

xlnPiWrapper(shape[, rec_name, n_name, ...])	Wraps lnPi objects with xarray functionality
xGrandCanonical(parent)	DataArray accessor to Grand Canonical properties from lnPi
xCanonical(parent)	Canonical ensemble properties

Functions:

xr_name([long_name, name, unstack])

Decorator to add name, longname to xarray output

class lnpy.ensembles.xlnPiWrapper(shape, rec_name='sample', n_name='n', lnz_name='lnz', comp_name='component', phase_name='phase')

Bases: object

Wraps lnPi objects with xarray functionality

Most likely, this shouldn’t be accessed by the user.

lnpy.ensembles.xr_name(long_name=None, name=None, unstack=True, **kws)

Decorator to add name, longname to xarray output

class lnpy.ensembles.xGrandCanonical(parent)

Bases: object

DataArray accessor to Grand Canonical properties from lnPi

This class is primarily interacted with through the attributes xge attached to lnPiMasked and lnPiCollection.

Attributes:

ncoords	Particle number coordinates.
ncoords_tot	Total number of particles coordinates
dims_n	Dimension(s) corresponding to number of particles
dims_lnz	Dimension corresponding to values of \(\ln z\)
dims_comp	Dimension of component number
dims_state	Dimensions corresponding to 'state variables'
dims_rec	Dimensions for replicates
beta	Inverse temperature \(\beta = 1 / (k_{\rm B} T)\)
volume	System volume \(V\).
betamu	Scaled chemical potential \(\beta \mu\)
lnz	Log of activity \(\ln z`\)
pi_norm	Normalized value of \(\Pi_{\rm norm}(N) = \Pi(N) / \sum_N \Pi(N)\)
pi_sum	Sum of unnormalized \(\Pi(N)\)
lnpi_norm	\(\ln \Pi_{\rm norm}(N)\).
nvec	Average number of particles of each component \(\overline{{\bf N}}\)
ntot	Average total number of particles \(\overline{N}\)
molfrac	Average molfrac for each components \({\bf x} = \overline{{\bf N}} / N\)
nvec_var	Variance in particle number \({\rm var}\, \bf{N}\)
ntot_var	Variance in total number of particles \({\rm var}\, N\)
dens	Density of each component \({\bf \rho} = \overline{{\bf N}} / V\)
dens_tot	Total density \(\overline{N} / V\)
PE	Potential energy \(\overline{PE}\)
mask_stable	Masks are True where values are stable.
PE_n	Potential energy per particle \(\overline{PE}/\overline{N}\)
betaG	Scaled Gibbs free energy \(\beta G = \sum_i \beta \mu_i \overline{N}_i\).
betaG_n	Scaled Gibbs free energy per particle \(\beta G / \overline{N}\).

Methods:

lnpi([fill_value])	xarray.DataArray view of \(\ln \Pi(N)\)
mean_pi(x[, allow_extra_kws])	Calculates \(\overline{x} = \sum_N \Pi_{\rm norm}(N) x(N)\)
var_pi(x[, y])	Calculate Grand Canonical variance from canonical properties.
pipe(func, *args, **kwargs)	Apply function to self
max()	\(\max_N \ln \Pi(N)\)
lnpi_max([fill_value, add_n_coords])	Maximum value of \(\max_N \ln \Pi(N, ...)\)
pi_norm_max([add_n_coords])	Maximum value \(\max_N \Pi_{\rm norm}(N, meta)\)
edge_distance(ref)	Distance from argmax(lnPi) to endpoint
edge_distance_val(ref[, val, max_frac])	Calculate min distance from where self.pi_norm > val to edge
betaOmega([lnpi_zero])	Scaled grand potential \(\beta \Omega\).
betaF_alt(betaF_can[, correction])	Alternate scaled Helmholtz free energy \(\beta \overline{F}\).
betaOmega_n([lnpi_zero])	Grand potential per particle \(\beta \Omega / \overline{N}\)
betapV([lnpi_zero])	\(\beta p V = - \beta \Omega\)
Z([lnpi_zero])	Compressibility factor \(\beta p / \rho\)
pressure([lnpi_zero])	Pressure \(p = -\Omega / V\)
table([keys, default_keys, ref, ...])	Create xarray.Dataset of calculated properties.
betaF([lnpi_zero])	Scaled Helmholtz free energy \(\beta F = \beta \Omega + \beta G\).
betaF_n([lnpi_zero])	Scaled Helmholtz free energy per particle \(\beta F / \overline{N}\).
betaE([ndim])	Scaled total energy \(\beta E = \beta \overline{PE} + \beta \overline{KE}\).
betaE_n([ndim])	Scaled total energy per particle \(\beta E / \overline{N}\).
S([lnpi_zero, ndim])	Scaled entropy \(S / k_{\rm B} = \beta E - \beta F\).
S_n([lnpi_zero, ndim])	Scaled entropy per particle \(S / (N k_{\rm B})\).

property ncoords

Particle number coordinates.

property ncoords_tot

Total number of particles coordinates

property dims_n

Dimension(s) corresponding to number of particles

property dims_lnz

Dimension corresponding to values of \(\ln z\)

property dims_comp

Dimension of component number

property dims_state

Dimensions corresponding to ‘state variables’

property dims_rec

Dimensions for replicates

property beta

Inverse temperature \(\beta = 1 / (k_{\rm B} T)\)

property volume

System volume \(V\).

betamu

Scaled chemical potential \(\beta \mu\)

property lnz

Log of activity \(\ln z`\)

lnpi(fill_value=None)

xarray.DataArray view of \(\ln \Pi(N)\)

Notes

This value is always in ‘stacked’ form. You must manually unstack it.

property pi_norm

Normalized value of \(\Pi_{\rm norm}(N) = \Pi(N) / \sum_N \Pi(N)\)

property pi_sum

Sum of unnormalized \(\Pi(N)\)

property lnpi_norm

\(\ln \Pi_{\rm norm}(N)\).

mean_pi(x, allow_extra_kws=True, **kwargs)

Calculates \(\overline{x} = \sum_N \Pi_{\rm norm}(N) x(N)\)

Parameters:

• x (ndarray, DataArray, callable(), or str) – If callable, should have form x = x(self, **kwargs). If string, then set x = self.parent.extra_kws[x]. Otherwise, should be an array of same shape as single lnPi. If x (or result of callable) is not a DataArray, try to convert it to one.

• *args, **kwargs – Extra arguments to x if passing callable

Returns:

ave (DataArray) – x can be an array or a callable of the form f(self, *args, **kwargs)

var_pi(x, y=None, **kwargs)

Calculate Grand Canonical variance from canonical properties.

Given x(N) and y(N), calculate

\[{\rm var}(x, y) = \overline{(x - \overline{x}) (y - \overline{y})}\]

x and y can be arrays, or callables, in which case: x = x(self, **kwargs)

See also

\(mean_pi\)

pipe(func, *args, **kwargs)

Apply function to self

nvec

Average number of particles of each component \(\overline{{\bf N}}\)

ntot

Average total number of particles \(\overline{N}\)

property molfrac

Average molfrac for each components \({\bf x} = \overline{{\bf N}} / N\)

nvec_var

Variance in particle number \({\rm var}\, \bf{N}\)

ntot_var

Variance in total number of particles \({\rm var}\, N\)

property dens

Density of each component \({\bf \rho} = \overline{{\bf N}} / V\)

property dens_tot

Total density \(\overline{N} / V\)

max()

\(\max_N \ln \Pi(N)\)

lnpi_max(fill_value=None, add_n_coords=True)

Maximum value of \(\max_N \ln \Pi(N, ...)\)

pi_norm_max(add_n_coords=True)

Maximum value \(\max_N \Pi_{\rm norm}(N, meta)\)

edge_distance(ref)

Distance from argmax(lnPi) to endpoint

edge_distance_val(ref, val=None, max_frac=None)

Calculate min distance from where self.pi_norm > val to edge

Parameters:

• ref (lnPiMasked) – reference object to consider.

• val (float)

• max_frac (bool, optional) – if not None, val = max_frac * self.pi_norm.max(self.dims_n)

betaOmega(lnpi_zero=None)

Scaled grand potential \(\beta \Omega\).

Parameters:

lnpi_zero (float or None) – if None, lnpi_zero = self.data.ravel()[0]

PE

Potential energy \(\overline{PE}\)

betaF_alt(betaF_can, correction=True)

Alternate scaled Helmholtz free energy \(\beta \overline{F}\).

Calculated using

\[\beta \overline{F} = \sum_N [\Pi(N) \beta F(N) + C(N)]\]

Parameters:

• betaF_can (array-like) – Value of \(F(N)\)

• correction (bool, default True) – If True, \(C(N) = \ln \Pi(N) `. Otherwise, :math:`C=0\).

betaOmega_n(lnpi_zero=None)

Grand potential per particle \(\beta \Omega / \overline{N}\)

betapV(lnpi_zero=None)

\(\beta p V = - \beta \Omega\)

mask_stable

Masks are True where values are stable. Only works for unstacked data.

Z(lnpi_zero=None)

Compressibility factor \(\beta p / \rho\)

pressure(lnpi_zero=None)

Pressure \(p = -\Omega / V\)

property PE_n

Potential energy per particle \(\overline{PE}/\overline{N}\)

table(keys=None, default_keys=('nvec', 'betapV', 'PE_n'), ref=None, mask_stable=False, dim_to_suffix=None)

Create xarray.Dataset of calculated properties.

Parameters:

• keys (sequence of str, optional) – keys of attributes or methods of self to include in output

• default_keys (sequence of str, optional) – Default keys to consider.

• ref (lnPiMasked, optional) – If calculating edge_distastance, need a reference lnPiMasked object.

• mask_stable (bool, default False) – If True, remove any unstable values

• dim_to_suffix (sequence of hashable, optional) – dimensions to remove from output. These are instead added as suffix to variable names

Returns:

ds (Dataset) – Containing all the calculated properties in a single object

Notes

The results can be easily convert to a pandas.DataFrame using ds.to_frame()

property betaG

Scaled Gibbs free energy \(\beta G = \sum_i \beta \mu_i \overline{N}_i\).

property betaG_n

Scaled Gibbs free energy per particle \(\beta G / \overline{N}\).

betaF(lnpi_zero=None)

Scaled Helmholtz free energy \(\beta F = \beta \Omega + \beta G\).

betaF_n(lnpi_zero=None)

Scaled Helmholtz free energy per particle \(\beta F / \overline{N}\).

betaE(ndim=3)

Scaled total energy \(\beta E = \beta \overline{PE} + \beta \overline{KE}\).

betaE_n(ndim=3)

Scaled total energy per particle \(\beta E / \overline{N}\).

S(lnpi_zero=None, ndim=3)

Scaled entropy \(S / k_{\rm B} = \beta E - \beta F\).

S_n(lnpi_zero=None, ndim=3)

Scaled entropy per particle \(S / (N k_{\rm B})\).

class lnpy.ensembles.xCanonical(parent)

Bases: object

Canonical ensemble properties

Parameters:

parent (lnPiMasked)

Methods:

lnpi([fill_value])	DataArray view of \(\ln Pi(N)\)
betaF([lnpi_zero])	Scaled Helmholtz free energy \(\beta F\)
betaF_n([lnpi_zero])	Scaled Helmholtz free energy per particle \(\beta F / N\)
betaE([ndim])	Scaled total energy \(\beta E = \beta PE + \beta KE\)
betaE_n([ndim])	Scaled total energy per particle
S([ndim, lnpi_zero])	Entropy \(S / k_{\rm B}\)
S_n([ndim, lnpi_zero])	Entropy per particle \(S / (N k_{\rm B})\)
betamu([lnpi_zero])	Scaled chemical potential \(\beta \mu\)
betaOmega([lnpi_zero])	Scaled Grand Potential \(\beta \Omega\)
betaOmega_n([lnpi_zero])	Scaled Grand potential per particle, \(\beta\Omega / N\)
betapV([lnpi_zero])	\(\beta p V = -\beta \Omega\)
Z([lnpi_zero])	Compressibility \(Z = \beta p / \rho = pV / (k_{\rm B} T)\)
pressure([lnpi_zero])	Pressure \(p = -\Omega / V\)
table([keys, default_keys, dim_to_suffix])	Create Dataset from attributes/methods of self

Attributes:

ncoords	Coordinate vector dims_n
nvec	Number of particles for each components \({\bf N}\)
ntot	Total number of particles \(N\)
PE	Internal Energy \(PE\)
PE_n	Internal energy per particle \(PE / N\)
dens	Density \(\rho = N / V\)

lnpi(fill_value=None)

DataArray view of \(\ln Pi(N)\)

ncoords

Coordinate vector dims_n

property nvec

Number of particles for each components \({\bf N}\)

ntot

Total number of particles \(N\)

betaF(lnpi_zero=None)

Scaled Helmholtz free energy \(\beta F\)

betaF_n(lnpi_zero=None)

Scaled Helmholtz free energy per particle \(\beta F / N\)

PE

Internal Energy \(PE\)

property PE_n

Internal energy per particle \(PE / N\)

betaE(ndim=3)

Scaled total energy \(\beta E = \beta PE + \beta KE\)

betaE_n(ndim=3)

Scaled total energy per particle

S(ndim=3, lnpi_zero=None)

Entropy \(S / k_{\rm B}\)

S_n(ndim=3, lnpi_zero=None)

Entropy per particle \(S / (N k_{\rm B})\)

betamu(lnpi_zero=None)

Scaled chemical potential \(\beta \mu\)

property dens

Density \(\rho = N / V\)

betaOmega(lnpi_zero=None)

Scaled Grand Potential \(\beta \Omega\)

betaOmega_n(lnpi_zero=None)

Scaled Grand potential per particle, \(\beta\Omega / N\)

betapV(lnpi_zero=None)

\(\beta p V = -\beta \Omega\)

Z(lnpi_zero=None)

Compressibility \(Z = \beta p / \rho = pV / (k_{\rm B} T)\)

pressure(lnpi_zero=None)

Pressure \(p = -\Omega / V\)

table(keys=None, default_keys=('betamu', 'betapV', 'PE_n', 'betaF_n'), dim_to_suffix=None)

Create Dataset from attributes/methods of self

Parameters:

• keys (sequence of str) – Names of attributes/methods to access

• default_keys (sequence of str) – Default keys to access.

• dim_to_suffix (str, sequence of str, optional) – If passed, convert dimensions in dim_to_suffix from dimensions in output to suffixes to variable names

Returns:

table (Dataset)