Proposed format change for pcd.yaml

docs/cpcd-parser.md

@@ -1,6 +1,7 @@
 # The CPCD Parser
 
-The Community Physical Constant Dictionary (CPCD) parser is a command-line tool that allow users to lookup physical constants in the YAML dictionary file and include them in their code by generating a suitable source file.
+The Community Physical Constant Dictionary (CPCD) parser is a command-line tool that allow users to generate a Fortran source file containing all or a selection of the contstants in the YAML
+Physical Constants Dictionary.
 
 ## Requirements
 
@@ -88,44 +89,39 @@ Main tool to validate, parse, and extract physical constant sets from the Commun
 
 Mandatory arguments to long options are mandatory for short options too.
   -d, --dictionary YAML_FILE    Use YAML_FILE as dictionary
-  -r, --request YAML_FILE       Extract constants listed in YAML_FILE
+  -r, --request YAML_FILE       Extract constants listed in YAML_FILE (optional)
+                                If not specified, extracts all constants
   -o, --output FILE             Save Fortran output to FILE
   -x, --validate                Validate dictionary file before proceeding
   -v, --verbose                 Use verbose output
   -V, --version                 Print version information
   -h, --help                    Display available options
 
 Exit status: 0 if successful, 1 if an error occurs.
-For bugs reporting, please visit: <https://github.com/ESCOMP/PhysicalConstantsDictionary>
+For bugs reporting, please visit: <https://github.com/ICAMS-US/PhysicalConstantsDictionary>
 ```
 
 ### Request File Format
 
-A collection of physical constants to be extracted from the dictionary is provided to the CPCD parser also in a YAML file. A sample file (`req.yaml`) is distributed with this package in the `cpcd/test/` directory. Its content is included below:
+A collection of physical constants to be extracted from the dictionary can be provided to the CPCD parser also in a YAML file. A sample file (`req.yaml`) is distributed with this package in the `cpcd/test/` directory. Its content is included below:
 
 ```yaml
 # This is an example of a user-requested list of physical constants
 # to be looked up in the dictionary by the CPCD parser and included
 # in the generated source code.
 
-ASHandbook1964: [ pi, gamma ]
-
-CODATA2014:
-  - standard_acceleration_of_gravity
-  - speed_of_light_in_vacuum
-  - stefan_boltzmann_constant
-
-GRS80: mean_radius
-
-IAPWS1995: [ liquid_water_triple_point_density, vapor_water_triple_point_density ]
-
-ASHandbook1964: square_root_of_2
-ASHandbook1964: pi
+mathematical: [pi, em_gamma, square_root_of_2]
+universal_physical:
+    - standard_acceleration_of_gravity
+    - speed_of_light_in_vacuum
+    - stefan_boltzmann_constant
+earth_physical: mean_radius
+water: [ liquid_water_triple_point_density, vapor_water_triple_point_density ]
 ```
 
 ### Example Usage
 
-When the file above is provided to `cpcd` via option `-r`, the CPCD parser will output a source file that can be added to a model source code. Fortran is the only output language currently supported by the CPCD parser.
+The CPCD parser will output a source file that can be added to a model source code. Fortran is the only output language currently supported by the CPCD parser.
 
 The following command:
 
@@ -137,24 +133,25 @@ will generate the Fortran module file `cpcd_mod.F90` in the current directory. T
 
 ```fortran
 module cpcd
-  integer, parameter :: cpcd_kind = kind(1.d0)
-
-  ! - from set ASHandbook1964
-  real(cpcd_kind), parameter :: ASHandbook1964_pi = 3.141592653589793238462643_cpcd_kind
-  real(cpcd_kind), parameter :: ASHandbook1964_gamma = 0.577215664901532860606512_cpcd_kind
-  real(cpcd_kind), parameter :: ASHandbook1964_square_root_of_2 = 1.4142135623730950488_cpcd_kind
 
-  ! - from set CODATA2014
-  real(cpcd_kind), parameter :: CODATA2014_speed_of_light_in_vacuum = 299792458_cpcd_kind
-  real(cpcd_kind), parameter :: CODATA2014_standard_acceleration_of_gravity = 9.80665_cpcd_kind
-  real(cpcd_kind), parameter :: CODATA2014_stefan_boltzmann_constant = 5.67036713E-08_cpcd_kind
-
-  ! - from set GRS80
-  real(cpcd_kind), parameter :: GRS80_mean_radius = 6371008.7714_cpcd_kind
+  integer, parameter :: cpcd_kind = kind(1.d0)
 
-  ! - from set IAPWS1995
-  real(cpcd_kind), parameter :: IAPWS1995_liquid_water_triple_point_density = 999.793_cpcd_kind
-  real(cpcd_kind), parameter :: IAPWS1995_vapor_water_triple_point_density = 0.00485458_cpcd_kind
+  character(len=*), parameter :: cpcd_version = '0.0.1'
+  character(len=*), parameter :: cpcd_institution = 'ICAMS'
+
+! - from set mathematical
+  real(cpcd_kind), parameter :: mathematical_pi = 3.141592653589793238462643_cpcd_kind
+  real(cpcd_kind), parameter :: mathematical_em_gamma = 0.577215664901532860606512_cpcd_kind
+  real(cpcd_kind), parameter :: mathematical_square_root_of_2 = 1.4142135623730950488_cpcd_kind
+! - from set universal_physical
+  real(cpcd_kind), parameter :: universal_physical_speed_of_light_in_vacuum = 299792458_cpcd_kind
+  real(cpcd_kind), parameter :: universal_physical_standard_acceleration_of_gravity = 9.80665_cpcd_kind
+  real(cpcd_kind), parameter :: universal_physical_stefan_boltzmann_constant = 5.67036713E-08_cpcd_kind
+! - from set earth_physical
+  real(cpcd_kind), parameter :: earth_physical_mean_radius = 6371008.7714_cpcd_kind
+! - from set water
+  real(cpcd_kind), parameter :: water_liquid_water_triple_point_density = 999.793_cpcd_kind
+  real(cpcd_kind), parameter :: water_vapor_water_triple_point_density = 0.00485458_cpcd_kind
 
 end module cpcd
 ```

docs/dictionary-syntax.md

@@ -17,11 +17,11 @@ physical_constants_dictionary:
 
 The value associated to the `physical_constants_dictionary` key consists of the following YAML mapping nodes:
 
-### version_number (optional)
+### version_number (mandatory)
 
 The dictionary version, as in the standard GNU scheme: major.minor.revision
 
-### institution (optional)
+### institution (mandatory)
 
 The name of the institution responsible for the dictionary
 
@@ -33,9 +33,15 @@ A short description of the dictionary file
 
 The email address of the designed POC for this file
 
+### references (mandatory)
+
+References that were used to obtain each value listed in the dictionary.  Each reference
+name starts with a key which is used later in each physical constant to indicate where
+the value came from.
+
 ### set (mandatory)
 
-Internally consistent physical constants sets are included as YAML [block sequences](http://yaml.org/spec/1.2/spec.html) of mappings. A physical constant set is codified as a YAML mapping node, with the set name as the main key. Each set must begin with a hyphen (-), separated by space from the set name (key).
+Physical constants sets are included as YAML [block sequences](http://yaml.org/spec/1.2/spec.html) of mappings. A physical constant set is codified as a YAML mapping node, with the set name as the main key. Each set must begin with a hyphen (-), separated by space from the set name (key).
 
 ## Physical Constants Sets
 
@@ -45,10 +51,6 @@ The value associated to a set key includes the following mapping nodes:
 
 A brief description of the constants set
 
-### citation (mandatory)
-
-Literature references associated with the set
-
 ### entries
 
 This node includes the actual dictionary entries for each physical constant included in the set. Entries are also organized as block sequences of mapping nodes, and must begin with a hyphen (-).
@@ -64,6 +66,7 @@ A physical constant entry can be defined as shown in the example below:
   prec: double
   type: strict
   uncertainty: exact
+  reference: key
   description: |
     Nominal acceleration of an object in a vacuum at sea level at a
     geodetic latitude of 45 degrees.
@@ -103,4 +106,4 @@ The constant's relative uncertainty (a number, or `exact`)
 
 ### description
 
-A detailed description of the physical constant, with additional references if necessary.
+A detailed description of the physical constant.

docs/index.md

@@ -1,14 +1,10 @@
 # Physical Constants Dictionary (PCD) Documentation
 
-This page provides up-to-date documentation of the features for the community-based Physical Constant Dictionary (PCD).
-
-Please contribute to it by opening an issue or pull request.
-
-Preliminary syntax rules for the YAML dictionary file are provided in [Dictionary Syntax](dictionary-syntax.md).
-
-An introductory guide to the CPCD parser is available in [The CPCD Parser](cpcd-parser.md).
-
-## Documentation Pages
+Features of the community-based Physical Constants Dictionary (PCD).
 
+## Syntax
 - [Dictionary Syntax](dictionary-syntax.md) - YAML syntax rules for the physical constants dictionary
-- [The CPCD Parser](cpcd-parser.md) - Guide to building and using the Community Physical Constant Dictionary parser
+
+## Parsers
+- [The CPCD Parser](cpcd-parser.md) - Building and using the C++ Community Physical Constants Dictionary parser
+- [Python Parser](python-parser.md) - Python based CPCD parser

docs/python-parser.md

@@ -0,0 +1,104 @@
+# Python Parser
+
+The Python parser (`tools/generate_source.py`) is a command-line tool for generating source code files from the `pcd.yaml` Physical Constants Dictionary. It is intended for use by Earth System Model applications to produce language-specific source files containing physical constants, ensuring that different parts of a project agree on common numerical values.
+
+## Requirements
+
+- Python 3
+- [PyYAML](https://pyyaml.org/) (`pip install pyyaml`)
+
+## Usage
+
+```
+generate_source.py --lang <LANG> --filename <FILE> [--groups <GROUP> ...]
+```
+
+### Options
+
+| Option | Short | Description |
+|---|---|---|
+| `--lang` | `-l` | Output language. Choices: `cxx` (C++ header) or `f90` (Fortran 90 module). Required. |
+| `--filename` | `-f` | Name of the generated output file. Required. |
+| `--groups` | `-g` | One or more groups to include. If omitted, all groups are included. |
+
+## Output Languages
+
+### C++ (`--lang cxx`)
+
+Generates a C++ header file that declares constants as `constexpr double` inside the `pcd` namespace, guarded by an include guard. Also provides `pcdversion` and `pcdinstitution` string constants.
+
+```cpp
+// WARNING! DO NOT EDIT THIS FILE!
+// This file was generated automatically from pcd.yaml
+// For more information, visit https://github.com/e3sm-project/PhysicalConstantsDictionary
+
+#ifndef PHYSICAL_CONSTANTS_DICTIONARY_HPP
+#define PHYSICAL_CONSTANTS_DICTIONARY_HPP
+
+#include <string>
+
+namespace pcd {
+
+// pcd.yaml version and institution information
+const std::string pcdversion = "1.0.0";
+const std::string pcdinstitution = "E3SM";
+
+// mathematics constants
+constexpr double pi = 3.14159265358979323846;
+// ...
+
+} // namespace pcd
+#endif // PHYSICAL_CONSTANTS_DICTIONARY
+```
+
+### Fortran 90 (`--lang f90`)
+
+Generates a Fortran 90 module named `pcd`. Constants are declared as double-precision `real` parameters using a locally defined `dp` kind. Also provides `pcdversion` and `pcdinstitution` character parameters.
+
+```fortran
+! WARNING! DO NOT EDIT THIS FILE!
+! This file was generated automatically from pcd.yaml
+! For more information, visit https://github.com/e3sm-project/PhysicalConstantsDictionary
+
+module pcd
+    implicit none
+
+    !define double precision kind
+    integer, parameter :: dp = selected_real_kind(12)
+
+    ! pcd.yaml version and institution information
+    character(len=*), parameter :: pcdversion = "1.0.0"
+    character(len=*), parameter :: pcdinstitution = "E3SM"
+
+    !mathematics constants
+    real(dp), parameter :: pi = 3.14159265358979323846_dp
+    ! ...
+
+end module pcd
+```
+
+## Examples
+
+Generate a Fortran 90 module with all constants:
+
+```bash
+python tools/generate_source.py --lang f90 --filename constants.F90
+```
+
+Generate a C++ header with only the `mathematics` group:
+
+```bash
+python tools/generate_source.py --lang cxx --groups mathematics --filename constants.h
+```
+
+Generate a Fortran 90 module with multiple specific groups:
+
+```bash
+python tools/generate_source.py --lang f90 --groups mathematics universal_physical --filename constants.F90
+```
+
+## Notes
+
+- The script reads `pcd.yaml` from the root of the repository (one level above `tools/`).
+- The generated file includes a warning comment at the top indicating it should not be edited manually.
+- If an invalid group name is supplied via `--groups`, the script exits with an error listing valid group names.