.. GEM-MACH documentation master file, created by sphinx-quickstart on Wed Oct 30 15:13:39 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. GEM-MACH ======== The GEM-MACH package provides a `sasktran.Climatology `_ and a `ISKClimatology `_ interface to the GEM-MACH 2.5 km regional climate model. It reads model output variables from netcdf4 generated by Chris McLinden's group at Environment Canada. Note that the model has relatively coarse height resolution in the stratosphere Quick Start ----------- Here is an example that shows you how to use GEM-MACH. With a bit of luck this will be all you really need. There are two things specific to this climatology that must be done before you can use it to get height profiles, #. You must tell the climatology which file to read with a call to `set_gem_filename`. #. You must tell the climatology which species you are interested in so it will load the appropriate variables from file. If you needmore info then you will have to read the rest of the documentation:: from datetime import datetime import numpy as np import matplotlib.pyplot as plt from sasktran_gcm import GEM_MACH climate = GEM_MACH() # Create the GEM-MACH object climate.set_gem_filename(r'\\datastore\valhalla\root\data_products\GEM\20180621_gemmach2p5.nc') # Tell GEM-MACH which file to read. climate.add_species ( 'SKCLIMATOLOGY_NO2_CM3') # Tell GEM-MACH which variables you want to load. You must do this before calling UpdateCache. climate.add_species ( 'SKCLIMATOLOGY_NO2_VMR') # Add all the variables you want. Each variable added will require several seconds of processing in UpdateCache latitude=50.3456289 # Set up a reference location longitude=247.982739087 # The latitude, longitude and utc utc=datetime.fromisoformat('2018-06-21T12:00:00.000000') # should be "inside" the GEM-MACH regional output ranges. climate.update_cache(latitude,longitude, utc) # [Optional] Load up the cache. The time variable is used to load in two snapshots that straddle the location mjd # All variables are now fixed. Only variables specified in `addvariable` are available h = np.arange( 0, 60000.0, 100.0) # Prepare to extract profiles. Create a height resolution set of heights, 0 to 60 km no2cm3 = climate.get_parameter( 'SKCLIMATOLOGY_NO2_CM3', latitude, longitude, h, utc) # Get a height profile of NO2 number density at the given location no2vmr = climate.get_parameter( 'SKCLIMATOLOGY_NO2_VMR', latitude, longitude, h, utc) # Get a height profile of NO2 volume mixing ratio at the given location plt.figure(1) # and plot the data plot the data. plt.plot( no2vmr,h, 'ko-') plt.figure(2) plt.plot( no2cm3,h, 'ko-') plt.show() print('Done') .. image:: images/gem_mach_no2_vmr.png .. image:: images/gem_mach_no2_nd.png Sasktran Usage -------------- The Sasktran GEM-MACH climatology is developed in C++ and complies with the `ISKClimatology `_ interface within the `SasktranIF `_ framework. A wrapper class has also been developed for use with the `Sasktran API `_: import GEM_MACH from the `sasktran_gcm` package and create a new instance of class GEM_MACH:: >>> from sasktran_gcm import GEM_MACH >>> gem = GEM_MACH() >>> print(gem) SasktranIF Climatology: GEM-MACH Supported Species: ['SKCLIMATOLOGY_NO2_CM3', 'SKCLIMATOLOGY_AIRNUMBERDENSITY_CM3', 'SKCLIMATOLOGY_TEMPERATURE_K', 'SKCLIMATOLOGY_SURFACE_GEOMETRIC_HEIGHT', 'SKCLIMATOLOGY_SURFACE_GEOPOTENTIAL_HEIGHT', 'SKCLIMATOLOGY_CO_CM3', 'SKCLIMATOLOGY_CH4_CM3', 'SKCLIMATOLOGY_NH3_CM3', 'SKCLIMATOLOGY_NO_CM3', 'SKCLIMATOLOGY_O3_CM3', 'SKCLIMATOLOGY_SO2_CM3', 'SKCLIMATOLOGY_PRESSURE_PA', 'SKCLIMATOLOGY_NO2_VMR', 'SKCLIMATOLOGY_CO_VMR', 'SKCLIMATOLOGY_CH4_VMR', 'SKCLIMATOLOGY_NH3_VMR', 'SKCLIMATOLOGY_NO_VMR', 'SKCLIMATOLOGY_O3_VMR', 'SKCLIMATOLOGY_SO2_VMR'] >>> GEM_MACH Class ^^^^^^^^^^^^^^ .. autoclass:: sasktran_gcm.gem_mach_climatology.GEM_MACH :members: SasktranIF Property List ^^^^^^^^^^^^^^^^^^^^^^^^ Users may wish to program the gem mach climatology object directly through the SasktranIF interface:: ok = gem.skif_object.SetProperty('PropertyName', value) The property name is not case sensitive, and the value may be a scalar, list, or array depending upon context .. option:: set_gem_filename (string name) Specifies the filename of the GEM-MACH model that will be loaded at the next call to update_cache. Users must specify the full filename of the GEM-MACH file although it can be relative or absolute with respect to the current folder. .. option:: add_species (string variablename) Specifies the name of a species to load at the next call to UpdateCache. Multiple variables can be requested using multiple calls to `add_species` but all calls must be made before the first call to update_cache or get_parameter. Variables --------- The GEM-MACH package supports the following geophysical parameters, ============================================== ======================================= Sasktran Handle Description ============================================== ======================================= SKCLIMATOLOGY_AIRNUMBERDENSITY_CM3 Air number density SKCLIMATOLOGY_PRESSURE_PA Pressure SKCLIMATOLOGY_TEMPERATURE_K Temperature SKCLIMATOLOGY_SURFACE_GEOPOTENTIAL_HEIGHT Surface Geopotential Height (meters) SKCLIMATOLOGY_SURFACE_GEOMETRIC_HEIGHT Surface Geometric Height (meters) SKCLIMATOLOGY_CH4_CM3 CH\ :sub:`4`\ . Methane SKCLIMATOLOGY_CH4_VMR CH\ :sub:`4`\ . Methane SKCLIMATOLOGY_CO_CM3 CO SKCLIMATOLOGY_CO_VMR CO SKCLIMATOLOGY_NH3_CM3 NH\ :sub:`3`\ . Ammonia SKCLIMATOLOGY_NH3_VMR NH\ :sub:`3`\ . Ammonia SKCLIMATOLOGY_NO2_CM3 NO\ :sub:`2` SKCLIMATOLOGY_NO2_VMR NO\ :sub:`2` SKCLIMATOLOGY_NO_CM3 NO SKCLIMATOLOGY_NO_VMR NO SKCLIMATOLOGY_O3_CM3 O\ :sub:`3`\ . Ozone SKCLIMATOLOGY_O3_VMR O\ :sub:`3`\ . Ozone SKCLIMATOLOGY_O2_CM3 O\ :sub:`2`\ . Oxygen SKCLIMATOLOGY_O2_O2_CM6 (O\ :sub:`2`\ )\ :sup:`2`\ for CIA SKCLIMATOLOGY_SO2_CM3 SO\ :sub:`2`\ SKCLIMATOLOGY_SO2_VMR SO\ :sub:`2`\ ============================================== ======================================= Variables are specified on 62 sigma pressure levels within the model across the *rectangular* region of interest. The system typically provides profiles that extend from the topographic surface to 40-45 km. The profiles have good height resolution at lower altitudes within the troposphere but become significantly coarser within the stratosphere. The current implementation provides no diagnostic information about the model height resolution to the user. The variables in any given file are specified for one day at 24 hourly snapshots across a limited *rectangular* latitude-longitude area, typically 13 degrees by 12 degrees. The GEM-MACH sastran package implicitly assumes the user will limit their usage of the GEM-MACH model to the limited time period and regional area covered by the model. The current implementation provides no diagnostic information to the user about the temporal and spatial extents of the regional model. Users can use other tools, eg. **xarray**, **Panoply** or **HDFView** to obtain information not provided by the Sasktran GEM-MACH package. Overview -------- Each GEM-MACH 2.5 km file provides a sequence of high spatial resolution snapshots of model output variables across a limited regional area. The area is typically of the order of ~13 degrees longitude by ~12 degrees latitude with 2.5 km resolution on a 62 level sigma level pressure grid. Snapshots are typically provided on the UTC hour for every hour in a specific day. For example, in the figure below we can see the geopotential height of the surface (in decimeters) across the regional area contained in an example GEM-MACH 2.5 km file. .. image:: images/GZ_in_20180621_gemmach2p5.png The grid covers approximately 13 degrees of longitude by 12.6 degrees of latitude. The internal coordinate system used by the GEM-MACH files is **rotated_pole** and once the regional area is mapped onto a geographic coordinate system we can from the image below see that the regional area is the lower half of Alberta Canada. The Rocky mountains are visible in the left hand corner of the regional plot above. .. image:: images/GZ_in_20180621_gemmach2p5_2.png Time Extrapolation ^^^^^^^^^^^^^^^^^^ The time range of any GEM-MACH variable is defined when calling `UpdateCache `_. At this point two snapshots are loaded from the model output that straddle the requested time (UTC expressed as mjd). It is an error to request a time that is outside the time range spanned by the model. .. note:: The GEM-MACH netcdf files only have 24 one hour samples which means it does not cover a full day. The files only cover the time from 00:00 UTC to 23:00 UTC on any specific day. Time Interpolation ^^^^^^^^^^^^^^^^^^ Any instant within the GEM-MACH time range is surround by two, hourly snapshots. Variables are calculated for each snapshot and then linearly interpolated in time. Linear interpolation occurs at a fixed geographic latitude, longitude and geometric height. Horizontal Extrapolation ^^^^^^^^^^^^^^^^^^^^^^^^ The GEM-MACH sasktran package allows users to ask for the value of variables outside the rectangular regional area but it will truncate results to the value at the appropriate border of the regional area. The intent of this rule is to proivide sensible support for the various secondary rays within a sasktran calculation that may stray beyond the limits of the GEM-MACH regional area. .. note:: The user is responsible for ensuring they do not run significant amounts of their calculations outside the regional area of the GEM-MACH model. Such behaviour will not generate any warnings and may give *"reasonable"* but wrong results. Horizontal Interpolation ^^^^^^^^^^^^^^^^^^^^^^^^ All variables within the GEM-MACH regional area are linearly interpolated in the horizontal direction. Any geographic point on any hourly snapshot within the regional area is surrounded by the 4 points, two in latitude and two in longitude, and linearly interpolate din both directions. The horizontal interpolation is performed at a fixed geometric height. Vertical Extrapolation ^^^^^^^^^^^^^^^^^^^^^^ All variables within the sasktran GEM-MACH package are set to zero at all altitudes above the highest level of the model. All variables, except temperature, are set to zero for all altitudes below the topographic surface. Note that the topographic surface is the height of actual ground above sea-level and can change within the GEM-MACH regional area from 1.4 km in the Rocky mountains to 200 meters on the Prairies. This latter, sub-surface, condition allows the topographic conditions inherent to the GEM-MACH model to be incorporated, at least to first order, within the Sasktran radiative transfer models by approximating the atmosphere below the topographic surface as a vacuum. .. note:: The *"vacuum below the surface"* approximation is not available in other sasktran climatologies. Users should ensure they have the appropriate, *"below surface"* behaviour in all climatologies used in any sasktran calculation otherwise strange results may occur. Vertical Interpolation ^^^^^^^^^^^^^^^^^^^^^^ Vertical interpolation of GEM-MACH variables, is to first order, arranged so that volume mixing ratios are linearly interpolated with altitude while number densities are log interpolated. In practice the interpolation of the number density parameters is more complicated. Number density parameters are not directly available in the GEM-MACH output and generated from interpolation of the appropriate volume mixing ratio, pressure and temperature. Volume mixing ratio and temperature are linearly interpolated while pressure is log interpolated. Acknowledgements ---------------- Some of the images were created by `Panoply `_ which provides a quick and convenient way to browse many geophysical data files