Type hints

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10"]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements/dev.txt
+          pip install .
+      - name: unit testing
+        run: |
+          cd tests
+          pytest .
+      - name: Code formatting
+        run: |
+          black --check libpyvinyl/

.gitignore

@@ -6,5 +6,16 @@
 *.code-workspace
 .ropeproject
 tags
-pyvinyl.egg-info/
 doc/build
+libpyvinyl.egg-info
+.#*.*
+.readthedocs.yaml
+**/notebooks/*.json
+**/notebooks/*.h5
+**/notebooks/tmp*
+**/notebooks/.ipynb_checkpoints/
+tests/*.json
+tests/*.h5
+tests/tmp*
+dist/
+build/

DEVEL.md

@@ -0,0 +1,22 @@
+How to test
+------------------------------
+
+Minimally needed:
+```
+pip install -e ./
+cd tests/unit
+python Test.py
+```
+
+Recommended:
+```
+pip install --user pytest
+pip install -e ./
+cd tests
+# Test all
+pytest ./
+# Unit test only
+pytest ./unit
+# Integration test only
+pytest ./integration
+```

README.md

@@ -1,34 +1,110 @@
 # libpyvinyl - The python APIs for Virtual Neutron and x-raY Laboratory
 
-[![Build Status](https://travis-ci.com/PaNOSC-ViNYL/libpyvinyl.svg?branch=master)](https://travis-ci.com/PaNOSC-ViNYL/libpyvinyl)
+[![CI](https://github.com/PaNOSC-ViNYL/libpyvinyl/actions/workflows/ci.yml/badge.svg)](https://github.com/PaNOSC-ViNYL/libpyvinyl/actions/workflows/ci.yml)
 [![Documentation Status](https://readthedocs.org/projects/libpyvinyl/badge/?version=latest)](https://libpyvinyl.readthedocs.io/en/latest/?badge=latest)
-      
+
 ## Summary
+
 The python package `libpyvinyl` exposes the high level API for simulation codes under
-the umbrella of the Virtual Neutron and x-raY Laboratory (ViNYL). 
+the umbrella of the Virtual Neutron and x-raY Laboratory (ViNYL).
 
 The fundamental class is the `BaseCalculator` and its sister class `Parameters`.
 While `Parameters` is a pure state engine, i.e. it's sole purpose is to encapsulate
 the physical, numerical, and computational parameters of a simulation, the `BaseCalculator`
-exposes the interface to 
+exposes the interface to
 
-- Configure a simulation (through the corresponding `Parameters` instance)
-- Launch the simulation run
-- Collect the simulation output data and make it queriable as a class attribute
-- Snapshoot a simulation by dumping the object to disk (using the `dill` library).
+- Configure a simulation.
+- Launch the simulation run.
+- Collect the simulation output data.
+- Construct a `Data` instance that represents the simulation output data.
+- Snapshoot a simulation by dumping the object to disk.
 - Reload a simulation run from disk and continue the run with optionally modified parameters.
 
-The `BaseCalculaton` is an abstract base class, it shall not be instantiated as such.
+The `BaseCalculator` is an abstract base class, it shall not be instantiated as such.
 The anticipated use is to inherit specialised `Calculators` from `BaseCalculator` and to
 implement the core functionality in the derived class. In particular, this is required
-for the methods responsible to launch a simulation (`run()`) .
+for the methods responsible to launch a simulation through the `backengine()` method.
 
 As an example, we demonstrate in an [accompanying notebook](https://github.com/PaNOSC-ViNYL/libpyvinyl/blob/master/doc/source/include/notebooks/example-01.ipynb)
 how to declare a derived `Calculator` and implement a `backengine` method. The example then
-shows how to run the simulation, store the results in a `hdf5` file, snapshot the simulation 
+shows how to run the simulation, store the results in a `hdf5` file, snapshot the simulation
 and reload the simulation into memory.
 
-## Acknowledgement
-This project has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No. 823852.
+## Installation
+
+We recommend installation in a virtual environment, either `conda` or `pyenv`.
+
+### Create a `conda` environment
+
+```
+$> conda create -n libpyvinyl
+```
+
+### Common users
+
+```
+$> pip install libpyvinyl
+```
+
+### Developers
+
+We provide a requirements file for developers in _requirements/dev.txt_.
+
+```
+$> cd requirements
+$> pip install -r dev.txt
+```
+
+`conda install` is currently not supported.
+
+Then, install `libpyvinyl` into the same environment. The `-e` flag links the installed library to
+the source code in the repository, such that changes in the latter are immediately effective in the installed version.
 
+```
+$> cd ..
+$> pip install -e .
+```
 
+## Testing
+
+We recommend to run the unittests and integration tests.
+
+```
+$> pytest tests
+```
+
+You should see a test report similar to this:
+
+```
+=============================================================== test session starts ================================================================
+platform linux -- Python 3.8.10, pytest-6.2.4, py-1.10.0, pluggy-0.13.1
+rootdir: /home/juncheng/Projects/libpyvinyl
+collected 100 items
+
+integration/plusminus/tests/test_ArrayCalculators.py .                                                                                       [  1%]
+integration/plusminus/tests/test_Instrument.py .                                                                                             [  2%]
+integration/plusminus/tests/test_NumberCalculators.py ...                                                                                    [  5%]
+integration/plusminus/tests/test_NumberData.py ...........                                                                                   [ 16%]
+unit/test_BaseCalculator.py ..........                                                                                                       [ 26%]
+unit/test_BaseData.py ...........................                                                                                            [ 53%]
+unit/test_Instrument.py .......                                                                                                              [ 60%]
+unit/test_Parameters.py ........................................                                                                             [100%]
+
+=============================================================== 100 passed in 0.56s ================================================================
+```
+
+You can also run unittests only:
+
+```
+pytest tests/unit
+```
+
+Or to run integration tests only:
+
+```
+pytest tests/integration
+```
+
+## Acknowledgement
+
+This project has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No. 823852.

doc/source/_templates/footer.html

@@ -10,7 +10,7 @@
 </p>
     <p>
     The software
-    <it>libpyvinyl</it> is licensed under the <a href="https://github.com/PaNOSC-ViNYL/libpyvinyl/blob/master/LICENSE">LGPL version 3 or later</a>.
+    <i>libpyvinyl</i> is licensed under the <a href="https://github.com/PaNOSC-ViNYL/libpyvinyl/blob/master/LICENSE">LGPL version 3 or later</a>.
 </p>
 <p>
 This project has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No. 823852