From 21fab166fd2b8e903df366dbc1c518dabd08c23f Mon Sep 17 00:00:00 2001 From: Tony Craig Date: Tue, 28 Nov 2023 10:04:36 -0800 Subject: [PATCH] Update Icepack to #f6ff8f7c4d4cb6f (#913) * Update Icepack to #f6ff8f7c4d4cb6f Split the developer guide infrastructure section from the dynamics documentation Add a coding standard section to the documentation Add a couple sentences about the state of the parameter nghost to the documentation Update opticep to use the latest main code for the unit test * update documentation --- .../unittest/opticep/ice_init_column.F90 | 2 + .../drivers/unittest/opticep/ice_step_mod.F90 | 3 +- doc/source/developer_guide/dg_about.rst | 50 +++++++++++ doc/source/developer_guide/dg_dynamics.rst | 79 ----------------- doc/source/developer_guide/dg_infra.rst | 84 +++++++++++++++++++ doc/source/developer_guide/index.rst | 1 + doc/source/user_guide/ug_implementation.rst | 4 +- icepack | 2 +- 8 files changed, 142 insertions(+), 83 deletions(-) create mode 100644 doc/source/developer_guide/dg_infra.rst diff --git a/cicecore/drivers/unittest/opticep/ice_init_column.F90 b/cicecore/drivers/unittest/opticep/ice_init_column.F90 index cb9b93df1..a55338556 100644 --- a/cicecore/drivers/unittest/opticep/ice_init_column.F90 +++ b/cicecore/drivers/unittest/opticep/ice_init_column.F90 @@ -1593,6 +1593,8 @@ subroutine input_zbgc write(nu_diag,1005) ' phi_snow = ', phi_snow endif write(nu_diag,1010) ' solve_zsal (deprecated) = ', solve_zsal + write(nu_diag,* ) ' WARNING: zsalinity has been deprecated. Namelists and interfaces' + write(nu_diag,* ) ' will be removed in a future version' write(nu_diag,1010) ' skl_bgc = ', skl_bgc write(nu_diag,1010) ' restart_bgc = ', restart_bgc diff --git a/cicecore/drivers/unittest/opticep/ice_step_mod.F90 b/cicecore/drivers/unittest/opticep/ice_step_mod.F90 index 5b85cb7bf..370fde6be 100644 --- a/cicecore/drivers/unittest/opticep/ice_step_mod.F90 +++ b/cicecore/drivers/unittest/opticep/ice_step_mod.F90 @@ -618,7 +618,7 @@ subroutine step_therm2 (dt, iblk) use ice_calendar, only: yday use ice_domain_size, only: ncat, nilyr, nslyr, nblyr, nfsd use ice_flux, only: fresh, frain, fpond, frzmlt, frazil, frz_onset, & - update_ocn_f, fsalt, Tf, sss, salinz, fhocn, rside, fside, wlat, & + fsalt, Tf, sss, salinz, fhocn, rside, fside, wlat, & meltl, frazil_diag use ice_flux_bgc, only: flux_bio, faero_ocn, & fiso_ocn, HDO_ocn, H2_16O_ocn, H2_18O_ocn @@ -709,7 +709,6 @@ subroutine step_therm2 (dt, iblk) fresh = fresh (i,j, iblk), & fsalt = fsalt (i,j, iblk), & fhocn = fhocn (i,j, iblk), & - update_ocn_f = update_ocn_f, & bgrid = bgrid, & cgrid = cgrid, & igrid = igrid, & diff --git a/doc/source/developer_guide/dg_about.rst b/doc/source/developer_guide/dg_about.rst index 37318b2c5..95645d45d 100644 --- a/doc/source/developer_guide/dg_about.rst +++ b/doc/source/developer_guide/dg_about.rst @@ -25,3 +25,53 @@ There is extensive Information for Developers documentation available. See http - Software development practices guide - git Workflow Guide - including extensive information about the Pull Request process and requirements - Documentation Workflow Guide + + +Coding Standard +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Overall, CICE code should be implemented as follows, + + * Adhere to the current coding and naming conventions + + * Write readable code. Use meaningful variable names; indent 2 or 3 spaces for loops and conditionals; vertically align similar elements where it makes sense, and provide concise comments throughout the code. + + * Declare common parameters in a shared module. Do not hardwire the same parameter in the code in multiple places. + + * Maintain bit-for-bit output for the default configuration (to the extent possible). Use namelist options to add new features. + + * Maintain global conservation of heat, water, salt + + * Use of C preprocessor (CPP) directives should be minimized and only used for build dependent modifications such as use of netcdf (or other "optional" libraries) or for various Fortran features that may not be supported by some compilers. Use namelist to support run-time code options. CPPs should be all caps. + + * All modules should have the following set at the top + + .. code-block:: fortran + + implicit none + private + + Any public module interfaces or data should be explicitly specified + + * All subroutines and functions should define the subname character parameter statement to match the interface name like + + .. code-block:: fortran + + character(len=*),parameter :: subname='(advance_timestep)' + + * Public Icepack interfaces should be accessed thru the icepack_intfc module like + + .. code-block:: fortran + + use icepack_intfc, only: icepack_init_parameters + + * Icepack does not write to output or abort, it provides methods to access those features. After each call to Icepack, **icepack_warnings_flush** should be called to flush Icepack output to the CICE log file and **icepack_warnings_aborted** should be check to abort on an Icepack error as follows, + + .. code-block:: fortran + + call icepack_physics() + call icepack_warnings_flush(nu_diag) + if (icepack_warnings_aborted()) call abort_ice(error_message=subname, file=__FILE__, line=__LINE__) + + * Use of new Fortran features or external libraries need to be balanced against usability and the desire to compile on as many machines and compilers as possible. Developers are encouraged to contact the Consortium as early as possible to discuss requirements and implementation in this case. + diff --git a/doc/source/developer_guide/dg_dynamics.rst b/doc/source/developer_guide/dg_dynamics.rst index 1f1430e71..2c886a95f 100644 --- a/doc/source/developer_guide/dg_dynamics.rst +++ b/doc/source/developer_guide/dg_dynamics.rst @@ -46,82 +46,3 @@ upwind and remap. These are set in namelist via the ``advection`` variable. Transport can be disabled with the ``ktransport`` namelist variable. -Infrastructure -======================= - -Kinds ------------------- - -**cicecore/shared/ice_kinds_mod.F90** defines the kinds datatypes used in CICE. These kinds are -used throughout CICE code to define variable types. The CICE kinds are adopted from the kinds -defined in Icepack for consistency in interfaces. - -Constants ------------------- - -**cicecore/shared/ice_constants.F90** defines several model constants. Some are hardwired parameters -while others have internal defaults and can be set thru namelist. - -Dynamic Array Allocation -------------------------------- - -CICE v5 and earlier was implemented using mainly static arrays and required several CPPs to be set to define grid size, -blocks sizes, tracer numbers, and so forth. With CICE v6 and later, arrays are dynamically allocated and those -parameters are namelist settings. The following CPPs are no longer used in CICE v6 and later versions, - - -DNXGLOB=100 -DNYGLOB=116 -DBLCKX=25 -DBLCKY=29 -DMXBLCKS=4 -DNICELYR=7 -DNSNWLYR=1 -DNICECAT=5 -DTRAGE=1 -DTRFY=1 -DTRLVL=1 -DTRPND=1 -DTRBRI=0 -DNTRAERO=1 -DTRZS=0 -DNBGCLYR=7 -DTRALG=0 -DTRBGCZ=0 -DTRDOC=0 -DTRDOC=0 -DTRDIC=0 -DTRDON=0 -DTRFED=0 -DTRFEP=0 -DTRZAERO=0 -DTRBGCS=0 -DNUMIN=11 -DNUMAX=99 - -as they have been migrated to :ref:`tabnamelist` - - nx_global, ny_global, block_size_x, block_size_y, max_blocks, nilyr, nslyr, ncat, nblyr, n_aero, n_zaero, n_algae, n_doc, n_dic, n_don, n_fed, n_fep, numin, numax - - -Time Manager ------------------- - -Time manager data is module data in **cicecore/shared/ice_calendar.F90**. Much of the time manager -data is public and operated on during the model timestepping. The model timestepping actually takes -place in the **CICE_RunMod.F90** file which is part of the driver code. - -The time manager was updated in early 2021. Additional information about the time manager can be found here, :ref:`timemanagerplus` - - - -Communication ------------------- - -Two low-level communications packages, mpi and serial, are provided as part of CICE. This software -provides a middle layer between the model and the underlying libraries. Only the CICE mpi or -serial directories are compiled with CICE, not both. - -**cicedyn/infrastructure/comm/mpi/** -is based on MPI and provides various methods to do halo updates, global sums, gather/scatter, broadcasts -and similar using some fairly generic interfaces to isolate the MPI calls in the code. - -**cicedyn/infrastructure/comm/serial/** support the same interfaces, but operates -in shared memory mode with no MPI. The serial library will be used, by default in the CICE scripts, -if the number of MPI tasks is set to 1. The serial library allows the model to be run on a single -core or with OpenMP parallelism only without requiring an MPI library. - -I/O ------------------- - -There are three low-level IO packages in CICE, io_netcdf, io_binary, and io_pio. This software -provides a middle layer between the model and the underlying IO writing. -Only one of the three IO directories can be built with CICE. The CICE scripts will build with the io_netcdf -by default, but other options can be selecting by setting ``ICE_IOTYPE`` in **cice.settings** in the -case. This has to be set before CICE is built. - -**cicedyn/infrastructure/io/io_netcdf/** is the -default for the standalone CICE model, and it supports writing history and restart files in netcdf -format using standard netcdf calls. It does this by writing from and reading to the root task and -gathering and scattering fields from the root task to support model parallelism. - -**cicedyn/infrastructure/io/io_binary/** supports files in binary format using a gather/scatter -approach and reading to and writing from the root task. - -**cicedyn/infrastructure/io/io_pio/** support reading and writing through the pio interface. pio -is a parallel io library (https://github.com/NCAR/ParallelIO) that supports reading and writing of -binary and netcdf file through various interfaces including netcdf and pnetcdf. pio is generally -more parallel in memory even when using serial netcdf than the standard gather/scatter methods, -and it provides parallel read/write capabilities by optionally linking and using pnetcdf. diff --git a/doc/source/developer_guide/dg_infra.rst b/doc/source/developer_guide/dg_infra.rst new file mode 100644 index 000000000..c38e2c16d --- /dev/null +++ b/doc/source/developer_guide/dg_infra.rst @@ -0,0 +1,84 @@ +:tocdepth: 3 + +.. _dev_infra: + + +Infrastructure +======================= + +Kinds +------------------ + +**cicecore/shared/ice_kinds_mod.F90** defines the kinds datatypes used in CICE. These kinds are +used throughout CICE code to define variable types. The CICE kinds are adopted from the kinds +defined in Icepack for consistency in interfaces. + +Constants +------------------ + +**cicecore/shared/ice_constants.F90** defines several model constants. Some are hardwired parameters +while others have internal defaults and can be set thru namelist. + +Dynamic Array Allocation +------------------------------- + +CICE v5 and earlier was implemented using mainly static arrays and required several CPPs to be set to define grid size, +blocks sizes, tracer numbers, and so forth. With CICE v6 and later, arrays are dynamically allocated and those +parameters are namelist settings. The following CPPs are no longer used in CICE v6 and later versions, + + -DNXGLOB=100 -DNYGLOB=116 -DBLCKX=25 -DBLCKY=29 -DMXBLCKS=4 -DNICELYR=7 -DNSNWLYR=1 -DNICECAT=5 -DTRAGE=1 -DTRFY=1 -DTRLVL=1 -DTRPND=1 -DTRBRI=0 -DNTRAERO=1 -DTRZS=0 -DNBGCLYR=7 -DTRALG=0 -DTRBGCZ=0 -DTRDOC=0 -DTRDOC=0 -DTRDIC=0 -DTRDON=0 -DTRFED=0 -DTRFEP=0 -DTRZAERO=0 -DTRBGCS=0 -DNUMIN=11 -DNUMAX=99 + +as they have been migrated to :ref:`tabnamelist` + + nx_global, ny_global, block_size_x, block_size_y, max_blocks, nilyr, nslyr, ncat, nblyr, n_aero, n_zaero, n_algae, n_doc, n_dic, n_don, n_fed, n_fep, numin, numax + + +Time Manager +------------------ + +Time manager data is module data in **cicecore/shared/ice_calendar.F90**. Much of the time manager +data is public and operated on during the model timestepping. The model timestepping actually takes +place in the **CICE_RunMod.F90** file which is part of the driver code. + +The time manager was updated in early 2021. Additional information about the time manager can be found here, :ref:`timemanagerplus` + + + +Communication +------------------ + +Two low-level communications packages, mpi and serial, are provided as part of CICE. This software +provides a middle layer between the model and the underlying libraries. Only the CICE mpi or +serial directories are compiled with CICE, not both. + +**cicedyn/infrastructure/comm/mpi/** +is based on MPI and provides various methods to do halo updates, global sums, gather/scatter, broadcasts +and similar using some fairly generic interfaces to isolate the MPI calls in the code. + +**cicedyn/infrastructure/comm/serial/** support the same interfaces, but operates +in shared memory mode with no MPI. The serial library will be used, by default in the CICE scripts, +if the number of MPI tasks is set to 1. The serial library allows the model to be run on a single +core or with OpenMP parallelism only without requiring an MPI library. + +I/O +------------------ + +There are three low-level IO packages in CICE, io_netcdf, io_binary, and io_pio. This software +provides a middle layer between the model and the underlying IO writing. +Only one of the three IO directories can be built with CICE. The CICE scripts will build with the io_netcdf +by default, but other options can be selecting by setting ``ICE_IOTYPE`` in **cice.settings** in the +case. This has to be set before CICE is built. + +**cicedyn/infrastructure/io/io_netcdf/** is the +default for the standalone CICE model, and it supports writing history and restart files in netcdf +format using standard netcdf calls. It does this by writing from and reading to the root task and +gathering and scattering fields from the root task to support model parallelism. + +**cicedyn/infrastructure/io/io_binary/** supports files in binary format using a gather/scatter +approach and reading to and writing from the root task. + +**cicedyn/infrastructure/io/io_pio/** support reading and writing through the pio interface. pio +is a parallel io library (https://github.com/NCAR/ParallelIO) that supports reading and writing of +binary and netcdf file through various interfaces including netcdf and pnetcdf. pio is generally +more parallel in memory even when using serial netcdf than the standard gather/scatter methods, +and it provides parallel read/write capabilities by optionally linking and using pnetcdf. diff --git a/doc/source/developer_guide/index.rst b/doc/source/developer_guide/index.rst index 6fc3356f4..680746beb 100644 --- a/doc/source/developer_guide/index.rst +++ b/doc/source/developer_guide/index.rst @@ -13,6 +13,7 @@ Developer Guide dg_about.rst dg_dynamics.rst + dg_infra.rst dg_driver.rst dg_forcing.rst dg_icepack.rst diff --git a/doc/source/user_guide/ug_implementation.rst b/doc/source/user_guide/ug_implementation.rst index ab1d2fcc3..af246ccff 100644 --- a/doc/source/user_guide/ug_implementation.rst +++ b/doc/source/user_guide/ug_implementation.rst @@ -192,7 +192,9 @@ recommend that the user choose the local domains so that the global domain is evenly divided, if this is not possible then the furthest east and/or north blocks will contain nonphysical points (“padding”). These points are excluded from the computation domain and have little effect -on model performance. +on model performance. ``nghost`` is a hardcoded parameter in **ice_blocks.F90**. +While the halo code has been implemented to support arbitrary sized halos, +``nghost`` is set to 1 and has not been formally tested on larger halos. .. _fig-grid: diff --git a/icepack b/icepack index d1a42fb14..f6ff8f7c4 160000 --- a/icepack +++ b/icepack @@ -1 +1 @@ -Subproject commit d1a42fb142033ca8c82a3f440ed38c63d992a314 +Subproject commit f6ff8f7c4d4cb6feabe3651b13204cf43fc948e3