Audience: coding agents and developers working on the Moist gridded component (convection, cloud microphysics, aerosol activation).
Describes: the MAPL2 line, branch develop.
Verified against: GEOSgcm_GridComp @ c7d81d7c (2026-11-05; source files identical to 45e1f86f, the earlier base, which only differs by the added documents).
Placement: as in the GEOSgcm fixture (components.yaml @ 0f2e0fb; repository GEOSgcm_GridComp, mounted at src/Components/@GEOSgcm_GridComp): src/Components/@GEOSgcm_GridComp/GEOSagcm_GridComp/GEOSphysics_GridComp/GEOSmoist_GridComp.
Other fixtures (for example GEOSadas, GEOSldas) may place this repository elsewhere; paths inside this repository do not change.
Paths below are relative to GEOSagcm_GridComp/GEOSphysics_GridComp/GEOSmoist_GridComp/ unless they start with GEOSagcm_GridComp/ or src/ (the latter are relative to the GEOSgcm fixture).
Parent: Physics. Siblings: Turbulence, GWD, Surface. Repository overview: ../../../docs/ARCHITECTURE.md.
Moist computes every process that changes the phase of water: deep and shallow convection, large-scale (stratiform) condensation, cloud microphysics, precipitation and cloud fraction. It also transports "friendly" tracers (chemistry and aerosol species) through convection and activates aerosol into cloud droplets and ice crystals (GEOS_MoistGridComp.F90, header comment, Run).
The component is one driver (GEOS_MoistGridCompMod) plus one interface module per scheme. Schemes are chosen once, by resource keys, in SetServices.
- Parent is Physics, which adds Moist as a leaf child:
MOIST = MAPL_AddChild(GC, NAME='MOIST', SS=MoistSetServices, ...)(GEOSagcm_GridComp/GEOSphysics_GridComp/GEOS_PhysicsGridComp.F90, SetServices). - Moist has no children. The schemes are Fortran modules called directly, not gridded components (
GEOS_MoistGridComp.F90,use GEOS_*_InterfaceMod). CMakeLists.txtbuilds one shared library from all scheme sources, including ones that cannot be selected (NSSL, section 5.1), pluspyMoist/pyMoist/fortran/moist_workarounds.F90, and installs thepyMoistPython tree (CMakeLists.txt,srcs,install).
Registered with MAPL_GridCompSetEntryPoint (GEOS_MoistGridComp.F90, SetServices). There is one Run phase; Physics runs Moist once per Physics step.
- SetServices: reads the scheme keys (5.1), calls the
*_Setupof each selected scheme (internal specs and timers), declares imports, exports and timers, thenMAPL_GenericSetServices.- Microphysics
*_Setupis called first: a comment says binary restarts expectQfirst inmoist_internal_rst, so the firstMAPL_AddInternalSpecmust come from microphysics. - Which imports exist depends on
WSUB_OPTIONandUSE_NCLOUD_CLIM(select case (WSUB_OPTION)).
- Microphysics
- Initialize:
MAPL_GenericInitialize, then each selected scheme's*_Initialize(scheme resources, alarms), then the radar alarmDBZ_RunAlarm(GEOS_MoistGridComp.F90, Initialize). - Run: 3.1.
- Finalize:
GFDL_1M_Finalize,UW_Finalize,GF_Finalize(these matter only for the Python bridge), thenMAPL_GenericFinalize(GEOS_MoistGridComp.F90, FINALIZE).
The body is under if (ESMF_AlarmIsRinging(ALARM)), ALARM being the component's RUNALARM. Its interval is the MAPL_Generic resource DT:, default RUN_DT: (src/Shared/@MAPL/generic/MAPL_Generic.F90, handle_clock_and_main_alarm). When it rings:
- Prologue: surface type
SRF_TYPE; pressure, height, mass; lower-tropospheric stabilityLTSand estimated inversion strengthEIS; saved windsUMST0,VMST0; convective available potential energyCAPE, buoyancyBYNCY, and the diagnosed convective fractionCNV_FRC(RUN,MOIST_PROLOGUE). - Tracer collection:
CNV_Tracers_Init(TR)on the import bundleMTR(7). - Aerosol activation: fills
NACTL,NACTI(8). - Convection:
UW_RunandGF_Run(orRAS_Run). IfSH_MD_DPis true: shallow, then deep; otherwise deep, then shallow (RUN,if (SH_MD_DP)). - Epilogue, part 1:
CNV_MFC,CNV_MFDfrom the_DCand_SCexports; inactive-convection detrainment (6.3). - Microphysics:
BACM_1M_Run,GFDL_1M_Run,THOM_1M_RunorMGB2_2M_Run. The microphysics*_Runalso fillsDTDTFRIC(section 9) and, for GFDL_1M and MGB2_2M, callscompute_radar_diagnostics(gated byDBZ_RunAlarm) (GEOS_GFDL_1M_InterfaceMod.F90, GFDL_1M_Run;Process_Library.F90,compute_radar_diagnostics). - Epilogue, part 2: cloud-fraction exports; rain-out of humidity above 110% of saturation (
DTDT_ER,DQVDT_ER,ER_PRCP); sums of per-process tendencies intoDUDT,DVDT,DTDT,DQDT,DQLDT,DQIDT,DQRDT,DQSDT,DQGDT,DQADT,DPDTMST; precipitation totals and types;*AFMOISTexports. The lightning exportLFR_GCCis set to zero here; the driver importsHEMCO_FlashRatebut does not call it (RUN, "Lightning Exports"; grep).
When the alarm is not ringing, only UAFMOIST, VAFMOIST, TAFMOIST, QAFMOIST, THAFMOIST, SAFMOIST, RH2 are refreshed (RUN, else ! Alarm ringing). Physics reads them every step (9).
Moist changes its imports in place: T, U, V (imports) and Q, QLLS, ... (internals) are updated by each scheme in turn, and later schemes see the result (GEOS_UW_InterfaceMod.F90, UW_Run: T = T + DTDT_SC*MOIST_DT; GEOS_GF_InterfaceMod.F90, GF_Run).
- Imports: 58
MAPL_AddImportSpeccalls in SetServices; only some carryAVERAGING_INTERVAL/REFRESH_INTERVAL. Couplings are made by Physics (9). Notable: bundleMTR(tracers), stateAERO(aerosol),DTDT_BL/DQDT_BL(boundary-layer tendencies for GF),KPBL_SC(boundary-layer level for UW). - Internal state, per scheme in
*_Setup:Q,QLLS,QLCN,CLLS,CLCN,QILS,QICNalways; precipitating species and numbers by microphysics (5.2);NACTL,NACTI; GF addsCNV_TR; UW addsCUSH.QisFRIENDLYTODYNAMICS:TURBULENCE:CHEMISTRY:ANALYSIS;QLLS,QLCN,QILS,QICNtoDYNAMICS:TURBULENCE;CLLS,CLCNtoDYNAMICSonly (GEOS_BACM_1M_InterfaceMod.F90, BACM_1M_Setup,FRIENDLIES).
- Exports: about 559
MAPL_AddExportSpeccalls in the driver, including the*_SCand*_DCconvection exports. Exports are also work space between driver and schemes: a scheme fetches them withMAPL_GetPointer(EXPORT, ..., ALLOC=.TRUE.)and the driver reads them (UMF_DC,UMF_SC,MFD_DC,MFD_SC,CNV_FRC,SRF_TYPE) (GEOS_UW_InterfaceMod.F90, UW_Run, "Required Exports"). - Module-level shared state:
Process_Library.F90(moduleGEOSmoist_Process_Library) holds scheme tunables (SH_MD_DP,USE_AEROSOL_NN,WSUB_OPTION,CNV_FRACTION_MIN/MAX/EXP,SIGMA_DX, ...) and the friendly-tracer arrayCNV_Tracers;aer_cloud.F90holdsAeroPropsNew; interface modules keep their own (USE_GF2020,USE_PYMOIST_UW). - Restarts:
moist_internal_rst:Q(MAPL_RestartRequired) and every internal spec not markedRestartSkip(MAPL defaultMAPL_RestartOptional,MAPL_Generic.F90, internal-spec routine): cloud species, the microphysics' precipitating species and numbers, UW'sCUSH.- Not restarted (
RestartSkip):NACTL,NACTI, GF'sCNV_TRandDSL__GF2020_LONS/LATS(*_Setup). - Imports without
RestartSkip(for exampleKH,TKE,WQT,KPBL,DTDT_BL,DQDT_BL) go tomoist_import_rst(src/Applications/@GEOSgcm_App/AGCM.rc.tmpl,MODELATMMOIST_IMPORT_RESTART_FILE). Inferred: this restores lagged imports. - Unverified: the held convective tendencies (6) are exports and are not checkpointed.
Read in SetServices with MAPL_GetResource(CF, ...) from the AGCM resource file (built from src/Applications/@GEOSgcm_App/AGCM.rc.tmpl), checked with _ASSERT (an unsupported string aborts):
| Key | Values | Default | Source |
|---|---|---|---|
CONVPAR_OPTION |
GF, RAS, NONE (deep convection) |
GF |
GEOS_MoistGridComp.F90, SetServices |
SHALLOW_OPTION |
UW, NONE (shallow convection) |
UW |
same |
CLDMICR_OPTION |
BACM_1M, GFDL_1M, THOM_1M, MGB2_2M |
BACM_1M |
same |
- In the template,
CONVPAR_OPTION: @CONVPAR_OPTIONis filled by the setup scripts (GF, orNONEat some very high resolutions);CLDMICR_OPTIONandSHALLOW_OPTIONcome from prefixed template lines (@GFDL_1M_CLDMICR_OPTION,@SHALLOW_UWSHALLOW_OPTION: UW,@SHALLOW_SHOCSHALLOW_OPTION: NONE) (AGCM.rc.tmpl,set_resolution_params.csh).gcm_setupoffers onlyBACM_1M(default for 72 levels),GFDL_1M(default otherwise),MGB2_2M;THOM_1Mis accepted by Moist but not offered (gcm_setup). - The choice is made by
if (adjustl(OPTION)=="...")chains in each of SetServices, Initialize, Run and Finalize; a new scheme needs an edit in all four. NSSL_2Mhas an interface module and is compiled but is not accepted byCLDMICR_OPTIONand not called by the driver (GEOS_MoistGridComp.F90, SetServices,LCLDMICR). Inferred: work in progress.RASis accepted, but the bodies ofRAS_InitializeandRAS_Runare inside#ifdef NODISABLE, which no CMake file defines (grep), so selecting RAS runs no convection (GEOS_RAS_InterfaceMod.F90). Inferred: RAS is disabled.
Each module has *_Setup, *_Initialize, *_Run; some also *_Finalize.
| Role | Option | Interface module | Science source | State added / notes |
|---|---|---|---|---|
| Deep convection | GF (Grell-Freitas) |
GEOS_GF_InterfaceMod.F90 |
ConvPar_GF2020.F90, ConvPar_GF_GEOS5.F90, ConvPar_GF_Shared.F90 (also GF2020_2M_MicrophysicsMod.F90) |
CNV_TR; USE_GF2020 picks 2020 or GEOS5 code (default 1, 0 at 72 levels); alarm GF_RunAlarm; USE_PYMOIST_GF2020 |
| Deep convection | RAS |
GEOS_RAS_InterfaceMod.F90 |
ras.F90, rascnvv2_v.F90, ddf.F90, RASPARAMS.F90 |
disabled (5.1) |
| Shallow convection | UW (University of Washington) |
GEOS_UW_InterfaceMod.F90 |
uwshcu.F90 |
CUSH; alarm UW_RunAlarm; USE_PYMOIST_UW |
| Microphysics | BACM_1M (one-moment) |
GEOS_BACM_1M_InterfaceMod.F90 |
cloudnew.F90, aer_cloud.F90 |
no precipitating species in the internal state |
| Microphysics | GFDL_1M |
GEOS_GFDL_1M_InterfaceMod.F90 |
gfdl_cloud_microphys.F90, gfdl_mp.F90 |
QRAIN, QSNOW, QGRAUPEL; USE_PYMOIST_GFDL1M |
| Microphysics | THOM_1M (Thompson) |
GEOS_THOM_1M_InterfaceMod.F90 |
module_mp_thompson.F90, module_mp_radar.F90 |
QRAIN, QSNOW, QGRAUPEL, NCPL, NCPI, NRAIN |
| Microphysics | MGB2_2M (two-moment) |
GEOS_MGB2_2M_InterfaceMod.F90 |
micro_mg3_0.F90, micro_mg_utils.F90, cldwat2m_micro.F90, GF2020_2M_MicrophysicsMod.F90 |
MGVERSION (default 3) sets which precipitating species are friendly to Dynamics; NCPL, NCPI, NRAIN, NSNOW, NGRAUPEL |
| (not selectable) | NSSL_2M |
GEOS_NSSL_2M_InterfaceMod.F90 |
module_mp_nssl_2mom.F90, mp_nssl.F90 |
5.1 |
Sources: *_Setup internal specs in each module; USE_GF2020, GF_RunAlarm in GEOS_GF_InterfaceMod.F90, GF_Initialize; MGVERSION in GEOS_MGB2_2M_InterfaceMod.F90, MGB2_2M_Setup.
SH_MD_DP: order of shallow versus deep (3.1 step 4); GF also reads it (ConvPar_GF2020.F90, plume loop). Module default.FALSE.(Process_Library.F90). OnlyGFDL_1M_InitializeandNSSL_2M_Initializeread the key (default.TRUE.). Trap: withBACM_1M,THOM_1MorMGB2_2ManSH_MD_DPline inAGCM.rcis ignored and the order is always deep, then shallow (grep ofGEOS_*InterfaceMod.F90).GF_DT,UW_DT: supercycling intervals (6). The template sets both to@CONV_DT.WSUB_OPTION(0 parameterized, 1 climatologyWSUB_CLIM, 2Wnet, 3 symbolicWnet): in the driver it chooses which imports exist (SetServices).USE_NCLOUD_CLIMmakesNCPL_CLIM,NCPI_CLIMimports and bypasses activation. TheWSUB_OPTIONbranches in code exist only inGEOS_MGB2_2M_InterfaceMod.F90; BACM_1M and GFDL_1M ignore it, yet the imports are declared anyway.USE_AEROSOL_NN(re-read by BACM_1M, GFDL_1M, THOM_1M, MGB2_2M and NSSL_2M Initialize),NN_FAC_*,NN_MIN_*,NN_MAX_*,NCCN_OCN/LND,NCIN_OCN/LND: aerosol activation (8).USE_TRACER_TRANSP,USE_TRACER_SCAVEN(GF),USE_TRACER_TRANSP_UW: convective tracer transport (7).CONVECTION_TRACER(GF, default 0): if 1, the diagnostic tracerCNV_TRis also friendly toDYNAMICS; otherwise only to Moist itself (GEOS_GF_InterfaceMod.F90, GF_Setup).DETRAIN_INACTIVE_CNV,TAU_DETRAIN_CNV(6.3).DEBUG_MST,DEBUG_TQ_ERRORS: diagnostics.USE_PYMOIST_UW,USE_PYMOIST_GF2020,USE_PYMOIST_GFDL1M: run the Python (NDSL) version throughMAPL_pybridge_gcinit/gcrun_with_internal/gcfinalizeinstead of the Fortran code. The Python tree ispyMoist/(own README and tests).- Resource-label search.
MAPL_GetResource(CF, ...)(SetServices) goes throughMAPL_GetResource_config_scalarwithoutcomponent_name, so only the exact label is searched. TheMAPL_GetResource(MAPL, ...)form (Initialize and the*_Initializeroutines) also tries<name>_<label>,<type>_<label>,<label>and<name>.<label>(src/Shared/@MAPL/base/MAPL_Resource.F90,get_labels_with_prefix;MAPL_Generic.F90,MAPL_GetResourceFromMAPL_scalar; separator.insrc/Shared/@MAPL/shared/Constants/InternalConstants.F90).
Deep (GF) and shallow (UW) convection may run less often than Moist.
- Each scheme creates its alarm in
*_Initialize:GF_RunAlarm(intervalGF_DT) andUW_RunAlarm(UW_DT), both defaulting to the Moist interval (GEOS_GF_InterfaceMod.F90, GF_Initialize;GEOS_UW_InterfaceMod.F90, UW_Initialize). - In
GF_RunandUW_Runthe scheme call and the computation of the tendency exports (DTDT_DC,DQVDT_DC, ... /DTDT_SC, ...) are insideif (alarm_is_ringing). The code after it runs on every Moist step: it adds the tendency exports (timesMOIST_DT) toT,U,V,Q,QLCN,QICN,CLCN(UW also toQLLS,QILSthroughQLSUB_SC,QLENT_SC, ...), then fills negatives (GF_Run, "Add tendencies to the moist import state";UW_Run, "Apply tendencies in a single fused loop"). - So between alarms the tendency is held: the exports are fetched with
ALLOC=.TRUE.and written only at an alarm. Inferred: the same holds for the other exports written only inside the alarm branch (mass fluxesUMF_*,MFD_*,CNPCPRATE), which the driver's epilogue reads every step. - Microphysics is not supercycled: it runs every Moist step.
- The schemes get their own interval (
GF_DT = DT_R8from the alarm;compute_uwshcu_inv(..., UW_DT, ...)), while the held tendency is applied withMOIST_DT.
- Alarm phase is not anchored. Both alarms are created with
RingTime = currentTimeat Initialize; a 00ZringTimeis computed but not used. So the scheme runs on the first step after any start or restart and then everyGF_DT/UW_DT. A restart at a time that is not a multiple of the interval shifts the phase. Inferred: this can break restart reproducibility whenGF_DT > RUN_DT. - Unverified: held tendencies are exports and are not in
moist_internal_rst; since the alarm rings on the first step after a restart, they are recomputed before use. - Tracers are not held (7): the scheme updates them at the alarm with the full interval; nothing re-applies them.
- Inferred:
GF_DTandUW_DTshould be multiples ofMOIST_DT; otherwise the applied total differs from the scheme's interval.
If DETRAIN_INACTIVE_CNV > 0, wherever the layer mass flux 0.5*(CNV_MFC(L)+CNV_MFC(L+1)) is below that value the driver moves convective condensate and cloud fraction to the large-scale species at rate (1 - MFC/DETRAIN_INACTIVE_CNV) * DT_MOIST/TAU_DETRAIN_CNV (TAU_DETRAIN_CNV default 3600 s). DETRAIN_INACTIVE_CNV defaults to 0.0, but to 5.0e-4 for GFDL_1M (GEOS_MoistGridComp.F90, Initialize and RUN, "Mass fluxes").
- Physics fills Moist's import bundle
MTRin its Initialize:ESMF_StateGet(GIM(MOIST),'MTR',BUNDLE)thenMAPL_GridCompGetFriendlies(GC,"MOIST",BUNDLE)andMAPL_GridCompGetFriendlies(GCS,"MOIST",BUNDLE). It also callsMAPL_TerminateImport(... 'MTR' ..., CHILD=MOIST), so nothing else supplies it (GEOSagcm_GridComp/GEOSphysics_GridComp/GEOS_PhysicsGridComp.F90, SetServices, Initialize). - A field is in
MTRif its owner declaredFRIENDLYTOcontainingMOIST; MAPL records this as the field attributeFriendlyToMOIST(src/Shared/@MAPL/generic/MAPL_Generic.F90,'FriendlyTo'//...). To find producers grepFRIENDLYTO.*MOIST(and the last column of*StateSpecs.rc), notFriendlyToMOIST. Producers in this fixture, all underGEOSagcm_GridComp/GEOSphysics_GridComp/@GEOSchem_GridComp/: GOCART2G (DU2G,SS2G,SU2G,CA2G,NI2GandAerosolStateSpecs),@QuickChem/OH_GridCompStateSpecs,@ACHEM/ACHEM_GridCompMod.F90,@MAM/MAM_GridCompMod.F90,@TR/TR_GridCompMod.F90(unlessGOCART_convectionis true),@RRG/RRGMod.F90, GEOS-Chem (GEOSCHEMchem_GridComp/@geos-chem/Interfaces/GEOS/geos_interface.F90,.../GCHP/Chem_GridCompMod.F90).@CARMAdeclaresDYNAMICS:TURBULENCEonly (grep), so its tracers are not transported by Moist. - Each Run the driver calls
CNV_Tracers_Init(TR)(Process_Library.F90). It counts fields whoseFriendlyToMOISTis true. The first time it allocates the module arrayCNV_Tracers, reads per-tracer attributes (ScavengingFractionPerKm,SetofHenryLawCts, and for GEOS-Chem washoutSetofKcScalFactors,IsWetDep,RetentionFactor,LiqAndGas,ConvFacI2G,OnlineCLDLIQ,OnlineVUD,UseGOCART,GOCARTfTempThreshold) and stores a pointer to the bundle data inCNV_Tracers(F)%Q. Later calls only assert the count is unchanged. - The schemes read and write
CNV_Tracers(:)%Qdirectly: GF inGF2020_INTERFACE/GF_GEOS5_Interface(Q += DT_moist*SRC_CHEM,DT_moist = GF_DT, floormintracer) whenUSE_TRACER_TRANSP == 1(ConvPar_GF2020.F90); UW incompute_uwshcu_invwhenUSE_TRACER_TRANSP_UW == 1(uwshcu.F90). WithUSE_PYMOIST_*,CNV_Tracers_To_SOA/CNV_Tracers_To_AOScopy between structure forms (pyMoist/pyMoist/fortran/moist_workarounds.F90). - Tracers therefore change only at convection alarms and by the full scheme interval. If shallow runs first (
SH_MD_DP), deep convection sees tracers already changed by UW. - Traps:
- Saved pointers. Inferred: anything that reallocates or reorders the bundle after the first Run breaks
CNV_Tracers(:)%Qsilently, since only the count is checked (CNV_Tracers_Init). - Order of friendlies. The bundle is filled in Physics Initialize (above). Inferred: a tracer that becomes
FRIENDLYTO MOISTlater is not seen. - With
CONVPAR_OPTION=NONEdeep convection does not transport tracers, butUWstill does ifUSE_TRACER_TRANSP_UWis 1 (default) (GEOS_UW_InterfaceMod.F90, UW_Initialize). - Moist does not export a tracer tendency. Physics forms increments by differencing the bundle around the Moist call:
Initialize_IncBundle_runandCompute_IncBundleinGEOSagcm_GridComp/GEOSphysics_GridComp/@GEOSchem_GridComp/Shared/Chem_Shared/Bundle_IncrementMod.F90, and the 2D mass-weightedInitialize_IncMBundle_run,Compute_IncMBundleinGEOSagcm_GridComp/GEOSphysics_GridComp/MBundle_IncrementMod.F90(called fromGEOS_PhysicsGridComp.F90, Run).
- Saved pointers. Inferred: anything that reallocates or reorders the bundle after the first Run breaks
AEROis an ESMF state import (DATATYPE = MAPL_StateItem). Physics connects it from Chemistry:MAPL_AddConnectivity(SHORT_NAME='AERO', DST_ID=MOIST, SRC_ID=CHEM)(GEOS_PhysicsGridComp.F90, SetServices).- After the tracer collection the driver gets
NACTL(droplet number) andNACTI(ice number) one of three ways (GEOS_MoistGridComp.F90, RUN,AERO_ACTIVATE):USE_NCLOUD_CLIM: copy importsNCPL_CLIM,NCPI_CLIM(ExtData;WSUB_ExtData.yaml).USE_AEROSOL_NN(module default true): callAer_Activation(aer_actv_single_moment.F90), scale byNN_FAC_LIQ/ICE, clip to[NN_MIN, NN_MAX]. Vertical velocity isW, or derived fromOMEGAwhenWis identically zero.- Otherwise constants from
NCCN_LND/OCN,NCIN_LND/OCNweighted byFRLAND.
Aer_Activationreads attributes of theAEROstate (number_of_aerosol_modes,aerosol_modes, field names for pressure, temperature, land fraction, which it writes:PLE,T,FRLAND). For each mode it setsaerosol_mode, runs the state's ESMF methodaerosol_activation_properties, and copies number, dry size, width, hygroscopicity (and optionally density, dust/soot/organic fractions) into the module arrayAeroPropsNew(n)(aer_cloud.F90). The method is registered by the chemistry components (grepaerosol_activation_propertiesunderGEOSchem_GridComp). With the default providerGOCART2Git is attached bysetup_aerosol_activationinGOCART2G_AerosolActivationMod.F90(@GEOSchem_GridComp/@GOCART/ESMF/Shared/), which the GOCART2G parent calls inInitialize; theCARMAchild also registers one (@GEOSchem_GridComp/@CARMA/CARMAchem_GridCompMod.F90,ESMF_MethodAdd). Details: GOCART2G document (../@GEOSchem_GridComp/@GOCART/ESMF/GOCART2G_GridComp/ARCHITECTURE.mdin the fixture), section 5; GOCART document (../@GEOSchem_GridComp/@GOCART/docs/ARCHITECTURE.mdin the fixture), section 5.1.- Activated number per mode uses updraft
w + sqrt(TKE); modes with hygroscopicity above 0.4 sum intoNACTL, dust/soot modes intoNACTI; diagnosticsNWFA,NIFA(aer_actv_single_moment.F90,Aer_Activation,GetActFrac). AeroPropsNewis also consumed by GF (GF_Runpasses it) and MGB2_2M (MGB2_2M_Run), so activation must run before convection and microphysics, as it does.- Traps:
- With zero modes
Aer_Activationreturns after setting onlyNWFA,NIFA;NACTL/NACTIkeep earlier values (Observation 3). AeroPropsNewis filled only on theUSE_AEROSOL_NNpath. Inferred: on the other two paths GF and MGB2 read stale or empty data.- The neural network
Wnet(Wnet.F90,Wnet_weights.rc) is reached throughaer_cloud_init(use_wnet)and is enabled only byMGB2_2MwithWSUB_OPTION=2; BACM_1M and GFDL_1M callaer_cloud_init(use_wnet=.false.)(GEOS_MGB2_2M_InterfaceMod.F90, MGB2_2M_Initialize;aer_cloud.F90).
- With zero modes
Physics calls Moist once per step with a plain ESMF_GridCompRun (no phase), after GWD and before the phased Surface, Chemistry, Turbulence calls and Radiation (GEOS_PhysicsGridComp.F90, Run). Then:
- Before the call: Physics resets the increment bundles and copies the turbulence liquid and ice tendencies into Moist's
DQLDTTRB(Observation 2). It also allocatesDTDTFRICof Moist's exports (alloc=.true.) (Run). - Lagged import.
DTDT_BL/DQDT_BL(boundary-layer tendencies for GF) are written into Moist's import state by Physics after Moist, so GF uses the previous step's values (GEOS_PhysicsGridComp.F90, Run, "Boundary Layer Tendencies for GF";GEOS_GF_InterfaceMod.F90, GF_Run). Physics terminates the connectivity to them (MAPL_TerminateImport). Inferred: Moist restarts them frommoist_import_rst. - Imports supplied by Physics (
GEOS_PhysicsGridComp.F90, SetServices, "Moist Imports"):U,V,T,TAUOROX/Yfrom GWD; turbulence moments,KH,KPBL,KPBL_SC,TKE,ALH,KM,RIfrom Turbulence;TS,SNOMAS,FRLAND,FROCEAN,FRLANDICE,FRACI,T2M,Q2M,TA,QA,SH,EVAPfrom Surface;AEROfrom Chemistry;RADLW,RADSWfrom Radiation.PLE,ZLE,W,OMEGA,PREFcome from Dynamics through the AGCM (GEOSagcm_GridComp/GEOS_AgcmGridComp.F90, SetServices). - Exports Physics reads from Moist (
GEX(MOIST)):DUDT,DVDT,DWDT,DTDT,DTDTFRIC,DPDTMST,DQDT,DQLDT,DQIDT,DQRDT,DQSDT,DQGDT, andUAFMOIST,VAFMOIST,TAFMOIST,THAFMOIST,QAFMOIST,SAFMOIST. The*AFMOISTfields carry the post-Moist state to Surface, Turbulence and Chemistry whenSYNCUV/SYNCTQ(Inferred: Physics switches that pass the post-Moist winds, and temperature and humidity, to the other children) are on. - Exports connected to siblings (
SRC_ID=MOIST): to TurbulenceQV,QLTOT,QITOT,QRTOT,QSTOT,QGTOT,FCLD,WTHV2,WQT_DC,EIS; to RadiationQV,QL,QI,QR,QS,QG,FCLD,RL,RI,RR,RS,RG; to SurfacePCU,PLS,SNO,ICE,FRZR,TPREC,CN_PRCP; to GWDQ,CNV_FRC,DTDT_micro,DTDT_DC; to Chemistry a long list of cloud, precipitation, mass-flux and CAPE fields. - Tendency convention.
DTDTis the sum of per-process rates times layer pressure thickness (Pa K s-1); it excludes friction heating, which comes separately asDTDTFRICfrom the microphysics*_Run(dissipative_ke_heating, orIKEX/IKEX2in BACM_1M's#elsebranch sinceKEDISS_MICROis undefined) and which Physics adds to the temperature budget (GEOS_MoistGridComp.F90, RUN, "Export Total Moist Tendencies";GEOS_*_InterfaceMod.F90,*_Run;GEOS_PhysicsGridComp.F90, Run,TICU). The totals also omit the negative-value fills and the cloud-fraction change from 6.3 (Observation 4). - Dynamics and the condensate split. In
FV_Run(GEOSagcm_GridComp/GEOSsuperdyn_GridComp/@FVdycoreCubed_GridComp/FV_StateMod.F90, FVdycoreCubed @4deed15), "Pull Tracers" addsQLLS+QLCNinto total liquid,QILS+QICNinto total ice andCLLS+CLCNinto total cloud fraction (fornwat3 or 6, chosen from the tracer count and hydrostaticity) and also copiesQLCN,QICN,CLCNas extra tracers. "Push Tracers (Dynamic Mass Separation for Option A)" clips each advected convective tracer to its total, writes it back, setsQLLS = total - QLCN(likewise ice and cloud fraction) and floors at zero. Only the hydrostaticnwat=1path advects the six species independently. So the large-scale species are not independently conserved by Dynamics. Inferred: the search found no cloud-fraction-ratio re-split of the partition. - Negative-value fills. Moist fills negatives itself (GF and UW:
DQVDT_FILL_DC,*_FILL_SC; microphysics;FILLQ2ZEROcalls in*_Run), and Physics also appliesFILLQ2ZEROto the water species before and after the Moist call (DQ*DT_FILL_AFMSTexports) (GEOS_PhysicsGridComp.F90, Run).
- Libraries (
CMakeLists.txt,esma_add_library):GEOS_Shared,GMAO_mpeu,MAPL,Chem_Shared,Chem_Base, ESMF, BLAS, LAPACK, OpenMP; Python bridgeMAPL_pybridge_*in MAPL. - Chemistry repository:
Lightning_modinGEOSagcm_GridComp/GEOSphysics_GridComp/@GEOSchem_GridComp/Shared/Chem_Shared/Lightning_mod.F90(imported by the driver). TheAEROactivation method comes from the chemistry components. - Shared helpers:
GEOS_UtilsMod(saturation functions such asGEOS_QSAT,GEOS_DQSAT) andGEOS_RadarMod, fromGEOS_Shared.FILLQ2ZERO(andFILLQ2ZERO_OLD) are public inProcess_Library.F90, not inGEOS_UtilsMod. - Compiler workarounds in
CMakeLists.txt: some sources use-O1with GCC 15 or later;GEOS_BACM_1M_InterfaceMod.F90uses-O1with Intel Release. - Build and test: with the GEOSgcm fixture; Python/NDSL tests in
pyMoist/tests(seepyMoist/README.md).
Scheme if chains in four routines (5.1); first internal spec order (3); SH_MD_DP read by two microphysics only (5.3); unanchored alarms (6.2); cached tracer pointers (7); order inside Run is part of the contract because schemes pass data through exports and module globals (AeroPropsNew, CNV_Tracers, SH_MD_DP) (3.1, 8); in-place modification of imports (3.1).
- Pattern: three resource strings are tested with
ifchains in SetServices, Initialize, Run and Finalize; unselected schemes declare no state (GEOS_MoistGridComp.F90). [Verified] - Likely reason: keeps unused schemes' state out of restarts and History; avoids runtime polymorphism. [Inferred]
- Question for maintainers: what is the intended status of the compiled-but-inert schemes (
NSSL_2M,RAS) — are they expected to be completed and used, or kept only for reference?
- Pattern: separate alarms for GF and UW; tendencies held in exports and applied each step (6.1). [Verified]
- Likely reason: deep convection is the most expensive scheme and is run at a longer interval at high resolution. [Inferred]
- Question for maintainers: are the unanchored alarms (6.2) intended?
- Pattern: schemes allocate exports on demand and the driver reads them back (4). [Verified]
- Likely reason: avoids a shared derived type between independently developed schemes. [Inferred]
WSUB_OPTIONhas several defaults, one dead. The driver reads it with default 3 (GEOS_MoistGridComp.F90, SetServices) and that value chooses the imports.MGB2_2M_SetupassignsMGB2_WSUB_OPTIONwith default 1 but never uses it;MGB2_2M_Initializere-reads it with default 3 before use (GEOS_MGB2_2M_InterfaceMod.F90). The default 1 is dead.DQIMSTreads the wrong label. Physics fetches the import'DQLDTTRB'twice; the ice tendency should come from'DQIDTTRB'(GEOS_PhysicsGridComp.F90, Run, "Pass Turbulence QL, QI tendencies to Moist Import state"). Moist never reads either import (grep), so there is no effect today.Aer_ActivationleavesNACTL/NACTIunassigned when there are zero modes (aer_actv_single_moment.F90,n_modes == 0); the driver then scales and clips them.- Total tendency exports omit the negative-value fills and the cloud-fraction change from inactive-convection detrainment (which moves condensate between
QLCN/QLLS, soDQLDT,DQIDTtotals are unaffected, butDQADTis) (GEOS_MoistGridComp.F90, RUN). DWDTis declared but never computed in Moist (SHORT_NAME = 'DWDT'; grep of the Moist directory), while Physics reads it asWIM(GEOS_PhysicsGridComp.F90, Run). Physics allocates it withalloc=.true.. Unverified: the initial value is zero (not checked in MAPL'sALLOC).- Duplicate timer name.
---CLDMACROis added twice (GEOS_MoistGridComp.F90, SetServices). - Stale comments. Initialize refers to "child Dynamics";
pyMoist/README.mdmentionsMGB2_3M; the module header saysCLDMACRO==MGB2_2Mwhile the key isCLDMICR_OPTION. RASandNSSL_2Mare accepted or compiled but inert (5.1).- Two implementations of
FILLQ2ZERO.Process_Library.F90(withFILLQ2ZERO_OLD) and a private copy inGEOS_PhysicsGridComp.F90; Physics does not use the Moist version.
Today the GF and UW alarms start at the current time of Initialize; a 00Z ring time is computed but unused (6.2). Should the convection alarms be anchored to a fixed reference time, so that a restart at an arbitrary time continues the same supercycle phase?