Skip to content

Commit

Permalink
readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@pablogila
pablogila committed Jan 5, 2025
1 parent cea0bf2 commit ec45118
Show file tree
Hide file tree
Showing 5 changed files with 291 additions and 6 deletions.
119 changes: 118 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,121 @@
<p align="center"><img width="50.0%" src="aton.svg"></p>

Welcome to the **A**b-ini**T**i**O** and **N**eutron research toolbox, or [Aton](https://en.wikipedia.org/wiki/Aten). Just as the ancient Egyptian deity, this all-in-one Python package provides powerful and comprehensive tools for cutting-edge materials research.
Welcome to the **A**b-ini**T**i**O** and **N**eutron research toolbox, or [Aton](https://en.wikipedia.org/wiki/Aten). Just as the ancient Egyptian deity, this all-in-one Python package provides powerful and comprehensive tools for cutting-edge materials research.

Aton allows you to easily create, edit and analyse all kinds of text files, with a special focus on *ab-initio* calculations. In particular, it contains interfaces for [Quantum ESPRESSO](https://www.quantum-espresso.org/), [Phonopy](https://phonopy.github.io/phonopy/) and [CASTEP](https://castep-docs.github.io/castep-docs/).

This is combined with a range of spectral analysis tools to analyse your experimental campaigns, from inelastic neutron scattering to FTIR spectroscopy.

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

The fastest way to install Aton is through pip:
```bash
pip install aton
```

## From source

Optionally, you can install Aton from the [GitHub repository](https://github.com/pablogila/Aton/).

First install the dependencies:
```bash
pip install pandas numpy scipy
```

Then 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
Check the [full Aton documentation online](https://pablogila.github.io/Aton/).
An offline version of the documentation is available in `docs/aton.html`.
Code examples are included in the `examples/` folder.

## Submodules
Aton contains the following modules:
- [text](https://pablogila.github.io/Aton/aton/text.html). See [General text edition](#general-text-edition).
- [interface](https://pablogila.github.io/Aton/aton/interface.html). See [Interfaces for ab-initio codes](#interfaces-for-ab-initio-codes).
- [spectra](https://pablogila.github.io/Aton/aton/spectra.html). See [Spectral analysis tools](#spectral-analysis-tools).
- [units](https://pablogila.github.io/Aton/aton/units.html). Physical constants and conversion factors.
- [atoms](https://pablogila.github.io/Aton/aton/atoms.html). Megadictionary with data of all chemical elements.
- [elements](https://pablogila.github.io/Aton/aton/elements.html). Sort and analyse element data, and manage the atoms dictionary.
- [file](https://pablogila.github.io/Aton/aton/file.html). Manipulate files.
- [call](https://pablogila.github.io/Aton/aton/call.html). Run bash scripts and related.
- [alias](https://pablogila.github.io/Aton/aton/alias.html). Useful dictionaries for user input correction.

## General text edition
The [text](https://pablogila.github.io/Aton/aton/text.html) module includes the following general text-related submodules:
- [find](https://pablogila.github.io/Aton/aton/text/find.html). Search for specific content in a text file.
- [edit](https://pablogila.github.io/Aton/aton/text/edit.html). Manipulate text files.
- [extract](https://pablogila.github.io/Aton/aton/text/extract.html). Extract data from raw text strings.

## Interfaces for ab-initio codes
The [interface](https://pablogila.github.io/Aton/aton/interface.html) module contains interfaces for several *ab-initio* codes. These are powered by the [text](https://pablogila.github.io/Aton/aton/text.html) module and can be easily extended. The following interfaces are included:
- [qe](https://pablogila.github.io/Aton/aton/interface/qe.html). Interface for [Quantum ESPRESSO](https://www.quantum-espresso.org/) calculations.
- [phonopy](https://pablogila.github.io/Aton/aton/interface/phonopy.html). Interface for [Phonopy](https://phonopy.github.io/phonopy/) calculations.
- [castep](https://pablogila.github.io/Aton/aton/interface/castep.html) Interface for [CASTEP](https://castep-docs.github.io/castep-docs/) calculations.

## Spectral analysis tools
The [spectra](https://pablogila.github.io/Aton/aton/spectra.html) module IS YET TO BE IMPLEMENTED.
- Things...


# 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 tests for new features or modifications.
- Arrange function arguments by order of relevance. Most implemented functions follow something similar to `function(file, key/s, value/s, optional)`.

## Testing with PyTest

If you are modifying the source code, you should run the automated tests of the `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
```


# License

Copyright (C) 2024 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.

2 changes: 1 addition & 1 deletion aton/elements.py
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
'''
# Description
This module contains functions to sort and organise element data
This module contains functions to sort and analyse element data
from the `aton.atoms` megadictionary, which contains the properties of all elements.
It also contains the tools needed to automatically update said megadictionary.
Expand Down
170 changes: 169 additions & 1 deletion docs/aton.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,29 @@
<input type="search" placeholder="Search..." role="searchbox" aria-label="search"
pattern=".+" required>

<h2>Contents</h2>
<ul>
<li><a href="#installation">Installation</a>
<ul>
<li><a href="#with-pip">With pip</a></li>
<li><a href="#from-source">From source</a></li>
</ul></li>
<li><a href="#documentation">Documentation</a>
<ul>
<li><a href="#submodules">Submodules</a></li>
<li><a href="#general-text-edition">General text edition</a></li>
<li><a href="#interfaces-for-ab-initio-codes">Interfaces for ab-initio codes</a></li>
<li><a href="#spectral-analysis-tools">Spectral analysis tools</a></li>
</ul></li>
<li><a href="#contributing">Contributing</a>
<ul>
<li><a href="#code-style">Code style</a></li>
<li><a href="#testing-with-pytest">Testing with PyTest</a></li>
<li><a href="#compiling-the-documentation">Compiling the documentation</a></li>
</ul></li>
<li><a href="#license">License</a></li>
</ul>


<h2>Submodules</h2>
<ul>
Expand Down Expand Up @@ -87,7 +110,152 @@ <h2>Submodules</h2>
<h1 class="modulename">
aton </h1>

<div class="docstring"><p>Welcome to the <strong>A</strong>b-ini<strong>T</strong>i<strong>O</strong> and <strong>N</strong>eutron research toolbox, or <a href="https://en.wikipedia.org/wiki/Aten">Aton</a>. Just as the ancient Egyptian deity, this all-in-one Python package provides powerful and comprehensive tools for cutting-edge materials research.</p>
<div class="docstring"><p>Welcome to the <strong>A</strong>b-ini<strong>T</strong>i<strong>O</strong> and <strong>N</strong>eutron research toolbox, or <a href="https://en.wikipedia.org/wiki/Aten">Aton</a>. Just as the ancient Egyptian deity, this all-in-one Python package provides powerful and comprehensive tools for cutting-edge materials research. </p>

<p>Aton allows you to easily create, edit and analyse all kinds of text files, with a special focus on <em>ab-initio</em> calculations. In particular, it contains interfaces for <a href="https://www.quantum-espresso.org/">Quantum ESPRESSO</a>, <a href="https://phonopy.github.io/phonopy/">Phonopy</a> and <a href="https://castep-docs.github.io/castep-docs/">CASTEP</a>. </p>

<p>This is combined with a range of spectral analysis tools to analyse your experimental campaigns, from inelastic neutron scattering to FTIR spectroscopy. </p>

<h1 id="installation">Installation</h1>

<p>As always, it is recommended to install your packages in a virtual environment: </p>

<div class="pdoc-code codehilite">
<pre><span></span><code>python3<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>.venv
<span class="nb">source</span><span class="w"> </span>.venv/bin/activate
</code></pre>
</div>

<h2 id="with-pip">With pip</h2>

<p>The fastest way to install Aton is through pip: </p>

<div class="pdoc-code codehilite">
<pre><span></span><code>pip<span class="w"> </span>install<span class="w"> </span>aton
</code></pre>
</div>

<h2 id="from-source">From source</h2>

<p>Optionally, you can install Aton from the <a href="https://github.com/pablogila/Aton/">GitHub repository</a>. </p>

<p>First install the dependencies: </p>

<div class="pdoc-code codehilite">
<pre><span></span><code>pip<span class="w"> </span>install<span class="w"> </span>pandas<span class="w"> </span>numpy<span class="w"> </span>scipy
</code></pre>
</div>

<p>Then clone the repository or download the <a href="https://github.com/pablogila/Aton/tags">latest stable release</a> as a ZIP, unzip it, and run inside the <code>Aton/</code> directory: </p>

<div class="pdoc-code codehilite">
<pre><span></span><code>pip<span class="w"> </span>install<span class="w"> </span>.
</code></pre>
</div>

<h1 id="documentation">Documentation</h1>

<p>Check the <a href="https://pablogila.github.io/Aton/">full Aton documentation online</a>.<br />
An offline version of the documentation is available in <code>docs/aton.html</code>.<br />
Code examples are included in the <code>examples/</code> folder. </p>

<h2 id="submodules">Submodules</h2>

<p>Aton contains the following modules: </p>

<ul>
<li><a href="https://pablogila.github.io/Aton/aton/text.html">text</a>. See <a href="#general-text-edition">General text edition</a>.</li>
<li><a href="https://pablogila.github.io/Aton/aton/interface.html">interface</a>. See <a href="#interfaces-for-ab-initio-codes">Interfaces for ab-initio codes</a>. </li>
<li><a href="https://pablogila.github.io/Aton/aton/spectra.html">spectra</a>. See <a href="#spectral-analysis-tools">Spectral analysis tools</a>.</li>
<li><a href="https://pablogila.github.io/Aton/aton/units.html">units</a>. Physical constants and conversion factors.</li>
<li><a href="https://pablogila.github.io/Aton/aton/atoms.html">atoms</a>. Megadictionary with data of all chemical elements. </li>
<li><a href="https://pablogila.github.io/Aton/aton/elements.html">elements</a>. Sort and analyse element data, and manage the atoms dictionary. </li>
<li><code><a href="aton/file.html">aton.file</a></code>. Manipulate files. </li>
<li><code><a href="aton/call.html">aton.call</a></code>. Run bash scripts and related. </li>
<li><a href="https://pablogila.github.io/Aton/aton/alias.html">alias</a>. Useful dictionaries for user input correction. </li>
</ul>

<h2 id="general-text-edition">General text edition</h2>

<p>The <a href="https://pablogila.github.io/Aton/aton/text.html">text</a> module includes the following general text-related submodules:</p>

<ul>
<li><code><a href="aton/text/find.html">aton.text.find</a></code>. Search for specific content in a text file. </li>
<li><a href="https://pablogila.github.io/Aton/aton/text/edit.html">edit</a>. Manipulate text files. </li>
<li><code><a href="aton/text/extract.html">aton.text.extract</a></code>. Extract data from raw text strings. </li>
</ul>

<h2 id="interfaces-for-ab-initio-codes">Interfaces for ab-initio codes</h2>

<p>The <a href="https://pablogila.github.io/Aton/aton/interface.html">interface</a> module contains interfaces for several <em>ab-initio</em> codes. These are powered by the <a href="https://pablogila.github.io/Aton/aton/text.html">text</a> module and can be easily extended. The following interfaces are included: </p>

<ul>
<li><code><a href="aton/interface/qe.html">aton.interface.qe</a></code>. Interface for <a href="https://www.quantum-espresso.org/">Quantum ESPRESSO</a> calculations.</li>
<li><code><a href="aton/interface/phonopy.html">aton.interface.phonopy</a></code>. Interface for <a href="https://phonopy.github.io/phonopy/">Phonopy</a> calculations.</li>
<li><code><a href="aton/interface/castep.html">aton.interface.castep</a></code> Interface for <a href="https://castep-docs.github.io/castep-docs/">CASTEP</a> calculations.</li>
</ul>

<h2 id="spectral-analysis-tools">Spectral analysis tools</h2>

<p>The <a href="https://pablogila.github.io/Aton/aton/spectra.html">spectra</a> module IS YET TO BE IMPLEMENTED.</p>

<ul>
<li>Things...</li>
</ul>

<h1 id="contributing">Contributing</h1>

<p>If you are interested in opening an issue or a pull request, please feel free to do so on <a href="https://github.com/pablogila/Aton/">GitHub</a>.<br />
For major changes, please get in touch first to discuss the details. </p>

<h2 id="code-style">Code style</h2>

<p>Please try to follow some general guidelines: </p>

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

<h2 id="testing-with-pytest">Testing with PyTest</h2>

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

<div class="pdoc-code codehilite">
<pre><span></span><code>pip<span class="w"> </span>install<span class="w"> </span>pytest
</code></pre>
</div>

<p>And then run PyTest inside the <code>Aton/</code> directory,</p>

<div class="pdoc-code codehilite">
<pre><span></span><code>pytest<span class="w"> </span>-vv
</code></pre>
</div>

<h2 id="compiling-the-documentation">Compiling the documentation</h2>

<p>The documentation can be compiled automatically to <code>docs/aton.html</code> with <a href="https://pdoc.dev/">pdoc</a> and Aton itself, by running:</p>

<div class="pdoc-code codehilite">
<pre><span></span><code>python3<span class="w"> </span>makedocs.py
</code></pre>
</div>

<h1 id="license">License</h1>

<p>Copyright (C) 2024 Pablo Gila-Herranz<br />
This program is free software: you can redistribute it and/or modify
it under the terms of the <strong>GNU Affero General Public License</strong> as published
by the Free Software Foundation, either version <strong>3</strong> of the License, or
(at your option) any later version.<br />
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.<br />
See the attached GNU Affero General Public License for more details. </p>
</div>

<input id="mod-aton-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
Expand Down
4 changes: 2 additions & 2 deletions docs/aton/elements.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ <h1 class="modulename">

<div class="docstring"><h1 id="description">Description</h1>

<p>This module contains functions to sort and organise element data
<p>This module contains functions to sort and analyse element data
from the <code><a href="atoms.html">aton.atoms</a></code> megadictionary, which contains the properties of all elements.
It also contains the tools needed to automatically update said megadictionary.</p>

Expand Down Expand Up @@ -187,7 +187,7 @@ <h1 id="references">References</h1>
<div class="pdoc-code codehilite"><pre><span></span><span id="L-1"><a href="#L-1"><span class="linenos"> 1</span></a><span class="sd">&#39;&#39;&#39;</span>
</span><span id="L-2"><a href="#L-2"><span class="linenos"> 2</span></a><span class="sd"># Description</span>
</span><span id="L-3"><a href="#L-3"><span class="linenos"> 3</span></a>
</span><span id="L-4"><a href="#L-4"><span class="linenos"> 4</span></a><span class="sd">This module contains functions to sort and organise element data</span>
</span><span id="L-4"><a href="#L-4"><span class="linenos"> 4</span></a><span class="sd">This module contains functions to sort and analyse element data</span>
</span><span id="L-5"><a href="#L-5"><span class="linenos"> 5</span></a><span class="sd">from the `aton.atoms` megadictionary, which contains the properties of all elements.</span>
</span><span id="L-6"><a href="#L-6"><span class="linenos"> 6</span></a><span class="sd">It also contains the tools needed to automatically update said megadictionary.</span>
</span><span id="L-7"><a href="#L-7"><span class="linenos"> 7</span></a>
Expand Down
Loading

0 comments on commit ec45118

Please sign in to comment.