V4 (#35)

* Enhance README formatting for better visibility and structure

* Add Peng-Robinson equation of state implementation and update changelog

* Refactor PengRobinsonEOS integration in GCMC class and update fugacity coefficient calculation

* Update GCMC class to set default fugacity coefficient and enhance docstring for clarity

* Add fugacity coefficient parameters to GCMC initialization

* Refactor GCMC initialization to streamline simulation parameters and enhance fugacity coefficient formatting

* Add critical parameters for GCMC: criticalTemperature, criticalPressure, and acentricFactor

* Update version to 0.4.0 and modify changelog for unreleased features

* Fix fugacity coefficient assignment in GCMC class for clarity and correctness

* Add functions to calculate perpendicular lengths and unit cell repetitions in utilities

* Add functions for perpendicular lengths and unit cell calculations in utilities; update GCMC to utilize these functions

* Add cutoff parameter to GCMC class for supercell check control; update changelog

* Refactor framework setup in GCMC class to include supercell creation and perpendicular lengths calculation

* Fix python on 3.10

* Print perpendicular lenghts on Widom

* Reorganize import statements in GCMC, utilities, and Widom modules for clarity

* Initialize ideal supercell in GCMC class and update framework setup to calculate supercell dimensions

* Update README to improve description of MLP Adsorption package

* Refactor enthalpy_of_adsorption function to use ase.units for gas constant

* Add framework density calculation to GCMC class

* Refactor framework density calculations in GCMC and Widom classes for consistency and clarity

* Fix framework density calculation in GCMC and Widom classes

* Add make_cubic function to transform structures into cubic supercells

* Refactor import statements in gcmc and widom modules for consistency

* Refactor random position using a numpy Generator in GCMC and Widom classes for reproducibility and clarity

* Add note on reproducibility with numpy.random.Generator in changelog

* Cosmetic changes by black

* Refactor random operations into a new module for better organization and reusability

* Remove the older vdw_overlap checks

* Refactor check_overlap function to improve clarity by renaming return value and updating docstring

* Enhance check_overlap function with return type annotation and performance note in docstring

* Update changelog for module path corrections and enhanced clarity

* Add base logger classes

* Abstract the simulation to a BaseSimulator abstract the system state management and general simulation logic.

* Refactor GCMC simulation logging by integrating GCMCLogger for improved output management and clarity

* Add logging enhancements to simulation output management with GCMCLogger and WidomLogger

* Refactor by black and isort

* Remove unused imports from gcmc.py to clean up the code

* Replace print methods with logger calls for improved output management in examples

* Enhance WidomLogger output with detailed simulation start and end messages

* Rename 'cutoff' parameter to 'cutoff_radius' for clarity and update output file paths in BaseSimulator, GCMC, and Widom classes.

* Refactor calculations in Widom class for improved readability and maintainability

* Remove unused import of VERSION from base_simulator.py to clean up the code

* Remove unnecessary newline at the end of run_GeoOpt+GCMC.py for cleaner code

* Add restart method to Widom class and update adsorbate atom references for clarity

* Refactor index calculations in GCMC and improve formatting in Widom class for clarity

* Refactor restart method in Widom class to streamline loading of internal energy data

* Add the cuequivariance-torch on the environment.

* Create a random_mol_insertion method to insert  molecules easier

* Add random seed to examples

* Ensure that all random methods use the same generator

* Apply black for code standardization

* FIx

* Add random seed handling to BaseSimulator and log it in BaseLogger

* Fix random_translation

* Add pyMSER integration for simulation equilibration and average uptake calculation

* Black and isort formating

* Remove unused import of enthalpy_of_adsorption from logger.py

* Refactor crystalOptimization to store convergence status in a variable

* Rename example

* Fix error in optimization convergence check

* Remove unused sys.path modification and streamline convergence print statement in crystalOptimization

* Update README.md to include installation warning and enhance GCMC parameters

* Add automatic supercell option and cutoff radius to GCMC and Widom classes; update examples accordingly

* Add warning for non-ideal supercell size in logger header

* Fix framework mass calculation to ensure it is a float

* Refactor framework mass calculation to use a dedicated method for improved clarity and maintainability

* Remove space

* Update changelog to set release date for version 0.4.0

Author: lipelopesoliveira

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## Unreleased
+## v[X.Y.Z] - YYYY-MM-DD (Unreleased)
 
 ### New Features 🎉
 
@@ -12,7 +12,44 @@
 
 ### Removed 🗑️
 
-## v[0.3.2] - 2025-08-05
+## 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 🎉
 
@@ -45,6 +82,8 @@
 
 ### 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.

README.md

@@ -1,6 +1,8 @@
-# MLP Adsorption
+# <span style="font-size:larger;">MLP Adsorption</span>
 
-This repository contains the MLP Adsorption package, which provides tools for molecular simulations and adsorption studies using machine learning potentials.
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+MLP Adsorption is a general purpose adsorption simulation toolbox built around the Atomic Simulation Environment (ASE), which provides tools for molecular simulations and adsorption studies using machine learning potentials, classical force fields, and other advanced techniques.
 
 ## Requirements
 
@@ -24,6 +26,10 @@ conda env create --file environment.yml
 
 You can install the MLP Adsorption package using pip:
 
+> **Warning**
+>
+> The code is not yet published on PyPI, so you need to install it directly from the GitHub repository.
+
 ```Shell
 pip install git+https://github.com/lipelopesoliveira/mlp_adsorption.git
 ```
@@ -96,21 +102,26 @@ gcmc = GCMC(
     adsorbate_atoms=adsorbate,
     temperature=Temperature,
     pressure=pressure,
-    fugacity_coeff=1,
     device=device,
     vdw_radii=vdw_radii,
     vdw_factor=0.6,
     save_frequency=1,
     debug=True,
     output_to_file=True,
+    criticalTemperature=304.1282,
+    criticalPressure=7377300.0,
+    acentricFactor=0.22394,
+    random_seed=42,
+    cutoff_radius=6.0,
+    automatic_supercell=True,
 )
 
 
-gcmc.print_introduction()
+gcmc.logger.print_header()
 
 gcmc.run(MCSteps)
 
-gcmc.print_finish()
+gcmc.logger.print_summary()
 
 ```
 

environment.yml

@@ -2,7 +2,7 @@ name: mlp_ads
 channels:
   - conda-forge
 dependencies:
-  - python>=3.10
+  - python=3.10
   - pip
   - jupyter
   - jupyterlab
@@ -16,5 +16,6 @@ dependencies:
   - simplejson
   - pip:
     - pymser
+    - cuequivariance-torch
     - mace-torch
     - torch-dftd

examples/Basic/1-Widom/run_widom.py

@@ -50,9 +50,12 @@
     vdw_radii=vdw_radii,
     debug=False,
     output_to_file=True,
+    random_seed=42,
+    cutoff_radius=6.0,
+    automatic_supercell=True,
 )
 
-widom.print_header()
+widom.logger.print_header()
 
 widom.run(NSteps)
-widom.print_footer()
+widom.logger.print_summary()

examples/Basic/2-Rigid_GCMC/run_GCMC.py

@@ -26,7 +26,7 @@
     dispersion=True,
     damping="zero",  # choices: ["zero", "bj", "zerom", "bjm"]
     dispersion_xc="pbe",
-    default_dtype="float32",
+    default_dtype="float64",
     device=device,
 )
 
@@ -51,18 +51,23 @@
     adsorbate_atoms=adsorbate,
     temperature=Temperature,
     pressure=pressure,
-    fugacity_coeff=1,
     device=device,
     vdw_radii=vdw_radii,
     vdw_factor=0.6,
     save_frequency=1,
     debug=True,
     output_to_file=True,
+    criticalTemperature=304.1282,
+    criticalPressure=7377300.0,
+    acentricFactor=0.22394,
+    random_seed=42,
+    cutoff_radius=6.0,
+    automatic_supercell=True,
 )
 
 
-gcmc.print_introduction()
+gcmc.logger.print_header()
 
 gcmc.run(MCSteps)
 
-gcmc.print_finish()
+gcmc.logger.print_summary()

examples/Basic/3-Rigid_GCMC_Isotherm/run_GCMC_Isotherm.py

@@ -63,19 +63,23 @@
         adsorbate_atoms=adsorbate,
         temperature=Temperature,
         pressure=pressure,
-        fugacity_coeff=1,
         device=device,
         vdw_radii=vdw_radii,
         debug=False,
         output_to_file=True,
+        criticalTemperature=304.1282,
+        criticalPressure=7377300.0,
+        acentricFactor=0.22394,
+        cutoff_radius=6.0,
+        automatic_supercell=True,
     )
 
-    gcmc.print_introduction()
+    gcmc.logger.print_header()
 
     if pressure > pressure_list[0]:
         print("Loading previous state for continuation...")
         output_dir = f"results_{Temperature:.2f}_{pressure_list[i-1]:.2f}"
         gcmc.load_state(os.path.join(output_dir, "GCMC_Trajectory.traj"))
 
     gcmc.run(MCSteps)
-    gcmc.print_finish()
+    gcmc.logger.print_summary()

examples/Intermediate/1-Geometry_Optimization_GCMC/run_GeoOpt+GCMC.py

@@ -11,7 +11,7 @@
 from ase.optimize import LBFGS
 from mace.calculators import mace_mp
 
-from mlp_adsorption.ase_utils import crystalOptmization
+from mlp_adsorption.ase_utils import crystalOptimization
 from mlp_adsorption.gcmc import GCMC
 
 warnings.filterwarnings("ignore", category=UserWarning)
@@ -37,7 +37,7 @@
 # Load the framework structure
 framework: ase.Atoms = read(FrameworkPath)  # type: ignore
 
-resultsDict, frameworkOpt = crystalOptmization(
+resultsDict, frameworkOpt = crystalOptimization(
     atoms_in=framework,
     calculator=model,
     optimizer=LBFGS,  # type: ignore
@@ -59,7 +59,7 @@
 # Load the adsorbate structure
 adsorbate: ase.Atoms = read(AdsorbatePath)  # type: ignore
 
-resultsDict, adsorbateOpt = crystalOptmization(
+resultsDict, adsorbateOpt = crystalOptimization(
     atoms_in=adsorbate,
     calculator=model,
     optimizer=LBFGS,  # type: ignore
@@ -94,18 +94,21 @@
     adsorbate_atoms=adsorbateOpt,
     temperature=Temperature,
     pressure=pressure,
-    fugacity_coeff=1,
     device=device,
     vdw_radii=vdw_radii,
     vdw_factor=0.6,
     save_frequency=1,
     debug=True,
     output_to_file=True,
+    criticalTemperature=304.1282,
+    criticalPressure=7377300.0,
+    acentricFactor=0.22394,
+    cutoff_radius=6.0,
+    automatic_supercell=True,
 )
 
-
-gcmc.print_introduction()
+gcmc.logger.print_header()
 
 gcmc.run(MCSteps)
 
-gcmc.print_finish()
+gcmc.logger.print_summary()

examples/Intermediate/2.-MD_GCMC/co2.xyz examples/Intermediate/2-MD_GCMC/co2.xyzexamples/Intermediate/2.-MD_GCMC/co2.xyz renamed to examples/Intermediate/2-MD_GCMC/co2.xyz

@@ -51,21 +51,25 @@
     adsorbate_atoms=adsorbate,
     temperature=Temperature,
     pressure=pressure,
-    fugacity_coeff=1,
     device=device,
     vdw_radii=vdw_radii,
     vdw_factor=0.6,
     save_frequency=1,
     debug=True,
     output_to_file=True,
+    criticalTemperature=304.1282,
+    criticalPressure=7377300.0,
+    acentricFactor=0.22394,
+    cutoff_radius=6.0,
+    automatic_supercell=True,
 )
 
 
-gcmc.print_introduction()
+gcmc.logger.print_header()
 
 for j in range(5):
     gcmc.run(MCSteps)
     gcmc.npt(nsteps=MDSteps, time_step=0.5, mode="aniso_flex")
 
 gcmc.run(MCSteps)
-gcmc.print_finish()
+gcmc.logger.print_summary()