Metadata-Version: 2.2
Name: atooms
Version: 3.25.0
Summary: A framework for simulations of interacting particles
Author-email: Daniele Coslovich <daniele.coslovich@umontpellier.fr>
License: GPLv3
Project-URL: repository, https://framagit.org/atooms/atooms
Project-URL: homepage, https://framagit.org/atooms/atooms
Project-URL: documentation, https://atooms.frama.io/atooms
Project-URL: changelog, https://framagit.org/atooms/atooms/-/blob/master/CHANGELOG.md
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2
Requires-Dist: f2py_jit>=1.1.1
Provides-Extra: backends
Requires-Dist: h5py; extra == "backends"
Requires-Dist: gsd~=2.0; extra == "backends"
Requires-Dist: matplotlib; extra == "backends"
Requires-Dist: lammps; extra == "backends"

Atooms
======

[![pypi](https://img.shields.io/pypi/v/atooms.svg)](https://pypi.python.org/pypi/atooms/)
[![version](https://img.shields.io/pypi/pyversions/atooms.svg)](https://pypi.python.org/pypi/atooms/)
[![license](https://img.shields.io/pypi/l/atooms.svg)](https://en.wikipedia.org/wiki/GNU_General_Public_License)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/git/https%3A%2F%2Fframagit.org%2Fatooms%2Fatooms/HEAD?labpath=docs%2F)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1183301.svg)](https://doi.org/10.5281/zenodo.1183301)
[![pipeline](https://framagit.org/atooms/atooms/badges/master/pipeline.svg)](https://framagit.org/atooms/atooms/badges/master/pipeline.svg)
[![coverage report](https://framagit.org/atooms/atooms/badges/master/coverage.svg)](https://framagit.org/atooms/atooms/-/commits/master)

**atooms** is a high-level Python framework for simulations of interacting particles, such as molecular dynamics or Monte Carlo.

This is the core package: it provides a consistent interface to the basic objects of particle-based simulations. [Feature packages](Feature packages) are built on top of it and implement complex simulation methods and analysis tools.

Quick start
-----------

Here is a small example for setting up a mixture of two types of particles, A and B, in a periodic elongated cell. The number density is set to unity.
```python
from atooms.system import System

system = System(N=64)
system.replicate(times=4, axis=0)
system.composition = {'A': 128, 'B': 128}
system.density = 1.0
```

Particles in the central part of the cell get a random displacement and are folded back into the simulation cell
```python
import numpy

for p in system.particle:
    if abs(p.position[0]) < system.cell.side[0] / 4:
        p.position += 0.5 * (numpy.random.random() - 0.5)
        p.fold(system.cell)
system.show('ovito')
```

![](https://framagit.org/atooms/atooms/-/raw/master/snapshot.png)

Simulation data are stored in trajectory files, which are easy to manipulate and convert with atooms. Here, we write the system species and positions in a single-frame trajectory file using the [xyz format](https://en.wikipedia.org/wiki/XYZ_format).
```python
from atooms.trajectory import TrajectoryXYZ

with TrajectoryXYZ('input.xyz', 'w') as th:
    th.variables = ['species', 'position']  # actually, this is the default
    th.write(system)
```

The trajectory file can now be used to start a simulation using one the available [simulation backends](https://atooms.frama.io/atooms/tutorial/simulations.html) or your own code.

Features
--------

- Focus on a simple and expressive interface
- API refined over the years towards consistency
- Modular and extensible design via namespace packages
- Semantic versioning - for what is worth
- Easy to interface: in-house codes and custom formats are first-class citizens
- Support for efficient simulation backends, with a focus on GPU codes

Documentation
-------------
Check out the [tutorial](https://atooms.frama.io/docs/) for more examples and the [public API](https://atooms.frama.io/atooms/) for more details.

Org-mode and jupyter notebooks are available under [docs](https://framagit.org/atooms/atooms/-/blob/master/docs/). You can run them interactively on [Binder](https://mybinder.org/v2/git/https%3A%2F%2Fframagit.org%2Fatooms%2Fatooms/HEAD?labpath=docs%2).

Installation
------------
From the python package index
```
pip install atooms
```

From the code repository
```
git clone https://framagit.org/atooms/atooms.git
cd atooms
make install
```

Contributing
------------
You are welcome to contribute to this project! Please have a look at [these guidelines](https://framagit.org/atooms/atooms/-/blob/master/CONTRIBUTING.md).

Feature packages 
------------------
Atooms is modular: it is easy to add new functionalities, and just those you actually need.

Feature packages are available from the [atooms main repository](https://framagit.org/atooms). They are installed in the `atooms` namespace to prevent name clashing. If you want to add your own feature package to the atooms namespace, structure it this way
```bash
atooms/your_package
atooms/your_package/__init__.py
```

where ```__init__.py``` contains

```python
from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)
```

Install `your_package` and you are ready to go
```python
import atooms.your_package
```

Authors
-------
Daniele Coslovich: https://www.units.it/daniele.coslovich/

Thanks go to Francesco Turci, Geert Kapteijns and Romain Simon for their contributions.
