Pysolar is similar to PyEphem, with a few key differences. Both libraries compute the location of the sun based on Bretagnon’s VSOP 87 theory. Pysolar is aimed at modeling photovoltaic systems, while PyEphem is targeted at astronomers. Pysolar is written in pure Python, while PyEphem is a Python wrapper for the libastro library, written in C, which is part of XEphem.

Pysolar is similar to the sun position module in Sunpy, which is a project focused on solar physics modeling. See, for example, their beautiful gallery of sun image renderings. The Sunpy position module is based on the same algorithm originally described by Jean Meeus, but it appears to omit the later work by Reda and Andreas at NREL that Pysolar uses, or at least the code is shorter. In any case, Sunpy is aimed at solar physics; Pysolar is aimed at modeling solar radiation on the earth.

Pysolar requires Python, which comes preinstalled on most Unix machines, including Apple’s OS X. You can check to see if you have it installed on a Unix machine by typing python3 at a command prompt. If the result is something like:

You can figure out your latitude and longitude from the URL from the “Link to this page” link on Google maps. Find your location on the map, click on the “Link to this page” link, and then look at the URL in the address bar of your browser. In between ampersands, you should see something like ll=89.123456,-78.912345. The first number is your latitude; the second is your longitude.

The reference frame for Pysolar is shown in the figure below. Altitude is reckoned with zero at the horizon. The altitude is positive when the sun is above the horizon. Azimuth is reckoned with zero corresponding to south. Positive azimuth estimates correspond to estimates east of south; negative estimates are west of south. In the northern hemisphere, if we speak in terms of (altitude, azimuth), the sun comes up around (0, 90), reaches (70, 0) around noon, and sets around (0, -90).

Then, use the solar.get_altitude() function to calculate the angle between the sun and a plane tangent to the earth where you are. The result is returned in degrees.:

Once you calculate azimuth and altitude of the sun, you can predict the direct irradiation from the sun using Pysolar. get_radiation_direct() returns a value in watts per square meter. As of version 0.7, the function is not smart enough to return zeros at night. It does account for the scattering of light by the atmosphere, though it uses an atmospheric model based on data taken in the United States.:

If you find yourself getting errors like AttributeError: ‘datetime.datetime’ object has no attribute ‘timestamp’, this probably means that you are using Python 2 instead of Python 3.

Pysolar no longer supports Python 2. So far, nobody has volunteered to do the work to backport the code to Python 2. If you’re stuck on Python 2 because of some other dependency, you should use Pysolar 0.6, which is the last version that works with Python 2.

Pysolar has been validated against similar ephemeris code maintained by the United States Naval Observatory (USNO). In a random sampling of 6000 locations distributed across the northern hemisphere at random times in 2008, Pysolar matched the observatory’s predictions very accurately. The azimuth estimations correlated much more closely than the altitude estimations, but both agreed with the naval observatory’s to within less than 0.1 degrees on average.

Using the script included in Pysolar called query_usno.py, around 6200 datapoints were gathered from the website of the US Naval Observatory. The datapoints were randomly distributed in time and space, with the following restrictions:

Times were limited to 2008 and, to match the USNO’s resolution, rounded to the nearest second.

Locations were limited to integral degrees of latitude and longitude in the northern hemisphere to match USNO’s resolution. (In theory, the USNO script should accept locations in the southern hemisphere; in practice, negative latitudes caused the script to fail.)

Make sure you have installed only the version of Pysolar that you want to validate.

Change to the test directory: cd pysolar/test/

Run python3-iquery_usno.pyusno_data_6259.txt. This runs Pysolar’s get_altitude() and get_azimuth() functions repeatedly, compares the results to a file included in Pysolar of data pulled from the USNO website, and writes the results to the file test/pysolar_v_usno.csv.

Start IPython Notebook and open validation.ipynb.

Run the code in test/validation.ipynb, which will calculate the error statistics and generate the graphs shown above.

Pysolar was initially hosted on Sourceforge with Subversion, but we switched to git and Github in 2008. Earlier releases are still on the Sourceforge site for now, but you’re probably wrong if you think you want to download them.

Pysolar has been used at several universities, including the University of Oldenburg in Germany, the University of Trento in Italy, and the University of Texas at Austin. It is also deployed in at least one commercial solar tracking system.