Merge pull request #15 from lorisercole/release/0.3.0

Release/0.3.0

.pre-commit-config.yaml

@@ -0,0 +1,51 @@
+# Install pre-commit hooks via
+# pre-commit install
+
+- repo: local
+  hooks:
+  # yapf = yet another python formatter
+  - id: yapf
+    name: yapf
+    entry: yapf
+    language: system
+    types: [python]
+    args: ["-i"]
+    exclude: &exclude_files >
+      (?x)^(
+        thermocepstrum_gui/utils/tk_html_widgets/*.py|
+        docs/.*|
+        examples/.*|
+        setup.py|
+      )$
+
+- repo: git://github.com/pre-commit/pre-commit-hooks
+  rev: v2.3.0
+  hooks:
+  - id: check-yaml
+  - id: check-merge-conflict
+  - id: check-symlinks
+  - id: check-json
+  - id: check-executables-have-shebangs
+  - id: double-quote-string-fixer
+  - id: end-of-file-fixer
+  - id: trailing-whitespace
+    exclude: >
+      (?x)^(
+        thermocepstrum_gui/utils/tk_html_widgets/*.py|
+        docs/.*|
+        examples/.*|
+      )$
+
+#  # prospector: collection of linters
+#  - id: prospector
+#    language: system
+#    types: [file, python]
+#    name: prospector
+#    description: "This hook runs Prospector: https://github.com/landscapeio/prospector"
+#    entry: prospector
+#
+#  - id: version-number
+#    name: Check version numbers
+#    entry: python ./.travis-data/check_version.py
+#    language: system
+#    files: '^(setup.json)|(aiida_diff/__init__.py)'

.style.yapf

@@ -0,0 +1,6 @@
+[style]
+based_on_style=google
+column_limit=120
+spaces_before_comment=3
+disable_ending_comma_heuristic=True
+SPLIT_BEFORE_NAMED_ASSIGNS=False

MANIFEST.in

@@ -0,0 +1,11 @@
+recursive-include examples *
+include LICENSE.txt
+include setup.json
+include thermocepstrum/README.md
+include thermocepstrum/metadata.json
+include thermocepstrum/utils/plot_style.mplstyle
+exclude thermocepstrum/utils/blocks.py
+exclude thermocepstrum/utils/blockanalysis.py
+include thermocepstrum_gui/README_GUI.md
+include thermocepstrum_gui/assets/icon.gif
+include thermocepstrum_gui/assets/languages.json

README.md

@@ -1,33 +1,51 @@
 # thermocepstrum
 Code to compute thermal conductivity through cepstral analysis of heat flux time series, as described in papers:
- - Ercole, Marcolongo, Baroni, Sci. Rep. 7, 15835 (2017), https://doi.org/10.1038/s41598-017-15843-2
- - for the multi-component analysis:  Baroni, Bertossa, Ercole, Grasselli, Marcolongo, https://arxiv.org/abs/1802.08006
 
-**Acknowledgement**  The development of this software is part of the scientific program of the EU MaX Centre of Excellence for Supercomputing Applications (Grant No. 676598) and has been partly funded through it.
+ - (cepstral analysis) [Ercole, Marcolongo, Baroni, *Sci. Rep.* **7**, 15835 (2017)](https://doi.org/10.1038/s41598-017-15843-2)
+ - (multicomponent systems) [Bertossa, Grasselli, Ercole, Baroni, *Phys. Rev. Lett.* **122**, 255901 (2019)](https://doi.org/10.1103/PhysRevLett.122.255901) ([arXiv](https://arxiv.org/abs/1808.03341))
+ - (review) [Baroni, Bertossa, Ercole, Grasselli, Marcolongo, *Handbook of Materials Modeling* (2018)](https://doi.org/10.1007/978-3-319-50257-1_12-1) ([arXiv](https://arxiv.org/abs/1802.08006))
+
+**Acknowledgment**  The development of this software is part of the scientific program of the EU MaX Centre of Excellence for Supercomputing Applications (Grant No. 676598, 824143) and has been partly funded through it.
 
 ### Usage
-The code can be used as a **library**, for example in a Jupyter notebook. 
-In the `examples` folder you can find some examples. 
+There is a [**GUI**](README_GUI.md) that you can try after installing everything (only Python 3).
+
+The code can be used as a **library**, for example in a Jupyter notebook.
+In the [`examples`](examples/) folder you can find some examples.
 
-Alternatively, you can run the code `analysis.py` from the **command line**.
+Alternatively, you can run the code `analysis.py` from the **command line** without any installation procedure.
 It can execute most of the cepstral analysis routines, returning the results in a series of data files and PDF plots.
-See the `examples` folder and the help (`python analysis.py --help`) for more information.
+See the [`examples/example_commandline_NaCl`](examples/example_commandline_NaCl/) folder and the help (`python analysis.py --help`) for more information.
 
 ### Requirements
- - Python 2.7
- - Numpy
- - Scipy
- - Matplotlib
+#### only cepstral analysis (command line interface)
+ - Python 2.7 or 3.x
+ - numpy
+ - scipy
+ - matplotlib
+#### graphical user interface
+ - all the requirements of cepstral analysis
+ - Python 3 only
+ - tkinter
+ - future-fstrings
+ - pillow (you may need upgrade it)
+ - tk-html-widgets
+ - markdown2
 
 ### Installation
-  You can simply pip-install thermocepstrum with `pip install thermocepstrum`.
+  You can simply pip-install thermocepstrum downloading it from PyPI with `pip install thermocepstrum`.
 
   Alternatively:
+
   1. Clone this repository: `git clone https://github.com/lorisercole/thermocepstrum.git`
   2. Install the package with pip (dependencies will be automatically downloaded). For example:
 ```
 cd thermocepstrum
 pip install .
 ```
-
   You are done! You can check that the installation is working by trying to run the command `thermocepstrum-analysis`.
+
+  If you use Python 3, the Graphical User Interface will be installed and can be started with the command `thermocepstrum-gui`.
+
+### Issues
+  You are strongly encouraged to report any issue on the [official](https://github.com/lorisercole/thermocepstrum/issues) GitHub issues page.

README_GUI.md

@@ -0,0 +1,19 @@
+# Thermocepstrum GUI
+
+### Installation
+   See [README.md](README.md)
+
+### Usage
+   - run `thermocepstrum-gui` from the command line
+   - select the input file with the  "..." button. After you select the file a preview will be shown if possible. If a binary file was selected the preview will not update, and a message will pop up.
+   - select the input format. "table" is the standard column formatted data file with in the first line an header with the names of the columns. Vector data (like the 3 components of the currents) must be grouped with "name_[1] name_[2] name_[3]" ("[]" must be present). Vectors will be automatically recognized. "dict" is a numpy dictionary (saved with np.save() ) with binary data. This type of file can be generated by this program when you press "export data" in the "File" menu. They are a lot faster to save and to load.
+   - "Next". If the selected file type is wrong, an error message will pop up and the program will return to the previous step.
+   - read the instructions and select the type of data of the various columns
+   - select the units
+   - "Next"
+   - Input the required values (if not already filled with the information encoded in the input file). "filter width" can be left as is, it is only for visualization purposes and can be changed later.
+   - select the resampling frequency with the cursor. You can press "Resample" to see the effect. This is necessary to not run the analysis on useless portions of the spectrum. You can select the first important feature of the plot near zero.
+   - "Next"
+   - the result is shown. It is possible to modify the number of cepstral coefficients and see the effect
+
+At any time it is possible to save everything by pressing "export data" in the menu. Later all the parameters will be automatically loaded if you select the generated file as the input.

examples/README.md

@@ -11,4 +11,4 @@ These examples show how to use the thermocepstrum package in a Python script, st
 
 #### Command line examples
 These examples show how to use the command line program `analysis.py` to perform cepstral analysis in a straightforward. This is an expedient tool to analyse a time series using predefined parameters. Results are produced in the form of numerous text/binary files and pdf plots.
-* `example_commandline_NaCl`: analysis of molten NaCl, a two-component system.
+* `example_commandline_NaCl`: analysis of molten NaCl, a two-component system.