<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.
Just like its [ancient Egyptian deity](https://en.wikipedia.org/wiki/Aten) counterpart,
this all-in-one Python package contains a range of 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/cc/19/71827b4ce1fa20bde4ca94301ec5908f408d28d4de0dae7ae98f743d6a62/aton-0.1.0.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.\n\nJust like its [ancient Egyptian deity](https://en.wikipedia.org/wiki/Aten) counterpart,\nthis all-in-one Python package contains a range of 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.1.0",
"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": "1f9d3819b0f07f1a770c35a241695498b6ee0f526eccda873dbf35e24740ca12",
"md5": "78a3d741dbb2d3e4c685d62931bec157",
"sha256": "edcf2475d63284072cb30cb1ed9ee6c4114cc95e9936ecfd87313692de8a976f"
},
"downloads": -1,
"filename": "aton-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "78a3d741dbb2d3e4c685d62931bec157",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 107540,
"upload_time": "2025-02-12T13:33:31",
"upload_time_iso_8601": "2025-02-12T13:33:31.785912Z",
"url": "https://files.pythonhosted.org/packages/1f/9d/3819b0f07f1a770c35a241695498b6ee0f526eccda873dbf35e24740ca12/aton-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cc1971827b4ce1fa20bde4ca94301ec5908f408d28d4de0dae7ae98f743d6a62",
"md5": "b1489ded922a6307b77bb3acdce79ca3",
"sha256": "14677dad825e76ce25cd11da0ee088b714af98df5de706d0bad66ada591f91db"
},
"downloads": -1,
"filename": "aton-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b1489ded922a6307b77bb3acdce79ca3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 97951,
"upload_time": "2025-02-12T13:33:34",
"upload_time_iso_8601": "2025-02-12T13:33:34.902501Z",
"url": "https://files.pythonhosted.org/packages/cc/19/71827b4ce1fa20bde4ca94301ec5908f408d28d4de0dae7ae98f743d6a62/aton-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-12 13:33:34",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "aton"
}
JSON