NAMD parsing

Parsers for extracting alchemical data from NAMD output files.

The parsers featured in this module are constructed to properly parse NAMD .fepout output files containing derivatives of the Hamiltonian and FEP (BAR) data. See the NAMD documentation for the theoretical backdrop and implementation details.

If you wish to use BAR on FEP data, be sure to provide the .fepout file from both the forward and reverse transformations.

After calling extract_u_nk() on the forward and reverse work values, these dataframes can be combined into one:

# replace zeroes in initial dataframe with nan
u_nk_fwd.replace(0, np.nan, inplace=True)
# replace the nan values with the reverse dataframe --
# this should not overwrite any of the fwd work values
u_nk_fwd[u_nk_fwd.isnull()] = u_nk_rev
# replace remaining nan values back to zero
u_nk_fwd.replace(np.nan, 0, inplace=True)
# sort final dataframe by `fep-lambda` (as opposed to `timestep`)
u_nk = u_nk_fwd.sort_index(level=u_nk_fwd.index.names[1:])

The fep-lambda index states at which lambda this particular frame was sampled, whereas the columns are the evaluations of the Hamiltonian (or the potential energy U) at other lambdas (sometimes called “foreign lambdas”).

API Reference

This submodule includes these parsing functions:

alchemlyb.parsing.namd.extract_u_nk(fep_files, T)

Return reduced potentials u_nk from NAMD fepout file(s).

Parameters

  • fep_file (str or list of str) –

    Path to fepout file(s) to extract data from. These are sorted by filename, not including the path, prior to processing, using natural-sort. This way, filenames including numbers without leading zeros are handled intuitively.

    Windows may be split across files, or more than one window may be present in a given file. Windows without footer lines (which may be in a different file than the respective header lines) will raise an error. This means that while windows may have been interrupted and restarted, they must be complete. Lambda values are expected to increase or decrease monotonically, and match between header and footer of each window.

  • T (float) – Temperature in Kelvin at which the simulation was sampled.

Returns

u_nk – Potential energy for each alchemical state (k) for each frame (n).

Return type

DataFrame

Note

If the number of forward and backward samples in a given window are different, the extra sample(s) will be discarded. This is typically zero or one sample.

Changed in version 0.5.0: The scipy.constants is used for parsers instead of the constants used by the corresponding MD engine.

Changed in version 0.6.0: Support for Interleaved Double-Wide Sampling files added, with various robustness checks.

fep_files can now be a list of filenames.

alchemlyb.parsing.namd.extract(fep_files, T)

Return reduced potentials u_nk from NAMD fepout file(s).

Parameters

  • fep_file (str or list of str) –

    Path to fepout file(s) to extract data from. These are sorted by filename, not including the path, prior to processing, using natural-sort. This way, filenames including numbers without leading zeros are handled intuitively.

    Windows may be split across files, or more than one window may be present in a given file. Windows without footer lines (which may be in a different file than the respective header lines) will raise an error. This means that while windows may have been interrupted and restarted, they must be complete. Lambda values are expected to increase or decrease monotonically, and match between header and footer of each window.

  • T (float) – Temperature in Kelvin at which the simulation was sampled.

Returns

A dictionary with keys of ‘u_nk’, which is a pandas DataFrame of potential energy for each alchemical state (k) for each frame (n).

Return type

Dict

Note

If the number of forward and backward samples in a given window are different, the extra sample(s) will be discarded. This is typically zero or one sample.

New in version 1.0.0.