# MonteCarloLib

{{#if: Abel Carreras, Kyoto University, Kyoto, Japan
|

Source authors:
Abel Carreras, Kyoto University, Kyoto, Japan

}}{{#if: MIT |

}}{{#if: GitHub |

}}{{#if: |

Documentation: {{{documentation}}}

}}{{#if:
• Monte Carlo
• |

| {{#if: |

| {{#if: |

| {{#if: |

|{{#if: |

| {{#if: |

|}}}}}}}}}}}}{{#if:
• Monte Carlo
• |

Functionalities:

}}{{#if: |

Algorithms:

{{{algorithms}}}

}}{{#if: |

Generic interfaces:

{{{generic interfaces}}}

}}{{#if: |

APIs:

{{{apis}}}

}}{{#if: |

Data standards:

{{{data standards}}}

}}{{#if: |

Software:

{{{software}}}

}}

MonteCarloLib is a Monte Carlo(MC) library for general purpose which uses Metropolis algorithm to evaluate a general potential function. This library is meant to be used as a way for other programs to easily implement MC simulations capabilities creating a specific potential energy and alteration rutines for each specific case.

## Algorithm

This library uses a generic Metropolis algorithm to evaluate the energy at each. This algorithm can be summarized in the following lines:

```        NewCoordinates = (*AlterationFunction)(Coordinates, Params);
NewEnergy = (*PotentialFunction)(NewCoordinates);

if (Energy < NewEnergy) {
Ratio = exp((Energy - NewEnergy)/(Params.temperature * Params.kb));
RandomNumber = RandomRange(0,1);

if (Ratio < RandomNumber){
free(NewCoordinates);
Acceptation = AcceptationAverage(0);
continue;
}

}
free(Coordinates);
Coordinates = NewCoordinates;
Energy = NewEnergy;
Acceptation = AcceptationAverage(1);
```

This software is designed to be modular and as much flexible as possible to be able to be adapted to different cases. To do that the routines that define the potential, coordinates alteration & random numbers calculation are totally separated and can be substituted or modified easily. The communication of the main program with the library is done mainly through two structure type variables that contains the parameters that the library needs to work and the results obtained form the library. This structure makes also simple to modify adding or removing parameters that can be used along the library cleanly.

## Programming interface

The main interface of this library is placed in the Monteli.cb file which is used along to the Random.c file routines to make the main core of the library. Potential energy and alteration rutines are provided by arguments which can be placed in other parts of the main code.

`MonteCarlo(PotentialFunction, AlterationFunction, conditions Params, LogFile)`

Arguments:

• `PotentialFunction` (input) double*(double*)
Pointer to the function which calculates the potential energy in function of a set of coordinates given by a double type pointer. The return of this function is a double type variable which contains the energy.
• `AlterationFunction`(input) double**(double*)
Pointer ti the function that calculates the alternated coordinates from an original set. This function must allocate a piece of memory inside containing the altered coordinates and return the pointer. This pointer will be deallocated at each step during the main metropolis algorithm.
• `Params` (input) conditions
Structure type variable that contains the conditions at which the Monte Carlo simulation will be carried out. This structure is defined in Montelib.h header file:
• `LogFile` (input/output) FILE*
Pointer to the log file used for writing useful data in the log file of the main program (errors/messages/warnings).

Return:

• `ResultData` (output) results
Structure type variable that contains the resulting data of the MC simulation. That includes the energy, final coordinates and specific heat. This structure type variable is also defined in Montelib.h file and can be easily modified to include additional properties.

Structure type variables

• `conditions`
```typedef struct {
double *coordinates;      //Contains the double type pointer with the initial coordinates
int dimensions;           //Number of coordinates to be used
double factor;            //Initial scale parameter that may be used in the alteration function.
int numberofcycles;       //Total number of MD cycles
double temperature;       //Temperature at which the simulation is carried out
double kb;                //Boltzmann constant (defines the units of energy and temperature)
int takesample;           //Number of cycles to print data in the files
double regulator;         //Parameter used to modify factor in order tot regulate acceptation ratio
FILE* coordinatesfile;    //Pointer to the file in which the coordinates are going to be stored
FILE* energyfile;         //Pointer to the file in which the energy, acceptation, cv, etc. are going to be stored
}conditions;
```
• `results`
```typedef struct {
double *coordinates;      //Pointer to the last coordinates obtained in MC
double energy;            //Final energy
double Cv;                //Final Specific heat (constant volume)
double AcceptationRatio;  //Final acceptation ratio
}results;
```

Note: coordinatesfile and energyfile can be not defined (or defined as NULL), in that case the coordinates and/or energy will not be written.

## Software description and installation

This library has to be compiled along with the main program. MonteLib.c/MonteLib.h contains the main code and is mandatory, as well as Random.c/Random.h which contains the random functions used in the program.

Potential.c/Potential.h and Alteration.c/Alteration.h contains the potential energy functions and alteration routines. These functions are optional, since they only contains example functions for different problems but, of course, if they are not used the main program has to provide its own potential and alteration functions adapted to the desired calculation. The functions contained in those files may be used as example to create new ones.

### Prerequisites

No additional prerequisites aside of standard c libraries.

### Instructions

Compile just using -std=c99 flag. No additional options are necessary.
Compilation of example1:
`gcc -std=c99 -o example1 example/example1.c src/Alteration.c src/Montelib.c src/Potential.c src/Random.c -Isrc`

### Examples

In the examples directory there are three examples that show how to implement different types of MC simulations using different routines for getting the energy and alternating the coordinates.

• Example 1: Single particle in a 2D harmonic potential.
• Example 2: Rotation of 3 independent rotors in a hindered environment defined by a sinusoidal potential.
• Example 3: Set of particles in a 2D periodic box interacting with a Lennard Jones potential.