Review 2011 changes for electron transport

[gonuke]

In preparation for FLUDAG, a full review of the handling of different use cases of the ray_firing wrapper for DAG-MCNP is necessary.

This review should consider the following:

• minimize the introduction of state variables that may lead to state confusion
• accommodate all the use cases anticipated in other charged particle transport schemes in a common way

In particular, the following SVN revisions are of interest:

• r303 (2011-06-23)
• r307 (2011-07-06)

[gonuke]

r303 commit log: Fix for problem with electron transport

• Provide a variant of dagmc_chkcel that behaves correctly when the test point is known to be at zero distance from a surface crossing. This variant operates only in terms of the direction of the particle.
• Use this variant at the appropriate place in echkcl. This is a candidate fix for ticket 446. I'm not certain it's the best fix, but it's worth testing.
• Get rid of a lot of unused parameters in dagmcchkcel_
• Document dagmcchkcel* functions
• Add a lot more tracing calls when TRACE_DAGMC_CALLS macro is defined.

[gonuke]

r307 commit log: wo bug workarounds for electron transport, both hacky:

• Only treat a call to track() as a streaming event if it is the first call to track() since the last call to newcel() (i.e., if it is the first call since a surface was traversed). If it's not the first such call, assume the particle didn't make it to the surface after all, and call rollback_last_intersection() on the ray history.

  What it fixes: situations where an electron advances part of the way along a particle track, then has some kind of event, then proceeds along the same ray with a second call to track(). We want such a call to return the same intersection as the first call.

  Why it's a hack: this isn't the right way to tell whether or not to roll back the ray history. The right way will be to detect all cases in MCNP where a particle's location is updated within its cell without reaching a surface or changing direction, and calling the rollback function in those cases.

• Add a dagmc_particle_terminate() function and call it when particles die. This function clears the ray history. It is a step towards a more comprehensive understanding of particle events within the dagmc glue code. (In the long run, we want to avoid having to infer such events from changes in program globals like xyz and nps.)

  Also call this function from getpar, which restores particle state from a temporary cache location that's distinct from the particle bank.

  What it fixes: situations where a particle spawns a new particle and state is temporarily stored in the savpar/getpar cache, leading dagmc to detect a streaming event when one should not occur.

  Why it's a hack: A call to getpar does not actually represent a particle termination, and should not necessarily lead to a discarding of the entire particle history. (I don't think discarding the history in this situation will ever lead to incorrect computation, so this workaround should be conservative.) This fix should be considered a short-term workaround while I figure out how the savepar/getpar cache should be integrated with the bank of ray histories. See notes on ticket #445.

This update requires MOAB r5044.