Add auto-doc and containerization of unit tests features

.github/workflows/auto_doc.yml

@@ -0,0 +1,29 @@
+name: Automated documentation build
+
+on: 
+
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build HTML
+      uses: ammaraskar/sphinx-action@master
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v3
+      with:
+        name: html-docs
+        path: docs/build/html/
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/master'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html

.github/workflows/build_container.yml

@@ -0,0 +1,21 @@
+name:  Build stochastic physics unit test image (Docker) 
+
+on:
+  # run it on push to the default repository branch
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write    
+    name: Build docker stochastic physics unit test image
+    steps:
+      - uses: actions/checkout@v2          
+      - name: docker build stochastic_physics unit test image
+        run: | 
+         echo "docker build stochastic_physics unit test image"
+         docker build -t stochastic_physics_test -f ./unit_tests/Dockerfile .

docs/requirements.txt

@@ -0,0 +1 @@
+furo==2021.11.16

docs/source/conf.py

@@ -61,7 +61,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+#jk 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,

stochastic_physics.F90

@@ -48,18 +48,17 @@ subroutine init_stochastic_physics(levs, blksz, dtp, sppt_amp, input_nml_file_in
 character(len=*),         intent(in)    :: fn_nml
 real(kind=kind_phys), intent(in)    :: xlon(:,:)
 real(kind=kind_phys), intent(in)    :: xlat(:,:)
-logical,                  intent(in)    :: do_sppt_in, do_shum_in, do_skeb_in ,do_spp_in
+logical,                  intent(in), optional    :: do_sppt_in, do_shum_in, do_skeb_in ,do_spp_in
 integer,                  intent(in)    :: lndp_type_in, n_var_lndp_in
-integer,                  intent(in)    :: n_var_spp_in
+integer,                  intent(in), optional :: n_var_spp_in
 real(kind=kind_phys), intent(in)    :: ak(:), bk(:) 
 logical,                  intent(out)   :: use_zmtnblck_out
-integer,                  intent(out)   :: skeb_npass_out
+integer,                  intent(out) :: skeb_npass_out
 character(len=3),         dimension(:), intent(out) :: lndp_var_list_out
 real(kind=kind_phys), dimension(:), intent(out) :: lndp_prt_list_out
-character(len=3),         dimension(:), intent(out) :: spp_var_list_out
-real(kind=kind_phys), dimension(:), intent(out) :: spp_prt_list_out
-real(kind=kind_phys), dimension(:), intent(out) :: spp_stddev_cutoff_out
-
+character(len=3),         dimension(:), intent(out), optional :: spp_var_list_out
+real(kind=kind_phys), dimension(:), intent(out), optional :: spp_prt_list_out
+real(kind=kind_phys), dimension(:), intent(out), optional :: spp_stddev_cutoff_out
 
 ! Local variables
 real(kind=kind_phys), parameter     :: con_pi =4.0d0*atan(1.0d0)
@@ -351,13 +350,13 @@ subroutine run_stochastic_physics(levs, kdt, fhour, blksz, sppt_wts, shum_wts, s
 integer,                  intent(in) :: levs, kdt
 real(kind=kind_phys), intent(in) :: fhour
 integer,                  intent(in) :: blksz(:)
-real(kind=kind_phys), intent(inout) :: sppt_wts(:,:,:)
-real(kind=kind_phys), intent(inout) :: shum_wts(:,:,:)
-real(kind=kind_phys), intent(inout) :: skebu_wts(:,:,:)
-real(kind=kind_phys), intent(inout) :: skebv_wts(:,:,:)
-real(kind=kind_phys), intent(inout) :: sfc_wts(:,:,:)
-real(kind=kind_phys), intent(inout) :: spp_wts(:,:,:,:)
-integer,                  intent(in)    :: nthreads
+real(kind=kind_phys), intent(inout), optional :: sppt_wts(:,:,:)
+real(kind=kind_phys), intent(inout), optional :: shum_wts(:,:,:)
+real(kind=kind_phys), intent(inout), optional :: skebu_wts(:,:,:)
+real(kind=kind_phys), intent(inout), optional :: skebv_wts(:,:,:)
+real(kind=kind_phys), intent(inout), optional :: sfc_wts(:,:,:)
+real(kind=kind_phys), intent(inout), optional :: spp_wts(:,:,:,:)
+integer,                 intent(in), optional :: nthreads
 
 real(kind_dbl_prec),allocatable :: tmp_wts(:,:),tmpu_wts(:,:,:),tmpv_wts(:,:,:),tmpl_wts(:,:,:),tmp_spp_wts(:,:,:)
 !D-grid

unit_tests/Dockerfile

@@ -0,0 +1,15 @@
+From noaaepic/ubuntu20.04-gnu9.3-hpc-stack:v1.2
+
+CMD ["/bin/bash"]
+
+ENV HOME=/home/builder
+
+COPY --chown=builder:builder . $HOME/stochastic_physics
+
+USER builder
+
+ENV USER=builder
+
+WORKDIR $HOME/stochastic_physics/unit_tests
+
+RUN /bin/sh -c $HOME/stochastic_physics/unit_tests/build_standalone.sh

unit_tests/build_standalone.sh

@@ -0,0 +1,45 @@
+#!/bin/sh
+compile_all=1
+DEBUG=1
+
+#rm standalone_stochy.x
+FMS_ROOT=/home/builder/opt
+NETCDF=/home/builder/opt
+echo ${FMS_ROOT}
+FC=mpif90
+FMS_INC=${FMS_ROOT}/include_r4
+FMS_LIB=${FMS_ROOT}/lib
+INCS="-I. -I${FMS_INC} -I${NETCDF}/include"
+if [ $DEBUG -eq 1 ]; then
+   FLAGS="-DDEBUG -ggdb -fbacktrace -cpp -fcray-pointer -ffree-line-length-none -fno-range-check -fdefault-real-8 -fdefault-double-8 -g -O0 -fno-unsafe-math-optimizations -frounding-math -fsignaling-nans -ffpe-trap=invalid,zero,overflow -fbounds-check -I. -fopenmp -c -Wargument-mismatch "$INCS
+else
+   FLAGS="-ggdb -fbacktrace -cpp -fcray-pointer -ffree-line-length-none -fno-range-check -O2 -fdefault-real-8 -O2 -fPIC -fopenmp -c -Wargument-mismatch "$INCS
+fi
+cd ..
+if [ $compile_all -eq 1 ];then
+   rm -f *.i90 *.i *.o *.mod lib*a
+   $FC ${FLAGS} kinddef.F90
+   $FC ${FLAGS} mpi_wrapper.F90
+   $FC ${FLAGS} unit_tests/fv_arrays_stub.F90
+   $FC ${FLAGS} unit_tests/fv_mp_stub_mod.F90
+   $FC ${FLAGS} unit_tests/fv_control_stub.F90
+   $FC ${FLAGS} unit_tests/atmosphere_stub.F90
+   $FC ${FLAGS} mersenne_twister.F90
+   $FC ${FLAGS} stochy_internal_state_mod.F90
+   $FC ${FLAGS} stochy_namelist_def.F90
+   $FC ${FLAGS} spectral_transforms.F90
+   $FC ${FLAGS} compns_stochy.F90
+   $FC ${FLAGS} stochy_patterngenerator.F90
+   $FC ${FLAGS} stochy_data_mod.F90
+   $FC ${FLAGS} get_stochy_pattern.F90
+   $FC ${FLAGS} lndp_apply_perts.F90
+   $FC ${FLAGS} stochastic_physics.F90
+fi
+ar rv libstochastic_physics.a *.o
+if [ $DEBUG -eq 1 ]; then
+   $FC -fdec -ggdb -fbacktrace -cpp -fcray-pointer -ffree-line-length-none -fno-range-check -fdefault-real-8 -fdefault-double-8 -g -O0 -fno-unsafe-math-optimizations -frounding-math -fsignaling-nans -ffpe-trap=invalid,zero,overflow -fbounds-check -I. -fopenmp -o unit_tests/standalone_stochy.x unit_tests/standalone_stochy.F90 ${INCS} -I${NETCDF}/include -L. -lstochastic_physics -L${FMS_LIB} -lfms_r4 -L${ESMF_LIB} -Wl,-rpath,${ESMF_LIB} -lesmf -L${NETCDF}/lib -lnetcdff -lnetcdf -L${HDF5_LIBRARIES} -lhdf5_hl -lhdf5 \
+-L${ZLIB_LIBRARIES} -lz -ldl
+else
+   $FC -fdec -fbacktrace -cpp -fcray-pointer -ffree-line-length-none -fno-range-check -fdefault-real-8 -fdefault-double-8 -g -O2 -I. -fopenmp -o unit_tests/standalone_stochy.x unit_tests/standalone_stochy.F90 ${INCS} -I${NETCDF}/include -L. -lstochastic_physics -L${FMS_LIB} -lfms_r4 -L${ESMF_LIB} -Wl,-rpath,${ESMF_LIB} -lesmf -L${NETCDF}/lib -lnetcdff -lnetcdf -L${HDF5_LIBRARIES} -lhdf5_hl -lhdf5 \
+-L${ZLIB_LIBRARIES} -lz -ldl
+fi

unit_tests/standalone_stochy.F90

@@ -179,11 +179,7 @@ program  standalone_stochy
 allocate(input_nml_file(1))
 input_nml_file='input.nml'
 comm=MPI_COMM_WORLD
-call init_stochastic_physics(nlevs, blksz, dtp, sppt_amp,                         &
-     input_nml_file, fn_nml, nlunit, xlon, xlat, do_sppt, do_shum,                &
-     do_skeb, lndp_type, n_var_lndp, use_zmtnblck, skeb_npass, &
-     lndp_var_list, lndp_prt_list,    &
-     ak, bk, nthreads, root_pe, comm, ierr)
+call init_stochastic_physics(nlevs, blksz, dtp, sppt_amp, input_nml_file, fn_nml, nlunit, xlon, xlat, do_sppt, do_shum, do_skeb, lndp_type, n_var_lndp, use_zmtnblck, skeb_npass, lndp_var_list, lndp_prt_list, ak=ak, bk=bk, nthreads=nthreads, mpiroot=root_pe, mpicomm=comm, iret=ierr)
 if (ierr .ne. 0) print *, 'ERROR init_stochastic_physics call' ! Draper - need proper error trapping here
 call get_outfile(fname)
 write(strid,'(I2.2)') my_id+1