Clarify D-Flow FM documentation

[theavuik]

Outstanding questions wrt the page D-Flow FM wrapper:

With respect to the section 'D-Flow FM Wrapper':

• Could we add a short explanation of what the “wrapper” does conceptually? It starts very abruptly.
• Is the “dcsmv5 (North Sea)” model public or internal? Should we link to where users can find it?
• Should it be forward slashes / or backward slashes \ to link to folders and files?

With respect to the section 'Start and End Time of Model Runs':

• At the end of the section on 'Start and end time of model runs' we give an example configuration for this data object. We earlier decided that we will refer here to a to-be-written file (by @erikpelgrim) with respect to files, ids and aliases (see also the question below).
• Furthermore, where in the XML hierarchy this snippet belongs?

With respect to the section 'Model state':

• Could we explain when to use map.nc vs _rst.nc files (criteria or use cases)?
• 'The previously mentioned Java class will create exchange items for each variable with the variable name as "exchange item id"'. I think we need some more explanation about exchange items, ids and aliases. I don't understand what you mean here, would you like to use the variable name as an id for the corresponding exchange item?

With respect to the section 'Boundary files':

• Could we clarify when to use .tim or .bc boundary file formats?
• Are the ids boundaries and bcfile always used for .tim and .bc files, respectively?

With respect to the section 'NetCDF concatenater':

• I cannot find any documentation related to action (see the code block). Please write a description of it.

With respect to the section 'Restarting from file':

• Do you have an example for which value for runId should be chosen?

With respect to the section 'Partitioning':

• The section assumes readers know what “partitioning” means, should we define it briefly?
• Should we clarify whether the argument must match a D-Flow FM setting elsewhere?
• Should we mention what happens if partitions are unequal or missing files?

Outstanding questions wrt the page D-Flow FM related information:

With respect to the section 'Writing Kalman Gain':

• Should we explain what determines the station_dimension (e.g., observation points, grid cells)?
• In this text we mention 'gridded noise'. We need more explanation on it.
• 'noise dimensions'. Shouldn't that be 'noise arguments' or so?
• What are s1 and unorm?
• What do you know by the 'number of predictors'?
• Where should the two lines with double for s1 and unorm be added? In the java code? Should a user actively add it or is this just to inform the user?

With respect to the section 'Reading Kalman gain':

• In the example block, is the time format fixed to dateTimeString or can other formats be used?
• In this text the dirPrefix name is explicitly mentioned: kgStorage_L100km_*. Why is this name mentioned, does this matter for the reader? Should we clarify what “L100km” refers to? Is it a correlation length or a specific configuration?

With respect to the section 'Maps Noise Model': this section is very unclear to me and should really be improved.

• Should we provide a short definition of “noise” here? Is it a noise model for gridded data?
• What is p and what is the meteofile_p?
• Should we include an XML example showing the entry for the NetcdfDataObject, to make it clearer?
• 'the following options should be configured: allowOverwriteForcastWith* and transformation="set"'. Where should this be configured? Should we describe what the “transformation” options mean and when to use each?
• Can we give some more information about the air pressure that is suddenly mentioned here?
• What are forecast noise and analysis noise?
• 'the following options should be configured: allowOverwriteForcastWith* and transformation="set"'. Where should this be configured?
• I really do not understand the last sentence of this file, 'For this reason, ...., 49.0, 48.0.' How are these y-coordinates related to the p? How do you know you start at 63? Maybe you just want to inform that the order should be 'time, y, x' where y should be decreasing? Are descending y-coordinates indeed required or is this just specific to this example? Is x increasing?

[theavuik]

Maybe some questions above are also related to the old issue #297?

[erikpelgrim]

Document with answering questions in progress

QandA_DFlowFM.txt