Next:
Contents
Contents
Earth System Modeling Framework
Software Developer's Guide
Silverio Vasquez, Sylvia Murphy, Cecelia DeLuca, Walter Spector, Gerhard Theurich
September 23, 2023
Contents
1
Introduction
1
.
1
About this Document
1
.
2
Supplementary Information
1
.
3
Acknowledgments
2
Groups and Roles in ESMF Development
2
.
1
Core Team
2
.
1
.
1
Core Team Roles
2
.
2
Joint Specification Team (JST)
2
.
3
Change Review Board (CRB)
2
.
4
Quality Assurance Responsibilities
3
Collaboration Environment and Communication
3
.
1
Mailing Lists
3
.
2
Meetings and Telecons
3
.
3
GitHub Open Source Development Environment
3
.
3
.
1
The Main ESMF Site and Repository
4
Processes
4
.
1
Software Process Model
4
.
2
ESMF Process History
4
.
2
.
1
Software Concept
4
.
2
.
2
Requirements Analysis
4
.
2
.
3
Architectural Design
4
.
3
Ongoing Development
4
.
3
.
1
Telecon Etiquette
4
.
3
.
2
Design Reviews
4
.
3
.
3
Implementation and Test Before Internal Release
4
.
3
.
4
Implementation and Test Before Public Release
4
.
3
.
5
Code Check-In
4
.
3
.
6
Code Reviews
4
.
3
.
7
Releases
4
.
3
.
8
Backups
4
.
4
Testing and Validation
4
.
4
.
1
Unit Tests
4
.
4
.
1
.
1
Writing Unit Tests
4
.
4
.
1
.
2
Analyzing unit test results
4
.
4
.
1
.
3
Disabling unit tests
4
.
4
.
1
.
4
Benchmarking Unit Tests
4
.
4
.
2
Examples
4
.
4
.
2
.
1
Disabling examples
4
.
4
.
3
System Tests
4
.
4
.
3
.
1
Writing System Tests
4
.
4
.
3
.
2
Disabling system tests
4
.
4
.
4
Test Harness
4
.
4
.
4
.
1
Analyzing Test Harness results
4
.
4
.
5
Use Test Cases (UTCs)
4
.
4
.
6
Beta Testing
4
.
4
.
7
Automated Regression Tests
4
.
4
.
8
Investigating Test Failures
4
.
4
.
9
Building the Documentation
4
.
4
.
10
Testing for Releases
4
.
5
User Support
4
.
5
.
1
Roles
4
.
5
.
2
Support Categories
4
.
5
.
3
Summary Work Flow
4
.
5
.
4
General Guidelines for Handling Tickets
4
.
5
.
5
esmf_support@ucar.edu Mail Archives
4
.
5
.
6
INFO:Code (subject) mail messages
4
.
5
.
7
freeCRM
4
.
5
.
8
Annual Code Contact
4
.
5
.
9
Dealing with Applications that use ESMF
5
Apps
6
Test Harness
6
.
1
Specifying Test Harness Tests
6
.
2
Running Test Harness Tests as Part of Unit Tests
6
.
3
Invoking a Single Test Harness Test Case Using gmake
6
.
4
Invoking a Single Test Harness Test Case from the Command Line
6
.
5
Top Level Configuration File
6
.
5
.
1
Problem descriptor file
6
.
5
.
2
Problem descriptor string syntax
6
.
5
.
2
.
1
Grid syntax
6
.
5
.
2
.
2
Distribution syntax
6
.
5
.
2
.
3
Transformation method
6
.
5
.
2
.
4
Staggering syntax (Not currently implemented)
6
.
5
.
3
General Data Structures
6
.
5
.
4
Specifier files
6
.
5
.
5
Grid Specification
6
.
5
.
5
.
1
Curvilinear Grid Coordinate Generation (For Future Implementation)
6
.
5
.
5
.
2
Specifier file syntax for redistribution
6
.
5
.
5
.
3
Specifier file syntax for regridding
6
.
5
.
6
Distribution Specification
6
.
5
.
7
Class Specification
6
.
6
Reporting test results
7
Conventions
7
.
1
Docs: Code and Documentation Templates and Associated Scripts
7
.
1
.
1
Documentation Generation Script
7
.
1
.
2
Code Generation Scripts
7
.
2
Docs: Documentation Guidelines and Conventions
7
.
2
.
1
Accessibility
7
.
2
.
2
File format
7
.
2
.
3
Typeface and Diagram Conventions
7
.
2
.
4
Style Rules for
L
A
T
E
X
7
.
3
Docs: Performance Report Conventions
7
.
4
Docs: Reference Manual Conventions
7
.
4
.
1
Description, Use and Examples, and Other Introductory Sections
7
.
4
.
2
Examples Sections
7
.
4
.
3
Flags and Options Sections
7
.
4
.
4
Class API Sections
7
.
5
Code: Method Conventions
7
.
5
.
1
Standard Method Names
7
.
5
.
2
Use of *Set and *Get
7
.
5
.
3
Use of Is* and Has*
7
.
5
.
4
Functions vs. Subroutines
7
.
5
.
5
Source and Destination Ordering
7
.
6
Code: Argument Conventions
7
.
6
.
1
Standard Variable Names
7
.
6
.
2
Use of Is* and Has*
7
.
6
.
3
Variable Capitalization
7
.
6
.
4
Variables Associated with Options
7
.
6
.
5
Variables Having Logical Data Type
7
.
6
.
6
Arguments which are Arrays
7
.
6
.
7
Arguments which are Pointers
7
.
7
Code: File Rules
7
.
7
.
1
License and Copyright Information
7
.
7
.
2
TODO: Reminder
7
.
7
.
3
FILENAME Macros
7
.
8
Code: Style Rules for Source Code
7
.
9
Code: Error Handling Conventions
7
.
9
.
1
Objectives
7
.
9
.
2
Approach
7
.
9
.
3
Error Masking
7
.
9
.
4
Example (pre-review method)
7
.
9
.
5
Example (post-review method)
7
.
9
.
6
Memory Allocation Checking
7
.
10
Initialization Standardization Instructions
7
.
10
.
1
Overview
7
.
10
.
2
Instructions
7
.
10
.
3
Module
7
.
10
.
4
Shallow Class
7
.
10
.
5
Deep Class
7
.
10
.
6
Parameter Class
7
.
10
.
7
Subroutine
7
.
10
.
8
ESMF Class Types
7
.
11
Code: Data Type Consistency Guidelines
7
.
11
.
1
Use ESMF names for data types in C and ESMF data kinds in Fortran
7
.
11
.
2
Fortran
7
.
11
.
3
C and C++
7
.
11
.
4
ESMF_TypeKind_Flag “labels”: When knowing the data type/kind is necessary
7
.
11
.
5
Guidelines for Fortran-C Interfaces
7
.
12
Code: Optional Argument Conventions for the C/C++ API
7
.
12
.
1
Overview
7
.
12
.
2
Approach
7
.
12
.
3
Internal Macros for Processing the Optional Argument List
7
.
12
.
4
Parsing the Optional Argument List
7
.
13
Code: Makefile Conventions
7
.
13
.
1
Code Building Rules
7
.
13
.
2
Document Building Rules
7
.
13
.
3
Include Files
7
.
14
Preprocessor Usage
7
.
14
.
1
Using the Preprocessor For Generic Fortran Code
7
.
14
.
2
System Dependent Strategy Using Preprocessor
7
.
15
ESMF Data Type Autopromotion Support Policy and Guide
7
.
15
.
1
How We Arrived at This Autopromotion Support Policy
7
.
16
Scripts: Script Coding Standard
7
.
16
.
1
Content Rules
7
.
17
Lang: Interlanguage Coding Conventions
7
.
17
.
1
Optional Arguments Across Language Interfaces
7
.
18
Lang: Fortran Coding Standard
7
.
18
.
1
Content Rules
7
.
18
.
2
Style Rules
7
.
19
Lang: C/C++ Coding Standard
7
.
20
Repo: Source Code Naming and Tagging Conventions
7
.
20
.
1
Public Releases
7
.
20
.
2
Internal Releases
7
.
21
Data Management Conventions
8
Tracking and Metrics
8
.
1
Release Schedule
8
.
2
Task List
8
.
3
Trackers
8
.
3
.
1
Setting Ticket Priorities
8
.
3
.
2
Labeling Tickets Longer than 2 Weeks
8
.
3
.
3
Estimating Ticket Completion Time
8
.
3
.
4
Labeling Tickets with Time Estimates
8
.
3
.
5
Cross-Referencing the Task List and Trackers
8
.
3
.
6
Summary
8
.
3
.
7
Types of Trackers
8
.
4
Metrics
8
.
4
.
1
Unit and System Tests Coverage
8
.
4
.
2
ESMF Requirements Coverage
8
.
4
.
3
Source Lines of Code, SLOC
9
Policies
9
.
1
External Software Libraries
9
.
2
Graphics Packages
Appendix A: Testing Terminology
Bibliography
About this document ...
esmf_support@ucar.edu
