v0.4.5

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.

v0.4.4

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.

Changes Proposed 🔧

• Now insertion and movements (rotation and translation) are tried max_overlap_tries times if there is atomic superposition.
• Now the results for GCMC are saved in a new pattern in a JSON file:

{
    "simulation": {
        "code_version": "0.4.4",
        "random_seed": 42,
        "temperature_K": 298.0,
        "pressure_Pa": 1000,
        "fugacity_coefficient": 0.999945281976659,
        "fugacity_Pa": 999.945281976659,
        "move_weights": {
            "insertion": 0.25,
            "deletion": 0.25,
            "translation": 0.25,
            "rotation": 0.25
        },
        "n_steps": 10000,
        "enlapsed_time_hours": 4.077218167777778
    },
    "equilibration": {
        "LLM": true,
        "t0": 1200,
        "average": 9.724318181818182,
        "uncertainty": 1.7381870746612549,
        "equilibrated": true,
        "ac_time": 246,
        "uncorr_samples": 35
    },
    "enthalpy": {
        "kJ_mol": {
            "mean": -29.47864781927827,
            "sd": 1.7597487192742096
        }
    },
    "uptake": {
        "nmol": {
            "mean": 9.724318181818182,
            "sd": 1.7381870746612549
        },
        "mol/kg": {
            "mean": 0.834706569924878,
            "sd": 0.14920081221642828
        },
        "mg/g": {
            "mean": 36.734601426374184,
            "sd": 6.566178543143679
        },
        "cm^3 STP/gr": {
            "mean": 18.709081434221115,
            "sd": 3.3441813523287722
        },
        "cm^3 STP/cm^3": {
            "mean": 17.039385370806105,
            "sd": 3.0457291563211224
        },
        "% wt": {
            "mean": 3.6734601426374183,
            "sd": 0.6566178543143679
        }
    }
}

and for Widom simulation

{
    "code_version": "0.4.4",
    "random_seed": 42,
    "enlapsed_time_hours": 3.833586242222222,
    "total_insertions": 30001,
    "temperature_K": 298.0,
    "henry_coefficient_mol_kg-1_Pa-1": 0.001701641278585589,
    "henry_coefficient_std_mol_kg-1_Pa-1": 0.0001263130556036855,
    "enthalpy_of_adsorption_kJ_mol-1": -34.012502919379564,
    "enthalpy_of_adsorption_std_kJ_mol-1": 0.4945944610234945
}

v0.4.3

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_<T>_<P> will be created based on the simulation temperature and pressure.

v0.4.2

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.

v0.4.1

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 🗑️

v0.4.0

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 was created to abstract the system state management and general simulation logic.
• Now all the output of the simulations is managed by an 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 uses it to update the simulation statistics.
• Now the code uses 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 in 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.

v0.3.2

v[0.3.2] - 2025-08-17

Description 📝

• This version improves the restart method as a result of #21 and fixes the bugs reported on #16, #25, #27, and #31

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.

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 the header and footer of Widom output. Now it correctly reports the unit as [mol kg-1 Pa-1].
• Add flush=True to print statements for immediate output in optimization and simulation logs;
• 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. This change ensures that the method clearly indicates an overlap condition, preventing 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 📖

Removed 🗑️

• Removed commented-out code for saving the system state in xyz format in the gcmc.py file to clean up the codebase.

Related Issues 📎

Fixes #25
Fixes #27
Fixes #31
Fixes #16

v0.3.1

v[0.3.1] - 2025-08-05

New Features 🎉

Fixed 🐛

#18:

• 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 🗑️

v0.3.0

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 - 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 🗑️

v0.2.0

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