Utilities for aiding in the construction of exciting inputs and the postprocessing exciting outputs.
Project description
exciting Tools
exciting tools is intended to be a collection of scripts to facilitate the generation of exciting inputs and the post-processing of exciting outputs.
Installation
If one wishes to import exciting tools in their own scripts, it can be installed from this project's root directory
(<EXCITINGROOT>/tools/exciting_tools
) with:
pip install -e .
External Package Dependencies
If a new external dependency is introduced to the package, this also requires adding to setup.py
such that pip is aware
of the new dependency.
Basic File Structure
In general, modules should begin with a docstring giving an overview of the module's purpose. External python
libraries should then be imported, followed by a space, then local modules belonging to exciting tools. Local modules
should be loaded with relative paths, rather than prepending the system path sys.path.insert(0,'/path/to/module_directory')
:
"""
Functions that operate on lattice vectors
"""
import numpy as np
from .maths.math_utils import triple_product
This may change in the future in favour of loading modules in __init__.py
.
Code Formatting
We're currently favouring yapf formatter, which by default applies PEP8 formatting to the code, however even formatter that applies the PEP8 standard is sufficient.
Documentation
Writing Documentation
All functions and classes should be documented. The favoured docstring is reStructuredText:
class SimpleEquation:
def demo(self, a: int, b: int, c: int) -> list:
"""
Function definition
:param int a: quadratic coefficient
:param int b: linear coefficient
:param c: free term
:type c: int
:return list y: Function values
"""
where the type can be specified in the param
description, or separately using the type
tag. For more details on the
documentation syntax, please refer to this link. The google style guide for reStructuredText docstrings is also
acceptable to follow.
Generating Documentation
- TODO(Alex) Issue 57 Set up generation of documentation from docstrings, and description here.
Testing
Every function should have a test where possible, unless the function is correct by inspection. The naming convention
for a module called module.py
is to prepend the it with test_
:
excitingtools/module.py # Collection of functions
tests/test_module.py # Collection of tests for functions in module.py
Tests are intended to be run using pytest, for which the documentation can be found here.
One is able to run pytest
from the exciting_tools
root with no arguments. By default, all test files, classes and functions defined in the specification,
exciting_tools/pytest.ini
, will get executed.
Parsers
The parsers are used in the test suite. Therefore, they should only return dictionaries with a specific structure.
The tolerance comparison will only evaluate the values of lowest-nested keys. As such, one should consider how they structure the parsed data. For example, it makes more sense to structure data like:
{‘wannier1’: {‘localisation_vector’: np.array(shape=(3)),
‘Omega’: float
}
}
such that the tolerances will be w.r.t. localisation_vector
, and Omega
, rather than using the structure:
{‘localisation_vector’: {‘wannier1’: np.array(shape=(3))
‘wannier2’: np.array(shape=(3))
},
‘Omega’: {‘wannier1’: float
‘wannier2’: float
}
}
which will results in tolerances defined w.r.t. wannier1
and wannier2
. One can see in the latter case, there is no distinction between localisation_vector
and Omega
. In general, we’re more likely to want to set different tolerances for different properties, rather than for different functions with the same set of properties.
One could also structure the data like:
{‘localisation_vector’: np.array(shape=(n_wannier, 3)),
‘Omega’: : np.array(shape=(n_wannier)
}
where the less serialised data removes the key nesting.
Uploading to PyPi
excitingtools is available as a separate package on PyPi. In order to upload a new version:
# Ensure twine is installed
pip3 install twine
# Build the wheels
cd $EXCITINGROOT/tools/exciting_tools
python3 setup.py sdist bdist_wheel
# Test the distribution and uploading (one requires a test-PyPi account)
twine check dist/*
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
# Upload to PyPi
twine upload dist/*
Before doing so, please ensure the semantic versioning is appropriately updated in setup.py
.
Contributors
The following people (in alphabetic order by their family names) have contributed to excitingtools:
- Alexander Buccheri
- Hannah Kleine
- Martin Kuban
- Benedikt Maurer
- Fabian Peschel
- Daniel Speckhard
- Elisa Stephan
- Mara Voiculescu
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for excitingtools-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1992aa029a1a96de99c009628bb7bc932d5c4e703ceb4d7b65c09a0b8a261449 |
|
MD5 | b95d0acce68c1b9439c2120f07beef01 |
|
BLAKE2b-256 | e10dde7b34ffba10cfc425b021d15921da947d2fd64984631fd5906bfcc881d3 |