Difference between revisions of "UKCA & UMUI Tutorial 3"
(70 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
[[UKCA & UMUI Tutorials | Back to UKCA & UMUI Tutorials]] |
[[UKCA & UMUI Tutorials | Back to UKCA & UMUI Tutorials]] |
||
+ | ==What is STASH?== |
||
− | ==Running an existing UKCA job== |
||
+ | ''STASH'' is the Unified Model's storage handling and diagnostic system. It is designed to cope with the many different configurations that the UM can be used in, but still provide output in a consistent and standard way. A full technical description of STASH can be found in '''Unified Model Documentation Paper C4''' which can be downloaded from the [http://collab.metoffice.gov.uk/twiki/pub/Support/Umdp Met Office Collaboration Twiki (password required)]. |
||
− | You will need to change a number of options within the UMUI to allow you to run this job successfully, such as your username, HECToR TIC code (if needed) etc. If you are using the MONSooN job you may also need to change the project group in |
||
+ | ===Prognostic and Diagnostic Fields=== |
||
− | Model Selection |
||
− | -> Post Processing |
||
− | -> Main Switch + General Questions |
||
+ | The UM considers variables (or ''fields'') to be of two different types, ''prognostic'' or ''diagnostic''. '''Prognostic''' fields are ones which the model must have values for, prior to each timestep, as the equations of motion the model solves require these fields (these are fields such as specific humidity or potential temperature) so they must exist in the model start dump. '''Diagnostic''' fields are all other fields that are derived from prognostic ones, and as such the model does not need to have prior values for these. Ancillary files (such as emissions, SSTs etc) contain prognostic fields. |
||
− | if you want to send output data to the /nerc data disk (this is advisable). |
||
+ | From a user's perspective, STASH is used to output fields during the run, and from this point of view it does not matter if these are prognostic or diagnostic fields. However, you will need to consider these differences when you [[UKCA & UMUI Tutorial 4 | add new chemical tracers]]. |
||
− | Once you have made these changes you can submit your job. First click '''Save''', then '''Process''', and once this has completed, click '''Submit'''. This will then extract the code from the FCM repositories and submit them to the supercomputer. If you are running on MONSooN you will need to enter your passcode at this stage. |
||
+ | ===STASH Sections and Items=== |
||
− | ==Checking the progress of a running job== |
||
+ | Each field that is considered by STASH has a unique address which is given by a '''section''' and an '''item''' number. Prognostic fields are mostly held in section 0 (with the exception of tracers) and diagnostics are organised by areas of the code, e.g. short-wave radiation diagnostics are held in section 1, long-wave radiation diagnostics are held in section 2 etc. Some sections will always be on, and some sections will only be on if a certain process is selected, e.g. the interactive land-surface scheme. Each section can hold up to 512 items, where each item is a separate prognostic or diagnostic field, and can be either 2D or 3D. |
||
− | Log-in to the supercomputer, and check that your job is running. For HECToR do |
||
+ | Each field has its own entry in a '''STASHmaster file'''. There is a master list of fields which is held in the ''STASHmaster_A'' file, which is located at |
||
− | qstat -u $USER |
||
+ | /work/n02/n02/hum/vn8.2/ctldata/STASHmaster/STASHmaster_A |
||
− | and for MONSooN do |
||
+ | on HECToR, and at |
||
− | llq -u $USER |
||
+ | /projects/um1/vn8.2/ctldata/STASHmaster/STASHmaster_A |
||
− | This should give a list of your running jobs. For example, on MONSooN you should get something like |
||
+ | on MONSooN. This is also a handy list of all the fields that can be outputted from the model, which is easier to search than by going through the UMUI panels. UKCA uses section 34 for chemical tracers and chemical diagnostics, and section 38 for aerosol diagnostics. |
||
− | $ llq -u $USER |
||
− | Id Owner Submitted ST PRI Class Running On |
||
− | ------------------------ ---------- ----------- -- --- ------------ ----------- |
||
− | mon001.64641.0 nlabra 6/5 12:36 R 50 parallel c139 |
||
− | |||
− | 1 job step(s) in query, 0 waiting, 0 pending, 1 running, 0 held, 0 preempted |
||
+ | ===User-STASHmaster files=== |
||
+ | As well as the prognostic and diagnostic fields held in the ''STASHmaster_A'' file, it is possible to make your own '''user STASHmaster file''' which can either add new prognostics/diagnostics, or over-write existing prognostics/diagnostics. These are added to the UMUI in the '''Model Selection → Atmosphere → STASH → User-STASHmaster files. Diags, Progs & Ancils''' panel. These new fields may then need to be initialised in the '''Model Selection → Atmosphere → STASH → Initialisation of User Prognostics''' panel. More information on user STASHmaster files will be given in the [[UKCA & UMUI Tutorial 4 | adding new chemical tracers]], [[UKCA & UMUI Tutorial 5 | adding new emissions]], and [[UKCA & UMUI Tutorial 9 | adding new UKCA diagnostics]] tutorials. |
||
− | You can also check how far a job has gone while it is running. To do this you will need to <tt>cd</tt> into the job directory (this will be on your <tt>/work</tt> space on HECToR or your <tt>/projects</tt> space on MONSooN). When you do this, you will see something like this |
||
+ | ==Output Files== |
||
− | $ ls |
||
− | baserepos/ pe_output/ umrecon/ xhklg.apstmp1 xhklg.astart xhklg.out xhklg.stash xhklg.xhist xhklga.pc19920901 |
||
− | bin/ umatmos/ umscripts/ xhklg.apsum1 xhklg.list xhklg.requests xhklg.umui.nl xhklga.da19920921_00 xhklga.pe1992sep |
||
+ | Before we cover outputting diagnostics from the UMUI STASH panel, we will first cover the different output fields files that are produced by the UM. Output from STASH is sent to different output streams, and there are two types of files used by these streams: '''standard PP files''' and '''climate mean files'''. |
||
− | Now <tt>cd</tt> into the <tt>pe_output/</tt> directory and do |
||
+ | The basic building block of UM output files is a 2D latitude-longitude slice. Surface variables are made up of a single slice, whereas 3D variables are made up of many slices. If you output a 3D variable, such as ozone, this is in fact made up of 85 (as there are 85 model levels) slices. |
||
− | $ tail -f <span style="color:blue">jobid</span>.fort6.pe0 | grep Atm_Step |
||
− | Atm_Step: Timestep 1744 Model time: 1992-09-25 05:20:00 |
||
− | Atm_Step: Timestep 1745 Model time: 1992-09-25 05:40:00 |
||
− | Atm_Step: Timestep 1746 Model time: 1992-09-25 06:00:00 |
||
− | Atm_Step: Timestep 1747 Model time: 1992-09-25 06:20:00 |
||
− | Atm_Step: Timestep 1748 Model time: 1992-09-25 06:40:00 |
||
− | Atm_Step: Timestep 1749 Model time: 1992-09-25 07:00:00 |
||
+ | ===Standard PP files=== |
||
− | (changing <span style="color:blue">jobid</span> as appropriate for your job). |
||
+ | [[Image:UMUI_PostProc_PPfiles_new.png|thumb|300px|right|Figure 1: The initialization and processing of PP files UMUI panel.]] |
||
− | ==Viewing and extracting output== |
||
+ | These files are controlled in '''Model Selection → Post Processing → Initialization and processing of mean and standard PP files'''. As well as choosing the packing profile (see the '''Help''' button for more information) this panel also describes how these different files are treated. As can be seen in Figure 1, there are 11 PP files defined, '''PP0''' to '''PP10''', which correspond to designators '''pa''' to '''pk''' (with units 60-69, and 151 - these unit numbers may be important in warning and error messages). |
||
+ | The table in this panel can be used to set various properties of these files, such as the time period the file covers, and whether or not the file is '''[[UKCA & UMUI Tutorials: Things to know before you start#Archiving|archived]]''' (i.e. either to the <tt>archive/</tt> sub-directory or RDF facility on HECToR, or two the <tt>/nerc</tt> disk or MOOSE on MONSooN). Being able to change the time period is very useful - while for many simulations monthly mean files are preferred (see the discussion about ''climate meaning'' below), often you may wish to output higher frequency data, e.g. 6-hourly. These PP files are usually limited to a finite size and so outputting a month of 6-hourly data may cause the model to crash at run-time. The solution to this is to change how frequently the files are generated, e.g. you could output daily files instead of monthly ones. |
||
− | [[Image:UKCA_Tutorial_Xconv01.png|thumb|300px|right|Figure 1: Xconv viewing the '''pm''' file.]] |
||
− | [[Image:UKCA_Tutorial_Xconv02.png|thumb|300px|right|Figure 1: Xconv viewing surface O3 concentration.]] |
||
− | To take a look at the output, you will need to change into the directory where the data has been archived. On HECToR this should be in the <tt>archive/</tt> sub-directory, on MONSooN it will be on <tt>/nerc/<span style="color:blue">project</span>/$USER/<span style="color:blue">jobid</span></tt>. Once in this directory <tt>ls</tt> to see the file listing |
||
+ | The last column in this table controls the archiving of these files. If you have set up your job to archive to a different directory (e.g. to the <tt>archive/</tt> sub-directory on HECToR, or are sending data to the <tt>/nerc</tt> disk on MONSooN or to the RDF on HECToR, then the files associated with each stream will only be moved if this column is set to '''Y'''. If it is '''N''' then the file will '''not be archived but will be deleted''' if you have requested the '''Delete superseded PP files''' in the '''Model Selection → Post Processing → Main Switch + General Questions''' panel. |
||
− | $ ls |
||
− | xhklga.pm1992sep.pp |
||
+ | If there is no data being sent to a stream (which is controlled in the STASH panel) then this will automatically be set to '''N'''. If you then send data to a stream you will need to manually set it to '''Y''' after you have made the diagnostic request. |
||
− | As you can see, there is only one file present, the '''"pm"''' file. This file is a montly-mean file that has come from the climate-meaning stream (climate-meaning will be covered in detail in the [[UKCA & UMUI Tutorial 2 | What is STASH?]] tutorial). |
||
+ | ===Climate Mean files=== |
||
− | $ ls |
||
− | xhklga.pm1992sep.pp |
||
+ | [[Image:UMUI_DumpMean_Main.png|thumb|300px|right|Figure 2: The dumping and meaning main UMUI panel.]] |
||
− | To quickly view output you can use [http://badc.nerc.ac.uk/help/software/xconv/ Xconv], which provides a simple data viewer. It can also be used to convert the UM format output files to netCDF. You can open this file by |
||
+ | [[Image:UMUI_DumpMean_NEXT.png|thumb|300px|right|Figure 3: The dumping and meaning follow-on UMUI panel.]] |
||
+ | Climate meaning is controlled in the same panel where the restart dump frequency is set: '''Model Selection → Atmosphere → Control → Post processing, Dumping & Meaning'''. The main panel is shown in Figure 2. In this example, as is standard for all climate jobs, restart dumps are created every 10 days, and this example as these dumps archived every 9 files, starting with the 9th file after the job is started, i.e. every 3 months (to save space you may choose to change this to 1 year or every 36 files). All other dumps are deleted after they are no longer needed. This means that if the model crashes and needs to be restarted, you will at most have lost 10 days of run. '''Note:''' while the model will bit compare on restarting from an old dump, this will not be the case if the dump frequency is changed. |
||
+ | This panel has selected '''regular frequency dumps with possible meaning sequence''' so that '''climate meaning''' is possible. To do this, you must specify a date for the meaning sequence. '''Note:''' you should be careful about this choice of date, especially if you are changing the start-date of the run. It is advised that this meaning sequence date is set to be on or before your start date. If it is not you will not generate some of the climate mean files. |
||
− | $ xconv -i xhklga.pm1992sep.pp |
||
+ | The follow-on window from this panel (shown in Figure 3) gives more details about how climate meaning works. These files work on multiples of the dump period, so the first climate mean file created will be a multiple of 3 dump periods (i.e. 3x10 days, or 30 days. Since we are running a 360-day calendar, this is 1 model month) which is the '''pm''' monthly-mean file, which we considered when [[UKCA & UMUI Tutorial 2 | running existing UKCA Job]]. The second climate-mean file is a multiple of 3 of the monthly-mean files (i.e. 3x30 days, or 90 days, which is a season), the '''ps''' seasonal-mean file (the meaning date is important here to get the correct 3 months for each season). The third climate-mean file is a multiple of 4 of the seasonal-mean files (i.e. 3x90 days, or 360 days, a year), the '''py''' annual-mean file. The final file created is a multiple of 10 of the annual-mean files - a decadal-mean '''px''' file. |
||
− | which will show the Xconv window as can been seen in Figure 1. If you scroll down the list of fields you will find ones that begin |
||
+ | The fields outputted to each of these pm, ps, pa, or px file is the same, and in the same order. All that is different is the meaning done to each field. '''Note:''' if you change the dump frequency you will change the frequency of creation of these climate-mean files. In this instance you would need to change the multiple for the first file to get a monthly-mean file correctly. |
||
− | Stash code = 34... |
||
+ | ==The UMUI STASH Panel== |
||
− | e.g. <tt>Stash code = 34001</tt> etc. These are the UKCA chemical tracer and diagnostic fields (although they are not labeled as such by default). A full listing of these can be found in the [[listing of UKCA fields at UM8.2]]. More information will be given on STASH in the [[UKCA & UMUI Tutorial 2 | What is STASH?]] tutorial. |
||
+ | [[Image:UMUI_STASHPanel_new.png|thumb|300px|right|Figure 4: The UMUI STASH panel.]] |
||
− | You can use Xconv to view certain fields. For example, you could view the surface ozone concentration double-clicking on the ''Stash code = 34001'' field and clicking the '''Plot data''' button (see Figure 2). While this is good to quickly check data, the plotting functions are rather limited as it is not possible to change e.g. the colour-bar, the scale, add a map projection etc. It is advisable to either export fields as netCDF from within Xconv, or to use another program, such as IDL (using the [http://cms.ncas.ac.uk/documents/IDL/idl_guide.html Met Office library]) or Python (using either [http://cfpython.bitbucket.org/ cf-python] or [http://scitools.org.uk/iris/ Iris]) which is able to read the UM PP/FieldsFile format directly. |
||
+ | This panel can be found at '''Model Selection → Atmosphere → STASH → STASH. Specification of Diagnostic requirements''' and is shown in Figure 4. When you first open this panel you may get a window telling you that system diagnostics have been over-written by user diagnostics - just click '''continue''' here. We will cover user diagnostics in the [[UKCA & UMUI Tutorial 9 | adding new UKCA diagnostics]] tutorial. |
||
+ | This panel is organised as a table, listing the diagnostics that have been selected (currently - more can be added) and what the '''time''', '''domain''', and '''usage''' profile for each diagnostic is. In the table as well as giving the name of each diagnostic, the STASH section and item number is also given, with the table sorted by section, item. |
||
− | To export fields as netCDF select them using the mouse (they should then highlight blue), enter a name for the netCDF file in the '''Output file name''' box (making sure that the ''Output format'' is ''Netcdf'') |
||
− | and click the '''Convert''' button. The window on the bottom right will show the progress of the conversion. For single fields this is usually quite quick, but it is possible to use Xconv to open multiple files containing a series of times. In this case Xconv will combine all the individual times into a single field, and outputting this can take some time. |
||
+ | '''Note:''' The UMUI STASH panel only reads the user STASHmaster files once, when it is initially started up. If you have opened this panel and then add in a new user STASHmaster file (which may over-write the name of an existing prognostic or diagnostic) then the changes it makes may not be shown in the STASH panel. For these changes to be seen you should '''save''' your job, '''close''' it, and then re-open it. This will then force the STASH panel to read (and reflect the changes in) the new user STASHmaster file. |
||
− | One issue you may have is that Xconv uses a quantity called the ''field code'' to determine the variable name of each field (the netCDF name attribute). For UKCA tracer fields at UM8.2 this code is all the same, so all variables will be called ''field1861''. It is possible to change the short field name in Xconv, prior to outputting a netCDF file. Select the variable you wish to output and select the '''Names''' button on the top-right of the Xconv window. Delete the contents of the '''short field name''' box and replace it with what you would like, e.g. for ozone (Stash code 34001) you may wish to use the CF standard name ''mass_fraction_of_ozone_in_air'' (as the units of UKCA tracers are kg(species)/kg(air)). The click '''apply''' and output the field as normal. When running <tt>ncdump</tt> on the resultant netCDF file you should see something like |
||
+ | [[Image:UMUI_STASH_TDMPMN.png|thumb|left|Figure 5: The TDMPMN Time Profile.]] |
||
− | float mass_fraction_of_ozone_in_air(t, hybrid_ht, latitude, longitude) ; |
||
+ | ===Time Profiles=== |
||
− | mass_fraction_of_ozone_in_air:source = "Unified Model Output (Vn 8.2):" ; |
||
− | mass_fraction_of_ozone_in_air:name = "mass_fraction_of_ozone_in_air" ; |
||
− | mass_fraction_of_ozone_in_air:title = "Stash code = 34001" ; |
||
− | mass_fraction_of_ozone_in_air:date = "01/09/91" ; |
||
− | mass_fraction_of_ozone_in_air:time = "00:00" ; |
||
− | mass_fraction_of_ozone_in_air:long_name = "Stash code = 34001" ; |
||
− | mass_fraction_of_ozone_in_air:units = " " ; |
||
− | mass_fraction_of_ozone_in_air:missing_value = 2.e+20f ; |
||
− | mass_fraction_of_ozone_in_air:_FillValue = 2.e+20f ; |
||
− | mass_fraction_of_ozone_in_air:valid_min = 8.680486e-09f ; |
||
− | mass_fraction_of_ozone_in_air:valid_max = 1.84475e-05f ; |
||
+ | There is a rather extensive list of time profiles already existing in this job, and it is possible to add more by making a new one in a blank slot. These time profiles define how the data is time-processed prior to being output. Some profiles, such as '''T6H''' have no meaning, and just output the field as it is every 6 hours, other profiles, such as '''TDAYM''' will result in a daily mean of a field. You can view how these profiles are defined by selecting a profile (it will highlight yellow) and going to '''Profiles → Edit Profile → Edit time''' in the STASH panel menu. |
||
+ | An example of the '''TDMPMN''' time profile is shown in Figure 5. This is the climate-meaning time profile, and samples fields every dump period, and should only be used with the '''UPMEAN''' usage profile (see below). |
||
− | Once you have your data as netCDF it is then possible to use any standard visualisation or processing package to view and manipulate the data. |
||
+ | |||
+ | ===Domain Profiles=== |
||
+ | |||
+ | These profiles cover the horizontal and vertical domain covered by fields as they are output. Depending on the diagnostic which is outputted, some of these are on pressure levels, model theta levels, model rho levels, or on a single (e.g. a surface of top of the atmosphere) level etc.. The '''DALLTH''' outputs variables on all model theta levels, and it is this domain which UKCA fields (except for surface fields) are usually outputted on. If you edit this profile you can also see that it is possible to output zonal means of fields, or to limit the output to a particular area. This last option can be especially useful if a large amount (e.g. hourly) data is required, but only for a specific part of the world, over the length of a long run. |
||
+ | |||
+ | ===Usage Profiles=== |
||
+ | |||
+ | These profiles determine which output stream to use. The '''UPMEAN''' profile will send data to the climate-meaning stream discussed above, whereas the '''UPA''' profile will send data to the '''pa''' file etc. |
||
+ | |||
+ | '''Note:''' If you are sending data to the climate-meaning stream '''UPMEAN''' you '''must''' use the '''TDMPMN''' time profile (or a variation thereof), otherwise this output will become corrupted or incorrectly meaned. |
||
+ | |||
+ | ===The Menu Bar=== |
||
+ | |||
+ | The STASH panel is unusual for the UMUI in that it has a separate menu bar, rather than using a row of buttons along the bottom of the panel. |
||
+ | |||
+ | ====STASH==== |
||
+ | |||
+ | This menu contains the usual '''Close''' (i.e. save and close panel) and '''Abandon''' (i.e. close without saving) options. |
||
+ | |||
+ | ====Profiles==== |
||
+ | |||
+ | As discussed above, you can use the '''Edit Profile''' options to view (and change) new or existing profiles. You can also '''Copy''' or '''Delete''' profiles from this menu. |
||
+ | |||
+ | ====Diagnostics==== |
||
+ | |||
+ | This menu contains the items that you will probably use the most. It is here that you can add new diagnostics and change the order of the diagnostics in the table. |
||
+ | |||
+ | =====Load New Diagnostics (Control-l)===== |
||
+ | |||
+ | Clicking on this option will bring up a new window, organised by section, listing all the items that can be outputted. This table will list if the field is available in the current model configuration, and there may also be '''Help''' available for some diagnostics (if there is, double click where it says ''"Help"''). |
||
+ | |||
+ | =====Remove Diagnostics (Control-r)===== |
||
+ | |||
+ | You can use this option to remove a diagnostic from the table, although it is easier to type '''Control-r'''. |
||
+ | |||
+ | =====Output Table to File===== |
||
+ | |||
+ | This outputs the current STASH table, in its current order, to a file (called <span style="color:blue">jobid</span>.A.diags) in your <tt>$HOME/umui_jobs</tt> directory on PUMA. If you wish to compare the STASH between two jobs it is best to output the STASH table from each and use xxdiff on PUMA, as comparing the two jobs using the UMUI diff is rather confusing when it comes to STASH. |
||
+ | |||
+ | =====Set Package Switches (Control-t)===== |
||
+ | |||
+ | You will notice that for some diagnostics in the 8th column of the STASH table (labelled ''Pckg'') there is a letter, e.g. J or +G etc. This corresponds to a package, which is set in this table. This is a useful way of organising diagnostics so that they can be easily turned on or off. For instance, if package J is off then the letter just appears as '''J''' (and the ''I+P+A'' column would say ''N''), however, this package can be turned on in the package switches table (set to '''Y'''), and if it is on this letter now appears as '''+J'''. You can only turn diagnostics which are organised through a package on by turning that package on (although you can remove the diagnostic from the package, or add it again but not in package). |
||
+ | |||
+ | =====Clear Table===== |
||
+ | |||
+ | '''Warning:''' clicking this option will remove all the diagnostics in your STASH table. If you do this in error go to '''STASH → Abandon''' to close the STASH window without saving. |
||
+ | |||
+ | =====Verify Diagnostics (Control-v)===== |
||
+ | |||
+ | This is a very useful option. When you add new diagnostics you may inadvertently have made some errors. For some diagnostics you may not be sure what levels (i.e. ''domain profile'') it should be outputted on. For example, UKCA tracer fields should be outputted on model theta levels (''DALLTH''). If this field is requested on model rho levels (''DALLRH'') then the '''Verify Diagnostics''' window would give |
||
+ | |||
+ | Diag: "O3 MASS MIXING RATIO AFTER TIMESTEP " (34,1) (TDMPMN,DALLRH,UPMEAN) |
||
+ | DOMAIN PROF ERROR: Use profile on model theta-levels. |
||
+ | |||
+ | =====Sort Diagnostics===== |
||
+ | |||
+ | Use this option to order the diagnostics by section, item. When adding new diagnostics they are usually added to the top of the list, rather than in order. |
||
+ | |||
+ | =====Change Sort Order===== |
||
+ | |||
+ | This will bring up a box where you can choose which columns are considered (and in which order) when it comes to sorting the diagnostics. The default ordering is equivalent to '''1 2''' i.e. sort by column 1 (section) then by column 2 (item). |
||
+ | |||
+ | ====Help==== |
||
+ | |||
+ | The '''Help''' menu has a more detailed description of the features and options in the STASH panel. |
||
+ | |||
+ | ==Task 3.1: add new output== |
||
+ | |||
+ | <span style="color:green">'''TASK 3.1:''' Output the instantaneous UKCA ozone field to the '''ph'''/'''UPH''' stream every 6 hours. </span> |
||
+ | |||
+ | {| class="collapsible collapsed wikitable" |
||
+ | |- |
||
+ | ! Hint |
||
+ | |- |
||
+ | | You will need to make the changes to the STASH table first, and remember to use '''Verify Diagnostics''' and correct any warnings generated for the '''ph/UPH''' stream (67). |
||
+ | |} |
||
+ | |||
+ | '''Remember:''' If you are using MONSooN you will need to delete/move any existing output files in your '''[[UKCA & UMUI Tutorials: Things to know before you start#Archiving|archive]]''' directory. |
||
+ | |||
+ | [[Solution to UKCA & UMUI Tutorial 3 Task 3.1 | Solution]] |
||
+ | |||
+ | ---- |
||
+ | ''Written by [[User:Nla27 | Luke Abraham]] 2013'' |
Latest revision as of 10:41, 5 July 2013
What is STASH?
STASH is the Unified Model's storage handling and diagnostic system. It is designed to cope with the many different configurations that the UM can be used in, but still provide output in a consistent and standard way. A full technical description of STASH can be found in Unified Model Documentation Paper C4 which can be downloaded from the Met Office Collaboration Twiki (password required).
Prognostic and Diagnostic Fields
The UM considers variables (or fields) to be of two different types, prognostic or diagnostic. Prognostic fields are ones which the model must have values for, prior to each timestep, as the equations of motion the model solves require these fields (these are fields such as specific humidity or potential temperature) so they must exist in the model start dump. Diagnostic fields are all other fields that are derived from prognostic ones, and as such the model does not need to have prior values for these. Ancillary files (such as emissions, SSTs etc) contain prognostic fields.
From a user's perspective, STASH is used to output fields during the run, and from this point of view it does not matter if these are prognostic or diagnostic fields. However, you will need to consider these differences when you add new chemical tracers.
STASH Sections and Items
Each field that is considered by STASH has a unique address which is given by a section and an item number. Prognostic fields are mostly held in section 0 (with the exception of tracers) and diagnostics are organised by areas of the code, e.g. short-wave radiation diagnostics are held in section 1, long-wave radiation diagnostics are held in section 2 etc. Some sections will always be on, and some sections will only be on if a certain process is selected, e.g. the interactive land-surface scheme. Each section can hold up to 512 items, where each item is a separate prognostic or diagnostic field, and can be either 2D or 3D.
Each field has its own entry in a STASHmaster file. There is a master list of fields which is held in the STASHmaster_A file, which is located at
/work/n02/n02/hum/vn8.2/ctldata/STASHmaster/STASHmaster_A
on HECToR, and at
/projects/um1/vn8.2/ctldata/STASHmaster/STASHmaster_A
on MONSooN. This is also a handy list of all the fields that can be outputted from the model, which is easier to search than by going through the UMUI panels. UKCA uses section 34 for chemical tracers and chemical diagnostics, and section 38 for aerosol diagnostics.
User-STASHmaster files
As well as the prognostic and diagnostic fields held in the STASHmaster_A file, it is possible to make your own user STASHmaster file which can either add new prognostics/diagnostics, or over-write existing prognostics/diagnostics. These are added to the UMUI in the Model Selection → Atmosphere → STASH → User-STASHmaster files. Diags, Progs & Ancils panel. These new fields may then need to be initialised in the Model Selection → Atmosphere → STASH → Initialisation of User Prognostics panel. More information on user STASHmaster files will be given in the adding new chemical tracers, adding new emissions, and adding new UKCA diagnostics tutorials.
Output Files
Before we cover outputting diagnostics from the UMUI STASH panel, we will first cover the different output fields files that are produced by the UM. Output from STASH is sent to different output streams, and there are two types of files used by these streams: standard PP files and climate mean files.
The basic building block of UM output files is a 2D latitude-longitude slice. Surface variables are made up of a single slice, whereas 3D variables are made up of many slices. If you output a 3D variable, such as ozone, this is in fact made up of 85 (as there are 85 model levels) slices.
Standard PP files
These files are controlled in Model Selection → Post Processing → Initialization and processing of mean and standard PP files. As well as choosing the packing profile (see the Help button for more information) this panel also describes how these different files are treated. As can be seen in Figure 1, there are 11 PP files defined, PP0 to PP10, which correspond to designators pa to pk (with units 60-69, and 151 - these unit numbers may be important in warning and error messages).
The table in this panel can be used to set various properties of these files, such as the time period the file covers, and whether or not the file is archived (i.e. either to the archive/ sub-directory or RDF facility on HECToR, or two the /nerc disk or MOOSE on MONSooN). Being able to change the time period is very useful - while for many simulations monthly mean files are preferred (see the discussion about climate meaning below), often you may wish to output higher frequency data, e.g. 6-hourly. These PP files are usually limited to a finite size and so outputting a month of 6-hourly data may cause the model to crash at run-time. The solution to this is to change how frequently the files are generated, e.g. you could output daily files instead of monthly ones.
The last column in this table controls the archiving of these files. If you have set up your job to archive to a different directory (e.g. to the archive/ sub-directory on HECToR, or are sending data to the /nerc disk on MONSooN or to the RDF on HECToR, then the files associated with each stream will only be moved if this column is set to Y. If it is N then the file will not be archived but will be deleted if you have requested the Delete superseded PP files in the Model Selection → Post Processing → Main Switch + General Questions panel.
If there is no data being sent to a stream (which is controlled in the STASH panel) then this will automatically be set to N. If you then send data to a stream you will need to manually set it to Y after you have made the diagnostic request.
Climate Mean files
Climate meaning is controlled in the same panel where the restart dump frequency is set: Model Selection → Atmosphere → Control → Post processing, Dumping & Meaning. The main panel is shown in Figure 2. In this example, as is standard for all climate jobs, restart dumps are created every 10 days, and this example as these dumps archived every 9 files, starting with the 9th file after the job is started, i.e. every 3 months (to save space you may choose to change this to 1 year or every 36 files). All other dumps are deleted after they are no longer needed. This means that if the model crashes and needs to be restarted, you will at most have lost 10 days of run. Note: while the model will bit compare on restarting from an old dump, this will not be the case if the dump frequency is changed.
This panel has selected regular frequency dumps with possible meaning sequence so that climate meaning is possible. To do this, you must specify a date for the meaning sequence. Note: you should be careful about this choice of date, especially if you are changing the start-date of the run. It is advised that this meaning sequence date is set to be on or before your start date. If it is not you will not generate some of the climate mean files.
The follow-on window from this panel (shown in Figure 3) gives more details about how climate meaning works. These files work on multiples of the dump period, so the first climate mean file created will be a multiple of 3 dump periods (i.e. 3x10 days, or 30 days. Since we are running a 360-day calendar, this is 1 model month) which is the pm monthly-mean file, which we considered when running existing UKCA Job. The second climate-mean file is a multiple of 3 of the monthly-mean files (i.e. 3x30 days, or 90 days, which is a season), the ps seasonal-mean file (the meaning date is important here to get the correct 3 months for each season). The third climate-mean file is a multiple of 4 of the seasonal-mean files (i.e. 3x90 days, or 360 days, a year), the py annual-mean file. The final file created is a multiple of 10 of the annual-mean files - a decadal-mean px file.
The fields outputted to each of these pm, ps, pa, or px file is the same, and in the same order. All that is different is the meaning done to each field. Note: if you change the dump frequency you will change the frequency of creation of these climate-mean files. In this instance you would need to change the multiple for the first file to get a monthly-mean file correctly.
The UMUI STASH Panel
This panel can be found at Model Selection → Atmosphere → STASH → STASH. Specification of Diagnostic requirements and is shown in Figure 4. When you first open this panel you may get a window telling you that system diagnostics have been over-written by user diagnostics - just click continue here. We will cover user diagnostics in the adding new UKCA diagnostics tutorial.
This panel is organised as a table, listing the diagnostics that have been selected (currently - more can be added) and what the time, domain, and usage profile for each diagnostic is. In the table as well as giving the name of each diagnostic, the STASH section and item number is also given, with the table sorted by section, item.
Note: The UMUI STASH panel only reads the user STASHmaster files once, when it is initially started up. If you have opened this panel and then add in a new user STASHmaster file (which may over-write the name of an existing prognostic or diagnostic) then the changes it makes may not be shown in the STASH panel. For these changes to be seen you should save your job, close it, and then re-open it. This will then force the STASH panel to read (and reflect the changes in) the new user STASHmaster file.
Time Profiles
There is a rather extensive list of time profiles already existing in this job, and it is possible to add more by making a new one in a blank slot. These time profiles define how the data is time-processed prior to being output. Some profiles, such as T6H have no meaning, and just output the field as it is every 6 hours, other profiles, such as TDAYM will result in a daily mean of a field. You can view how these profiles are defined by selecting a profile (it will highlight yellow) and going to Profiles → Edit Profile → Edit time in the STASH panel menu.
An example of the TDMPMN time profile is shown in Figure 5. This is the climate-meaning time profile, and samples fields every dump period, and should only be used with the UPMEAN usage profile (see below).
Domain Profiles
These profiles cover the horizontal and vertical domain covered by fields as they are output. Depending on the diagnostic which is outputted, some of these are on pressure levels, model theta levels, model rho levels, or on a single (e.g. a surface of top of the atmosphere) level etc.. The DALLTH outputs variables on all model theta levels, and it is this domain which UKCA fields (except for surface fields) are usually outputted on. If you edit this profile you can also see that it is possible to output zonal means of fields, or to limit the output to a particular area. This last option can be especially useful if a large amount (e.g. hourly) data is required, but only for a specific part of the world, over the length of a long run.
Usage Profiles
These profiles determine which output stream to use. The UPMEAN profile will send data to the climate-meaning stream discussed above, whereas the UPA profile will send data to the pa file etc.
Note: If you are sending data to the climate-meaning stream UPMEAN you must use the TDMPMN time profile (or a variation thereof), otherwise this output will become corrupted or incorrectly meaned.
The Menu Bar
The STASH panel is unusual for the UMUI in that it has a separate menu bar, rather than using a row of buttons along the bottom of the panel.
STASH
This menu contains the usual Close (i.e. save and close panel) and Abandon (i.e. close without saving) options.
Profiles
As discussed above, you can use the Edit Profile options to view (and change) new or existing profiles. You can also Copy or Delete profiles from this menu.
Diagnostics
This menu contains the items that you will probably use the most. It is here that you can add new diagnostics and change the order of the diagnostics in the table.
Load New Diagnostics (Control-l)
Clicking on this option will bring up a new window, organised by section, listing all the items that can be outputted. This table will list if the field is available in the current model configuration, and there may also be Help available for some diagnostics (if there is, double click where it says "Help").
Remove Diagnostics (Control-r)
You can use this option to remove a diagnostic from the table, although it is easier to type Control-r.
Output Table to File
This outputs the current STASH table, in its current order, to a file (called jobid.A.diags) in your $HOME/umui_jobs directory on PUMA. If you wish to compare the STASH between two jobs it is best to output the STASH table from each and use xxdiff on PUMA, as comparing the two jobs using the UMUI diff is rather confusing when it comes to STASH.
Set Package Switches (Control-t)
You will notice that for some diagnostics in the 8th column of the STASH table (labelled Pckg) there is a letter, e.g. J or +G etc. This corresponds to a package, which is set in this table. This is a useful way of organising diagnostics so that they can be easily turned on or off. For instance, if package J is off then the letter just appears as J (and the I+P+A column would say N), however, this package can be turned on in the package switches table (set to Y), and if it is on this letter now appears as +J. You can only turn diagnostics which are organised through a package on by turning that package on (although you can remove the diagnostic from the package, or add it again but not in package).
Clear Table
Warning: clicking this option will remove all the diagnostics in your STASH table. If you do this in error go to STASH → Abandon to close the STASH window without saving.
Verify Diagnostics (Control-v)
This is a very useful option. When you add new diagnostics you may inadvertently have made some errors. For some diagnostics you may not be sure what levels (i.e. domain profile) it should be outputted on. For example, UKCA tracer fields should be outputted on model theta levels (DALLTH). If this field is requested on model rho levels (DALLRH) then the Verify Diagnostics window would give
Diag: "O3 MASS MIXING RATIO AFTER TIMESTEP " (34,1) (TDMPMN,DALLRH,UPMEAN) DOMAIN PROF ERROR: Use profile on model theta-levels.
Sort Diagnostics
Use this option to order the diagnostics by section, item. When adding new diagnostics they are usually added to the top of the list, rather than in order.
Change Sort Order
This will bring up a box where you can choose which columns are considered (and in which order) when it comes to sorting the diagnostics. The default ordering is equivalent to 1 2 i.e. sort by column 1 (section) then by column 2 (item).
Help
The Help menu has a more detailed description of the features and options in the STASH panel.
Task 3.1: add new output
TASK 3.1: Output the instantaneous UKCA ozone field to the ph/UPH stream every 6 hours.
Hint |
---|
You will need to make the changes to the STASH table first, and remember to use Verify Diagnostics and correct any warnings generated for the ph/UPH stream (67). |
Remember: If you are using MONSooN you will need to delete/move any existing output files in your archive directory.
Written by Luke Abraham 2013