<p align="center"><img width="40.0%" src="pics/aton.png"></p>
# Welcome to ATON
The **A**b-ini**T**i**O** & **N**eutron research toolbox,
or [ATON](https://pablogila.github.io/ATON/),
provides powerful and comprehensive tools
for cutting-edge materials research,
focused on (but not limited to) neutron science.
Designed to bridge the gap between theoretical modeling and experimental validation,
ATON allows researchers to streamline and simplify workflows in the study of advanced materials.
Just like its [ancient Egyptian deity](https://en.wikipedia.org/wiki/Aten) counterpart,
this all-in-one Python package comprises a range of utility tools
from INS spectra analysis to *ab-initio* interfaces
for [Quantum ESPRESSO](https://www.quantum-espresso.org/),
[Phonopy](https://phonopy.github.io/phonopy/) and
[CASTEP](https://castep-docs.github.io/castep-docs/).
Conversion factors and universal constants from the [2022 CODATA](https://doi.org/10.48550/arXiv.2409.03787)
Recommended Values of the Fundamental Physical Constants are also included.
The source code is available on [GitHub](https://github.com/pablogila/ATON/).
Check the [full documentation online](https://pablogila.github.io/ATON/).
---
# Installation
As always, it is recommended to install your packages in a virtual environment:
```bash
python3 -m venv .venv
source .venv/bin/activate
```
## With pip
Install ATON with
```bash
pip install aton
```
Or upgrade to a new version as
```bash
pip install aton -U
```
## From source
Optionally, you can install ATON from the [GitHub repo](https://github.com/pablogila/ATON/).
Clone the repository or download the [latest stable release](https://github.com/pablogila/ATON/tags)
as a ZIP, unzip it, and run inside the `ATON/` directory:
```bash
pip install .
```
---
# Documentation
The full ATON documentation is available [online](https://pablogila.github.io/ATON/).
An offline version is found at `docs/aton.html`.
Code examples are included in the [`examples/`](https://github.com/pablogila/ATON/tree/main/examples) folder.
## Interfaces for *ab-initio* codes
The **interface** module contains Python interfaces for several *ab-initio* codes.
These are powered by the [aton.txt](#general-text-edition) module and can be easily extended.
### [aton.interface](https://pablogila.github.io/ATON/aton/interface.html)
| | |
| --- | --- |
| [interface.qe](https://pablogila.github.io/ATON/aton/interface/qe.html) | Interface for [Quantum ESPRESSO](https://www.quantum-espresso.org/)'s [pw.x](https://www.quantum-espresso.org/Doc/INPUT_PW.html) module |
| [interface.phonopy](https://pablogila.github.io/ATON/aton/interface/phonopy.html) | Interface for [Phonopy](https://phonopy.github.io/phonopy/) calculations |
| [interface.castep](https://pablogila.github.io/ATON/aton/interface/castep.html) | Interface for [CASTEP](https://castep-docs.github.io/castep-docs/) calculations |
| [interface.slurm](https://pablogila.github.io/ATON/aton/interface/slurm.html) | Batch jobs via [Slurm](https://slurm.schedmd.com/) |
## Physico-chemical constants
The **phys** module contains physico-chemical definitions.
Values are accessed directly as `phys.value` or `phys.function()`.
### [aton.phys](https://pablogila.github.io/ATON/aton/phys.html)
| | |
| --- | --- |
| [phys.units](https://pablogila.github.io/ATON/aton/phys/units.html) | Physical constants and conversion factors |
| [phys.atoms](https://pablogila.github.io/ATON/aton/phys/atoms.html) | Megadictionary with data for all chemical elements |
| [phys.functions](https://pablogila.github.io/ATON/aton/phys/functions.html) | Functions to sort and analyse element data |
## Quantum rotations
The **QRotor** module is used to study quantum rotations,
such as those of methyl and amine groups.
### [aton.qrotor](https://pablogila.github.io/ATON/aton/qrotor.html)
| | |
| --- | --- |
| [qrotor.rotate](https://pablogila.github.io/ATON/aton/qrotor/rotate.html) | Rotate specific atoms from structural files |
| [qrotor.constants](https://pablogila.github.io/ATON/aton/qrotor/constants.html) | Bond lengths and inertias |
| [qrotor.system](https://pablogila.github.io/ATON/aton/qrotor/system.html) | Definition of the quantum `System` object |
| [qrotor.systems](https://pablogila.github.io/ATON/aton/qrotor/systems.html) | Functions to manage several System objects |
| [qrotor.potential](https://pablogila.github.io/ATON/aton/qrotor/potential.html) | Potential definitions and loading functions |
| [qrotor.solve](https://pablogila.github.io/ATON/aton/qrotor/solve.html) | Solve rotation eigenvalues and eigenvectors |
| [qrotor.plot](https://pablogila.github.io/ATON/aton/qrotor/plot.html) | Plotting functions |
## Spectra analysis
The **spx** module includes tools for spectral analysis from
Inelastic Neutron Scattering, Raman, Infrared, etc.
### [aton.spx](https://pablogila.github.io/ATON/aton/spx.html)
| | |
| --- | --- |
| [spx.classes](https://pablogila.github.io/ATON/aton/spx/classes.html) | Class definitions for the spectra module |
| [spx.fit](https://pablogila.github.io/ATON/aton/spx/fit.html) | Spectra fitting functions |
| [spx.normalize](https://pablogila.github.io/ATON/aton/spx/normalize.html) | Spectra normalization |
| [spx.plot](https://pablogila.github.io/ATON/aton/spx/plot.html) | Plotting |
| [spx.deuterium](https://pablogila.github.io/ATON/aton/spx/deuterium.html) | Deuteration estimations via INS |
| [spx.samples](https://pablogila.github.io/ATON/aton/spx/samples.html) | Sample materials for testing |
## General text edition
The **txt** module handles text files.
It powers more complex subpackages,
such as [aton.interface](#interfaces-for-ab-initio-codes).
### [aton.txt](https://pablogila.github.io/ATON/aton/txt.html)
| | |
| --- | --- |
| [txt.find](https://pablogila.github.io/ATON/aton/txt/find.html) | Search for specific content in text files |
| [txt.edit](https://pablogila.github.io/ATON/aton/txt/edit.html) | Manipulate text files |
| [txt.extract](https://pablogila.github.io/ATON/aton/txt/extract.html) | Extract data from raw text strings |
## System tools
The **st** module contains System Tools for common system tasks across subpackages.
### [aton.st](https://pablogila.github.io/ATON/aton/st.html)
| | |
| --- | --- |
| [st.file](https://pablogila.github.io/ATON/aton/st/file.html) | File manipulation |
| [st.call](https://pablogila.github.io/ATON/aton/st/call.html) | Run bash scripts and related |
| [st.alias](https://pablogila.github.io/ATON/aton/st/alias.html) | Useful dictionaries for user input correction |
---
# Contributing
If you are interested in opening an issue or a pull request, please feel free to do so on [GitHub](https://github.com/pablogila/ATON/).
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](#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/`](https://github.com/pablogila/ATON/tree/main/tests) folder to check that everything works as intended.
To do so, first install PyTest in your environment,
```bash
pip install pytest
```
And then run PyTest inside the `ATON/` directory,
```bash
pytest -vv
```
## Compiling the documentation
The documentation can be compiled automatically to `docs/aton.html` with [Pdoc](https://pdoc.dev/) and ATON itself, by running:
```shell
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](https://doi.org/10.1021/acs.cgd.3c01112)
# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "aton",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": null,
"keywords": "Aton, Neutron, Neutron research, Spectra, Inelastic Neutron Scattering, INS, Ab-initio, DFT, Density Functional Theory, MD, Molecular Dynamics, Quantum ESPRESSO, Phonopy, CASTEP",
"author": "Pablo Gila-Herranz",
"author_email": "pgila001@ikasle.ehu.eus",
"download_url": "https://files.pythonhosted.org/packages/45/fa/3b0e25fc56b171debc6db6b8023aaa89057b9d3e964b8081f7ba7a34ac7d/aton-0.2.4.tar.gz",
"platform": null,
"description": "<p align=\"center\"><img width=\"40.0%\" src=\"pics/aton.png\"></p>\n\n\n# Welcome to ATON\n\nThe **A**b-ini**T**i**O** & **N**eutron research toolbox,\nor [ATON](https://pablogila.github.io/ATON/),\nprovides powerful and comprehensive tools\nfor cutting-edge materials research,\nfocused on (but not limited to) neutron science.\nDesigned to bridge the gap between theoretical modeling and experimental validation,\nATON allows researchers to streamline and simplify workflows in the study of advanced materials.\n\nJust like its [ancient Egyptian deity](https://en.wikipedia.org/wiki/Aten) counterpart,\nthis all-in-one Python package comprises a range of utility tools\nfrom INS spectra analysis to *ab-initio* interfaces\nfor [Quantum ESPRESSO](https://www.quantum-espresso.org/),\n[Phonopy](https://phonopy.github.io/phonopy/) and\n[CASTEP](https://castep-docs.github.io/castep-docs/).\nConversion factors and universal constants from the [2022 CODATA](https://doi.org/10.48550/arXiv.2409.03787)\nRecommended Values of the Fundamental Physical Constants are also included. \n\nThe source code is available on [GitHub](https://github.com/pablogila/ATON/). \nCheck the [full documentation online](https://pablogila.github.io/ATON/). \n\n\n---\n\n\n# Installation\n\nAs always, it is recommended to install your packages in a virtual environment: \n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\n```\n\n\n## With pip\n\nInstall ATON with \n```bash\npip install aton\n```\n\nOr upgrade to a new version as\n```bash\npip install aton -U\n```\n\n\n## From source\n\nOptionally, you can install ATON from the [GitHub repo](https://github.com/pablogila/ATON/).\nClone the repository or download the [latest stable release](https://github.com/pablogila/ATON/tags)\nas a ZIP, unzip it, and run inside the `ATON/` directory: \n```bash\npip install .\n```\n\n\n---\n\n\n# Documentation\n\nThe full ATON documentation is available [online](https://pablogila.github.io/ATON/). \nAn offline version is found at `docs/aton.html`. \nCode examples are included in the [`examples/`](https://github.com/pablogila/ATON/tree/main/examples) folder. \n\n\n## Interfaces for *ab-initio* codes\n\nThe **interface** module contains Python interfaces for several *ab-initio* codes.\nThese are powered by the [aton.txt](#general-text-edition) module and can be easily extended.\n\n### [aton.interface](https://pablogila.github.io/ATON/aton/interface.html)\n\n| | | \n| --- | --- | \n| [interface.qe](https://pablogila.github.io/ATON/aton/interface/qe.html) | Interface for [Quantum ESPRESSO](https://www.quantum-espresso.org/)'s [pw.x](https://www.quantum-espresso.org/Doc/INPUT_PW.html) module | \n| [interface.phonopy](https://pablogila.github.io/ATON/aton/interface/phonopy.html) | Interface for [Phonopy](https://phonopy.github.io/phonopy/) calculations | \n| [interface.castep](https://pablogila.github.io/ATON/aton/interface/castep.html) | Interface for [CASTEP](https://castep-docs.github.io/castep-docs/) calculations | \n| [interface.slurm](https://pablogila.github.io/ATON/aton/interface/slurm.html) | Batch jobs via [Slurm](https://slurm.schedmd.com/) |\n\n\n## Physico-chemical constants\n\nThe **phys** module contains physico-chemical definitions.\nValues are accessed directly as `phys.value` or `phys.function()`.\n\n### [aton.phys](https://pablogila.github.io/ATON/aton/phys.html)\n\n| | | \n| --- | --- | \n| [phys.units](https://pablogila.github.io/ATON/aton/phys/units.html) | Physical constants and conversion factors | \n| [phys.atoms](https://pablogila.github.io/ATON/aton/phys/atoms.html) | Megadictionary with data for all chemical elements | \n| [phys.functions](https://pablogila.github.io/ATON/aton/phys/functions.html) | Functions to sort and analyse element data | \n\n\n## Quantum rotations\n \nThe **QRotor** module is used to study quantum rotations,\nsuch as those of methyl and amine groups.\n\n### [aton.qrotor](https://pablogila.github.io/ATON/aton/qrotor.html)\n\n| | |\n| --- | --- |\n| [qrotor.rotate](https://pablogila.github.io/ATON/aton/qrotor/rotate.html) | Rotate specific atoms from structural files |\n| [qrotor.constants](https://pablogila.github.io/ATON/aton/qrotor/constants.html) | Bond lengths and inertias |\n| [qrotor.system](https://pablogila.github.io/ATON/aton/qrotor/system.html) | Definition of the quantum `System` object |\n| [qrotor.systems](https://pablogila.github.io/ATON/aton/qrotor/systems.html) | Functions to manage several System objects |\n| [qrotor.potential](https://pablogila.github.io/ATON/aton/qrotor/potential.html) | Potential definitions and loading functions |\n| [qrotor.solve](https://pablogila.github.io/ATON/aton/qrotor/solve.html) | Solve rotation eigenvalues and eigenvectors |\n| [qrotor.plot](https://pablogila.github.io/ATON/aton/qrotor/plot.html) | Plotting functions |\n\n\n## Spectra analysis\n\nThe **spx** module includes tools for spectral analysis from\nInelastic Neutron Scattering, Raman, Infrared, etc.\n\n### [aton.spx](https://pablogila.github.io/ATON/aton/spx.html)\n\n| | | \n| --- | --- | \n| [spx.classes](https://pablogila.github.io/ATON/aton/spx/classes.html) | Class definitions for the spectra module | \n| [spx.fit](https://pablogila.github.io/ATON/aton/spx/fit.html) | Spectra fitting functions | \n| [spx.normalize](https://pablogila.github.io/ATON/aton/spx/normalize.html) | Spectra normalization | \n| [spx.plot](https://pablogila.github.io/ATON/aton/spx/plot.html) | Plotting | \n| [spx.deuterium](https://pablogila.github.io/ATON/aton/spx/deuterium.html) | Deuteration estimations via INS | \n| [spx.samples](https://pablogila.github.io/ATON/aton/spx/samples.html) | Sample materials for testing | \n\n\n## General text edition\n\nThe **txt** module handles text files.\nIt powers more complex subpackages,\nsuch as [aton.interface](#interfaces-for-ab-initio-codes).\n\n### [aton.txt](https://pablogila.github.io/ATON/aton/txt.html)\n\n| | | \n| --- | --- | \n| [txt.find](https://pablogila.github.io/ATON/aton/txt/find.html) | Search for specific content in text files | \n| [txt.edit](https://pablogila.github.io/ATON/aton/txt/edit.html) | Manipulate text files | \n| [txt.extract](https://pablogila.github.io/ATON/aton/txt/extract.html) | Extract data from raw text strings | \n\n\n## System tools\n\nThe **st** module contains System Tools for common system tasks across subpackages.\n\n### [aton.st](https://pablogila.github.io/ATON/aton/st.html)\n\n| | | \n| --- | --- | \n| [st.file](https://pablogila.github.io/ATON/aton/st/file.html) | File manipulation | \n| [st.call](https://pablogila.github.io/ATON/aton/st/call.html) | Run bash scripts and related | \n| [st.alias](https://pablogila.github.io/ATON/aton/st/alias.html) | Useful dictionaries for user input correction | \n\n\n---\n\n\n# Contributing\n\nIf you are interested in opening an issue or a pull request, please feel free to do so on [GitHub](https://github.com/pablogila/ATON/). \nFor major changes, please get in touch first to discuss the details. \n\n\n## Code style\n\nPlease try to follow some general guidelines: \n- Use a code style consistent with the rest of the project. \n- Include docstrings to document new additions. \n- Include automated tests for new features or modifications, see [automated testing](#automated-testing). \n- Arrange function arguments by order of relevance. Most implemented functions follow something similar to `function(file, key/s, value/s, optional)`. \n\n\n## Automated testing\n\nIf you are modifying the source code, you should run the automated tests of the [`ATON/tests/`](https://github.com/pablogila/ATON/tree/main/tests) folder to check that everything works as intended.\nTo do so, first install PyTest in your environment,\n```bash\npip install pytest\n```\n\nAnd then run PyTest inside the `ATON/` directory,\n```bash\npytest -vv\n```\n\n\n## Compiling the documentation\n\nThe documentation can be compiled automatically to `docs/aton.html` with [Pdoc](https://pdoc.dev/) and ATON itself, by running:\n```shell\npython3 makedocs.py\n```\n\nThis runs Pdoc, updating links and pictures, and using the custom theme CSS template from the `css/` folder.\n\n\n---\n\n\n# Citation\n\nATON development started for the following paper, please cite if you use ATON in your work: \n[*Cryst. Growth Des.* 2024, 24, 391\u2212404](https://doi.org/10.1021/acs.cgd.3c01112) \n\n\n# License\n\nCopyright (C) 2025 Pablo Gila-Herranz \nThis program is free software: you can redistribute it and/or modify\nit under the terms of the **GNU Affero General Public License** as published\nby the Free Software Foundation, either version **3** of the License, or\n(at your option) any later version. \nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. \nSee the attached GNU Affero General Public License for more details. \n\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "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.",
"version": "0.2.4",
"project_urls": null,
"split_keywords": [
"aton",
" neutron",
" neutron research",
" spectra",
" inelastic neutron scattering",
" ins",
" ab-initio",
" dft",
" density functional theory",
" md",
" molecular dynamics",
" quantum espresso",
" phonopy",
" castep"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "da3a2ca3e4f2e7f04fee49ac8263eaa49851efb72e3de62f621a0f9e2e4ee965",
"md5": "72ad4c5ce540aded83c877d23fa9e457",
"sha256": "ddd61aa4fe312e57c6f276b4f68957e9622945dd3694f90723989a0e143f5532"
},
"downloads": -1,
"filename": "aton-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "72ad4c5ce540aded83c877d23fa9e457",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 110421,
"upload_time": "2025-02-26T19:14:56",
"upload_time_iso_8601": "2025-02-26T19:14:56.884371Z",
"url": "https://files.pythonhosted.org/packages/da/3a/2ca3e4f2e7f04fee49ac8263eaa49851efb72e3de62f621a0f9e2e4ee965/aton-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "45fa3b0e25fc56b171debc6db6b8023aaa89057b9d3e964b8081f7ba7a34ac7d",
"md5": "f2c8e69d185b7fe9c3bf8c6405c8ef8e",
"sha256": "c27a5a46297e51dfe97b23e0c4ca261cfeaecfaf159d9db40bdf9b27886102da"
},
"downloads": -1,
"filename": "aton-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "f2c8e69d185b7fe9c3bf8c6405c8ef8e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 100476,
"upload_time": "2025-02-26T19:14:58",
"upload_time_iso_8601": "2025-02-26T19:14:58.567019Z",
"url": "https://files.pythonhosted.org/packages/45/fa/3b0e25fc56b171debc6db6b8023aaa89057b9d3e964b8081f7ba7a34ac7d/aton-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-26 19:14:58",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "aton"
}
JSON