SAM Weather File Format Descriptions

For descriptions of SAM's weather file formats, see the "Weather File Formats" topic in the software's Help system. The following excerpt is a copy of that topic from SAM 2020.2.29 r1:

  • SAM weather file format descriptons from Help (PDF 1 MB)

Publications Related to Weather Data

Dobos, A.; Gilman, P.; Kasberg, M. (2012). "P50/P90 Analysis for Solar Energy Systems Using the System Advisor Model." NREL Conference Paper Preprint No. CP-6A20-54488. (PDF 432 KB)

Habte, A.; Lopez, A.; Sengupta, M.; Wilcox, S. (2014). "Temporal and Spatial Comparison of Gridded TMY, TDY, and TGY Data Sets." NREL Report No. TP-5D00-60866. (PDF 17.4 MB)

National Solar Radiation Database. (1992). " National Solar Radiation Data Base User's Manual (1961-1990)." [TMY2 format description.]

Sengupta, M.; Habte, A.; Gueymard, C.; Wilbert, S.; Renne, D.; Stoffel, T. (2017). "Best Practices Handbook for the Collection and Use of Solar Resource Data for Solar Energy Applications: Second Edition." NREL Report No. TP-5D00-68886. (PDF 8.1 MB)

Sengupta, M.; Habte, A.; Kurtz, S.; Dobos, A.; Wilbert, S.; Lorenz, E.; Stoffel, T.; Renne, D.; Myers, D.; Wilcox, S.; Blanc, P.; Perez, R. (2015). "Best Practices Handbook for the Collection and Use of Solar Resource Data for Solar Energy Applications." NREL Report No. TP-5D00-63112. (PDF 8.9 MB)

Wilcox, S.; Marion, W. (2008). "Users Manual for TMY3 Data Sets (Revised)." 58 pp.; NREL Report No. TP-581-43156. (PDF 1.7 MB)

The files below are intended to serve as examples to help you learn how to use different SAM features. The data in the files is fictitious, and not intended to represent costs or designs of any particular project or system.

SAM files

  • Photovoltaic microinverter example (SAM 346 KB)
  • Parametric Quick Setup examples with explanatory notes (SAM 1.1 MB)

LK Script Cookbook

The following script examples are for specific tasks you might want to include in your LK scripts and macros.

  1. Read electric utility rate data from the OpenEI International Utility Rate Database (IURDB) given an OpenEI GUID, based on SAM 2017.1.17 r3 and Version 4 of the IURDB. Uses curl() and json_read() functions to download and parse a JSON string from the database. (LK 11 KB)
  2. SAM 2017.1.17 has a new scripting capability for the photovoltaic models' 3D Shade Calculator. This sample script demonstrates the use of the special LK functions for creating and managing objects in the scene. (LK 1 KB)
  3. Work with the "Specify desired array size" and "Specify modules and inverters" sizing modes for the Detailed Photovoltaic model. (LK 4.6 KB)
  4. Convert an hourly weather file in SAM CSV format from hourly to 15-minute data by replicating the data in each hour for each of the four 15-minute time steps in the hour. (LK 1.37 KB)
  5. Work with solar resource data files. Use the use_specific_weather_file and user_specified_weather_file variables to either choose a file from SAM's built-in solar resource library, or to choose a file stored on disk. Also demonstrates how to use the choose_file() function to browse files on your computer (LK 3.4 KB).
  6. Convert SolarAnywhere file to SAM CSV format. Automatically detects whether the file is in the SolarAnywhere format, or SolarAnywhere TMY3 format. For files with historical data over a multi-year period, the script converts each year of data into a separate SAM CSV file and appends the year to the file name so that SAM's P50/P90 simulation feature will recognize the files. UPDATED 6/23/2017 TO FIX ISSUE WITH ASSIGNING 12/31 TO THE TIME STAMP LAST HOUR OF THE DAY AND TO CORRECTLY CONVERT ARRAYS TO STRINGS IN SAM 2017.1.17 (LK 15 KB)
  7. Run a set of simulations for multiple weather files using either sequential simulations simulate() or parallel simulations parsim(). Display simulation error messages when simulations fail. Works with a photovoltaic or CSP case. Weather files include a "broken" one with 8759 rows instead of 8760 to demonstrate simulation error reporting. Script (LK 4 KB), Sample weather files (ZIP 806 KB).
  8. Calculate and display a table of monthly totals of hourly data, and define a function (LK 1.2 KB)
  9. Use csvread() and csvwrite() to work with CSV files (LK 3.6 KB)
  10. Run CSP power tower SolarPILOT heliostat field optimization from LK (LK 6 KB)
  11. Use the dview() function to display time series data in the data viewer (ZIP 545 KB)
  12. Use lhs()parsim() and parout() to generate parametric values with Latin hypercube sampling for PV array tilt and azimuth inputs and run parallel simulations. Works with either a detailed photovoltaic or PVWatts case. (LK 1.72 KB)
  13. Use plot() and related functions to create graphs and save graph image to file. Examples include line graph with two y axes, tornado-style graph, stacked bar chart, and changing thickness of line and scatter plots. (LK 2.71 KB)
  14. Use plot() and related functions to create histograms. To use this sample script, download both the and histdata.csv files, and place them in the same folder on your computer. (LK 2 KB, CSV 3 KB)
  15. Run the 6parsolve compute module from an LK script in SAM to caclulate input parameters for the CEC module model from manufacturer data sheet parameters. (LK 1 KB)

3-D Shading Scenes

The following files are files that you can import to SAM's photovoltaic shade calculator to learn how to use objects to create a three-dimensional representation of a photovoltaic array, buildings, and nearby shading objects.

Exchanging Data between SAM Inputs and Excel

The following files demonstrate two ways you can set the value of SAM inputs to values in an Excel file, or set the value of cells in Excel to values of SAM inputs.

Example using SAM's Excel Exchange feature. Download the Excel file and SAM file and put them in the same folder on your computer. Then open the SAM file, and run a simulation. See the note on the System Costs page in the SAM file and the Excel Exchange topic in SAM's help system for details:

  • SAM file for Excel Exchange example (SAM 105 KB)
  • Excel file for Excel Exchange example (XLSX 55 KB)

Example using SAM's LK scripting language. Download the LK script along with the SAM file and Excel file above, and put all three files in the same folder on your computer. Then open the SAM file, and open the LK script from SAM's start menu:

  • LK script demonstrating how to exchange data with an Excel file (LK 2 KB)

A SAM weather file is a text file that contains one year's worth of data in hourly or subhourly time steps describing the solar resource or wind resource at a particular location. A weather file may contain typical-year data that represents long-term historical data or single-year data for a particular year. The solar resource and meteorological data in a SAM weather file may have been developed from ground measurements, data from a satellite, or a combination of the two.

For more information about weather data for SAM, see the "Weather Data" chapter in SAM's Help system. The Help system is available in SAM from the software's Help menu, and as a PDF file on the Download page.

For a description of SAM's weather file formats, see the "Weather File Formats" chapter in SAM's Help system, or download the PDF excerpt from the Weather Data Publications page.

Where to find Solar Resource Data to Use with SAM

United States, North and South America, and Southern Asia

For the United States, North and South America, and Southern Asia, the NREL National Solar Radiation Database (NSRDB) is the best source of data for locations in the United States, Canada, Central and South America, Sri Lanka, India, Nepal, Bhutan, Bangladesh, and parts of Pakistan, Afghanistan, and Myanmar, and western Southeast Asia.

You can use the Download buttons on SAM's Location and Resource input page to download NSRDB data directly from SAM.

The NSRDB provides access to the latest weather files as both single-year and typical-year files from the latest PSM dataset, and from the legacy TMY2 (MTS1) and TMY3 (MTS2) datasets.

Note about snow depth data. If you are looking for snow depth data to use with SAM's detailed photovoltaic model, please see this post on the SAM forum.

Europe, Africa, Central Asia, Southeast Asia

For Europe, Africa, Central Asia, Southeast Asia, the European Commission's Photovoltaic Geographical Information System (PVGIS) is a good source.

When you download PVGIS data, for now, the best format to use with SAM is the typical-year (TMY) in the EPW format: After setting the location, click the TMY tab and click the EPW button. To use this data in SAM, after downloading the EPW files to a folder on your computer, on the Location and Resource page, click the Add/remove weather file folders button to add the folder to the list SAM uses to build the solar resource library. The files will then appear in the library where you can select them.

Other Sources of Solar Resource Data

If you know of other data sources to add to this list, please contact us.

The following sources in addition to the NSRDB and PVGIS sources described above provide free weather data:

AUSTELA Australia Single-year hourly data (select years between 1996 and 2011). Twelve locations. SAM-ready TMY3 format. Free.
EnergyPlus Global Typical-year hourly data from various sources. Over 2,100 locations. SAM-ready EPW format. Free.
Climate.OneBuilding Global Typical-year hourly data from various sources. Over 9,000 locations. SAM-ready EPW format. Free.
SIREN Toolkit Global Single-year (1979 - present) from NASA MERRA-2. Use makeweather2 program in toolkit or download separate sen_makeweather_getmerra2 package. Free.
Old NREL NSRDB United States Original typical-year hourly data files with additional data and documentation for legacy NREL NSRDB 1961 - 1990 (TMY2), 1991 - 2010 update (TMY3), and 1998 - 2014 update (TMY3). Free.

The following sources are are for commercial data products that will work with SAM:

Clean Power Research North America Single-year data (1998 - ). Satellite-derived data. 10 km grid cells. SAM-ready TMY3 format. $$ (some free data).
SolarGIS Global Single-year and typical-year data (1994 - ). Satellite-derived data. 250 m grid cells. $$.
Meteonorm Global Single-year and typical-year data. Model-generated data from various sources. Various formats. $$.
White Box Technologies Global Single-year and typical-year data. Over 4,000 locations. Data from ASHRAE IWEC2, NSRDB, CWEC2, and CZ2010. $$.
Deutscher Wetterdienst WebWerdis Germany and other countries Single-year data. Free and $$.
Vaisala Global Single-year data and typical-year data. 3 km grid cells.$$.

Upcoming Webinars

SAM webinars are one-hour lectures with question and answer sessions that cover various topics about SAM. All webinars are free and start at 2 pm Mountain. To register for a webinar, click its name in the following list.

Round Tables

SAM round tables are 30-minute informal discussions online with the SAM team.

Recordings of Past Webinars

Video recordings and presentation materials are available for the following webinars.

Photovoltaic Systems

Photovoltaic-Battery Systems

Concentrating Solar Power

Financial Models


General Overviews

Wind, Geothermal, and Biopower Systems

Advanced Modeling Techniques

SAM YouTube Channel 

Visit the SAM YouTube channel for webinar recordings and instructional videos.

SAM YouTube cover picture

SAM Virtual Conferences

The SAM virtual conferences are one-day events that feature presentations and discussion by professionals who have used SAM in their work.