From 8534a77e22875419ce9240d83b332971246fd7ca Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 14 Feb 2022 15:35:15 -0500 Subject: [PATCH] Updated documentation accordingly for qfyaml 0.3.1 docs/source/known_bugs.rst - Add info about error returning long YAML sequences in v0.3.0 - Add info about array sizes restriction for QFYAML_Add_Get in v0.3.0 Signed-off-by: Bob Yantosca --- docs/source/known-bugs.rst | 24 ++++++++++ docs/source/running-tests.rst | 87 ++++++++++++++++++++--------------- 2 files changed, 73 insertions(+), 38 deletions(-) diff --git a/docs/source/known-bugs.rst b/docs/source/known-bugs.rst index 83d2924..50ed355 100644 --- a/docs/source/known-bugs.rst +++ b/docs/source/known-bugs.rst @@ -39,3 +39,27 @@ Use underscores instead of spaces in YAML sequence items: - Star_fruit And then you can remove the underscores in post-processing. + +Error returning long YAML sequences +=================================== + +It was discovered that only a subset long YAML sequences were being +returned. Upon further investigation, a string variable in routine +:file:`Get_Fields_string` was found to be too short to hold all of the +stored data within a YAML variable. + +We have fixed this behavior in :program:`qfyaml 0.3.1`. + +Arrays passed to QFYAML_Add_Get had to be the same size as the data in +the YAML file +=================================== + +When passing an array to routine :file:`QFYAML_Add_Get`, an error +would be returned if the array was not the same length as the array or +sequence in the YAML file. + +In :program:`qfyaml 0.3.1`, arrays that are larger than the size of +the data may be passed to :file:`QFYAML_Add_Get`. This will let you +declare an array size that is sufficiently large in the calling +routine. This can be especially useful if you do not know the size of +the data to be read in from the YAML file. diff --git a/docs/source/running-tests.rst b/docs/source/running-tests.rst index 05e9083..ae49ff6 100644 --- a/docs/source/running-tests.rst +++ b/docs/source/running-tests.rst @@ -37,8 +37,8 @@ output. If the test is successful you will see this output: .. code-block:: console - ### Reading input.yml - + ### Reading qfyaml.yml + ### YAML VARIABLES author%age : 29 author%fav_reals : 1.00 2.00 @@ -51,28 +51,28 @@ output. If the test is successful you will see this output: weather%temperature%daily : 23.043436 weather%temperature%weekly%units : K weather%pressure : 1013.250000 - + ### YAML SEQUENCES fruits 1 Apples 2 Bananas 3 Oranges - + more_fruits%p_fruits 1 Pears 2 Plums 3 Peaches 4 Pomegranites - + even_more_fruits%exotic_fruits%hard_to_find 1 Kumquats 2 Kiwi 3 Passion_fruit 4 Star_fruit 5 Durians - + #### finishing - + .. _geos-chem_tests: ******************************** @@ -81,16 +81,16 @@ GEOS-Chem-specific test programs The following test programs can be used to debug source code for reading YAML-format configuration files into the `GEOS-Chem model -`_. +`_. -.. _test_geoschem_config.x: +.. _test_input_options.x: -test_geoschem_config.x +test_input_options.x ====================== This test program attempts to read the `GEOS-Chem master configuration file -`_ +`_ and echo back output. The master configuration file will replace :file:`input.geos` in GEOS-Chem 14.0.0 and later. @@ -99,33 +99,48 @@ To run this test, type at the command line: .. code-block:: console $ cd qfyaml/bin # Skip if you are already in qfyaml/bin - $ ./test_geoschem_config.x + $ ./test_input_options.x And you should see output such as: .. code-block :: console - ### Reading geoschem_config.yml - simulation%start | 20190701 0 - simulation%end | 20190801 0 - simulation%met_field | MERRA2 - simulation%name | UNKNOWN - simulation%species_database_file | species_database.yml - simulation%debug_printout | F - simulation%use_gcclassic_timers | F - --- - grid%resolution | 0.5x0.625 - grid%longitude_range | -140.00 -40.00 - grid%center_lon_at_180 | T - grid%latitude_range | -10.00 70.00 - grid%half_size_polar_boxes | T - grid%number_of_levels | 72 - grid%nested_grid_simulation | T - grid%buffer_zone_NSEW | 3 3 3 3 - --- - timesteps%transport_and_convection | 300 - timesteps%chemistry_and_emissions | 600 - ... etc ... + ### Reading input_options.yml + simulation%start + ==> 20190701 0 + simulation%end + ==> 20190801 0 + simulation%data_dir + ==> /n/holyscratch01/external_repos/GEOS-CHEM/gcgrid/data/ExtData + simulation%met_field + ==> MERRA2 + simulation%name + ==> fullchem + simulation%species_database_file + ==> species_database.yml + simulation%debug_printout + ==> F + simulation%use_gcclassic_timers + ==> F + + grid%resolution + ==> 0.5x0.625 + grid%longitude_range + ==> -140.000000 -40.0000000 + grid%center_lon_at_180 + ==> T + grid%latitude_range + ==> -10.0000000 70.0000000 + grid%half_size_polar_boxes + ==> T + grid%number_of_levels + ==> 72 + grid%nested_grid_simulation + ==> T + grid%buffer_zone_NSEW + ==> 3 3 3 3 + + . . . etc . . . .. _test_species_database.x: @@ -186,9 +201,5 @@ You should see output similar to this: ACTA%WD_RainoutEff | -999.00 -999.00 -999.00 ACTA%WD_RainoutEff_Luo | -999.00 -999.00 -999.00 ACTA%WD_RetFactor | 0.02 - - ... etc for other species ... - - - + . . . etc . . .