Dust Process Documentation¶

Overview¶

Dust emission process for mineral dust aerosols from arid and semi-arid surfaces

Author: Generated by CATChem Process Generator Version: 1.0

Features¶

Available Schemes¶

Fengsha: Fengsha implementation
Ginoux: Ginoux implementation

Modern Architecture¶

This process follows the modern CATChem architecture where: - Process interface handles all state management, looping, and diagnostics - Scheme modules are pure science kernels operating on simple arrays - Automatic diagnostic registration and validation - Configurable parameters and error handling

Usage¶

Initialization¶

use ProcessInterface_Mod, only : ProcessInterface
use ProcessDustCreator_Mod, only : create_dust_process

class(ProcessInterface), allocatable :: process
type(StateContainerType) :: container
integer :: rc

! Create the process
call create_dust_process(process, rc)

! Initialize the process with container
call process%init(container, rc)

Running the Process¶

! Run the process
call process%run(container, rc)

Finalization¶

! Clean up
call process%finalize(rc)

Configuration¶

Basic Configuration¶

processes:
  - name: dust
    enabled: true
    scheme: Fengsha  # Available: Fengsha, Ginoux
    parameters:
      # Fengsha scheme parameters
      Fengsha:
        alpha_scale: 1.0  # Alpha scaling factor for Fengsha dust emissions
        beta_scale: 1.0  # Beta scaling factor for Fengsha dust emissions
        moist_opt: 1  # Soil moisture option (1=Fecan, 2=Shao)
        drag_opt: 1  # Drag partition option (1=MB95, 2=custom)
        horiz_flux_opt: 1  # Horizontal flux option (1=Draxler, 2=Kawamura)
      # Ginoux scheme parameters
      Ginoux:
        source_function_scale: 1.0  # Source function scaling factor for Ginoux scheme
        threshold_velocity_scale: 1.0  # Threshold velocity scaling factor
        clay_factor: 0.1  # Clay fraction effect factor
    diagnostics:
      - process_rate
      - species_tendency

Advanced Configuration¶

processes:
  - name: dust
    enabled: true
    scheme: Fengsha
    timestep: 60.0  # seconds
    parameters:
      # Add process-specific parameters
    diagnostics:
      output_frequency: hourly
      include_metadata: true
      compression: true
    validation:
      check_mass_conservation: true
      tolerance: 1.0e-12
    error_handling:
      on_failure: "continue"
      log_level: "warning"

Required Dependencies¶

This process requires the following components:

Meteorological Fields¶

U10M - U10m
V10M - V10m
USTAR - Ustar
PS - Ps
GWETTOP - Gwettop
FRSNO - Frsno
FRVEG - Frveg

Surface Data¶

CLAYFRAC - Clayfrac
SANDFRAC - Sandfrac
DLUSE - Dluse
DSOILTYPE - Dsoiltype

Species Categories¶

is_dust - Species with is dust attribute

Implementation Guide¶

Step 1: Add Physics Implementation¶

Edit the scheme files to implement the actual physics as pure science kernels:

! In schemes/DustFengshaScheme_Mod.F90
subroutine Fengsha_scheme_run( &
    ! Input meteorological fields
    dt, temperature, pressure, humidity, wind_speed, &
    ! Input species concentrations and surface data
    species_in, surface_data, &
    ! Output tendencies
    species_tendencies, &
    ! Status
    rc)

  use, intrinsic :: iso_fortran_env, only: real64
  implicit none

  ! Arguments
  real(real64), intent(in) :: dt                        ! Time step [s]
  real(real64), intent(in) :: temperature(:)            ! Temperature [K]
  real(real64), intent(in) :: pressure(:)               ! Pressure [Pa]
  real(real64), intent(in) :: humidity(:)               ! Humidity [kg/kg]
  real(real64), intent(in) :: wind_speed(:)             ! Wind speed [m/s]
  real(real64), intent(in) :: species_in(:,:)           ! Species concentrations
  real(real64), intent(in) :: surface_data(:)           ! Surface data
  real(real64), intent(out) :: species_tendencies(:,:)  ! Species tendencies
  integer, intent(out) :: rc

  ! Local variables
  integer :: k, n_levels

  rc = 0  ! Success
  n_levels = size(temperature)

  ! Initialize tendencies
  species_tendencies = 0.0_real64

  ! Implement your calculations here...
  do k = 1, n_levels
    ! Calculate tendencies for this level
    ! species_tendencies(k, :) = calculate_tendencies(...)
  end do

end subroutine

Step 2: Configure Process Parameters¶

Parameters are handled automatically through the configuration system:

processes:
  - name: dust
    parameters:
      example_param: 1.0
      another_param: 2.5
      enable_feature: true

The process interface will automatically extract and validate these parameters.

Step 3: Add Custom Diagnostics¶

Additional diagnostics are registered automatically based on configuration:

processes:
  - name: dust
    diagnostics:
      - name: "custom_diagnostic"
        description: "Custom process diagnostic"
        units: "custom_units"
        frequency: "every_timestep"

Process Structure¶

src/process/dust/
├── ProcessDustInterface_Mod.F90  # Main process interface
├── ProcessDustCreator_Mod.F90    # Process creator
├── CMakeLists.txt                               # Build configuration
└── schemes/                                     # Scheme implementations
    ├── FengshaScheme_Mod.F90              # Pure science kernel
    ├── GinouxScheme_Mod.F90              # Pure science kernel

Testing¶

Unit Tests¶

Unit tests are available in:

tests/test_dust_process.F90

Run tests with:

cd build
ctest -R dust -V

Adding Custom Tests¶

Extend the generated tests with specific test cases:

subroutine test_dust_physics()
  ! Test the actual physics implementation
  class(ProcessInterface), allocatable :: process
  type(StateContainerType) :: container

  ! Create and initialize process
  call create_dust_process(process, rc)
  call process%init(container, rc)

  ! Set up test conditions
  ! Run process
  call process%run(container, rc)

  ! Verify results
  call assert_approximately_equals(expected_value, actual_value, tolerance)
end subroutine

Architecture Features¶

This process includes the following modern features:

Automatic State Management: Process interface handles all state extraction and updates
Column-wise Processing: Optimized for vertical column operations
Diagnostic Integration: Automatic registration and update of diagnostic fields
Validation Support: Built-in state validation and error checking
Flexible Configuration: YAML-based parameter configuration
Pure Science Kernels: Scheme modules operate on simple arrays for maximum reusability

Performance Considerations¶

Column-wise processing for optimal cache performance
Minimal memory allocation through state container reuse
Optional diagnostic outputs to reduce overhead
Vectorized operations where possible in scheme modules

Troubleshooting¶

Common Issues¶

Initialization fails: Check that required meteorological fields and surface data are available
Physics not working: Verify scheme implementation in scheme modules
Configuration errors: Validate YAML syntax and parameter values
Test failures: Ensure test data matches expected formats

Debugging¶

Enable verbose logging:

logging:
  level: debug
  modules: [ProcessDustInterface_Mod]

References¶

CATChem Process Architecture Guide
Creating Custom Processes
Process Testing Guide
[State Container Guide../../../developer-guide/state-container.md)

Generated by CATChem Process Generator on 2025-07-06 22:04:18