Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Text/us-499 Documentation to address Sigma Level Output #1105

Open
wants to merge 7 commits into
base: develop
Choose a base branch
from
Open

Text/us-499 Documentation to address Sigma Level Output #1105

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
460db16
Added section for enabling output
jdkublnick Dec 13, 2024
6bc932a
Added index file
jdkublnick Dec 13, 2024
fdb86b5
RTD format changes
jdkublnick Dec 13, 2024
51d1556
added reference to text file chapter
jdkublnick Dec 13, 2024
7c7daa7
Format fix
jdkublnick Dec 13, 2024
83aa4c8
Merge branch 'develop' into text/us-499
WenMeng-NOAA Dec 31, 2024
03e2967
Merge branch 'develop' into text/us-499
WenMeng-NOAA Jan 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions doc/UserGuide/CustomizingTheUPP/EnablingOutput.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
.. _enabling-Output:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
.. _enabling-Output:
.. _enabling-output:


********************************
User-Defined Sigma Level Output
********************************

This documentation describes the steps to generate model output at user-defined sigma levels using the Unified Post Processor (UPP). The instructions address the configuration of XML files and the resolution of potential issues encountered during this process.

Generating Sigma Level Output
-----------------------------

UPP can output temperature, U, and V components on sigma surfaces. These correspond to indices 206, 208, and 209 in the :term:`GRIB2`` table. Follow these steps to configure your workflow for this output:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
UPP can output temperature, U, and V components on sigma surfaces. These correspond to indices 206, 208, and 209 in the :term:`GRIB2`` table. Follow these steps to configure your workflow for this output:
UPP can output temperature, U, and V components on sigma surfaces. These correspond to indices 206, 208, and 209 in the :term:`GRIB2` table. Follow these steps to configure your workflow for this output:

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you actually link to the table? That's more important in terms of knowing what variables are possible in UPP.


**Configuring XML Files**

1. **Locate XML Configuration Files**:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's best to replace the numbers with #. because then it autofills the numbers, and you don't have to worry about renumbering if steps are added or removed over time.

- Use the XML files in the `UPP/parm` directory as references. Specifically, the `post_avblflds.xml` file contains all the fields that UPP can output.

2. **Modify Control XML**:
- Copy the entries for temperature, U, and V (indices 206, 208, and 209) from `post_avblflds.xml` to the control XML file used in your workflow.

3. **Validation**:
- Validate the control XML file against the `EMC_POST_CTRL_Schema.xsd` schema.

4. **Flat Text File Generation**:
- Convert the control XML to a flat text file, ensuring that it is validated as part of the process. More information can be found in the :ref:`create_txt_file` documentation.
Comment on lines +16 to +26
Copy link
Collaborator

@gspetro-NOAA gspetro-NOAA Jan 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. **Locate XML Configuration Files**:
- Use the XML files in the `UPP/parm` directory as references. Specifically, the `post_avblflds.xml` file contains all the fields that UPP can output.
2. **Modify Control XML**:
- Copy the entries for temperature, U, and V (indices 206, 208, and 209) from `post_avblflds.xml` to the control XML file used in your workflow.
3. **Validation**:
- Validate the control XML file against the `EMC_POST_CTRL_Schema.xsd` schema.
4. **Flat Text File Generation**:
- Convert the control XML to a flat text file, ensuring that it is validated as part of the process. More information can be found in the :ref:`create_txt_file` documentation.
An XML :ref:`control file <control-file>` determines what fields and levels UPP will output.
#. **Locate the XML Control File**: Control files for various operational models are located in the ``UPP/parm`` directory. The ``post_avblflds.xml`` file contains all fields that the UPP can output.
#. **Modify the Control XML**: Copy the entries for temperature, U, and V (indices 206, 208, and 209) from ``post_avblflds.xml`` to the control XML file used in your workflow. Be sure to include a ``<level></level>`` tag with the appropriate levels in the XML control file to define which sigma levels to output.
#. **Validate the Control File**: Validate the control XML file against the `EMC_POST_CTRL_Schema.xsd` schema according to :ref:`these instructions <create_txt_file>`.
#. **Flat Text File Generation**: Convert the control XML to a flat text file based on the information in the :ref:`create_txt_file` documentation.


**Sigma Levels**

By default, only certain sigma levels are outputted. These levels are in the source file `SET_LVLSXML.f` and can be found between lines 342 and 363. Users must:
Copy link
Collaborator

@gspetro-NOAA gspetro-NOAA Jan 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
By default, only certain sigma levels are outputted. These levels are in the source file `SET_LVLSXML.f` and can be found between lines 342 and 363. Users must:
By default, only certain sigma levels are outputted. These levels are defined in `SET_LVLSXML.f <https://github.com/NOAA-EMC/UPP/blob/develop/sorc/ncep_post.fd/SET_LVLSXML.f>`_ using the ``ASIGO1`` array. Users must review these levels in the ``SET_LVLSXML.f`` file to confirm compatibility with their requirements.

Best not to indicate specific lines of code because they can change.


- **Verify Default Levels**:
Review these levels in the `SET_LVLSXML.f` source file to confirm their compatibility with your requirements.

- **Add <level></level> Tags**:
Include a `<level></level>` tag in the XML configuration to explicitly define the sigma levels to be output.
Comment on lines +32 to +36
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Verify Default Levels**:
Review these levels in the `SET_LVLSXML.f` source file to confirm their compatibility with your requirements.
- **Add <level></level> Tags**:
Include a `<level></level>` tag in the XML configuration to explicitly define the sigma levels to be output.

The level tags pertain to the control file, not the SET_LVLSXML.f, so I moved that info up and combined the remaining bullet point into the sentence above.


Required Source Code Modifications
----------------------------------

If the default sigma levels are insufficient, you must:

1. **Modify `SET_LVLSXML.f`**:
- Change the entries for `ASIGO1` to include your desired sigma levels.

2. **Recompile UPP**:
- Recompile the UPP source code after making the changes.

3. **Update XML Tags**:
- Ensure that the XML tags explicitly reference the modified sigma levels.
Comment on lines +41 to +50
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If the default sigma levels are insufficient, you must:
1. **Modify `SET_LVLSXML.f`**:
- Change the entries for `ASIGO1` to include your desired sigma levels.
2. **Recompile UPP**:
- Recompile the UPP source code after making the changes.
3. **Update XML Tags**:
- Ensure that the XML tags explicitly reference the modified sigma levels.
If the default sigma levels are insufficient, users must:
#. **Modify `SET_LVLSXML.f`**: Change the entries for ``ASIGO1`` to include your desired sigma levels.
#. **Recompile UPP**: Recompile the UPP source code after making the changes.
#. **Update XML Tags**: Ensure that the XML control file explicitly references the modified sigma levels in the <level></level> tag.


Important Notes
---------------

- Adding `<level></level>` tags manually allows UPP to compile and run successfully, but it will not produce any output unless the levels are also modified in `SET_LVLSXML.f` and properly referenced.

- Fortran I/O errors may occur if the sigma levels in the control file are not synchronized with the source code configuration.

- Comprehensive documentation on control files can be found in the :ref:`control-file` documentation, which provides details about XML file formatting and flat file generation.

By following these steps, users can successfully configure UPP to generate model output on user-defined sigma levels while avoiding common pitfalls.
Comment on lines +52 to +61
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Important Notes
---------------
- Adding `<level></level>` tags manually allows UPP to compile and run successfully, but it will not produce any output unless the levels are also modified in `SET_LVLSXML.f` and properly referenced.
- Fortran I/O errors may occur if the sigma levels in the control file are not synchronized with the source code configuration.
- Comprehensive documentation on control files can be found in the :ref:`control-file` documentation, which provides details about XML file formatting and flat file generation.
By following these steps, users can successfully configure UPP to generate model output on user-defined sigma levels while avoiding common pitfalls.
.. hint::
- Adding `<level></level>` tags manually allows UPP to compile and run successfully, but it will not produce any output unless the levels are also modified in ``SET_LVLSXML.f`` and properly referenced.
- Fortran I/O errors may occur if the sigma levels in the control file are not synchronized with the source code configuration.
- Comprehensive documentation on control files can be found in the :ref:`control-file` documentation, which provides details about XML file formatting and flat file generation.

1 change: 1 addition & 0 deletions doc/UserGuide/CustomizingTheUPP/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,5 @@ Customizing the UPP

AddNewVariable
Regridding
EnablingOutput