.. _advanced: Advanced Topics *************** Creating SasktranIF Like Objects ================================ Motivation ---------- Often it is desired to create a new optical property or climatology for a project, but modifying the SasktranIF internals is not an option. In the climatology case solution for this kind of problem is to use the UserDefined classes available to make a climatology for example. However this has the downside that the created object no longer acts like a `Climatology`, it is often fixed to an instant in time and location. With the `sasktran` package we are able to create pseudo-sasktranif objects where the logic is implemented in Python, but are still able to be used in the same way as regular `sasktranif` style objects. This allows a decoupling of the configuration and execution stages. How It Works ------------ All climatologies, optical properties, etc, that are input to a SASKTRAN engine must still be raw `sasktranif` objects. However since in the `sasktran` package we operate one level above the raw `sasktranif` interface, only converting to `ISK` style objects when necessary, we can defer this conversion until the last possible moment, typically right before the radiative transfer calculation. At the time of this conversion we ideally have a variety of information available to us, for example, the wavelengths of the calculation, and the internal model reference point. Therefore any class that has information that can be converted into a `sasktranif` base object, such as a `UserDefinedProfile` can be integrated very closely with the `sasktran` package. Example - Scaling Climatology ----------------------------- As a first example, we will implement a scaling climatology, something which takes in an existing climatology and scales it by a constant value. :: from sasktran.climatology import ClimatologyBase import numpy as np class ScalingClimatology(ClimatologyBase): def __init__(self, other_climatology, scale_factor): self._other_climatology = other_climatology self._scale_factor = scale_factor def get_parameter(self, species: str, latitude: float, longitude: float, altitudes: np.ndarray, mjd: float): return self._other_climatology.get_parameter(species, latitude, longitude, altitudes, mjd) * self._scale_factor def skif_object(self, **kwargs): pass All we do is call the other climatology, and scale it by a number. Let's try it out:: from sasktran.climatology import Labow other_clim = Labow() scaled_clim = ScalingClimatology(other_clim, scale_factor=2.0) other_clim.get_parameter('SKCLIMATOLOGY_O3_CM3', 0, 0, [10000, 30000], 54372) # array([ 4.78059418e+11, 3.66810991e+12]) scaled_clim.get_parameter('SKCLIMATOLOGY_O3_CM3', 0, 0, [10000, 30000], 54372) # array([ 9.56118837e+11, 7.33621983e+12]) Now we have a climatology that we can get parameters out of it, but can we can't actually use this in a radiative transfer calculation. The climatology is passed through to the SASKTRAN engine by using the `skif_object` method, which we have not yet implemented. In this function we need to convert our Climatology to a form that SASKTRAN can use. This can be done in a variety of ways, but lets take advantage of an existing class, the ClimatologyUserDefined class. We also need to know what the reference point for the model is, this is where the \*\*kwargs argument saves the day. All standard engines when calling skif_object will pass a reference to themselves inside the \*\*kwargs argument. :: from sasktran.climatology import ClimatologyBase, ClimatologyUserDefined import numpy as np class ScalingClimatology(ClimatologyBase): def __init__(self, other_climatology, scale_factor): self._other_climatology = other_climatology self._scale_factor = scale_factor def get_parameter(self, species: str, latitude: float, longitude: float, altitudes: np.ndarray, mjd: float): return self._other_climatology.get_parameter(species, latitude, longitude, altitudes, mjd) * self._scale_factor def skif_object(self, **kwargs): altitudes = np.arange(0, 100000, 500) clim_values = dict() engine = kwargs['engine'] reference_point = engine.model_parameters['referencepoint'] latitude = reference_point[0] longitude = reference_point[1] mjd = reference_point[3] for species in self._other_climatology.supported_species(): clim_values[species] = self.get_parameter(species, latitude, longitude, altitudes, mjd) userdef_clim = ClimatologyUserDefined(altitudes, clim_values) return userdef_clim.skif_object() Here we have taken the reference point from the engine right before the radiative transfer calculation is about to happen, and then we create our climatology dynamically based upon this. For this example we have hard coded the altitudes in, however we could also look at the engines option map and figure out what the optical property table altitudes are. We now have an object where the logic is implemented inside python, but we can still use it the same as any `sasktranif` climatology object. Why Not Just Make a User Defined Climatology? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We could have just as easily make a ClimatologyUserDefined object with the scaled values above and used that instead, what is better about what we have done? The primary advantage is that we do not need to know the configuration ahead of time. If we wanted to make a UserDefined object from the beginning we would need to know what latitude/longitude/mjd to use for our values, and if we wanted to change them later we would need to remake the object. Another advantage is that we can change things in our climatology relatively easy. If we wanted to add a method to change the scaling factor we could do that very easily. If we wanted to change the scaling factor of the UserDefined climatology we would have to remake the object, and reset its reference in other places such as the atmosphere class. Writing these kinds of objects allows easy integration with the core of the `sasktran` package.