Changelog ========= Version 1.5.8 ------------- Release date: 2024-09-24 Fixed ^^^^^ - Changed the parameter :math:`\Omega` from ``7.15 * 1e-5`` to ``7.2722 * 1e-5`` Version 1.5.6 ------------- Release date: 2023-12-29 Fixed ^^^^^ - Introduced a new exception class ``InvalidObserverLatitudeError`` in ``exceptions.py`` for better error handling of invalid observer latitude values. - Updated ``IrradiationCalculator`` in ``numerical_integration.py`` to handle cases where the ``irradiance_components`` dictionary is empty, providing a meaningful return value based on observer latitude. - Fixed ``Observer`` class validation in ``observer.py`` to include a check for the observer's latitude being within the valid range. Testing ^^^^^^^ - Added test case ``test_calculate_sunrise_sunset_invalid_latitude`` to ensure exceptions are properly raised for invalid latitude inputs. - Added missing tests for invalid observer latitude in ``test_observer.py``. Version 1.5.5 ------------- Release date: 2023-12-28 Fixed ^^^^^ - Removed the logs of ``observer.py`` Version 1.5.4 ------------- Release date: 2023-12-28 Fixed ^^^^^ - Removed the logs of unnecessary function calls. 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 ------------- Release date: 2023-12-23 Changed ^^^^^^^ - Refactoring in various modules (``plotter.py``, ``report.py``, ``tests/test_pysolorie.py``, etc.) to improve code clarity and reduce the complexity. - Renamed "optimal orientation" to "optimal tilt angle" in the README, documentation, and examples to more accurately reflect solar panel positioning. - Updated and clarified solar irradiance discussion in the paper draft, along with audience benefits, terminology, and code usage in the README and documentation. - Improved various code samples across the documentation for enhanced clarity and consistency. Fixed ^^^^^ - Fixed the incorrect setting of logger instances within several classes and refactored the decorating function to correctly set the logger attribute. - Resolved mypy type checking errors by adding type ignore comments where necessary. Testing ^^^^^^^ - Extensive refactoring of test cases, with tests being moved to newly named files according to their respective functionalities. - Addition of test cases for new refactorings and exception handling enhancements to ensure code reliability and correctness. Documentation ^^^^^^^^^^^^^ - Amended the Sphinx configuration with the ``sphinx-copybutton`` extension and updated the packages list to include the extension. - Corrected and improved the structure of documentation files to enhance user understanding and readability. Miscellaneous ^^^^^^^^^^^^^ - Simplified GitHub issue templates to make them more accessible and concise for users. - Refinement of content descriptions, departmental affiliations for authors, and enhancement of figure captions in the paper draft. Version 1.5.1 ------------- Release date: 2023-12-20 Added ^^^^^ - Implemented class ``InvalidClimateTypeError`` in ``exceptions.py``, providing custom exception handling for when an invalid climate type is provided. - Implemented class ``MissingObserverLatitudeError`` in ``exceptions.py``, to manage the error when the observer's latitude is not provided. Changed ^^^^^^^ - Reorganized the ``__all__`` list in ``__init__.py`` within the ``pysolorie`` package for improved module import organization. - Refactored the ``HottelModel`` class in ``model.py`` to provide a climate type check and raise the newly implemented ``InvalidClimateTypeError`` if the climate type is not recognized. - Enhanced error handling across various modules by using the new custom exception classes defined in ``exceptions.py``. Fixed ^^^^^ - Addressed an issue where the wrong logger was referenced in the `plotter.py`, which now correctly references the logger set for ``_calculate_optimal_orientations``. - Updated logging setup in ``logger.py`` by shifting ``basicConfig`` setup outside the ``logger_decorator`` function for improved logging practices. - Updated the ``plotter.py`` to correct the logger name used in the ``plot_optimal_orientation`` method for consistency and correctness. Documentation ^^^^^^^^^^^^^ - Included changes in documentation to reflect the addition of new issue templates for bug reporting and feature requests. - Updated documentation to cover the new exception classes and their usage within the application. Testing ^^^^^^^ - Expanded ``test_pysolorie.py`` to include tests for newly introduced exceptions ``InvalidClimateTypeError`` and ``MissingObserverLatitudeError`` ensuring robust error handling. - Augmented logging tests in ``test_pysolorie.py``, verifying that appropriate messages are recorded at info level, indicating successful operation of the updated functionality. Version 1.5.0 ------------- Release date: 2023-12-20 Added ^^^^^ - Added badges for CodeQL, pre-commit, and code style (black) in README.md, enhancing the visibility of code quality and style adherence. - Implemented ``generate_optimal_orientation_json_report`` method for JSON report generation in ``ReportGenerator``. - Developed ``generate_optimal_orientation_xml_report`` method in ``ReportGenerator`` for producing XML formatted reports. - Expanded ``test_pysolorie.py`` with tests for JSON (``test_generate_optimal_orientation_json_report``) and XML (``test_generate_optimal_orientation_xml_report``) report generation. Changed ^^^^^^^ - Updated ``plot_total_direct_irradiation`` method's ``ylabel`` argument to use "Megajoules per square meter" instead of "MW/m²" for clarity and accuracy in ``plotter.py``. - Refactored ``plot_total_direct_irradiation`` in ``Plotter`` to use a private method for calculating optimal orientations, streamlining the plotting process. Fixed ^^^^^ - Altered the ``Plotter`` methods to handle axis labels and titles through dynamic ``plot_kwargs``, making the labeling more robust and customizable. - Harmonized and corrected unit values and labelings across the entire codebase and documentation for consistency and accuracy. - Refined the ``ReportGenerator`` generate methods' docstrings, clearly specifying the return value unit as "Megajoules per square meter". - Changed the calculation of the solar irradiance formula in ``SolarIrradiance`` from ``0.33`` to ``0.033`` to correct the eccentricity correction factor according to established astronomical equations. Documentation ^^^^^^^^^^^^^ - Enhanced documentation in ``getting_started.rst`` with examples and instructions for the new JSON and XML report generation methods. - Altered the representation of solar irradiance units in documentation to match the codebase changes. Testing ^^^^^^^ - Enriched ``test_pysolorie.py`` with further assertions for newly added JSON and XML report functionalities, ensuring correct report file creation and data integrity. 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 ------------- Release date: 2023-12-16 Added ^^^^^ - An image has been added to the README file, with the solar panel's picture and width specified as 600. (``docs/_static/images/solar_panel.svg``) Changed ^^^^^^^ - Correction of typographical error in the README.md, changing “Solar Orie” to “Sol Orie” in the abbreviation of “pysolorie”. - Updated the utilization description from “the Hottel Model” to “Hottel's Model” in the README.md. Documentation ^^^^^^^^^^^^^ - A detailed explanation of the factors affecting solar irradiation energy received by a solar panel. It includes time of irradiation, latitude and climate of the location, and the solar panel's shape and orientation. - Mention of how solar collectors can be positioned and adjusted for fixed periods or optimal annual performance. - Description of the components of solar irradiation: direct beam, sky diffusion, and ground reflection. - Clarification that the library is now considering flat solar panels and focusing on direct beam irradiation. - Usage of Hottel's model to estimate the transmittance of direct solar radiation through clear atmospheres. - A new “References” section with three references to support the text added to the Introduction. - In the introduction, the leading question has been rephrased for clarity. - Updated the feature listing of “Calculating the zenith angle” to “Calculating the solar zenith angle”. Testing ^^^^^^^ - New test case: ``test_generate_optimal_orientation_csv_report`` has been added to verify the functionality of generating CSV reports for the optimal orientation of solar panels over a specified range of days. This test ensures that the CSV file is created correctly and contains the expected data. - New test case: ``test_plot_optimal_orientation`` is introduced to test the generation of plots for the optimal orientation. It checks if the plot file is created and has content, ensuring that the visual representation of the data is correctly generated. - New test case: ``test_plot_method`` to verify internal plotting functionality. This test covers the private method ``_plot``, which underlies the plotting functionality. It checks whether the matplotlib library's ``show`` method is called when plotting data without a specified path (used for displaying plots directly). - The existing test cases have been supplemented with type annotations, providing clearer code documentation and potentially preventing type-related errors. Types such as ``Path``, ``ReportGenerator``, ``IrradiationCalculator``, ``List``, ``Dict``, ``Any``, and several others are now explicitly declared, making the codebase more robust and static type checker friendly. Version 1.3.0 ------------- Release date: 2023-12-15 Added ^^^^^ - Codecov integration in the GitHub Actions pipeline for Python 3.10. - Documentation badges including Documentation Status, PyPI Version, PyPI Format, PyPI Status, and Codecov coverage report. - A new logger module with a logger_decorator for logging the start and finish of functions. - ReportGenerator and Plotter classes for generating CSV reports and plotting optimal orientations of solar panels. - Detailed feature listing in the README.md: Providing the added functionalities of generating CSV reports and plotting optimal orientations for a range of days. - Automated module documentation generation for pysolorie.logger, pysolorie.plotter, and pysolorie.report. - matplotlib now a dependency, reflecting new plotting capabilities. Changed ^^^^^^^ - Updated README.md to reflect new library capabilities and contribution guidance. - Updated contributing section in the documentation, providing clarity on how to contribute and the kinds of contributions welcomed. - Upgraded Development Status classifier indicating the project is now considered production/stable. Documentation ^^^^^^^^^^^^^ - Expansive enrichment of the README.md and documentation (``docs/*``), highlighting new features in detail and offering guidance on library usage. - Detailed description of plotting and generating CSV report functionalities in the getting_started.rst. - Inclusion of plotting and CSV report generation examples in the documentation. - Contribution documentation updated to reflect recent changes and guidelines for adding new features and writing test cases. Testing ^^^^^^^ - Added unit tests for the ReportGenerator and Plotter functionalities. - pytest is now configured to produce both terminal and XML coverage reports.