Skip to content

Commit fb57256

Browse files
MinsukJi-NOAADusanJovic-NOAAmark-a-pottsarunchawla-NOAA
authored
Merge release hotfix into develop (#45)
* Set default values for model_configure variables (#18) RUN_CONTINUE = .false. ENS_SPS = .false. TOTAL_MEMBER = 1 * fixes problem with MPI_Comm_Split in openmpi when hash is negative * removed redundant check on hash > 0 * Add GNU LPGL (#32) * Add NEMS documentation (#33) * Add nems documentation in doc directory *Include in .gitignore NEMS/doc/html/ and NEMS/doc/webpage.tar.gz *Remove milestones.dox which is no longer needed *Modify Makefile to include doxygen command on Hera *Remove in prep_inputs.py two functions related to milestones * Remove webpage.tar.gz file * Update NEMS documentation *Add Doxyfile in NEMS/.gitignore * Update based on documentation meeting * Updates to the documentation (#35) * Documentation update (#36) * Modify license file (#37) * Modify license file * Fix typo in license Co-authored-by: Dusan Jovic <[email protected]> Co-authored-by: Mark A. Potts <[email protected]> Co-authored-by: Mark Potts <[email protected]> Co-authored-by: Mark Potts <[email protected]> Co-authored-by: arun chawla <[email protected]>
1 parent 6a4254b commit fb57256

16 files changed

+3293
-1
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,5 @@
11
*.pyc
22
__pycache__
3+
/doc/html/
4+
/doc/webpage.tar.gz
5+
/doc/Doxyfile

‎doc/Doxyfile.IN

Lines changed: 2445 additions & 0 deletions
Large diffs are not rendered by default.

‎doc/Makefile

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
LOCAL_DOCS=$(wildcard *.md) $(wildcard *.dox)
2+
CONTROL_FILES=Makefile prep_inputs.py Doxyfile.IN DoxygenLayout.xml.IN
3+
4+
5+
# Find Doxygen
6+
7+
ifndef DOXYGEN
8+
DOXYGEN=doxygen
9+
endif
10+
11+
ifeq ("$(DOXYGEN)","doxygen")
12+
$(info Attempting to auto-detect environment.)
13+
THEIA_DOXYGEN=/scratch3/NCEPDEV/hwrf/save/Samuel.Trahan/doxygen-1.8.10/bin/doxygen
14+
JET_DOXYGEN=/contrib/doxygen/1.8.10/bin/doxygen
15+
LUNA_DOXYGEN=/gpfs/hps3/emc/hwrf/noscrub/soft/doxygen-1.8.10/bin/doxygen
16+
TIDE_DOXYGEN=/hwrf/noscrub/soft/doxygen-1.8.10/bin/doxygen
17+
HERA_DOXYGEN=/usr/bin/doxygen
18+
19+
ifneq ($(wildcard $(THEIA_DOXYGEN)*),)
20+
$(info On Theia.)
21+
DOXYGEN=$(THEIA_DOXYGEN)
22+
TARGET ?= [email protected]:/home/www/emc/htdocs/projects/nems-sample/.
23+
else ifneq ($(wildcard $(JET_DOXYGEN)*),)
24+
$(info On Jet.)
25+
DOXYGEN=$(JET_DOXYGEN)
26+
TARGET ?= [email protected]:/home/www/emc/htdocs/projects/nems-sample/.
27+
else ifneq ($(wildcard $(LUNA_DOXYGEN)*),)
28+
$(info on Luna or Surge.)
29+
DOXYGEN=$(LUNA_DOXYGEN)
30+
TARGET ?= [email protected]:/home/www/emc/htdocs/mmb/rvasic/nems-sample/.
31+
else ifneq ($(wildcard $(TIDE_DOXYGEN)*),)
32+
$(info on Tide or Gyre.)
33+
DOXYGEN=$(TIDE_DOXYGEN)
34+
TARGET ?= [email protected]:/home/www/emc/htdocs/mmb/rvasic/nems-sample/.
35+
else ifneq ($(wildcard $(HERA_DOXYGEN)*),)
36+
$(info on Local machine.)
37+
DOXYGEN=$(HERA_DOXYGEN)
38+
else
39+
$(error Could not detect environment. You must set TARGET and DOXYGEN manually)
40+
endif
41+
else
42+
$(info DOXYGEN set in environment. Will not set TARGET variable. You must set it manually. DOXYGEN=$(DOXYGEN))
43+
endif
44+
45+
TARGET ?= /please/update/TARGET/in/Makefile
46+
47+
default:
48+
@echo Specify build mode:
49+
@echo doc = build documentation just for this directory
50+
@echo clean = delete outputs
51+
@echo deliver = copy to website
52+
exit 19
53+
54+
clean:
55+
rm -rf html webpage.tar.gz repo_info.sh.inc Doxyfile DoxygenLayout.xml
56+
57+
doc: clean
58+
./prep_inputs.py ..
59+
set -x ; $(DOXYGEN)
60+
tar -cpzf webpage.tar.gz html Doxyfile
61+
62+
deliver: html
63+
cd html && rsync -arv . "$(TARGET)/."
64+

‎doc/architecture.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
Architecture {#architecture}
2+
============
3+
4+
The NEMS architecture is based on an ESMF component hierarchy with the
5+
application driver `MAIN_NEMS` at the top, calling into the
6+
`NEMS_COMP` component, which in turn drives the `EARTH_COMP`
7+
component. The `EARTH_COMP` drives the `ATM` and other components.
8+
The architecture allows for multiple `EARTH_COMP` instances.
9+
10+
NEMS includes atmosphere, ocean, ice, wave, land,
11+
aerosol/chemistry, and hydrologic models, with coupling interface and
12+
utilities based on the
13+
[Earth System Modeling Framework (ESMF)](https://www.earthsystemcog.org/projects/esmf/).
14+
The NEMS applications also utilize intreopereability conventions
15+
introduced by the
16+
[National Unified Operational Prediction Capability (NUOPC)](https://www.earthsystemcog.org/projects/nuopc/).
17+
18+
Key architecture features are:
19+
20+
* Data exchanges between major model components go through a central
21+
(NEMS) mediator component. There
22+
may be additional specialized mediators (e.g. for the 3D
23+
interactions associated with space weather coupling).
24+
25+
* The NEMS mediator component is an integral part of the NEMS
26+
software. The mediator source code is managed alongside the NEMS
27+
source code, is integrated into the NEMS make system and is built
28+
when the NEMS executable is built.
29+
30+
* Component models are treated by NEMS as external
31+
dependencies. Their source code is managed outside of NEMS,
32+
typically in the proximity of the organization maintaining the
33+
official version of the model. Each model maintains its own separate
34+
make system with a NUOPC compliant build option. NEMS requires that
35+
the pre-built models are available when the NEMS executable is being
36+
built.
37+
38+
* All of the components driven by they EARTH_COMP are NUOPC-compliant
39+
components.
40+
41+
* All of the components driven by they EARTH_COMP can be configured to
42+
run on a specific set of PETs (MPI processes), supporting concurrent
43+
or sequential component execution.
44+
45+
* Data exchanges between components are handled by generic
46+
NUOPC_Connector components.
47+
* The generic connectors perform basic regrid and redist operations as needed to
48+
take field data from one side to the other.

‎doc/cap-doc.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Cap Documentation {#cap-page}
2+
=================
3+
4+
Caps are codes that act as adaptors, enabling models to use
5+
[NUOPC](https://www.earthsystemcog.org/projects/nuopc/)
6+
standard component interfaces. They are called caps because they "sit
7+
on top" of user code and call into it. They contain translations of
8+
native model data structures into ESMF data structures.
9+
10+
For documentation of caps, see the
11+
[Earth System Prediction Suite (ESPS)](https://www.earthsystemcog.org/projects/esps/)
12+
site. Find the components on the table on the landing page, and
13+
follow the corresponding Code Access and Documentation link. Not all
14+
listed components have documented caps. The ESPS is a collection of
15+
components that are compliant with NUOPC conventions.

‎doc/configuring.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
Configuring {#configuring}
2+
===========
3+
4+
The NEMS application is highly configurable. During
5+
build-time, i.e. when the NEMS executable is being compiled and
6+
linked, choices are made as to which model and mediator components are
7+
built into the system. The built-in components become accessible
8+
during run-time, allowing the execution of different run
9+
configurations without the need to rebuild NEMS.
10+
11+
Often the build and run configurability of NEMS is hidden from the
12+
user by application or test scripts. However, there are times where it
13+
is useful to understand the technical details on the level of the NEMS
14+
executable.
15+
16+
Run Configuration
17+
-----------------
18+
19+
During run-time of the NEMS executable, it accesses a file called
20+
nems.configure, which it expects to find in the run directory. This
21+
file specifies the dynamic component selection, and the exact run
22+
sequence to be used. Only models built into the executable at
23+
build-time are accessible during run-time. An error will be triggered
24+
if an unavailable model is selected in nems.configure. The component
25+
selection is based on two variables:
26+
27+
xxx_model: abc
28+
xxx_petlist_bounds: lower upper
29+
30+
Here `xxx` can be `atm`, `ocn`, `ice`, `ipm`, `med`. The `abc`
31+
stands for the actual instance name, e.g. `fv3` or `mom6`. The
32+
lower and upper bounds of the petList specification are integer PET
33+
numbers.
34+
35+
The specification of the run sequence provides the flexibility needed
36+
to cover different coupling scenarios. The format is line based
37+
between special tags:
38+
39+
runSeq::
40+
line1
41+
line2
42+
...
43+
lineN
44+
::
45+
46+
There are a number of format options for each line:
47+
48+
* A time loop is introduced by a `@` symbol, followed immediatly by
49+
the number of seconds of the associated time step.
50+
51+
* A time loop is closed by a single `@` symbol on a line.
52+
53+
* The `RUN` method of model component `xxx` is called by specifying
54+
just `xxx` on a line. The supported values of `xxx` are the same
55+
as for the model specification above. A specific RUN phase can be
56+
provided by adding the phase label to the same line, following the
57+
model string.
58+
59+
* A connector going from component `xxx` to component `yyy` is
60+
specified by a line like this: `xxx -> yyy`. An additional
61+
argument on the same line can be used to specify connection options
62+
for all of the field handled by the connector. The format and
63+
supported values of the connection options is documented in the
64+
NUOPC reference manual.
65+
66+
A very simple run sequence is running only the atmospheric uncoupled model.
67+
The run sequence looks like:
68+
69+
# Run Sequence #
70+
runSeq::
71+
ATM
72+
::
73+
74+
A more complex example is when components are exchanging information at two time scales:
75+
76+
# Run Sequence #
77+
runSeq::
78+
@7200.0
79+
OCN -> MED
80+
MED MedPhase_slow
81+
MED -> OCN
82+
OCN
83+
@3600.0
84+
MED MedPhase_fast_before
85+
MED -> ATM
86+
ATM
87+
ATM -> MED
88+
MED MedPhase_fast_after
89+
@
90+
@
91+
::
92+
93+
Anything on a line after the `#` symbol is treated as a comment and
94+
ignored. Indentation in the formatting does not change the meaning of
95+
a line, but is purely used to increase readability.

‎doc/documentation.dox

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
/**@page documentation Users Guide and Reference
2+
3+
These pages contain general documentation for the NEMS, such as
4+
guides, howtos and system descriptions.
5+
6+
+ @subpage introduction
7+
+ @subpage architecture
8+
+ @subpage configuring
9+
+ @subpage mediator
10+
+ @subpage cap-page
11+
12+
*/

‎doc/introduction.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
Introduction to NEMS {#introduction}
2+
====================
3+
4+
The NOAA Environmental Modeling System (NEMS) is the infrastructure
5+
underlying NOAA's [Unified Forecast System (UFS)] (https://ufscommunity.org/) a fully coupled modeling framework that supports predictions of
6+
Earth's environment at a range of time scales. Examples of other
7+
coupled modeling systems are the
8+
[Community Earth System Model (CESM)](http://www.cesm.ucar.edu)
9+
and the
10+
[Met Office Unified Model] (http://www.metoffice.gov.uk/research/modelling-systems/unified-model).
11+
12+
NEMS includes infrastructure for coupling model components
13+
representing major Earth system domains and processes.
14+
**A model component** is a software representation of a physical
15+
domain or process, for example sea ice. It is often developed by a
16+
team of specialists in that domain. Model coupling is a software
17+
representation of feedbacks between physical processes. It involves
18+
modifying the exported fields of a component through grid, unit,
19+
temporal, and other transformations so that they can be used as the
20+
inputs for another component. These components are managed through repositories, primarily on GitHub.
21+
22+
In general, model components are
23+
coupled through the NEMS mediator (in other coupled modeling systems
24+
this is often called the "coupler"). NEMS also includes some
25+
specialized mediators; for example, for space weather. In some cases
26+
in NEMS, the model components are coupled "in-line", meaning that they
27+
are called directly from another model component instead of having
28+
fields sent through the mediator.
29+
30+
NEMS can be assembled into a number of different **modeling
31+
applications** (often shortened to just applications). Modeling
32+
applications are associated with a purpose, like medium-range
33+
forecasting; a set of model components; and a set of parameters that
34+
represent a range of supported options, including grids and
35+
resolutions. Different NEMS modeling applications can have different
36+
types and numbers of model components. Also, the same physical domain
37+
may be represented by different model components in different modeling
38+
applications. For example, in some NEMS modeling applications the
39+
ocean component may be the HYbrid Coordinate Ocean Model (HYCOM) and
40+
in others it may be the Modular Ocean Model (MOM).
41+
42+
Infrastructure
43+
--------------
44+
45+
[NEMS is built using the Earth System Modeling Framework (ESMF)](https://www.earthsystemcog.org/projects/esmf/)
46+
infrastructure software. ESMF provides utilities like generation of
47+
interpolation weights and utilities for calendar and timee management,
48+
and also wrappers that create a standard component calling
49+
interface. This enables model components developed at different sites
50+
to be coupled more easily.
51+
52+
[The National Unified Operational Prediction Capability (NUOPC) Layer] (https://earthsystemcog.org/projects/nuopc/)
53+
adds additional rules about how ESMF models interact and increases
54+
their interoperability. The NUOPC Layer covers aspects from the level
55+
of build dependencies, to standardization of initialization phases,
56+
all the way to standard names of the exchanged fields. NEMS is an
57+
example of a modeling system built using the NUOPC Layer architecture.
58+
59+
Architecture
60+
------------
61+
62+
The NEMS architecture is based on an ESMF component hierarchy with the
63+
application driver `MAIN_NEMS` at the top, calling into the
64+
`NEMS_COMP` component, which in turn drives the `EARTH_COMP`
65+
component. The `EARTH_COMP` drives the `ATM` and other components.
66+
The architecture allows for
67+
multiple `EARTH_COMP` instances, supporting ensemble applications such
68+
as the Global Ensemble Forecast System (GEFS).
69+
70+
Coupled NEMS includes atmosphere, ocean, ice, wave, land,
71+
aerosol/chemistry, and hydrologic models, with coupling interface and
72+
utilities based on the
73+
[Earth System Modeling Framework (ESMF)](https://www.earthsystemcog.org/projects/esmf/).
74+
The NEMS applications also utilize intreopereability conventions
75+
introduced by the
76+
[National Unified Operational Prediction Capability (NUOPC)](https://www.earthsystemcog.org/projects/nuopc/).

‎doc/make-images-fit.css

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
img {
2+
max-width: 100%
3+
}

0 commit comments

Comments
 (0)