Merge pull request #23 from noaa-psd/psd/develop

Psd/develop

.travis.yml

@@ -0,0 +1,56 @@
+# This will run on Travis' 'new' container-based infrastructure
+sudo: false 
+
+before_install:
+    - wget http://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh
+    - chmod +x miniconda.sh
+    - "./miniconda.sh -b"
+    - export PATH=/home/travis/miniconda2/bin:$PATH
+    - conda update --yes conda
+
+install:
+    - conda install --yes sphinx
+    - pip install sphinx_rtd_theme
+
+# Blacklist
+branches:
+  only:
+    - ufs_public_release
+    - release/public-v1
+
+# Environment variables
+env:
+  global:
+    - GH_REPO_NAME: stochastic_physics
+    - DOXYFILE: $TRAVIS_BUILD_DIR/
+    - GH_REPO_REF: github.com/noaa-psd/stochastic_physics.git
+
+# Install dependencies
+addons:
+  apt:
+    packages:
+      - doxygen
+      - graphviz
+
+# Build your code e.g. by calling make
+script:
+    - doxygen
+    - pushd docs
+#   Use Sphinx to make the html docs
+    - make html
+#   Tell GitHub not to use jekyll to compile the docs
+    - touch build/html/.nojekyll
+    - popd
+
+# Generate and deploy documentation
+before_deploy:
+    - cp -r html docs/build/html/doxygen
+deploy:
+  provider: pages
+  skip_cleanup: true
+  local_dir: docs/build/html
+  github_token: $GH_REPO_TOKEN
+  on:
+    branch: 
+       - ufs_public_release
+       - release/public-v1

Doxyfile

@@ -0,0 +1,22 @@
+PROJECT_NAME           = "stochastic physics"
+PROJECT_NUMBER         = v1
+STRIP_FROM_PATH        = 
+INPUT                  = 
+FILE_PATTERNS          = *.md  \
+                         *.h   \
+                         *.doc \
+                         *.c   \
+                         *.f   \
+                         *.F90
+RECURSIVE              = YES
+USE_MDFILE_AS_MAINPAGE = README.md
+OPTIMIZE_FOR_FORTRAN   = YES
+GENERATE_XML           = NO  
+INLINE_SIMPLE_STRUCTS  = YES
+EXTRACT_ALL            = YES
+HAVE_DOT               = YES
+CALL_GRAPH             = YES
+CALLER_GRAPH           = YES
+PROJECT_LOGO           = docs/UFS_logo.png
+DISABLE_INDEX          = YES
+GENERATE_TREEVIEW      = YES

LICENSE.md

@@ -0,0 +1,21 @@
+Copyright 2020 The Regents of the University of Colorado
+
+The stochastic_physics code incorporated in the Unified Forecast System (UFS) 
+was jointly developed by the National Oceanic and Atmospheric Administration and the 
+University of Colorado, Boulder. The gold standard copy of the Code 
+will be maintained by NOAA at https://github.com/noaa-psd/stochastic_physics.
+
+In cooperation with the Copyright Holder, the National Oceanic and 
+Atmospheric Administration is releasing this code under the 
+GNU Lesser General PUblic License v3.0 (the "License"); you may not use this 
+file except in compliance with the License. 
+
+You may obtain a copy of the License at
+
+    https://www.gnu.org/licenses/lgpl-3.0.en.html
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License

compile_standalone

@@ -1,5 +1,5 @@
 #!/bin/sh -x
-compile_all=1
+compile_all=0
 FC=mpif90
 INCS="-I. -I../FV3/gfsphysics/ -I../FMS/include -I../FV3/atmos_cubed_sphere -I../FMS/fv3gfs"
 FLAGS64=" -traceback -real-size 64 -DSTOCHY_UNIT_TEST -c "$INCS
@@ -18,7 +18,6 @@ if [ $compile_all -eq 1 ];then
    $FC ${FLAGS64} setlats_lag_stochy.f
    $FC ${FLAGS64} glats_stochy.f
    $FC ${FLAGS64} gozrineo_stochy.f
-   $FC ${FLAGS64} num_parthds_stochy.f
    $FC ${FLAGS64} dezouv_stochy.f
    $FC ${FLAGS64} dozeuv_stochy.f
    $FC ${FLAGS64} epslon_stochy.f

compns_stochy.F90

@@ -1,10 +1,14 @@
+!>@brief The module 'compns_stochy_mod' contains the subroutine compns_stochy
 module compns_stochy_mod
 
    implicit none
 
    contains
 
 !-----------------------------------------------------------------------
+!>@brief The module 'compns_stochy_mod' set the default namelist options reads in the stochastic physics namelist
+!! and  sets logicals and other parameters based on the namelist
+!>@details Namelist can be either a file, or an internal namelist
       subroutine compns_stochy (me,sz_nml,input_nml_file,fn_nml,nlunit,deltim,iret)
 !$$$  Subprogram Documentation Block
 !

dezouv_stochy.f

@@ -1,9 +1,14 @@
+!>@brief The module 'dezouv_stochy_mod' contains the subroutine dezouv_stochy
+! of divergence and odd harmonics of vorticty
       module dezouv_stochy_mod
 
       implicit none
 
       contains
 
+!>@brief The subroutine 'dezouv_stochy' caculates even u and odd v winds harmonics from the even harmonics
+! of divergence and odd harmonics of vorticty
+!>@details This code is taken from the legacy spectral GFS
       subroutine dezouv_stochy(dev,zod,uev,vod,epsedn,epsodn,
      &                  snnp1ev,snnp1od,ls_node)
 cc

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/environment.yml

@@ -0,0 +1,7 @@
+name: stochast_physics-docs
+
+channels:
+  - conda-forge
+
+dependencies:
+  - breathe

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,70 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+#import os
+#import sys
+#sys.path.append( "/Users/ppegion/.local/bin" )
+#sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'UFS stochastic physics'
+copyright = '2020,  The Regents of the University of Colorado'
+author = 'Philip Pegion'
+
+# The full version, including alpha/beta/rc tags
+release = 'public'
+
+# assign master document
+
+master_doc = 'index'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+
+# create doxygen documentation
+#import subprocess
+#read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
+#print('read_the_docs_build',read_the_docs_build)
+#if read_the_docs_build:
+#    subprocess.call('cd ../../ ; doxygen', shell=True)
+#extensions = ['sphinx.ext.autodoc', 'breathe']
+##extensions = ['breathe']
+#breathe_projects = { "stochastic_physics": "../../xml/" }
+#breathe_default_project = "stochastic_physics"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+

docs/source/developers_guide.rst

@@ -0,0 +1,14 @@
+Developer's guide
+=================
+
+Code is housed on github at https://github.com/noaa-psd/stochastic_physics.  Please read more about the Development process at https://github.com/ufs-community/ufs/wiki/Development-Processes#Developing-with-Gitflow.
+
+Please make a fork and checkout the entire ufs-community weather model at https://github.com/ufs-community/ufs-weather-model and point to your fork of the stochastic_physics submodule.
+
+Standalone testing
+""""""""""""""""""
+If you intend to make modifications to the stochastic physics source code, there is a simplified program that exercises the random pattern generator without needing to run the entire model.  Please see README.standalone in the stochastic_physics directory.
+
+Full model tests
+""""""""""""""""
+The code updates are not expected to change existing results, so the full model regression tests need to be run.  All of the tests must pass, although only a sub-set of tests are needed to consider adding changes to the stochastic_physics repository: fv3_control, fv3_stochy, fv3_ccpp_control, and fv3_ccpp_stochy.  If the results are expected to change, then there needs to be scientific evidience that the change in results are what is expected.  

docs/source/getting_started.rst

@@ -0,0 +1,10 @@
+Getting Started
+==================================================
+The stochastic physics currently only works with the UFS-atmosphere model
+
+You should get the full system at https://github.com/ufs-community/ufs-weather-model, which will include the stochastic physics code.
+
+In order to enable stochastic physics in a model run, you will need to turn it on via `namelist options <namelist_options.html>`_
+
+If using the CIME workflow decribed at https://ufs-mrweather-app.readthedocs.io/en/latest/, please add do_sppt=T, etc. to user_nl_ufsatm in the case directory.
+

docs/source/index.rst

@@ -0,0 +1,18 @@
+Welcome to UFS stochastic physics's documentation!
+==================================================
+
+.. toctree::
+   :maxdepth: 2
+
+   getting_started
+   users_guide
+   namelist_options
+   developers_guide
+   references        
+
+
+Source Code Documentation
+==========================
+
+Doxygen generated `content <https://noaa-psd.github.io/stochastic_physics/doxygen/index.html>`_
+