Obtain maximal and minimal values for conserved quantities

[ole]

Will Power suggested at the August Tsunami Risk Modelling Workshop that a simple feature reporting maxima and minima (and the times they occurred) of all conserved quantities would be very useful.

Tom Baldock further suggested that the location of reported extrema should be specified (e.g. as an (x,y) coordinate).

I'd suggest we implement this feature to have an optional polygon (and time interval) restricting the domain in which extrema are sought. This would be very similar to the maximal runup height defined in ticket:172 and implemented in changeset:4551 and changeset:4554.

A decision whether this function should work on sww files or during computation must be made. I leand towards the former as it allows the feature to be recomputed without having to rerun the model.

[William Power]

With regard to the question of whether the function should work on sww files or during computation:

It would be much more helpful to me if this could be done during computation. The reason for this is that when working with short period waves it becomes necessary to write out to the sww file at short time intervals (eg 20 or 30 sec) in order to be sure of capturing the maximum. And this leads to very large sww files... sometimes so large that the results have to be spread across several sww files (because of 2Gb limit).

Hence my preference for collecting this data during the computation.

[ole]

I am planning the following syntax

The idea is be to specify which quantities (or derived quantities) to monitor. This is done when the model is created.

	domain.monitor_quantities('stage', 'xmomentum', 
	  				   'stage-elevation', ....)

One may optionally specify a polygon and a time interval to restrict the extrema calculation as in

	domain.monitor_quantities('stage', 
			          polygon = ...,
				  time_interval = [2053.3, 4008])

Then, accumulated and instantaneous extrema (as well as their locations) for all listed quantities subject to restrictions can be reported using a method like timestepping_statistics() or boundary_statistics() as in

for _ in evolve(..,..):
        print domain.timestepping_statistics()
	print domain.quantity_statistics()

The output at each timesteps would be something like

Time = 4.2500, delta t in [0.5210, 0.0723], steps=3 (0) Monitored quantities (restricted by specified polygon):
    stage 
	  Values at time = 4.2500 in [8.23, 11.23]
        Minimum attained at location = (267.19, 224.6) 
	  Maximum attained at location = (711.43, 102.41)

        Values over time [1.3000, 4.2500] in [-3.456, 12.345]
        Minimum attained at time = 2.2134, location = (235.3, 525.6) 
	  Maximum attained at time = 4.1307, location = (753.88, 182.4)

    stage-elevation
	  ...
        ...

The final calculated extrema subject to polygon and time interval are then stored in the sww file as

stage_extrema xmomentum_extrema stage-elevation_extrema etc

[ole]

Also the update must take place at every *internal* timestep.

[ole]

Implemented in changeset:4699 through to changeset:4706.

[ole]

I am reopening this ticket due to a suggestion from Joaquim Luis et al that it'd be better to store the extrema for each vertex in the sww file. The overall values can then easily be deducted if need be. I suggest we use some the work done here to implement Joaquim's suggestion. See Sourcforge postings in April-May 2008.

[ole]

The storage of extrema across all nodes should also be used by the new OGRE viewer so this feature should be implemented before viewer development is resumed.