BaseSimulator Class

The BaseSimulator class serves as the foundational interface for handling simulation logic. It separates the specific implementation details from the general logic required for Atomic Simulation Environment (ASE) based workflows.

class flames.base_simulator.BaseSimulator(model, framework_atoms, adsorbate_atoms, temperature, pressure, device, vdw_radii, framework_energy=None, adsorbate_energy=None, vdw_factor=0.6, max_deltaE=1.555, save_frequency=100, save_rejected=False, output_to_file=True, output_folder=None, debug=False, fugacity_coeff=1.0, random_seed=None, cutoff_radius=6.0, automatic_supercell=True)[source]

This class handles all base parameters for the simulations. Separates the basic logic used in the simulations from the specific implementation details.

Parameters:

  • model (ase.calculators.calculator.Calculator) – The calculator to use for energy calculations. Can be any ASE-compatible calculator. The output of the calculator should be in eV.

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

  • adsorbate_atoms (ase.Atoms) – The adsorbate structure as an ASE Atoms object.

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

  • pressure (float) – Pressure of the ideal reservoir in Pascal.

  • device (str) – Device to run the simulation on, e.g., 'cpu' or 'cuda'.

  • vdw_radii (np.ndarray) – Van der Waals radii for the atoms in the framework and adsorbate. Should be an array of the same length as the number of atomic numbers in ASE.

  • framework_energy (float) – Total energy of the framework.

  • adsorbate_energy (float) – Total energy of the adsorbate.

  • 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).

  • save_frequency (int, optional) – Frequency at which to save the simulation state and results. Default is 100.

  • 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 GCMC_Output.out in the results directory.

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

  • debug (bool, optional) – If True, prints detailed debug information during the simulation. Default is False.

  • fugacity_coeff (float, optional) – Fugacity coefficient to correct the pressure. Default is 1.0. Only used if criticalTemperature, criticalPressure, and acentricFactor are not provided.

  • 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) – If True, automatically creates a supercell based on the cutoff radius. Default is True.

get_framework_mass()[source]

Calculate the mass of the framework in kg.

Returns:

The mass of the framework in kg.

Return type:

float

get_ideal_supercell()[source]

Get the ideal supercell dimensions based on the cutoff radius.

Returns:

An array of three integers representing the number of unit cells in each dimension.

Return type:

np.ndarray

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

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.

nvt(nsteps, time_step=0.5, set_momenta=True, output_interval=100, movie_interval=100, calculator=None, **kwargs)[source]

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 (default is 0.5 fs).

  • 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.

optimize_adsorbate(max_steps=1000, max_force=0.05)[source]

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)[source]

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

set_adsorbate(adsorbate_atoms, adsorbate_energy=None, n_adsorbates=0)[source]

Set the adsorbate structure for the simulation.

Parameters:

  • adsorbate_atoms (ase.Atoms) – The new adsorbate structure as an ASE Atoms 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)[source]

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)[source]

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