# Changelog ## v[0.4.8] - 2026-07-22 ### New Features 🎉 - Now it is possible to use a different calculator for the MD simulation in the `BaseSimulator` class. The `calculator` parameter can be provided to the `npt` and `nvt` methods, allowing users to specify a different calculator for energy calculations during the MD simulation. If not provided, the default model will be used. ### Enhanced ✨ ### Fixed 🐛 - Fixed a bug in the ase_utils.py file where the `output_interval` and `movie_interval` parameters were mixed up, resulting in incorrect logging intervals for the MD simulations. Now the `output_interval` is correctly used for logging the MD simulation data, while the `movie_interval` is used for controlling the frequency of snapshot saving. ### Documentation 📖 - Add an example on how to use a different calculator for the MD simulation in the `GCMC` class. ### Removed 🗑️ ## v[0.4.7] - 2026-07-22 ### New Features 🎉 ### Enhanced ✨ - Changed the `BaseSimulator` class to multiply the total energy by the supercell size when calculating the adsorption energy. This change ensures that the adsorption energy is correctly calculated based on the total energy of the system, which includes contributions from all atoms in the supercell. - Created a new `CustomLennardJones` calculator based on JIT for improved performance in calculating Lennard-Jones interactions. - Created a new `EwaldSum` calculator based on JIT for improved performance in calculating electrostatic interactions. - Add workarounds for loading and saving labels in ASE's Trajectory since it does not support custom arrays. Now the labels are saved in the `info` attribute of the Trajectory and loaded back into the Atoms object when reading the trajectory. - Create new `CustomGNP` calculator to implemente the Generalized Nonbonded Potential (GNP) based on the work of Luo and Goddard III, J. Chem. Theory Comput. 2025, 21, 1, 499-515. - Now a message is printed when the `GCMC` tries to restart a simulation from a trajectory file that is empty or corrupted. This message informs the user that the last state of the simulation cannot be loaded, and that the simulation will start from scratch. ### Fixed 🐛 - Fixed a bug in the MD classes that was causing the `output_interval` and `movie_interval` parameters to be mixed up, resulting in incorrect logging intervals for the MD simulations. Now the `output_interval` is correctly used for logging the MD simulation data, while the `movie_interval` is used for controlling the frequency of snapshot saving. - Fixed a bug in the `BaseSimulator` class where the `set_state` method was not properly updating the current system state, which could lead to inconsistencies in the simulation. Now the `set_state` method correctly updates the current system state with the provided state, ensuring that the simulation runs with the correct configuration. - Improve behavior when the cif file does not have partial charges. - Fixed the LennardJones parameters for the `UFF` force field. ### Documentation 📖 - Improvements in the documentation. ### Removed 🗑️ ## v[0.4.6] - 2026-04-14 ### New Features 🎉 - Core implemenation of the `TMMC` class allowing to run transition matrix Monte Carlo insertion/deletion moves on-top of a `GCMC` or MD simulation. - Added tests for the `Widom` and the `GCMC` class, likewise to the `TMMC` class. With those tests the overall test coverage increases to 58%. ### Enhanced ✨ - Added `**kwargs` to expose the interface of the underlying `ase` MD classes allowing the user to pass on parameters via that overwrite the default values. - Added the parameters `output_interval` and `movie_interval` to decouple those parameters from the `save_every` attribute. - Added the `set_momenta` parameter to switch on/off the initialization of atomic momenta based on the input temperature. ### Fixed 🐛 ### Documentation 📖 ### Removed 🗑️ ## v[0.4.5] - 2025-12-08 ### New Features 🎉 - Added the `Reinsertion` move to the GCMC simulation. This move allows for the reinsertion of an adsorbate molecule that has been previously deleted, providing a mechanism to recover from unfavorable deletions and improve sampling efficiency. - Added the `insert_molecules` method to the `GCMC` class. This method allows users to insert a specified number of adsorbate molecules into the simulation box at once, facilitating the initialization of the system with a desired loading. - Added excess uptake calculation to the GCMC simulation results. - Added the `void_fraction` parameter to the `GCMC` class that allows users to specify the void fraction of the structure for calculating the excess uptake. - Added the `get_bulk_phase_molar_density` on the `PengRobinsonEOS` class to calculate the bulk phase molar density needed for the excess uptake calculation. - Now it is possible to manually set the adsorbate and framework energy when initializing the `GCMC` and `Widom` classes. This allows users to provide pre-calculated energies for the adsorbate and framework. - Added the `nPT_MTKNPT` method on ase_utils for running NPT Molecular Dynamics (MD) simulations using the MTK NPT thermostat/barostat. This method is now the default for NPT MD simulations in the `BaseSimulator` class. ### Fixed 🐛 - Remove the `max_overlap_tries` parameter from the GCMC class, as any value greater than 1 may cause problems on the GCMC simulation. - Fix conversion factor for 'nmol' in BaseSimulator to account for supercell dimensions - Remove the `save_frequency` parameter from the `Widom` class, to avoid confusion since the snapshots are now controlled by the `save_snapshots` parameter. - Changed the default value for the LLM parameter in the GCMC class to False. - Rename the `N_ads` attribute to `n_adsorbates` in both the `GCMC` and `Widom` classes for better clarity. ### Enhanced ✨ - Change the json output file name on the `GCMC.save_results` method to `results__

.json` if no file name is provided by the user. - Add the `production_start` parameter to the `GCMC.equilibrate` method to allow users to specify the step from which the production analysis should begin. This provides greater flexibility in analyzing the simulation data and helps to exclude initial equilibration steps from the analysis, specially when running MD + GCMC simulations. - Add the `save_snapshots` parameter to the `Widom` class to allow users to control whether to save the simulation snapshots during the Widom insertion process. When set to `True`, the simulation state and results will be saved every step; when set to `False`, they will not be saved. By default, this parameter is set to `True`. - Now `move_weights` parameter is a property in the `GCMC` class, allowing for get and set methods to change the move weights after initialization. ### Documentation 📖 - Att online documentation for the code at https://lipelopesoliveira.github.io/flames/ ### Removed 🗑️ ## v[0.4.4] - 2025-11-04 ### New Features 🎉 - GCMC RDF: The `ase_utils` now has the `rdf_gcmc`, that can calculate the Radial Distribution Function (RDF) on a trajectory with different number of atoms. - Added the `EwaldSum` calculator to calculate the electrostatic interactions - Added the `CustomLennardJones` calculator to calculate the Lennard-Jones interaction energy ### Fixed 🐛 - Fix the bug where the `output_folder` parameter was not being properly passed to the `BaseSimulator` on `GCMC` class. - Fix a major bug in rotating molecules that have part of their atoms in one unit cell and parts in another. ### Enhanced ✨ - Introduced the `max_overlap_tries` parameter in `GCMC` and `Widom` classes to try `n` attempts for placing an adsorbate without van der Waals overlap. If a valid position is not found within the specified number of tries, the insertion is rejected. This applies to insertion, rotation and translation moves. - Only create the `Trajectory_rejected.traj` file if the `save_rejected` parameter is set to `True` when initializing the `BaseSimulator` class. - Abstracted a few methods on the `Widom` class for better code reusability. - Refactor the results json to improve the clarity - Both `Widom` and `GCMC` classes now saves the random seed and enlapsed time on the `results.json` file. - Now the use of Left-most Local Minima for pyMSER equilibration can defined on the GCMC class through the `LLM` parameter. By default it is `True`. - Now the molecular rotation are based on a unit vector on a sphere, using the method proposed by George Marsaglia in The Annals of Mathematical Statistics, 1972, Vol. 43, No. 2, 645-646. ### Documentation 📖 - Fix a bug on the isotherm simulation example. ### Removed 🗑️ ## v[0.4.3] - 2025-10-15 ### New Features 🎉 - Added support for custom output folders in the `GCMC` and `Widom` classes. Users can now specify a custom folder for saving output files through the `output_folder` parameter. If not provided, a default folder named 'results__

' will be created based on the simulation temperature and pressure. ### Fixed 🐛 ### Enhanced ✨ ### Documentation 📖 ### Removed 🗑️ ## v[0.4.2] - 2025-10-14 ### New Features 🎉 - Added the `GCMC.equilibrate` method to allow users to perform equilibration analysis separately from the main simulation run. This method uses the pyMSER library to analyze the uptake data and determine when the system has reached equilibrium. - Added the `GCMC.save_results` method to save the results of the equilibration analysis to a JSON file. This includes key metrics such as average uptake, uncertainty, and enthalpy of adsorption. - Allow for custom move weights in the GCMC simulation. Users can now specify different probabilities for insertion, deletion, translation, and rotation moves through the `move_weights` parameter when initializing the `GCMC` class. This provides greater flexibility in tailoring the simulation to specific systems or research needs. - Improved the logging of Widom simulation results to include standard deviations for both the Henry coefficient and the enthalpy of adsorption. The standard deviations are calculated using 5-fold cross-validation, providing a more robust measure of uncertainty in the results. - Added the `Widom.save_results` method to include standard deviations for the Henry coefficient and enthalpy of adsorption. - Added the `save_rejected` parameter to both the `GCMC` and `Widom` classes. When set to `True`, this parameter enables the saving of rejected moves to a separate trajectory file, allowing users to analyze these configurations post-simulation. ### Fixed 🐛 - The %wt conversion factor was incorrectly calculated using a factor of 1e-3 instead of 1e-1. This has been corrected in the `GCMC` class and related calculations to ensure accurate representation of adsorption data in weight percent. - The restart method in the `GCMC` class was not properly resetting the simulation state. This has been fixed to ensure that all relevant attributes are correctly reinitialized when restarting a simulation. ### Enhanced ✨ - Improved the handling of tags in the ASE Atoms objects for both the framework and adsorbate molecules. The framework atoms are now tagged with `0`, and adsorbate atoms are tagged with `1`. This tagging system helps differentiate between framework and adsorbate atoms during simulations and analyses. This is also a necessary step for future implementations of multiple adsorbates. - Now the rotation movements are restricted to an arc of -15 to +15 degrees around an random axis instead of a full random rotation. This change aims to improve the acceptance rate of rotation moves in the GCMC simulation by making smaller, more controlled adjustments to the adsorbate positions. This angle can be adjusted by the user through the `max_rotation_angle` parameter when initializing the `GCMC` class. ### Documentation 📖 - Examples have been updated to save the results of the simulations using the new `save_results` method. ### Removed 🗑️ ## v[0.4.1] - 2025-09-19 ### New Features 🎉 - The final name of the package is now `FLAMES - Flexible Lattice Adsorption by Monte Carlo Engine Simulation`. The code repository, documentation site, and examples have been updated to reflect this change. ### Fixed 🐛 ### Enhanced ✨ - Added a `max_deltaE` parameter to the `BaseSimulator`, `GCMC`, and `Widom` classes to prevent errors from the model during energy calculations. This parameter sets a maximum threshold for energy changes, ensuring numerical stability during simulations. The default value is set to 1.555 eV (150 kJ/mol). - Change the `random_seed` parameter to pick a random integer between 1 and 1,000,000 if not provided by the user. This ensures the use of a valid seed for the random number generator, enhancing reproducibility in simulations. ### Documentation 📖 ### Removed 🗑️ ## v[0.4.0] - 2025-09-04 ### New Features 🎉 - Added the Peng-Robinson equation of state (EOS) to the `mlp_adsorption.eos` module. - This allows for the calculation of fugacity coefficients and bulk phase density using the Peng-Robinson EOS. - Add functions to calculate perpendicular lengths and unit cell repetitions in `utilities`. - Add a new parameter `cutoff` on the `mlp.gcmc` class for controlling the supercell check based on a cutoff radius for the potential. - Add the `get_density` function to the `mlp_adsorption.utilities` module. - Add a `mlp_adsorption.utilities.make_cubic` function that can create a cubic (or close to) supercell from a given structure. - Now all movements are based on a `numpy.random.Generator` to ensure reproducibility. A `random_seed` can be provided to the `GCMC` and `Widom` classes for this purpose. - New module for checking the overlap between atoms (`mlp_adsorption.operations.check_overlap`) - A new `BaseSimulator` method created to abstract the system state management and general simulation logic. - Now all the output of the simulations are managed by a `mlp_adsorption.logger` instance. It introduces: - `BaseLogger`: A base class for logging simulation information, including restart and iteration details. - `GCMCLogger`: A logger specifically for GCMC simulations, extending `BaseLogger` with additional functionality. - `WidomLogger`: A logger specifically for Widom simulations, extending `BaseLogger` with additional functionality. - Now the `Widom` has a `restart` method to allow restarting a Widom simulation from a saved state. Since Widom does not insert adsorbates on the structure, it simply reads the existing list of insertion energies and use it to update the simulation statistics. - Now the code uses [pyMSER](https://github.com/IBM/pymser) to evaluate the equilibration of the simulation and calculate the average uptake and enthalpy of adsorption. ### Fixed 🐛 - Fix the framework density calculation on `GCMC` and `Widom` class. - Fix an error on the check if the optimization converged. ### Enhanced ✨ - Move the random operations (insertion, rotation, translation) to a separate `mlp_adsorption.operations.py` module for better organization and reusability. ### Documentation 📖 - Add the critical parameters to the examples. ### Removed 🗑️ - Old `mlp_adsorption.operations.vdw_overlap` and `mlp_adsorption.operations.vdw_overlap2` functions. ## v[0.3.2] - 2025-08-17 ### New Features 🎉 - New `restart` method in the `GCMC` class to allow restarting a GCMC simulation from a saved state. - It reads the state from an existing `Trajectory` object, enabling the continuation of simulations without losing progress. - It reads the total uptake, total energy, and adsorption energy `npy` files for seamless simulation restoration. - Now the `vdw_factor` can be set when initializing the `GCMC` class, allowing for more flexible control over the Van der Waals radii scaling. By default, it is set to 0.6. - Add `flush=True` to print statements for immediate output in optimization and simulation logs ### Fixed 🐛 - Fixed the handling of NaN values in the Van der Waals radii in both `gcmc.py` and `widom.py` files to ensure that any NaN value is replaced by 1.5, preventing potential issues during simulations. - Fixed unit for Henry constant on header and footer of Widom output. Now it correctly reports the unit as [mol kg-1 Pa-1]. - Change the energy return value in the `try_insertion` method of the `Widom` class to 1000 eV when there is a Van der Waals overlap and limit the number of insertion attempts to 100. This change ensures that the method prevents an infinite loop in the simulation. ### Enhanced ✨ - Restart of a GCMC simulation: - Now the `load_state` method in the `GCMC` class can load the state from a `Trajectory` object, allowing for restarting simulations from saved states. - Add new examples for running GCMC simulations with different configurations, including: - Basic - Widom Insertion - Rigid GCMC - Rigid GCMC Isotherm - Intermediate - Geometry Optimization + GCMC - Flexible GCMC: Molecular Dynamics + GCMC ### Documentation 📖 - New examples are documented in the README file, providing clear instructions on how to run GCMC simulations and Widom insertion tests. ### Removed 🗑️ - Removed commented-out code for saving the system state in xyz format in the `gcmc.py` file to clean up the codebase. ## v[0.3.1] - 2025-08-05 ### New Features 🎉 ### Fixed 🐛 - Fixed the calculation of Henry's law constant in the Widom insertion method to ensure it is correctly computed in units of [mol kg-1 Pa-1]. - Fixed the calculation of the heat of adsorption (Qst) in the Widom insertion method to ensure it is correctly computed in units of [kJ/mol]. ### Enhanced ✨ ### Documentation 📖 ### Removed 🗑️ ## v[0.3.0] - 2025-07-31 ### New Features 🎉 - Now GCMC has three different methods for NPT Molecular Dynamics (MD): - Isotropic volume change and fixed shape with Berendsen thermostat/barostat (`mode=iso_shape`) - Anisotropic volume change and fixed shape with Berendsen thermostat/barostat (`mode=aniso_shape`) - Anisotropic volume change and flexible shape with Nose-Hoover/Parrinello-Rahman thermostat/barostat (`mode=aniso_flex`). - Added a new method `nvt` to the GCMC class for running NVT MD simulations. ### Fixed 🐛 [#10](https://github.com/lipelopesoliveira/mlp_adsorption/issues/10) - The cell angles are not changing during the MD simulation. ### Enhanced ✨ - Now the NPT MD simulation log also prints the cell volume. - Now it is possible to control the type of NPT MD simulation through the use of a keyword argument on the `npt` method of GCMC simulation. ### Documentation 📖 ### Removed 🗑️ ## v[0.2.0] - 2025-07-12 ### New Features 🎉 - Support for saving the snapshots of the simulation on the same trajectory file in the `gcmc.py` and `widom.py` codes. - New examples for using the GCMC and Widom insertion methods in the `examples` directory. ### Fixed 🐛 - Incorrect statement on the insertion method in the `gcmc.py` file. ### Enhanced ✨ - Updated the `gcmc.py` file to use the `Trajectory.write` method instead of `write_proteindatabank`. - Updated the `ase_utils.py` file to accept a `trajectory` parameter in the `npt_md` function. - Replaces PDB output with ASE Trajectory for snapshot saving in `widom.py`. - Removed the unused import of `write_proteindatabank` in `widom.py`. ### Documentation 📖 - Added docstrings to all functions and classes in the `gcmc.py` and `widom.py` files. - Updated the README file with examples of how to use the GCMC and Widom insertion methods. ### Removed 🗑️ - Unused imports and commented-out code in `widom.py`. ## v[0.1.0] - 2025-07-12 - Initial release of the MLP Adsorption code, including the GCMC and Widom methods with basic functionality on the simulation of adsorption processes. ## v[X.Y.Z] - YYYY-MM-DD (Unreleased) ### New Features 🎉 ### Fixed 🐛 ### Enhanced ✨ ### Documentation 📖 ### Removed 🗑️