merge of master into dev/emc

.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
+```

README.md

@@ -2,14 +2,22 @@
 
 This is for the FV3 dynamical core and the GFDL Microphysics for use by NCEP/EMC within GFS.
 The source in this branch reflects the codebase used by NCEP/EMC for use in GFS and UFS.
+
 # 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 Chen et al (2013) and Zhou et al (2019) when using the GFDL Microphysics.
+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
 
@@ -22,7 +30,7 @@ The top level directory structure groups source code and input files as follow:
 | ```model/```         | contains the source code for core of the FV3 dyanmical core |
 | ```driver/```        | contains drivers used by different models/modeling systems |
 | ```tools/```         | contains source code of tools used within the core |
-| ```docs/```          | contains documentation for the FV3 dynamical core |
+| ```docs/```          | contains documentation for the FV3 dynamical core, and Python notebooks demonstrating basic capabilities. |
 
 # Disclaimer