Ctrl+K

General Contributions#

To submit a new feature or bug-fix, first create an issue on the TUV-x GitHub repository that describes the new feature or bug. The software contribution can then be submitted as a pull request. Please reference the issue in the pull request description.

Software contributions must apply the MUSICA FORTRAN Style Guide. See also the MUSICA Recommendations for Contributors and the MUSICA software development plan.

Developers must ensure that new features have complete unit test coverage. Pull requests that decrease the test coverage of the TUV-x code base will not be accepted. Developers must also ensure that new features are fully run-time configurable.

Science Contributions#

Cross Sections#

The base functionality for cross section calculations is described in src/cross_section.F90. The base cross section type ~tuvx_cross_section/cross_section_t defined in this module includes a constructor that reads a set of NetCDF files specified in the configuration JSON object as an array of file paths with the key netcdf files.

Here is an exmple configuration for a base cross section:

{
  "type": "base",
  "netcdf files": [ "path/to/my/netcdf/file.nc" ]
}

More description of the cross section configuration can be found here. The reading of NetCDF file data is available to cross section subclasses through the tuvx_cross_section/base_constructor function.

Data from each NetCDF file in the array in the configuration data will be loaded into an element of the cross_section_parms data member. If a NetCDF variable named cross_section_parameters is present, it will be used to populate the array(:,:) data member of the cross_section_parms_t object. This first dimension of the array is wavelength, and will be interpolated to the native TUV-x wavelength grid if this differs from the wavelength grid in the netcdf file (named wavelength). The second dimension is used to accomodate multiple wavelength-resolved parameters for cross section calculations.

If a NetCDF variable named temperature is present, it will be used to populate the temperature(:) data member of the cross_section_parms_t object.

The calculation of cross sections is done by calling the calculate() type-bound procedure on a ~tuvx_cross_section/cross_section_t object.

The base-class calculation of cross sections returns the wavelength-interpolated first parameter (array(:,1)) from the first NetCDF file (cross_section_parms(1)) specified in the configuration data.

Cross section subclasses are located in the src/cross_sections/ folder. These each provide unique algorithms for calculating cross sections.

Before adding a new cross section class, first check to make sure there is not an existing class that can be configured to accomodate your needs. If you find that an existing cross section subclass could be used by moving one or more hard-coded parameters to the configuration data, this is preferable to adding a new subclass.

If you determine that a new cross section subclass is needed, this can be done in five steps:

Create subclass module#

First, choose a unique name for your cross section calculation. Ideally, this name will describe the algorithm, rather than the specific photolysis reaction you are applying it to. However, many subclasses currently in TUV-x are named for specific photolysis reactions. For this example, we will use the name foo for our cross section algorithm.

Pay special attention to naming of files, modules, types, and functions in these instructions.

Create a file to hold your new subclass module in src/cross_sections/ named foo.F90. The general layout of the module will be (comments have been omitted for this example, but should be included in an actual module):

! Copyright (C) 2020 National Center for Atmospheric Research
! SPDX-License-Identifier: Apache-2.0
!
module tuvx_cross_section_foo

  use tuvx_cross_section,              only : cross_section_t

  implicit none

  private
  public :: cross_section_foo_t

  type, extends(cross_section_t) :: cross_section_foo_t
  contains
    procedure :: calculate
  end type cross_section_foo_t

  interface cross_section_foo_t
    module procedure constructor
  end interface cross_section_foo_t

contains

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

  function constructor( config, grid_warehouse, profile_warehouse )           &
      result( this )

    use musica_assert,                 only : assert_msg
    use musica_config,                 only : config_t
    use musica_string,                 only : string_t
    use tuvx_cross_section,            only : base_constructor
    use tuvx_grid_warehouse,           only : grid_warehouse_t
    use tuvx_profile_warehouse,        only : profile_warehouse_t

    class(cross_section_t),    pointer       :: this
    type(config_t),            intent(inout) :: config
    type(grid_warehouse_t),    intent(inout) :: grid_warehouse
    type(profile_warehouse_t), intent(inout) :: profile_warehouse

    type(string_t) :: required_keys(1), optional_keys(1)

    ! This block of code ensures that the configuration keys are valid for
    ! your class. These can be modified to fit your needs. The first
    ! argument to assert_msg() should be a unique integer code for this error.
    required_keys(1) = "type"
    optional_keys(1) = "name"
    call assert_msg( 465568611,                                               &
                     config%validate( required_keys, optional_keys ),         &
                     "Bad configuration data format for "//                   &
                     "foo cross section." )

    allocate( cross_section_foo_t :: this )

    ! You can call the base_constructor function to load data from NetCDF
    ! files into the `cross_section_parms(:)` data member according to the
    ! standard base class logic. Alternatively, you can perform custom
    ! initialization of the subclass object here.
    call base_constructor( this, config, grid_warehouse, profile_warehouse )

  end function constructor

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

  function calculate( this, grid_warehouse, profile_warehouse, at_mid_point ) &
      reuslt( cross_section )

    use musica_constants,              only : dk => musica_dk
    use tuvx_grid_warehouse,           only : grid_warehouse_t
    use tuvx_profile_warehouse,        only : profile_warehouse_t

    class(cross_section_foo_t), intent(in) :: this
    type(grid_warehouse_t),     intent(inout) :: grid_warehouse
    type(profile_warehouse_t),  intent(inout) :: profile_warehouse
    ! This flag indicates whether the cross-section data should be calculated
    ! at mid-points on the vertical grid. If it is false or omitted, cross-
    ! section data are calculated at interfaces on the vertical grid.
    logical, optional,          intent(in)    :: at_mid_point
    real(kind=dk), allocatable                :: cross_section(:,:)

    ! Do your calculation here

  end function calculate

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

end module tuvx_cross_section_foo

The constructor function is reponsible for initializing new instances of your cross section subclass. First, you allocate the pointer to be returned as your new type (cross_section_foo_t in this example). Then you initialize its data members. If you just want to use the default initialization of the base class, you can call the base_constructor() function as shown above. You can alternatively initialize data members of the base class (cross_section_parms(:)) directly in this function or add data members to your subclass and initialize them here (see src/cross_sections/o3_tint.F90 for an example).

The calculate() function overrides the base-class calculate() function and will be called when a user calls the calculate() type-bound procedure on an instance of your new subclass. You can access grid and profile data from the “warehouse” objects passed in as function arguments, and any data in the base-class data members or in data members you’ve added to your subclass to perform your calculations. See the files in src/cross_sections/ for examples of how to access this data in the calculate() function.

Add subclass module to build scripts#

To include your new class in the build, edit the src/cross_sections/CMakeLists.txt file and add your file name to the list saved as SRC. Files are in alphabetical order.

################################################################################
# Cross section source

set(SRC acetone-ch3co_ch3.F90
        bro-br_o.F90
        ccl4.F90
        cfc-11.F90
        chbr3.F90
        chcl3.F90
        ch3ono2-ch3o_no2.F90
        ch2o.F90
        cl2-cl_cl.F90
        clono2.F90
        foo.F90
        h2o2-oh_oh.F90
        hcfc.F90
        hno3-oh_no2.F90
        hobr-oh_br.F90
        n2o-n2_o1d.F90
        n2o5-no2_no3.F90
        nitroxy_acetone.F90
        nitroxy_ethanol.F90
        no2_tint.F90
        o3_tint.F90
        oclo.F90
        rono2.F90
        t_butyl_nitrate.F90
        tint.F90
        rayliegh.F90
        )

list(TRANSFORM SRC PREPEND "${CMAKE_CURRENT_SOURCE_DIR}/")
set(CROSS_SECTION_SRC ${SRC} PARENT_SCOPE)

################################################################################

Add subclass to factory function#

In order to use your new subclass, you will need to add it to the tuvx_cross_section_factory module in src/cross_section_factory.F90. First, use-associate your new class at the module level:

use tuvx_cross_section_foo,            only : cross_section_foo_t

Then, inside the cross_section_builder() function, add these lines to the select case block:

case( 'foo' )
  new_cross_section => cross_section_foo_t( config, grid_warehouse,          &
                                            profile_warehouse )

Now, when you add a cross section of type foo to the configuration data, an instance of your new subclass will be created.

MPI functions#

If your new class includes custom data members, you will have to add MPI functions. See MPI Functions for more details.

Create unit test#

The last step to adding a cross section is to create a unit test. This will ensure that your calculations are doing what you intended. It will also serve as an example for how users can configure and use your new subclass.

See Test Creation for more details.

Dose Rates#

Dose rates apply a spectral weight to the radiation field at each interface on the vertical grid. The configuration for a dose rate is:

{
  "weights": { ... }
}

The value of weights defines the spectral weight used to calculate the dose rate. The standard spectral weight configuration is described here.

If a new dose rate requires an algorithm for calculating the spectral weight that TUV-x does not currently support, a new spectral weight algorithm can be introduced in four steps:

Create subclass module#

First, choose a unique name for your spectral weight algorithm. Ideally, this name will describe the algorithm, rather than the specific dose rate you are applying it to.

Pay special attention to the naming of files, modules, types, and functions in these instructions.

Create a file to hold your new subclass module in src/spectral_weights/ named foo.F90. The general layout of the module will be (comments have been omitted in this example, but should be included in an actual module):

! Copyright (C) 2020 National Center for Atmospheric Research
! SPDX-License-Identifier: Apache-2.0
!
module tuvx_spectral_weight_foo

  use tuvx_spectral_weight,            only : spectral_weight_t

  implicit none

  private
  public :: spectral_weight_foo_t

  type, extends(spectral_weight_t) :: spectral_weight_foo_t
  contains
    procedure :: calculate
  end type spectral_weight_t

  interface spectral_weight_t
    module procedure :: constructor
  end interface spectral_weight_t

contains

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

  function constructor( config, grid_warehouse, profile_warehouse )           &
      result ( this )

    use musica_assert,                 only : assert_msg
    use musica_config,                 only : config_t
    use musica_string,                 only : string_t
    use tuvx_grid_warehouse,           only : grid_warehouse_t
    use tuvx_profile_warehouse,        only : profile_warehouse_t
    use tuvx_spectral_weight,          only : base_constructor

    class(spectral_weight_t),  pointer       :: this
    type(config_t),            intent(inout) :: config
    type(grid_warehouse_t),    intent(inout) :: grid_warehouse
    type(profile_warehouse_t), intent(inout) :: profile_warehouse

    type(string_t) :: required_keys(1), optional_keys(1)

    ! This block of code ensures that the configuration keys are valid for
    ! your class. These can be modified to fit your needs. The first
    ! argument to assert_msg() should be a unique integer code for this error.
    required_keys(1) = "type"
    optional_keys(1) = "name"
    call assert_msg( 407417332,                                               &
                     config%validate( required_keys, optional_keys ),         &
                     "Bad configuration data format for "//                   &
                     "foo spectral weight." )

    allocate( spectral_weight_foo_t :: this )

    ! You can call the base_constructor function to load data from NetCDF
    ! files into the `spectral_weight_parms(:)` data member according to the
    ! standard base class logic. Alternatively, you can perform custom
    ! initialization of the subclass object here.
    call base_constructor( this, config, grid_warehouse, profile_warehouse )

  end function constructor

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

  subroutine calculate( this, grid_warehouse, profile_warehouse )             &
      result( spectral_weight )

    use musica_constants,              only : dk => musica_dk
    use tuvx_grid_warehouse,           only : grid_warehouse_t
    use tuvx_profile_warehouse,        only : profile_warehouse_t

    class(spectral_weight_foo_t),  intent(in)    :: this
    type(grid_warehouse_t),        intent(inout) :: grid_warehouse
    type(profile_warehouse_t),     intent(inout) :: profile_warehouse
    real(kind=dk), allocatable                   :: spectral_weight(:)

    ! do your calculations here

  end subroutine calculate

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

end module tuvx_spectral_weight_foo

The constructor function is reponsible for initializing new instances of your spectral weight subclass. First, you allocate the pointer to be returned as your new type (spectral_weight_foo_t in this example). Then you initialize its data members. If you just want to use the default initialization of the base class, you can call the base_constructor() function as shown above. You can alternatively initialize data members of the base class (spectral_weight_parms(:)) directly in this function or add data members to your subclass and initialize them here.

The calculate() function overrides the base-class calculate() function and will be called when a user calls the calculate() type-bound procedure on an instance of your new subclass. You can access grid and profile data from the “warehouse” objects passed in as function arguments, and any data in the base-class data members or in data members you’ve added to your subclass to perform your calculations. See the files in src/spectral_weights/ for examples of how to access this data in the calculate() function.

Add subclass module to build scripts#

To include your new class in the build, edit the src/spectral_weights/CMakeLists.txt file and add your file name to the list saved to SRC. Files are listed in alphabetical order.

################################################################################
# Spectral weight source

set(SRC notch_filter.F90
        gaussian_filter.F90
        eppley.F90
        par.F90
        exp_decay.F90
        foo.F90
        scup_mice.F90
        standard_human_erythema.F90
        UV_Index.F90
        phytoplankton_boucher.F90
        plant_damage.F90
        plant_damage_flint_caldwell.F90
        plant_damage_flint_caldwell_ext.F90
        )

list(TRANSFORM SRC PREPEND "${CMAKE_CURRENT_SOURCE_DIR}/")
set(SPECTRAL_WGHT_SRC ${SRC} PARENT_SCOPE)

################################################################################

Add subclass to factory#

In order to use your new subclass, you will need to add it to the tuvx_spectral_weight_factory module in src/spectral_weight_factory.F90. First use-associate your new class at the module level:

use tuvx_spectral_weight_foo,          only : spectral_weight_foo_t

Then, inside the spectral_weight_builder() function, add these lines to the select case block:

case( 'foo' )
  new_spectral_weight => spectral_weight_foo_t( config, grid_warehouse,       &
                                                profile_warehouse )

Now, when you add a spectral weight of type foo to the configuration data, an instance of your new subclass will be created.

MPI functions#

If your new class includes custom data members, you will have to add MPI functions. See MPI Functions for more details.

Create unit test#

The last step to adding a spectral weight is to create a unit test. This will ensure that your calculations are doing what you intended. It will also serve as an example for how users can configure and use your new subclass.

See Test Creation for more details.

Quantum Yields#

The base functionality for quantum yield calculations is described in src/quantum_yield.F90. The base quantum yield type quantum_yield_t defined in this module includes a constructor that reads a set of NetCDF files specified in the configuration JSON object as an array of file paths with the key netcdf files if present, or can set the value of the quantum yield to a constant when the constant value key is present and set to a real number.

Here is an example configuration for a quantum yield:

{
  "type": "base",
  "constant value": 1.0
}

Data from each NetCDF file will be loaded into an element of the quantum_yield_parms data member. If a NetCDF variable named quantum_yield_parameters is present, it will be used to populate the array(:,:) data member of the quantum_yield_parms_t object. This first dimension of the array is wavelength, and will be interpolated to the native TUV-x wavelength grid if this differs from the wavelength grid in the netcdf file (named wavelength). The second dimension is used to accomodate multiple wavelength-resolved parameters for quantum yield calculations.

If a NetCDF variable named temperature is present, it will be used to populate the temperature(:) data member of the quantum_yield_parms_t object.

The calculation of quantum yields is done by calling the calculate() type-bound procedure on a quantum_yield_t object.

The base-class calculation of quantum yields returns the wavelength-interpolated first parameter (array(:,1)) from the first NetCDF file (quantum_yield_parms(1)) specified in the configuration data.

Quantum yield subclasses are located in the src/quantum_yields/ folder. These each provide unique algorithms for calculating quantum yields.

Before adding a new quantum yield class, first check to make sure there is not an existing class that can be configured to accomodate your needs. If you find that an existing quantum yield subclass could be used by moving one or more hard-coded parameters to the configuration data, this is preferable to adding a new subclass.

If you determine that a new quantum yield subclass is needed, this can be done in four steps:

Create subclass module#

First, choose a unique name for your quantum yield calculation. Ideally, this name will describe the algorithm, rather than the specific photolysis reaction you are applying it to. However, many subclasses currently in TUV-x are named for specific photolysis reactions. For this example, we will use the name foo for our quantum yield algorithm.

Pay special attention to naming of files, modules, types, and functions in these instructions.

Create a file to hold your new subclass module in src/quantum_yields/ named foo.F90. The general layout of the module will be (comments have been omitted for this example, but should be included in an actual module):

! Copyright (C) 2020 National Center for Atmospheric Research
! SPDX-License-Identifier: Apache-2.0
!
module tuvx_quantum_yield_foo

  use tuvx_quantum_yield,              only : quantum_yield_t

  implicit none
  private

  public :: quantum_yield_foo_t

  type, extends(quantum_yield_t) :: quantum_yield_foo_t
  contains
    procedure :: calculate
  end type quantum_yield_foo_t

  interface quantum_yield_foo_t
    module procedure constructor
  end interface

contains

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

  function constructor( config, grid_warehouse, profile_warehouse )           &
      result( this )

    use musica_assert,                 only : assert_msg
    use musica_config,                 only : config_t
    use musica_string,                 only : string_t
    use tuvx_grid_warehouse,           only : grid_warehouse_t
    use tuvx_profile_warehouse,        only : profile_warehouse_t
    use tuvx_quantum_yield,            only : base_constructor

    class(quantum_yield_t),    pointer       :: this
    type(config_t),            intent(inout) :: config
    type(grid_warehouse_t),    intent(inout) :: grid_warehouse
    type(profile_warehouse_t), intent(inout) :: profile_warehouse

    type(string_t) :: required_keys(1), optional_keys(1)

    ! This block of code ensures that the configuration keys are valid for
    ! your class. These can be modified to fit your needs. The first
    ! argument to assert_msg() should be a unique integer code for this error.
    required_keys(1) = "type"
    optional_keys(1) = "name"
    call assert_msg( 409635586,                                               &
                     config%validate( required_keys, optional_keys ),         &
                     "Bad configuration data format for "//                   &
                     "foo quantum yield." )

    allocate( quantum_yield_foo_t :: this )

    ! You can call the base_constructor function to load data from NetCDF
    ! files into the `quantum_yield_parms(:)` data member according to the
    ! standard base class logic. Alternatively, you can perform custom
    ! initialization of the subclass object here.
    call base_constructor( this, config, grid_warehouse, profile_warehouse )

  end function constructor

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

  function calculate( this, grid_warehouse, profile_warehouse )               &
      result( quantum_yield )

    use musica_constants,              only : dk => musica_dk
    use tuvx_grid_warehouse,           only : grid_warehouse_t
    use tuvx_profile_warehouse,        only : profile_warehouse_t

    class(quantum_yield_foo_t), intent(in)    :: this
    type(grid_warehouse_t),     intent(inout) :: grid_warehouse
    type(profile_warehouse_t),  intent(inout) :: profile_warehouse
    real(kind=dk), allocatable                :: quantum_yield(:,:)

    ! Do your calculations here

  end function calculate

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

end module tuvx_quantum_yield_foo

The constructor function is reponsible for initializing new instances of your quantum yield subclass. First, you allocate the pointer to be returned as your new type (quantum_yield_foo_t in this example). Then you initialize its data members. If you just want to use the default initialization of the base class, you can call the base_constructor() function as shown above. You can alternatively initialize data members of the base class (quantum_yield_parms(:)) directly in this function or add data members to your subclass and initialize them here (see src/quantum_yields/tint.F90 for an example).

The calculate() function overrides the base-class calculate() function and will be called when a user calls the calculate() type-bound procedure on an instance of your new subclass. You can access grid and profile data from the “warehouse” objects passed in as function arguments, and any data in the base-class data members or in data members you’ve added to your subclass to perform your calculations. See the files in src/quantum_yields/ for examples of how to access this data in the calculate() function.

Add subclass module to build scripts#

To include your new class in the build, edit the src/quantum_yields/CMakeLists.txt file and add your file name to the list saved to SRC. Files are listed in alphabetical order.

set(SRC acetone-ch3co_ch3.F90
     c2h5cho.F90
     ch2chcho.F90
     ch2o.F90
     ch3cho-ch3_hco.F90
     ch3coch2ch3-ch3co_ch2ch3.F90
     ch3cocho.F90
     clo-cl_o1d.F90
     clo-cl_o3p.F90
     clono2-clo_no2.F90
     clono2-cl_no3.F90
     foo.F90
     ho2-oh_o.F90
     mvk.F90
     no2_tint.F90
     no3_aq.F90
     o3-o2_o1d.F90
     o3-o2_o3p.F90
     tint.F90
     )

Add subclass to factory function#

In order to use your new subclass, you will need to add it to the tuvx_quantum_yield_factory module in src/quantum_yield_factory.F90. First use-associate your new class at the module level:

use tuvx_quantum_yield_foo,            only : quantum_yield_foo_t

Then, inside the quantum_yield_builder() function, add these lines to the select case block:

case( 'foo' )
  quantum_yield => quantum_yield_foo_t( config, grid_warehouse,              &
                                        profile_warehouse )

Now, when you add a quantum yield of type foo to the configuration data, an instance of your new subclass will be created.

MPI functions#

If your new class includes custom data members, you will have to add MPI functions. See MPI Functions for more details.

Create unit test#

The last step to adding a quantum yield is to create a unit test. This will ensure that your calculations are doing what you intended. It will also serve as an example for how users can configure and use your new subclass.

See Test Creation for more details.

Radiators#

Radiators are atmospheric constituents that affect the calculation of the radiative field. The configuration for a standard radiator is:

{
  "name": "foo",
  "type": "base",
  "cross section": "foo",
  "vertical profile": "foo",
  "vertical profile units": "molecule cm-3"
}

A description of the components of the radiator configuration are provided here.

Most radiators can use the standard radiator configuration. If a new algorithm for calculating the optical properties of radiators is required, a new radiator subclass can be introduced in four steps:

Create subclass module#

First, choose a unique name for your radiator algorithm. Ideally, this name will describe the algorithm, rather than the specific atmospheric constituent you are applying it to. For this example, we will use the name foo for our radiator algorithm.

Pay special attention to naming of files, modules, types, and functions in these instructions.

Create a file to hold your new subclass module in src/radiators/ named foo.F90. The general layout of the module will be (comments have been omitted for this example, but should be included in an actual module):

! Copyright (C) 2020 National Center for Atmospheric Research
! SPDX-License-Identifier: Apache-2.0
!
module tuvx_radiator_foo

  use tuvx_radiator,                   only : radiator_t

  implicit none

  private
  public :: radiator_foo_t

  type, extends(radiator_t) :: radiator_foo_t
  contains
    procedure :: update_state
  end type radiator_foo_t

  interface radiator_foo_t
    module procedure :: constructor
  end interface radiator_foo_t

contains

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

  function constructor( config, grid_warehouse ) result( this )

    use musica_assert,                 only : assert_msg
    use musica_config,                 only : config_t
    use musica_string,                 only : string_t
    use tuvx_grid_warehouse,           only : grid_warehouse_t
    use tuvx_radiator,                 only : base_constructor

    class(radiator_t),      pointer       :: this
    type(config_t),         intent(inout) :: config
    type(grid_warehouse_t), intent(inout) :: grid_warehouse

    type(string_t) :: required_keys(1), optional_keys(1)

    ! This block of code ensures that the configuration keys are valid for
    ! your class. These can be modified to fit your needs. The first
    ! argument to assert_msg() should be a unique integer code for this error.
    required_keys(1) = "type"
    optional_keys(1) = "name"
    call assert_msg( 302604745,                                               &
                     config%validate( required_keys, optional_keys ),         &
                     "Bad configuration data format for "//                   &
                     "foo radiator." )

    allocate( radiator_foo_t :: this )

    ! You can call the base_constructor function to load data data members
    ! with configuration data available from the standard radiator class.
    ! Alternatively, you can perform custom initialization of the subclass
    ! object here.
    call base_constructor( this, config, grid_warehouse )

  end function constructor

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

  subroutine update_state( this, grid_warehouse, profile_warehouse,           &
      cross_section_warehouse )

    use tuvx_cross_section_warehouse,  only : cross_section_warehouse_t
    use tuvx_grid_warehouse,           only : grid_warehouse_t
    use tuvx_profile_warehouse,        only : profile_warehouse_t

    class(radiator_foo_t),           intent(inout) :: this
    type(grid_warehouse_t),          intent(inout) :: grid_warehouse
    type(profile_warehouse_t),       intent(inout) :: profile_warehouse
    type(cross_section_warehouse_t), intent(inout) :: cross_section_warehouse

    ! Calculate optical properties (layer optical depth, layer single
    ! scattering albedo, and layer asymmetry factor) and load them into
    ! this%state_

  end subroutine update_state

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

end module tuvx_radiator_foo

The constructor() function is responsible for initializing new instances of your radiator subclass. First, you allocate the pointer to be returned as your new type (radiator_foo_t in this example). Then, you initialize its data members. If you want to use the default initialization of the base class, you can call the base_constructor() function as shown above. You can alternatively initialize data members of the base class directly in this function or add data members to your subclass and initialize them here.

The update_state() function overrides the base-class update_state() function and will be called when a user calls the update_state() type-bound procedure on an instance of your new subclass. You can access grid, profile, and cross section data from the “warehouse” objects passed in as function arguments, and any data in the base-class data members or in data members you’ve added to your subclass to perform your calculations. See the files in src/radiators/ for examples of how to access this data in the update_state() function.

Add subclass module to build scripts#

To include your new class in the build, edit the src/radiators/CMakeLists.txt file and add your file name to the list save to SRC. Files are listed in alphabetical order.

################################################################################
# Radiator transfer source

set(SRC aerosol.F90
        foo.F90
        )

list(TRANSFORM SRC PREPEND "${CMAKE_CURRENT_SOURCE_DIR}/")
set(RADIATOR_SRC ${SRC} PARENT_SCOPE)

################################################################################

Add subclass to factory#

In order to use your new subclass, you will need to add it to the tuvx_radiator_factory module in src/radiator_factory.F90. First, use-associate your new class at the module level:

use tuvx_radiator_foo,                 only : radiator_foo_t

Then, inside the radiator_builder() function, add these lines to the select case block:

case( 'foo' )
  new_radiator => radiator_foo_t( config, grid_warehouse )

Now, when you add a radiator of type foo to the configuration data, an instance of your new subclass will be created.

You must also add lines to the functions for getting a type by name and allocating a variable by type name. Inside the radiator_type_name() function, add these lines to the select type block:

type is( radiator_foo_t )
  name = "radiator_foo_t"

Then, inside the radiator_allocate() function, add these lines to the select case block:

case( 'radiator_foo_t' )
  allocate( radiator_foo_t :: radiator )

These two functions allow your type to be passed among MPI processes in an HPC environment.

MPI functions#

If your new class includes custom data members, you will have to add MPI functions. See MPI Functions for more details.

Create unit test#

The last step to adding a radiator is to create a unit test. This will ensure that your calculations are doing what you intended. It will also serve as an example for how users can configure and use your new subclass.

See Test Creation for more details.

MPI Functions#

If you are extending one of the classes described in this section, and your new class contains its own data members (beyond what are defined in the base class), you will have to include three MPI functions in your new module. These will allow instances of your class to be passed via MPI.

Note: You do not need to add or modify code to call these functions. As they override base-class functions, the calling functions will use them without modification.

First, the pack_size( ), mpi_pack( ), and mpi_unpack( ) functions must be included in your type definition:

type, extends(base_class_t) :: foo_t
  integer :: foos_ ! a data member specific to your class
contains
  ...
  procedure :: pack_size
  procedure :: mpi_pack
  procedure :: mpi_unpack
end type foo_t

The first of these functions returns the size of an MPI buffer that would be required to hold the data members of your type. Because you will be overriding the base class pack_size() function, you must include the size required to hold both your specific data members and the base class data members (whether you need them or not).

This first function for the foo_t example is as follows:

integer function pack_size( this, comm )

  use musica_mpi,                    only : musica_mpi_pack_size

  class(foo_t), intent(in) :: this ! object to be packed
  integer,      intent(in) :: comm ! MPI communicator

#ifdef MUSICA_USE_MPI
  pack_size = this%base_class_t%pack_size( comm ) +                         &
              musica_mpi_pack_size( this%this%foos_, comm )
#else
  pack_size = this%cross_section_t%pack_size( comm )
#endif

end function pack_size

The C preprocessor flags (#ifdef, #else, and #endif) are used here to determine whether MPI support has been compiled in or not. The first argument in the assignment of pack_size is the size required to pack the data members of the base class (this must always be included). The musica_mpi_pack_size() function can be used to get the pack size of many primitive Fortran data types and allocatable arrays (see the musica core library documentation for more details).

The second MPI function that must be added packs an instance of your new class onto a character buffer so that it can be passed to other MPI processes:

subroutine mpi_pack( this, buffer, position, comm )

  use musica_assert,                 only : assert
  use musica_mpi,                    only : musica_mpi_pack

  class(foo_t), intent(in)    :: this      ! object to be packed
  character,    intent(inout) :: buffer(:) ! memory buffer
  integer,      intent(inout) :: position  ! current buffer position
  integer,      intent(in)    :: comm      ! MPI communicator

#ifdef MUSICA_USE_MPI
  integer :: prev_pos

  prev_pos = position
  call this%base_class_t%mpi_pack( buffer, position, comm )
  call musica_mpi_pack( buffer, position, this%foos_, comm )
  call assert( 582324821, position - prev_pos <= this%pack_size( comm ) )
#endif

end subroutine mpi_pack

The call to this%base_class_t%mpi_pack( ) packs the data members of the base class onto the character buffer, and is required. Similar to the pack_size( ) function, this subroutine makes use of the generic musica_mpi_pack( ) function for packing primitive Fortran data types onto a character buffer (see the musica core library documentation for more details). The assert( ) call helps with debugging MPI errors and ensures that the data you packed fits in the pack size from the pack_size( ) function.

The final MPI function that must be added unpacks an instance of your new class from a character buffer:

subroutine mpi_unpack( this, buffer, position, comm )

  use musica_assert,                 only : assert
  use musica_mpi,                    only : musica_mpi_unpack

  class(foo_t), intent(out)   :: this      ! object to be unpacked
  character,    intent(inout) :: buffer(:) ! memory buffer
  integer,      intent(inout) :: position  ! current buffer position
  integer,      intent(in)    :: comm      ! MPI communicator

#ifdef MUSICA_USE_MPI
  integer :: prev_pos

  prev_pos = position
  call this%base_class_t%mpi_unpack( buffer, position, comm )
  call musica_mpi_unpack( buffer, position, this%foos_, comm )
  call assert( 560718944, position - prev_pos <= this%pack_size( comm ) )
#endif

end subroutine mpi_unpack

The call to this%base_class_t%mpi_unpack( ) unpacks the data members of the base class from the character buffer, and is required. Similar to the pack_size( ) function, this subroutine makes use of the generic musica_mpi_unpack( ) function for unpacking primitive Fortran data types from a character buffer (see the musica core library documentation for more details). The assert( ) call helps with debugging MPI errors and ensures that the data you packed fits in the pack size from the pack_size( ) function.

Test Creation#

Standard Test Program#

Unit tests are required for all new code contributions. Source code for new unit tests should be added to the test/unit/ folder or one of its sub-folders depending on the module being tested. Unit tests are typically Fortran programs that are linked to the tuv-x library and test the components of a single Fortran module in the src/ tree.

An example of a unit test for the fictitous foo module is shown below.

program test_foo

  implicit none

  call test_foo_t( )

contains

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

  subroutine test_foo_t( )
    ! Tests the foo_t type

    use musica_assert,              only : assert
    use tuvx_foo,                   only : foo_t

    type(foo_t) :: my_foo

    call assert( 501352581, my_foo%do_bar( ) .eq. 12.5 )
    call assert( 503258115, my_foo%do_baz( ) .eq. "qux" )

  end subroutine test_foo_t

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

end program test_foo

The musica_assert module contains a number of functions that can be useful in unit tests.

Test Program with MPI#

If your new class requires the MPI functions pack_size( ), mpi_pack( ), and mpi_unpack( ), these should be tested as well. The approach used in most TUV-x unit tests is to create the object to be tested on the primary process, pass it to all other MPI processes, and test the object on all MPI processes. An example for the fictitous grid_foo_t module follows.

program test_grid_foo

  use musica_mpi,                      only : musica_mpi_init,                &
                                              musica_mpi_finalize
  implicit none

  call musica_mpi_init( )
  call test_grid_foo_t( )
  call musica_mpi_finalize( )

contains

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

  subroutine test_grid_foo_t( )
    ! Test the grid_foo_t type that extends the grid_t type

    use musica_assert,                 only : assert
    use musica_mpi
    use musica_string,                 only : string_t
    use tuvx_grid_foo,                 only : grid_foo_t
    use tuvx_grid_factory,             only : grid_type_name, grid_allocate

    class(grid_t), pointer :: my_grid
    character, allocatable :: buffer(:)
    integer :: pos, pack_size
    type(string_t) :: type_name
    integer, parameter :: comm = MPI_COMM_WORLD

    ! Create the grid on the primary process
    if( musica_mpi_rank( comm ) == 0 ) then
      my_grid => grid_foo_t( )
      type_name = grid_type_name( my_grid )
      pack_size = type_name%pack_size( comm ) + my_grid%pack_size( comm )
      allocate( buffer( pack_size ) )
      pos = 0
      call type_name%mpi_pack( buffer, pos, comm )
      call my_grid%mpi_pack(   buffer, pos, comm )
      call assert( 582976374, pos <= pack_size )
    end if

    ! Broadcast the buffer to all other MPI processes
    call musica_mpi_bcast( pack_size, comm )
    if( musica_mpi_rank( comm ) .ne. 0 ) allocate( buffer( pack_size ) )
    call musica_mpi_bcast( buffer, comm )

    ! Unpack the buffer on all other MPI processes
    if( musica_mpi_rank( comm ) .ne. 0 ) then
      pos = 0
      call type_name%unpack( buffer, pos, comm )
      my_grid => grid_allocate( type_name )
      call my_grid%mpi_unpack( buffer, pos, comm )
      call assert( 127437743, pos <= pack_size )
    end if
    deallocate( buffer )

    ! test the object on all processes
    call assert( 501352581, my_grid%do_bar( ) .eq. 12.5 )
    call assert( 503258115, my_grid%do_baz( ) .eq. "qux" )

    deallocate( my_grid )

  end subroutine test_grid_foo_t

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

end program test_grid_foo

Similar patters apply to profiles, cross sections, quantum yields, and radiators. Note that this test should pass whether MPI support is compiled in or not. When MPI support is not compiled in, the pack functions do nothing and all tests are performed on the primary (only) process.

When MPI support for TUV-x is built in, as described in MPI Support, when the tests are run, they will be run with 2 or more MPI processes and your message passing functions will be tested when, from the build folder, you run:

make test

Update to Build Script#

For both the standard test program or the test program with MPI support, you will need to modify the CMakeLists.txt file in the folder where you saved your test source code (for this example we assume the above file is named test_foo.F90) to include your new source in the build, and your test in the test suite. An updated CMakeLists.txt file for the foo test is shown below.

################################################################################
# Test utilities

include(test_util)

################################################################################
# Photo-decomp tests

create_standard_test(NAME some_existing_test SOURCES test_bar.F90)
create_standard_test(NAME foo SOURCES test_foo.F90)

################################################################################

The create_standard_test() CMake function adds your new executable to the build, links it to the tuv-x library, and includes the test as well as a memory check of your test to the testing suite. The function is defined in cmake-modules/test_util.cmake, but can generally used as shown above.

If your test needs access to data files, you can place these in the test/data/ folder. By default, your test executable will be run in the build folder and can access data files you place in this folder using a relative path: test/data/my_foo_data.txt.

On this page
Show Source