Revised documentation, whatsnew and deprecations.#31
Revised documentation, whatsnew and deprecations.#31pp-mo merged 1 commit intostructured_load_apifrom
Conversation
pp-mo
force-pushed
the
structured_load_api_whatsnew
branch
from
19e38d6 to
73b290b
Compare
| @@ -0,0 +1,10 @@ | |||
| * Support for "fast" loading of UM files has been added. | |||
| This can dramatically accelerate loading speeds of fieldsfiles and PP files, | |||
| if they meet certain common structural requirements. | |||
There was a problem hiding this comment.
I wonder whether a little more on the common structural requirement would help here.
Perhaps something along the lines of
common structural requirements. The expected structure is the one that Fields Files conform to
as they are written out by the Met Office Unified model, where fields are ordered by vertical level,
then by time, and finally by STASH code, within the file
I also think a glib statement about results being unpredictable in cases where this structure does not exist within the file would be useful
There was a problem hiding this comment.
You're right, we really do need a specific explanation somewhere that "normal" UM outputs will definitely meet the "structured criteria".
However, my key goal right here was to keep this as short as possible,
as I don't think anything lengthy belongs in the initial 'whatsnew' list.
so I'm thinking we should link to the main docs for all the details.
However, it's just struck me that it would be very natural to have a discussion of this as a "featured item" at the bottom of the whatsnew page, as we have done before.
So, that would be a good home for some introductory non-reference-documentation-like notes and explanations.
I'm not quite sure how we can prototype that approach, but it can be stuck in this file for now
-- the contributions files are really only source material for someone finalising a release, after all.
Does that sound appropriate to you @marqh ?
I think that approach should let us to incorporate all your suggestions here so far (for more detail in the whatsnew) without breaking up the flow.
I'll have a go ...
| # | ||
| # Also in our case, we need to apply the basic single-field filtering | ||
| # operation that speeds up phenomenon selection. | ||
| # operation which speeds up phenomenon selection. |
| 'structured' UM files, providing much faster load times. | ||
| "Structured" loading is a streamlined, fast load operation, to be used | ||
| **only** on fieldsfiles or PP files whose fields repeat regularly over | ||
| the same vertical levels and times (see full details below). |
There was a problem hiding this comment.
perhaps useful working to repeat in the what's new entry
| vertical levels and time points found in the file. | ||
| When a user callback function is used with structured-loading, it is | ||
| called in a somewhat different way than in a 'normal' load : | ||
| The callback is called once for each basic *structured* cube loaded, |
There was a problem hiding this comment.
should the need to alter encoding of call back functions be explicitly referenced in the what's new?
pp-mo
force-pushed
the
structured_load_api_whatsnew
branch
from
73b290b to
c97a57d
Compare
|
Rebased. |
|
I'm going to merge this back onto the main branch (cf #27), and make a full Iris PR out of it ... |
2 participants
Attempt at whatsnew + detail documentation.
For now at least, I've put all the details docs into the docstring of the public context-manager.
Note that in documenting callback requirements, I had to make 'FieldCollation' a public class.
More work wanted before I'm ready with this...
DO NOT MERGE