org.chocosolver.solver.constraints

Class Propagator<V extends Variable>

java.lang.Object

org.chocosolver.solver.constraints.Propagator<V>

All Implemented Interfaces:

Serializable, Comparable<Propagator>, ICause, Identity

Direct Known Subclasses:

PropAbsolute, PropAllDiff, PropAllDiffAC, PropAllDiffBC, PropAllDiffInst, PropAllDisjoint, PropAllEqual, PropAMNV, PropAmongGAC, PropAmongGAC_GoodImpl, PropAntiArborescences, PropAtLeastNValues, PropAtLeastNValues_AC, PropAtMost1Empty, PropAtMostNValues, PropAtMostNValues_BC, PropBinCSP, PropBitChanneling, PropBoolChannel, PropBoolMax, PropBoolMin, PropBoolSumCoarse, PropBoolSumIncremental, PropCardinality, PropCircuit_ArboFiltering, PropCircuitSCC, PropClause, PropClauseChanneling, PropCondAllDiff_AC, PropConditionnal, PropCostRegular, PropCount_AC, PropCountVar, PropDiffN, PropDistanceXYC, PropDistanceXYZ, PropDivXYZ, PropElement, PropElement, PropElementV_fast, PropEnumDomainChanneling, PropEqualX_Y, PropEqualX_YC, PropEqualXC, PropEqualXY_C, PropFalse, PropFastGCC, PropFullCumulative, PropGreaterOrEqualX_Y, PropGreaterOrEqualX_YC, PropGreaterOrEqualXC, PropGreaterOrEqualXY_C, PropIntBoundedMemberSet, PropIntChannel, PropIntEnumMemberSet, PropIntersection, PropInverse, PropInverseChannelAC, PropInverseChannelBC, PropKLoops, PropKnapsack, PropLargeCSP, PropLargeMDDC, PropLessOrEqualXC, PropLessOrEqualXY_C, PropLex, PropLexChain, PropMax, PropMaxBC, PropMaxElement, PropMemberBound, PropMemberEnum, PropMin, PropMinBC, PropMinElement, PropMultiCostRegular, PropNbEmpty, PropNogoods, PropNoSubtour, PropNotEmpty, PropNotEqualX_Y, PropNotEqualX_YC, PropNotEqualXC, PropNotEqualXY_C, PropNotMemberBound, PropNotMemberEnum, PropNotMemberIntSet, PropNotMemberSetInt, PropOffSet, PropOpposite, PropRegular, PropReif, PropSat, PropScalarEq, PropScale, PropSetIntValuesUnion, PropSort, PropSquare, PropSubcircuit, PropSubcircuit_AntiArboFiltering, PropSubCircuitSCC, PropSubsetEq, PropSumEq, PropSumOfElements, PropSymmetric, PropTableStr2, PropTimesNaive, PropTimesXY, PropTimesZ, PropTrue, PropUnion, RealPropagator

public abstract class Propagator<V extends Variable>
extends Object
implements Serializable, ICause, Identity, Comparable<Propagator>

A Propagator class defines methods to react on a Variable objects modifications. It is observed by Constraint objects and can notify them when a Variable event occurs.
Propagator methods are assumed to be idempotent, ie : Let f be a propagator method, such that f : D -> D' include D, where D the union of variable domains involved in f. Then, f(D)=f(D').

A Propagator declares a filtering algorithm to apply to the Variables objects in scope in order to reduce their Domain objects. That's why the propagate method should be adapted to the expected filtering algorithm. This method is called through Constraint observers when an event occurs on a scoped Variable object. propagate method can throw a ContradictionException when this Propagator object detects a contradiction, within its filtering algorithm, like domain wipe out, out of domain value instantiation or other incoherence.
Furthermore, a Propagator object can be entailed : considering the current state of its Variable objects, the internal filtering algorithm becomes useless (for example: NEQ propagator and a couple of Variable objects with disjoint domains). In other words, whatever are the future events occurring on Variable objects, new calls to propagate method would be useless.
this can be deactivated using the setPassivemethod. It automatically informs Constraint observers of this new "state".

The developer of a propagator must respect some rules to create a efficient propagator:
- internal references to variables must be achieved referencing the this.vars after the call to super, this prevents from wrong references when a variable occurs more than once in the scope (See PropCount_AC for instance).
- //to complete

Since:

0.01

Version:

0.01, june 2010

Author:

Xavier Lorca, Charles Prud'homme, Jean-Guillaume Fages

See Also:

Variable, Constraint, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected Propagator	aCause
protected static short	ACTIVE
protected Constraint	constraint
protected static org.slf4j.Logger	LOGGER
protected static short	NEW
protected static short	PASSIVE
protected PropagatorPriority	priority
protected boolean	reactToFineEvt
protected static short	REIFIED
protected Solver	solver
protected V[]	vars

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Propagator(V... vars) Creates a non-incremental propagator which does not react to fine events but simply calls a coarse propagation any time a variable in vars has changed.
protected	Propagator(V[] vars, PropagatorPriority priority, boolean reactToFineEvt) Creates a new propagator to filter the domains of vars.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	addVariable(V... nvars) Enlarges the variable scope of this propagator Should not be called by the user.
boolean	advise(int idxVarInProp, int mask) Advise a propagator of a modification occurring on one of its variables, and decide if this should be scheduled.
int	arity()
int	compareTo(Propagator o)
void	contradiction(Variable variable, String message) Throws a contradiction exception based on
void	decNbPendingEvt() informs that a fine event has been treated.
void	defineIn(Constraint c) Informs this propagator the (unique) constraint it filters.
void	duplicate(Solver solver, gnu.trove.map.hash.THashMap<Object,Object> identitymap) Duplicate the current propagator.
int	dynPriority()
void	flushPendingEvt() informs that all fine events have been treated.
void	forcePropagate(PropagatorEventType evt) Schedules a coarse propagation to filter all variables at once.
Constraint	getConstraint()
int	getId()
int	getNbPendingEvt()
int	getNbVars()
PropagatorPriority	getPriority()
protected int	getPropagationConditions(int vIdx) Return the specific mask indicating the variable events on which this Propagator object can react.
Solver	getSolver()
V	getVar(int i) Returns the element at the specified position in this internal list of V objects.
V[]	getVars()
int[]	getVIndices()
int	hashCode()
void	incNbPendingEvt() informs that a new fine event has to be treated.
boolean	isActive()
boolean	isCompletelyInstantiated()
abstract ESat	isEntailed() Check wether this is entailed according to the current state of its internal structure.
boolean	isPassive()
boolean	isReifiedAndSilent()
boolean	isStateLess()
abstract void	propagate(int evtmask) Call the main filtering algorithm to apply to the Domain of the Variable objects.
void	propagate(int idxVarInProp, int mask) Incremental filtering algorithm defined within the Propagator, called whenever the variable of index idxVarInProp has changed.
boolean	reactToFineEvent()
void	setActive() informs that this propagator is now active.
void	setPassive() informs that this propagator is now passive : it holds but no further filtering can occur, so it is useless to propagate it.
void	setReifiedSilent() informs that this reified propagator may not hold.
void	setReifiedTrue() informs that this reified propagator must hold.
void	setVIndices(int idx, int val) Changes the index of a variable in this propagator.
String	toString()
boolean	why(RuleStore ruleStore, IntVar var, IEventType evt, int value) Add new rules to the rule store

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

LOGGER

protected static final org.slf4j.Logger LOGGER

NEW

protected static final short NEW

See Also:

Constant Field Values

REIFIED

protected static final short REIFIED

See Also:

Constant Field Values

ACTIVE

protected static final short ACTIVE

See Also:

Constant Field Values

PASSIVE

protected static final short PASSIVE

See Also:

Constant Field Values

aCause

protected Propagator aCause

priority

protected final PropagatorPriority priority

reactToFineEvt

protected final boolean reactToFineEvt

constraint

protected Constraint constraint

solver

protected final Solver solver

vars

protected V extends Variable[] vars

Constructor Detail

Propagator

protected Propagator(V[] vars,
          PropagatorPriority priority,
          boolean reactToFineEvt)

Creates a new propagator to filter the domains of vars.

To limit memory consumption, the array of variables is referenced directly (no clone). This is the responsibility of the propagator's developer to take care of that point.

Parameters:

vars - variables of the propagator. Their modification will trigger filtering

priority - priority of this propagator (lowest priority propagators are called first)

reactToFineEvt - indicates whether or not this propagator must be informed of every variable modification, i.e. if it should be incremental or not

Propagator

@SafeVarargs
protected Propagator(V... vars)

Creates a non-incremental propagator which does not react to fine events but simply calls a coarse propagation any time a variable in vars has changed. This propagator has a regular (linear) priority.

Parameters:

vars - variables of the propagator. Their modification will trigger filtering

Method Detail

addVariable

@SafeVarargs
protected final void addVariable(V... nvars)

Enlarges the variable scope of this propagator Should not be called by the user.

Parameters:

nvars - variables to be added to this propagator

defineIn

public void defineIn(Constraint c)

Informs this propagator the (unique) constraint it filters. The constraint reference will be overwritten in case of reification. Should not be called by the user.

Parameters:

c - the constraint containing this propagator

getPropagationConditions

protected int getPropagationConditions(int vIdx)

Return the specific mask indicating the variable events on which this Propagator object can react.
Checks are made applying bitwise AND between the mask and the event. Reacts to any kind of event by default.

Parameters:

vIdx - index of the variable within the propagator

Returns:

int composed of REMOVE and/or INSTANTIATE and/or DECUPP and/or INCLOW

propagate

public abstract void propagate(int evtmask)
                        throws ContradictionException

Call the main filtering algorithm to apply to the Domain of the Variable objects. It considers the current state of this objects to remove some values from domains and/or instantiate some variables. Calling this method is done from 2 (and only 2) steps:
- at the initial propagation step,
- when involved in a reified constraint.
It should initialized the internal data structure and apply filtering algorithm from scratch.

Parameters:

evtmask - type of propagation event this must consider.

Throws:

ContradictionException - when a contradiction occurs, like domain wipe out or other incoherencies.

advise

public boolean advise(int idxVarInProp,
             int mask)

Advise a propagator of a modification occurring on one of its variables, and decide if this should be scheduled. At least, this method SHOULD check the propagation condition of the event received. In addition, this method can be used to update internal state of this. This method can returns true even if the propagator is already scheduled.

Parameters:

idxVarInProp - index of the modified variable

mask - modification event mask

Returns:

true if this should be scheduled, false otherwise.

propagate

public void propagate(int idxVarInProp,
             int mask)
               throws ContradictionException

Incremental filtering algorithm defined within the Propagator, called whenever the variable of index idxVarInProp has changed. This method calls a CUSTOM_PROPAGATION (coarse-grained) by default.

This method should be overridden if the argument reactToFineEvt is set to true in the constructor. Otherwise, it executes propagate(PropagatorEventType.CUSTOM_PROPAGATION.getStrengthenedMask());

Parameters:

idxVarInProp - index of the variable var in this

mask - type of event

Throws:

ContradictionException - if a contradiction occurs

forcePropagate

public final void forcePropagate(PropagatorEventType evt)
                          throws ContradictionException

Schedules a coarse propagation to filter all variables at once.

Add the coarse event recorder into the engine

Parameters:

evt - event type

Throws:

ContradictionException

setActive

public void setActive()

informs that this propagator is now active. Should not be called by the user.

setReifiedTrue

public void setReifiedTrue()

informs that this reified propagator must hold. Should not be called by the user.

setReifiedSilent

public void setReifiedSilent()

informs that this reified propagator may not hold. Should not be called by the user.

setPassive

public void setPassive()

informs that this propagator is now passive : it holds but no further filtering can occur, so it is useless to propagate it. Should not be called by the user.

isEntailed

public abstract ESat isEntailed()

Check wether this is entailed according to the current state of its internal structure. At least, should check the satisfaction of this (when all is instantiated).

Returns:

ESat.TRUE if entailed, ESat.FALSE if not entailed, ESat.UNDEFINED if unknown

isCompletelyInstantiated

public boolean isCompletelyInstantiated()

Returns:

true iff all this propagator's variables are instantiated

incNbPendingEvt

public void incNbPendingEvt()

informs that a new fine event has to be treated. Should not be called by the user.

decNbPendingEvt

public void decNbPendingEvt()

informs that a fine event has been treated. Should not be called by the user.

flushPendingEvt

public void flushPendingEvt()

informs that all fine events have been treated. Should not be called by the user.

arity

public int arity()

Returns:

the number of uninstantiated variables

dynPriority

public int dynPriority()

contradiction

public void contradiction(Variable variable,
                 String message)
                   throws ContradictionException

Throws a contradiction exception based on

Parameters:

variable - involved variable

message - detailed message

Throws:

ContradictionException - expected behavior

compareTo

public int compareTo(Propagator o)

Specified by:

compareTo in interface Comparable<Propagator>

getId

public int getId()

Specified by:

getId in interface Identity

getSolver

public Solver getSolver()

Returns:

the solver this propagator is defined in

hashCode

public int hashCode()

Overrides:

hashCode in class Object

getNbPendingEvt

public int getNbPendingEvt()

Returns:

the number of fine events which have not been treated yet

getVar

public final V getVar(int i)

Returns the element at the specified position in this internal list of V objects.

Parameters:

i - index of the element

Returns:

a V object

getVars

public final V[] getVars()

Returns:

the variable set this propagator holds on. Note that variable multiple occurrence may have lead to variable duplications (i.e. the creation of new variable)

getVIndices

public int[] getVIndices()

Returns:

the index of the propagator within its variables

setVIndices

public void setVIndices(int idx,
               int val)

Changes the index of a variable in this propagator. This method should not be called by the user.

Parameters:

idx - old index

val - new index

getNbVars

public final int getNbVars()

Returns:

the number of variables involved in this.

getConstraint

public final Constraint getConstraint()

Returns:

the constraint including this propagator

getPriority

public final PropagatorPriority getPriority()

Returns:

the priority of this propagator (may influence the order in which propagators are called)

isStateLess

public boolean isStateLess()

Returns:

true iff this propagator is stateless: its initial propagation has not been performed yet

isReifiedAndSilent

public boolean isReifiedAndSilent()

Returns:

true iff this propagator is reified and it is not established yet whether it should hold or not

isActive

public boolean isActive()

Returns:

true iff this propagator is active (it should filter)

isPassive

public boolean isPassive()

Returns:

true iff this propagator is passive. This happens when it is entailed : the propagator still hold but no more filtering can occur

reactToFineEvent

public final boolean reactToFineEvent()

Returns:

true iff the propagator reacts to fine event, that is, it needs to know which variable has been modified and the modification that happened.

toString

public String toString()

Overrides:

toString in class Object

duplicate

public void duplicate(Solver solver,
             gnu.trove.map.hash.THashMap<Object,Object> identitymap)

Duplicate the current propagator. A restriction is that the resolution process should have not begun yet. That's why state of the propagator may not be duplicated.

Parameters:

solver - the target solver

identitymap - a map to ensure uniqueness of objects

why

public boolean why(RuleStore ruleStore,
          IntVar var,
          IEventType evt,
          int value)

Description copied from interface: ICause

Add new rules to the rule store

Specified by:

why in interface ICause

Parameters:

ruleStore - the rule store

var - the modified variable

evt - the undergoing event

value - the value (for REMOVE only)

Returns:

true if at least one rule has been added to the rule store