TSEvent: refactor and fix bugs, add TSSetPostEventStep()

Refactor the core algorithm for resolution of events: TSEventHandler()
and the helper functions, fixing the existing bugs.

Chang

TSEvent: refactor and fix bugs, add TSSetPostEventStep()

Refactor the core algorithm for resolution of events: TSEventHandler()
and the helper functions, fixing the existing bugs.

Change event indicator functions from PetscScalar to PetscReal.
Change the API of TSSetEventHandler(): in the user `indicator()` callback,
the 'fvalue' argument type changed from PetscScalar[] to PetscReal[].

Add TSSetPostEventStep(), deprecate TSSetPostEventIntervalStep().
Deprecate option -ts_event_post_eventinterval_step.

Fix bugs in interaction of TSEvent with tspan.
Add six new test examples.

Below are the examples of bugs fixed by this patch.
The source codes (ex3.c, ex3span.c, ex4.c, ex5.c) can be found
in src/ts/event/tests. To run them with the older Petsc versions,
one would need to comment out "#define NEW_VERSION".
Behaviour for three library versions is reported below:
* ORIG: current Petsc version, before the proposed patch.
* 6688: independently of the proposed patch, Merge Request 6688 was
developed, which fixed some bugs with zero-crossing directions.
* NEW : the proposed patch.

./ex3 -ts_monitor -ts_event_monitor -ts_view -ts_type beuler \
-ts_adapt_type basic -flg -V 1e9 -ts_adapt_dt_min 1e-6 -change5 1 -dir 1
* ORIG: fails to resolve 5 out of 6 events, and resolves 23 incorrect events.
* 6688: fails to exit the TSEvent iteration via the step size (bracket size)
criterion.
* NEW : ok, resolves all 6 events.

./ex4 -ts_adapt_type basic -ts_type rk -ts_dt 0.25 -ts_event_tol 1e-8 \
-dir 0 -ts_adapt_dt_min 1e-10 -ts_view -ts_monitor -ts_event_monitor
* ORIG: only reaches t = 0.0300236 after 10000 TS steps.
* 6688: only reaches t = 0.0300236 after 10000 TS steps.
* NEW : ok, reaches the final time t = 4.0 after 96 TS steps, resolving
all 16 events.

./ex5 -ts_monitor -ts_event_monitor -ts_type rk -ts_adapt_type basic \
-ts_view -ts_dt 0.25 -flg -dir 0
* ORIG: only reaches t = 4.0 after 10000 TS steps, erroneously reports
event at t = 4.0 around 5000 times.
* 6688: only reaches t = 4.0 after 10000 TS steps.
* NEW : ok, reaches the final time t = 10.0 after 99 TS steps, resolving
all 34 events.

./ex5 -ts_monitor -ts_event_monitor -ts_type rk -ts_adapt_type basic \
-ts_view -ts_dt 0.25 -flg -dir 1
* ORIG: fails, starts taking negative time steps, no events are correctly
resolved.
* 6688: ok, but slower: 90 TS steps to resolve all 17 events.
* NEW : ok, and faster: 48 TS steps to resolve all 17 events.

./ex5 -ts_monitor -ts_event_monitor -ts_type rk -ts_adapt_type basic \
-ts_view -ts_dt 0.25 -flg -dir -1
* ORIG: fails, starts taking 'nan' time steps.
* 6688: mostly fails, only reaches t = 4.99993 after 10000 TS steps.
* NEW : ok, reaches the final time t = 10.0 after 74 TS steps, resolving
all 17 events.

The same run in parallel:
mpirun -n 2 ./ex5 -ts_monitor -ts_event_monitor -ts_type rk \
-ts_adapt_type basic -ts_view -ts_dt 0.25 -flg -dir -1
* ORIG: fails, starts taking negative time steps, exits with runtime error.
* 6688: mostly fails, only reaches t = 3, besides, the parallel run is not
consistent with the serial run (see above).
* NEW : ok, reaches the final time t = 10.0 after 74 TS steps, resolving
all 17 events.

./ex3span -ts_monitor -ts_event_monitor
* ORIG: (confused by events) misses tspan points: 4.02, 4.21, 4.98, 5.01,
5.21, 5.98, 6, 6.01, 6.02, 6.21, 6.99, 7.21, 8.01, 8.21, 9.01.
* 6688: (confused by events) misses tspan points: 4.02, 4.21, 4.98, 5.01,
5.21, 5.98, 6, 6.01, 6.02, 6.21, 6.99, 7.21, 8.01, 8.21, 9.01.
* NEW : ok.

./ex3span -ts_monitor -ts_event_monitor -ts_event_post_event_step 0.5
* ORIG: misses the majority of tspan points (except 0.01 and 0.21),
and also resolves the last event location at wrong time t = 9.21.
* 6688: misses the majority of tspan points (except 0.01 and 0.21),
and also resolves the last event location at wrong time t = 9.21.
* NEW : ok.

show more ...

Merge remote-tracking branch 'origin/release'

Fix -Wzero-as-null-pointer-constant errors

Fix PetscOptionsGetViewer() so it works in a thread-safe way

When PetscOptionsGetViewer() returns, for example, PETSC_VIEWER_STDOUT_SELF the same object is shared
by all threads that call PetscOptio

Fix PetscOptionsGetViewer() so it works in a thread-safe way

When PetscOptionsGetViewer() returns, for example, PETSC_VIEWER_STDOUT_SELF the same object is shared
by all threads that call PetscOptionsGetViewer(). In the previous code PetscObjectReference() and
dereference (via PetscViewerDestroy() where called on the viewer by multiple threads after the viewer
was accessed thus corrupting the object.

This branch introduces a PetscOptionsRestoreViewer() that allows not doing the referencing and dereferencing
on persistant viewers, thus removing the specific race condition above.

Other possible solutions include

Use a lock on each PetscObjectReference/Dereference() just in case they are shared. Could be time consuming so one
could mark each object as either threadshared or independent and only do the locks on threadshared objects. This lowers
the cost but would require more extensive changes to PETSc infrastructure. And I do not know if this shared/not shared model
is what we need in the long run, though it might be.

show more ...

Merge remote-tracking branch 'origin/release'

Fixes for use of Calling Sequence of ... in the manual page

Merge branch 'release'

Remove unneeded on in Collective statements and fix Collective over

Commit-type: documentation

Rename rules.doc and rules.utils because GitLab treats the former as a MS Word document.

Thanks-to: Jed Brown

Remove DIRS variable and unneeded tabs from all makefiles since no longer needed

Commit-type: housekeeping

Fix typos

Remove first and last empty lines