Atooms

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.

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

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')

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.

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 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 for more examples and the public API for more details.

Org-mode and jupyter notebooks are available under docs. You can run them interactively on Binder.

Installation

From the python package index

pip install atooms

From the code repository

git clone https://framagit.org/atooms/atooms.git
cd atooms
pip install .

Contributing

You are welcome to contribute to this project! Please have a look at these guidelines.

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. 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

atooms/your_package  # flat layout

src/atooms/your_package  # src layout

Install your_package and you are ready to go

import atooms.your_package

Authors

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

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

Release files for atooms 3.30.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for atooms 3.30.0
File	Size	Uploaded
atooms-3.30.0.tar.gz	185.9 kB	Sep 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for atooms 3.30.0
File	Interpreter	ABI	Platform	Reset
atooms-3.30.0-py3-none-any.whl 187.6 kB Sep 9, 2026	Python 3	none	any	Details

Total release size: 373.6 kB

Release files / atooms-3.30.0.tar.gz

Download URL	atooms-3.30.0.tar.gz
Size	185.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`dcd920c5ad5d70f87699f6b70f7f7084f4223f1839df785a200373bedce7e5d3`
BLAKE2b-256 checksum How to use checksums	`41d35ffbf42dc2fd4558bc79e4a2593db0ff2069cafefcb3314eadc76507f98a`
Upload date	Sep 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.10.12`

Release files / atooms-3.30.0-py3-none-any.whl

Download URL	atooms-3.30.0-py3-none-any.whl
Size	187.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1e228d3b7f7e0cb0d249797ec4028094cc13bf091fb4239022c6b85057757e0e`
BLAKE2b-256 checksum How to use checksums	`0f62917bb0533d16479e9ce954ebfa344dc76231caa5d94ca3044985510a3219`
Upload date	Sep 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.10.12`