macrostate_distribution

This module analyzes and manipulates macrostate probability distributions generated by FEASST flat-histogram simulations. See more information on FEASST at https://doi.org/10.18434/M3S095

class macrostate_distribution.MacrostateDistribution(file_name, macrostate_header='state', ln_prob_header='ln_prob', comment='#')

Contains macrostates, the natural logarithm of the macrostate probability and other per-macrostate quantities generated by a FEASST flat histogram simulation. This may include canonical ensemble averages and blocks.

__init__(file_name, macrostate_header='state', ln_prob_header='ln_prob', comment='#')

Constructs all the necessary attributes for a MacrostateDistribution.

Parameters:

• file_name (str) – The name of the csv file which stores per-macrostate quantities. If None, do not read a file, and instead use set_dataframe later.

• macrostate_header (str) – In the grand canonical ensemble, the macrostates are the number of particles. This is the header for that column in a pandas data frame.

• ln_prob_header (str) – The natural logarithm of the probability of observing each macrostate.

>>> from pyfeasst import macrostate_distribution
>>> import pandas as pd
>>> lnpi = macrostate_distribution.MacrostateDistribution(file_name='../../tests/lnpi.csv')

set_dataframe(dataframe, normalize=True)

Set the dataframe.

Parameters:

normalize (bool) – normalize the ln_prob after setting the dataframe.

concat_dataframe(dataframe, add_prefix)

Concatenate dataframe (e.g., for average energy per macrostate).

dataframe()

Return the dataframe.

set_macrostates(macrostates)

Set the macrostates in the dataframe.

macrostates()

Return the macrostates.

set_ln_prob(ln_prob)

Set the natural logarithm of the probability.

ln_prob()

Return the natural logarithm of the probability.

set_minimum_smoothing(minimum_smoothing=10)

During the search for the minimum, the number of macrostates that the minimum must be smaller than in both directions. Increase this if the data is noisey or if there are undulations in the ln_prob.

minimum_smoothing()

Return the minimum smoothing.

normalize(*args)

Set the sum of the probabilities of a series to one.

If no arguments provided, use the internal ln_prob. If ln_prob is provided as a series, return the normalized series.

average_macrostate()

Return the average macrostate.

>>> from pyfeasst import macrostate_distribution
>>> lnpi = macrostate_distribution.MacrostateDistribution(file_name='../../tests/lnpi.csv')
>>> round(float(lnpi.average_macrostate()), 8)
437.68207872

ensemble_average(header)

Return the grand canonical ensemble average of the data present in header, for example, canonical averages.

>>> import pandas as pd
>>> from pyfeasst import macrostate_distribution
>>> lnpi = macrostate_distribution.MacrostateDistribution(file_name='../../tests/lnpi.csv')
>>> round(float(lnpi.ensemble_average(header='energy')), 8)
-2701.39300435

plot(show=False, label=None, fontsize=16)

Create a matplotlib.pyplot plot of the ln_prob.

minimums()

Return the minimums of the ln_prob.

>>> from pyfeasst import macrostate_distribution
>>> lnpi = macrostate_distribution.MacrostateDistribution(file_name='../../tests/lnpi.csv')
>>> mins = lnpi.minimums()
>>> len(mins)
1
>>> int(mins.values[0])
150

split(minimum=-1)

Return two MacrostateDistribution by splitting at the last minimum in the ln_prob. Both MacrostateDistribution will contain the minimum.

Parameters:

minimum (int) – If -1, find the last minimum. Otherwise, supply it.

>>> from pyfeasst import macrostate_distribution
>>> lnpi = macrostate_distribution.MacrostateDistribution(file_name='../../tests/lnpi.csv')
>>> vapor, liquid = lnpi.split()
>>> round(float(vapor.average_macrostate()), 8)
1.4212647
>>> round(float(vapor.ensemble_average('energy')), 8)
-0.04911667
>>> round(float(liquid.average_macrostate()), 8)
437.68207872
>>> round(float(liquid.ensemble_average('energy')), 8)
-2701.39300435

reweight(delta_beta_mu, inplace=False)

Reweight the ln_prob by delta_beta_mu. If inplace, replace current ln_prob with the reweighted ones.

>>> from pyfeasst import macrostate_distribution
>>> lnpi = macrostate_distribution.MacrostateDistribution(file_name='../../tests/lnpi.csv')
>>> reweight = lnpi.reweight(-1)
>>> round(float(reweight.dataframe()['ln_prob'][0]), 8)
-0.50108687
>>> reweight = lnpi.reweight(1.5)
>>> round(float(reweight.dataframe()['ln_prob'][0]), 8)
-811.74010444

reweight_to_macrostate(target_macrostate, delta_beta_mu_guess=0, tol=1e-06)

Reweight ln_prob and return the delta_beta_mu for an average target_macrostate.

Parameters:

• delta_beta_mu_guess (float) – Provide a guess for delta_beta_mu which brings the ln_prob closer to equilibrium.

• tol (float) – Tolerance of minimization algorithm.

>>> from pyfeasst import macrostate_distribution
>>> lnpi = macrostate_distribution.MacrostateDistribution(file_name='../../tests/lnpi.csv')
>>> round(float(lnpi.reweight_to_macrostate(target_macrostate=10)), 8)
-0.32218376
>>> round(float(lnpi.average_macrostate()), 5)
10.0

equilibrium(delta_beta_mu_guess=-0.1, tol=1e-06)

Reweight ln_prob to equilibrium and return the delta_beta_mu of the equilibrium condition.

Parameters:

• delta_beta_mu_guess (float) – Provide a guess for delta_beta_mu which brings the ln_prob closer to equilibrium.

• tol (float) – Tolerance of minimization algorithm.

>>> from pyfeasst import macrostate_distribution
>>> lnpi = macrostate_distribution.MacrostateDistribution(file_name='../../tests/lnpi.csv')
>>> round(float(lnpi.equilibrium(delta_beta_mu_guess=-1, tol=1e-4)), 8)
-0.31323799
>>> vapor, liquid = lnpi.split()
>>> round(float(vapor.average_macrostate()/8**3), 8)
0.00200035
>>> round(float(liquid.average_macrostate()/8**3), 8)
0.84304803

macrostate_distribution.splice(windows, extra_overlap=0)

Return a MacrostateDistribution that is spliced together from multiple MacrostateDistribution. Each MacrostateDistribution must overlap by atleast one macrostate with its neighbor. If macrostates overlap by more than one (extra_overlap), simply drop the macrostates in the upper MacrostateDistribution.

>>> from pyfeasst import macrostate_distribution
>>> lnpis=list()
>>> for i in range(4):
...     lnpis.append(macrostate_distribution.MacrostateDistribution(
...         file_name='../../tests/lnpin'+str(i)+'.csv'))
>>> lnpi = macrostate_distribution.splice(lnpis)
>>> lnpi.set_minimum_smoothing(50)
>>> round(float(lnpi.average_macrostate()), 8)
596.29289902
>>> len(lnpi.minimums())
0
>>> round(float(lnpi.equilibrium(delta_beta_mu_guess=-1.5)), 8)
-1.2768126
>>> vapor, liquid = lnpi.split()
>>> round(float(vapor.average_macrostate()), 8)
0.03172081
>>> round(float(liquid.average_macrostate()), 8)
523.35530815

macrostate_distribution.splice_files(prefix, suffix, ln_prob_header=None, extra_overlap=0)

As above, Return a MacrostateDistribution that is spliced together. But this time, provide the prefix and suffix of the filenames and search the files.

>>> from pyfeasst import macrostate_distribution
>>> lnpi = macrostate_distribution.splice_files(prefix='../../tests/lj_lnpin', suffix='.txt')
>>> round(float(lnpi.equilibrium()), 8)
-0.31402411
>>> vapor, liquid = lnpi.split()
>>> round(float(vapor.average_macrostate()/8**3), 8)
0.00199501
>>> round(float(liquid.average_macrostate()/8**3), 8)
0.84318346

macrostate_distribution.read_appended(file_name, num_states)

Read an appended ln_prob file, and return a list of pairs of MacrostateDistributions and parameters from a required first line comment.

>>> from pyfeasst import macrostate_distribution
>>> dists = macrostate_distribution.read_appended(
...     '../../tests/lj_lnpi_appended.txt', num_states=2)
>>> dists[10][1]['cpu_hours']
0.117464
>>> round(float(dists[10][0].ln_prob()[0]), 8)
-4.68014742

macrostate_distribution.splice_collection_matrix(prefix, suffix, use_soft=False)

Splice collection matrix of files and return a MacrostateDistribution with ln_prob computed from the P_up and P_down matrix elements.

Parameters:

use_soft (bool) – use soft_min and soft_max to trim the file before concatenation.

>>> from pyfeasst import macrostate_distribution
>>> lnp = macrostate_distribution.splice_collection_matrix(prefix="../../tests/lj_crit",
...                                                        suffix=".txt")
>>> round(float(lnp.ln_prob()[0]), 8)
-12.27534328