next_if¶

Syntax¶

next_if(<state_name>, <expression>)

Parameters¶

<state_name>: A valid name of a state within the current condition as the target of the transition.
<expression>: An expression that evaluates to true or false to determine if this transition should apply.

Truthy and Falsey Values¶

Like in many programming languages, FRED's numeric expressions can be evaluated as either true or false. Values that evaluate to true are considered "truthy", and values that evaluate to false are considered "falsey".

In FRED, a value of 0 is falsey, and all non-zero values are truthy.

Description¶

Important

This is a special action which cannot appear within an if statement or loop!

Each agent typically transitions from one state to another after waiting for a period of time. The next_if statement defines a conditional transition that applies only when the specified condition evaluates to true.

A next_if transition has an implicit probability of 100% when its condition is true. Like other transition rules, these probabilities are normalized if multiple transitions apply.

The difference between transition rules¶

There are three types of transition rules:

next_with_prob - Defines a transition with an explicit probability
next_if - Defines a transition that applies with 100% probability when its condition is true
default - Defines the transition that applies when other rules don't apply or for the remaining probability

A state can only have one default transition rule, and it cannot be conditionally defined. However, multiple next_with_prob and next_if rules can be defined within a state.

All transition rule probabilities are considered together. For next_with_prob, the probability is explicitly specified. For next_if, the probability is 100% when the condition is true, and 0% when false.

If the combined probabilities from all applicable transition rules (including next_with_prob and next_if) 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.

Example: Combined age-based transitions¶

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

state A {
    age_based_prob = 0
    if (age() < 10) {
        age_based_prob = 0.25
    }
    wait(0)
    next_with_prob(B, age_based_prob)
    default(C)
}

For agents less than 10 years old, the probability of going to state B is 0.25. Because the total probability is less than 1.0, the default transition rule applies with probability 0.75 = 1.0 - 0.25.

For agents 10 or older, age_based_prob remains 0, so the total probability equals 0.0. In this case, the default transition rule applies with probability 1.0.

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)
    next_if(B, age() <= 10)
}

state A {
    wait(24)
    next_if(B, age() <= 10)
    default(A)
}

This might lead to unexpected results if a missing default rule is applied. For example:

state A {
    wait(0)
    next_if(B, age() <= 10) # WRONG!
}

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

Examples¶

In this example, a conditional transition is defined using next_if:

state MyState {
    wait(0)
    next_if(StateA, age() > 18)
    default(StateB)
}
}

Multiple conditional transitions can be defined:

state MyState {
    wait(24)
    next_if(StateA, age() < 18)
    next_if(StateB, (age() >= 18) && (age() < 65))
    default(StateC) # for age() >= 65
}