How to add a variable to history.nc

Author: S. Luyssaert
Last revision: 2020/02/28, F. Maignan

Define the variable in ioipslctrl.f90, check whether the correct operators (i.e. ave) and history level i.e. (4) are defined more information on 'histdef' and 'histwrite' can be found on the documentation page of this wiki (​http://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/UserGuide/HistoryOperators )

The first big question is where to put the histdef. It goes in ioipslctrl.f90, but there are five possible places for it. The questions you need to ask yourself are: 1) Is this a stomate or sechiba variable? 2) If it is sechiba, do I want to write it to the high frequency file or just the regular file (only a few variables should, in theory, be written to the HF file)? 3) Is this variable part of the ALMA convention or not (if you're not sure, the answer is probably "no")?

The basic structure of ioipslctrl for defining variables is:

  SUBROUTINE

  ! Writing to the main history file, file id hist_id
         IF ( .NOT. almaoutput ) THEN

              ... a few hundred lines of histdefs

          ELSE

              ... a few hundred lines of histdefs

          ENDIF

    ! Writing to the HF file, file ID hist2_id
        IF ( .NOT. almaoutput ) THEN

              ... a few hundred lines of histdefs

          ELSE

              ... a few hundred lines of histdefs

          ENDIF

! Writing to the STOMATE history file
      CALL stom_define_history

  END SUBROUTINE

  SUBROUTINE stom_define_history

    ... a few hundred lines of histdefs

  END SUBROUTINE

Your histdef should go in one of those five places based on how you answered the three questions above, and will look something like this.

! total fruit biomass
    CALL histdef (hist_id_stom, &
         &               TRIM("Fruit_M             "), &
         &               TRIM("Fruit biomass                                       "), &
         &               TRIM("gC/m^2/pft          "), iim,jjm, hist_hori_id, &
         &               nvm,1,nvm, hist_PFTaxis_id,32, ave(4), dt, hist_dt)

Once you have done that (making sure to use the correct file ID for the section, as well as the correct axes IDs, write frequency (dw, dw2, or hist_dt), and operation array (for the HF file, the operation arrays are followed by 2), you have to write out the variable with a histwrite somewhere in the other routines. Make sure that the histwrite and histdef have the same file ID (you will get an error if you try to write a variable to a file for which it has not been defined), and also make sure that it appears either in the same almaoutput branch that you defined it in (if you define it in the IF statement where almaoutput is TRUE but write it surrounded by an IF statement that checks if almaoutput is FALSE, you will not see it in the history file).

CALL histwrite (hist_id_stomate, 'FRUIT_M', itime, &
         biomass(:,:,ifruit), npts*nvm, horipft_index)

There also seems to be a convention that if you are defining a variable for ALMA output, the first letter is a capital letter, and otherwise it is lowercase. I do not know this for a fact, but it seems to be that way in the code.

If despite your best efforts you get error messages (i.e., define the variable XXX) it may be worth to check the length of your variable name in histdef. There is a maximal length. If that length is exceeded, the string will get truncated and so the field that you think that does exist e.g. VERYLONGVARIABLENAME is in the model known as e.g. VERYLONGVARI.

Note that IOIPSL routines (histdef, histwrite, getin, ...) are case sensitive. That is another classic cause of apparently illogic problems.