From 31e85f2de262a55fa85661ffaba8d8cf17378853 Mon Sep 17 00:00:00 2001 From: Tony Craig Date: Tue, 20 Jun 2023 09:40:38 -0700 Subject: [PATCH 1/2] update readthedocs.yaml, turn on pdf (#438) --- .readthedocs.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index f83760cce..cc2b2817b 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -20,8 +20,8 @@ sphinx: configuration: doc/source/conf.py # If using Sphinx, optionally build your docs in additional formats such as PDF -# formats: -# - pdf +formats: + - pdf # Optionally declare the Python requirements required to build your docs python: From d024340f19676bc5f6c0effe0c5dbfb763a5882a Mon Sep 17 00:00:00 2001 From: Tony Craig Date: Thu, 6 Jul 2023 10:29:43 -0700 Subject: [PATCH 2/2] Update icepack_step_therm2, make fsd arguments optional (#440) * Update icepack_step_therm2, make fsd arguments optional * Update interface documentation * Update user guide, change references from master to main * update optional arguments in lower level routines for fsd step_therm2 * update documentation about optional arguments * update documentation about optional arguments --- columnphysics/icepack_therm_itd.F90 | 190 ++++++++++++--------- doc/source/developer_guide/dg_col_phys.rst | 63 ++++--- doc/source/intro/citing.rst | 2 +- doc/source/user_guide/interfaces.include | 71 ++++---- doc/source/user_guide/ug_testing.rst | 4 +- 5 files changed, 184 insertions(+), 146 deletions(-) diff --git a/columnphysics/icepack_therm_itd.F90 b/columnphysics/icepack_therm_itd.F90 index c16e38fe7..97c24c2ee 100644 --- a/columnphysics/icepack_therm_itd.F90 +++ b/columnphysics/icepack_therm_itd.F90 @@ -927,15 +927,7 @@ subroutine lateral_melt (dt, ncat, & meltl , & ! lateral ice melt (m/step-->cm/day) fzsal ! salt flux from zsalinity (kg/m2/s) - real (kind=dbl_kind), dimension (:), intent(in) :: & - floe_rad_c , & ! fsd size bin centre in m (radius) - floe_binwidth ! fsd size bin width in m (radius) - - real (kind=dbl_kind), dimension (:), intent(out) :: & - d_afsd_latm ! change in fsd due to lateral melt (m) - - real (kind=dbl_kind), dimension(nbtrcr), & - intent(inout) :: & + real (kind=dbl_kind), dimension(nbtrcr), intent(inout) :: & flux_bio ! biology tracer flux from layer bgc (mmol/m^2/s) real (kind=dbl_kind), dimension(:), intent(inout) :: & @@ -944,6 +936,13 @@ subroutine lateral_melt (dt, ncat, & real (kind=dbl_kind), dimension(:), intent(inout) :: & fiso_ocn ! isotope flux to ocean (kg/m^2/s) + real (kind=dbl_kind), dimension (:), intent(in) :: & + floe_rad_c , & ! fsd size bin centre in m (radius) + floe_binwidth ! fsd size bin width in m (radius) + + real (kind=dbl_kind), dimension (:), intent(out) :: & + d_afsd_latm ! change in fsd due to lateral melt (m) + ! local variables integer (kind=int_kind) :: & @@ -970,15 +969,14 @@ subroutine lateral_melt (dt, ncat, & delta_an , & ! change in the ITD rsiden ! delta_an/aicen - real (kind=dbl_kind), dimension (nfsd,ncat) :: & + real (kind=dbl_kind), dimension (:,:), allocatable :: & afsdn , & ! floe size distribution tracer afsdn_init ! initial value - real (kind=dbl_kind), dimension (nfsd) :: & - df_flx, & ! finite difference for FSD - afsd_tmp, d_afsd_tmp - - real (kind=dbl_kind), dimension(nfsd+1) :: & + real (kind=dbl_kind), dimension (:), allocatable :: & + df_flx , & ! finite difference for FSD + afsd_tmp , & ! + d_afsd_tmp, & ! f_flx ! real (kind=dbl_kind) :: & @@ -1002,19 +1000,24 @@ subroutine lateral_melt (dt, ncat, & G_radialn = c0 delta_an = c0 rsiden = c0 - afsdn = c1 - afsdn_init = c0 - df_flx = c0 - f_flx = c0 if (tr_fsd) then call icepack_cleanup_fsd (ncat, nfsd, trcrn(nt_fsd:nt_fsd+nfsd-1,:)) if (icepack_warnings_aborted(subname)) return - afsdn = trcrn(nt_fsd:nt_fsd+nfsd-1,:) - aicen_init = aicen - afsdn_init = afsdn ! for diagnostics - d_afsd_latm(:) = c0 + allocate(afsdn(nfsd,ncat)) + allocate(afsdn_init(nfsd,ncat)) + allocate(df_flx(nfsd)) + allocate(afsd_tmp(nfsd)) + allocate(d_afsd_tmp(nfsd)) + allocate(f_flx(nfsd+1)) + + aicen_init = aicen + afsdn = trcrn(nt_fsd:nt_fsd+nfsd-1,:) + afsdn_init = afsdn ! for diagnostics + df_flx = c0 + d_afsd_latm = c0 + f_flx = c0 end if if (tr_fsd .and. wlat > puny) then @@ -1257,6 +1260,14 @@ subroutine lateral_melt (dt, ncat, & + afsdn(k,n)*aicen(n) - afsdn_init(k,n)*aicen_init(n) end do end do + + deallocate(afsdn) + deallocate(afsdn_init) + deallocate(df_flx) + deallocate(afsd_tmp) + deallocate(d_afsd_tmp) + deallocate(f_flx) + end if end subroutine lateral_melt @@ -1403,7 +1414,7 @@ subroutine add_new_ice (ncat, nilyr, & real (kind=dbl_kind), intent(in) :: & wave_sig_ht ! significant height of waves globally (m) - real (kind=dbl_kind), dimension(:), intent(in) :: & + real (kind=dbl_kind), dimension(:), intent(in) :: & wave_spectrum ! ocean surface wave spectrum, E(f) (m^2 s) real(kind=dbl_kind), dimension(:), intent(in) :: & @@ -1414,11 +1425,6 @@ subroutine add_new_ice (ncat, nilyr, & floe_rad_c , & ! fsd size bin centre in m (radius) floe_binwidth ! fsd size bin width in m (radius) - real (kind=dbl_kind), dimension(ncat) :: & ! for now - ! change in thickness distribution (area) - d_an_latg , & ! due to fsd lateral growth - d_an_newi ! new ice formation - real (kind=dbl_kind), dimension(:), intent(out) :: & ! change in thickness distribution (area) d_afsd_latg , & ! due to fsd lateral growth @@ -1468,12 +1474,17 @@ subroutine add_new_ice (ncat, nilyr, & vicen_init ! volume per unit area of ice (m) ! floe size distribution - real (kind=dbl_kind), dimension (nfsd,ncat) :: & + real (kind=dbl_kind), dimension (:,:), allocatable :: & afsdn ! floe size distribution tracer (originally areal_mfstd_init) ! real (kind=dbl_kind), dimension (nfsd) :: & ! afsd , & ! fsd tracer for each thickness category + real (kind=dbl_kind), dimension(ncat) :: & ! for now + ! change in thickness distribution (area) + d_an_latg , & ! due to fsd lateral growth + d_an_newi ! new ice formation + real (kind=dbl_kind), dimension (ncat) :: & d_an_tot, & ! change in the ITD due to lateral growth and new ice area2 ! area after lateral growth and before new ice formation @@ -1497,7 +1508,6 @@ subroutine add_new_ice (ncat, nilyr, & hsurp = c0 hi0new = c0 ai0new = c0 - afsdn(:,:) = c0 d_an_latg(:) = c0 d_an_tot(:) = c0 d_an_newi(:) = c0 @@ -1520,6 +1530,8 @@ subroutine add_new_ice (ncat, nilyr, & endif if (tr_fsd) then + allocate(afsdn(nfsd,ncat)) + afsdn(:,:) = c0 call icepack_cleanup_fsd (ncat, nfsd, trcrn(nt_fsd:nt_fsd+nfsd-1,:)) if (icepack_warnings_aborted(subname)) return endif @@ -1636,7 +1648,7 @@ subroutine add_new_ice (ncat, nilyr, & if (vi0new > c0) then - if (tr_fsd) & ! lateral growth of existing ice + if (tr_fsd) then ! lateral growth of existing ice ! calculate change in conc due to lateral growth ! update vi0new, without change to afsdn or aicen call fsd_lateral_growth (ncat, nfsd, & @@ -1647,8 +1659,8 @@ subroutine add_new_ice (ncat, nilyr, & lead_area, latsurf_area, & G_radial, d_an_latg, & tot_latg) - - if (icepack_warnings_aborted(subname)) return + if (icepack_warnings_aborted(subname)) return + endif ai0mod = aice0 ! separate frazil ice growth from lateral ice growth @@ -1822,7 +1834,7 @@ subroutine add_new_ice (ncat, nilyr, & trcrn(nt_FY,n) = min(trcrn(nt_FY,n), c1) endif - if (tr_fsd) & ! evolve the floe size distribution + if (tr_fsd) then ! evolve the floe size distribution ! both new frazil ice and lateral growth call fsd_add_new_ice (ncat, n, nfsd, & dt, ai0new, & @@ -1837,8 +1849,8 @@ subroutine add_new_ice (ncat, nilyr, & d_afsd_newi, & afsdn, aicen_init, & aicen, trcrn) - - if (icepack_warnings_aborted(subname)) return + if (icepack_warnings_aborted(subname)) return + endif if (vicen(n) > puny) then if (tr_iage) & @@ -1938,7 +1950,7 @@ subroutine add_new_ice (ncat, nilyr, & !----------------------------------------------------------------- ! Biogeochemistry !----------------------------------------------------------------- - if (tr_brine .or. nbtrcr > 0) & + if (tr_brine .or. nbtrcr > 0) then call add_new_ice_bgc(dt, nblyr, & ncat, nilyr, nltrcr, & bgrid, cgrid, igrid, & @@ -1948,6 +1960,11 @@ subroutine add_new_ice (ncat, nilyr, & nbtrcr, sss, ocean_bio,& flux_bio, hsurp) if (icepack_warnings_aborted(subname)) return + endif + + if (tr_fsd) then + deallocate(afsdn) + endif end subroutine add_new_ice @@ -1996,14 +2013,16 @@ subroutine icepack_step_therm2 (dt, ncat, nltrcr, & integer (kind=int_kind), intent(in) :: & ncat , & ! number of thickness categories - nfsd , & ! number of floe size categories nltrcr , & ! number of zbgc tracers nblyr , & ! number of bio layers nilyr , & ! number of ice layers nslyr ! number of snow layers + integer (kind=int_kind), intent(in), optional :: & + nfsd ! number of floe size categories + logical (kind=log_kind), intent(in) :: & - update_ocn_f ! if true, update fresh water and salt fluxes + update_ocn_f ! if true, update fresh water and salt fluxes real (kind=dbl_kind), dimension(0:ncat), intent(inout) :: & hin_max ! category boundaries (m) @@ -2013,42 +2032,27 @@ subroutine icepack_step_therm2 (dt, ncat, nltrcr, & Tf , & ! freezing temperature (C) sss , & ! sea surface salinity (ppt) rside , & ! fraction of ice that melts laterally - frzmlt , & ! freezing/melting potential (W/m^2) - wave_sig_ht ! significant height of waves in ice (m) - - real (kind=dbl_kind), intent(in), optional :: & - wlat ! lateral melt rate (m/s) - - real (kind=dbl_kind), dimension(:), intent(in) :: & - wave_spectrum ! ocean surface wave spectrum E(f) (m^2 s) - - real(kind=dbl_kind), dimension(:), intent(in) :: & - wavefreq, & ! wave frequencies (s^-1) - dwavefreq ! wave frequency bin widths (s^-1) - - real (kind=dbl_kind), dimension (:), intent(in) :: & - floe_rad_c , & ! fsd size bin centre in m (radius) - floe_binwidth ! fsd size bin width in m (radius) + frzmlt ! freezing/melting potential (W/m^2) integer (kind=int_kind), dimension (:), intent(in) :: & trcr_depend, & ! = 0 for aicen tracers, 1 for vicen, 2 for vsnon n_trcr_strata ! number of underlying tracer layers real (kind=dbl_kind), dimension (:,:), intent(in) :: & - trcr_base ! = 0 or 1 depending on tracer dependency - ! argument 2: (1) aice, (2) vice, (3) vsno + trcr_base ! = 0 or 1 depending on tracer dependency + ! argument 2: (1) aice, (2) vice, (3) vsno integer (kind=int_kind), dimension (:,:), intent(in) :: & - nt_strata ! indices of underlying tracer layers + nt_strata ! indices of underlying tracer layers real (kind=dbl_kind), dimension (nblyr+2), intent(in) :: & - bgrid ! biology nondimensional vertical grid points + bgrid ! biology nondimensional vertical grid points real (kind=dbl_kind), dimension (nblyr+1), intent(in) :: & - igrid ! biology vertical interface points + igrid ! biology vertical interface points real (kind=dbl_kind), dimension (nilyr+1), intent(in) :: & - cgrid ! CICE vertical coordinate + cgrid ! CICE vertical coordinate real (kind=dbl_kind), dimension(:), intent(in) :: & salinz , & ! initial salinity profile @@ -2068,6 +2072,9 @@ subroutine icepack_step_therm2 (dt, ncat, nltrcr, & frazil , & ! frazil ice growth (m/step-->cm/day) frazil_diag ! frazil ice growth diagnostic (m/step-->cm/day) + real (kind=dbl_kind), intent(in), optional :: & + wlat ! lateral melt rate (m/s) + real (kind=dbl_kind), dimension(:), intent(inout) :: & aicen_init,& ! initial concentration of ice vicen_init,& ! initial volume per unit area of ice (m) @@ -2081,14 +2088,7 @@ subroutine icepack_step_therm2 (dt, ncat, nltrcr, & trcrn ! tracers logical (kind=log_kind), dimension(:), intent(inout) :: & - first_ice ! true until ice forms - - real (kind=dbl_kind), dimension(:), intent(out) :: & - ! change in floe size distribution (area) - d_afsd_latg , & ! due to fsd lateral growth - d_afsd_newi , & ! new ice formation - d_afsd_latm , & ! lateral melt - d_afsd_weld ! welding + first_ice ! true until ice forms real (kind=dbl_kind), intent(inout), optional :: & frz_onset ! day of year that freezing begins (congel or frazil) @@ -2098,12 +2098,34 @@ subroutine icepack_step_therm2 (dt, ncat, nltrcr, & ! water isotopes real (kind=dbl_kind), dimension(:), intent(inout), optional :: & - fiso_ocn ! isotope flux to ocean (kg/m^2/s) + fiso_ocn ! isotope flux to ocean (kg/m^2/s) real (kind=dbl_kind), intent(in), optional :: & HDO_ocn , & ! ocean concentration of HDO (kg/kg) H2_16O_ocn , & ! ocean concentration of H2_16O (kg/kg) H2_18O_ocn ! ocean concentration of H2_18O (kg/kg) + + real (kind=dbl_kind), intent(in), optional :: & + wave_sig_ht ! significant height of waves in ice (m) + + real (kind=dbl_kind), dimension(:), intent(in), optional :: & + wave_spectrum ! ocean surface wave spectrum E(f) (m^2 s) + + real(kind=dbl_kind), dimension(:), intent(in), optional :: & + wavefreq, & ! wave frequencies (s^-1) + dwavefreq ! wave frequency bin widths (s^-1) + + real (kind=dbl_kind), dimension(:), intent(out), optional :: & + ! change in floe size distribution (area) + d_afsd_latg, & ! due to fsd lateral growth + d_afsd_newi, & ! new ice formation + d_afsd_latm, & ! lateral melt + d_afsd_weld ! welding + + real (kind=dbl_kind), dimension (:), intent(in), optional :: & + floe_rad_c, & ! fsd size bin centre in m (radius) + floe_binwidth ! fsd size bin width in m (radius) + !autodocument_end ! local variables @@ -2129,7 +2151,18 @@ subroutine icepack_step_therm2 (dt, ncat, nltrcr, & endif endif if (tr_fsd) then - if (.not.(present(wlat))) then + if (.not.(present(nfsd) .and. & + present(wlat) .and. & + present(wave_sig_ht) .and. & + present(wave_spectrum) .and. & + present(wavefreq) .and. & + present(dwavefreq) .and. & + present(d_afsd_latg) .and. & + present(d_afsd_newi) .and. & + present(d_afsd_latm) .and. & + present(d_afsd_weld) .and. & + present(floe_rad_c) .and. & + present(floe_binwidth))) then call icepack_warnings_add(subname//' error in FSD arguments, tr_fsd=T') call icepack_warnings_setabort(.true.,__FILE__,__LINE__) return @@ -2244,12 +2277,13 @@ subroutine icepack_step_therm2 (dt, ncat, nltrcr, & if (icepack_warnings_aborted(subname)) return ! Floe welding during freezing conditions - if (tr_fsd) & - call fsd_weld_thermo (ncat, nfsd, & - dt, frzmlt, & - aicen, trcrn, & - d_afsd_weld) - if (icepack_warnings_aborted(subname)) return + if (tr_fsd) then + call fsd_weld_thermo (ncat, nfsd, & + dt, frzmlt, & + aicen, trcrn, & + d_afsd_weld) + if (icepack_warnings_aborted(subname)) return + endif !----------------------------------------------------------------- ! For the special case of a single category, adjust the area and diff --git a/doc/source/developer_guide/dg_col_phys.rst b/doc/source/developer_guide/dg_col_phys.rst index 8ebc62c59..c144a91f3 100755 --- a/doc/source/developer_guide/dg_col_phys.rst +++ b/doc/source/developer_guide/dg_col_phys.rst @@ -19,12 +19,11 @@ The column physics source code contains the following files | **icepack_firstyear.F90** handles most work associated with the first-year ice area tracer | **icepack_flux.F90** fluxes needed/produced by the model | **icepack_fsd.F90** supports floe size distribution -| **icepack_isotope.F90** handles isotopes | **icepack_intfc.F90** interface routines for linking Icepack with a host sea ice model +| **icepack_isotope.F90** handles isotopes | **icepack_itd.F90** utilities for managing ice thickness distribution | **icepack_kinds.F90** basic definitions of reals, integers, etc. | **icepack_mechred.F90** mechanical redistribution (ridging) -| **icepack_meltpond_cesm.F90** CESM melt pond parameterization | **icepack_meltpond_lvl.F90** level-ice melt pond parameterization | **icepack_meltpond_topo.F90** topo melt pond parameterization | **icepack_mushy_physics.F90** physics routines for mushy thermodynamics @@ -33,7 +32,6 @@ The column physics source code contains the following files | **icepack_parameters.F90** basic model parameters including physical and numerical constants requried for column package | **icepack_shortwave.F90** shortwave and albedo parameterizations | **icepack_snow.F90** snow physics -| **icepack_therm_0layer.F90** zero-layer thermodynamics of :cite:`Semtner76` | **icepack_therm_bl99.F90** multilayer thermodynamics of :cite:`Bitz99` | **icepack_therm_itd.F90** thermodynamic changes mostly related to ice thickness distribution | **icepack_therm_mushy.F90** mushy-theory thermodynamics of :cite:`Turner13` @@ -61,9 +59,8 @@ The column physics does not have a time manager. Calendaring is expected to be dealt with by the host model. The column physics does not read any forcing data, that is passed into the column physics though interfaces. In fact, there are no direct IO capabilities in the column physics. That is to say, the -column physics does not open files to read or write. The column physics is able to write -data via several different routines that specifically have a fortran unit number as an input -argument. In addition, there is a warning and abort package (see section :ref:`aborts`) that +column physics does not open files to read or write. However, the column physics +contains a warning and abort package (see section :ref:`aborts`) that provides the column package with the ability to store log output. That output can be queried by the host model or it can be written directly via a specific routine. The warning package also provides access to an abort flag that the host model can @@ -75,6 +72,7 @@ The internal constants, parameters, and tracer settings have init (set), query ( write interfaces that provides access to internal column physics settings. The host model should not have to use "use" statements to access any of the column physics data outside of what is provided through the icepack_intfc module. + The public column physics interfaces use optional arguments where it makes sense and there is an ongoing effort to extend the optional arguments supported. It's strongly recommended that calls to the icepack interfaces be done with keyword=value arguments. All icepack arguments @@ -127,17 +125,19 @@ Overall, columnphysics changes in the Icepack model should include the following to support errors backing up the call tree to the external program - * Variables defined in icepack_kinds, icepack_tracers, icepack_parameters, and icepack_orbital should be accessed within Icepack by Fortran use statements. It's also possible to access some of those variables thru methods that query for the value, but this tends to be a little more cumbersome, so Fortran use statements are recommended within columnphysics. From the icepack driver or other external programs, the columnphysics variables should ALWAYS be access thru the interface methods and icepack_intfc (see also :ref:`calling`). + * Variables defined in icepack_kinds, icepack_tracers, icepack_parameters, and icepack_orbital should be accessed from WITHIN Icepack by Fortran use statements (even though this is not recommended for drivers). It's also possible to use the public methods to access internal Icepack variables. Again, from the icepack driver or other external programs, the columnphysics variables should ALWAYS be access thru the interface methods and icepack_intfc (see also :ref:`calling`). - * Optional arguments are encouraged in the public Icepack interfaces. They allow for easier backwards compatible Icepack public interfaces and support future extensions. There is also a desire to allow users to pass only the data thru the Icepack interfaces that is needed. There are several ways optional arguments can be passed down the calling tree in Icepack. Two options, copying into local data or copying into module data are viable. But the recommended approach is to + * Icepack is a simple serial code. Global flags and parameters should be set identically on all tasks/threads that call into Icepack. Icepack has no ability to reconcile or identify inconsistencies between different tasks/threads. All aspects of correct parallel implementation is managed by the driver code. - * Use universal flags and parameters to turn on/off features. + * Optional arguments are encouraged in the public Icepack interfaces. They provide backwards compatibility in the public interfaces and allow future extensions. Argument that are not always required should ultimately be made optional. There are several ways optional arguments can be passed down the calling tree in Icepack. Two options, copying into local data or copying into module data are viable. But the recommended approach is to - * Have all optional features trigger from the flags and parameters. + * Use universal flags and parameters to turn on/off features. Avoid having features triggered by the presence of optional arguments. * Verify that the optional arguments required for any feature are passed in at the top level of each Icepack interface. If not, then abort. - * Pass all optional arguments down the calling tree as optional arguments. + * Leverage the icepack subroutine ``icepack_checkoptargflags`` which controls how often to check the optional arguments. The ``argcheck`` namelist setting controls when to do the checks, 'never', 'first', or 'always' are valid settings + + * Pass all optional arguments down the calling tree as needed. Optional arguments can be passed down a calling tree as non-optional as long as they are not used unless they have been passed in above. This is the recommended method for optional arguments within Icepack. Sometimes the optional attribute needs to be defined in lower level routines for a variable if that variable needs to be checked by Fortran's present. That's OK, but should generally be avoided if possible. * An example of how this might look is @@ -150,26 +150,31 @@ Overall, columnphysics changes in the Icepack model should include the following real (kind=dbl_kind), optional, dimension(:), intent(inout) :: arg2 real (kind=dbl_kind), optional, intent(inout) :: arg3 + logical, save :: first_call = .true. character(len=*), parameter :: subname = '(icepack_public_interface)' - if (flag_arg2) then - if (.not.present(arg2)) then - call icepack_warnings_setabort(.true.,__FILE__,__LINE__) - call icepack_warnings_add(subname//' flag_arg2 set but arg2 not passed') + if (icepack_chkoptargflag(first_call)) then + if (flag_arg2) then + if (.not.present(arg2)) then + call icepack_warnings_setabort(.true.,__FILE__,__LINE__) + call icepack_warnings_add(subname//' flag_arg2 set but arg2 not passed') + endif endif - endif - if (flag_arg3) then - if (.not.present(arg3)) then - call icepack_warnings_setabort(.true.,__FILE__,__LINE__) - call icepack_warnings_add(subname//' flag_arg3 set but arg3 not passed') + if (flag_arg3) then + if (.not.present(arg3)) then + call icepack_warnings_setabort(.true.,__FILE__,__LINE__) + call icepack_warnings_add(subname//' flag_arg3 set but arg3 not passed') + endif endif + if (icepack_warnings_aborted(subname)) return endif - if (icepack_warnings_aborted(subname)) return ... call some_columnphysics_subroutine(arg1, arg2, arg3, ...) ... + first_call = .false. + end subroutine !------------ @@ -177,8 +182,8 @@ Overall, columnphysics changes in the Icepack model should include the following subroutine some_columnphysics_subroutine(arg1, arg2, arg3, ...) real (kind=dbl_kind), intent(inout) :: arg1 - real (kind=dbl_kind), optional, dimension(:), intent(inout) :: arg2 - real (kind=dbl_kind), optional, intent(inout) :: arg3 + real (kind=dbl_kind), dimension(:), intent(inout) :: arg2 + real (kind=dbl_kind), intent(inout) :: arg3 if (flag_arg2) then arg2(:) = ... @@ -194,7 +199,7 @@ Overall, columnphysics changes in the Icepack model should include the following subroutine someother_columnphysics_subroutine(arg3) - real (kind=dbl_kind), optional, intent(inout) :: arg3 + real (kind=dbl_kind), intent(inout) :: arg3 arg3 = ... @@ -203,15 +208,9 @@ Overall, columnphysics changes in the Icepack model should include the following Some notes - * If optional arguments are passed but not needed, this is NOT an error. + * If optional arguments are passed but not needed, this is NOT an error. If optional argument are not passed but needed, this is an error. - * If checking and implementation are done properly, optional arguments that are not needed will never be referenced anywhere in Icepack at that timestep + * If checking and implementation are done properly, optional arguments that are not needed will never be referenced anywhere in Icepack at that timestep. Optional arguments should be matched with the appropriate flags at the first entry into Icepack. * There is a unit test in CICE to verify robustness of this approach. - * We recommend doing all checks for optional arguments for an interface before returning just for completeness (as shown above) - - * An argcheck parameter will control when to do the checks, 'none', 'first', or 'all' may be possible settings - - * Icepack is a simple serial code. Global flags and parameters should be set identically on all tasks/threads that call into Icepack. Icepack has no ability to reconcile or identify inconsistencies between different tasks/threads. - diff --git a/doc/source/intro/citing.rst b/doc/source/intro/citing.rst index 42919384a..12b224c98 100644 --- a/doc/source/intro/citing.rst +++ b/doc/source/intro/citing.rst @@ -15,7 +15,7 @@ More information can be found by following the DOI link to zenodo. If you use Icepack, please cite the version number of the code you are using or modifying. -If using code from the CICE-Consortium repository ``master`` branch +If using code from the CICE-Consortium repository ``main`` branch that includes modifications that have not yet been released with a version number, then in addition to the most recent version number, the hash at time of diff --git a/doc/source/user_guide/interfaces.include b/doc/source/user_guide/interfaces.include index c45625551..b55be984c 100644 --- a/doc/source/user_guide/interfaces.include +++ b/doc/source/user_guide/interfaces.include @@ -1990,14 +1990,16 @@ icepack_step_therm2 integer (kind=int_kind), intent(in) :: & ncat , & ! number of thickness categories - nfsd , & ! number of floe size categories nltrcr , & ! number of zbgc tracers nblyr , & ! number of bio layers nilyr , & ! number of ice layers nslyr ! number of snow layers + integer (kind=int_kind), intent(in), optional :: & + nfsd ! number of floe size categories + logical (kind=log_kind), intent(in) :: & - update_ocn_f ! if true, update fresh water and salt fluxes + update_ocn_f ! if true, update fresh water and salt fluxes real (kind=dbl_kind), dimension(0:ncat), intent(inout) :: & hin_max ! category boundaries (m) @@ -2007,42 +2009,27 @@ icepack_step_therm2 Tf , & ! freezing temperature (C) sss , & ! sea surface salinity (ppt) rside , & ! fraction of ice that melts laterally - frzmlt , & ! freezing/melting potential (W/m^2) - wave_sig_ht ! significant height of waves in ice (m) - - real (kind=dbl_kind), intent(in), optional :: & - wlat ! lateral melt rate (m/s) - - real (kind=dbl_kind), dimension(:), intent(in) :: & - wave_spectrum ! ocean surface wave spectrum E(f) (m^2 s) - - real(kind=dbl_kind), dimension(:), intent(in) :: & - wavefreq, & ! wave frequencies (s^-1) - dwavefreq ! wave frequency bin widths (s^-1) - - real (kind=dbl_kind), dimension (:), intent(in) :: & - floe_rad_c , & ! fsd size bin centre in m (radius) - floe_binwidth ! fsd size bin width in m (radius) + frzmlt ! freezing/melting potential (W/m^2) integer (kind=int_kind), dimension (:), intent(in) :: & trcr_depend, & ! = 0 for aicen tracers, 1 for vicen, 2 for vsnon n_trcr_strata ! number of underlying tracer layers real (kind=dbl_kind), dimension (:,:), intent(in) :: & - trcr_base ! = 0 or 1 depending on tracer dependency - ! argument 2: (1) aice, (2) vice, (3) vsno + trcr_base ! = 0 or 1 depending on tracer dependency + ! argument 2: (1) aice, (2) vice, (3) vsno integer (kind=int_kind), dimension (:,:), intent(in) :: & - nt_strata ! indices of underlying tracer layers + nt_strata ! indices of underlying tracer layers real (kind=dbl_kind), dimension (nblyr+2), intent(in) :: & - bgrid ! biology nondimensional vertical grid points + bgrid ! biology nondimensional vertical grid points real (kind=dbl_kind), dimension (nblyr+1), intent(in) :: & - igrid ! biology vertical interface points + igrid ! biology vertical interface points real (kind=dbl_kind), dimension (nilyr+1), intent(in) :: & - cgrid ! CICE vertical coordinate + cgrid ! CICE vertical coordinate real (kind=dbl_kind), dimension(:), intent(in) :: & salinz , & ! initial salinity profile @@ -2062,6 +2049,9 @@ icepack_step_therm2 frazil , & ! frazil ice growth (m/step-->cm/day) frazil_diag ! frazil ice growth diagnostic (m/step-->cm/day) + real (kind=dbl_kind), intent(in), optional :: & + wlat ! lateral melt rate (m/s) + real (kind=dbl_kind), dimension(:), intent(inout) :: & aicen_init,& ! initial concentration of ice vicen_init,& ! initial volume per unit area of ice (m) @@ -2075,14 +2065,7 @@ icepack_step_therm2 trcrn ! tracers logical (kind=log_kind), dimension(:), intent(inout) :: & - first_ice ! true until ice forms - - real (kind=dbl_kind), dimension(:), intent(out) :: & - ! change in floe size distribution (area) - d_afsd_latg , & ! due to fsd lateral growth - d_afsd_newi , & ! new ice formation - d_afsd_latm , & ! lateral melt - d_afsd_weld ! welding + first_ice ! true until ice forms real (kind=dbl_kind), intent(inout), optional :: & frz_onset ! day of year that freezing begins (congel or frazil) @@ -2092,12 +2075,34 @@ icepack_step_therm2 ! water isotopes real (kind=dbl_kind), dimension(:), intent(inout), optional :: & - fiso_ocn ! isotope flux to ocean (kg/m^2/s) + fiso_ocn ! isotope flux to ocean (kg/m^2/s) real (kind=dbl_kind), intent(in), optional :: & HDO_ocn , & ! ocean concentration of HDO (kg/kg) H2_16O_ocn , & ! ocean concentration of H2_16O (kg/kg) H2_18O_ocn ! ocean concentration of H2_18O (kg/kg) + + real (kind=dbl_kind), intent(in), optional :: & + wave_sig_ht ! significant height of waves in ice (m) + + real (kind=dbl_kind), dimension(:), intent(in), optional :: & + wave_spectrum ! ocean surface wave spectrum E(f) (m^2 s) + + real(kind=dbl_kind), dimension(:), intent(in), optional :: & + wavefreq, & ! wave frequencies (s^-1) + dwavefreq ! wave frequency bin widths (s^-1) + + real (kind=dbl_kind), dimension(:), intent(out), optional :: & + ! change in floe size distribution (area) + d_afsd_latg, & ! due to fsd lateral growth + d_afsd_newi, & ! new ice formation + d_afsd_latm, & ! lateral melt + d_afsd_weld ! welding + + real (kind=dbl_kind), dimension (:), intent(in), optional :: & + floe_rad_c, & ! fsd size bin centre in m (radius) + floe_binwidth ! fsd size bin width in m (radius) + icepack_therm_shared.F90 diff --git a/doc/source/user_guide/ug_testing.rst b/doc/source/user_guide/ug_testing.rst index edaed9ff1..08db08fe0 100755 --- a/doc/source/user_guide/ug_testing.rst +++ b/doc/source/user_guide/ug_testing.rst @@ -8,7 +8,7 @@ Testing Icepack This section documents primarily how to use the Icepack scripts to carry out icepack testing. Exactly what to test is a separate question and depends on the kinds of code changes being made. Prior to merging -changes to the CICE Consortium master, changes will be reviewed and +changes to the CICE Consortium main branch, changes will be reviewed and developers will need to provide a summary of the tests carried out. There is a base suite of tests provided by default with Icepack and this @@ -424,7 +424,7 @@ Test Suite Examples set mydate = `date -u "+%Y%m%d"` git clone https://github.com/myfork/icepack icepack.$mydate cd icepack.$mydate - ./icepack.setup --suite base_suite --mach conrad --env cray,gnu,intel,pgi --testid $mydate --bcmp default --bgen default --bdir /tmp/work/user/ICEPACK_BASELINES_MASTER + ./icepack.setup --suite base_suite --mach conrad --env cray,gnu,intel,pgi --testid $mydate --bcmp default --bgen default --bdir /tmp/work/user/ICEPACK_BASELINES_MAIN When this is invoked, a new set of baselines will be generated and compared to the prior results each time without having to change the arguments.