diff --git a/components/eamxx/.clang-format b/components/eamxx/.clang-format index d7ac296204d4..8f0ed4356777 100644 --- a/components/eamxx/.clang-format +++ b/components/eamxx/.clang-format @@ -7,7 +7,7 @@ AlignConsecutiveMacros: true AlignEscapedNewlines: true AlignTrailingComments: true --- -# # these are the defaults for the LLVM style, generated by +# # you can obtain the defaults for the LLVM style by running # # clang-format --style=llvm --dump-config > [outfile] # # the option definitions are found here: # # https://clang.llvm.org/docs/ClangFormatStyleOptions.html diff --git a/components/eamxx/docs/developer/style/format.md b/components/eamxx/docs/developer/style/format.md new file mode 100644 index 000000000000..afa722b3df21 --- /dev/null +++ b/components/eamxx/docs/developer/style/format.md @@ -0,0 +1,55 @@ +# EAMxx Code Formatting Standards + +To enforce consistent code format throughout EAMxx, we make use of an +autoformatting workflow, carried out via Github Actions in the E3SM repository. + +- The tool we employ is + [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html), + and the version we have chosen is v14.[^v14] + +- The standard we maintain is largely identical to the + [LLVM Coding Standards](https://llvm.org/docs/CodingStandards.html), + and a list of the handful of customizations of this convention are + enumerated in the configuration file [`$EAMXX_ROOT/.clang-format`](https://github.com/E3SM-Project/E3SM/blob/master/components/eamxx/.clang-format). + - See this [How-to Guide](resources/clang-format_HOWTO.md) + for additional details on how to configure `clang-format` on your chosen + development machine. + +## Automated Workflow Summary + +- The `eamxx-format` workflow runs automatically and passes or fails based on + adherence to our formatting standard. +- The workflow is triggered by any Pull Request (PR) that modifies EAMxx code. + - It is also triggered by other PR-related triggers, such as pushing + changes, or converting from **draft** to **ready**. +- All code modified by a PR must be formatted prior to **merging**. +- It is not necessary for your code to be formatted upon ***opening*** a + Pull Request, but feel free to `clang-format` as you develop if that is + your preference. + - The one situation for which opening a pre-formatted PR may not be + preferred is if the file has never previously been `clang-format`-ed + and requires a large number of changes. + - I.e., touching the majority of lines in a file for format-only + changes will make it difficult for a reviewer to determine which + lines were changed for substantive reasons. + - In this case, please refrain from formatting the code prior to + opening the PR, and, instead, run `clang-format` once the PR is + approved to be merged and make that the final commit. +- As of now, the `eamxx-format` workflow only considers files that are edited + by the Pull Request. +- In addition to the pass/fail status, the workflow, provides the path to any + files that caused the failure. + - This information is found on the ***Summary*** page for any failed + `eamxx-format` ***Job***.[^huh-where] + +[^v14]: It turns out that this is important because there really are +differences in behavior across versions. +[^huh-where]: To get to this summary, select the ***Checks*** tab at the top of +the PR page and select the `eamxx-format` workflow from the left sidebar. +The summary is in the main pane of the page with the title +**clang-format-linter summary**.[^also] +[^also]: Note that this can also be accessed the long way around by following the +***Actions*** link at the top of the E3SM repository page; +select `eamxx-format` from the ***All workflows*** section of the ***Actions*** +sidebar; then choose the most recent run that is associated with your PR, +which should be near the top of the list. diff --git a/components/eamxx/docs/developer/style/functions.md b/components/eamxx/docs/developer/style/functions.md new file mode 100644 index 000000000000..b536dfe669ab --- /dev/null +++ b/components/eamxx/docs/developer/style/functions.md @@ -0,0 +1,66 @@ +# Functions and Methods + +## Naming + +- Please name functions (methods) to be ***descriptive*** and ***verb**-ish* so + that the name describes what the function *does*. + - For example, `install_flux_capacitor()` instead of `f_capacitor_method()` + or `ifc()`. + - To note, if your function cannot be named verb-ishly, that is probably a + sign that there is a fundamental issue with your function. +- In general, functions should use `snake_case` and not contain capitalization, + unless capitalizing that quantity is a standard convention (e.g., + `find_Doc_Brown()`). + +## Usage + +- In situations where multiple class-member variables are passed as function + arguments, favor passing the object, rather than the individual variables, + for the sake of shorter lines and function signatures. +- As a rule of thumb, developers should prefer passing arguments by reference, + rather than by value, especially in cases for which the argument is ***large*** + or structurally ***complex***. + - E.g., prefer `func(Type &x) { ... }` versus `func(Type x) { ... }`. + - This holds true much of the time because passing by value creates a copy + of the argument for use by the function, and this increases memory + pressure and a resultant performance penalty. +- To be more in-depth on the topic, we echo the guidance from the + [***C++ Core Guidelines***](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-introduction) + and would encourage the curious to read more deeply on the topic. + + > - For "in" parameters, pass cheaply-copied types by value and others by + > reference to `const`. + > - For "in-out" parameters, pass by reference to non-`const`. + > - For "out" parameters, prefer return values to output parameters. + + - The authors go on to explain that "cheap to copy" includes variables + holding 2 or 3 words--for example a double, pointer, or reference. + - To illustrate, the below function adheres to the provided guidance. + + ```c++ + SmallStruct func(LargeNComplex ¬Small, double forty_two, + const int *laser, const BigStruct &lotsaData) { + + // SmallStruct object is only assigned-to and then returned, so it is + // defined as the return type + SmallStruct ans; + // forty_two, a scalar double, is considered small and so passed by value + ans.val = forty_two; + // lotsaData, a BigStruct object, is only accessed and so is + // passed by const reference + ans.other_val = lotsaData.small_piece; + + // we pass laser by value and as const because pointers are cheap to copy, + // and the value is not changed + for (int i = 0; i < forty_two; ++i) { + ans.val_vector.push_back(laser[i] + notSmall.epsilon[i]); + } + + // notSmall is large and also modified in the function, so we pass by + // reference + // it is also accessed, above, so it must be an argument and not the + // return value + notSmall.ans_struct = ans; + return ans; + } + ``` diff --git a/components/eamxx/docs/developer/style/resources/clang-format_HOWTO.md b/components/eamxx/docs/developer/style/resources/clang-format_HOWTO.md new file mode 100644 index 000000000000..dfd2a142fa51 --- /dev/null +++ b/components/eamxx/docs/developer/style/resources/clang-format_HOWTO.md @@ -0,0 +1,208 @@ +# How-to Guide: `clang-format` + +This guide is for developers who wish to apply `clang-format` on their chosen +development machine, whether that be their personal machine or a multi-user +cluster. +In this guide, we will describe how to configure/run `clang-format` on EAMxx +code and also how to install it if necessary. + +## Configure and Run `clang-format` + +Running `clang-format` according to the defined EAMxx standard ***can*** be +done using only command line arguments; however, the command is quite long. +The easier route is to reference the configuration file +(`$EAMXX_ROOT/.clang-format`). +In this case the command is + +```bash {.copy} +clang-format [-i] --style="file:${EAMXX_ROOT}/.clang-format" +``` + +where the `-i` (`--in-place`) argument controls whether the formatting edits +are conducted and change the source file(s) ("in place") or the required edits +are printed to `stdout` (flag omitted). +Also, note that the `--style` flag can also fully define the options without +the configuration file as follows, but this is not recommended as the +configuration could change before this guide is updated to reflect as such. + + +??? Danger "Terminal One-(long-)liner" + + ```bash {.copy} + clang-format [-i] --style="{BasedOnStyle: llvm, ColumnLimit: 100, AlignConsecutiveAssignments: true, AlignConsecutiveBitFields: true, AlignConsecutiveMacros: true, AlignEscapedNewlines: true, AlignTrailingComments: true}" + ``` + + +## Installing `clang-format` + +On a personal machine, which we will consider to be one for which you have +`sudo` privileges, installation can be conducted via package manager or by +building `llvm v14` from scratch. +If you are a non-admin user of a multi-user cluster, HPC platform, etc., then +it is likely to be an ***easy*** process, though potentially not immediate. + + +??? Note "If you require or already have multiple versions of `clang-format` installed" + + Note that, depending on your requirements, this could be placed in your shell + config file (`.bashrc`, `.zshrc`), or if only needed for a shell session, it + can be done directly from the command line. + + The other option is to add a versioned symbolic link to your `PATH`. + This is sometimes included in the package's `bin/` directory by default and, + if not, can be added there after of placed somewhere that is already on your + `PATH`. + + ```c++ + $ cd /opt/homebrew/opt/llvm@14/bin + $ ls clang-format* + clang-format + // no versioned binary so we create symlink + $ ln -s ./clang-format ./clang-format-14 + $ which clang-format + /opt/homebrew/opt/llvm@14/bin/clang-format-14 + ``` + + **OR** + + ```c++ + $ cd /opt/homebrew/opt/llvm@14/bin + $ ls clang-format* + clang-format + // no versioned binary so we create symlink in a directory already on PATH + $ echo $PATH + /usr/bin:/usr/local/bin + $ ln -s ./clang-format /usr/local/bin/clang-format-14 + $ which clang-format + /usr/local/bin/clang-format-14 + ``` + + +=== "Personal Machine" + + + === "Mac Users (Homebrew Package Manager)" + + For Mac users, the [Homebrew](https://brew.sh) + package manager (`brew`) is the quickest and most straightforward way + to get `clang-format` installed. + Since `clang-format` v14 is not available to install directly from + Homebrew, we install the entire LLVM package at version 14, and this + is as simple as + + ```bash {.copy} + brew install llvm@14 + ``` + + It it likely that Homebrew will issue a message about not linking the + `clang`-related tools by default, so next we add the binary to our `PATH`. + + ```bash {.copy} + $ export PATH="/opt/homebrew/opt/llvm@14/bin/clang-format:$PATH" + # Note: this is the default location for a recent Mac running Apple silicon. + # It may be different on another system. + # You can confirm where yours is installed via 'brew info llvm@14' + $ which clang-format + /opt/homebrew/opt/llvm@14/bin/clang-format + ``` + + Note also, that if your system has multiple version of `clang-format` installed, + it may be preferable to instead set a versioned alias to `clang-format` + (`clang-format-14`) as in + + ```c++ + // create a shell-alias + alias clang-format-14="/opt/homebrew/opt/llvm@14/bin/clang-format" + ``` + + === "Linux Users (Package Manager)" + + Given the many flavors of Linux, it is difficult to generalize, but there + is a high probability the proper version of `clang-format` or `llvm` is + provided by the built-in package manager. + The commands will differ based on your Linux distribution, but using the + Debian/Ubuntu `apt` syntax, it could be accomplished via something like + + ```bash {.copy} + $ apt search clang-format + [...] + clang-format-14/... + $ apt install clang-format-14 + ``` + + === "Build from Source" + + If you do not succeed in the above, `clang-format` can also be fully built + from the [LLVM Compiler Infrastructure](https://github.com/llvm/llvm-project). + It will begin with something like + + ```bash {.copy} + git clone git@github.com:llvm/llvm-project.git + git checkout llvmorg-14.0.6 # version tag + ``` + + Also, if you only need `clang-format` and not any of the other tooling, + it will build faster/smaller if you use the CMake flag + `-DLLVM_ENABLE_PROJECTS="clang"` to only build `clang` and it's friends, + rather than all of `llvm`. + And finally, the README for [LLVM version 14.0.6](https://github.com/llvm/llvm-project/tree/llvmorg-14.0.6) + is far more comprehensive that the one for the latest version, and it contains + instructions specific to that build. + +=== "Multi-user System" + + In many cases `llvm`, `clang`, or `clang-format` will be available as a module, + though whether version 14 is an option could be less likely. + In the optimistic case, it could be as simple as (using Lmod syntax) + + ```bash {.copy} + $ module avail llvm # [clang, clang-format] + [... list ] + $ module load llvm/14.0.6 + ``` + + If it is not available, you will probably need to reach out to a system + administrator to get an official version installed.[^but-conda] + + +--- + + +??? Tip "Unnecessary but Convenient Workflow Customization (`direnv`)" + + If you'd like to add a layer of automation/complexity to ensure you only use + `clang-format v14` on `EAMxx` and/or want to use a newer version on the rest + of your system, there is a very handy terminal tool called + [direnv](https://direnv.net/) + (`brew install direnv`) that allows you to automatically load and unload + environment variables based on `$PWD` using a `.envrc` file. + As an example, here's my `.envrc` that adds `clang-format v14` to the path + when I'm working on `EAMxx`. + + ```bash {.copy} + PATH_add /opt/homebrew/opt/llvm@14/bin/clang-format + + # also, since I often forget to load a python environment that's required for + # running ctest, this creates or loads a python 3 virtual environment with numpy + layout python3 + pip install --upgrade pip + # the upgrade isn't strictly necessary but trades a little extra setup on + # the front end to avoid pip endlessly reminding you to update + pip install numpy + ``` + + This file can be placed in the top-level `EAMxx` directory, and running + `direnv allow` enables the functionality. + Namely, executing `cd EAMxx` loads the defined environment that stays loaded + in any subdirectories, and resets the standard environment when exiting to a + directory above/outside of `EAMxx`. + + For the `conda` fans, this tool can also be used to auto-load a + pre-configured `conda` environment since the `.envrc` is essentially a bash + script with a few bells and whistles tacked on. + + + +[^but-conda]: There are rumors of using `conda` creatively to do a user-install, +but that is not an option we support or suggest. + diff --git a/components/eamxx/docs/developer/style/style.md b/components/eamxx/docs/developer/style/style.md new file mode 100644 index 000000000000..72345b5af902 --- /dev/null +++ b/components/eamxx/docs/developer/style/style.md @@ -0,0 +1,56 @@ +# EAMxx Code Style Standards + +EAMxx does not currently impose strict styling standards, other than those of +the autoformatter. +However, if we can follow consistent style and usage guidelines, we can make +EAMxx developers' lives easier and turnaround times quicker. +In the age of modern text editors with autocomplete and running our code on +machines with enormous storage capacity, there is no real need to save screen +or disk space with minimal naming strategies or other meaning-obscuring style +choices. +So, please adhere to the spirit of these guidelines, and your fellow developers +will thank you for it! + +## General Guidelines + +- Please give ***descriptive***, rather than ***terse***, names to your + variables, functions, classes, etc. +- Avoid idiosyncratic naming or styling conventions. + - If the utility of a style decision would not be immediately apparent to + a reasonable developer, please avoid its usage. +- In the hierarchy of coding concerns, correctness and speed take the top + tiers, but below that level, please favor readability and clarity over + space savings, line-breaking, heavy use of arcane language features, etc. + - That said, if an arcane language feature ***is*** the correct tool to + be used, please do so. + - And perhaps add a comment to aid the non-Jedi-Master developers who + read the code next. :slightly_smiling_face: +- With regard to comments, the general wisdom is that the correct amount of + comments is the amount required to make the code clear and easy to understand. + - To quote + [Jeff Atwood](https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/) + from his essay about code comments: + > Only at the point where the code *cannot* be made easier to understand + should you begin to add comments. + - However, since that does not offer much in the way of prescriptive + guidance, here are some guidelines gathered from around the internet. + - A general rule of thumb, though not always true, is that comments + should explain ***why*** something is being done in the code, + rather than ***what*** the code is doing.[^butwhattabout] + - Comments should dispel confusion and not cause it. + - Comments should not duplicate the code.[^dupe] + - Provide links or references when using code from elsewhere or + whenever it is otherwise appropriate. + - A bad comment is worse than no comment. + - Add comments to explain non-standard usage or unidiomatic code. + +[^butwhattabout]: An obvious exception to this is explaining complex or opaque +parts of the code that cannot be made simpler--for instance, a clever arithmetic +trick in a complicated interpolation scheme. +[^dupe]: For example, this type of comment does not add any information and +is unnecessary. + + ```c++ + // perform initialization + this->initialize(); + ``` diff --git a/components/eamxx/docs/developer/style/style_guide_overview.md b/components/eamxx/docs/developer/style/style_guide_overview.md new file mode 100644 index 000000000000..93691250a0d6 --- /dev/null +++ b/components/eamxx/docs/developer/style/style_guide_overview.md @@ -0,0 +1,25 @@ +# EAMxx C++ Style Guide + +EAMxx enforces some standards on ***style*** and ***format***. +For the purpose of this guide, we draw a distinction between these two related +topics and loosely define them as: + +- **Style** + - Style is concerned with how the code ***reads*** on a lexical level as + well as with the structural and technical decisions that determine how + the code ***runs***. + - For example: + - Descriptive, as opposed to terse, variable names. + - Employing small, single-purpose functions. + - Usage or non-usage of advanced C++ features. + - The usage and content of comments. +- **Format** + - Format is the domain of how the code ***looks*** or how the code is + organized. + - The good news for formatting is that we enforce a strict, LLVM-based + formatting standard, and we employ + [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html) + to automatically conduct and enforce this standard. + +More detail regarding each of these topics is contained in the following +sections. diff --git a/components/eamxx/docs/developer/style/templates.md b/components/eamxx/docs/developer/style/templates.md new file mode 100644 index 000000000000..402991b27ead --- /dev/null +++ b/components/eamxx/docs/developer/style/templates.md @@ -0,0 +1,31 @@ +# Templating + +- Templating and polymorphism are arguably the most powerful features of C++, + but with great power comes great potential pain. + - EAMxx makes extensive use of templates, throughout, and this is encouraged + but should be done judiciously. + - Adding complexity should only be done in service of improved + functionality or speed because these typically come at the price of + clarity and readability. +- Template parameters should mostly obey the same naming conventions of the + type they correspond to. + - `lower_snake_case` for variables. + - E.g., variables of integral types or objects. + - `UpperCamelCase` for types, classes, or structs. + - However, terseness that follows EAMxx or Kokkos conventions can improve + readability, though favoring ***descriptiveness*** should be the default + case. + - Take this `update()` function declaration as an example. + + ```c++ + template + void update(const Field &x, const ST alpha, const ST beta); + ``` + + - The first template parameter is an integer-pointer that self-describes. + - The second template parameter, `HD` (`enum` type), is + tersely-named but the type provides sufficient descriptive + information. + - The second and third template parameters, including `ST` + ("scalar type"), are standard conventions used throughout EAMxx, and + the abbreviation saves an enormous amount of space in aggregate. diff --git a/components/eamxx/docs/developer/style/types.md b/components/eamxx/docs/developer/style/types.md new file mode 100644 index 000000000000..61bc0575651a --- /dev/null +++ b/components/eamxx/docs/developer/style/types.md @@ -0,0 +1,95 @@ +# Types, Classes, Structures + +## Naming + +- Please name types (classes, structures/`struct`, enumerations/`enum`) as + ***descriptive nouns***, + that describe what the type *is* or what its *purpose* is. + - As an example, `AtmosphericManipulator` and not `Manipulator` or `AtMnp`. + - If you find yourself unable to name your type this way, that may + indicate that it should be broken into independent classes, variables, + or functions. + - See FIXME: below for an example. +- Types, classes, or structs should make use of `UpperCamelCase`. + - Variables containing an object or an instance of a type, class, or struct, + should follow the + [naming convention for variables](variables.md#naming) + and be `lower_snake_case`. + +## Usage + +- There should be a logical grouping among the variables and classes contained + in a type, such that the name captures that association. + - To demonstrate, consider the following `Fruit` class. + + ```c++ + class Fruit { + enum FruitName {Apple, Banana, Orange}; + + FruitName m_fruit_name; + + void is_juiceable(FruitName fruit_) { ... }; + + enum Color {Red, Green, Blue}; + + Color fruit_color; + + bool is_favorite_color(Color color_) { ... }; + }; + ``` + + - It would be better to break this into a separate `Fruit` and `Color` + class because: + 1. `Color` is not inherently associated with fruits--it could also + belong to, for instance, a `Vegetable` class. + 2. There is no strong reason the `is_favorite_color()` needs to be a + part of `Fruit`, since it would work the same way if it knew nothing + about fruits. +- Related to the previous guideline, types/classes/structs should ideally + encapsulate ***concepts*** to improve both readability and usability. + - This implies that even a small struct has a reason to exist when it + serves the goal of shrinking or simplifying the outer class. + - An example of this in EAMxx is the + [`TimeInterval`](https://github.com/E3SM-Project/E3SM/blob/75b5b0a0c9078e18736860b2445a8975d7de750d/components/eamxx/src/share/util/eamxx_time_stamp.hpp#L114) + struct that only contains 4 class variables and 3 relatively simple + methods; yet, it serves to keep the + [`DataInterpolation`](https://github.com/E3SM-Project/E3SM/blob/75b5b0a0c9078e18736860b2445a8975d7de750d/components/eamxx/src/share/util/eamxx_data_interpolation.hpp#L14) + class smaller and better-organized. + +### Organization + +For the sake of consistency to aid readability and findability, we recommend +classes be organized (ordered) according to the following rules. + +- Public interfaces should appear at the top of a class declaration. + - These are the typically what other developers or users will be looking + for when reading or interacting with your code. +- Place methods first and class variables last, according to the same logic as + above. +- Group methods of the same "kind" or "purpose." + - E.g., group *getters* together and separate them from state-changing + methods that are also grouped together. + - Avoid interleaving functions of different kind. +- Seek to group class-variable declarations together in a meaningful way. + - This could be according to the actual C++ ***type***, but even better + would be done according to how the variables will be used or what + other parts of the code they will interact with. + - To illustrate, in the snippet below, a class storing 2 grid-types and + a `bool` should prefer `class A` to `class B` + + ```c++ + class A { + MyGrid source; + MyGrid target; + bool forward; + }; + class B { + MyGrid source; + bool forward; + MyGrid target; + }; + ``` + +We acknowledge that these rules do not form a complete logical schema, and so, +we defer to the judgement of the developer and their willingness to consider +the poor souls that will one day read their code. :slightly_smiling_face: diff --git a/components/eamxx/docs/developer/style/variables.md b/components/eamxx/docs/developer/style/variables.md new file mode 100644 index 000000000000..ad1324037c16 --- /dev/null +++ b/components/eamxx/docs/developer/style/variables.md @@ -0,0 +1,69 @@ +# Variables + +## Naming + +- Please name variables as ***descriptive nouns***. + - That is, for a variable holding data related to *horizontal winds*, choose + `horizontal_winds` or even `horiz_winds` versus `wh`. + - In cases for which this may be untenable, add comments explaining + non-obvious variable names. +- In general, variables should use `snake_case` and be entirely lowercase, + unless capitalizing is a standard convention (e.g., `T` for temperature). +- We do not currently employ a stylistic distinction between different types of + variables--e.g., `const`, `static`, member variables, etc. +- We do, however, ask that some convention is employed to identify member + variables of a class. + - Some commonly used techniques include distinguishing member variables + with a leading `m_` (`m_var` $\approx$ "my var"), or a trailing/leading + underscore (`var_` or `_var`). + - That said, this convention should be ***locally consistent*** within a + given class, struct, or otherwise. +- As to favoring ***nouns*** for naming, one should avoid using articles or + verbs in variable names. + - The key "exception" here would be prefixes like `is_`, `has_`, `can_` + that are commonly used with boolean variables. + +## Usage + +### Intermediate Variables + +There is a balance to be struck between introducing extra, or intermediate, +variables and avoiding excess allocations/de-allocations or minimizing clutter. + +- In line with the hierarchy of correct/fast/understandable, mentioned in + the [Style Standards Overview](style.md#general-guidelines), + it often improves matters to introduce an intermediate variable, + pointer, subview, etc., rather than triply-indexing into a variable + that's contained within a class-member struct. +- This principle applies to calculations as well, as there are situations + in which readability is improved by breaking complex operations into + multiple steps. +- **Generally speaking**, unless the code is highly-optimized and/or + performance-critical, **usage of intermediate variables is preferred**. + - Here, readability and bug-safety are the top concerns, so the clarity + provided by descriptive intermediate variables and resultant shorter + lines, trumps most other factors. + +### Descriptive Power vs. Brevity in Naming + +There is obvious a crossover point at which a name becomes **too** descriptive +or simply too long, so as to be cumbersome to use. +Thus, the issue of descriptive naming should be balanced against brevity in +name choice, and we give some examples and rules of thumb. + +- Consider synonyms that may shorten a variable name without sacrificing clarity. +- Make use of common word truncations or abbreviations. + - E.g., `mgr` instead of `manager` or `dev` in place of `device`. + - However, avoid non-standard abbreviations that may only be common + parlance within a small group. + - This includes names that correspond to standard arithmetic variables + in an equation (`gamma`, `y_hat`), ***unless*** the equation is + included as a comment and the connection is readily apparent. +- The converse of the previous is avoid making contractions that negatively + impact clarity. + - A notorious example of this is removing vowels. + - E.g., `loop_cnt`, rather than `loop_count` provides little savings, + at the expense of clarity.[^funfact] + +[^funfact]: Much like some [dangerous options-trading strategies](https://www.investopedia.com/ask/answers/050115/what-types-options-positions-create-unlimited-liability.asp), +this practice offers limited upside, yet the potential downside is unlimited. diff --git a/components/eamxx/docs/developer/style_guide.md b/components/eamxx/docs/developer/style_guide.md deleted file mode 100644 index 102f4d7b489f..000000000000 --- a/components/eamxx/docs/developer/style_guide.md +++ /dev/null @@ -1,9 +0,0 @@ -# EAMxx C++ Style Guide - -Here's our style guide. Let the holy wars begin! - -## Types - -## Functions and Methods - -## Variables diff --git a/components/eamxx/docs/refs/aerocom_cldtop.bib b/components/eamxx/docs/refs/aerocom_cldtop.bib deleted file mode 100644 index 45ed58088600..000000000000 --- a/components/eamxx/docs/refs/aerocom_cldtop.bib +++ /dev/null @@ -1,24 +0,0 @@ - -@techreport{tiedtke_ecmwf_1979, - address = {Shinfield Park, Reading}, - type = {Technical {Report}}, - title = {{ECMWF} model parameterisation of sub-grid scale processes}, - language = {en}, - institution = {ECMWF}, - author = {Tiedtke, M. and Geleyn, J.-F. and Hollingsworth, A. and Louis, J.-F.}, - month = jan, - year = {1979}, - note = {10}, - pages = {146}, -} - -@article{raisanen2004stochastic, - title={Stochastic generation of subgrid-scale cloudy columns for large-scale models}, - author={R{\"a}is{\"a}nen, Petri and Barker, Howard W and Khairoutdinov, Marat F and Li, Jiangnan and Randall, David A}, - journal={Quarterly Journal of the Royal Meteorological Society: A journal of the atmospheric sciences, applied meteorology and physical oceanography}, - volume={130}, - number={601}, - pages={2047--2067}, - year={2004}, - publisher={Wiley Online Library} -} diff --git a/components/eamxx/docs/refs/general.bib b/components/eamxx/docs/refs/eamxx.bib similarity index 87% rename from components/eamxx/docs/refs/general.bib rename to components/eamxx/docs/refs/eamxx.bib index b87994f796db..75ea44c1517f 100644 --- a/components/eamxx/docs/refs/general.bib +++ b/components/eamxx/docs/refs/eamxx.bib @@ -122,3 +122,27 @@ @article{Taylor_et20 note = {e2019MS001783 10.1029/2019MS001783}, year = {2020} } + +@techreport{tiedtke_ecmwf_1979, + address = {Shinfield Park, Reading}, + type = {Technical {Report}}, + title = {{ECMWF} model parameterisation of sub-grid scale processes}, + language = {en}, + institution = {ECMWF}, + author = {Tiedtke, M. and Geleyn, J.-F. and Hollingsworth, A. and Louis, J.-F.}, + month = jan, + year = {1979}, + note = {10}, + pages = {146}, +} + +@article{raisanen2004stochastic, + title={Stochastic generation of subgrid-scale cloudy columns for large-scale models}, + author={R{\"a}is{\"a}nen, Petri and Barker, Howard W and Khairoutdinov, Marat F and Li, Jiangnan and Randall, David A}, + journal={Quarterly Journal of the Royal Meteorological Society: A journal of the atmospheric sciences, applied meteorology and physical oceanography}, + volume={130}, + number={601}, + pages={2047--2067}, + year={2004}, + publisher={Wiley Online Library} +} diff --git a/components/eamxx/mkdocs.yml b/components/eamxx/mkdocs.yml index d8a96adf17f4..edb6c516558d 100644 --- a/components/eamxx/mkdocs.yml +++ b/components/eamxx/mkdocs.yml @@ -2,12 +2,9 @@ site_name: EAMxx nav: - 'Home': 'index.md' - # - 'WIP Sandbox': 'WIP.md' - 'User Guide': - 'Overview': 'user/index.md' - # - 'Quick-start Guide': 'user/user_quickstart.md' - 'EAMxx case basics': 'user/eamxx_cases.md' - # - 'Testing': 'user/user_testing.md' - 'Model Configuration': 'user/model_configuration.md' - 'Nudging': 'user/nudging.md' - 'Extra radiation calls': 'user/clean_clear_sky.md' @@ -23,19 +20,25 @@ nav: - 'Field contraction diagnostics': 'user/diags/field_contraction.md' - 'Presentations': 'user/presentations.md' - 'Developer Guide': - # - 'Overview': 'developer/index.md' - 'Quick-start Guide': 'developer/dev_quickstart.md' - 'Code Structure and Organization': 'developer/code_structure.md' - # - 'Installation': 'common/installation.md' - - 'Style Guide': 'developer/style_guide.md' + - 'Style Guide': + - 'Overview': 'developer/style/style_guide_overview.md' + - 'Code Formatting Standards': 'developer/style/format.md' + - 'Code Style Standards': + - 'Overview': 'developer/style/style.md' + - 'Types, Classes, Structures': 'developer/style/types.md' + - 'Functions and Methods': 'developer/style/functions.md' + - 'Variables': 'developer/style/variables.md' + - 'Templating': 'developer/style/templates.md' + - 'Resources': + - 'How-to Guide: clang-format': 'developer/style/resources/clang-format_HOWTO.md' - 'Testing': - 'Overview': 'developer/dev_testing/index.md' - 'Testing for Development': 'developer/dev_testing/testing_for_development.md' - 'Automated Standalone Testing': 'developer/dev_testing/test_all_eamxx.md' - 'Full model (CIME)': 'developer/dev_testing/full_model_testing.md' - 'CI and Nightly Testing': 'developer/dev_testing/ci_nightly.md' - # - 'Supported Computing Platforms': 'developer/dev_testing/supported_machines.md' - # - 'Testing Locally': 'developer/dev_testing/local_test.md' - 'Important Tools and Objects': - 'Kokkos and EKAT': 'developer/kokkos_ekat.md' - 'Fields': 'developer/field.md' @@ -46,7 +49,6 @@ nav: - 'Technical Guide': - 'Overview': 'technical/index.md' - 'AeroCom cloud top': 'technical/aerocom_cldtop.md' - # - 'Glossary': 'common/glossary.md' edit_uri: "" diff --git a/docs/refs/eamxx.bib b/docs/refs/eamxx.bib new file mode 100644 index 000000000000..75ea44c1517f --- /dev/null +++ b/docs/refs/eamxx.bib @@ -0,0 +1,148 @@ +@article{Bogenschutz_Krueger13, +author = {Bogenschutz, Peter A. and Krueger, Steven K.}, +title = {A simplified PDF parameterization of subgrid-scale clouds and turbulence for cloud-resolving models}, +journal = {Journal of Advances in Modeling Earth Systems}, +volume = {5}, +number = {2}, +pages = {195-211}, +keywords = {cloud parameterization, turbulence, boundary layer clouds}, +doi = {https://doi.org/10.1002/jame.20018}, +url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1002/jame.20018}, +year = {2013} +} + +@Article{Bradley_et22, +AUTHOR = {Bradley, A. M. and Bosler, P. A. and Guba, O.}, +TITLE = {Islet: interpolation semi-Lagrangian element-based transport}, +JOURNAL = {Geoscientific Model Development}, +VOLUME = {15}, +YEAR = {2022}, +NUMBER = {16}, +PAGES = {6285--6310}, +URL = {https://gmd.copernicus.org/articles/15/6285/2022/}, +DOI = {10.5194/gmd-15-6285-2022} +} + +@article{Caldwell_et21, +author = {Caldwell, P. M. and Terai, C. R. and Hillman, B. and Keen, N. D. and Bogenschutz, P. and Lin, W. and Beydoun, H. and Taylor, M. and Bertagna, L. and Bradley, A. M. and Clevenger, T. C. and Donahue, A. S. and Eldred, C. and Foucar, J. and Golaz, J.-C. and Guba, O. and Jacob, R. and Johnson, J. and Krishna, J. and Liu, W. and Pressel, K. and Salinger, A. G. and Singh, B. and Steyer, A. and Ullrich, P. and Wu, D. and Yuan, X. and Shpund, J. and Ma, H.-Y. and Zender, C. S.}, +title = {Convection-Permitting Simulations With the E3SM Global Atmosphere Model}, +journal = {Journal of Advances in Modeling Earth Systems}, +volume = {13}, +number = {11}, +pages = {e2021MS002544}, +keywords = {cloud resolving model, storm resolving model, general circulation model, convection permitting model, E3SM}, +doi = {https://doi.org/10.1029/2021MS002544}, +url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2021MS002544}, +eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2021MS002544}, +note = {e2021MS002544 2021MS002544}, +year = {2021} +} + +@article{Fiedler_Panofsky72, +author = {Fiedler, F. and Panofsky, H. A.}, +title = {The geostrophic drag coefficient and the ‘effective’ roughness length}, +journal = {Quarterly Journal of the Royal Meteorological Society}, +volume = {98}, +number = {415}, +pages = {213-220}, +doi = {https://doi.org/10.1002/qj.49709841519}, +url = {https://rmets.onlinelibrary.wiley.com/doi/abs/10.1002/qj.49709841519}, +eprint = {https://rmets.onlinelibrary.wiley.com/doi/pdf/10.1002/qj.49709841519}, +abstract = {Abstract An ‘effective’ roughness length is defined for use over heterogeneous terrain as the roughness length which homogeneous terrain would have to give the correct surface stress over a given area. A method is suggested to compute geostrophic drag coefficient, wind-contour angle and surface heat flux, given this roughness length, latitude, geostrophic wind speed and insolation or ground-air temperature differences.}, +year = {1972} +} + + +@article{Hannah_et21, +author = {Hannah, Walter M. and Bradley, Andrew M. and Guba, Oksana and Tang, Qi and Golaz, Jean-Christophe and Wolfe, Jon}, +title = {Separating Physics and Dynamics Grids for Improved Computational Efficiency in Spectral Element Earth System Models}, +journal = {Journal of Advances in Modeling Earth Systems}, +volume = {13}, +number = {7}, +pages = {e2020MS002419}, +keywords = {computational efficiency, E3SM, effective resolution, grid remap methods}, +doi = {https://doi.org/10.1029/2020MS002419}, +url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2020MS002419}, +eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2020MS002419}, +note = {e2020MS002419 2020MS002419}, +year = {2021} +} + +@article {Morrison_Milbrandt15, + author = "Hugh Morrison and Jason A. Milbrandt", + title = "Parameterization of Cloud Microphysics Based on the Prediction of Bulk Ice Particle Properties. Part I: Scheme Description and Idealized Tests", + journal = "Journal of the Atmospheric Sciences", + year = "2015", + publisher = "American Meteorological Society", + address = "Boston MA, USA", + volume = "72", + number = "1", + doi = "10.1175/JAS-D-14-0065.1", + pages= "287 - 311", + url = "https://journals.ametsoc.org/view/journals/atsc/72/1/jas-d-14-0065.1.xml" +} + +@article{Pincus_et19, +author = {Pincus, Robert and Mlawer, Eli J. and Delamere, Jennifer S.}, +title = {Balancing Accuracy, Efficiency, and Flexibility in Radiation Calculations for Dynamical Models}, +journal = {Journal of Advances in Modeling Earth Systems}, +volume = {11}, +number = {10}, +pages = {3074-3089}, +keywords = {radiation, atmospheric model, parameterization}, +doi = {https://doi.org/10.1029/2019MS001621}, +url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2019MS001621}, +eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2019MS001621}, +year = {2019} +} + +@Article{Stevens_et17, +AUTHOR = {Stevens, B. and Fiedler, S. and Kinne, S. and Peters, K. and Rast, S. and M\"usse, J. and Smith, S. J. and Mauritsen, T.}, +TITLE = {MACv2-SP: a parameterization of anthropogenic aerosol optical properties and an associated Twomey effect for use in CMIP6}, +JOURNAL = {Geoscientific Model Development}, +VOLUME = {10}, +YEAR = {2017}, +NUMBER = {1}, +PAGES = {433--452}, +URL = {https://gmd.copernicus.org/articles/10/433/2017/}, +DOI = {10.5194/gmd-10-433-2017} +} + +@article{Taylor_et20, +author = {Taylor, Mark A. and Guba, Oksana and Steyer, Andrew and Ullrich, Paul A. and Hall, David M. and Eldred, Christopher}, +title = {An Energy Consistent Discretization of the Nonhydrostatic Equations in Primitive Variables}, +journal = {Journal of Advances in Modeling Earth Systems}, +volume = {12}, +number = {1}, +pages = {e2019MS001783}, +keywords = {nonhydrostatic, hamiltonian, dynamical core, energy conservation, mimetic}, +doi = {https://doi.org/10.1029/2019MS001783}, +url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2019MS001783}, +eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2019MS001783}, +note = {e2019MS001783 10.1029/2019MS001783}, +year = {2020} +} + +@techreport{tiedtke_ecmwf_1979, + address = {Shinfield Park, Reading}, + type = {Technical {Report}}, + title = {{ECMWF} model parameterisation of sub-grid scale processes}, + language = {en}, + institution = {ECMWF}, + author = {Tiedtke, M. and Geleyn, J.-F. and Hollingsworth, A. and Louis, J.-F.}, + month = jan, + year = {1979}, + note = {10}, + pages = {146}, +} + +@article{raisanen2004stochastic, + title={Stochastic generation of subgrid-scale cloudy columns for large-scale models}, + author={R{\"a}is{\"a}nen, Petri and Barker, Howard W and Khairoutdinov, Marat F and Li, Jiangnan and Randall, David A}, + journal={Quarterly Journal of the Royal Meteorological Society: A journal of the atmospheric sciences, applied meteorology and physical oceanography}, + volume={130}, + number={601}, + pages={2047--2067}, + year={2004}, + publisher={Wiley Online Library} +} diff --git a/mkdocs.yaml b/mkdocs.yaml index fc1508f4c397..e2a806af550f 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -62,6 +62,7 @@ markdown_extensions: - pymdownx.arithmatex: generic: true - md_in_html + - attr_list - tables - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji