(HOLD until #477) Abstract aerosol interface; bulk aerosols (BAM); radiative_aerosol and physical props infra; optics core code; pfUnit tests

[jimmielin]

Tag name (required for release branches):
Originator(s): @jimmielin coauthored with claude-opus-4.6

Description (include the issue title, and the keyword ['closes', 'fixes', 'resolves'] followed by the issue number):

• Port the aerosol optics infrastructure from CAM to CAM-SIMA. This includes:
  • the abstract aerosol interface (aerosol_properties, aerosol_state, aerosol_optics);
  • the radiative aerosol module (radiative_aerosol, radiative_aerosol_definitions), the CAM-SIMA equivalent of former rad_constituents;
  • aerosol instances management (aerosol_instances_mod);
  • aerosol physical properties reader (aerosol_physical_properties, formerly phys_prop)
  • all concrete optics implementations (insoluble, hygroscopic, hygro, hygrocoreshell, hygrowghtpct, refractive, volcrad).
  • The bulk aerosol model (BAM) concrete types (bulk_aerosol_properties, bulk_aerosol_state) are fully implemented;
  • modal and CARMA types are stubs (but their optics implementations are in.)
  • Copy of aerosol_optics_core which dispatches optics object creation based on opticstype parameter verbatim from CAM;
  • Implement aerosol_mmr_ccpp which retrieves aerosol mixing ratios from CCPP constituents (replacing CAM state and pbuf)
• Copy of table_interp_mod from CAM for table interpolation.
• Move nswbands and nlwbands to the radiation_namelist from atmos_phys
• "Front-port" @fvitt's fixes to bulk aerosol optics in https://github.com/ESCOMP/CAM/pulls/1500
• pfUnit tests for radiative_aerosol parsing; abstract aerosol interface (incl. BAM concrete implementation); aerosol optics was authored by claude-opus-4.6:
  Because there were many modules to test (while aerosol_physical_properties.F90, formerly phys_prop uses PIO input), Claude made the following test decisions for unit testing:

  the tests mock at the radiative_aerosol facade boundary — the single point where file I/O enters the aerosol module hierarchy. A configurable mock_radiative_aerosol
  module lets tests populate optics tables and aerosol metadata in-memory, while the real bulk_aerosol_properties, bulk_aerosol_state, and insoluble_aerosol_optics objects
  are exercised with full OOP dispatch.

  (the test cases are) organized in four tiers by dependency complexity.
  Tier 1 tests the pure interpolation functions in table_interp_mod (weights calculation, 1D/2D/4D interpolation, clamping behavior).
  Tier 2 tests the namelist parsing logic in radiative_aerosol_definitions — both parse_rad_specifier (bulk aerosol, gas, mode/bin specifiers, edge cases) and list_populate (populating aerosol/mode/gas lists from parsed data).
  Tier 3 tests the concrete BAM types bulk_aerosol_properties and bulk_aerosol_state, verifying construction, property queries (density, hygroscopicity, species type mapping), MMR retrieval, and derived quantities like dry volume.
  Tier 4 tests insoluble_aerosol_optics end-to-end, verifying SW optical properties (extinction, single-scatter albedo, asymmetry, absorption) and LW absorption against analytically expected values.

Describe any changes made to build system:

• Added src/aerosol to source include paths in cime_config/buildlib.
• Added test/unit/fortran/src/aerosol pfUnit test subdirectory with CMakeLists.txt.

Describe any changes made to the namelist:

• Add radiatively active aerosol namelist group (rad_aer_nl) with entries for mode_defs, bin_defs, rad_aer_climate (formerly rad_climate), and rad_aer_diag_1 through rad_aer_diag_10.
• Added nswbands (default 14) and nlwbands (default 16) to radiation_nl group (moved from RRTMGP atmos_phys)

List any changes to the defaults for the input datasets (e.g. boundary datasets): N/A

List all files eliminated and why: N/A

List all files added and what they do:

A       src/aerosol/aerosol_properties_mod.F90
  - abstract base class defining the aerosol configuration interface (bins, species, density, optics parameters).

A       src/aerosol/aerosol_state_mod.F90
  - abstract base class for time-varying aerosol state (mixing ratios, number concentrations).

A       src/aerosol/aerosol_optics_mod.F90
  - abstract base class defining the aerosol optics interface (sw_props, lw_props methods).

A       src/aerosol/aerosol_instances_mod.F90
  - factory/registry managing persistent aerosol properties and state objects across aerosol models and radiation lists.

A       src/aerosol/aerosol_mmr_ccpp.F90
  - mixing-ratio retrieval from CCPP constituents array; replaces CAM pbuf/state%q indexing.

A       src/aerosol/aerosol_optics_core.F90
  - dispatcher that creates concrete optics objects based on opticstype parameter.

A       src/aerosol/aerosol_physical_properties.F90
  - utility module reading aerosol optical property data from files (phys_prop); caches complex refractive indices.

A       src/aerosol/radiative_aerosol_definitions.F90
  - core definitions: mode/species/morphology types, parsing routines for aerosol namelist configuration.

A       src/aerosol/radiative_aerosol_definitions.meta
  - CCPP metadata for radiative_aerosol_definitions module variables.

A       src/aerosol/radiative_aerosol.F90
  - facade module providing rad_aer_* query routines; bridges constituents to optics.

A       src/aerosol/bulk_aerosol_properties_mod.F90
  - concrete aerosol_properties implementation for bulk aerosol model (BAM).

A       src/aerosol/bulk_aerosol_state_mod.F90
  - concrete aerosol_state implementation for BAM; stores CCPP constituents pointers.

A       src/aerosol/modal_aerosol_properties_mod.F90
  - stub aerosol_properties for modal aerosol (not yet implemented).

A       src/aerosol/modal_aerosol_state_mod.F90
  - stub aerosol_state for modal aerosol (not yet implemented).

A       src/aerosol/carma_aerosol_properties_mod.F90
  - stub aerosol_properties for CARMA sectional aerosol (not yet implemented).

A       src/aerosol/carma_aerosol_state_mod.F90
  - stub aerosol_state for CARMA sectional aerosol (not yet implemented).

A       src/aerosol/insoluble_aerosol_optics_mod.F90
  - concrete optics for non-hygroscopic aerosol (constant ext/SSA/asymmetry per band).

A       src/aerosol/hygro_aerosol_optics_mod.F90
  - concrete optics: SW-hygroscopic / LW-insoluble with RH-dependent tables.

A       src/aerosol/hygrocoreshell_aerosol_optics_mod.F90
  - concrete optics: core-shell morphology with core fraction, BC/dust fraction, kappa, and RH dimensions.

A       src/aerosol/hygroscopic_aerosol_optics_mod.F90
  - concrete optics: SW/LW hygroscopic with RH-dependent tables.

A       src/aerosol/hygrowghtpct_aerosol_optics_mod.F90
  - concrete optics: weight-percent-based hygroscopic (H2SO4/H2O solution).

A       src/aerosol/refractive_aerosol_optics_mod.F90
  - concrete optics: table-lookup using wet radius and complex refractive index with Chebyshev polynomials.

A       src/aerosol/volcrad_aerosol_optics_mod.F90
  - concrete optics: geometric mean radius parameterization for volcanic stratospheric aerosols.

A       src/utils/table_interp_mod.F90
  - copied from CAM
  - pure Fortran module for 1D/2D/4D table interpolation with weight calculation and edge clamping.

A       test/unit/fortran/src/aerosol/CMakeLists.txt
  - CMake build for 4-tier aerosol pfUnit test suite.

A       test/unit/fortran/src/aerosol/mock_radiative_aerosol.F90
  - configurable in-memory aerosol data facade for unit testing (replaces file I/O).

A       test/unit/fortran/src/aerosol/mock_aerosol_mmr_ccpp.F90
A       test/unit/fortran/src/aerosol/mock_aerosol_physical_properties.F90
A       test/unit/fortran/src/aerosol/mock_cam_abortutils.F90
A       test/unit/fortran/src/aerosol/mock_cam_logfile.F90
A       test/unit/fortran/src/aerosol/mock_physconst.F90
A       test/unit/fortran/src/aerosol/mock_shr_infnan_mod.F90
A       test/unit/fortran/src/aerosol/mock_shr_string_mod.F90
A       test/unit/fortran/src/aerosol/mock_spmd_utils.F90
A       test/unit/fortran/src/aerosol/shr_kind_mod.F90
  - mock/stub modules for unit testing without CESM infrastructure.

A       test/unit/fortran/src/aerosol/test_table_interp.pf
  - Tier 1: 9 tests for pure interpolation functions (weights, 1D/2D/4D, clamping).

A       test/unit/fortran/src/aerosol/test_parse_rad_specifier.pf
  - Tier 2: 7 tests for rad_specifier parsing (bulk/gas/mode/bin, whitespace, edge cases).

A       test/unit/fortran/src/aerosol/test_list_populate.pf
  - Tier 2: 3 tests for aerosol/mode/gas list population from parsed data.

A       test/unit/fortran/src/aerosol/test_bulk_aerosol_properties.pf
  - Tier 3: 6 tests for BAM properties (constructor, density, hygro, species type, model_is).

A       test/unit/fortran/src/aerosol/test_bulk_aerosol_state.pf
  - Tier 3: 4 tests for BAM state (constructor, MMR retrieval, dry volume, total bin MMR).

A       test/unit/fortran/src/aerosol/test_insoluble_aerosol_optics.pf
  - Tier 4: 2 end-to-end tests for SW (ext/SSA/asymmetry) and LW absorption optics.

List all existing files that have been modified, and describe the changes:
(Helpful git command: git diff --name-status development...<your_branch_name>)

M       cime_config/buildlib
  - add src/aerosol to source include paths.

M       cime_config/namelist_definition_cam.xml
  - add nswbands, nlwbands to radiation_nl.
  - add rad_aer_nl namelist group (mode_defs, bin_defs, rad_aer_climate, rad_aer_diag_1..10).

M       src/control/cam_comp.F90
  - add rad_aer_init_all() subroutine called after stepon_init to initialize
    aerosol optics infrastructure (rad_aer_init, aerosol_instances_init,
    wire CCPP constituents, mark radiative_aerosol_definitions vars as initialized).

M       src/control/runtime_opts.F90
  - add call to rad_aer_readnl() for radiative aerosol namelist reading.

M       src/data/registry.xml
  - add metadata_file reference to radiative_aerosol_definitions.meta.
 
M       src/physics/utils/radiation_namelist.F90
M       src/physics/utils/radiation_namelist.meta
  - move nswbands and nlwbands module variables from atmos_phys.

M       src/physics/utils/solar_parms_data.F90
  - change getfil() to cam_get_file() just because I saw it,
    this module has nothing to do with all the other changes.

M       test/unit/fortran/CMakeLists.txt
  - add aerosol test subdirectory.

If there are new failures (compared to the test/existing-test-failures.txt file),
have them OK'd by the gatekeeper, note them here, and add them to the file.
If there are baseline differences, include the test and the reason for the
diff. What is the nature of the change? Roundoff?

derecho/intel/aux_sima:

derecho/gnu/aux_sima:

derecho/nvhpc/aux_sima:

If this changes climate describe any run(s) done to evaluate the new
climate in enough detail that it(they) could be reproduced:

CAM-SIMA date used for the baseline comparison tests if different than latest: