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.

python3 -m pip install pysolorie

Calculating Direct Irradiation for a Year

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.

from pysolorie import IrradiationCalculator

# Instantiate an IrradiationCalculator object for the city of Tehran
irradiation_calculator = IrradiationCalculator(
    climate_type="MIDLATITUDE SUMMER",
    observer_altitude=1200,
    observer_latitude=35.6892
)

from_day = 1
to_day = 365
total_irradiation = 0

# 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 = irradiation_calculator.find_optimal_orientation(day)
    # Calculate the direct irradiation for the given day and add it to the total
    total_irradiation += irradiation_calculator.calculate_direct_irradiation(
        optimal_tilt_angle, day
    )

# Print the total direct irradiation received by the solar panel over the year
print(total_irradiation)

Finding the Optimal Orientation

The find_optimal_orientation method finds the optimal tilt angle 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"

from pysolorie import IrradiationCalculator

# Instantiate an IrradiationCalculator object for the city of Tehran
irradiation_calculator = IrradiationCalculator(
    climate_type="MIDLATITUDE SUMMER",
    observer_altitude=1200,
    observer_latitude=35.6892
)

# Find the optimal orientation for June 21st
result = irradiation_calculator.find_optimal_orientation(172)

print(f"Optimal orientation: {result}")

Calculating Direct Irradiation

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:

  • "MIDLATITUDE SUMMER"

  • "MIDLATITUDE WINTER"

  • "TROPICAL"

  • "SUBARCTIC SUMMER"

from pysolorie import IrradiationCalculator

# Instantiate an IrradiationCalculator object for the city of Tehran
irradiation_calculator = IrradiationCalculator(
    climate_type="MIDLATITUDE SUMMER",
    observer_altitude=1200,
    observer_latitude=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}")

Plotting the Optimal Orientation

With the pysolorie package, you can plot the optimal orientation of a solar panel given the climate type, altitude, and latitude of the location. For instance, the following code plots the optimal orientation for each day of the year for the city of Tehran.

from pathlib import Path
from pysolorie import IrradiationCalculator, Plotter

# Instantiate a Plotter object from the pysolorie library
plotter = Plotter()

# Instantiate an IrradiationCalculator object for the city of Tehran
irradiation_calculator = IrradiationCalculator(
    climate_type="MIDLATITUDE SUMMER",
    observer_altitude=1200,
    observer_latitude=35.6892
)

# Use the plotter to plot the optimal tilt angle of a solar panel for each day of the year
plotter.plot_optimal_orientation(
    irradiation_calculator,
    from_day=1,
    to_day=365,
    path=Path("results.svg"),
    plot_kwargs={
        "xlabel": "Day",
        "ylabel": "Beta (degrees)",
        "title": "Optimal Solar Panel Orientation",
    },
    savefig_kwargs={"dpi": 300},
)

This figure, generated by the example code, illustrates the optimal tilt angle of a solar panel for each day of the year in Tehran. The x-axis represents the day of the year, while the y-axis represents the optimal angle (Beta) in degrees. As can be seen, the optimal angle varies throughout the year, highlighting the importance of adjusting the tilt angle of the solar panel to maximize the energy received.

_images/example_usage.svg

The plot_optimal_orientation method plots the optimal orientation for a range of days.

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.

Plotting the Direct Irradiation

The plot_total_direct_irradiation method plots the direct irradiation for a range of days.

from pysolorie import Plotter, IrradiationCalculator
from pathlib import Path

# Create a plotter
plotter = Plotter()
# Instantiate an IrradiationCalculator object for the city of Tehran
irradiation_calculator = IrradiationCalculator(
    climate_type="MIDLATITUDE SUMMER",
    observer_altitude=1200,
    observer_latitude=35.6892
)

# 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": "Direct Irradiation (Megajoules per square meter)",
       "title": "Direct Irradiation",
   },
   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.

Generating Reports

The pysolorie package provides methods to generate reports of the optimal orientation for a range of days in different formats: CSV, JSON, and XML.

from pysolorie import ReportGenerator, IrradiationCalculator
from pathlib import Path

# Create a report generator and an irradiation calculator
report_generator = ReportGenerator()
irradiation_calculator = IrradiationCalculator(
    climate_type="MIDLATITUDE SUMMER",
    observer_altitude=1200,
    observer_latitude=35.6892,
)

# Generate a CSV report for days 60 to 70
report_generator.generate_optimal_orientation_csv_report(
    path=Path('results.csv'),
    irradiation_calculator=irradiation_calculator,
    from_day=60,
    to_day=70,
)

# Generate a JSON report for days 60 to 70
report_generator.generate_optimal_orientation_json_report(
    path=Path('results.json'),
    irradiation_calculator=irradiation_calculator,
    from_day=60,
    to_day=70,
)

# Generate an XML report for days 60 to 70
report_generator.generate_optimal_orientation_xml_report(
    path=Path('results.xml'),
    irradiation_calculator=irradiation_calculator,
    from_day=60,
    to_day=70,
)

The report files will be saved to the specified paths.

Calculating Sunrise and Sunset

The calculate_sunrise_sunset method calculates the sunrise and sunset hour angles for a given day of the year.

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(
    day_of_year=172
)

print(f"Sunrise hour angle: {sunrise_hour_angle}")
print(f"Sunset hour angle: {sunset_hour_angle}")

Calculating the Solar Zenith Angle

The calculate_zenith_angle method calculates the zenith angle given the day of the year and solar time.

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:

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.

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.

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’s Model

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 \(a_0\), \(a_1\), and \(k\) based on climate type and observer altitude.

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.