From 4c94bb5378a645203c58f0f749b4b631b49309ee Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Mon, 20 May 2024 10:08:20 -0600 Subject: [PATCH 1/5] Add info about new suite naming guidelines --- CCPPtechnical/source/ConstructingSuite.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CCPPtechnical/source/ConstructingSuite.rst b/CCPPtechnical/source/ConstructingSuite.rst index 1aedeb1..7717fa0 100644 --- a/CCPPtechnical/source/ConstructingSuite.rst +++ b/CCPPtechnical/source/ConstructingSuite.rst @@ -14,7 +14,11 @@ In addition to the :term:`primary parameterization ` categories The format of the SDF is specified by a schema and all host models that use :term:`CCPP` include file ``suite.xsd`` to describe the schema. -The name of the suite is listed at the top of the SDF, right after the XML declaration, and must be consistent with the name of the SDF: file ``suite_ABC.xml`` contains ``suite name=’ABC’``, as in the example below. The suite name is followed by the version of the XML schema used. +The name of the suite is listed at the top of the SDF, right after the XML declaration, and must be consistent with the name of the SDF: file ``ABC.xml`` contains ``suite name="ABC"``, as in the example below. The suite name is followed by the version of the XML schema used. There is no technical restriction on the names that a suite can have, but the convention decided on by CCPP developers has been to avoid "self-descriptive" names; this avoids many problems with confusion about the contents and use of various suite files (see `this presentation `_ for further reasoning). + +A suite file should also include a description as an xml comment; it is recommended that this description be as verbose as possible as to the reason why this particular set and order of schemes was selected. For example, if it was created for a particular operational prototype, used in a particular study, or (if a modified version of another suite), the reasoning for a specific modification. + +Suite filenames must be in the form ``suitename.xml``, where ``suitename`` is the name of the physics suite as referenced by the suite tag -------------- Groups From e2c61b809fe4f42d1212e5e5a79365ec29d679a4 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Tue, 21 May 2024 21:35:45 -0600 Subject: [PATCH 2/5] Some more detail on arbitrary nature of suite names --- CCPPtechnical/source/ConstructingSuite.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CCPPtechnical/source/ConstructingSuite.rst b/CCPPtechnical/source/ConstructingSuite.rst index 7717fa0..a1f2f44 100644 --- a/CCPPtechnical/source/ConstructingSuite.rst +++ b/CCPPtechnical/source/ConstructingSuite.rst @@ -14,7 +14,7 @@ In addition to the :term:`primary parameterization ` categories The format of the SDF is specified by a schema and all host models that use :term:`CCPP` include file ``suite.xsd`` to describe the schema. -The name of the suite is listed at the top of the SDF, right after the XML declaration, and must be consistent with the name of the SDF: file ``ABC.xml`` contains ``suite name="ABC"``, as in the example below. The suite name is followed by the version of the XML schema used. There is no technical restriction on the names that a suite can have, but the convention decided on by CCPP developers has been to avoid "self-descriptive" names; this avoids many problems with confusion about the contents and use of various suite files (see `this presentation `_ for further reasoning). +The name of the suite is listed at the top of the SDF, right after the XML declaration, and must be consistent with the name of the SDF: file ``ABC.xml`` contains ``suite name="ABC"``, as in the example below. The suite name is followed by the version of the XML schema used. There is no technical restriction on the names that a suite can have, but the convention decided on by CCPP developers has been to avoid "self-descriptive" names; this avoids many problems with confusion about the contents and use of various suite files (see `this presentation `_ for further reasoning). For the initial roll-out, a convention of bird names was arbitrarily adopted. A suite file should also include a description as an xml comment; it is recommended that this description be as verbose as possible as to the reason why this particular set and order of schemes was selected. For example, if it was created for a particular operational prototype, used in a particular study, or (if a modified version of another suite), the reasoning for a specific modification. From 12e0a6fe29f449cadaf5e4e2c19b946cdb0e8623 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Tue, 21 May 2024 22:48:19 -0600 Subject: [PATCH 3/5] Add example of description comment and suite name tag --- CCPPtechnical/source/ConstructingSuite.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/CCPPtechnical/source/ConstructingSuite.rst b/CCPPtechnical/source/ConstructingSuite.rst index a1f2f44..c465ebe 100644 --- a/CCPPtechnical/source/ConstructingSuite.rst +++ b/CCPPtechnical/source/ConstructingSuite.rst @@ -18,7 +18,18 @@ The name of the suite is listed at the top of the SDF, right after the XML decla A suite file should also include a description as an xml comment; it is recommended that this description be as verbose as possible as to the reason why this particular set and order of schemes was selected. For example, if it was created for a particular operational prototype, used in a particular study, or (if a modified version of another suite), the reasoning for a specific modification. -Suite filenames must be in the form ``suitename.xml``, where ``suitename`` is the name of the physics suite as referenced by the suite tag +Suite filenames must be in the form ``suitename.xml``, where ``suitename`` is the name of the physics suite as referenced by the suite tag: + +.. code-block:: xml + > cat crossbill.xml + + + + ... + ... -------------- Groups From f737d46921c186ba274b12043d887d1e693ba5c3 Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Tue, 21 May 2024 22:51:28 -0600 Subject: [PATCH 4/5] Fix formatting of example --- CCPPtechnical/source/ConstructingSuite.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/CCPPtechnical/source/ConstructingSuite.rst b/CCPPtechnical/source/ConstructingSuite.rst index c465ebe..0f49540 100644 --- a/CCPPtechnical/source/ConstructingSuite.rst +++ b/CCPPtechnical/source/ConstructingSuite.rst @@ -21,6 +21,7 @@ A suite file should also include a description as an xml comment; it is recommen Suite filenames must be in the form ``suitename.xml``, where ``suitename`` is the name of the physics suite as referenced by the suite tag: .. code-block:: xml + > cat crossbill.xml