aton 0.7.2

The Ab-iniTiO & Neutron research toolbox, or ATON, provides powerful and comprehensive tools for cutting-edge materials research, focused on (but not limited to) neutron science.

Welcome to ATON

A Text Optimizer for scieNtific python, or ATON, is a package that provides powerful text-edition tools to edit and analyse simuation data.

Just like its ancient Egyptian deity counterpart, this Python package comprises several utilities to facilitate your simulation routines. This includes a txt module for easy and straight-forward text edition; an api module with interfaces for simulation and HPC codes, such as Quantum ESPRESSO, Phonopy and CASTEP; and a phys module with physico-chemical definitions, such as the 2022 CODATA Recommended Values of the Fundamental Physical Constants.

The source code is available on GitHub.
Check the full documentation online.

---

Installation

As always, it is recommended to install your packages in a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

With pip

Install or upgrade ATON with

pip install aton -U

From source

Optionally, you can install ATON from the GitHub repo. Clone the repository or download the latest stable release as a ZIP, unzip it, and run inside it:

pip install .

---

Documentation

The full ATON documentation is available online.
An offline version is found at docs/aton.html.
Code examples are included in the examples/ folder.

General text edition

The txt module handles text files. It powers more complex subpackages, such as aton.api.

aton.txt

txt.find	Search for specific content in text files
txt.edit	Manipulate text files
txt.extract	Extract data from raw text strings

Interfaces for ab-initio codes

The api module contains Python interfaces for several ab-initio codes and related. These are powered by the aton.txt module and can be easily extended.

aton.api

api.qe	Interface for Quantum ESPRESSO's pw.x module
api.phonopy	Interface for Phonopy calculations
api.castep	Interface for CASTEP calculations
api.slurm	Batch jobs via Slurm

Physico-chemical constants

The phys module contains physical constants and conversion factors, as well as chemical information from all known elements. Values are accessed directly as phys.value or phys.function().

aton.phys

phys.units	Physical constants and conversion factors
phys.atoms	Megadictionary with data for all chemical elements
phys.isotope	Analyse isotope data from text strings
phys.export_atoms	Update and export the aton.phys.atoms dict

System tools

Additional utility tools are available for common system tasks.

aton.file	File manipulation
aton.alias	Useful dictionaries for user input correction
aton.call	Run bash scripts and related

---

Contributing

If you are interested in opening an issue or a pull request, please feel free to do so on GitHub.
For major changes, please get in touch first to discuss the details.

Code style

Please try to follow some general guidelines:

• Use a code style consistent with the rest of the project.
• Include docstrings to document new additions.
• Include automated tests for new features or modifications, see automated testing.
• Arrange function arguments by order of relevance. Most implemented functions follow something similar to function(file, key/s, value/s, optional).

Automated testing

If you are modifying the source code, you should run the automated tests of the ATON/tests/ folder to check that everything works as intended. To do so, first install PyTest in your environment,

pip install pytest

And then run PyTest inside the ATON/ directory,

pytest -vv

Compiling the documentation

The documentation can be compiled automatically to docs/aton.html with Pdoc and ATON itself, by running:

python3 makedocs.py

This runs Pdoc, updating links and pictures, and using the custom theme CSS template from the css/ folder.

---

Citation

ATON development started for the following paper, please cite if you use ATON in your work:
Cryst. Growth Des. 2024, 24, 391−404

License

Copyright (C) 2025 Pablo Gila-Herranz
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the attached GNU Affero General Public License for more details.