Enum IntEventType

  • All Implemented Interfaces:
    Serializable, Comparable<IntEventType>, IEventType

    public enum IntEventType
    extends Enum<IntEventType>
    implements IEventType
    An enum defining the integer variable event types:
    • REMOVE: value removal event,
    • INCLOW: lower bound increase event,
    • DECUPP: upper bound decrease event,
    • BOUND: lower bound increase and/or upper bound decrease event,
    • INSTANTIATE: variable instantiation event
    Int event types are used with four different purposes. But first of all, there is a hierarchy between events REMOVE is the smallest one, INCLOW and DECUPP are equivalent and induce REMOVE and INSTANTIATE is the greatest and induced the three lower ones. Those four events aim at reducing the event footprint: for example if one propagator removes values 1,2 and 3 from V={1, 2, 3, 4, 5}, it can be seen either by a sequence of 3 REMOVE OR one INCLOW. Both express the same operations, one with 3 items the second with only one Now, the purposes:
    1. in Propagator.getPropagationConditions(int i). It helps sorting the propagator of the variable i wrt the types of event they can deal with. Propagators which react to the same type of events are placed in the same "bucket". Thus, when the variable i is modified, only propagators which are able to deduce something from that event are called. In that case, combinations of events are allowed, such as {REMOVE, INCLOW} or {REMOVE, INCLOW, DECUPP, INSTANTIATE}, and are stored, for each variable, with the help of bit mask.
    2. when the variable is actually modified. Any propagators can modify its variable, always through one of the provided methods, such as IntVar.instantiateTo(int, ICause) or IntVar.updateLowerBound(int, ICause). In that case, when the propagation engine is triggered, with only single one event as input: INSTANTIATE or INCLOW. Then, in the propagation engine, the event is stored, possibly merged with not propagates ones, for future execution.
    3. when a propagator is selected for propagation, the events its variables have registered are treated sequentially. Here, if a variable has registered multiple events, the union is given as input to the propagator through Propagator.propagate(int, int). In this method, it may happen that the events registered are filtered, calling isRemove(int) or isBound(int), to adapt the filtering to the type of events registered. Note that the conditional tests should consider that events can be merged.
    4. for explanation purpose, to adapt the explanation schema to the type of event received.
    If a propagator reacts on value removals, it is executed on any events occurring on the variable(s), since REMOVE is the smallest event. Then, if other type of event occurs, it is greater and maybe a specific and/or more efficient algorithm can be used instead. So, we prefer testing whether an event is greater than smaller. More over, using deltas, we can iterate over newly removed values, without paying interest to the type of events registered.

    When, in your propagator, you declare Propagator.getPropagationConditions(int i) like this:

    
          public int getPropagationConditions(int vIdx) {
              return IntEventType.boundAndInst();
          }
     
     
    your propagator will be informed anytime one if its variables is modified by any events but REMOVE (that is INCLOW and/or DECUPP and/or INSTANTIATE). On the contrary, if you defined something like:
     
          public int getPropagationConditions(int vIdx) {
              return IntEventType.all();
          }
     
     
    your propagator will be informed anytime one of its variable is modified by any events. Later, when your propagator is actually executed, the aggregated events mask is given as input (2nd parameter of Propagator.propagate(int i,int m)), and here you can adapt the algorithm to the events got. Indeed, you can have a merge event made of DECUPP and INCLOW and REMOVE which indicates that:
    1. the upper bound of the variable i has decreased,
    2. its upper bound has increased and
    3. some values has been removed between old LB and old UB.
    IMPORTANT: note that, if a variablev={1,2,3,4,5,6} is chronologically modified like this:
    1. v \ {2}
    2. v < 6
    3. v > 3
    then the first event ( v \ {2}) is subsumed by the third one (v > 3). There is no efficient way to consider the subsumption by the propagation engine.
    Author:
    Charles Prud'homme, Jean-Guillaume Fages
    • Enum Constant Detail

      • REMOVE

        public static final IntEventType REMOVE
        Value removal event
      • INCLOW

        public static final IntEventType INCLOW
        Increasing lower bound event
      • DECUPP

        public static final IntEventType DECUPP
        Decreasing upper bound event
      • BOUND

        public static final IntEventType BOUND
        Increasing lower bound and decreasing upper bound event
      • INSTANTIATE

        public static final IntEventType INSTANTIATE
        Instantiation event
    • Method Detail

      • values

        public static IntEventType[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
        for (IntEventType c : IntEventType.values())
            System.out.println(c);
        
        Returns:
        an array containing the constants of this enum type, in the order they are declared
      • valueOf

        public static IntEventType valueOf​(String name)
        Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
        Parameters:
        name - the name of the enum constant to be returned.
        Returns:
        the enum constant with the specified name
        Throws:
        IllegalArgumentException - if this enum type has no constant with the specified name
        NullPointerException - if the argument is null
      • getMask

        public int getMask()
        Description copied from interface: IEventType
        Return the value of the mask associated with the event.
        Specified by:
        getMask in interface IEventType
        Returns:
        the mask of the event.
      • combine

        public static int combine​(IntEventType... evts)
        Combines into a single mask some evts.
        Parameters:
        evts - list of events to combine
        Returns:
        mask expressing the combination of evts
      • all

        public static int all()
        Returns:
        the remove, bounds and instantiation events' mask
      • boundAndInst

        public static int boundAndInst()
        Returns:
        the bound and instantiation events' mask
      • instantiation

        public static int instantiation()
        Returns:
        the instantiation event's mask
      • isInstantiate

        public static boolean isInstantiate​(int mask)
        Parameters:
        mask - the mask to check
        Returns:
        true if mask contains an INSTANTIATE event mask.
      • isRemove

        public static boolean isRemove​(int mask)
        Parameters:
        mask - the mask to check
        Returns:
        true if mask contains an REMOVE event mask. Note that it does not test event hierarchy: even if INCLOW is a sequence of REMOVE this method will return false when '2' is given as input.
      • isBound

        public static boolean isBound​(int mask)
        Parameters:
        mask - the mask to check
        Returns:
        true if mask contains an BOUND event mask.
      • isInclow

        public static boolean isInclow​(int mask)
        Parameters:
        mask - the mask to check
        Returns:
        true if mask contains an INCLOW event mask.
      • isDecupp

        public static boolean isDecupp​(int mask)
        Parameters:
        mask - the mask to check
        Returns:
        true if mask contains an DECUPP event mask.