Pratmo_BoxModel

class Pratmo_Boxmodel

The Pratmo_Boxmodel is the python class that implements the pratmo photo-chemical box model. In practice the class is a shallow SWIG wrapper for C++ code. The class is in paackage pratmo and can be installed on 64 bit python systems (python 3.4 and higher) by installing the appropriate wheel. An instance of the pratmo box model is created with the following code:

>>> from pratmo import pratmo
>>>
>>> boxmodel = pratmo.Pratmo_BoxModel()
>>> numbad = boxmodel.Solve( 60.0, 0.0, 56732.5)
>>> speciesnames = boxmodel.GetVariableNames('ARMLJ')
>>> [ok,no2]     = boxmodel.GetSpecies('NO2')

Descriptions

SetDailyConvergenceRatio(ratio : float) → bool

Sets the fractional convergence criteria for the values of radicals at the start and end of each day. Pratmo will continue to iterate through days until all radicals meet or exceed this convergence ratio or until the maximum number of days is encountered. The value can have a significant impact upon performance. The default value is set to 0.5% (i.e. 5.0E-03). Note that pratmo struggles to meet even this requirement at lower altitudes.

Parameters:ratio (float) – The desired daily convergence ratio to be used on the next call to Solve. The default is 5.0E-03.
Return type:bool
Returns:True if successful
SetClimatology(speciesname : str, input_climate :ISKClimatology) → bool

Instructs pratmo to use the provided climatology for a given species within the model. The species name should be taken from the first column of the table below and is not a standard CLIMATOLOGY name. The new climatology will be used on the next call to Solve()

Parameters:
  • speciesname – The name of the climatology that will be changed in the Pratmo model. A list of valid, case-sensitive, names is given in the table below.
  • climatology – An instance of the ISKClimatology object for the species being changed. This ISKClimatology object must support the CLIMATOLOGY_HANDLE specified for each species indicated in the table below.
Return type:

bool
Returns:

True if successful
Name Description ISKClimatology instance must support
‘T’ Temperature profile in Kelvins SKCLIMATOLOGY_TEMPERATURE_K
‘P’ Pressure profile in Pascals. SKCLIMATOLOGY_PRESSURE_PA
‘DM’ Air number density in molecules/cm3 SKCLIMATOLOGY_AIRNUMBERDENSITY_CM3
‘JH2O’ H2O photodissociation. Default was calculated by Chris McLinden SKCLIMATOLOGY_JH2O
‘ASA’ Aerosol Surface Area in µm2/cm3 SKCLIMATOLOGY_AEROSOLSURFACEAREA_UM2PerCM3
‘O3’ Mixing ratio profile. SKCLIMATOLOGY_O3_VMR
‘N2O’ Mixing ratio profile. SKCLIMATOLOGY_N2O_VMR
‘NOY’ Mixing ratio profile. SKCLIMATOLOGY_NOY_VMR
‘CO2’ Mixing ratio profile. Default is constant 314 ppm. SKCLIMATOLOGY_CO2_VMR
‘N2’ Mixing ratio profile. Default is constant 0.78084. SKCLIMATOLOGY_N2_VMR
‘O2’ Mixing ratio profile. Default is constant 0.20948. SKCLIMATOLOGY_O2_VMR
‘CO’ Mixing ratio profile. Default is 30 ppb. SKCLIMATOLOGY_CO_VMR
‘CF2CL2’ Mixing ratio profile. Default is 100 ppt. SKCLIMATOLOGY_CF2CL2_VMR
‘CFCL3’ Mixing ratio profile. Default is 100 ppt. SKCLIMATOLOGY_CFCL3_VMR
‘CCL4’ Mixing ratio profile. Default is 100 ppt. SKCLIMATOLOGY_CCL4_VMR
‘MECL’ Mixing ratio profile. Default is 100 ppt. SKCLIMATOLOGY_MECL_VMR
‘NH3’ Mixing ratio profile. Default is 0. SKCLIMATOLOGY_NH3_VMR
‘C5H8’ Mixing ratio profile. Default is 0. SKCLIMATOLOGY_C5H8_VMR
‘CH3BR’ Mixing ratio profile. Default is 10 ppt. SKCLIMATOLOGY_CH3BR_VMR
‘XXX’ Mixing ratio profile. Default is 0. SKCLIMATOLOGY_XXX_VMR
‘H2’ Mixing ratio profile. Default is 0.5 ppm SKCLIMATOLOGY_H2_VMR
‘CH4’ Mixing ratio profile. Default is from an n2o scaling. SKCLIMATOLOGY_CH4_VMR
‘H2O’ Mixing ratio profile. Default is from an n2o scaling SKCLIMATOLOGY_H2O_VMR
‘BRY’ Mixing ratio profile. Default is from an n2o scaling SKCLIMATOLOGY_BRY_VMR
‘CLY’ Mixing ratio profile. Default is from an n2o scaling SKCLIMATOLOGY_CLY_VMR
‘CH3CL’ Mixing ratio profile. Default is from an n2o scaling SKCLIMATOLOGY_CH3CL_VMR
SetAtmosphericStateClimatology(input_climate : ISKClimatology) → bool

A shortcut allowing the same ISKClimatology object, representing the background atmopshere, to be used for pressure (‘P’), temperature (‘T’) and air density (‘DM’) in the pratmo model.

Parameters:input_climate – An ISKClimatology that supports a tandard background atmosphere, P, T and DM.
Returns:True if successful
SetBoxHeights(heightmeters:numpy_array) → bool

Sets the heights in meters of the photochemical boxes used within the Pratmo box model. The chemical and photochemical composition of the atmosphere is calculated at this array of heights. Typical values range from 0 to 60 km in 1 or 2 km steps. The default is 0 to 60 in 1 km steps.

Parameters:heightmeters – An array of heights in meters in ascending order.
Returns:True if successful
SetAtmosphericHeights(heightmeters:numpy_array) → bool

Sets the heights within the pratmo box model that will be used to cache all atmospheric species and will be used by the internal radiative transfer engine. This will typically go from 0 to 80 km in 1 or 2 km steps. The default is 0 to 80 km in 1 km steps.

Parameters:heightmeters – An array of heights in meters in ascending order.
Returns:True if successful
SetAlbedo(albedo:float) → bool

Sets the albedo used by the internal radiative transfer engine. The albedo will be used across the entire wavelength range used by the pratmo model.

Parameters:albedo – The albedo value used by the model. The default is 0.0.
Returns:True if successful
SetNominalTimeSteps(numtimesteps : int) → bool

Sets the number of time steps used in the Pratmo model. Pratmo splits a 24 hour interval into a sequence of this many time steps. The time steps are evenly spaced in the cosine of solar zenith angle as this gives better temporal resolution than equally spaced time steps in the dawn/dusk sectors where many chemicals change rapidly. Please note that the number is nominal and the box model usually adds a few more points to deal with various issues during its execution of Solve. Users can also add extra time steps by calling :AddCustomLocalSolarTime() or AddCustomSolarZenithAngle().

Parameters:numtimesteps – The number of timesteps used in a day. The default is 48 samples per 24 hour period.
Returns:True if successful
SetNumDaysForConvergence(numdays : int) → bool

Sets the number of days to run the pratmo model. The pratmo model internally saves only the last 24 hour period and must run for several days to ensure the 24 hour period solution has converged. This function will limit the number of days, typically so it avoids running in an infinite, non-converging loop. Note that pratmo will exit before this value is reached if the solution has converged to limits set by SetDailyConvergenceRatio()

Parameters:numdays – The maximum number of days to that the model will run. The default is 100 (I think).
Returns:True if successful
SetOzoneLongLived(islonglived : bool) → bool

Instructs Pratmo to either treat ozone as a long lived species (default) or as a radical species.

Parameters:islonglived – If True then pratmo treats as a long lived species.
Returns:True if successful
AddCustomLocalSolarTime(lst: float) → bool

Allows the user to add specific Local Solar Times to the list of time steps internally generated by Pratmo. This is useful if the user wants to ensure that Pratmo generates a solution at a specific local solar time.

Parameters:lst – The specific local solar time (0.0 to 24) in hours to be added to the list of time steps. 0 is midnight, 6 is nominal dawn, 12 is noon and 18 is nominal dusk.
Returns:True if successful
AddCustomSolarZenithAngle(sza: float) → bool

Allows the user to add the two times of a specific solar zenith angles to the list of time steps internally generated by Pratmo. Useful if the user wants to ensure that Pratmo generates a solution at a specific solar zenith angle. Note that a specific solar zenith angle will occur before and after noon and both times are inserted into the processing.

Parameters:sza – The Solar Zenith Angle of the two times to be inserted into the processing. The solar zenith angle must be between 0 and 180. The code will internally store but ignore solar zenith angles which are out of the possible range of values for a given location on a given date.
Returns:True if successful
GetSpecies(species_name : str ) -> (bool, 2darray)

Returns the values calculated for the requested species at each box altitude and time step during the last call to Solve. Pratmo supports over 110 species, the names of which can be found by calling GetVariableNames(), a subset is also given in the table in method SetClimatology(). A few important values are ‘NO2’, ‘NO’, ‘NOY’ and ‘M’ where M is the atmospheric number density.

Parameters:species_name – The name of the required species. The value is case-sensitive. Most names must be capitalized. See GetVariableNames()
Returns:(ok, species)

ok True if successful

species
A 2-D numpy array of size [BoxHeights() x LocalSolarTimes()]. Contains the value of the required species at each time step and altitude.
GetMaxStoichiometryErrors() -> ( bool, 2darray)

Returns the maximum iteration convergence errors for each box altitude and time step during the last call to Solve. The convergence errors indicate the fractional change of the value in the last iteration within Pratmo.

Returns:(ok, errors)

ok True if successful

errors
Returns a 2d array of stoichiometry error values of size [BoxHeights() x LocalSolarTimes()]. Typical convergence values are better than 1.0E-10 although these can be significantly degraded when numerical round off errors become important. Contains the error at each time step and altitude.
GetMaxStoichiometryConvergence() -> (bool, 2darray)

Returns the maximum iteration convergence errors for each box altitude and time step during the last call to Solve. The convergence errors indicate the fractional change of the value in the last iteration within Pratmo.

Returns:(ok, convergence)

ok True if successful

convergence
The 2d array of convergence error values of size [BoxHeights() x LocalSolarTimes()]. Typical convergence values are better than 1.0E-10 although these can be significantly degraded when numerical round off errors become important.
GetSpeciesConvergenceProfile(radicalname : string) -> (bool, 1darray)

Returns the profile of fractional differences between the start and end values for a given radical species during the last call to Solve. This value indicates how closely the solution has achieved stability. The code will try to exceed the convergence set in the last call to SetDailyConvergenceRatio(), typically around 0.5%, but the code may fail to reach the desired goal, especially at lower altitudes.

Parameters:radicalname – The name of the radical to be examined.
Returns:(ok, convergence_profile)

ok True if successful

convergence_profile
Returns the array of convergence fractions for the given species. This is a 1d array of size [BoxHeights()]. One entry is provided for each altitude specified by the box heights.
GetVariableNames(regions : str) → string_array

Return the names of all the variables stored inside the pratmo model. The user can select variables by the internal regions used within Pratmo or can provide an empty regionfilter string to select all regions. The names returned can be used in method GetSpecies() to retrieve profiles of any of Pratmo`s many internal variables.

Parameters:regions – A string used to select the names of variables in the 5 regions of the pratmo model (see table below). An empty string will return the names in all regions. The function will return variables for a given region if the Id code given in the table below can be found in the string. For example, “ARL” will return variables in the Atmospheric, Radical and Long-Lived sections of Pratmo.
Returns:an array of names (strings) that can be used in functions like GetSpecies().
Id Description Comment
A Atmospheric Section Constant
R Radical Section Changed by Pratmo
L Long-Lived Section Constant
M Miscellaneous Section mixed
J Photo-dissociation Section Changed by Pratmo
BoxHeights() → 1darray

Returns the altitudes of the box heights used in Pratmo

Returns:a 1d-array of heights used in the pratmo model. Heights are returned in meters.
LocalSolarTimes() → 1darray

Returns the array of time steps used in pratmo as an array of local solar times. The local solar time varies between 0 and 24 where 0 is midnight, 6 is nominal dawn, 12 is noon and 18 is nominal dusk.

Returns:a 1d-array of time steps used in the pratmo model expresed as solar times.
SZA() → 1darray

Returns the array of time steps used in pratmo as an array of local solar zenith angles. The local solar zenith angles varies between 0 and 180.

Returns:a 1d-array of time steps used in the pratmo model expressed as solar zenith angles.
Solve(latitude : float, longitude : float, mjd : float) → int

Uses the current configuration to solve the pratmo stoichiometry at the given latitude, longitude and time. The code will normally execute in a few seconds using default settings but may take substantially longer if the configuration demands it. The code is multi-threaded and tries to use all cpu resources. You may find other applications are sluggish during execution.

Parameters:
  • latitude – The latitude where a solution is required. Between -90 and +90.
  • longitude – The longitude where a solution is required. Between -180 and +360.
  • mjd – The modified Julian date where a solution is required.
Returns:

Returns the number of box heights that failed to converge. A negative value implies an internal error within the pratmo model. A value of 0 implies all box heights successfully converged. A value greater than 0 indicates the number of box heights that failed to converge. Beware that normal execution of pratmo can returns heights which are not fully converged. The user can check the convergence of specific species with calls to GetSpeciesConvergenceProfile()
InterpolateSpecies(species_name : string, latitude : float, longitude : float, height : float, mjd : float) → [bool , float]

Interpolates the specified species within the pratmo model to the specified location. Note that latitude is ignored in the current implementation. the longitude and mjd are used to get local solar time offsets into the current solution and interpolate values.

Parameters:
  • species_name – The name of the internal pratmo variable. See GetVariableNames().
  • latitude – The latitude where a solution is required. Between -90 and +90. Ignored by curent implementation
  • longitude – The longitude where a solution is required. Between -180 and +360.
  • height – The height in meters where a solution is required. Between bottom and top of box model.
  • mjd – The modified Julian date where a solution is required.
Returns:

(ok, value)

ok True if successful

value

returns the interpolated value.