Add documentation (#53)

Author: romainljsimon

.gitignore

@@ -8,13 +8,13 @@ Manifest.toml
 *.xyz
 *.out
 *.err
-*.pdf
 *.DS_Store
 *.gz
 *.cov
 log_output/
 log_error/
 data/*
 deps/build.log
+docs/build/*
 
 !config_0.xyz

README.md

@@ -1,5 +1,5 @@
 <h1 align="center">
-  <img src="particlesmc_logo.png" width="500"/>
+  <img src="https://raw.githubusercontent.com/TheDisorderedOrganization/ParticlesMC/main/logo.png" width="500"/>
 </h1>
 
 <div align="center">
@@ -16,7 +16,7 @@ ParticlesMC is a Julia package for performing atomic and molecular Monte Carlo s
 </p>
 
 <p align="center">
-  <img src="https://github.com/TheDisorderedOrganization/ParticlesMC/blob/main/examples/movie/movie.gif" alt="MC simulation of a 2D liquid" width="400">
+  <img src="https://raw.githubusercontent.com/TheDisorderedOrganization/ParticlesMC/main/examples/movie/movie.gif" alt="MC simulation of a 2D liquid" width="400">
 </p>
 
 <p align="center">

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+ParticlesMC = "98828e2c-de49-11ef-324d-d77a22de11e4"
+
+[compat]
+Documenter = "1.8"

docs/make.jl

@@ -0,0 +1,34 @@
+using Documenter
+using ParticlesMC
+
+readme = read(joinpath(@__DIR__, "..", "README.md"), String)
+html_part = readme[1:findlast("</p>", readme)[end]]
+html_part = replace(html_part, r"<div align=\"center\">[\s\S]*?</div>" => "")
+md_part = readme[findlast("</p>", readme)[end]+1:end]
+readme = "```@raw html\n" * html_part * "\n```\n" * md_part
+write(joinpath(@__DIR__, "src", "index.md"), readme)
+
+makedocs(
+    sitename = "ParticlesMC",
+    format = Documenter.HTML(;
+        prettyurls = get(ENV, "CI", nothing) == "true",
+        size_threshold_ignore = ["api.md"],
+        sidebar_sitename = false
+    ),
+    modules = [ParticlesMC],
+    warnonly = [:missing_docs],
+    pages = [
+        "Home" => "index.md",
+        "Manual" => Any[
+            "man/particlesmc.md",
+            "man/architecture.md",
+            "man/simulations.md"
+        ],
+        "API" => "api.md",
+    ]
+)
+
+# Deploying to GitHub Pages
+deploydocs(;
+    repo = "github.com/TheDisorderedOrganization/ParticlesMC.git",
+)

docs/src/api.md

@@ -0,0 +1,20 @@
+# API
+
+This is the documentation of the ParticlesMC module's functions, types and structures.
+
+# API Reference
+
+```@meta
+CurrentModule = ParticlesMC
+```
+
+## Index
+
+```@index
+```
+
+## Types and Functions
+
+```@autodocs
+Modules = [ParticlesMC]
+```

docs/src/assets/goodpolicy.pdf

@@ -0,0 +1,134 @@
+```@raw html
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/TheDisorderedOrganization/ParticlesMC/main/logo.png" width="500"/>
+</h1>
+
+
+
+<p align="center">
+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 <a href="https://github.com/TheDisorderedOrganization/Arianna.jl"> Arianna </a> module, it leverages Arianna’s Monte Carlo framework.
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/TheDisorderedOrganization/ParticlesMC/main/examples/movie/movie.gif" alt="MC simulation of a 2D liquid" width="400">
+</p>
+
+<p align="center">
+  MC simulation of a 2D liquid. This example can be reproduced by running <code>particlesmc params.toml</code> in the <code>examples/movie/</code> folder. Movie generated with <a href="https://www.ovito.org/"> ovito</a>.
+</p>
+```
+
+
+## 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.

docs/src/assets/maniac.jpg

@@ -0,0 +1,58 @@
+
+# Package Architecture
+
+The package adopts a modular architecture, with each module responsible for a distinct component of the simulation workflow. 
+
+## Core systems
+
+Two fundamental data structures represent physical systems: the **Atoms** struct for atomic systems and the **Molecules** struct for molecular systems. 
+Both structures inherit from the abstract **Particles** type, which itself is a subtype of **AriannaSystem** (see *Arianna* [types](https://thedisorderedorganization.github.io/Arianna.jl/stable/man/system/)). 
+This design allows the use of the [*Arianna.jl*](https://github.com/TheDisorderedOrganization/Arianna.jl) framework. The **Atoms** struct encapsulates properties such as particle positions, 
+atom types, and interaction potentials. The **Molecules** struct extends the **Atoms**  struct by including bond information (type and interaction potential).
+
+Users can choose from a variety of potentials for calculating interactions between particles. The interactions depend solely on the type of the particles.
+For molecular systems, users choose potentials for both bonded particles and non-bonded particles. The interactions depend on the type of particles for 
+non-bonded interactions and on the type of bond for bonded interactions.
+
+In both cases, the target distribution is the Boltzmann distribution and thus, 
+simulations are performed in the canonical ensemble (constant number of particles, volume, and temperature). An extension to perform
+simulations in the NPT ensemble (constant number of particles, pressure, and temperature) is in current development.
+
+## Monte Carlo Moves
+
+To use the [*Arianna.jl*](https://github.com/TheDisorderedOrganization/Arianna.jl) framework, the package implements moves defined through actions and policies, as described in the previous [section](https://thedisorderedorganization.github.io/ParticlesMC/stable/man/particlesmc). 
+The package provides a collection of predefined actions and policies corresponding to standard and state-of-the-art Monte Carlo moves in atomic and molecular simulations:
+
+- Standard displacement moves.
+- Swap moves for particle exchange in atomic systems.
+- Flip moves in molecular systems.
+- Intramolecular swap moves in polymeric systems.
+
+Each action supports multiple policy implementations. For instance, displacement moves can employ either normal 
+or uniform probability distributions for trial move generation.
+
+All moves are designed to be compatible with both the Metropolis-Hastings algorithm and the Policy-Guided Monte Carlo (PGMC) method of Arianna.
+This means that all functions required by the *Arianna.jl* framework (see *Arianna* [moves](https://thedisorderedorganization.github.io/Arianna.jl/stable/man/system/)) are implemented for each action and policy.
+
+## Neighbour Lists
+
+The package incorporates efficient neighbor list algorithms[^1] to accelerate interaction computations between particles.
+Users can choose two neighbor list implementations, **LinkedList** and **EmptyList**. Both structs are subtypes of the 
+**NeighbourList** type. The **EmptyList** is a dummy neighbour list that does not store any information, and thus 
+the interaction between particles is computed by looping over all the particles. The **LinkedList** struct is 
+a cell list implementation that divides the simulation box into cells of size larger that the maximul cutoff of the interaction
+potentials. This permits to calculate the potential energy of a particle by only calculating its interactions with particles 
+inside the neighbouring cells. For large systems, using the **LinkedList** struct accelerates significantly simulations 
+compared to using the **EmptyList** struct. 
+
+
+## Input/Output
+
+The package handle file operations, supporting configuration import from *.xyz*, *.exyz*, and *.lammps* formats.
+The package can also write the output trajectories in these same formats, providing users flexibility in choosing their preferred file format 
+for data storage and analysis.
+
+Additionally, the package provides callback functions for on-the-fly calculation of thermodynamic and structural properties during simulations, 
+including energy and pressure for both atomic and molecular systems. These callbacks are stored in the output directory for post-processing.
+
+[^1]: *Computer simulation of liquids*, Allen, Michael P and Tildesley, Dominic J, 2017