175 lines
4.5 KiB
Python
175 lines
4.5 KiB
Python
"""
|
||
DICE Monte Carlo Simulation Interface
|
||
=====================================
|
||
|
||
This package provides utilities for configuring and running simulations with
|
||
the DICE Monte Carlo molecular simulation program.
|
||
|
||
DICE performs statistical sampling of molecular systems using the Metropolis
|
||
Monte Carlo algorithm. Simulations are defined by text input files containing
|
||
keywords that control the thermodynamic ensemble, system composition, and
|
||
simulation parameters.
|
||
|
||
---------------------------------------------------------------------
|
||
|
||
Simulation Ensembles
|
||
--------------------
|
||
|
||
DICE supports multiple statistical ensembles.
|
||
|
||
NVT
|
||
Canonical ensemble where the following properties remain constant:
|
||
|
||
- N: number of molecules
|
||
- V: system volume
|
||
- T: temperature
|
||
|
||
The system density is fixed and the simulation box volume does not change
|
||
during the simulation.
|
||
|
||
NPT
|
||
Isothermal–isobaric ensemble where the following properties remain constant:
|
||
|
||
- N: number of molecules
|
||
- P: pressure
|
||
- T: temperature
|
||
|
||
The simulation box volume is allowed to fluctuate in order to maintain the
|
||
target pressure.
|
||
|
||
---------------------------------------------------------------------
|
||
|
||
Simulation Stages
|
||
-----------------
|
||
|
||
Simulations are typically executed in multiple stages.
|
||
|
||
Thermalization (TER)
|
||
Initial phase where the system relaxes to the desired thermodynamic
|
||
conditions. Molecular configurations stabilize and the system reaches
|
||
equilibrium.
|
||
|
||
During this stage statistical properties are **not accumulated**.
|
||
|
||
Production / Equilibration (EQ)
|
||
Main sampling phase after the system has equilibrated.
|
||
|
||
Statistical properties such as energies, densities, and radial
|
||
distribution functions are collected and configurations may be saved
|
||
for later analysis.
|
||
|
||
---------------------------------------------------------------------
|
||
|
||
Typical Simulation Pipeline
|
||
---------------------------
|
||
|
||
Two common execution workflows are used.
|
||
|
||
NVT Simulation
|
||
Used when the system density is known.
|
||
|
||
1. NVT.ter → thermalization at constant density
|
||
2. NVT.eq → production sampling
|
||
|
||
NPT Simulation
|
||
Used when the equilibrium density is unknown.
|
||
|
||
1. NVT.ter → initial thermalization at approximate density
|
||
2. NPT.ter → pressure relaxation (volume adjustment)
|
||
3. NPT.eq → production sampling at target pressure
|
||
|
||
---------------------------------------------------------------------
|
||
|
||
DICE Input Keywords
|
||
-------------------
|
||
|
||
The following keywords are used in the generated input files.
|
||
|
||
title
|
||
Descriptive title printed in the simulation output.
|
||
|
||
ncores
|
||
Number of CPU cores used by the DICE executable.
|
||
|
||
ljname
|
||
File containing Lennard-Jones parameters and molecular topology.
|
||
|
||
outname
|
||
Prefix used for simulation output files.
|
||
|
||
nmol
|
||
Number of molecules of each species in the system.
|
||
|
||
dens
|
||
System density (g/cm³). Used only in NVT simulations or for
|
||
initialization of NPT runs.
|
||
|
||
press
|
||
Target pressure used in NPT simulations.
|
||
|
||
temp
|
||
Simulation temperature.
|
||
|
||
nstep
|
||
Number of Monte Carlo cycles executed in the simulation stage.
|
||
|
||
init
|
||
Defines how the simulation initializes molecular coordinates.
|
||
|
||
yes
|
||
Random initial configuration.
|
||
|
||
no
|
||
Continue from a previous configuration.
|
||
|
||
yesreadxyz
|
||
Read coordinates from a previously saved XYZ configuration.
|
||
|
||
vstep
|
||
Frequency of volume-change moves in NPT simulations.
|
||
|
||
mstop
|
||
Molecule displacement control flag used internally by DICE.
|
||
|
||
accum
|
||
Enables or disables accumulation of statistical averages.
|
||
|
||
iprint
|
||
Frequency of simulation information printed to the output.
|
||
|
||
isave
|
||
Frequency at which configurations are written to trajectory files.
|
||
|
||
irdf
|
||
Controls calculation of radial distribution functions.
|
||
|
||
seed
|
||
Random number generator seed used by the Monte Carlo algorithm.
|
||
|
||
upbuf
|
||
Buffer size parameter used internally by DICE during thermalization.
|
||
|
||
---------------------------------------------------------------------
|
||
|
||
Output Files
|
||
------------
|
||
|
||
Important output files produced during the simulation include:
|
||
|
||
phb.xyz
|
||
XYZ trajectory containing sampled molecular configurations.
|
||
|
||
last.xyz
|
||
Final configuration of the simulation, often used as the starting
|
||
configuration for the next simulation cycle.
|
||
|
||
---------------------------------------------------------------------
|
||
|
||
References
|
||
----------
|
||
|
||
DICE is a Monte Carlo molecular simulation program developed primarily
|
||
by researchers at the University of São Paulo (USP) for studying liquids,
|
||
solutions, and solvation phenomena.
|
||
"""
|