Merge pull request #150 from RAMP-project/release/0.5.2

Release v0.5.2

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,19 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[Bug] Bug_short_description"
+labels: bug
+assignees: ''
+
+---
+
+Describe_the_bug
+
+Checklist to make sure that the bug report ist complete:
+- [ ] OS: *your_operating_system*, *your_distribution*
+- [ ] RAMP version or Branch: *RAMP version* or *branch_name*, updated on *update_date*
+- [ ] If applicable: Attach full error message
+- [ ] If applicable: Share screenshots/images of your problem
+- [ ] If applicable: Share used input data
+
+<sub>*For more information on how to contribute, please check the [Contributing Guidelines](https://github.com/RAMP-project/RAMP/blob/main/CONTRIBUTING.md).*<sub>

.github/ISSUE_TEMPLATE/custom.md

@@ -0,0 +1,16 @@
+---
+name: Custom issue template
+about: If your issue is not a bug
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+
+Providing the following information will help RAMP developers assisting you:
+- [ ] OS: *your_operating_system*, *your_distribution*
+- [ ] RAMP version or Branch: *RAMP version* or *branch_name*, updated on *update_date*
+- [ ] If applicable: Share used input data
+- 
+<sub>*For more information on how to contribute, please check the [Contributing Guidelines](https://github.com/RAMP-project/RAMP/blob/main/CONTRIBUTING.md).*<sub>

.github/pull_request_template.md

@@ -0,0 +1,6 @@
+Fix #Issue
+
+**Changes proposed in this pull request**:
+- Your_changes
+
+<sub>*For more information on how to contribute, please check the [Contributing Guidelines](https://github.com/RAMP-project/RAMP/blob/main/CONTRIBUTING.md).*<sub>

.github/workflows/pytest.yml

@@ -5,9 +5,9 @@ name: RAMP tests
 
 on:
   push:
-    branches: [ "main", "development" ]
+    branches: [ "main", "development", "joss-paper"]
   pull_request:
-    branches: [ "main", "development" ]
+    branches: [ "main", "development", "joss-paper"]
 
 permissions:
   contents: read
@@ -26,7 +26,7 @@ jobs:
     - name: Install black
       run: |
         python -m pip install --upgrade pip
-        pip install black
+        pip install black[jupyter]==24.4.2
     - name: Lint with black
       run: |
         black . --check
@@ -37,4 +37,15 @@ jobs:
         pip install -r tests/requirements.txt
     - name: Test with pytest
       run: |
-        pytest tests/
+        coverage run -m pytest tests/
+
+    - name: Check test coverage
+      run: |
+        coverage report -m
+
+    - name: Report to coveralls
+      run: |
+        coveralls
+      env:
+        COVERALLS_REPO_TOKEN: ${{ secrets.COVERALL_TOKEN }}
+        COVERALLS_SERVICE_NAME: github

.github/workflows/python-publish-pypi.yml

@@ -8,6 +8,9 @@ jobs:
   build_and_deploy:
     name: Build the release and deploy to test pypi
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
     steps:
       - name: Checkout code
         uses: actions/checkout@master
@@ -32,4 +35,4 @@ jobs:
         with:
           verbose: true
           password: ${{ secrets.RAMP_PYPI_PW }}
-          repository_url: https://upload.pypi.org/legacy/
+          repository_url: https://upload.pypi.org/legacy/

.github/workflows/python-pypi-test.yml

@@ -14,6 +14,9 @@ jobs:
   build_and_deploy:
     name: Build the release and deploy to test pypi
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
     steps:
       - name: Checkout code
         uses: actions/checkout@master
@@ -39,4 +42,4 @@ jobs:
           skip-existing: true
           verbose: true
           password: ${{ secrets.RAMP_TEST}}
-          repository-url: https://test.pypi.org/legacy/
+          repository-url: https://test.pypi.org/legacy/

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+exclude: '.git'
+default_stages: [commit]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+
+  - repo: https://github.com/psf/black
+    rev: 24.4.2
+    hooks:
+      - id: black

.readthedocs.yml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.7"
+    python: "3.10"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -23,4 +23,4 @@ sphinx:
 # Optionally set the version of Python and requirements required to build your docs
 python:
    install:
-      - requirements: docs/docs-requirements.txt
+      - requirements: docs/docs-requirements.txt

AUTHORS

@@ -23,3 +23,4 @@ Maria C.G. Hart, Leibniz Universität Hannover <[email protected]>
 Francesco Sanvito, TU Delft <[email protected]>
 Gregory Ireland, Reiner Lemoine Institut <[email protected]>
 Sergio Balderrama, Universidad Mayor de San Simon <[email protected]>
+Johann Kraft, Reiner Lemoine Institut <[email protected]>

CHANGELOG.md

@@ -4,8 +4,45 @@ Release History
 0.5.2 (dev)
 -----------
 
+**|new|**       Addition of the 'coveralls' badge to the README
+
+**|new|**       Addition of a random-seed functionality to ensure reproducible results if needed
+
+**|new|**       If a `User` instance doesn't have any appliance, its `repr` method prints the user name, and number of users with a message to mention no appliances are assigned to the instance yet. Before it raised a `ValueError`.
+
+**|new|**       Documentation template was changed to sphinx wagtail theme to improve the navigation through the documentation sections
+
+**|new|**       Add issue templates for issue creation on github
+
+**|new|**       Automatic testing of the jupyter notebooks of the documentation, to make sure the examples are always running through
+
+**|new|**       Adding depreciation warning to back-compatibility `Appliance` method in `User` class to let users know they should use the `add_appliance` method instead.
+
+**|new|**       Introduction of an Appliance parameter to model productive use duty cycles: `continuous_use_duty_cycle`
+
+**|changed|**   Expanded and revised documentation, with a particular focus on more and clearer usage examples
+
+**|changed|**   Updated requirements for contributing, including pip dependencies specific to developers
+
+**|changed|**   Expanded test coverage
+
+**|changed|**   Updated .py example input files to match the latest formalism of the RAMP code
+
+**|changed|**   Python version was bumped from 3.8 to 3.10
+
+**|changed|**   Improved the way to run the quantitative tests and the instructions to do so
+
+**|fixed|**     Windows compatibility of path to convert .py to .xlsx
+
+**|fixed|**     `rand_peak_enlarge` is rounded to be at least 1 so that the `peak_time_range` is never empty
+
+**|fixed|**     Running .xlsx files form the command line
+
+**|fixed|**     Ignore profile of appliances if any of their functional time or randomly allocated time of use are 0
+
 0.5.1 (2024-02-08)
------------
+------------------
+
 **|fixed|**     Plotting a cloud of profiles from the command line is fixed
 
 0.5.0 (2023-12-06)
@@ -38,7 +75,7 @@ Release History
 0.4.1 (2023-10-XX)
 ------------------
 
-**|hotfix|**    added option `-o` to the terminal command line interface to enable the user to provide output path to save ramp results. This option is also accessible to python users using `ofname` argument of the `ramp/ramp_run.py::run_usecase` or the `ramp/post_process/post_process.py::export_series` functions. 
+**|hotfix|**    added option `-o` to the terminal command line interface to enable the user to provide output path to save ramp results. This option is also accessible to python users using `ofname` argument of the `ramp/ramp_run.py::run_usecase` or the `ramp/post_process/post_process.py::export_series` functions.
 
 0.4.0 (2023-02-17)
 ------------------
@@ -57,7 +94,7 @@ Release History
 
 **|fixed|**     the way in which the random switch-on time is computed in the `stochastic_process` has been changed so that it is sampled with uniform probability from a concatenated set of functioning windows, rather than for each window separately (which led to short windows having higher concentration of switch-on events and demand peaks)
 
-**|fixed|**     the default value for the `peak_enlarg` parameter has been changed from the mistyped value of 0 to the intended value of 0.15 
+**|fixed|**     the default value for the `peak_enlarg` parameter has been changed from the mistyped value of 0 to the intended value of 0.15
 
 **|new|**       added a paragraph describing the algorithm of RAMP
 
@@ -93,4 +130,3 @@ Release History
 **|changed|**   changed the way in which the probability of coincident switch-on of several identical appliances owned by a single user is computed. Now, it penalisse less the probability of maximum coincidence for off-peak events
 
 **|fixed|**     `s_peak` value is now set by default to 0.5, rather than 1. This fixes an unwanted behaviour in how the `random.gauss` function worked
-

CONTRIBUTING.md

@@ -13,16 +13,40 @@ Some of the resources to look at if you're interested in contributing:
 
 By contributing to RAMP, e.g. through opening a pull request or submitting a patch, you represent that your contributions are your own original work and that you have the right to license them, and you agree that your contributions are licensed under the EUROPEAN UNION PUBLIC LICENCE v. 1.2.
 
+## Open an issue
+
+[Open an issue](https://github.com/RAMP-project/RAMP/issues) to report a bug or for a feature request, please try to provide the information summarized below
+
+- OS: *your_operating_system*, *your_distribution*
+- RAMP version or Branch: *RAMP version* or *branch_name*, updated on *update_date*
+- If applicable: Attach full error message
+- If applicable: Share screenshots/images of your problem
+- If applicable: Share used input data
+
 ## Submitting changes
 
 To contribute changes:
 - Fork the project on GitHub
+- Follow the "Setup" steps below
 - Create a feature branch (e.g. named "add-this-new-feature") to work on in your fork
 - Add your name to the [AUTHORS](AUTHORS) file
 - Commit your changes to the feature branch
 - Push the branch to GitHub
 - On GitHub, create a new pull request from the feature branch
 
+### Setup
+
+1. Create a virtual environment and install the dev dependencies with
+
+        pip install -r dev_requirements.txt
+
+2. Install the pre-commit hooks with
+
+        pre-commit install
+
+   This will mainly make sure you can't commit if your code is not linted with black.
+   The pre-commit hook will check if your code is linted and if it is not it will simply lint it for you, you then only need to stage the changes made by the linter and commit again, as simple as that :)
+
 ### Pull requests
 
 Before submitting a pull request, check whether you have:
@@ -44,18 +68,32 @@ Please try to write clear commit messages. One-line messages are fine for small
 
 ## Testing
 
-We have a qualitative testing functionality that allows to compare the results arising from a modified version of the code against default ones, for the 3 reference input files provided within the code itself.
+Testing is used by RAMP developers to make sure their new feature/bug fix is not breaking existing code. As RAMP is stochastic some tests are only qualitative, other unit tests are ran by GitHub Actions.
+
+Before running the tests locally, you need to install the testing dependencies
+
+```
+pip install -r tests/requirements.txt
+```
+
+### Qualitative testing
+
+The qualitative testing functionality allows to compare the results arising from a modified version of the code against default ones, for the 3 reference input files provided within the code itself.
+
+To run the qualitative test, you'll have to run
+ ```
+ python ramp/test/test_run.py
+ ```
+from the root level of this repository.
+
+If you already ran this script, you will be asked if you want to overwrite the results files (if you decide not to, the results are not going to be regenerated from your latest code version). You should compare the results of your code and those saved from the latest stable version thanks to the image which is displayed after the script ran.
 
-This functionality is accessible via `test/test_run.py`. To run the qualitative test, you'll have to go through the following steps:
-   1. run your modified code for the 3 reference input files for 30 days each. This will create 3 corresponding output files in the `results` folder
-   2. run `test/test_run.py` and visualise the comparison between the results of your code and those obtainable with the latest stable version
-
 Ideally, the difference between reference and new results should be minimal and just due to the stochastic nature of the code. If more pronounced, it should be fully explainable based on the changes made to the code and aligned to the expectations of the developers (i.e. it should reflect a change in the output *wanted* and precisely *sought* with the commit in question).
 
 ### Unit tests
 
-Install `pytest` (`pip install pytest`) and run `pytest tests/` form the root of the repository to run the unit tests
+Run `pytest tests/` form the root of the repository to run the unit tests.
 
 ## Attribution
 
-The layout and content of this document is partially based on [calliope](https://github.com/calliope-project/calliope/blob/master/CONTRIBUTING.md)'s equivalent document.
+The layout and content of this document is partially based on [calliope](https://github.com/calliope-project/calliope/blob/master/CONTRIBUTING.md)'s equivalent document.