Add optional ObsFcstAna NetCDF4 output with structured species metadata

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added optional NetCDF4 output mode for ObsFcstAna, including NetCDF metadata and runtime context. Changed namelist variable "out_ObsFcstAna" from logical to integer.
+
 ### Changed
 
 - Revised and cleaned up RESTART options:

GEOSlandassim_GridComp/GEOS_LandAssimGridComp.F90

@@ -98,14 +98,14 @@ module GEOS_LandAssimGridCompMod
   real    :: fcsterr_inflation_fac
   integer :: N_obs_param
   logical :: out_obslog
-  logical :: out_ObsFcstAna
+  integer :: out_ObsFcstAna
   logical :: out_smapL4SMaup
   integer :: N_obsbias_max
 
   integer,                 dimension(:), pointer     :: N_catl_vec,low_ind
   integer                                            :: N_catf
 
-  !reordered tile_coord_rf and mapping l2rf
+  ! reordered tile_coord_rf and mapping l2rf
   integer,                 dimension(:), pointer     :: l2rf, rf2l,rf2g, rf2f
   type(tile_coord_type),   dimension(:), pointer     :: tile_coord_rf => null()
 
@@ -1407,7 +1407,7 @@ subroutine Initialize(gc, import, export, clock, rc)
     call MPI_BCAST(fcsterr_inflation_fac, 1, MPI_REAL,           0,MPICOMM,mpierr)
     call MPI_BCAST(N_obs_param,           1, MPI_INTEGER,        0,MPICOMM,mpierr)
     call MPI_BCAST(out_obslog,            1, MPI_LOGICAL,        0,MPICOMM,mpierr)
-    call MPI_BCAST(out_ObsFcstAna,        1, MPI_LOGICAL,        0,MPICOMM,mpierr)
+    call MPI_BCAST(out_ObsFcstAna,        1, MPI_INTEGER,        0,MPICOMM,mpierr)
     call MPI_BCAST(out_smapL4SMaup,       1, MPI_LOGICAL,        0,MPICOMM,mpierr)
     call MPI_BCAST(N_obsbias_max,         1, MPI_INTEGER,        0,MPICOMM,mpierr)
 
@@ -1953,6 +1953,7 @@ subroutine RUN ( GC, IMPORT, EXPORT, CLOCK, RC )
             N_catl, tile_coord_l,                                        &
             N_catf, tile_coord_rf, tcinternal%pgrid_g,                   &
             N_catl_vec, low_ind, rf2l,                                   &
+            update_type, LandAssimDTstep,                                &
             obs_param,                                                   &
             met_force, lai,                                              &
             cat_param, cat_progn, mwRTM_param,                           &

GEOSlandassim_GridComp/clsm_ensupd_upd_routines.F90

@@ -235,7 +235,7 @@ subroutine read_ens_upd_inputs(               &
     type(obs_param_type), dimension(:), pointer :: obs_param     ! output
 
     logical,              intent(out)   :: out_obslog
-    logical,              intent(out)   :: out_ObsFcstAna
+    integer,              intent(out)   :: out_ObsFcstAna
     logical,              intent(out)   :: out_smapL4SMaup
 
     integer,              intent(out)   :: N_obsbias_max
@@ -272,6 +272,8 @@ subroutine read_ens_upd_inputs(               &
     character(len=400) :: err_msg
     character(len=  6) :: tmpstring6
     logical :: file_exists
+    integer :: ios
+    character(len=400) :: iomsg
 
     ! -----------------------------------------------------------------
 
@@ -300,8 +302,12 @@ subroutine read_ens_upd_inputs(               &
     if (logit) write (logunit,*)
     if (logit) write (logunit,'(400A)') 'reading *default* EnKF inputs from ' // trim(fname)
     if (logit) write (logunit,*)
-
-    read (10, nml=ens_upd_inputs)
+
+    read (10, nml=ens_upd_inputs, iostat=ios, iomsg=iomsg)
+    if (ios /= 0) then
+       err_msg = 'Error reading ens_upd_inputs.  NOTE: "out_ObsFcstAna" must be integer.  ' // trim(iomsg)
+       call ldas_abort(LDAS_GENERIC_ERROR, Iam, err_msg)
+    end if
 
     close(10,status='keep')
 
@@ -325,7 +331,13 @@ subroutine read_ens_upd_inputs(               &
        if (logit) write (logunit,'(400A)') 'reading *special* EnKF inputs from ' // trim(fname)
        if (logit) write (logunit,*)
 
-       read (10, nml=ens_upd_inputs)
+       read (10, nml=ens_upd_inputs, iostat=ios, iomsg=iomsg)
+
+       ! if read error, exit gracefully; hint at possible cause (out_ObsFcstAna changed from logical to integer, Apr 2026)
+       if (ios /= 0) then
+          err_msg = 'Error reading ens_upd_inputs.  NOTE: "out_ObsFcstAna" must be integer.  ' // trim(iomsg)
+          call ldas_abort(LDAS_GENERIC_ERROR, Iam, err_msg)
+       end if
 
        close(10,status='keep')
 
@@ -337,15 +349,63 @@ subroutine read_ens_upd_inputs(               &
     !
     ! none implemented so far (reichle, 19 Jul 2005)
 
+
+    ! -----------------------------------------------------------------
+
+    ! fill obs_param%fcstvarname and obs_param%fcstunits
+
+    do i=1,N_obs_species_nml
+
+       ! expect "fcstvarname" and "fcstunits" to be 'NULL'; they are not meant to be filled by the user in the config nml file
+
+       if (trim(obs_param_nml(i)%fcstvarname) /= 'NULL' .and. trim(obs_param_nml(i)%fcstvarname) /= 'null')     &
+            call ldas_abort(LDAS_GENERIC_ERROR, Iam, 'obs_param_nml%fcstvarname must be NULL on input')
+
+       if (trim(obs_param_nml(i)%fcstunits  ) /= 'NULL' .and. trim(obs_param_nml(i)%fcstunits  ) /= 'null')     &
+            call ldas_abort(LDAS_GENERIC_ERROR, Iam, 'obs_param_nml%fcstunits must be NULL on input')
+
+       ! IMPORTANT: Must maintain consistency in the mapping between obs and model variables 
+       !            that is encoded here with that in get_obs_pred().
+
+       select case (trim(obs_param_nml(i)%varname))
+
+       case ('sfmc', 'sfds')
+
+          ! NOTE: 'sfds' is scaled into volumetric units of sfmc
+
+          obs_param_nml(i)%fcstvarname = 'sfmc'
+          obs_param_nml(i)%fcstunits   = 'm3 m-3'
+
+       case ('rzmc', 'tsurf', 'FT', 'Tb', 'asnow', 'NULL')
+
+          obs_param_nml(i)%fcstvarname = obs_param_nml(i)%varname 
+          obs_param_nml(i)%fcstunits   = obs_param_nml(i)%units  
+
+       case default
+
+          call ldas_abort(LDAS_GENERIC_ERROR, Iam, 'unknown obs_param_nml%varname')
+
+       end select
+
+    end do
+
     ! -----------------------------------------------------------------
     !
     ! consistency checks etc
+
+    if (out_ObsFcstAna<0 .or. out_ObsFcstAna>3) then        
+       write(tmpstring6,'(I6)') out_ObsFcstAna
+       err_msg = 'Unknown integer value of "out_ObsFcstAna": "' // trim(tmpstring6) // '". Use 0=OFF, 1=BIN, 2=NC4, 3=BIN and NC4.'
+       call ldas_abort(LDAS_GENERIC_ERROR, Iam, err_msg)
+    end if
 
     if (update_type==0) then
        err_msg = 'executable was built for assimilation but update_type=0'
        call ldas_abort(LDAS_GENERIC_ERROR, Iam, err_msg)
     end if
 
+    ! obs bias init and checks
+
     N_obsbias_max = 0  ! initialize
 
     do i=1,N_obs_species_nml
@@ -1166,6 +1226,9 @@ subroutine get_obs_pred(                                       &
 
     do i=1,N_obs_param  
 
+       ! IMPORTANT: Must maintain consistency in the mapping between obs and model ("lH") variables 
+       !            that is encoded here with that in read_ens_upd_inputs().
+
        select case (trim(obs_param(i)%varname))
 
        case ('sfmc', 'sfds')