Merge pull request #15 from aaghamohammadi/dev

Ready to publish v1.5.3
aaghamohammadi · Dec 28, 2023 · f6c1208 · f6c1208
2 parents 3cc4015 + 254a420
commit f6c1208
Show file tree

Hide file tree

Showing 17 changed files with 304 additions and 78 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,18 @@
+# Description
+
+Please include a summary of the changes, along with relevant motivation and context. If there are any related issues, please mention them. Also, list any dependencies required for this change.
+
+Fixes # (issue)
+
+## Type of change
+
+We use semantic versioning for the pysolorie project. Therefore, to determine the appropriate version, please delete the options that are not relevant.
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] This change requires a documentation update
+
+# How Has This Been Tested?
+
+Please describe the tests that you ran to verify your changes.
diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # pysolorie
 
-[![CodeQL](https://github.com/aaghamohammadi/pysolorie/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/aaghamohammadi/pysolorie/actions/workflows/github-code-scanning/codeql)
 [![Quality Checks](https://github.com/aaghamohammadi/pysolorie/actions/workflows/quality_checks.yml/badge.svg?branch=main)](https://github.com/aaghamohammadi/pysolorie/actions/workflows/quality_checks.yml)
 [![Publish](https://github.com/aaghamohammadi/pysolorie/actions/workflows/publish.yml/badge.svg?branch=main)](https://github.com/aaghamohammadi/pysolorie/actions/workflows/publish.yml)
+[![CodeQL](https://github.com/aaghamohammadi/pysolorie/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/aaghamohammadi/pysolorie/actions/workflows/github-code-scanning/codeql)
 ![GitHub License](https://img.shields.io/github/license/aaghamohammadi/pysolorie)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/pysolorie)
 [![Documentation Status](https://readthedocs.org/projects/pysolorie/badge/?version=latest)](https://pysolorie.readthedocs.io/en/latest/?badge=latest)
@@ -13,6 +13,9 @@
 ![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)
 ![code style: black](https://img.shields.io/badge/code%20style-black-black)
 
+[![SonarCloud](https://sonarcloud.io/images/project_badges/sonarcloud-white.svg)](https://sonarcloud.io/summary/new_code?id=aaghamohammadi_pysolorie)
+
+
 
 **pysolorie** stands for **Py**thon **Sol**ar **Orie**ntation Analysis of Solar Panel. It is a Python library designed to help you analyze the orientation of solar panels.
 
@@ -27,7 +30,7 @@ How can one maximize the solar irradiation energy received by a solar panel?
 
 - Finding the optimal tilt angle for a fixed solar panel, assuming a clear-sky condition.
 - Plotting the optimal tilt angle over a range of days.
-- Plotting the total direct irradiation over a range of days.
+- Plotting the daily direct irradiation energy over a range of days.
 - Generating a CSV, JSON, or XML report detailing the optimal tilt angle over a range of days.
 - Calculating the sunrise and sunset hour angles for a specific day.
 - Utilizing Hottel's model to quantify clear-sky conditions and estimate the atmospheric transmission of clear-sky beam radiation.

diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -1,6 +1,40 @@
 Changelog
 =========
 
+Version 1.5.3
+-------------
+
+Release date: 2023-12-28
+
+Changed
+^^^^^^^
+
+- Improved documentation and code comments to clarify the calculation and representation of direct irradiation, rather than total direct irradiation.
+- Standardized exception handling in the ``observer.py`` by decorating relevant methods, ensuring consistency in logging exceptions.
+- Made code improvements in ``tests/test_*`` files for comprehensive coverage and robust testing of the solar irradiation logic under different geographical and temporal conditions.
+
+Fixed
+^^^^^
+- Modified ``numerical_integration.py`` to return 0 for direct irradiation during the polar night when the sun does not rise.
+- Addressed improper handling of zero values for sunrise and sunset hour angles representing extreme latitude scenarios (Midnight Sun and Polar Night).
+- Enhanced the ``observer.py`` to handle cases of Midnight Sun and Polar Night with appropriate logging for exceptional circumstances.
+- Fixed issues with missing logger instances in ``plotter.py`` by correctly setting up decorators and ensuring log messages are adequately recorded.
+
+Documentation
+^^^^^^^^^^^^^
+- Refactored ``README.md`` for syntactical accuracy in the representation of solar irradiance and optimized the explanation of solar panel orientation.
+- Updated all instances in documentation where "total direct irradiation" was mentioned to "direct irradiation" to maintain consistency with the recent code updates.
+- Included explanation for Midnight Sun and Polar Night phenomena in solar irradiance context to educate users about edge cases in solar panel energy calculations.
+- Refined code examples and added clarifications on special cases where zero irradiation is expected, enhancing the user's understanding.
+
+Testing
+^^^^^^^
+
+- Expanded the test suite to cover new scenarios, like polar regions and edge calendar days where the sun's behavior significantly differs (e.g., Midnight Sun and Polar Night).
+- Implemented additional assertions in unit tests to cover the new edge cases introduced by the recent geographic and temporal scenarios handled in the update.
+
+
+
 Version 1.5.2
 -------------
 

diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -26,9 +26,10 @@ It is highly recommended to use ``virtualenv`` for the development. ``virtualenv
 
     .. code-block:: bash
 
-        $ python3 -m venv .venv
-        $ source .venv/bin/activate
-        $ pip install -r dev-requirements.txt
+        python3 -m venv .venv
+        source .venv/bin/activate
+        pip install --upgrade pip
+        pip install -r dev-requirements.txt
 
 5. **Install pre-commit**:
 
@@ -37,7 +38,7 @@ remote repository. ``pre-commit`` is a tool that manages and maintains multi-lan
 
     .. code-block:: bash
 
-        $ pre-commit install
+        pre-commit install
 
 
 Running Tests
@@ -56,31 +57,31 @@ For example, to run the linter, you would use the following command:
 
     .. code-block:: bash
 
-        $ tox -e lint
+        tox -e lint
 
 If you want to reformat the source code. You can use the following command:
 
     .. code-block:: bash
 
-        $ tox -e format -- src tests
+        tox -e format -- src tests
 
 To verify the correctness of the formatting, execute the command below:
 
     .. code-block:: bash
 
-        $ tox -e format
+        tox -e format
 
 To check the types in the code with mypy, use this:
 
     .. code-block:: bash
 
-        $ tox -e typecheck
+        tox -e typecheck
 
 To run unit tests for the python, e.g., python 3.10, you can run this command:
 
     .. code-block:: bash
 
-        $ tox -e py310
+        tox -e py310
 
 Submitting Your Contributions
 -----------------------------
@@ -92,6 +93,7 @@ We welcome and appreciate your contributions to the pysolorie project! Here are
 - **Adding New Features**: Contribute by introducing new features that can enhance the functionality of the project.
 
 After making your changes and ensuring all tests pass, you can submit your contributions by creating a pull request on GitHub.
+Please be informed that the pull request should be created for the **dev branch**. We do not accept pull requests for the main branch.
 
 Please note, we strive to keep our dependencies to a minimum. Any addition of a new dependency should be well justified and absolutely necessary.
 

diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -13,17 +13,17 @@ The easiest way to install ``pysolorie``  is from PyPI.
 
     python3 -m pip install pysolorie
 
-Calculating Total Direct Irradiation for a Year
------------------------------------------------
+Calculating Direct Irradiation for a Year
+-----------------------------------------
 
-Suppose we aim to calculate the total direct irradiation for a specific location. The following code determines the total direct irradiation received by a solar panel, assuming an optimal tilt angle for each day of the year at a given location. In this scenario, the location is Tehran, Iran.
+Suppose we aim to calculate the direct irradiation for a specific location. The following code determines the direct irradiation received by a solar panel, assuming an optimal tilt angle for each day of the year at a given location. In this scenario, the location is Tehran, Iran.
 
 .. code-block:: python
 
    from pysolorie import IrradiationCalculator
 
    # Instantiate an IrradiationCalculator object for the city of Tehran
-   calculator = IrradiationCalculator(
+   irradiation_calculator = IrradiationCalculator(
        climate_type="MIDLATITUDE SUMMER",
        observer_altitude=1200,
        observer_latitude=35.6892
@@ -36,9 +36,9 @@ Suppose we aim to calculate the total direct irradiation for a specific location
    # Loop over each day of the year
    for day in range(from_day, to_day + 1):
        # Find the optimal tilt angle for the given day
-       optimal_tilt_angle = calculator.find_optimal_orientation(day)
+       optimal_tilt_angle = irradiation_calculator.find_optimal_orientation(day)
        # Calculate the direct irradiation for the given day and add it to the total
-       total_irradiation += calculator.calculate_direct_irradiation(
+       total_irradiation += irradiation_calculator.calculate_direct_irradiation(
            optimal_tilt_angle, day
        )
 
@@ -65,7 +65,7 @@ The ``climate_type`` can be one of the following:
     from pysolorie import IrradiationCalculator
 
     # Instantiate an IrradiationCalculator object for the city of Tehran
-    calculator = IrradiationCalculator(
+    irradiation_calculator = IrradiationCalculator(
         climate_type="MIDLATITUDE SUMMER",
         observer_altitude=1200,
         observer_latitude=35.6892
@@ -80,7 +80,7 @@ The ``climate_type`` can be one of the following:
 
 Calculating Direct Irradiation
 ------------------------------
-The ``calculate_direct_irradiation`` method calculates the total direct irradiation received by a solar panel for a specified tilt angle and day of the year.
+The ``calculate_direct_irradiation`` method calculates the direct irradiation received by a solar panel for a specified tilt angle and day of the year.
 
 The ``climate_type`` can be one of the following:
 
@@ -94,7 +94,7 @@ The ``climate_type`` can be one of the following:
     from pysolorie import IrradiationCalculator
 
     # Instantiate an IrradiationCalculator object for the city of Tehran
-    calculator = IrradiationCalculator(
+    irradiation_calculator = IrradiationCalculator(
         climate_type="MIDLATITUDE SUMMER",
         observer_altitude=1200,
         observer_latitude=35.6892
@@ -156,10 +156,10 @@ The plot will be saved to the specified path. The ``plot_kwargs`` and ``savefig_
 parameters can be used to customize the plot and the savefig function, respectively. If no path is provided, the plot will be displayed but not saved.
 If the path is provided, the plot will be saved to the specified path and not displayed. If you want to both display and save the plot, you should call ``plt.show()`` after this function.
 
-Plotting the Total Direct Irradiation
+Plotting the Direct Irradiation
 -------------------------------------
 
-The ``plot_total_direct_irradiation`` method plots the total direct irradiation for a range of days.
+The ``plot_total_direct_irradiation`` method plots the direct irradiation for a range of days.
 
 .. code-block:: python
 
@@ -175,16 +175,16 @@ The ``plot_total_direct_irradiation`` method plots the total direct irradiation
         observer_latitude=35.6892
     )
 
-    # Plot the total direct irradiation for days 60 to 70
+    # Plot the direct irradiation for days 60 to 70
     plotter.plot_total_direct_irradiation(
        irradiation_calculator,
        from_day=60,
        to_day=70,
        path=Path("results.png"),
        plot_kwargs={
            "xlabel": "Day",
-           "ylabel": "Total Direct Irradiation (Megajoules per square meter)",
-           "title": "Total Direct Irradiation",
+           "ylabel": "Direct Irradiation (Megajoules per square meter)",
+           "title": "Direct Irradiation",
        },
        savefig_kwargs={"dpi": 300},
     )
@@ -346,10 +346,10 @@ and the ``hour_angle`` method calculates the hour angle given the solar time.
 This will print the solar declination and hour angle in radians.
 For example, on January 1st at 1pm, the solar declination is approximately ``-0.401`` radians and the hour angle is approximately ``0.262`` radians.
 
-Calculating Transmittance Components with the Hottel Model
-----------------------------------------------------------
+Calculating Transmittance Components with the Hottel's Model
+------------------------------------------------------------
 
-The Hottel Model is used for estimating clear-sky beam radiation transmittance based on climate type and observer altitude. The `calculate_transmittance_components` method of the `HottelModel` class calculates the components of clear-sky beam radiation transmittance :math:`a_0`, :math:`a_1`, and :math:`k` based on climate type and observer altitude.
+The Hottel's model  is used for estimating clear-sky beam radiation transmittance based on climate type and observer altitude. The `calculate_transmittance_components` method of the `HottelModel` class calculates the components of clear-sky beam radiation transmittance :math:`a_0`, :math:`a_1`, and :math:`k` based on climate type and observer altitude.
 
 .. code-block:: python
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -31,7 +31,7 @@ In our case, we are using Hottel's model to estimate the transmittance of direct
 
 - Finding the optimal tilt angle for a fixed solar panel, assuming a clear-sky condition.
 - Plotting the optimal tilt angle over a range of days.
-- Plotting the total direct irradiation over a range of days.
+- Plotting the daily direct irradiation energy over a range of days.
 - Generating a CSV, JSON, or XML report detailing the optimal tilt angle over a range of days.
 - Calculating the sunrise and sunset hour angles for a specific day.
 - Utilizing Hottel's model to quantify clear-sky conditions and estimate the atmospheric transmission of clear-sky beam radiation.

diff --git a/docs/reference/pysolorie.numerical_integration.rst b/docs/reference/pysolorie.numerical_integration.rst
@@ -1,5 +1,5 @@
-Total Direct Irradiation
-========================
+Direct Irradiation
+==================
 
 .. automodule:: pysolorie.numerical_integration
    :members: