https://github.com/thedisorderedorganization/particlesmc
Package to run atomic / molecular Monte Carlo simulations
https://github.com/thedisorderedorganization/particlesmc
julia julialang markov-chain-monte-carlo molecular-simulation monte-carlo monte-carlo-simulation physics-simulation
Last synced: 24 days ago
JSON representation
Package to run atomic / molecular Monte Carlo simulations
- Host: GitHub
- URL: https://github.com/thedisorderedorganization/particlesmc
- Owner: TheDisorderedOrganization
- License: gpl-3.0
- Created: 2025-01-29T13:29:57.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-05-23T10:26:00.000Z (5 months ago)
- Last Synced: 2025-06-05T10:13:43.060Z (4 months ago)
- Topics: julia, julialang, markov-chain-monte-carlo, molecular-simulation, monte-carlo, monte-carlo-simulation, physics-simulation
- Language: Julia
- Homepage:
- Size: 63.1 MB
- Stars: 18
- Watchers: 0
- Forks: 0
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.bib
Awesome Lists containing this project
README
[](https://github.com/TheDisorderedOrganization/ParticlesMC/blob/main/LICENSE)
[](https://github.com/TheDisorderedOrganization/ParticlesMC/actions/workflows/ci.yml)
[](https://github.com/JuliaTesting/Aqua.jl)
[](https://codecov.io/gh/TheDisorderedOrganization/ParticlesMC)
ParticlesMC is a Julia package for performing atomic and molecular Monte Carlo simulations. It is designed to be efficient and user-friendly, making it suitable for both research and educational purposes. Built on top of the Arianna module, it leverages Arianna’s Monte Carlo framework.
MC simulation of a 2D liquid. This example can be reproduced by running particlesmc params.toml in the examples/movie/ folder. Movie generated with ovito.
## Features
- **Flexible execution**: Simulations can be run from standalone scripts or through a command-line interface (CLI), enabling easy integration into workflows.
- **Interaction potentials**: Supports a broad range of interatomic and intermolecular interaction potentials.
- **Monte Carlo moves**: Implements state-of-the-art Monte Carlo moves for both atomic and molecular simulations.
- **Computational efficiency**: Designed with performance in mind to enable fast simulations.
- **Arianna framework integration**: Leverages the [Arianna](https://github.com/TheDisorderedOrganization/Arianna.jl) Monte Carlo framework, benefiting from advanced techniques such as Policy-Guided Monte Carlo (PGMC) and parallel tempering (soon).
## Installation
### Requirements
- Julia version 1.9 or higher
### Installing ParticlesMC
You can install ParticlesMC using the Julia package manager in one of two ways:
1. Using the package mode (press `]` in the Julia REPL):
```julia
add https://github.com/TheDisorderedOrganization/ParticlesMC.git
```
2. Using the Pkg API:
```julia
using Pkg
Pkg.add(url="https://github.com/TheDisorderedOrganization/ParticlesMC.git")
```
### Building ParticlesMC
The build should be automatic when installing `ParticlesMC`. If it hasn't, you can manually build the package, by entering the package mode (press `]` in the Julia REPL) and by typing:
```julia
build
```
This will build the `particlesmc` executable at `~/.julia/bin` (please add this path to your PATH).
## Usage
### Running a Monte Carlo Simulation
To run a Monte Carlo simulation, you need an input atomic or molecular configuration file (typically with a `.xyz` extension) and a parameter file (in `TOML` format). The parameter file specifies both the system details (such as temperature, density, and interaction model) and the simulation details (such as simulation type, number of steps, Monte Carlo moves, and outputs). A minimal example is presented below. More detailed explanations can be found in the documentation.
**config.xyz**
```
3
Lattice="1.7321 0.0 0.0 0.0 1.7321 0.0 0.0 0.0 0.0" Properties=type:I:1:pos:R:2
1 0.1585 0.4965
1 1.7215 0.7468
1 0.7606 1.1439
```
**params.toml**
```toml
[system]
config = "config.xyz"
temperature = 1.0
density = 1.0
list_type = "LinkedList"
[model]
[model."1-1"]
name = "LennardJones"
epsilon = 1.0
sigma = 1.0
rcut = 2.5
[simulation]
type = "Metropolis"
steps = 500
seed = 10
parallel = false
output_path = "./"
[[simulation.move]]
action = "Displacement"
probability = 1.0
policy = "SimpleGaussian"
parameters = {sigma = 0.05}
[[simulation.output]]
algorithm = "StoreTrajectories"
scheduler_params = {linear_interval = 50}
fmt = "XYZ"
```
**Explanation of the example:**
This example defines a minimal Monte Carlo simulation setup:
- The `[system]` section specifies the input configuration file (`config.xyz`), the simulation temperature and density, and the use of a linked list for neighbor searching.
- The `[model]` section defines the interaction potential between particles. Here, a Lennard-Jones potential is used for species pair "1-1" with specified parameters (`epsilon`, `sigma`, and cutoff `rcut`).
- The `[simulation]` section sets the simulation type to Metropolis, the number of Monte Carlo steps to 500, the random seed, whether to run in parallel, and the output path.
- The `[[simulation.move]]` section describes the Monte Carlo move to use: a displacement move with probability 1.0, guided by a simple Gaussian policy with a standard deviation (`sigma`) of 0.05.
- The `[[simulation.output]]` section configures the output: trajectories will be stored every 50 steps in the XYZ format.
By executing `particlesmc params.toml` you will run a basic Metropolis Monte Carlo simulation of particles interacting via the Lennard-Jones potential, using displacement moves, and periodically saving the system's trajectory.
## Contributing
We welcome contributions from the community. If you have a new system or feature to add, please fork the repository, make your changes, and submit a pull request.
## Citing
If you use Arianna in your research, please cite it! You can find the citation information in the [CITATION](https://github.com/TheDisorderedOrganization/ParticlesMC/blob/main/CITATION.bib) file or directly through GitHub's "Cite this repository" button.
## License
This project is licensed under the GNU General Public License v3.0. License. See the [LICENSE](https://github.com/TheDisorderedOrganization/ParticlesMC/blob/main/LICENSE) file for details.
## Contact
For any questions or issues, please open an issue on the GitHub repository or contact the maintainers.