DOI: 10.5281/zenodo.13826278
title: Size scalability of Monte Carlo simulations applied to oxidized polypyrrole systems: Data and Codes

description: This work generalizes our recently proposed coarse grained force field (CGFF) for halogen oxidized PPy in the condensed phases and introduces a novel implementation of the Nettropolis Monte Carlo (MMC) simulation based on the CGFF that enables simulations of polymer systems with more than100000 particles. The MMC implementation utilizes a combination of CPU and GPUs and exploits a numerical approximation based on polynomial piecewise interpolation for the calculation of the CGFF pairwise additive terms. Our simulations evidence that the oxidized PPy thermodynamic and structural properties are consistent as the system size is scaled up. Predicted properties include density, enthalpy, potential energy, heat capacity, coefficient of thermal expansion, caloric curve, glass transition temperature range, compressibility, bulk modulus, radial distribution functions, and polymer chain characteristics.
description: Documentation for the Metropolis Monte Carlo Simulation of Polypyrroles

Publication: Size scalability of Monte Carlo simulations applied to oxidized polypyrrole systems 

Greg Helmick, Yoseph Abere and Estela Blaisten-Barojas

Computational Materials Science 247 (2025) 113538; DOI:10.1016/j.commatsci.2024.113538

1   1. Overview

This is a C++ project developed for conducting Monte Carlo simulations, with a focus on oxidized polypyrrole systems. It combines GPU acceleration and parallel processing with MPI to efficiently compute various properties across multiple nodes. The project is highly configurable through input files and can be built using CMake.

.    2. Requirements

·  C++ compiler with C++11 support.

·  CUDA Toolkit.

·  MPI Library.

·  CMake (version 3.10 or higher).

     3. List of the 24 enclosed file






appConfig_npt_br.conf



getopt_pp_standalone.h



model-params_i.txt





appConfig_npt_cl.conf



getopt_pp.cpp



model-params.txt





appConfig_npt_f.conf



getopt_pp.h



ModelPotential.cpp





appConfig_npt_i.conf



gpuHelper.cu



ModelPotential.h





appConfig_nvt_br.conf



gpuHelper.cuh



MyRandom.h





appConfig_nvt_cl.conf



Logger.cpp



polymerUtil.cpp





appConfig_nvt_f.conf



Logger.h



polymerUtil.h





appConfig_nvt_i.conf



main.cpp



Random.cpp





AppConfig.h



Model-params_br.txt



Random.h





CMakeLists.txt



model-params_cl.txt



util.h





cuUtil.cuh



model-params_f.txt



 





 These files should be put in a directory termed cuSMMC. Their explanation follows:

3.1  Source files

·     main.cpp: The entry point for the application.

·     gpuHelper.cu: Contains functions and helpers optimized for GPU computation.

·     polymerUtil.cpp: Provides utilities for polymer-related calculations.

·     Random.cpp: Implements random number generation utilities.

·     ModelPotential.cpp: Defines the model potentials for the simulation.

·     Logger.cpp: Handles logging throughout the application.

·     getopt_pp.cpp: It helps for parsing command-line options.

3.2 Include/: header files

·     AppConfig.h: Configuration management.

·     cuUtil.cuh: Utility functions for CUDA.

·     gpuHelper.cuh: Header for GPU helpers.

·     Logger.h: Logging utilities.

·     ModelPotential.h: Header for potential modeling.

·     MyRandom.h: Random number generator class.

·     polymerUtil.h: Header for polymer utilities.

·     Random.h: Header for random utilities.

·     util.h: General utility functions.

·     getopt_pp.h: Header file defining the public interface and classes for the GetOpt_pp library, including option parsing and handling.

·     getopt_pp_standalone.h: A standalone header file that includes both the interface and implementation of GetOpt_pp.

3.3  Input files

·  appConfig_npt_br.conf: Bromine dopant input file for NPT simulation

·  appConfig_npt_cl.conf: Chlorine dopant input file for NPT simulation

·  appConfig_npt_f.conf: Fluorine dopant input file for NPT simulation

·  appConfig_npt_i.conf: Iodine dopant input file for NPT simulation

·  appConfig_nvt_br.conf: Bromine dopant input file for NVT simulation

·  appConfig_nvt_cl.conf: Chlorine dopant input file for NVT simulation

·  appConfig_nvt_f.conf: Fluorine dopant input file for NVT simulation

·  appConfig_nvt_i.conf: Iodine input file for NVT simulation

·  CMakeLists.txt: CMake configuration file

·     model-params.txt: this file needs to be populated by copying one of the following 4 files:

i)   model-params_br.txt: database with numerical approximation parameters for the CGFF of PPy with bromine dopants

ii)   model-params_cl.txt: database with numerical approximation parameters for the CGFF of PPy with chlorine dopants

iii)   model-params_f.txt: database with numerical approximation parameters for the CGFF of PPy with fluorine dopants

iv)   model-params_i.txt: database with numerical approximation parameters for the CGFF of PPy with iodine dopants

    4. Compilation

Ensure you have the necessary dependencies installed, including a suitable C++ compiler, the CUDA toolkit, and an MPI library. Use the following steps to compile the project:

    -- mkdir bin

    -- cd bin

     -- mkdir intermediate

     -- cmake ../cuSMMC/ -DCMAKE_BUILD_TYPE=Release

    -- make

      Alternatively, you can use:

·  -- cmake ../cuSMMC/ -DCMAKE_BUILD_TYPE=RELEASE && make

Note: The intermediate folder will save intermediate steps outputs of the simulation in .xyz and .bin formats, which can be used for a restart.

    5. Configuration possibilities:

      5.1   CMake Configuration

The CMakeList.txt configuration file sets the minimum version of CMake required to build the project to 3.10, which includes support for CUDA as a first-class language.

      5.2   Conditional Compilation (Windows vs. Linux)

The file uses an if-else structure to provide different configurations for Windows and non-Windows (presumably Linux) systems.

      5.3   Windows-specific configuration:

 --  PROJECT(cuSMMC_hybrid LANGUAGES CXX CUDA): Defines the project name and specifies C++ and CUDA as the languages used.

--  add_definitions(...): Several preprocessor definitions are added:

--  -D__MINIMIZE_OUTPUT__: Reduces output for speed optimization.

--  -D__MAXIMUM_SPEED__: Enables maximum speed optimizations.

--  -D__INDIVIDUAL_PARTICLE_VOLUME_ACC_RATE__: Likely related to volume acceptance rate calculations. 

--  -D__USE_UNIFORM_SCALE__: Enables uniform scaling.

--  FILE(GLOB SOURCES ".cu" ".cuh" ".cpp" ".c" "*.h"): Gathers all source files with the specified extensions.

--  ADD_EXECUTABLE(cuSMMC_hybrid ${SOURCES}): Creates the executable from the gathered source files.

--  CMAKE_CUDA_STANDARD is set to 11 if not already defined.

--  find_package(OpenMP) and find_package(MPI REQUIRED): Finds and links OpenMP and MPI libraries.

             --  CUDA compilation flags are set, including C++11 support, optimization level O3, and various CUDA-specific options.

      5.4   Linux-specific configuration:

Similar to Windows, but with some differences:





Explicitly finds CUDA package.

Adds -D__USE_GPU__ definition.

Uses CUDA_ADD_EXECUTABLE instead of ADD_EXECUTABLE.



      5.5   Common configurations:

CUDA flags for both platforms include:





Optimization flags (-O3).

Architecture-specific code generation (-gencode arch=compute_60, code=sm_60).

Stream configuration (--default-stream per-thread).



   6. Commented-out options:

      Several add definitions are commented out, suggesting optional features:





USE_FLOAT: Option to use float instead of double.

USE_SIMPLE_POLYNOMIAL, USE_INLINE_HERMITE_SPLINE, USE_INLINE_SPLINE: Different interpolation methods.

WEIGHTED_VOLUME_ACC_RATE, COMBINED_PARTICLE_ACC_RATE: Alternative acceptance rate calculations.



     7. CUDA-specific settings:

·     CUDA separable compilation is enabled for Windows.

·     CUDA host flags propagation is disabled for Linux.

·     Include directories: CUDA include directories are added to the include path.

     8. Running the simulation

The simulation input in which a database is used (numerical approximation based on polynomial piecewise interpolation) is provided for each of the four dopants. These files need to be copied into the corresponding generic file that does not contain the specific dopant as follows:



Numerical approximation files: model-params_{dopant}.txt

Sample input files for NPT simulations: appConfig_npt_{dopant}.conf

Sample input Files for NVT simulations: appConfig_nvt_{dopant}.conf


Use the correct input file based on the simulation needed. For example, to run an NPT simulation for a fluorine dopant at a temperature of 300K and 1 atm pressure:

./cuSMMC -n 12 -t 300 -s 1 -p 1.0 -c appConfig_npt_f.conf

If restarting from the last simulation configuration, use:

./cuSMMC -n 12 -t 300 -s 1 -p 1.0 -c appConfig_npt_f.conf -f after_300.bin

Please copy the numerical approximation file and rename it by removing the dopant suffix. For example, rename model-params_f.txt to model-params.txt.

The appConfig_{dopant}.conf file is the main configuration file where the size of the system, number of iterations, charges, constants, simulation parameters, etc., are set. The model-params.txt file is generated based on the type of dopants, their parameters, and the size of the system. It is a numerical approximation based on polynomial piecewise interpolation for the calculation of the coarse-grained force field pairwise additive terms.

       9. Command Line Arguments



-n <number of processes>: Specifies the number of processes for parallel computing.

-t <temperature>: Sets the temperature for the simulation.

-s <simulation type>: Simulation types. (0–NVT, 1-NPT, …)

-p <pressure>: Pressure of the system (used in NPT simulations).

-c <config_file>: Path to the configuration file.

-f <restart_file>: (Optional) Path to a binary file to restart the simulation from a previous state.


1   10. Some output files



sys_energy_300.csv: CSV file containing system energy data when the simulation is run at 300K.

after_300.bin: Binary file for restarting the simulation.

after_300.xyz: XYZ format file of the system configuration after 300K simulation.

working_300.xyz: Working XYZ format file of the system configuration.


1    11. Features



GPU and CPU support: Optimized for GPU computation with the capability to switch to CPU if needed.

MPI and parallel processing: Leverages MPI to distribute computations across multiple processors, enhancing simulation speed and scalability.

Ensemble simulations: Supports both NPT (constant number of particles, pressure, and temperature) and NVT (constant number of particles, volume, and temperature) simulations.

Modular design: Includes modules for random number generation, potential modeling, and logging, making the codebase easy to extend and maintain.

Configurable Input: Extensive configurability through a single input file for various simulation parameters.

Restart capability: Ability to restart simulations from a saved state, allowing for long-running simulations to be paused and resumed.

Output: Generates a wide range of output files, including energy logs, state configurations in multiple formats.