Metadata-Version: 2.1
Name: atooms
Version: 3.4.0
Summary: A framework for simulations of interacting particles
Home-page: https://framagit.org/atooms/atooms
Author: Daniele Coslovich
Author-email: daniele.coslovich@umontpellier.fr
License: GPLv3
Platform: UNKNOWN
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Scientific/Engineering :: Physics
Description-Content-Type: text/markdown
Requires-Dist: numpy

Atooms
======

|pypi| |version| |license| |DOI| |pipeline| |coverage report|

**atooms** is a Python framework for simulations of interacting
particles. It makes it easy to develop simulation and analysis tools
using an expressive language, without sacrificing efficiency. To achieve
this, atooms relies on backends written in C, CUDA or Fortran.

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

The goal of atooms is to provide a coherent interface to the basic
objects of `molecular
dynamics <https://en.wikipedia.org/wiki/Molecular_dynamics>`__ or `Monte
Carlo <https://en.wikipedia.org/wiki/Monte_Carlo_method_in_statistical_physics>`__
simulations. The simulation data are stored in trajectory files, which
are easy to analyze, manipulate and convert with atooms.

In this quick example, we read a trajectory file in `xyz
format <https://en.wikipedia.org/wiki/XYZ_format>`__ composed by
multiple frames. Each frame holds the state of the system at a given
instant of time during the simulation. Accessing the coordinates of the
particles in a trajectory file goes like this:

.. code:: python

   from atooms.trajectory import Trajectory

   with Trajectory('input.xyz') as trajectory:
       for system in trajectory:
           print('The position of particle 0 is', system.particle[0].position)

Note that trajectories support iteration and indexing, just like lists.

Here we pick the last frame of the trajectory, change the density of the
system to unity and write this new configuration to a trajectory format
suitable for the `RUMD <http://rumd.org>`__ simulation package:

.. code:: python

   with Trajectory('input.xyz') as trajectory:
       system = trajectory[-1]
       system.density = 1.0
       print('The new density is', len(system.particle) / system.cell.volume)

   from atooms.trajectory import TrajectoryRUMD
   with TrajectoryRUMD('rescaled.xyz.gz', 'w') as trajectory:
       trajectory.write(system, step=0)

We can now run 1000 molecular dynamics steps using the Lennard-Jones
potential:

.. code:: python

   import rumd
   from atooms.backends.rumd import RUMD
   from atooms.simulation import Simulation

   # Kob-Andersen model
   potential = rumd.Pot_LJ_12_6(cutoff_method=rumd.ShiftedPotential)
   potential.SetParams(i=0, j=0, Epsilon=1.0, Sigma=1.0, Rcut=2.5)

   backend = RUMD('rescaled.xyz.gz', [potential], 
                  output_path='/tmp/outdir', integrator='nve')
   sim = Simulation(backend)
   sim.run(1000)
   print('Final temperature and density', sim.system.temperature, sim.system.density)

Documentation
-------------

See the `tutorial <https://atooms.frama.io/atooms/>`__ for a
step-by-step introduction to atooms objects and the `public API
documentation <https://atooms.frama.io/atooms/api/atooms/>`__ for full
details.

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/atooms-3.0.0/CONTRIBUTING.md>`__.

Simulation backends
-------------------

atooms has a generic simulation interface that abstracts out most of the
common parts of particle-based simulations. The actual simulation code
is wrapped by a simulation backend that exposes a minimal but consistent
interface. This enables one to develop more complex simulation
frameworks (e.g., `parallel
tempering <https://framagit.org/atooms/parallel_tempering>`__) that are
essentially decoupled from the underlying simulation code.

Trajectory conversion
---------------------

atooms provides a command line tool to convert between various
trajectory formats. The following command will convert a trajectory file
produced by `RUMD <http://rumd.org>`__ into a simpler xyz format

.. code:: bash

   $ trj.py convert -i rumd -o xyz trajectory.xyz.gz output.xyz

If you don’t specify the output path, the trajectory is written to
standard output. This is useful for quick inspection of complex
trajectory formats or for piping into sed / awk.

``trj.py`` provides means to fine tune the format of the output file.
Type ``trj.py --help`` to get a list of options and supported trajectory
formats.

Custom trajectory formats
-------------------------

It is easy to add new trajectory formats by subclassing existing
trajectory classes. Just create a package called ``atooms_plugins`` and
add your trajectory modules there. They will be automatically available
to all client codes that use atooms.

Suppose you wrote a custom trajectory class ``TrajectoryABC`` in
``atooms_plugins/test.py`` (the last path is relative to the current
directory). You can now convert an existing xyz trajectory to your
custom format:

.. code:: bash

   $ trj.py convert output.xyz output.abc

Remember to add an empty ``__init__.py`` file at the root of
``atooms_plugins``. Actually, the ``atooms_plugins`` package can be put
anywhere in your ``PYTHONPATH``.

Additional packages
-------------------

Atooms is composable: it is easy to add new functionalities, and just
those you actually need. Additional packages are available from the
`atooms main repository <https://framagit.org/atooms>`__. These packages
will be installed in the atooms namespace to prevent name clashing.

If you want to add your own package to the atooms namespace, structure
it this way

.. code:: bash

   atooms/your_package
   atooms/your_package/__init__.py

where ``__init__.py`` contains

.. code:: python

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

Add the package root folder to $PYTHONPATH. You can now import your
package as

.. code:: python

   import atooms.your_package

Authors
-------

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

.. |pypi| image:: https://img.shields.io/pypi/v/atooms.svg
   :target: https://pypi.python.org/pypi/atooms/
.. |version| image:: https://img.shields.io/pypi/pyversions/atooms.svg
   :target: https://pypi.python.org/pypi/atooms/
.. |license| image:: https://img.shields.io/pypi/l/atooms.svg
   :target: https://en.wikipedia.org/wiki/GNU_General_Public_License
.. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1183301.svg
   :target: https://doi.org/10.5281/zenodo.1183301
.. |pipeline| image:: https://framagit.org/atooms/atooms/badges/master/pipeline.svg
   :target: https://framagit.org/atooms/atooms/badges/master/pipeline.svg
.. |coverage report| image:: https://framagit.org/atooms/atooms/badges/master/coverage.svg
   :target: https://framagit.org/atooms/atooms/-/commits/master


