sync of dev/gfdl with master (#130)

* Removing use of mpp_io_mod and fms_io_mod from the dycore code.  Replacing the necessary functions with fms2_io_mod functions

* Adding a call to set_filename_appendix so that nest is added to filename when needed and removing unneccessary code in fv_io_mod

* Updating dimension string arrays to address GNU compilation errors.

* correcting some typos, addressing comments from PR#74

* Adding Issue Templates

* Adding Code Style guide to the repository.

* FV3 Documentation
 - Formatted PDF and source files for FV3 documentation.
 - Revision 1.0a

* Updated defaults for hord options to use 8 and 10, and removal of mention of hord = 9, which is now a different (experimental, unsupported) scheme.

* Initialize {sw,se,nw,ne}_corner to .false in model/fv_arrays.F90
(cherry picked from commit bf0630f)

* merge of latest dev work from GFDL Weather and Climate Dynamics Division (#114)

* release notes updates in RELEASE.md

* Update README.md

* read ak/bk from user specified files (#115)

* add input.nml parameter fv_eta_file for user specified ak/bk; change ks calculation when npz_type=input; use newunit to replace fixed file unit for npz_type=input
(cherry picked from commit 3a0d35a)

* FV3 Example Notebooks and cleanup of docs directory (#117)

* removed module use of INPUT_STR_LENGTH in fv_control.F90 (#122)

* updates logic for file read of eta levels (#124)

* add check on eta levels to ensure their monotonicity

* update Jili Dong's ak/bk external input to
  - use the FMS ascii_read (single read/broadcast)
  - error check input to ensure the proper number of levels present

* merge of minor updates from GFDL Weather and Climate Dynamics Division (20210804) (#127)

* output conversion error warning in debug mode w/ Intel

* Makes the non-hydrostatic restart variables optional for reads to allow hydrostatic ICs

Co-authored-by: Lauren Chilutti <Lauren.Chilutti@noaa.gov>
Co-authored-by: laurenchilutti <60401591+laurenchilutti@users.noreply.github.com>
Co-authored-by: lharris4 <53020884+lharris4@users.noreply.github.com>
Co-authored-by: Dusan Jovic <dusan.jovic@noaa.gov>
Co-authored-by: Jili Dong <jili.dong@noaa.gov>
Co-authored-by: Tom Robinson <thomas.robinson@noaa.gov>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug Report
+about: Create a bug report to help us improve
+title: ''
+labels: Bug
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is
+
+**To Reproduce**
+Steps to reproduce the behavior
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**System Environment**
+Describe the system environment, include:
+- OS: [e.g. RHEL 7.2]
+- Compiler(s): Type and version [e.g. Intel 19.1]
+- MPI type, and version (e.g. MPICH, Cray MPI, openMPI)
+- netCDF Version: For both C and Fortran
+- Configure options: Any additional flags, or macros passed to configure
+
+**Additional context**
+Add any other context about the problem.  If applicable, include where any files
+that help describe, or reproduce the problem exist.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: 'enhancement'
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/support_request.md

@@ -0,0 +1,14 @@
+---
+name: Support request
+about: Request for help
+title: ''
+labels: 'question'
+assignees: ''
+---
+
+**Is your question related to a problem? Please describe.**
+A clear and concise description of what the problem is.
+
+**Describe what you have tried**
+A clear and concise description of what steps you have taken.  Include command
+lines, and any messages from the command.

CODE_STYLE.md

@@ -0,0 +1,127 @@
+# Coding Style
+
+## General
+
+* Trim all trailing whitespace from every line (some editors can do this
+  automatically).
+* No tab characters.
+* A copy of the FV3 Gnu Lesser General Public License Header
+  must be included at the top of each file.
+* Supply an author block for each file with a description of the file and the author(s)
+  name or GitHub ID.
+* Documentation may be written so that it can be parsed by [Doxygen](http://www.doxygen.nl/).
+* All variables should be defined, and include units. Unit-less variables should be marked `unitless`
+* Provide detailed descriptions of modules, interfaces, functions, and subroutines
+* Define all function/subroutine arguments, and function results (see below)
+* Follow coding style of the current file, as much as possible.
+
+## Fortran
+
+### General
+
+* Use Fortran 95 standard or newer
+* Two space indentation
+* Never use implicit variables (i.e., always specify `IMPLICIT NONE`)
+* Lines must be <= 120 characters long (including comments)
+* logical, compound logical, and relational if statements may be one line,
+  using “&” for line continuation if necessary:
+  ```Fortran
+  if(file_exists(fileName)) call open_file(fileObj,fileName, is_restart=.false)
+  ```
+* Avoid the use of `GOTO` statements
+* Avoid the use of Fortran reserved words as variables (e.g. `DATA`, `NAME`)
+* `COMMON` blocks should never be used
+
+### Derived types
+
+* Type names must be in CapitalWord format.
+* Description on the line before the type definition.
+* Inline doxygen descriptions for all member variables.
+
+## Functions
+* Functions should include a result variable on its own line, that does not have
+  a specific intent.
+* Inline descriptions for all arguments, except the result variable.
+* Description on the line(s) before the function definition.  Specify what the function is returning (with the `@return` doxygen keyword if using doxygen).
+
+## Blocks
+* terminate `do` loops with `enddo`
+* terminate block `if`, `then` statements with `endif`
+
+## OpenMP
+
+* All openMP directives should specify default(none), and then explicitly list
+  all shared and private variables.
+* All critical sections must have a unique name.
+
+## Fortran Example
+
+```Fortran
+
+!***********************************************************************
+!*                   GNU Lesser General Public License
+!*
+!* This file is part of the FV3 dynamical core.
+!*
+!* The FV3 dynamical core is free software: you can redistribute it
+!* and/or modify it under the terms of the
+!* GNU Lesser General Public License as published by the
+!* Free Software Foundation, either version 3 of the License, or
+!* (at your option) any later version.
+!*
+!* The FV3 dynamical core is distributed in the hope that it will be
+!* useful, but WITHOUT ANYWARRANTY; without even the implied warranty
+!* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+!* See the GNU General Public License for more details.
+!*
+!* You should have received a copy of the GNU Lesser General Public
+!* License along with the FV3 dynamical core.
+!* If not, see <http://www.gnu.org/licenses/>.
+
+!***********************************************************************
+
+!> @file
+!! @brief Example code
+!! @author <developer>
+!! @email <email>
+
+module example_mod
+  use util_mod, only: util_func1
+  implicit none
+  private
+
+  public :: sub1
+  public :: func1
+
+  !> @brief Doxygen description of type.
+  type,public :: CustomType
+    integer(kind=<KIND>) :: a_var !< Inline doxygen description.
+    real(kind=<KIND>),dimension(:),allocatable :: b_arr !< long description
+                                                        !! continued on
+                                                        !! multiple lines.
+  endtype CustomType
+
+  contains
+
+  !> @brief Doxygen description.
+  subroutine sub1(arg1, &
+    & arg2, &
+    & arg3)
+    real(kind=<KIND>),intent(in) :: arg1 !< Inline doxygen description.
+    integer(kind=<KIND>),intent(inout) :: arg2 !< Inline doxygen description.
+    character(len=*),intent(inout) :: arg3 !< Long inline doxygen
+                                           !! description.
+  end subroutine sub1
+
+  !> @brief Doxygen description
+  !! @return Function return value.
+  function func1(arg1, &
+    & arg2) &
+    & result(res)
+    integer(kind=<KIND>),intent(in) :: arg1 !< Inline doxygen description
+    integer(kind=<KIND>),intent(in) :: arg2 !< Inline doxygen description
+    integer(kind=<KIND>) :: res
+  end function func1
+
+end module example_mod
+```

GFDL_tools/fv_diag_column.F90

@@ -381,7 +381,7 @@ subroutine debug_column(pt, delp, delz, u, v, w, q, npz, ncnst, sphum, nwat, zvi
        write(unit, *) '==================================================================='
        write(unit, *)
        flush(unit)
- 
+
     enddo
 
   end subroutine debug_column

README.md

@@ -4,11 +4,19 @@ The source contained herein merges in the [2021 January Release](https://github.
 
 # Where to find information
 
-Visit the [FV3 website](https://www.gfdl.noaa.gov/fv3/) for more information. Reference material is available at [FV3 documentation and references](https://www.gfdl.noaa.gov/fv3/fv3-documentation-and-references/). 
+Visit the [FV3 website](https://www.gfdl.noaa.gov/fv3/) for more information. Reference material is available at [FV3 documentation and references](https://www.gfdl.noaa.gov/fv3/fv3-documentation-and-references/).
 
 # Proper usage attribution
 
-Cite Putman and Lin (2007) and Harris and Lin (2013) when describing a model using the FV3 dynamical core.
+Cite _Putman and Lin (2007)_ and _Harris and Lin (2013)_ when describing a model using the FV3 dynamical core.
+
+Cite _Chen et al (2013)_ and _Zhou et al (2019)_ when using the GFDL Microphysics.
+
+# Documentation
+
+The up-to-date FV3 Scientific reference guide is included in LaTex and PDF formats in the ```docs/``` directory. There are also some notebooks in docs/examples demonstrating basic FV3 capabilities and analysis techniques.
+
+A [DOI referenceable version](https://doi.org/10.25923/6nhs-5897) is available in the [_NOAA Institutional Repository_](https://repository.library.noaa.gov/view/noaa/30725)
 
 # What files are what
 
@@ -23,12 +31,7 @@ The top level directory structure groups source code and input files as follow:
 | ```driver/```        | contains drivers used by different models/modeling systems |
 | ```tools/```         | contains source code of tools used within the core |
 | ```GFDL_tools/```    | contains source code of tools specific to GFDL models |
-| ```docs/```          | contains documentation for the FV3 dynamical core |
-
-# Generating PDF Documentation
-To update the ```refmans.pdf``` file:
-1. In the ```docs/``` directory enter the command ```doxygen Doxyfile```
-2. Navigate to the ```latex/``` directory and enter the command ```make pdf```
+| ```docs/```          | contains documentation for the FV3 dynamical core, and Python notebooks demonstrating basic capabilities. |
 
 # Dependencies
 

RELEASE.md

@@ -1,5 +1,22 @@
 # RELEASE NOTES for GFDL FV3: Summary
 
+# RELEASE NOTES for GFDL_2021.03.01: Summary
+GFDL_2021.03.01 --- August 2021
+
+This version has been tested within the current GFDL Models (AM4+, CM4+, ESM4+, SPEAR, etc.) and requires a
+release of the [FMS infrastructure](https://github.com/NOAA-GFDL/FMS) 2021.03 or greater.
+
+This release includes the following:
+
+- Comprehensive documentation in LaTEX format (FV3 team)
+- Default changes to some namelist options and updated inline documentation
+- Multiple same-level and telescoping nests for the Regional domain (J Mouallem)
+- Updated fms2_io functionality (L Chilutti)
+- Revised Regional domain code (K-Y Cheng)
+- Reproducibility fixes for global+nests and regional+nests (tested for absolute reproducibility across PE counts, restarts)
+- Other updates and general cleanup
+
+
 # RELEASE NOTES for GFDL_2021.01: Summary
 GFDL_2021.01 --- April 2021
 
@@ -12,16 +29,15 @@ Includes all of the features from the [202101 Public Release](https://github.com
 - In-line GFDL Microphysics
 - Fast-timescale Rayleigh damping
 - Updated namelist documentation
-- Implemented multiple same-level and telescoping nests for the global system (from J Mouallem)
-- Updated coarse-graining capabilities (from S Clark)
+- Implemented multiple same-level and telescoping nests for the global system (J Mouallem)
+- Updated coarse-graining capabilities (S Clark)
 - Re-organized fv_diagnostics, moving the revised fv_diag_column functionality and the declaration of diagnostic IDs to separate files
 - and other updates and general cleanup
 
 This version of FV3 is described as component of SHiELD in Harris et al. (2020, JAMES).
 
 
 # RELEASE NOTES for 2020.02: Summary
-
 2020.02 --- 22 April 2020
 
 This version has been tested within current GFDL Models (AM4+, CM4+, ESM4+, SPEAR, etc.) and requires the 2020.02 release of the [FMS infrastructure](https://github.com/NOAA-GFDL/FMS).
@@ -47,7 +63,3 @@ Includes all of the features from the [201912 Public Release](https://github.com
   - has been removed
 
 Update your build system as appropriate
-
-# Documentation
-
-For a complete technical description see the NOAA Technical Memorandum OAR GFDL: https://repository.library.noaa.gov/view/noaa/23432

docs/doc_source/README

@@ -0,0 +1 @@
+These are LaTeX and BibTeX source files and associated graphics files. They should not require any special LaTeX packages not present in current TeX distributions.