diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 0000000..a5693d9 --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,2 @@ +Changelog +========= diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..436f06e --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,94 @@ +Contributing +============ + +We welcome contributions to the pysolorie project! +This document will guide you through the process of setting up your development environment, +running tests, and submitting your contributions. + +Setting Up Your Development Environment +--------------------------------------- + +1. **Fork the repository**: + +Start by forking the pysolorie repository on GitHub. + +2. **Clone the repository**: + +Clone your fork of the repository to your local machine using the command ``git clone https://github.com//pysolorie``. + +3. **Install Python**: + +pysolorie requires Python 3.9 or higher. You can download Python from the official website. + +4. **Setup environment**: + +It is highly recommended to use ``virtualenv`` for the development. ``virtualenv`` is a tool to create isolated Python environments. + + .. code-block:: bash + + $ python3 -m venv .venv + $ source .venv/bin/activate + $ pip install -r dev-requirements.txt + +5. **Install pre-commit**: + +We use ``pre-commit`` hooks for some validation before letting you push to the +remote repository. ``pre-commit`` is a tool that manages and maintains multi-language pre-commit hooks. + + .. code-block:: bash + + $ pre-commit install + + +Running Tests +------------- + +We use ``tox`` to run our tests. ``tox`` is a generic virtualenv management and test command-line tool. +The ``setup.cfg`` file in the root of the repository defines several test environments: + +- ``format``: Checks the formatting of the code with black. +- ``lint``: Runs the flake8 linter on the code. +- ``typecheck``: Checks the types in the code with mypy. +- ``py311``, ``py310``, ``py39``: Runs the test suite with pytest on Python 3.11, 3.10, and 3.9 respectively. + +You can run these tests locally with the ``tox -e`` command. +For example, to run the linter, you would use the following command: + + .. code-block:: bash + + $ 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 + +To verify the correctness of the formatting, execute the command below: + + .. code-block:: bash + + $ tox -e format + +To check the types in the code with mypy, use this: + + .. code-block:: bash + + $ 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 + +Submitting Your Contributions +----------------------------- + +Contributions to the pysolorie project can start with writing test cases. This is a great way to understand the project and ensure its robustness. Once you've made your changes and all tests are passing, you can submit your contributions by creating a pull request on GitHub. + +**We are also looking to add plotting support to the project.** If you're interested, you could start by looking into libraries like matplotlib or other similar tools. However, it's important to note that we aim to keep our dependencies minimal. Any new dependency should be clearly justified and absolutely necessary. + +When submitting your contributions, please make sure to include a clear and detailed description of your changes. Before submitting new ones, please check the existing issues and pull requests to avoid duplication. + +Thank you for contributing to pysolorie! diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 0000000..00d5f54 --- /dev/null +++ b/docs/getting_started.rst @@ -0,0 +1,171 @@ +Getting Started +=============== +This guide will help you get started with using the pysolorie library. + +How to Install pysolorie +------------------------ + +``pysolorie`` requires Python 3.9 or higher. + +The easiest way to install ``pysolorie`` is from PyPI. + +.. code-block:: bash + + $ python3 -m pip install pysolorie + + + +Finding the Optimal Orientation +------------------------------- +The ``find_optimal_orientation`` method finds the optimal orientation for a solar +panel given the climate type, observer altitude, observer latitude, 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 + ) + + # Find the optimal orientation for June 21st + result = irradiation_calculator.find_optimal_orientation(172) + + print(f"Optimal orientation: {result}") + +Calculating Sunrise and Sunset +------------------------------ + +The ``calculate_sunrise_sunset`` method calculates the sunrise and sunset hour angles +for a given day of the year. + +.. code-block:: python + + from pysolorie import Observer + + # Create an observer located in Tehran + observer = Observer(observer_latitude=35.69) + + # Calculate the sunrise and sunset hour angles for June 21st + sunrise_hour_angle, sunset_hour_angle = observer.calculate_sunrise_sunset(172) + + print(f"Sunrise hour angle: {sunrise_hour_angle}") + print(f"Sunset hour angle: {sunset_hour_angle}") + + +Calculating the Zenith Angle +---------------------------- + +The ``calculate_zenith_angle`` method calculates the zenith angle given the day of the year +and solar time. + + +.. code-block:: python + + from pysolorie import Observer + + # Create an observer located in Tehran (latitude 35.69, longitude 51.39) + observer = Observer(35.69, 51.39) + + # Calculate the zenith angle for March 22nd (81st day of the year) at solar noon (12 * 60 * 60 seconds) + zenith_angle = observer.calculate_zenith_angle(81, 12 * 60 * 60) + + print(f"Zenith angle: {zenith_angle}") + +Note that the observer's latitude must be provided when creating an ``Observer`` instance. +If it's not provided, a ``ValueError`` will be raised: + +.. code-block:: python + + from pysolorie import Observer + + # Attempt to create an observer without specifying the latitude + try: + observer = Observer(None, 0) + observer.calculate_zenith_angle(1, 12 * 60 * 60) + except ValueError as e: + print(f"Caught an exception: {e}") + +Calculating Solar Time +---------------------- + +The ``solar_time`` method calculates the solar time given the hour angle. + + +.. code-block:: python + + from pysolorie import SunPosition + + # Create a SunPosition instance + sun_position = SunPosition() + + # Calculate the solar time for solar noon (hour angle 0) + solar_time = sun_position.solar_time(0) + + print(f"Solar time: {solar_time}") + +This will print the solar time in seconds. For example, +solar noon (when the sun is at its highest point in the sky) +corresponds to ``12 * 60 * 60 = 43200`` seconds. + +Calculating Solar Declination and Hour Angle +-------------------------------------------- + +The ``solar_declination`` method calculates the solar declination given the day of the year, +and the ``hour_angle`` method calculates the hour angle given the solar time. + +.. code-block:: python + + from pysolorie import SunPosition + + # Create a SunPosition instance + sun_position = SunPosition() + + # Calculate the solar declination for January 1st + declination = sun_position.solar_declination(1) + + # Calculate the hour angle for 1pm (13 * 60 * 60 seconds) + hour_angle = sun_position.hour_angle(13 * 60 * 60) + + print(f"Solar declination: {declination}") + print(f"Hour angle: {hour_angle}") + +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 +---------------------------------------------------------- + +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. + +.. code-block:: python + + from pysolorie import HottelModel + + # Create a HottelModel instance + hottel_model = HottelModel() + + # Calculate the transmittance components for Tehran in the summer at an altitude of 1200m + result = hottel_model.calculate_transmittance_components("MIDLATITUDE SUMMER", 1200) + + print(f"Transmittance components: {result}") + +This will print the transmittance components as a tuple of three values. For example, for Tehran in the summer at an altitude of 1200m, the transmittance components are approximately ``(0.228, 0.666, 0.309)``. + +The ``climate_type`` parameter can be one of the following: + +- ``"TROPICAL"`` +- ``"MIDLATITUDE SUMMER"`` +- ``"SUBARCTIC SUMMER"`` +- ``"MIDLATITUDE WINTER"`` + +If an invalid climate type is provided, a ``ValueError`` will be raised. diff --git a/docs/index.rst b/docs/index.rst index ac52444..4813f0f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,14 +3,37 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to pysolorie's documentation! +pysolorie: Orientation Analysis of Solar Panel +============================================== + + +Introduction +============ +How can one find the optimal orientation of a solar panel to maximize the total energy received from the sun? + +``pysolorie`` is a library designed to help you find this optimal orientation. Its features include, but are not limited to: + +- Finding the optimal orientation for a fixed solar panel under the assumption of a clear-sky model. +- Calculating the sunrise and sunset hour angles for a given day. +- Utilizing the Hottel Model to estimate clear-sky beam radiation transmittance. +- Calculating the zenith angle. +- Calculating the solar time. +- Calculating Solar Declination and Hour Angle. + + + +Contents ===================================== .. toctree:: :maxdepth: 2 - :caption: Contents: + getting_started reference/modules + contributing + license + changelog + GitHub diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000..8f3cf1f --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,4 @@ +License +======= + +.. literalinclude:: ../LICENSE