Buildings.BoundaryConditions.WeatherData.ReaderTMY3 (2024)

Information

This component reads TMY3 weather data (Wilcox and Marion, 2008) or user specified weather data.The Modelica built-in variable time determines what rowof the weather file is read.The value of time is the number of secondsthat have passed since January 1st at midnight (00:00) in the local time zone.The local time zone value, longitude and latitute are also read from the weather data,such that the solar position computations are consistent with the weather data.

The weather data format is the Typical Meteorological Year (TMY3)as obtained from the EnergyPlus web site athttp://energyplus.net/weather. Thesedata, which are in the EnergyPlus format, need to be converted as describedbelow.

Output to weaBus

The following variables serve as output and are accessible via weaBus:

Adding new weather data

To add new weather data, proceed as follows:

1. Download the weather data file with the epw extension fromhttp://energyplus.net/weather.
2. Add the file to Buildings/Resources/weatherdata (or to any directoryfor which you have write permission).
3. On a console window, type

    cd Buildings/Resources/weatherdata java -jar ../bin/ConvertWeatherData.jar inputFile.epw

   if inputFile contains space in the name:

    java -jar ../bin/ConvertWeatherData.jar "inputFile .epw"

   This will generate the weather data file inputFile.mos, which can be readby the modelBuildings.BoundaryConditions.WeatherData.ReaderTMY3.

Location data that are read automatically from the weather data file

The following location data are automatically read from the weather file:

• The latitude of the weather station, lat,
• the longitude of the weather station, lon, and
• the time zone relative to Greenwich Mean Time, timZone.

Wet bulb temperature

By default, the data bus contains the wet bulb temperature.This introduces a nonlinear equation.However, we have not observed an increase in computing time becauseof this equation.To disable the computation of the wet bulb temperature, setcomputeWetBulbTemperature=false.

Using constant or user-defined input signals for weather data

This model has the option of using a constant value, using the data from the weather file,or using data from an input connector for the following variables:

• The atmospheric pressure,
• the ceiling height,
• the total sky cover,
• the opaque sky cover,
• the dry bulb temperature,
• the dew point temperature,
• the sky black body temperature,
• the relative humidity,
• the wind direction,
• the wind speed,
• the global horizontal radiation, direct normal and diffuse horizontal radiation,and
• the infrared horizontal radiation.

By default, all data are obtained from the weather data file,except for the atmospheric pressure, which is set to theparameter pAtm=101325 Pascals.

The parameter *Sou configures the source of the data.For the atmospheric pressure, temperatures, relative humidity, wind speed and wind direction,the enumerationBuildings.BoundaryConditions.Types.DataSourceis used as follows:

Because global, diffuse and direct radiation are related to each other, the parameterHSou is treated differently.It is set to a value of the enumerationBuildings.BoundaryConditions.Types.RadiationDataSource,and allows the following configurations:

Length of weather data and simulation period

If weather data span a year, which is the default for TMY3 data, or multiple years,then this model can be used for simulations that span multiple years. The simulationstart time needs to be set to the clock time of the respective start time. For example,to start at January 2 at 10am, set start time to t=(24+10)*3600 seconds.For this computation, the used date and time (here January 2, 10 am) must be expressed in the same time zoneas the one that is used to define the TMY3 file. This is usually the local (winter) time zone.The parameter `timZon` represents the TMY3 file time zone, expressed in seconds compared to UTC.

Moreover, weather data need not span a whole year, or it can span across New Year.In this case, the simulation cannot exceed the time of the weather data file. Otherwise,the simulation stops with an error.

As weather data have one entry at the start of the time interval, the end time of the weatherdata file is computed as the last time entry plus the average time increment of the file.For example, an hourly weather data file has 8760 entries, starting on January 1 at 0:00.The last entry in the file will be for December 31 at 23:00. As the time increment is 1 hour,the model assumes the weather file to end at December 31 at 23:00 plus 1 hour, e.g., at January 1 at 0:00.

Notes

1. In HVAC systems, when the fan is off, changes in atmospheric pressure can cause small air flow ratesin the duct system due to change in pressure and hence in the mass of air that is storedin air volumes (such as in fluid junctions or in the room model).This may increase computing time. Therefore, the default value for the atmospheric pressure is set to a constant.Furthermore, if the initial pressure of air volumes are differentfrom the atmospheric pressure, then fast pressure transients can happen in the first few seconds of the simulation.This can cause numerical problems for the solver. To avoid this problem, set the atmospheric pressure to thesame value as the medium default pressure, which is typically set to the parameter Medium.p_default.For medium models for moist air and dry air, the default isMedium.p_default=101325 Pascals.

2. Different units apply depending on whether data are obtained from a file, orfrom a parameter or an input connector:

   • When using TMY3 data from a file (e.g. USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.mos), the units must be the same as the original TMY3 file used by EnergyPlus (e.g.USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw).The TMY3 data used by EnergyPlus are in both SI units and non-SI units.If Resources/bin/ConvertWeatherData.jar is used to convert the .epw file to an .mos file, the units of the TMY3 data are preserved and the file can be directlyused by this data reader.The data reader will automatically convert units to the SI units used by Modelica.For example, the dry bulb temperature TDryBul in TMY3 is in degree Celsius.The data reader will automatically convert the data to Kelvin.The wind direction winDir in TMY3 is degrees and will be automatically converted to radians.
   • When using data from a parameter or from an input connector,the data must be in the SI units used by Modelica.For instance, the unit must bePa for pressure,K for temperature,W/m2 for solar radiations andrad for wind direction.

3. Hourly and subhourly timestamp are handled in a different way in .epw files.From the EnergyPlus Auxiliary Programs Document (v9.3.0, p. 63):In hourly data the minute field can be 00 or 60. In this case as mentioned in the previous section, the weather datais reported at the hourly value and the minute field has to be ignored, writing 1, 60 or 1, 00 is equivalent.If the minute field is between 00 and 60, the file becomes subhourly, in this case the timestamp corresponds to theminute field in the considered hour. For example: 1, 30 is equivalent to 00:30 and 3, 45 is equivalent to 02:45.
   (Note the offset in the hour digit.)

4. The ReaderTMY3 should only be used with TMY3 data. It contains a time shift for solar radiation datathat is explained below. This time shift needs to be removed if the user may want touse the ReaderTMY3 for other weather data types.

Implementation

Start and end data for annual weather data files

The TMY3 weather data, as well as the EnergyPlus weather data, start at 1:00 AMon January 1, and provide hourly data until midnight on December 31.Thus, the first entry for temperatures, humidity, wind speed etc. are valuesat 1:00 AM and not at midnight. Furthermore, the TMY3 weather data files can havevalues at midnight of December 31 that may be significantly different from the valuesat 1:00 AM on January 1.Since annual simulations require weather data that start at 0:00 on January 1,data need to be provided for this hour. Due to the possibly large change inweatherdata between 1:00 AM on January 1 and midnight at December 31,the weather data files in the Buildings library do not use the data entry frommidnight at December 31 as the value for t=0. Rather, thevalue from 1:00 AM on January 1 is duplicated and used for 0:00 on January 1.To maintain a data record with 8760 hours, the weather data record frommidnight at December 31 is deleted.These changes in the weather data file are done in the Java programBuildings/Resources/bin/ConvertWeatherData.jar that convertsEnergyPlus weather data file to Modelica weather data files, and which is describedabove.The length of the weather data is calculated as theend time stamp minus start time stamp plus average increment, where theaverage increment is equal to the end time stamp minus start time stamp dividedby the number of rows minus 1.This only works correctly for weather files with equidistant time stamps.

Time shift for solar radiation data

To read weather data from the TMY3 weather data file, there aretwo data readers in this model. One data reader obtains all dataexcept solar radiation, and the other data reader reads only thesolar radiation data, shifted by 30 minutes.The reason for this time shift is as follows:The TMY3 weather data file contains for solar radiation the"...radiation receivedon a horizontal surface duringthe 60-minute period ending atthe timestamp."Thus, as the figure below shows, a more accurate interpolation is obtained iftime is shifted by 30 minutes prior to reading the weather data.

References

• Wilcox S. and W. Marion. Users Manual for TMY3 Data Sets.Technical Report, NREL/TP-581-43156, revised May 2008.

Revisions

• September 6, 2021, by Ettore Zanetti:
  Changed alt and lat to real inputs.
  This is forIBPSA, #1477.
• May 2, 2021, by Ettore Zanetti:
  Added altitude to parameters.
  This is forIBPSA, #1477.
• October 4, 2020, by Ettore Zanetti:
  Updated documentation for Java weather file generator.
  This is for#1396.
• August 20, 2019, by Filip Jorissen:
  Better clarified the meaning of time in the documentation.
  This is for#1192.
• March 5, 2019, by Michael Wetter:
  Updated documentation.
  This is for#842.
• September 20, 2018, by Michael Wetter:
  Corrected documentation.
  This is for#1022.
• December 4, 2017, by Michael Wetter:
  Removed function call to getAbsolutePath, as this causes in Dymola 2018FD01the error"A call of loadResource with a non-literal string remains in the generated code; it will not work for an URI."when exporting Buildings.Fluid.FMI.ExportContainers.Examples.FMUs.ThermalZoneas an FMU. Instead, if the weather file is specified as a Modelica, URI, syntax such asModelica.Utilities.Files.loadResource("modelica://Buildings/Resources/weatherdata/USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.mos")should be used.
  This is for#867.
• February 18, 2017, by Filip Jorissen:
  Infrared radiation on horizontal surface is now delayed by 30 minutessuch that the results inTBlaSkyare consistent.This is for#648.
• December 06, 2016, by Thierry S. Nouidui:
  Constrained the direct normal radiation to not be bigger than the solar constant when usingglobal and diffuse solar radiation data provided via the inputs connectors.This is for#608.
• April 21, 2016, by Michael Wetter:
  Introduced absFilNam to avoid multiple calls toBuildings.BoundaryConditions.WeatherData.BaseClasses.getAbsolutePath.This is forBuildings, #506.
• January 6, 2016, by Moritz Lauster:
  Changed output radHorIR to HHorIR.This is for#376.
• January 4, 2016, by Moritz Lauster:
  Added a table in documentation with output variables accessible via weaBus.This is for#376.
• December 15, 2015, by Michael Wetter:
  Added the block cheTemBlaSky. This also allows to graphicallyconnect the black body sky temperature to the weather bus, which is requiredin Dymola 2016 for the variable weaBus.TBlaSky to appearin the graphical editor.This is for#377.
• September 24, 2015, by Marcus Fuchs:
  Replace Dymola specific annotation by loadSelectorfor MSL compliancy as reported by @tbeu atRWTH-EBC/AixLib#107
• June 6, 2015, by Michael Wetter:
  Removed redundant but consistentconnect(TBlaSkyCom.TBlaSky, weaBus.TBlaSky)statement.This avoids a warning ifBuildings.BoundaryConditions.SolarIrradiation.BaseClasses.Examples.SkyClearnessis translated in pedantic mode in Dymola 2016.This is for#266.
• March 26, 2015, by Michael Wetter:
  Added option to obtain the black body sky temperaturefrom a parameter or an input signal.
• October 17, 2014, by Michael Wetter:
  Corrected error that led the total and opaque sky cover to be ten timestoo low if its value was obtained from the parameter or the input connector.For the standard configuration in which the sky cover is obtained fromthe weather data file, the model was correct. This error only affectedthe other two possible configurations.
• September 12, 2014, by Michael Wetter:
  Removed redundant connection connect(conHorRad.HOut, cheHorRad.HIn);.
• May 30, 2014, by Michael Wetter:
  Removed undesirable annotation Evaluate=true.
• May 5, 2013, by Thierry S. Nouidui:
  Added the option to use a constant, an input signal or the weather file as the sourcefor the ceiling height, the total sky cover, the opaque sky cover, the dew point temperature,and the infrared horizontal radiation HInfHor.
• October 8, 2013, by Michael Wetter:
  Improved the algorithm that determines the absolute path of the file.Now weather files are searched in the path specified, and if not found, the urlsfile://, modelica:// and modelica://Buildingsare added in this order to search for the weather file.This allows using the data reader without having to specify an absolute path,as long as the Buildings libraryis on the MODELICAPATH.This change was implemented inBuildings.BoundaryConditions.WeatherData.BaseClasses.getAbsolutePathand improves this weather data reader.
• May 2, 2013, by Michael Wetter:
  Added function call to getAbsolutePath.
• October 16, 2012, by Michael Wetter:
  Added computation of the wet bulb temperature.Computing the wet bulb temperature introduces a nonlinearequation. As we have not observed an increase in computing timebecause of computing the wet bulb temperature, it is computedby default. By setting the parametercomputeWetBulbTemperature=false, the computation of thewet bulb temperature can be removed.Revised documentation.
• August 11, 2012, by Wangda Zuo:
  Renamed radHor to radHorIR andimproved the optional inputs for radiation data.
• July 24, 2012, by Wangda Zuo:
  Corrected the notes of SI unit requirements for input files.
• July 13, 2012, by Michael Wetter:
  Removed assignment of HGloHor_in in its declaration,because this gives an overdetermined system if the input connectoris used.Removed non-required assignments of attribute displayUnit.
• February 25, 2012, by Michael Wetter:
  Added subbus for solar position, which is needed by irradition andshading model.
• November 29, 2011, by Michael Wetter:
  Fixed wrong display unit for pAtm_in_internal andmade propagation of parameter final.
• October 27, 2011, by Wangda Zuo:
  
  1. Added optional connectors for dry bulb temperature, relative humidity, wind speed, wind direction, global horizontal radiation, diffuse horizontal radiation.
     
  2. Separate the unit conversion for TMY3 data and data validity check.
• October 3, 2011, by Michael Wetter:
  Propagated value for sky temperature calculation to make it accessible as a parameter.
• July 20, 2011, by Michael Wetter:
  Added the option to use a constant, an input signal or the weather file as the sourcefor the atmospheric pressure.
• March 15, 2011, by Wangda Zuo:
  Delete the wet bulb temperature since it may cause numerical problem.
• March 7, 2011, by Wangda Zuo:
  Added wet bulb temperature. Changed reader to read only needed columns.Added explanation for 30 minutes shift for radiation data.
• March 5, 2011, by Michael Wetter:
  Changed implementation to obtain longitude and time zone directlyfrom weather file.
• June 25, 2010, by Wangda Zuo:
  First implementation.