# EasyIsing
This is a Python module that performs the simulation of the Ising model on a square lattice using the Metropolis algorithm. Initially, this tool was made to be used in courses on data analysis or statistical mechanics so that students could generate their own data without having to build a simulator from scratch.
Nevertheless, it contains reasonably clean code with minimal optimizations that can be copied and modified, making it easier for undergraduate students to start their projects.
It is important to note that this module describes the Ising system in terms of a reduced set of variables, which is a common practice.
In other words, $\frac{E}{J}(\{\sigma\}) = -\sum_{(i,j)}\sigma_i \sigma_j - \frac{H}{J} \sum_i \sigma_i$
, where the reduced energy is denoted as $\frac{E}{J}$, the reduced magnetic field as $\frac{H}{J}$, and the reduced temperature $t$ is the inverse of $\beta$, where $\beta = \frac{J}{T k_B}$ and $k_B$ is the Boltzmann constant.
The square lattice is a network of sites, each of which has four immutable connections/interactions with other sites, known as nearest neighbors, indicated by $(i,j)$ under the summation symbol. This is translated into an array of size $L$ by $L$, with periodic boundary conditions, where the elements are integers with values of $\sigma=1$ or $\sigma=-1$, representing a spin-up or a spin-down, respectively.
There is some freedom in the Metropolis algorithm, allowing for the choice of how to change spins in any way that satisfies the detailed balance condition. Typically, one site is chosen randomly because there are no particular reasons to favor one site over another. All sites are equivalent and, due to periodic boundary conditions, are indistinguishable even spatially.
The checkerboard decomposition parallelization approach consists of separating the lattice into two sub-lattices of the same size, like a chessboard. Since the interactions are restricted to first neighbors, there is no interaction between sites of the same sub-lattice. One can update all sites of a sub-lattice at once, which is a common approach to parallelizing Ising-like models.
Both random sequential and checkerboard parallelization should have the same equilibrium properties since both satisfy the detailed balance condition.
This library contains four classes, each with a different implementation:
|Class | Name | Description |
| :--- | :---: | :--- |
|EasyIsing.Ising | Python | Vanilla, traditional random sequential site selection.|
|EasyIsing.IsingC | C | Same as above, but in C. The source code will be compiled and saved in the working directory and called through numpy.ctypeslib.|
|EasyIsing.IsingNumpy | NumPy | Checkerboard decomposition model parallelization scheme using NumPy array functions.|
|EasyIsing.IsingCupy | CuPy | Same as above, but in CuPy to run on the GPU. Note that this class will only be loaded if CuPy is detected.|
With different [performances](examples/Performance.ipynb):
<picture>
<img src="examples/performance.png">
</picture>
It is assumed that the reader/user is being instruted about Ising model and [Metropolis Algorithm](https://en.wikipedia.org/wiki/Equation_of_State_Calculations_by_Fast_Computing_Machines
).
So, no futher information will be provided.
### Instalation
```Shell
pip install EasyIsing
```
### Usage
When imported, there are four classes of objects that can be used.
The user just have to create an instance with the desired arguments.
For example:
```Python
import EasyIsing
L = 10
age = 1000
sample = 1000
T = 2.1
H = 0
seed = 84598945
mac = EasyIsing.IsingNumpy(L, seed)
mac.update(age,T,H)
R = mac.sampling(sample,T,H)
print(R)
```
EasyIsing.Ising.sampling return a dict with the data accumulated.
```JSON
{'temperature': 2.1,
'field': 0,
'age': 2000,
'sampleSize': 1000,
'length': 10,
'seed': 84598945,
'energy1': -167.976,
'magnet1': -88.684,
'energy2': 28579.168,
'magnet2': 7945.392,
'name': 'Numpy'}
```
There is a few examples in directory examples:
* [Specific heat](examples/SpecificHeat.ipynb)
* [Magnetic Hysteresis](examples/MagneticHysteresisLoop.ipynb)
* [performances](examples/Performance.ipynb)
The user can override 'EasyIsing.Ising.sampling' to accumulate other data, or create custom sampling routine. For example, to include the spatial correlation function or 'energy4' and 'magnet4' to calculate Binder's coefficient.
## Suggestions
Here are some suggestions for fun things students can do and analyze using the Ising model simulation:
* Observe the system "walking" to equilibrium with different initial states.
* Analyze the size of error bars for energy, magnetization, etc. as a function of sample size and lattice size.
* Explore specific heat and magnetic susceptibility using the Fluctuation-Dissipation Theorem and derivatives.
* Calculate the entropy of the system.
* Compare Binder's coefficient with histogram results.
* Analyze critical coefficients.
* Study cluster statistics.
* Analyze the radial distribution function and the Virial expansion.
* Explore magnetic hysteresis using the Magnetic Hysteresis Loop example provided in the EasyIsing module.
<picture>
<img src="examples/magnetization.png">
</picture>
<picture>
<img src="examples/specificHeat.png">
</picture>
<picture>
<img src="examples/mh2.8.jpg">
</picture>
## Conclutions
Conclusively, C is an excellent choice for single-threaded performance.
I expect similar performance for FORTRAN, Rust, and C++.
For larger systems, delegating the work to a GPU is by far the better option.
Systems of size $L=128$ are big enough for most projects.
As we can see, for my test machine, for size $L=128$, with the exception of pure Python, the performance of all examples is similar.
Several improvements can be made to increase performance, but they will cost development time and increase the chance of mistakes.
Machine specifications:
Intel® Core™ i7-8700K CPU @ 3.70GHz,
GeForce GTX 1080 Ti,
Ubuntu 22.04.1 LTS,
Python 3.10.4,
gcc version 11.2.0 (Ubuntu 11.2.0-19ubuntu1)
Raw data
{
"_id": null,
"home_page": null,
"name": "EasyIsing",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Ising,Lattice gas,Metropolis,Monte Carlo,Statistical mechanics",
"author": null,
"author_email": "\"Henrique S. Guidi\" <henriquesguidi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e2/10/d9384843d3463e9c4554d3b5e9efdcab94c641536dd8cfba719f2dd7ab9c/easyising-0.1.0.tar.gz",
"platform": null,
"description": "# EasyIsing\n\nThis is a Python module that performs the simulation of the Ising model on a square lattice using the Metropolis algorithm. Initially, this tool was made to be used in courses on data analysis or statistical mechanics so that students could generate their own data without having to build a simulator from scratch.\n\nNevertheless, it contains reasonably clean code with minimal optimizations that can be copied and modified, making it easier for undergraduate students to start their projects.\n\nIt is important to note that this module describes the Ising system in terms of a reduced set of variables, which is a common practice.\nIn other words, $\\frac{E}{J}(\\{\\sigma\\}) = -\\sum_{(i,j)}\\sigma_i \\sigma_j - \\frac{H}{J} \\sum_i \\sigma_i$\n, where the reduced energy is denoted as $\\frac{E}{J}$, the reduced magnetic field as $\\frac{H}{J}$, and the reduced temperature $t$ is the inverse of $\\beta$, where $\\beta = \\frac{J}{T k_B}$ and $k_B$ is the Boltzmann constant.\n\nThe square lattice is a network of sites, each of which has four immutable connections/interactions with other sites, known as nearest neighbors, indicated by $(i,j)$ under the summation symbol. This is translated into an array of size $L$ by $L$, with periodic boundary conditions, where the elements are integers with values of $\\sigma=1$ or $\\sigma=-1$, representing a spin-up or a spin-down, respectively.\n\nThere is some freedom in the Metropolis algorithm, allowing for the choice of how to change spins in any way that satisfies the detailed balance condition. Typically, one site is chosen randomly because there are no particular reasons to favor one site over another. All sites are equivalent and, due to periodic boundary conditions, are indistinguishable even spatially.\n\nThe checkerboard decomposition parallelization approach consists of separating the lattice into two sub-lattices of the same size, like a chessboard. Since the interactions are restricted to first neighbors, there is no interaction between sites of the same sub-lattice. One can update all sites of a sub-lattice at once, which is a common approach to parallelizing Ising-like models.\n\nBoth random sequential and checkerboard parallelization should have the same equilibrium properties since both satisfy the detailed balance condition.\n\nThis library contains four classes, each with a different implementation:\n\n|Class | Name | Description |\n| :--- | :---: | :--- |\n|EasyIsing.Ising | Python | Vanilla, traditional random sequential site selection.|\n|EasyIsing.IsingC | C | Same as above, but in C. The source code will be compiled and saved in the working directory and called through numpy.ctypeslib.|\n|EasyIsing.IsingNumpy | NumPy | Checkerboard decomposition model parallelization scheme using NumPy array functions.|\n|EasyIsing.IsingCupy | CuPy | Same as above, but in CuPy to run on the GPU. Note that this class will only be loaded if CuPy is detected.|\n\nWith different [performances](examples/Performance.ipynb):\n\n<picture>\n <img src=\"examples/performance.png\">\n</picture>\n\n\n\nIt is assumed that the reader/user is being instruted about Ising model and [Metropolis Algorithm](https://en.wikipedia.org/wiki/Equation_of_State_Calculations_by_Fast_Computing_Machines\n). \nSo, no futher information will be provided.\n\n\n### Instalation\n```Shell\npip install EasyIsing\n```\n### Usage\n\nWhen imported, there are four classes of objects that can be used.\nThe user just have to create an instance with the desired arguments.\nFor example:\n\n```Python\nimport EasyIsing\n\nL = 10\nage = 1000\nsample = 1000\nT = 2.1\nH = 0\nseed = 84598945\n\nmac = EasyIsing.IsingNumpy(L, seed)\nmac.update(age,T,H)\nR = mac.sampling(sample,T,H)\nprint(R)\n\n```\nEasyIsing.Ising.sampling return a dict with the data accumulated.\n\n```JSON\n{'temperature': 2.1,\n 'field': 0,\n 'age': 2000,\n 'sampleSize': 1000,\n 'length': 10,\n 'seed': 84598945,\n 'energy1': -167.976,\n 'magnet1': -88.684,\n 'energy2': 28579.168,\n 'magnet2': 7945.392,\n 'name': 'Numpy'}\n```\n\nThere is a few examples in directory examples:\n* [Specific heat](examples/SpecificHeat.ipynb)\n* [Magnetic Hysteresis](examples/MagneticHysteresisLoop.ipynb)\n* [performances](examples/Performance.ipynb)\n\nThe user can override 'EasyIsing.Ising.sampling' to accumulate other data, or create custom sampling routine. For example, to include the spatial correlation function or 'energy4' and 'magnet4' to calculate Binder's coefficient.\n\n## Suggestions\n\nHere are some suggestions for fun things students can do and analyze using the Ising model simulation:\n\n* Observe the system \"walking\" to equilibrium with different initial states.\n* Analyze the size of error bars for energy, magnetization, etc. as a function of sample size and lattice size.\n* Explore specific heat and magnetic susceptibility using the Fluctuation-Dissipation Theorem and derivatives.\n* Calculate the entropy of the system.\n* Compare Binder's coefficient with histogram results.\n* Analyze critical coefficients.\n* Study cluster statistics.\n* Analyze the radial distribution function and the Virial expansion.\n* Explore magnetic hysteresis using the Magnetic Hysteresis Loop example provided in the EasyIsing module.\n\n<picture>\n <img src=\"examples/magnetization.png\">\n</picture>\n\n<picture>\n <img src=\"examples/specificHeat.png\">\n</picture>\n\n<picture>\n <img src=\"examples/mh2.8.jpg\">\n</picture>\n\n## Conclutions\n\nConclusively, C is an excellent choice for single-threaded performance.\nI expect similar performance for FORTRAN, Rust, and C++.\nFor larger systems, delegating the work to a GPU is by far the better option.\nSystems of size $L=128$ are big enough for most projects.\nAs we can see, for my test machine, for size $L=128$, with the exception of pure Python, the performance of all examples is similar.\n\nSeveral improvements can be made to increase performance, but they will cost development time and increase the chance of mistakes.\n\nMachine specifications:\nIntel\u00ae Core\u2122 i7-8700K CPU @ 3.70GHz,\nGeForce GTX 1080 Ti,\nUbuntu 22.04.1 LTS,\nPython 3.10.4,\ngcc version 11.2.0 (Ubuntu 11.2.0-19ubuntu1)\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A small package that provides a simple Ising model simulation on a squared lattice with the Metropolis algorithm.",
"version": "0.1.0",
"split_keywords": [
"ising",
"lattice gas",
"metropolis",
"monte carlo",
"statistical mechanics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5e17cbbbb20ac3ad16abd9a2b77ba486f68ffbfe21db69bba7cb085b9c89a64f",
"md5": "1d4e64659202fec6d2a4887cfb5b841a",
"sha256": "c52b3cb638f9b40a330f03c8b8f24965dcee2cbe0bc05093f770a815e2b59706"
},
"downloads": -1,
"filename": "easyising-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1d4e64659202fec6d2a4887cfb5b841a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10448,
"upload_time": "2023-03-25T20:00:02",
"upload_time_iso_8601": "2023-03-25T20:00:02.298207Z",
"url": "https://files.pythonhosted.org/packages/5e/17/cbbbb20ac3ad16abd9a2b77ba486f68ffbfe21db69bba7cb085b9c89a64f/easyising-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e210d9384843d3463e9c4554d3b5e9efdcab94c641536dd8cfba719f2dd7ab9c",
"md5": "25a83176791cd8d2fa6b2d3fc5255e57",
"sha256": "3dd4173b2c7a31d094df1b2f6265cf6ceeb62774f1e8273ad79da8e02a696754"
},
"downloads": -1,
"filename": "easyising-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "25a83176791cd8d2fa6b2d3fc5255e57",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 981385,
"upload_time": "2023-03-25T20:00:06",
"upload_time_iso_8601": "2023-03-25T20:00:06.001397Z",
"url": "https://files.pythonhosted.org/packages/e2/10/d9384843d3463e9c4554d3b5e9efdcab94c641536dd8cfba719f2dd7ab9c/easyising-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-25 20:00:06",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "easyising"
}
JSON