next¶

Syntax¶

next()
next(state_name)
next(state_name) with prob(p)

Parameters¶

state_name: Optional. A valid name of a state within the current condition as the target of the transition.
p: Optional. Required only if with prob is used. The probability of the given state transition. 0 represents a 0% chance and 1 represents a 100% chance.

Description¶

Each agent typically transitions from one state to another after a waiting for period of time. This statement dictates which state agents in a given state are to transition to next.

If next appears with no arguments, it indicates a transition from the current state into the current state again.

A next rule can optionally be followed by with prob, which allows a user to define the probability that an agent follows the transition defined by the rule.

The difference between using `next` and `default`¶

Transition rule probabilities for next depend on the prob clause at the end of each rule (with a default clause of prob(1), or 100%). If the probabilities sum to more than 1.0, they are normalized so that the sum is exactly 1.0. If the probabilities sum to less than 1.0, the default rule is assigned the remaining probability.

Suppose we have three states A, B, and C, and we are writing transition rules for state A. Suppose we want to have agents less than 10 years old transition from A to B with probability 0.25 and to state C with probability 0.75 (i.e. all other agents should always transition to state C).

The preferred code for this situation would be:

state A {
    ...
    if (age() < 10) then next(B) with prob(0.25)
    default(C)
}

If an agent less than 10 years old is in state A then the if() statement is the only qualifying transition rule, so the tentative probability of going to state B is set to 0.25. Because the total probability is less than 1.0, the default next state rule applies, and the probability of going to C is set to 0.75 = 1.0 - 0.25.

If an agent 10 or older is in state A then there are no qualifying transition rules, so the total probability equals 0.0; In this case the default transition rule applies and sets the probability of going to state C to 1.0 = 1.0 - 0.0.

The following code would lead to incorrect results:

state A {
    ...
    if (age() < 10) then next(B) with prob(0.25)
    next(C)  # WRONG!
}

Things work fine for agents 10 or older, but if an agent less than 10 years old is in state A then both transition rules apply. The if statement sets the tentative probability of going to state B to 0.25. The next statement sets the tentative probability of going to C to 1.0. The Total is 1.25 = 0.25 + 1.0, so the probabilities are normalized to

p(A,B) = 0.25/1.25 = 0.20

and

p(A,C) = 1.0/1.25 = 0.80

which are not the desired results.

Missing Default Rule¶

If no default rule is included in a state, the default transition state is the state itself, so these two snippets are equivalent:

state A {
    ...
    wait(24)
    if (age() <= 10) then next(B)
}

state A {
    ...
    wait(24)
    if (age() <= 10) then next(B)
    default(A)
}

This might lead to unexpected results if a missing default rules is applied. For example, consider this snippet:

state A {
    wait(0)
    if (age() <= 10) then next(B)  # WRONG!
}

For all agents over age 10, the above code would lead to an infinite loop back to state A, which is probelmatic because we do not wait in this state.

Examples¶

This example shows a portion of a possible INFLUENZA condition.

condition INFLUENZA {
    ...
    state Exposed {
        INFLUENZA.sus = 0
        wait(24 * lognormal(1.9, 1.23))
        next(InfectiousAsymptomatic) with prob(0.33)
        default(InfectiousSymptomatic)
    }

    state InfectiousAsymptomatic {
        ...
    }

    state InfectiousSymptomatic {
        ...
    }
    ...
}

In this example, a next rule is conditionally defined.

state MyState {
    wait(0)
    if (age() > 18) then next(StateA)
    default(StateB)
}

In these example, a transition between state A and state B is defined with a probability of 50%.

state A {
    wait(24)
    next(B) with prob(0.5)
    default(A)
}