Merge pull request #11 from aaghamohammadi/dev

Ready to release version 1.4.0
aaghamohammadi · Dec 18, 2023 · 23b68d4 · 23b68d4
2 parents f5a4ff4 + e5fb675
commit 23b68d4
Show file tree

Hide file tree

Showing 24 changed files with 430 additions and 138 deletions.
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -1,6 +1,38 @@
 Changelog
 =========
 
+
+Version 1.4.0
+-------------
+
+Release date: 2023-12-18
+
+Added
+^^^^^
+- Added ``plot_total_direct_irradiation`` method in the Plotter class for plotting total direct irradiation over a specified range of days with an example included in getting_started.rst.
+
+Changed
+^^^^^^^
+- Streamlined ``setup.cfg`` to remove unnecessary sphinx-apidoc commands.
+- Optimized numerical integration methods to use radians and improved precision settings.
+- Updated CSV report generation in ``ReportGenerator`` to include total direct irradiation in output.
+
+Documentation
+^^^^^^^^^^^^^
+- Implemented significant restructuring and simplifying of the reStructuredText (rst) documentation across many files (modules.rst and individual module documentation).
+- Updated module titles to match functionality more accurately, such as "Atmospheric Transmission" and "Hottel Model" for improved clarity in the table of contents.
+- Standardized and enhanced docstrings in all module scripts to include detailed descriptions and references where applicable.
+
+
+Testing
+^^^^^^^
+- Extended tests in ``test_pysolorie.py`` for additional coverage of new features.
+
+Bug Fixes
+^^^^^^^^^
+- Corrected the value and unit of the solar constant in ``SolarIrradiance`` from Watts to Megawatts per square meter.
+
+
 Version 1.3.1
 -------------
 

diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -42,6 +42,35 @@ The ``climate_type`` can be one of the following:
 
     print(f"Optimal orientation: {result}")
 
+Calculating Direct Irradiation
+------------------------------
+The ``calculate_direct_irradiation`` method calculates the total direct irradiation for a given solar panel orientation and day of the year.
+
+The ``climate_type`` can be one of the following:
+
+- ``"MIDLATITUDE SUMMER"``
+- ``"MIDLATITUDE WINTER"``
+- ``"TROPICAL"``
+- ``"SUBARCTIC SUMMER"``
+
+.. code-block:: python
+
+    from pysolorie import IrradiationCalculator
+
+    # Create an irradiation calculator for Tehran in the summer
+    irradiation_calculator = IrradiationCalculator(
+        "MIDLATITUDE SUMMER", 1200, 35.6892
+    )
+
+    # Define the panel orientation and day of the year
+    panel_orientation: float = 45.0  # degrees
+    day_of_year: int = 172  # June 21, approximately the summer solstice
+
+    # Calculate the direct irradiation
+    result = irradiation_calculator.calculate_direct_irradiation(panel_orientation, day_of_year)
+
+    print(f"Direct irradiation: {result}")
+
 
 Generating a CSV Report
 -----------------------
@@ -85,6 +114,29 @@ 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
+-------------------------------------
+
+The ``plot_total_direct_irradiation`` method plots the total direct irradiation for a range of days.
+
+.. code-block:: python
+
+    from pysolorie import Plotter, IrradiationCalculator
+    from pathlib import Path
+
+    # Create a plotter and an irradiation calculator
+    plotter = Plotter()
+    irradiation_calculator = IrradiationCalculator("MIDLATITUDE SUMMER", 1200, 35.6892)
+
+    # Plot the total direct irradiation for days 60 to 70
+    plotter.plot_total_direct_irradiation(irradiation_calculator, 60, 70, Path('results.png'), plot_kwargs={'xlabel': 'Day', 'ylabel': 'Total Direct Irradiation (MW/m²)', 'title': 'Total Direct Irradiation', "figsize": (16,9)}, savefig_kwargs={'dpi': 300})
+
+The plot will be saved to the specified path. The ``plot_kwargs`` and ``savefig_kwargs``
+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.
+
+
+
 
 Calculating Sunrise and Sunset
 ------------------------------

diff --git a/docs/index.rst b/docs/index.rst
@@ -23,7 +23,9 @@ A solar collector can be positioned at a fixed orientation to maximize energy re
 or it can be fixed for optimal performance throughout the year.
 The orientation can then be adjusted for the next time period. Solar irradiation is composed of three components: the direct beam, sky diffusion, and ground reflection.
 Now, we are considering flat solar panels and focusing on direct beam irradiation, which contributes the most to solar irradiation.
-There are various models available for different climate types. In our case, we are using Hottel's model to estimate the transmittance of direct solar radiation through clear atmospheres [3]_.
+There are various models available for different climate types.
+Moreover, a cloudy sky or polluted air affects the solar energy received on Earth.
+In our case, we are using Hottel's model to estimate the transmittance of direct solar radiation through clear atmospheres [3]_.
 
 ``pysolorie`` is a library designed to help you find this optimal orientation. Its features include, but are not limited to:
 

diff --git a/docs/reference/modules.rst b/docs/reference/modules.rst
@@ -1,7 +1,14 @@
-pysolorie
-=========
+API Reference
+=============
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 3
 
-   pysolorie
+   pysolorie.atmospheric_transmission
+   pysolorie.irradiance
+   pysolorie.model
+   pysolorie.numerical_integration
+   pysolorie.observer
+   pysolorie.plotter
+   pysolorie.report
+   pysolorie.sun_position
diff --git a/docs/reference/pysolorie.atmospheric_transmission.rst b/docs/reference/pysolorie.atmospheric_transmission.rst
@@ -1,7 +1,5 @@
-pysolorie.atmospheric\_transmission module
-==========================================
+Atmospheric Transmission
+========================
 
 .. automodule:: pysolorie.atmospheric_transmission
    :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/reference/pysolorie.irradiance.rst b/docs/reference/pysolorie.irradiance.rst
@@ -1,7 +1,5 @@
-pysolorie.irradiance module
-===========================
+Solar Irradiance
+================
 
 .. automodule:: pysolorie.irradiance
    :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/reference/pysolorie.logger.rst b/docs/reference/pysolorie.logger.rst
diff --git a/docs/reference/pysolorie.model.rst b/docs/reference/pysolorie.model.rst
@@ -1,7 +1,5 @@
-pysolorie.model module
-======================
+Hottel Model
+============
 
 .. automodule:: pysolorie.model
    :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/reference/pysolorie.numerical_integration.rst b/docs/reference/pysolorie.numerical_integration.rst
@@ -1,7 +1,5 @@
-pysolorie.numerical\_integration module
-=======================================
+Total Direct Irradiation
+========================
 
 .. automodule:: pysolorie.numerical_integration
    :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/reference/pysolorie.observer.rst b/docs/reference/pysolorie.observer.rst
@@ -1,7 +1,5 @@
-pysolorie.observer module
-=========================
+Observer
+========
 
 .. automodule:: pysolorie.observer
    :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/reference/pysolorie.plotter.rst b/docs/reference/pysolorie.plotter.rst
@@ -1,7 +1,5 @@
-pysolorie.plotter module
-========================
+Plotter
+=======
 
 .. automodule:: pysolorie.plotter
    :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/reference/pysolorie.report.rst b/docs/reference/pysolorie.report.rst
@@ -1,7 +1,5 @@
-pysolorie.report module
-=======================
+Report
+======
 
 .. automodule:: pysolorie.report
    :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/reference/pysolorie.rst b/docs/reference/pysolorie.rst
diff --git a/docs/reference/pysolorie.sun_position.rst b/docs/reference/pysolorie.sun_position.rst
@@ -1,7 +1,5 @@
-pysolorie.sun\_position module
-==============================
+Sun Position
+============
 
 .. automodule:: pysolorie.sun_position
    :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/setup.cfg b/setup.cfg
@@ -1,6 +1,6 @@
 [metadata]
 name = pysolorie
-version = 1.3.1
+version = 1.4.0
 description = Orientation Analysis of Solar Panel
 long_description = file: README.md
 long_description_content_type = text/markdown
@@ -103,11 +103,4 @@ deps =
     sphinx
     sphinx-rtd-theme
 commands =
-    sphinx-apidoc \
-        --force \
-        --implicit-namespaces \
-        --module-first \
-        --separate \
-        -o docs/reference/ \
-        src/pysolorie/
     sphinx-build -W -b html docs/ docs/_build/
diff --git a/src/pysolorie/atmospheric_transmission.py b/src/pysolorie/atmospheric_transmission.py
@@ -18,6 +18,10 @@
 
 
 class AtmosphericTransmission:
+    r"""
+    A class to model the atmospheric transmission.
+    """
+
     def __init__(
         self,
         climate_type: str,
@@ -61,7 +65,7 @@ def calculate_transmittance(self, day_of_year: int, solar_time: float) -> float:
             coefficient of the direct beam
         | - :math:`a_0`, :math:`a_1`, and :math:`k` are the components
             of clear-sky beam radiation transmittance
-        | - :math:`\theta_z` is the zenith angle
+        | - :math:`\theta_z` is the solar zenith angle
 
         :param day_of_year: The day of the year.
         :type day_of_year: int

diff --git a/src/pysolorie/irradiance.py b/src/pysolorie/irradiance.py
@@ -18,6 +18,10 @@
 
 
 class SolarIrradiance:
+    r"""
+    A class to model the solar irradiance.
+    """
+
     def __init__(self, sun_position: SunPosition):
         r"""
         To instantiate the ``SolarIrradiance`` class, provide the following parameter.
@@ -32,35 +36,42 @@ def calculate_extraterrestrial_irradiance(self, day_of_year: int) -> float:
         r"""
         Calculate the extraterrestrial solar irradiance for a given day of the year.
 
-        The extraterrestrial solar irradiance, :math:`E`,
-        is the amount of solar energy received per unit area on
-        a surface perpendicular to the Sun's rays outside Earth's atmosphere.
+        The extraterrestrial solar irradiance, :math:`I`,
+        is the annual average of the Sun's irradiation intensity.
+        This refers to the amount of solar energy received per unit
+        area per unit time on a surface perpendicular to the Sun's rays,
+        outside Earth's atmosphere.
 
         The formula used is:
 
         .. math::
-            E = SC
+            I = SC
             \times (1 + 0.33 \times \cos (\frac{2\pi~n}{365}))
 
 
         | - :math:`SC` is the average solar radiation arriving outside
            of the Earth's atmosphere,
-           which is approximately ``1367`` Watts per square meter.
+           which is approximately ``1367`` Megawatts per square meter [1]_.
            This is also known as the solar constant.
-        | - The factor ``0.033`` accounts
-          for the variation in the Earth-Sun distance
-          due to the Earth's elliptical orbit.
+        | - The factor ``0.033``, which is two times the eccentricity of
+            the Earth's orbit around the Sun, accounts for the variation
+            in the Earth-Sun distance due to the Earth's elliptical orbit.
         | - :math:`n` is the day of the year (i.e., ``day_of_year``)
 
         :param day\_of\_year: The day of the year, ranging from 1 to 365.
         :type day\_of\_year: int
 
-        :return: The extraterrestrial solar irradiance in Watts per square meter.
+        :return: The extraterrestrial solar irradiance in Megawatts per square meter.
         :rtype: float
+
+        References
+        ----------
+        .. [1] Duffie (Deceased), J., Beckman, W., & Blair, N. (2020).
+                Solar Engineering of Thermal Processes, Photovoltaics and Wind. Wiley.
         """
 
-        # Solar constant (W/m^2)
-        SOLAR_CONSTANT = 1367
+        # Solar constant (MW/m^2)
+        SOLAR_CONSTANT = 1367 * 1e-6
 
         # Factor to account for the Earth's orbital eccentricity
         earth_orbital_eccentricity = 0.033