From f44ebc1c15432fc9286e07226d4e312e5905562d Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Thu, 6 Jan 2022 05:40:48 -0700 Subject: [PATCH 1/8] Easy stuff first: correct spelling, remove note about this being a un-supported pre-release --- README.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/README.md b/README.md index 590f863a..3f44f288 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# CCPP Framwork +# CCPP Framework Common Community Physics Package (CCPP) Framework. @@ -16,20 +16,6 @@ testing of the CCPP. The CCPP repository may also be used in conjunction with th GMTB Single Column Model (SCM). Please see the [GMTB SCM+CCPP page](http://www.dtcenter.org/GMTB/gmtb_scm_ccpp_doc/) for more information on combining the GMTB SCM and the CCPP. -This is the release v0.1.0 of the CCPP. As this is the initial release, -the CCPP only has infrastructure to support the neccesary functioning of -the anticipated package, without having actual (i.e. physically valid) -physical parameterization schemes included. The included physical -parameterization schemes inside of the CCPP are "stub" only. While the -schemes do have arguments similar to what traditional schemes require -(wind, surface temperature, physical constants), the schemes immediately -return after a message "I am in this scheme" has been output. - -This repository for the CCPP and the CCPP driver contains tests to verify -proper running of the CCPP and driver. Detailed information on how to -include fully functioning physical parameterizations schemes will be -provided once examples of fully functioning schemes are part of the CCPP. - ## Requirements ### Compilers From 4c4282abd82f381ae22ab2e3df6c29ae057e51e8 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Thu, 6 Jan 2022 05:45:31 -0700 Subject: [PATCH 2/8] Remove old, broken CI stuff, expand description of repository a little, remove "Notes to Users" section that is outdated with broken links --- README.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/README.md b/README.md index 3f44f288..6be9bd6b 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,6 @@ # CCPP Framework -Common Community Physics Package (CCPP) Framework. - -| Branch | Linux/MacOS Build | Coverage | -|--- |--- |--- | -| Master | [![Build Status](https://travis-ci.org/NCAR/gmtb-ccpp.svg?branch=master)](https://travis-ci.org/NCAR/gmtb-ccpp) | [![Coverage Status](https://codecov.io/github/NCAR/gmtb-ccpp/coverage.svg?branch=master)](https://codecov.io/github/NCAR/gmtb-ccpp) | -| Develop | [![Build Status](https://travis-ci.org/NCAR/gmtb-ccpp.svg?branch=develop)](https://travis-ci.org/NCAR/gmtb-ccpp) | [![Coverage Status](https://codecov.io/github/NCAR/gmtb-ccpp/coverage.svg?branch=develop)](https://codecov.io/github/NCAR/gmtb-ccpp?branch=develop) | - - -## Notes to Users -This repository contains the Common Community Physics Packages (CCPP) Framework. - -The repository for the CCPP and the CCPP driver contains sufficient code for standalone -testing of the CCPP. The CCPP repository may also be used in conjunction with the -GMTB Single Column Model (SCM). Please see the [GMTB SCM+CCPP page](http://www.dtcenter.org/GMTB/gmtb_scm_ccpp_doc/) -for more information on combining the GMTB SCM and the CCPP. +This repository contains the Common Community Physics Package (CCPP) Framework: The infrastructure that connects CCPP physics schemes with a host model, as well as stand-alone tools for use with CCPP. ## Requirements From 7764c79ababb9194ae393bd1108b570c5e5f2b2d Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Thu, 6 Jan 2022 06:11:21 -0700 Subject: [PATCH 3/8] Add documentation section pointing to other resources --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index 6be9bd6b..3ec95aa9 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,13 @@ This repository contains the Common Community Physics Package (CCPP) Framework: The infrastructure that connects CCPP physics schemes with a host model, as well as stand-alone tools for use with CCPP. +## Documentation +The CCPP Framework is designed to be used with the [CCPP Physics repository](https://github.com/NCAR/ccpp-physics) and a host model. Links to further information about this repository and its place in the context of the CCPP as a whole can be found on the [GitHub Wiki](https://github.com/NCAR/ccpp-framework/wiki). + +The CCPP Single Column Model (SCM) is designed as a simple host model for testing and development of the CCPP; information about building and using the CCPP in this context can be found in [the CCPP SCM Users Guide](https://dtcenter.org/sites/default/files/paragraph/scm-ccpp-guide-v5.0.0.pdf). + +More information about the design and use of CCPP can be found in the [CCPP Technical Documentation](https://ccpp-techdoc.readthedocs.io/en/v5.0.0/). + ## Requirements ### Compilers From 7190dabaa32e0c2907d046f15f1abaad67d0488c Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Thu, 6 Jan 2022 06:13:41 -0700 Subject: [PATCH 4/8] None of these build or testing instructions seem to work; they appear to be superseded by other procedures --- README.md | 118 ------------------------------------------------------ 1 file changed, 118 deletions(-) diff --git a/README.md b/README.md index 3ec95aa9..adc4988f 100644 --- a/README.md +++ b/README.md @@ -9,124 +9,6 @@ The CCPP Single Column Model (SCM) is designed as a simple host model for testin More information about the design and use of CCPP can be found in the [CCPP Technical Documentation](https://ccpp-techdoc.readthedocs.io/en/v5.0.0/). -## Requirements - -### Compilers -The CCPP uses both the C and Fortran compilers. Note, the -Fortran compiler must be 2008 compliant. There are a number of Fortran -2003 pieces, and a single convenience right now with Fortran 2008. - -1. [GNU Compiler Collection](https://gcc.gnu.org/) -2. [Intel 16.0.2](https://software.intel.com/en-us/intel-compilers) and beyond work. -3. [PGI](http://www.pgroup.com/) compilers do **not** easily support C functions - calling Fortran routines. The PGI compilers attach the Fortran module name as a - prefix to the Fortran symbol. This **breaks** the method that the CCPP uses to - identify which schemes to call. - -### [Cmake](https://cmake.org) - -The CCPP build system uses cmake. - -### [LibXML2](http://xmlsoft.org/) - -The suite definition is currently written in XML, LibXML2 is currently used to -parse these files. - -## Building -It is recommend to do an out of source build. This is "cmake" terminology -for creating a separate directory where all of the built code (objects, -libraries, executables) exist. - -1. Clone the repository. -``` -git clone https://github.com/NCAR/ccpp-framework ccpp -``` -2. Change into the repository clone -``` -cd ccpp -``` -3. Specify the compiler to use. For example the GNU compilers, - when it is available as a module called `gcc`. - * For sh or bash -``` -ml gcc -export CC=gcc -export FC=gfortran -export CXX=g++ -``` - * For csh or tcsh -``` -ml gcc -setenv CC gcc -setenv FC gfortran -setenv CXX g++ -``` -4. Make a build directory and change into it. -``` -mkdir build -cd build -``` -5. Create the makefiles. -``` -cmake .. -``` -6. Build the CCPP library and test programs. -``` -make -``` - -## Running Tests -There are a few test programs within the `ccpp/src/tests` directory. -These should be built when the CCPP library is compiled. - -To run the tests you have to add the CCPP check scheme library (`libcheck.so`) -to your `LD_LIBRARY_PATH` (`DYLD_LIBRARY_PATH` for OS X). - -For sh or bash: -``` -export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${PWD}/schemes/check/src/check-build/ -``` - -For csh or tcsh: -``` -setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${cwd}/schemes/check/src/check-build/ -``` - -Note that if CCPP was built as part of a build system, you might have to load -the compiler and set environment variables that were used by the build system. - - -Then issue the following within the build directory. - * `make test` - -All tests should pass, if not, please open an issue. The output should be -similar to: -~~~~{.sh} -Running tests... -Test project /home/tbrown/Sources/ccpp-framework/build - Start 1: XML_1 -1/8 Test #1: XML_1 ............................ Passed 0.02 sec - Start 2: XML_2 -2/8 Test #2: XML_2 ............................ Passed 0.01 sec - Start 3: XML_3 -3/8 Test #3: XML_3 ............................ Passed 0.01 sec - Start 4: XML_4 -4/8 Test #4: XML_4 ............................ Passed 0.01 sec - Start 5: XML_5 -5/8 Test #5: XML_5 ............................ Passed 0.00 sec - Start 6: XML_6 -6/8 Test #6: XML_6 ............................ Passed 0.00 sec - Start 7: FIELDS -7/8 Test #7: FIELDS ........................... Passed 0.00 sec - Start 8: CHECK -8/8 Test #8: CHECK ............................ Passed 0.01 sec - -100% tests passed, 0 tests failed out of 8 - - -Total Test time (real) = 0.08 sec -~~~~ - ## Validating XML A suite is defined in XML. There are several test suites defined within the `ccpp/src/tests` directory (which are able to test the build and From b8e86a1b78dc9fb20fdf4c0178eb41d7d9729d10 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Thu, 6 Jan 2022 06:34:00 -0700 Subject: [PATCH 5/8] "Physics Schemes" section can be removed, it is outdated and what is not outdated is described elsewhere --- README.md | 29 ----------------------------- 1 file changed, 29 deletions(-) diff --git a/README.md b/README.md index adc4988f..b7de77e7 100644 --- a/README.md +++ b/README.md @@ -85,35 +85,6 @@ early testing, and is included in the initial release. * For each scheme, an XML file (the scheme definition file) needs to exist. For the initial release, this XML file has not yet been designed. -## Physics Schemes -All physics schemes are kept in the GitHub repository ccpp-physics. - -To add a new scheme one needs to - -1. Add/Create the scheme within `schemes`. You should create a - sub-directory under the `schemes` directory. You will need to - add a [`ExternalProject_Add()`](https://cmake.org/cmake/help/latest/module/ExternalProject.html). - call to the `schemes/CMakeLists.txt` file. -2. Create a `cap` subroutine. The CCPP will call your - cap routine. - - 1. The cap routine must be labelled "schemename_cap". - - For example, the dummy scheme has a cap called - "dummy_cap". The requirements are that it is - 1. The scheme name is lowercase (the symbol is called from a C - function). - 2. "_cap" is appended. - - 2. Map all the inputs for the cap from the `cdata` encapsulating - type (this is of the `ccpp_t` type). The cap will extract the - fields from the fields array with the `ccpp_field_get()` - subroutine. - -An example of a scheme is `schemes/check/test.f90`. It has the cap -routine and the run routine. The run routine prints out that the -scheme has been entered. - ## Usage The CCPP must first be initialized, this is done by calling `ccpp_init()`. From ec67b8841ae1e868754d1b409d5a883d15624686 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Thu, 6 Jan 2022 06:42:44 -0700 Subject: [PATCH 6/8] Usage and Doc sections can be removed, outdated and irrelevant --- README.md | 58 ------------------------------------------------------- 1 file changed, 58 deletions(-) diff --git a/README.md b/README.md index b7de77e7..eb025b16 100644 --- a/README.md +++ b/README.md @@ -86,64 +86,6 @@ early testing, and is included in the initial release. For the initial release, this XML file has not yet been designed. -## Usage -The CCPP must first be initialized, this is done by calling `ccpp_init()`. -Once initialized, all variables that will be required in a physics scheme -have to be added to the ccpp data object (of type `ccpp_t`). These variables -can later be retrieved in a physics schemes cap. - -Example usage, in an atmosphere component: -~~~~{.f90} -type(ccpp_t), target :: cdata -character(len=128) :: scheme_xml_filename -integer :: ierr - -ierr = 0 - -! Initialize the CCPP and load the physics scheme. -call ccpp_init(scheme_xml_filename, cdata, ierr) -if (ierr /= 0) then - call exit(1) -end if - -! Add surface temperature (variable surf_t). -call ccpp_field_add(cdata, 'surface_temperature', surf_t, ierr, 'K') -if (ierr /= 0) then - call exit(1) -end if - -! Call the first physics scheme -call ccpp_ipd_run(cdata%suite%ipds(1)%subcycles(1)%schemes(1), cdata, ierr) -if (ierr /= 0) then - call exit(1) -end if -~~~~ - -Example usage, in a physics cap: -~~~~{.f90} -type(ccpp_t), pointer :: cdata -real, pointer :: surf_t(:) -integer :: ierr - -call c_f_pointer(ptr, cdata) -call ccpp_field_get(cdata, 'surface_temperature', surf_t, ierr) -if (ierr /= 0) then - call exit(1) -end if -~~~~ - -Note, the cap routine must -* Accept only one argument of type `type(c_ptr)`. -* Be marked as `bind(c)`. - -## Documentation -The code is documented with [doxygen](www.doxygen.org/). -To generate the documentation you must have [doxygen](www.doxygen.org/) -and [graphviz](http://www.graphviz.org/) installed. Then execute: -``` -make doc -``` - ## Code Coverage The code can be built and run to indicate code coverage. In order to do this, you must have GNU [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) From 93669f88ee7f451881ff8e694cbfe278e165d762 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Fri, 7 Jan 2022 09:11:13 -0700 Subject: [PATCH 7/8] Remove remainder of old sections based on feedback from CCPP team; xmllint is no longer needed (sufficient error checking in rest of code) and "code coverage" option no longer exists --- README.md | 91 ------------------------------------------------------- 1 file changed, 91 deletions(-) diff --git a/README.md b/README.md index eb025b16..dced2973 100644 --- a/README.md +++ b/README.md @@ -9,94 +9,3 @@ The CCPP Single Column Model (SCM) is designed as a simple host model for testin More information about the design and use of CCPP can be found in the [CCPP Technical Documentation](https://ccpp-techdoc.readthedocs.io/en/v5.0.0/). -## Validating XML -A suite is defined in XML. There are several test suites defined within -the `ccpp/src/tests` directory (which are able to test the build and -installation of the standalone CCPP). There is also the XML Schema -Definition in that directory too. To validate a new test suite, you can -use `xmllint`. For example to validate `suite_EXAMPLE.xml`: -~~~~{.sh} -cd src/tests -xmllint --schema suite.xsd --noout suite_EXAMPLE.xml -suite_EXAMLE.xml validates -~~~~ - -Within the `src/tests` directory there is a Fortran file -`test_init_finalize.f90` which will get built into an executable program -when the CCPP library is built. This program only calls: - * `ccpp_init()` - * `ccpp_finalize()` - -It is a program to check the suite XML validation within the CCPP -library. The following is an example of using it from within the -`build` directory. -~~~~{.sh} -src/tests/test_init_finalize my_suite.xml -~~~~ - -For this to work, the library that is referenced in the xml file -must be added to the LD_LIBRARY_PATH (see above). To test the -correct functionality of CCPP itself, the suite suite_EXAMPLE.xml -in src/tests can be used. - -There are two general types of XML files for the CCPP. The first is the -definition file for a suite. These reside in the host model repositories. -Here is a fairly short example: - -~~~~{.xml} - - - - - - RRTMGLW - RRTMGSW - MYNNSFC - RUCLSM - MYNNPBL - GF - - - - - THOMPSONAERO - - - -~~~~ - -* suite - * This text string "name" attribute is compared to the user-selected - physics suite option at run-time. -* ipd part - * To allow for the design of the interface between the dynamics and -physical parameterization schemes, this attribute clearly associates particular -packages with the dynamical sections. In this XML example, there are two "part" -sections, with the second part only containing the "THOMPSONAERO" microphysics -scheme. - * Users should carefully construct the XML file to map the schemes into the -existing sections of the code that calls the physical parameterization schemes. -* subcycle - * This functionality is not fully enabled. It is expected to be utilized for -early testing, and is included in the initial release. -* scheme - * The scheme elements fully describe the calling sequence of the physical - parameterization schemes within the model. - * For each scheme, an XML file (the scheme definition file) needs to exist. - For the initial release, this XML file has not yet been designed. - - -## Code Coverage -The code can be built and run to indicate code coverage. In order to do -this, you must have GNU [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) -and [lcov](http://ltp.sourceforge.net/coverage/lcov.php) installed. -To generate the coverage: - -1. Make sure you are using the GNU compilers. -2. Configure the build for coverage. - * `cmake -DCMAKE_BUILD_TYPE=Coverage ..` -3. Build the CCPP. - * `make` -4. Build the coverage report - * `make coverage` -The coverage report will be in the `coverage` directory within the build. From d360ca773aa6b4331ea323b98e5ccc2cfeeb1c32 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Fri, 7 Jan 2022 09:12:33 -0700 Subject: [PATCH 8/8] Removing outdated/obsolete "README_TODO" --- README_TODO.txt | 9 --------- 1 file changed, 9 deletions(-) delete mode 100644 README_TODO.txt diff --git a/README_TODO.txt b/README_TODO.txt deleted file mode 100644 index 09f72242..00000000 --- a/README_TODO.txt +++ /dev/null @@ -1,9 +0,0 @@ -# Dom 2018/02/13 - -- Python scripts/modules in this directory are superseded by those in ../scripts - -- Other functionality (longnames_autocheck, parse_fortran) must be moved over/merged and updated to provide the same functionality - -- The tests run in this directory needs updating. For instance, mkcap.py in ../scripts looks slightly different - -- More tests desirable!