# positiveValue (1d, 2d, 3d)¶

Computes a time step given such that when a source time depenedent source is added to the value, the value in question does not become negative. An example of this is adding radiation loss to the energy of a fluid. If the time step is too large the fluid energy can become negative, however a smaller time step will allow the fluid to radiate energy until radiated energy is negligible and then the time step will rise again. The positiveValue restriction as defined the following way. $$S$$ is the source term, $$E$$ is the energy, $$B_{v}$$ is the lowest value that we would like $$E$$ to be, $$\Delta t$$ is the time step, $$c$$ is a coefficient which is generally used to alter the sign of the source term and $$\alpha$$ is a reduction factor which scales the time step. The time step is given below

The time step restriction is derived from simple considerations

$\notag \begin{equation} \frac{\partial E}{\partial t}=S \end{equation}$

Which suggests that

$\notag \begin{equation} E^{n+1}=E^{n}+\Delta t\,S>B_{v} \end{equation}$

So if we want to make sure we do not subtract all the energy off in one time step then $$\Delta t$$ would be chosen as

$\notag \begin{equation} \Delta t<-\frac{E^{n}-B_{v}}{S} \end{equation}$

We introduce the factor $$\alpha$$ and $$c$$ to provide more flexibility in determining how the restriction should be applied and the relative sign of the source S. The restriction is then given by the following relation.

$\notag \begin{equation} \Delta t = -\alpha\frac{E-B_{v}}{c\,S} \end{equation}$

In the case where $$c\,S>0$$ no restriction is applied to $$\Delta t$$.

## Parameters¶

alpha (float, required)
If alpha is 1.0 then the time step that results will zero out the pressure in one time step. If alpha=0.25 then it will zero out the pressure in 4 time steps. alpha is similar to a cfl number where 1.0 is the maximum value that should be used.
positiveIndex (integer, required)
Tell which component of the value we intend to keep positive should be used for comparison
sourceIndex (integer, required)
Tell which component source vector should be used for comparison
basementValue (float, required)
The value for which the positiveValue should not go lower than
coefficient (float, required)
The restriction compares the positive value with the source value. If the source value is going to be added to the positive value then coefficient=1.0. If the source value is going to be subtracted from the source value then coefficient=-1.0 is correct.
numComponents (integer, optional)
Occasionally the user will want to apply the postitive value restriction to an array of variables such as densities in chemical reactions. numComponents allows you to specify the number of components that the restriction will be applied to. It’s assumed that the values will range from positiveIndex to positiveIndex+numComponents-1 and sourceIndex to sourceIndex+numComponents-1 and that coefficient and alpha will be constant for all components.

## Parent Updater Data¶

The following data structures should be specified to the timeStepRestrictionUpdater (1d, 2d, 3d) that calls the positiveValue Time Step Restriction.

in (string vector, required)
1st variable
The first variable is the value we want to keep positive. An example would be energy or pressure.
2nd variable
The second variable is the value that will be added to the first value when multiplied by $$\Delta t$$. An example of the second value could be energy loss rate due to radiation or mass loss rate due to chemical reactions.

## Example¶

The following block demonstrates positiveValue used in combination with timeStepRestrictionUpdater (1d, 2d, 3d) to compute a time step that keeps the energy of the fluid (component 4 of input variable q) positive:

<Updater timeStepRestrictionEnerngy>
kind = timeStepRestrictionUpdater2d
in = [q, reactionEnergy]
timeSteps = [diffDT4]
onGrid = domain
restrictions = [positiveSource]
courantCondition = 1.0

<TimeStepRestriction positiveSource>
kind = positiveValue2d
positiveIndex = 4
sourceIndex = 0
alpha = 0.01
coefficient = 1.0
basementValue = BASEMENT_ENERGY
includeInTimeStep = false
</TimeStepRestriction>

</Updater>