LAMMPS Parsing

Parsers for extracting alchemical data from LAMMPS output files.

Use Cases for extract_* Functions

For clarity, we would like to distinguish the difference between \(\lambda\) and \(\lambda'\). We refer to \(\lambda\) as the potential scaling of the equilibrated system, so that when this value is changed, the system undergoes another equilibration step. On the other hand, \(\lambda'\) is the value used to scale the potentials for the configurations of the system equilibrated for \(\lambda\). The value of \(\lambda'\) is used in two instances. First, in thermodynamic integration (TI), values of \(\lambda'\) that are very close to \(\lambda\) can be used to calculate the derivative. This is needed because LAMMPS does not compute explicit derivatives; although one should check whether explicit expressions can be derived, this is not possible for changes of \(\lambda'\) in the soft Lennard-Jones (LJ) potential.

The extract_* functions in this module are designed to handle different aspects of alchemical free energy calculations. Below is an overview of their use cases:

extract_u_nk

• Purpose: Extracts reduced potentials (u_nk) for each alchemical state (k) for each frame (n).

• Use Case: Suitable for MBAR (Multistate Bennett Acceptance Ratio) analysis, where the reduced potentials are required to compute free energy differences across multiple states.

• Input Requirements: Requires columns for timestep, lambda values, potential energy, and optionally volume (for NPT ensemble).

extract_dHdl

• Purpose: Extracts the derivative of the Hamiltonian with respect to lambda (dH/dλ) for each alchemical state.

• Use Case: Used in Thermodynamic Integration (TI) to compute free energy differences by integrating dH/dλ over lambda.

• Input Requirements: Requires columns for timestep, lambda values, lambda derivatives, and derivative values for different components.

extract_H

• Purpose: Extracts the Hamiltonian (potential energy) for each alchemical state.

• Use Case: Provides the raw potential energy data for analysis or validation purposes.

• Input Requirements: Requires columns for timestep, lambda values, and potential energy.

extract_u_nk_from_u_n

• Purpose: Constructs u_nk from files containing u_n given a separable dependence on lambda.

• Use Case: Useful when the dependence of the potential energy on lambda can be expressed as a separable function. This function is provided to reduce the IO cost required if all \(\lambda'\) must be computed during a simulation.

• Input Requirements: Requires columns for lambda, potential energy, and optionally volume (for NPT ensemble).

File Format Requirements

The parsers featured in this module are constructed to parse LAMMPS output files output using the fix ave/time command, containing data for given potential energy values (an approximation of the Hamiltonian) at specified values of \(\lambda\) and \(\lambda'\), \(U_{\lambda,\lambda'}\). Note that in LAMMPS, fix adapt/fep changes \(\lambda\) and compute fep changes \(\lambda'\).

Given the broad flexibility and unstandardized format of LAMMPS output files a user should consider the way they write the output of their simulation. A user may find the package generate_alchemical_lammps_inputs useful to generate their input scripts. Input files should be space-separated text files produced by LAMMPS fix ave/time command, typically with the following characteristics:

File Structure: - Space-separated columns with no header - Lines starting with ‘#’ are treated as comments and ignored - Each row represents a single timestep/frame - Compressed files (.gz, .bz2) are automatically handled

Essential Columns: The specific column indices depend on the extraction function, but generally include:

For MBAR extraction (extract_u_nk): - Column 0: Timestep/iteration number - Columns 1-2: Lambda values (λ, λ’) defining the alchemical state - Column 3: Potential energy U at the current lambda state - Column 4: Potential energy difference dU between lambda states - Column 6: Volume (for NPT ensemble, optional)

For TI extraction (extract_dHdl): - Column 0: Timestep/iteration number - Column 1: Lambda value λ - Column 2: Lambda derivative dλ/dt - Columns 5,7: Derivative values ∂H/∂λ for different components - Additional columns may contain volume, pressure, etc.

Example File Content:

# LAMMPS output from fix ave/time
# Time Lambda1 Lambda2 U dU Volume dHdl1 dHdl2
100   0.0     0.0     -1234.5  0.0      12345.6  -23.4   15.2
200   0.0     0.1     -1235.1  -0.6     12346.1  -24.1   15.8
300   0.0     0.2     -1236.2  -1.7     12347.0  -25.3   16.5
...

Filename Conventions: - Filenames should encode lambda values for proper parsing: - Format: prefix_λ1_λ2_suffix.ext (using underscores as separators) - Examples: mbar_charge_0.0_1.0.txt, fep_vdw_0.5_0.75.dat - Lambda values are extracted from specific positions in the filename - Compression extensions (.gz, .bz2) are automatically removed during parsing

Supported Units: - LAMMPS unit systems: “real”, “lj”, “metal”, “si”, “cgs”, “electron”, “micro”, “nano”

Ensemble Support: - NVT: Standard canonical ensemble (no volume correction) - NPT: Isothermal-isobaric ensemble (requires volume column and pressure specification)

Added in version 2.4.1.

alchemlyb.parsing.lammps.beta_from_units(T: float, units: str) → float

Output value of beta from temperature and units.

Supported types are: cgs, electron, lj, metal, micro, nano, real, si

Parameters:

• T (float) – Temperature that the system was run with

• units (str) – LAMMPS style unit

Returns:

beta – Value of beta used to scale the potential energy.

Return type:

float

Raises:

• ValueError – If unit string is not recognized.

• .. versionadded: – 2.4.1:

alchemlyb.parsing.lammps.energy_from_units(units: str) → float

Output conversion factor for pressure * volume to LAMMPS energy units

Supported types are: cgs, electron, lj, metal, micro, nano, real, si

Parameters:

units (str) – LAMMPS style unit

Returns:

conversion_factor – Conversion factor for pressure * volume to LAMMPS energy units

Return type:

float

Raises:

• ValueError – If unit string is not recognized.

• .. versionadded: – 2.4.1:

alchemlyb.parsing.lammps.tuple_from_filename(filename: str, separator: str = '_', indices: list[int] = [2, 3], prec: int = 4) → tuple[float, ...]

Pull a tuple representing the lambda values used, as defined by the filenames.

This function extracts lambda values from structured filenames that contain numerical lambda values separated by a specified separator character. The function is designed to work with various filename formats as long as they follow a consistent pattern.

Examples with different indices configurations:

Default indices=[2, 3], separator=”_”:

• fep_0.0_1.0.txt → (0.0, 1.0)

• simulation_data_0.25_0.75_output.dat → (0.25, 0.75)

• lammps_run_0.5_1.0.log.gz → (0.5, 1.0)

• path/to/file_prefix_0.1_0.9_suffix.txt.bz2 → (0.1, 0.9)

indices=[0, 1], separator=”_”:

• 0.0_1.0_fep.txt → (0.0, 1.0)

• 0.25_0.75_simulation.dat → (0.25, 0.75)

indices=[1, 3], separator=”_”:

• run_0.0_data_1.0_output.txt → (0.0, 1.0)

• sim_0.25_info_0.75_result.dat → (0.25, 0.75)

indices=[0, 2], separator=”-“:

• 0.0-data-1.0.txt → (0.0, 1.0)

• 0.25-sim-0.75.dat → (0.25, 0.75)

indices=[-2, -1], separator=”_” (negative indexing):

• prefix_data_0.0_1.0.txt → (0.0, 1.0)

• long_filename_with_many_parts_0.25_0.75.dat → (0.25, 0.75)

The function automatically handles compressed files (.gz, .bz2) by removing the compression extensions before parsing.

This module is compatible with the standard outputs of generate_alchemical_lammps_inputs.

Parameters:

• filename (str) – Filename and path. The filename (excluding path and file extension) should contain numerical lambda values separated by the specified separator.

• separator (str, default="_") – Separator used to breakup the filename. The choice in indices is dependent on this choice.

• indices (list, default=[2, 3]) – Indices used to pull \(\lambda\) and \(\lambda'\) from the filename components after splitting by separator. Supports both positive and negative indexing.

• prec (int, default=4) – Number of decimal points in the output.

Returns:

Tuple of lambda values (\(\lambda\), \(\lambda'\))

Return type:

tuple[float]

Raises:

• ValueError – If the specified indices cannot be converted to float values.

• .. versionadded: – 2.4.1:

alchemlyb.parsing.lammps.lambda_from_filename(filename: str, separator: str = '_', index: int = -1, prec: int = 4) → float

Pull the \(\lambda'\) value, as defined by the filenames.

Here \(\lambda'\) is the scaling value applied to a configuration that is equilibrated to a different value of \(\lambda\).

Parameters:

• filename (str) – Filename and path

• separator (str, default="_") – Separator used to breakup the filename. The choice in index is dependent on this choice.

• index (int, default=-1) – Index used to pull \(\lambda'\)

• prec (int, default=4) – Number of decimal points in the output.

Returns:

• float – Lambda prime value

• .. versionadded:: 2.4.1

alchemlyb.parsing.lammps.get_bar_lambdas(fep_files: str | list[str], indices: list[int] = [2, 3], prec: int = 4, force: bool = False) → tuple[list[float], list[tuple[float, ...]], float | None]

Retrieves all lambda values from FEP filenames.

Parameters:

• fep_files (str or list of str) – Path(s) to fepout files to extract data from.

• indices (list[int], default=[2,3]) – In provided file names, using underscore as a separator, these indices mark the part of the filename containing the lambda information. If three values, implies a value of lambda2 is present. See tuple_from_filename() for details on how indices are used to extract lambda values.

• prec (int, default=4) – Number of decimal places defined used in round() function.

• force (bool, default=False) – If True the dataframe will be created, even if not all lambda and lambda prime combinations are available.

Returns:

• lambda_values (list) – List of tuples lambda values contained in the file.

• lambda_pairs (list) – List of tuples containing two floats, lambda and lambda’.

• lambda2 (float) – Value of lambda2 that is held constant.

• .. versionadded:: 2.5.0

alchemlyb.parsing.lammps.extract_u_nk_from_u_n(fep_files: str | list[str], T: float, column_lambda: int, column_U: int, column_U_cross: int, dependence: ~collections.abc.Callable[[float], float] = <function <lambda>>, index: int = -1, units: str = 'real', prec: int = 4, ensemble: str = 'nvt', pressure: float | None = None, column_volume: int = 4) → DataFrame

Produce u_nk from files containing u_n given a separable dependence on lambda.

Parameters:

• fep_files (str or list) – If not a list, a str representing the path to fepout file(s) to extract data from. Filenames and paths are aggregated using glob. For example, “/path/to/files/something_*.txt”.

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

• column_lambda (int) – Indices for columns (file column number minus one) representing the lambda at which the system is equilibrated

• column_U (int) – Index for the column (file column number minus one) representing the potential energy of the system.

• column_U_cross (int) – Index for the column (file column number minus one) representing the potential energy of the cross interactions between the solute and solvent.

• dependence (func, default=`lambda x : (x)`) – Dependence of changing variable on the potential energy, which must be separable.

• index (int, default=-1) – In provided file names, using underscore as a separator, these indices mark the part of the filename containing the lambda information for alchemlyb.parsing.lambda_from_filename(). If column_lambda2 != None this list should be of length three, where the last value represents the invariant lambda.

• units (str, default="real") – Unit system used in LAMMPS calculation. Currently supported: “cgs”, “electron”, “lj”, “metal”, “micro”, “nano”, “real”, “si”

• prec (int, default=4) – Number of decimal places defined used in round() function.

• ensemble (str, default="nvt") – Ensemble from which the given data was generated. Either “nvt” or “npt” is supported where values from NVT are unaltered, while those from NPT are corrected

• pressure (float, default=None) – The pressure of the system in the NPT ensemble in units of energy / volume, where the units of energy and volume are as recorded in the LAMMPS dump file.

• column_volume (int, default=4) – The column for the volume in a LAMMPS dump file.

Returns:

• u_nk_df (pandas.Dataframe) – Dataframe of potential energy for each alchemical state (k) for each frame (n). Note that the units for timestamps are not considered in the calculation.

  Attributes

  • temperature in K

  • energy unit in kT

• .. versionadded:: 2.4.1

alchemlyb.parsing.lammps.extract_u_nk(fep_files: str | list[str], T: float, columns_lambda1: list[int] = [1, 2], column_dU: int = 4, column_U: int = 3, column_lambda2: int | None = None, indices: list[int] = [1, 2], units: str = 'real', vdw_lambda: int = 1, ensemble: str = 'nvt', pressure: float | None = None, column_volume: int = 6, prec: int = 4, force: bool = False, tol: float | None = None) → DataFrame

Return reduced potentials u_nk from LAMMPS dump file(s).

Each file is imported as a data frame where the columns kept are either:

[0, columns_lambda1[0] columns_lambda1[1], column_U, column_dU]

or if columns_lambda2 is not None:

[0, columns_lambda1[0] columns_lambda1[1], column_lambda2, column_U, column_dU]

If the simulation took place in the NPT ensemble, column_volume is appended to the end of this list.

Parameters:

• fep_files (str or list) –

  If not a list of filenames, represents the path to fepout file(s) to extract data from. Filenames and paths are aggregated using glob. For example, “/path/to/files/something_*_*.txt”.

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

• columns_lambda1 (list[int], default=[1,2]) – Indices for columns (column number minus one) representing (1) the lambda at which the system is equilibrated and (2) the lambda used in the computation of the potential energy.

• column_dU (int, default=4) – Index for the column (column number minus one) representing the difference in potential energy between lambda states

• column_U (int, default=3) – Index for the column (column number minus one) representing the potential energy

• column_lambda2 (int, default=None) – Index for column (column number minus one) for the unchanging value of lambda for another potential. If None then we do not expect two lambda values being varied.

• indices (list[int], default=[1,2]) – In provided file names, using underscore as a separator, these indices mark the part of the filename containing the lambda information for alchemlyb.parsing.get_bar_lambdas(). If column_lambda2 != None this list should be of length three, where the last value represents the invariant lambda.

• units (str, default="real") – Unit system used in LAMMPS calculation. Currently supported: “cgs”, “electron”, “lj”, “metal”, “micro”, “nano”, “real”, “si”

• vdw_lambda (int, default=1) – In the case that column_lambda2 is not None, this integer represents which lambda represents vdw interactions.

• ensemble (str, default="nvt") – Ensemble from which the given data was generated. Either “nvt” or “npt” is supported where values from NVT are unaltered, while those from NPT are corrected

• pressure (float, default=None) – The pressure of the system in the NPT ensemble in units of energy / volume, where the units of energy and volume are as recorded in the LAMMPS dump file.

• column_volume (int, default=6) – The column for the volume in a LAMMPS dump file.

• prec (int, default=4) – Number of decimal places defined used in round() function.

• force (bool, default=False) – If True the dataframe will be created, even if not all lambda and lambda prime combinations are available.

• tol (float, default=None) – Tolerance in checking that the difference between lambda and lambda’ states is zero. If None, this tolerance is set to np.finfo(float).eps. Take care in increasing this value! It’s more likely that something is wrong with your column indexing.

• Results

• -------

• u_nk_df (pandas.Dataframe) –

  Dataframe of potential energy for each alchemical state (k) for each frame (n). Note that the units for timestamps are not considered in the calculation.

  Attributes

  • temperature in K

  • energy unit in kT

• versionadded: (..) – 2.4.1:

alchemlyb.parsing.lammps.extract_dHdl_from_u_n(fep_files: str | list[str], T: float, column_lambda: int | None = None, column_u_cross: int | None = None, dependence: ~collections.abc.Callable[[float], float] = <function <lambda>>, units: str = 'real', prec: int = 4) → DataFrame

Produce dHdl dataframe from separated contributions of the potential energy.

Each file is imported as a dataframe where the columns are:

[0, column_lambda, column_solvent, column_solute, column_cross]

Parameters:

• fep_files (str or list) –

  If not a list, represents a path to fepout file(s) to extract data from. Filenames and paths are aggregated using glob. For example, “/path/to/files/something_*.txt”.

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

• column_lambda (int, default=None) – Indices for columns (file column number minus one) representing the lambda at which the system is equilibrated

• column_u_cross (int, default=None) – Index for the column (file column number minus one) representing the cross interaction potential energy of the system

• dependence (func, default=`lambda x : (1/x)`) – Transform of lambda needed to convert the potential energy into the derivative of the potential energy with respect to lambda, which must be separable. For example, for the LJ potential U = eps * f(sig, r), dU/deps = f(sig, r), so we need a dependence function of 1/eps to convert the potential energy to the derivative with respect to eps.

• units (str, default="real") – Unit system used in LAMMPS calculation. Currently supported: “cgs”, “electron”, “lj”, “metal”, “micro”, “nano”, “real”, “si”

• prec (int, default=4) – Number of decimal places defined used in round() function.

• Results

• -------

• dHdl (pandas.Dataframe) –

  Dataframe of the derivative for the potential energy for each alchemical state (k) for each frame (n). Note that the units for timestamps are not considered in the calculation.

  Attributes

  • temperature in K or dimensionless

  • energy unit in kT

• versionadded: (..) – 2.4.1:

alchemlyb.parsing.lammps.extract_dHdl(fep_files: str | list[str], T: float, column_lambda1: int = 1, column_dlambda1: int = 2, column_lambda2: int | None = None, columns_derivative: list[int] = [8, 7], vdw_lambda: int = 1, units: str = 'real', prec: int = 4) → DataFrame

Return reduced potentials dHdl from LAMMPS dump file(s).

Each file is imported as a data frame where the columns kept are either:

[0, column_lambda, column_dlambda1, columns_derivative[0], columns_derivative[1]]

or if columns_lambda2 is not None:

[
    0, column_lambda, column_dlambda1, column_lambda2, column_dlambda2,
    columns_derivative[0], columns_derivative[1],
]

Parameters:

• fep_files (str or list) –

  If not a list, represents the path to fepout file(s) to extract data from. Filenames and paths are aggregated using glob. For example, “/path/to/files/something_*_*.txt”.

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

• column_lambda1 (int, default=1) – Index for column (column number minus one) representing the lambda at which the system is equilibrated.

• column_dlambda1 (int, default=2) – Index for column (column number minus one) for the change in lambda.

• column_lambda2 (int, default=None) – Index for column (column number minus one) for a second value of lambda. If this array is None then we do not expect two lambda values.

• columns_derivative (list[int], default=[8, 7]) – Indices for columns (column number minus one) representing the the forward and backward derivative respectively.

• vdw_lambda (int, default=1) – In the case that column_lambda2 is not None, this integer represents which lambda represents vdw interactions.

• units (str, default="real") – Unit system used in LAMMPS calculation. Currently supported: “cgs”, “electron”, “lj”, “metal”, “micro”, “nano”, “real”, “si”

• prec (int, default=4) – Number of decimal places defined used in round() function.

• Results

• -------

• dHdl (pandas.Dataframe) –

  Dataframe of the derivative for the potential energy for each alchemical state (k) for each frame (n). Note that the units for timestamps are not considered in the calculation.

  Attributes

  • temperature in K or dimensionless

  • energy unit in kT

• versionadded: (..) – 2.4.1:

alchemlyb.parsing.lammps.extract_H(fep_files: str | list[str], T: float, column_lambda1: int = 1, column_pe: int = 5, column_lambda2: int | None = None, units: str = 'real', ensemble: str = 'nvt', pressure: float | None = None, column_volume: int = 6) → DataFrame

Return reduced potentials Hamiltonian from LAMMPS dump file(s).

Each file is imported as a data frame where the columns kept are either:

[0, column_lambda, column_dlambda1, columns_derivative[0], columns_derivative[1]]

or if columns_lambda2 is not None:

[
    0, column_lambda, column_dlambda1, column_lambda2, column_dlambda2,
    columns_derivative1[0], columns_derivative1[1]
]

Parameters:

• fep_files (str or list) –

  If not a list, represents the path to fepout file(s) to extract data from. Filenames and paths are aggregated using glob. For example, “/path/to/files/something_*_*.txt”.

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

• column_lambda1 (int, default=1) – Index for column (column number minus one) representing the lambda at which the system is equilibrated.

• column_pe (int, default=5) – Index for column (column number minus one) representing the potential energy of the system.

• column_lambda2 (int, default=None) – Index for column (column number minus one) for a second value of lambda. If this array is None then we do not expect two lambda values.

• units (str, default="real") – Unit system used in LAMMPS calculation. Currently supported: “cgs”, “electron”, “lj”, “metal”, “micro”, “nano”, “real”, “si”

• ensemble (str, default="nvt") – Ensemble from which the given data was generated. Either “nvt” or “npt” is supported where values from NVT are unaltered, while those from NPT are corrected

• pressure (float, default=None) – The pressure of the system in the NPT ensemble in units of energy / volume, where the units of energy and volume are as recorded in the LAMMPS dump file.

• column_volume (int, default=6) – The column for the volume in a LAMMPS dump file.

• Results

• -------

• H (pandas.Dataframe) –

  Dataframe of potential energy for each alchemical state (k) for each frame (n). Note that the units for timestamps are not considered in the calculation.

  Attributes

  • temperature in K or dimensionless

  • energy unit in kT

• versionadded: (..) – 2.4.1:

API Reference

This submodule includes these parsing functions:

alchemlyb.parsing.lammps.extract_dHdl(fep_files: str | list[str], T: float, column_lambda1: int = 1, column_dlambda1: int = 2, column_lambda2: int | None = None, columns_derivative: list[int] = [8, 7], vdw_lambda: int = 1, units: str = 'real', prec: int = 4) → DataFrame

Return reduced potentials dHdl from LAMMPS dump file(s).

Each file is imported as a data frame where the columns kept are either:

[0, column_lambda, column_dlambda1, columns_derivative[0], columns_derivative[1]]

or if columns_lambda2 is not None:

[
    0, column_lambda, column_dlambda1, column_lambda2, column_dlambda2,
    columns_derivative[0], columns_derivative[1],
]

Parameters:

• fep_files (str or list) –

  If not a list, represents the path to fepout file(s) to extract data from. Filenames and paths are aggregated using glob. For example, “/path/to/files/something_*_*.txt”.

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

• column_lambda1 (int, default=1) – Index for column (column number minus one) representing the lambda at which the system is equilibrated.

• column_dlambda1 (int, default=2) – Index for column (column number minus one) for the change in lambda.

• column_lambda2 (int, default=None) – Index for column (column number minus one) for a second value of lambda. If this array is None then we do not expect two lambda values.

• columns_derivative (list[int], default=[8, 7]) – Indices for columns (column number minus one) representing the the forward and backward derivative respectively.

• vdw_lambda (int, default=1) – In the case that column_lambda2 is not None, this integer represents which lambda represents vdw interactions.

• units (str, default="real") – Unit system used in LAMMPS calculation. Currently supported: “cgs”, “electron”, “lj”, “metal”, “micro”, “nano”, “real”, “si”

• prec (int, default=4) – Number of decimal places defined used in round() function.

• Results

• -------

• dHdl (pandas.Dataframe) –

  Dataframe of the derivative for the potential energy for each alchemical state (k) for each frame (n). Note that the units for timestamps are not considered in the calculation.

  Attributes

  • temperature in K or dimensionless

  • energy unit in kT

• versionadded: (..) – 2.4.1:

alchemlyb.parsing.lammps.extract_u_nk(fep_files: str | list[str], T: float, columns_lambda1: list[int] = [1, 2], column_dU: int = 4, column_U: int = 3, column_lambda2: int | None = None, indices: list[int] = [1, 2], units: str = 'real', vdw_lambda: int = 1, ensemble: str = 'nvt', pressure: float | None = None, column_volume: int = 6, prec: int = 4, force: bool = False, tol: float | None = None) → DataFrame

Return reduced potentials u_nk from LAMMPS dump file(s).

Each file is imported as a data frame where the columns kept are either:

[0, columns_lambda1[0] columns_lambda1[1], column_U, column_dU]

or if columns_lambda2 is not None:

[0, columns_lambda1[0] columns_lambda1[1], column_lambda2, column_U, column_dU]

If the simulation took place in the NPT ensemble, column_volume is appended to the end of this list.

Parameters:

• fep_files (str or list) –

  If not a list of filenames, represents the path to fepout file(s) to extract data from. Filenames and paths are aggregated using glob. For example, “/path/to/files/something_*_*.txt”.

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

• columns_lambda1 (list[int], default=[1,2]) – Indices for columns (column number minus one) representing (1) the lambda at which the system is equilibrated and (2) the lambda used in the computation of the potential energy.

• column_dU (int, default=4) – Index for the column (column number minus one) representing the difference in potential energy between lambda states

• column_U (int, default=3) – Index for the column (column number minus one) representing the potential energy

• column_lambda2 (int, default=None) – Index for column (column number minus one) for the unchanging value of lambda for another potential. If None then we do not expect two lambda values being varied.

• indices (list[int], default=[1,2]) – In provided file names, using underscore as a separator, these indices mark the part of the filename containing the lambda information for alchemlyb.parsing.get_bar_lambdas(). If column_lambda2 != None this list should be of length three, where the last value represents the invariant lambda.

• units (str, default="real") – Unit system used in LAMMPS calculation. Currently supported: “cgs”, “electron”, “lj”, “metal”, “micro”, “nano”, “real”, “si”

• vdw_lambda (int, default=1) – In the case that column_lambda2 is not None, this integer represents which lambda represents vdw interactions.

• ensemble (str, default="nvt") – Ensemble from which the given data was generated. Either “nvt” or “npt” is supported where values from NVT are unaltered, while those from NPT are corrected

• pressure (float, default=None) – The pressure of the system in the NPT ensemble in units of energy / volume, where the units of energy and volume are as recorded in the LAMMPS dump file.

• column_volume (int, default=6) – The column for the volume in a LAMMPS dump file.

• prec (int, default=4) – Number of decimal places defined used in round() function.

• force (bool, default=False) – If True the dataframe will be created, even if not all lambda and lambda prime combinations are available.

• tol (float, default=None) – Tolerance in checking that the difference between lambda and lambda’ states is zero. If None, this tolerance is set to np.finfo(float).eps. Take care in increasing this value! It’s more likely that something is wrong with your column indexing.

• Results

• -------

• u_nk_df (pandas.Dataframe) –

  Dataframe of potential energy for each alchemical state (k) for each frame (n). Note that the units for timestamps are not considered in the calculation.

  Attributes

  • temperature in K

  • energy unit in kT

• versionadded: (..) – 2.4.1:

alchemlyb.parsing.lammps.extract_dHdl_from_u_n(fep_files: str | list[str], T: float, column_lambda: int | None = None, column_u_cross: int | None = None, dependence: ~collections.abc.Callable[[float], float] = <function <lambda>>, units: str = 'real', prec: int = 4) → DataFrame

Produce dHdl dataframe from separated contributions of the potential energy.

Each file is imported as a dataframe where the columns are:

[0, column_lambda, column_solvent, column_solute, column_cross]

Parameters:

• fep_files (str or list) –

  If not a list, represents a path to fepout file(s) to extract data from. Filenames and paths are aggregated using glob. For example, “/path/to/files/something_*.txt”.

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

• column_lambda (int, default=None) – Indices for columns (file column number minus one) representing the lambda at which the system is equilibrated

• column_u_cross (int, default=None) – Index for the column (file column number minus one) representing the cross interaction potential energy of the system

• dependence (func, default=`lambda x : (1/x)`) – Transform of lambda needed to convert the potential energy into the derivative of the potential energy with respect to lambda, which must be separable. For example, for the LJ potential U = eps * f(sig, r), dU/deps = f(sig, r), so we need a dependence function of 1/eps to convert the potential energy to the derivative with respect to eps.

• units (str, default="real") – Unit system used in LAMMPS calculation. Currently supported: “cgs”, “electron”, “lj”, “metal”, “micro”, “nano”, “real”, “si”

• prec (int, default=4) – Number of decimal places defined used in round() function.

• Results

• -------

• dHdl (pandas.Dataframe) –

  Dataframe of the derivative for the potential energy for each alchemical state (k) for each frame (n). Note that the units for timestamps are not considered in the calculation.

  Attributes

  • temperature in K or dimensionless

  • energy unit in kT

• versionadded: (..) – 2.4.1:

alchemlyb.parsing.lammps.extract_u_nk_from_u_n(fep_files: str | list[str], T: float, column_lambda: int, column_U: int, column_U_cross: int, dependence: ~collections.abc.Callable[[float], float] = <function <lambda>>, index: int = -1, units: str = 'real', prec: int = 4, ensemble: str = 'nvt', pressure: float | None = None, column_volume: int = 4) → DataFrame

Produce u_nk from files containing u_n given a separable dependence on lambda.

Parameters:

• fep_files (str or list) –

  If not a list, a str representing the path to fepout file(s) to extract data from. Filenames and paths are aggregated using glob. For example, “/path/to/files/something_*.txt”.

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

• column_lambda (int) – Indices for columns (file column number minus one) representing the lambda at which the system is equilibrated

• column_U (int) – Index for the column (file column number minus one) representing the potential energy of the system.

• column_U_cross (int) – Index for the column (file column number minus one) representing the potential energy of the cross interactions between the solute and solvent.

• dependence (func, default=`lambda x : (x)`) – Dependence of changing variable on the potential energy, which must be separable.

• index (int, default=-1) – In provided file names, using underscore as a separator, these indices mark the part of the filename containing the lambda information for alchemlyb.parsing.lambda_from_filename(). If column_lambda2 != None this list should be of length three, where the last value represents the invariant lambda.

• units (str, default="real") – Unit system used in LAMMPS calculation. Currently supported: “cgs”, “electron”, “lj”, “metal”, “micro”, “nano”, “real”, “si”

• prec (int, default=4) – Number of decimal places defined used in round() function.

• ensemble (str, default="nvt") – Ensemble from which the given data was generated. Either “nvt” or “npt” is supported where values from NVT are unaltered, while those from NPT are corrected

• pressure (float, default=None) – The pressure of the system in the NPT ensemble in units of energy / volume, where the units of energy and volume are as recorded in the LAMMPS dump file.

• column_volume (int, default=4) – The column for the volume in a LAMMPS dump file.

Returns:

• u_nk_df (pandas.Dataframe) – Dataframe of potential energy for each alchemical state (k) for each frame (n). Note that the units for timestamps are not considered in the calculation.

  Attributes

  • temperature in K

  • energy unit in kT

• .. versionadded:: 2.4.1

alchemlyb.parsing.lammps.extract_H(fep_files: str | list[str], T: float, column_lambda1: int = 1, column_pe: int = 5, column_lambda2: int | None = None, units: str = 'real', ensemble: str = 'nvt', pressure: float | None = None, column_volume: int = 6) → DataFrame

Return reduced potentials Hamiltonian from LAMMPS dump file(s).

Each file is imported as a data frame where the columns kept are either:

[0, column_lambda, column_dlambda1, columns_derivative[0], columns_derivative[1]]

or if columns_lambda2 is not None:

[
    0, column_lambda, column_dlambda1, column_lambda2, column_dlambda2,
    columns_derivative1[0], columns_derivative1[1]
]

Parameters:

• fep_files (str or list) –

  If not a list, represents the path to fepout file(s) to extract data from. Filenames and paths are aggregated using glob. For example, “/path/to/files/something_*_*.txt”.

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

• column_lambda1 (int, default=1) – Index for column (column number minus one) representing the lambda at which the system is equilibrated.

• column_pe (int, default=5) – Index for column (column number minus one) representing the potential energy of the system.

• column_lambda2 (int, default=None) – Index for column (column number minus one) for a second value of lambda. If this array is None then we do not expect two lambda values.

• units (str, default="real") – Unit system used in LAMMPS calculation. Currently supported: “cgs”, “electron”, “lj”, “metal”, “micro”, “nano”, “real”, “si”

• ensemble (str, default="nvt") – Ensemble from which the given data was generated. Either “nvt” or “npt” is supported where values from NVT are unaltered, while those from NPT are corrected

• pressure (float, default=None) – The pressure of the system in the NPT ensemble in units of energy / volume, where the units of energy and volume are as recorded in the LAMMPS dump file.

• column_volume (int, default=6) – The column for the volume in a LAMMPS dump file.

• Results

• -------

• H (pandas.Dataframe) –

  Dataframe of potential energy for each alchemical state (k) for each frame (n). Note that the units for timestamps are not considered in the calculation.

  Attributes

  • temperature in K or dimensionless

  • energy unit in kT

• versionadded: (..) – 2.4.1:

alchemlyb.parsing.lammps.beta_from_units(T: float, units: str) → float

Output value of beta from temperature and units.

Supported types are: cgs, electron, lj, metal, micro, nano, real, si

Parameters:

• T (float) – Temperature that the system was run with

• units (str) – LAMMPS style unit

Returns:

beta – Value of beta used to scale the potential energy.

Return type:

float

Raises:

• ValueError – If unit string is not recognized.

• .. versionadded: – 2.4.1: