Clarifying attack/damage rates

[drbergman]

Motivating question

If cd8 attacks tumor with attack_rate("tumor") = 1.0 and the damage_rate for cd8 is 1.0, how much damage do we expect a tumor agent to accumulate per minute as it continuously as a neighboring cd8 cell?

Expected answer

If the attack rate is in attack/minute (against a given neighbor) and the damage rate is in damage/attack, the answer is obvious: we expect 1.0 damage/minute. This answer is sensible, predictable, and knowable from only the two numbers above.

What actually happens

The cd8 attacks in a mechanics_dt (default = 0.1 min) with probability probability = attack_rate("tumor") * mechanics_dt = 1.0 * 0.1 = 0.1 [^1][^2]. This has the desirable effect of initiating an "attack" once per minute, exactly as the attack rate suggests.

Then the unexpected happens. Upon successful attack by the cd8, the tumor agent accumulates damage_rate * mechanics_dt = 1.0 * 0.1 = 0.1 damage[^3]. The net effect is that the tumor agent is expected to accumulate 0.1 damage per minute from this interaction.

Analyzing this more closely, we see the expected damage accumulation in a minute for the tumor agent is

$$ \begin{align*} \Delta\text{damage} & = \mathbb{E}[\text{num attacks}] \times \text{damage}/\text{attack} \ & = \text{attack probability per dt} * \text{num steps} \times (\text{damage rate} * dt) \ & = (\text{attack rate} * dt) * (1.0 \text{ min} / dt) \times (\text{damage rate} * dt) \ & = \text{attack rate} * \text{damage rate} * dt \end{align*} $$

Notice that $dt$, the mechanics_dt, factors in to how much damage is accumulated by the tumor agent. In other words, knowing only the attack rate and damage rate is insufficient to predict the damage accumulation rate.

Proposed change

Redefine the damage_rate to be damage/attack rather than damage/minute. That is, the attack_rate will be the rate at which the attacking cell type, cd8 above, attacks a given neighbor (possibly modulated by immunogenicity[^1]); and the damage_rate is the amount of damage dealt to the attacked cell type, tumor above, given that the attacker attacked.

[^1]: There is also an immunogenicity factor I'll ignore here. [^2]: cf. https://github.com/MathCancer/PhysiCell/blob/3d7051f167b6b3551296a4b6d93db742dc532ee6/core/PhysiCell_standard_models.cpp#L1234 [^3]: cf. https://github.com/MathCancer/PhysiCell/blob/3d7051f167b6b3551296a4b6d93db742dc532ee6/core/PhysiCell_cell.cpp#L1407

[drbergman]

See #224

[drbergman]

Going to be addressed in a soon-to-be-opened PR from development-paul