Widom Class

The Widom class serves as the main interface for handling Widom insertion simulation logic.

class flames.widom.Widom(framework_atoms, adsorbate_atoms, temperature, model, vdw_radii, framework_energy=None, adsorbate_energy=None, vdw_factor=0.6, max_deltaE=1.555, device='cpu', save_snapshots=True, save_rejected=False, output_to_file=True, save_only_adsorbate=False, output_folder=None, debug=False, random_seed=None, cutoff_radius=6.0, automatic_supercell=True)[source]

Bases: BaseSimulator

Base class for Widom insertion method using ASE.

This class performs the Widom insertion method to calculate the enthalpy of adsorption and Henry coefficient of an adsorbate in a framework.

Currently, it supports only one adsorbate molecule and any ASE-compatible calculator for energy calculations.

Parameters:

  • framework_atoms (ase.Atoms) – The empty framework structure where the adsorbate will be inserted.

  • adsorbate_atoms (Adsorbate) – The adsorbate molecule to be inserted into the framework.

  • temperature (float) – Temperature of the ideal reservoir in Kelvin.

  • model (ase.calculators.calculator.Calculator) – ASE-compatible calculator for energy calculations.

  • vdw_radii (np.ndarray) – Van der Waals radii of the atoms in the framework and adsorbate.

  • framework_energy (float or None, optional) – Pre-calculated potential energy of the empty framework in eV. If not provided, it will be calculated during initialization.

  • adsorbate_energy (float or None, optional) – Pre-calculated potential energy of the adsorbate molecule in eV. If not provided, it will be calculated during initialization.

  • vdw_factor (float, optional) – Factor to scale the Van der Waals radii. Default is 0.6.

  • max_deltaE (float, optional) – Maximum energy difference (in eV) to consider for acceptance criteria. This is used to avoid overflow due to problematic calculations. Default is 1.555 eV (approx. 150 kJ/mol).

  • device (str, optional) – Device to run the calculations on, either 'cpu' or 'cuda'. Default is 'cpu'.

  • save_snapshots (bool, optional) – Whether to save the simulation state and results. Default is True.

  • save_rejected (bool, optional) – If True, saves the rejected moves in a trajectory file. Default is False.

  • output_to_file (bool, optional) – If True, writes the output to a file named Widom_Output.out in the results directory. Default is True.

  • save_only_adsorbate (bool, optional) – If True, saves only the adsorbate atoms in the trajectory file. Default is False.

  • output_folder (str or None, optional) – Folder to save the output files. If None, a folder named results_<T>_<P> will be created.

  • debug (bool, optional) – If True, enables debug mode with more verbose output. Default is False.

  • random_seed (int or None, optional) – Random seed for reproducibility. Default is None.

  • cutoff_radius (float, optional) – Interaction potential cut-off radius used to estimate the minimum unit cell. Default is 6.0.

  • automatic_supercell (bool, optional) – Whether to automatically create a supercell based on the cutoff radius. Default is True.

get_framework_mass()

Calculate the mass of the framework in kg.

Returns:

The mass of the framework in kg.

Return type:

float

md(nsteps, atoms=None, time_step=0.5, ensemble='NVT', thermostat='NoseHoover', output_interval=100, movie_interval=100, calculator=None, update_state=True, trajectory_file=None, set_momenta=True, **kwargs)

Run a molecular dynamics simulation using the specified ensemble and thermostat.

Parameters:

  • nsteps (int) – Number of steps to run the MD simulation.

  • time_step (float, optional) – Time step for the MD simulation in femtoseconds (default is 0.5 fs).

  • ensemble (str, optional) – The ensemble to use for the MD simulation (default is “NVT”). Can be one of “NVT” or “NPT”.

  • thermostat (str, optional) – The thermostat to use for the MD simulation (default is “NoseHoover”). For NVT, can be one of “Berendsen”, “NoseHoover”, or “Langevin”. For NPT, can be one of “Berendsen”, “NoseHoover”, or “MTKNPT”.

  • output_interval (int, optional) – The interval for logging output (default is 100 steps).

  • movie_interval (int, optional) – The interval for saving trajectory frames (default is 100 steps).

  • calculator (ase.calculators.calculator.Calculator or None, optional) – The calculator to use for energy calculations. If None, the default model will be used.

  • update_state (bool, optional) – If True, updates the current state of the simulation with the final state after MD. If False, returns the final state without updating. This difference is important for using the same method in the GCMC simulations when a MD step is used as a move. Default is True.

  • trajectory_file (str or None, optional) – If provided, saves the trajectory to the specified file instead of the default trajectory.

  • set_momenta (bool, optional) – Whether to set the atomic momenta to a Maxwell-Boltzmann distribution of the simulation temperature.

  • **kwargs (optional) –

    Additional parameters passed directly to the specific MD thermostat (e.g., taut, tdamp, friction).

    NVT Berendsen:
    • tautfloat, optional

      Time constant for the Berendsen thermostat in fs (default is 1.0 fs).

    NVT Nose-Hoover:
    • tdampfloat, optional

      Time constant for the Nose-Hoover thermostat in fs (default is 50.0 fs).

    • tchainint, optional

      Number of thermostats in the Nose-Hoover chain (default is 3).

    • tloopint, optional

      Number of loops for the Nose-Hoover chain (default is 1).

    NVT Langevin:
    • frictionfloat, optional

      Friction coefficient for the Langevin dynamics (default is 0.01).

    NPT Berendsen:
    • isotropicbool, optional

      Whether to use isotropic pressure coupling (default is True).

    • compressibilityfloat, optional

      Compressibility of the material in bar^-1 (default is 1e-4 bar^-1).

    • tautfloat, optional

      Time constant for the Berendsen thermostat in fs (default is 10.0 fs).

    • taupfloat, optional

      Time constant for the Berendsen barostat in fs (default is 500.0 fs).

    NPT Nose-Hoover:
    • ttimefloat, optional

      Time constant for the Nose-Hoover thermostat in fs (default is 25.0 fs).

    • ptimefloat, optional

      Time constant for the Parrinello-Rahman barostat in fs (default is 75.0 fs).

    • bulk_modulusfloat, optional

      Bulk modulus of the material in GPa (default is 30.0 GPa).

    NPT MTK:
    • tdampfloat, optional

      Time constant for the Nose-Hoover thermostat in fs (default is 50.0 fs).

    • pdampfloat, optional

      Time constant for the Nose-Hoover barostat in fs (default is 500.0 fs).

    • tchainint, optional

      Number of thermostats in the Nose-Hoover chain (default is 3).

    • pchainint, optional

      Number of barostats in the Nose-Hoover chain (default is 3).

    • tloopint, optional

      Number of loops for the Nose-Hoover thermostat chain (default is 1).

    • ploopint, optional

      Number of loops for the Nose-Hoover barostat chain (default is 1).

    • vol_constraintbool, optional

      If True, the (N, V, sigma_a = 0, T)-ensemble is sampled, which allows for full cell fluctuations while keeping the cell volume fixed (default is False).

Return type:

None | Atoms

npt(nsteps, time_step=0.5, mode='iso_shape', driver='MTKNPT', set_momenta=True, output_interval=100, movie_interval=100, calculator=None, **kwargs)

Run a NPT simulation using the Berendsen thermostat and barostat.

Parameters:

  • nsteps (int) – Number of steps to run the NPT simulation.

  • time_step (float, optional) – Time step for the NPT simulation (default is 0.5 fs).

  • mode (str, optional) – The mode of the NPT simulation (default is “iso_shape”). Can be one of “iso_shape”, “aniso_shape”, or “aniso_flex”.

  • driver (str, optional) – The driver to use for the NPT simulation. Can be Berendsen, NoseHoover or MTKNPT (default is “MTKNPT”).

  • set_momenta (bool, optional) – Whether to set the atomic momenta to a Maxwell-Boltzmann distribution of the simulation temperature.

  • output_interval (int, optional) – The interval for logging output (default is 100 steps).

  • movie_interval (int, optional) – The interval for saving trajectory frames (default is 100 step).

  • calculator (ase.calculators.calculator.Calculator or None, optional) – The calculator to use for energy calculations. If None, the default model will be used.

  • kwargs (optional) – Arguments passed to the ase molecular dynamics class.

Return type:

None | Atoms

nvt(nsteps, time_step=0.5, set_momenta=True, driver='NoseHoover', output_interval=100, movie_interval=100, calculator=None, **kwargs)

Run a NVT simulation using the Berendsen thermostat.

Parameters:

  • nsteps (int) – Number of steps to run the NVT simulation.

  • time_step (float, optional) – Time step for the NVT simulation in femtoseconds (default is 0.5 fs).

  • set_momenta (bool, optional) – Whether to set the atomic momenta to a Maxwell-Boltzmann distribution of the simulation temperature.

  • driver (str, optional) – The driver to use for the NVT simulation. Can be “NoseHoover” (default), Langevin, or “Berendsen” (Not recommended, for testing purposes only).

  • output_interval (int, optional) – The interval for logging output (default is 100 steps).

  • movie_interval (int, optional) – The interval for saving trajectory frames (default is 100 step).

  • calculator (ase.calculators.calculator.Calculator or None, optional) – The calculator to use for energy calculations. If None, the default model will be used.

  • kwargs (optional) – Arguments passed to the ase molecular dynamics class.

  • NoseHoover (For)

  • tdamp (-) – Time constant for the thermostat in fs (default is 50.0 fs).

  • tchain (-) – Length of the Nose-Hoover chain (default is 3).

  • tloop (-) – Number of loops for the Nose-Hoover chain (default is 1).

  • Langevin (For)

  • friction (-) – Friction coefficient for the Langevin thermostat in fs^-1 (default is 0.1 fs^-1).

  • Berendsen (For)

  • tau (-) – Time constant for the Berendsen thermostat in fs (default is 1.0 fs).

optimize_adsorbate(max_steps=1000, max_force=0.05)

Optimize the adsorbate structure using the provided calculator.

Parameters:

  • max_steps (int, optional) – Maximum number of optimization steps (default is 1000).

  • symm_tol (float, optional) – Tolerance for symmetry (default is 1e-3).

  • max_force (float, optional) – Maximum force tolerance for convergence (default is 0.05 eV/Å).

Returns:

The optimized adsorbate structure.

Return type:

ase.Atoms

optimize_framework(max_steps=1000, opt_cell=True, fix_symmetry=True, hydrostatic_strain=True, symm_tol=0.001, max_force=0.05)

Optimize the framework structure using the provided calculator.

Parameters:

  • max_steps (int, optional) – Maximum number of optimization steps (default is 1000).

  • tol (float, optional) – Tolerance for convergence (default is 1e-5).

Returns:

The optimized framework structure.

Return type:

ase.Atoms

restart()[source]

Restart the simulation from the last state.

This method loads the last saved state from the trajectory file and restores the simulation to that state. It also loads the uptake, total energy, and total adsorbates lists from the saved files if they exist.

Return type:

None

run(N)[source]
Return type:

None

save_results(file_name='Widom_Results.json')[source]

Save a json file with the main results of the simulation.

Parameters:

file_name (str, optional) – Name of the output json file (default is ‘Widom_Results.json’).

Return type:

None

set_adsorbates(adsorbates, adsorbate_energy=None)

Set the adsorbate structure for the simulation.

Parameters:

  • adsorbates (Adsorbate) – The list of adsorbate structure(s) as an Adsorbate object.

  • adsorbate_energy (float or None, optional) – The energy of the adsorbate in eV. If None, the energy will be calculated using the provided model.

  • n_adsorbates (int) – Number of adsorbate molecules in the framework.

Return type:

None

set_framework(framework_atoms, framework_energy=None)

Set the framework structure for the simulation.

Parameters:

  • framework_atoms (ase.Atoms) – The new framework structure as an ASE Atoms object.

  • framework_energy (float or None, optional) – The energy of the framework in eV. If None, the energy will be calculated using the provided model.

Return type:

None

set_state(state)

Set the current state of the simulation.

Parameters:

state (ase.Atoms) – The current state of the simulation as an ASE Atoms object.

Return type:

None

step(iteration)[source]

Run a single iteration of the Widom insertion method.

Parameters:

iteration (int) – The current iteration number.

Return type:

None

try_insertion()[source]

Try to insert a new adsorbate molecule into the framework. This method randomly places the adsorbate in the framework and checks for van der Waals overlap. If there is no overlap, it calculates the new potential energy and decides whether to accept the insertion based on the acceptance criteria.

Return type:

tuple[float, Atoms]

Returns:

  • deltaE (float) – The change in energy associated with the insertion. If the insertion fails, returns a large value (1000.0).

  • atoms_trial (ase.Atoms) – The trial configuration after the insertion attempt.

update_statistics(deltaE)[source]

Update the statistics of the Widom insertion method after a new insertion.

Parameters:

deltaE (float) – The change in energy associated with the latest insertion.

Return type:

None