Class Store

java.lang.Object
org.jacop.core.Store

public class Store extends Object
It is an abstract class to describe all necessary functions of any store.
Version:
4.10
  • Field Details

    • failException

      public static final FailException failException
      It stores standard fail exception used when empty domain encountered.
    • debug

      public static final boolean debug
      It specifies if some debugging information is printed.
      See Also:
    • changed

      public SimpleHashSet<Constraint>[] changed
      It stores constraints scheduled for reevaluation. It does not register constraints which are already scheduled for reevaluation.
    • changeHistory4BooleanVariables

      public BooleanVar[] changeHistory4BooleanVariables
      It stores boolean variables as soon as they change (become grounded or number of constraints being attached is changed). Later each level remembers the part of the array which contains variables changed at this level (efficient backtracking).
    • removeLevelListeners

      public Set<Stateful> removeLevelListeners
      More advanced constraints may require to be informed of a backtrack to be able to recover the older versions of the data structures. For example, the constraints can clear their queue of changed variables if a backtracks has occurred. It holds the list of constraints which want to be informed about level being removed before it has actually began.
    • removeLevelLateListeners

      public Set<RemoveLevelLate> removeLevelLateListeners
      More advanced constraints may require to be informed of a backtrack to be able to recover the older versions of the data structures. For example, the constraints can clear their queue of changed variables if a backtracks has occurred. It holds the list of constraints which want to be informed about level being removed after it has been removed.
    • auxilaryVariables

      public List<Var> auxilaryVariables
      It contains all auxilary variables created by decomposable constraints. They have to be grounded by search for a solution to be valid.
    • currentConstraint

      public Constraint currentConstraint
      It stores constraint which is currently re-evaluated.
    • recentlyFailedConstraint

      public Constraint recentlyFailedConstraint
      It stores constraint that has recently failed during store.consistency() execution.
    • currentQueue

      public int currentQueue
      It stores current queue, which is being evaluated.
    • description

      public String description
      It specifies long description of the store.
    • id

      public String id
      Id string of the store.
    • level

      public int level
      It specifies the time point in the search. Every time this variable is increased a new layer of changes to the variables are recorded. This is the most important variable. It is assumed that initially this value is equal to zero. Use setLevel function if you want to play with it.
    • mutableVariables

      protected List<MutableVar> mutableVariables
      A mutable variable is a special variable which can change value during the search. In the event of backtracks the old value must be restored, therefore the store keeps information about all mutable variables.
    • propagationHasOccurred

      public boolean propagationHasOccurred
      This variable specifies if there was a new propagation. Any change to any variable will setup this variable to true. Usefull variable to discover the idempodence of the consistency propagator.
    • numberOfConstraints

      protected int numberOfConstraints
      It stores the number of constraints which were imposed to the store.
    • pointer4GroundedBooleanVariables

      public TimeStamp<Integer> pointer4GroundedBooleanVariables
      It specifies the current pointer to put next changed boolean variable. It has to be maintained manually (within removeLevel function).
    • queueNo

      public int queueNo
      It stores number of queues used in this store. It has to be at least 1. No constraint can be imposed with queue index greater or equal this number.
    • raiseLevelBeforeConsistency

      public boolean raiseLevelBeforeConsistency
      Some constraints maintain complex data structure based on function recentDomainPruning of a variable, this function for proper functioning requires to raise store level after imposition and before any changes to variables of this constraint occur. This flag is set by constraints at imposition stage.
    • variableWeightManagement

      public boolean variableWeightManagement
      It specifies if the weight of variables which are in the scope of the failure constraint should be increased.
    • removeDebug

      final boolean removeDebug
      It switches on/off debuging of remove level facilities.
      See Also:
    • size

      protected int size
      Number of variables stored within a store.
    • numberConsistencyCalls

      public long numberConsistencyCalls
      Number of calls to consistency methods of constraints.
    • strict

      public boolean strict
      It indicates that consistency function should immediately return fail if last inconsistency was not followed yet by removeLevel function.
    • isLastConsistencyFailure

      public boolean isLastConsistencyFailure
      This flag is set to true when consistency function of the store encounters failure.
    • timeStamps

      protected List<Stateful> timeStamps
      TimeStamp variable is a simpler version of a mutable variable. It is basically a stack. During search items are push onto the stack. If the search backtracks then the old values can be simply restored. Simple and efficient way for getting mutable variable functionality for simple data types.
    • watchedConstraints

      public Map<Var,Set<Constraint>> watchedConstraints
      This keeps information about watched constraints by given variable. Watched constraints are active all the time. Use this with care and do not be surprised if some constraints stay longer than you expect. It can be directly manipulated in any way (including setting to null if no watched constraints are being in the queue system).
    • replacements

      private Map<Class<? extends Constraint>,Set<Replaceable>> replacements
      It stores all the active replacements of constraints that are being applied upon constraint imposition. It makes it possible to replace constraints into other constraints. It can be very useful for efficiency or testing purposes.
    • constraintAFCManagement

      boolean constraintAFCManagement
      Variables for accumulated failure count (AFC) for constraints. constraintAFCManagement- opens AFC menagement decay- decay factor allConstraints- all constraints in the store
    • allConstraints

      Set<Constraint> allConstraints
    • decay

      double decay
    • variableActivityManagement

      boolean variableActivityManagement
      Variables for pruning count (variable activity) for constraints. variableActivityManagement- opens activity menagement variablePrunnedConstraints- all constraints in the store
    • variablesPrunned

      Set<Var> variablesPrunned
    • seed

      static long seed
      It specifies the seed for random number generators.
    • seedPresent

      static boolean seedPresent
    • variableIdPrefix

      protected String variableIdPrefix
      The prefix of any variable which was noname.
    • vars

      public Var[] vars
      It stores integer variables created within a store.
    • trailManager

      public BacktrackableManager trailManager
      It allows to manage information about changed variables in efficient/specialized/tailored manner.
    • variablesHashMap

      public Map<String,Var> variablesHashMap
      It may be used for faster retrieval of variables given their id. However, by default this variable is not created to reduce memory consumption. If it exists then it will be used by functions looking for a variable given the name.
    • sparseSet

      public SparseSet sparseSet
      It is used by Extensional MDD constraints. It is to represent G_yes.
    • sparseSetSize

      public int sparseSetSize
      It is used by Extensional MDD constraints. It is to represent the size of G_yes.
  • Constructor Details

    • Store

      public Store()
      It specifies the default constructor of the store.
    • Store

      public Store(int size)
      It specifies the constructor of the store, which allows to decide what is the initial size of the Variable list.
      Parameters:
      size - specifies the initial number of variables.
  • Method Details

    • deregisterWatchedLiteralConstraint

      public void deregisterWatchedLiteralConstraint(Var v, Constraint c)
      Variable given as a parameter no longer watches constraint given as parameter. This function will be called when watch is being moved from one variable to another.
      Parameters:
      v - variable at which constraint is no longer watching.
      c - constraint which is no longer watched by given variable.
    • deregisterWatchedLiteralConstraint

      public void deregisterWatchedLiteralConstraint(Constraint c)
      Watched constraint given as parameter is being removed, no variable will be watching it.
      Parameters:
      c - constraint for which all watches are removed.
    • countWatches

      public int countWatches()
      It returns number of watches which are used to watch constraints.
      Returns:
      returns the number of watches attached to variables.
    • registerWatchedLiteralConstraint

      public void registerWatchedLiteralConstraint(Var v, Constraint c)
      It register variable to watch given constraint. This function is called either by impose function of a constraint or by consistency function of a constraint when watch is being moved.
      Parameters:
      v - variable which is used to watch the constraint.
      c - the constraint being used.
    • clearWatchedConstraint

      public void clearWatchedConstraint()
      It removes all watches to constraints, therefore constraints are no longer watched, no longer part of the model.
    • addChanged

      public void addChanged(Constraint c)
      This function schedules given constraint for re-evaluation. This function will most probably be rarely used as constraints require reevaluation only when a variable changes.
      Parameters:
      c - constraint which needs reevaluation.
    • addChanged

      public void addChanged(Var var, int pruningEvent, int info)
      This function schedules all attached (not yet satisfied constraints) for given variable for re-evaluation. This function must add all attached constraints for reevaluation but it will do it any order which suits it.
      Parameters:
      var - variable for which some pruning event has occurred.
      pruningEvent - specifies the type of the pruning event.
      info - it specifies detailed information about the change of the variable domain. the inputs of the currentConstraint in the manner that would validate another execution.
    • clearChanged

      public void clearChanged()
      It clears the queue of constraints which need to be reevaluated usefull if different scheme propagation scheme needs to be implemented.
    • consistency

      public boolean consistency()
      This function computes the consistency function. It evaluates all constraints which are in the changed queue.
      Returns:
      returns true if all constraints which were in changed queue are consistent, false otherwise.
    • countConstraint

      public void countConstraint()
      This function is called when a counter of constraints should be increased. It is most probable that this function will called from the impose function of the constraint.
    • countConstraint

      public void countConstraint(int n)
      This function is called when a counter of constraints should be increased by given value. If for some reason some constraints should be counted as multiple ones than this function could be called.
      Parameters:
      n - integer by which the counter of constraints should be increased.
    • findVariable

      public Var findVariable(String id)
      This function looks for a variable with given id. It will first check the existence of a hashmap variablesHashMap to get the variable from the hashmap in constant time. Only if the variable was not found or hashmap object was not created a linear algorithm scanning through the whole list of variables will be employed.
      Parameters:
      id - unique identifier of the variable.
      Returns:
      reference to a variable with the given id.
    • getCurrentConstraint

      public Constraint getCurrentConstraint()
      This function returns the constraint which is currently reevaluated. It is an easy way to discover which constraint caused a failure right after the inconsistency is signaled.
      Returns:
      constraint for which consistency method is being executed.
    • getDescription

      public String getDescription()
      This function returns the long description of the store.
      Returns:
      store description.
    • getFirstChanged

      public Constraint getFirstChanged()
      This function returns the constraint scheduled for re-evaluation. It returns constraints based on criteria first-in-first out. It is simple, easy, fair, and efficient way of getting constraints for reevaluation. The constraint is _removed_ from the queue, since it is assumed that they are reevaluated right away.
      Returns:
      first constraint which is being marked as the one which needs to be checked for consistency.
    • getName

      public String getName()
      This function returns the id of the store.
      Returns:
      id of store.
    • getVariableIdPrefix

      public String getVariableIdPrefix()
      This function returns the prefix of the automatically generated names for noname variables.
      Returns:
      he prefix of the automatically generated names for noname variables.
    • impose

      public void impose(Constraint c)
      This function imposes a constraint to a store. The constraint is scheduled for evaluation for the next store consistency call. Therefore, the constraint is added to queue of changed constraints.
      Parameters:
      c - constraint to be imposed.
    • impose

      public void impose(Constraint c, int queueIndex)
      This function imposes a constraint to a store. The constraint is scheduled for evaluation for the next store consistency call. Therefore, the constraint is added to queue of changed constraints.
      Parameters:
      c - constraint to be added to specified queue.
      queueIndex - specifies index of the queue for a constraint.
    • imposeWithConsistency

      public void imposeWithConsistency(Constraint c) throws FailException
      In some special cases it may be beneficial to compute consistency of constraint store immediately after the constraint is imposed. This function will impose a constraint and call the consistency function of the store immediately.
      Parameters:
      c - constraint to be imposed.
      Throws:
      FailException - failure exception.
    • imposeWithConsistency

      public void imposeWithConsistency(Constraint c, int queueIndex) throws FailException
      In some special cases it may be beneficial to compute consistency of constraint store immediately after the constraint is imposed. This function will impose a constraint and call the consistency function of the store immediately.
      Parameters:
      c - constraint to be imposed.
      queueIndex - constraint priority for evaluation.
      Throws:
      FailException - failure exception.
    • imposeDecomposition

      public <T extends Constraint> void imposeDecomposition(DecomposedConstraint<T> c)
      This function imposes a decomposable constraint to a store. The decomposition is scheduled for evaluation for the next store consistency call. Therefore, the constraints are added to queue of changed constraints.
      Parameters:
      c - constraint to be imposed.
    • imposeDecomposition

      public <T extends Constraint> void imposeDecomposition(DecomposedConstraint<T> c, int queueIndex)
      This function imposes a constraint decomposition to a store. The decomposition constraints are scheduled for evaluation for the next store consistency call. Therefore, the constraints are added to queue of changed constraints.
      Parameters:
      c - constraint to be added to specified queue.
      queueIndex - specifies index of the queue for a constraint.
    • imposeDecompositionWithConsistency

      public <T extends Constraint> void imposeDecompositionWithConsistency(DecomposedConstraint<T> c)
      In some special cases it may be beneficial to compute consistency of constraint store immediately after the decomposed constraint is imposed. This function will impose constraint decomposition and call the consistency function of the store immediately.
      Parameters:
      c - decomposed constraint to be imposed.
    • isGround

      public boolean isGround()
      This function checks if all variables within a store are grounded. It is advised to make sure that after search all variables are grounded.
      Returns:
      true if all variables are singletons, false otherwise.
    • numberConstraints

      public int numberConstraints()
      This function returns the number of constraints.
      Returns:
      number of constraints.
    • print

      public void print()
      This function prints the information of the store to standard output stream.
    • putMutableVar

      public int putMutableVar(MutableVar value)
      Any constraint may have their own mutable variables which can be register at store and then store will be responsible for calling appropriate functions from MutableVar interface to keep the variables consistent with the search.
      Parameters:
      value - MutableVariable to be added and maintained by a store.
      Returns:
      the position of MutableVariable at which it is being stored.
    • putMutableVar

      public int putMutableVar(Stateful value)
      Any entity (for example constraints) may have their own mutable variables (timestamps) which can be register at store and then store will be responsible for calling appropriate functions from TimeStamp class to keep the variables consistent with the search.
      Parameters:
      value - timestamp to be added and maintained by a store.
      Returns:
      the position of timestamp at which it is being stored.
    • putVariable

      public int putVariable(Var var)
      This function is used to register a variable within a store. It will be most probably called from variable constructor. It returns the current position of fdv in a store local data structure.
      Parameters:
      var - variable to be registered.
      Returns:
      position of the variable at which it is being stored.
    • recordBooleanChange

      public void recordBooleanChange(BooleanVar recordedVariable)
      Any boolean variable which is changed must be recorded by store, so it can be restored to the previous state if backtracking is performed.
      Parameters:
      recordedVariable - boolean variable which has changed.
    • recordChange

      public void recordChange(Var recordedVariable)
      Any change of finite domain variable must also be recorded, so intervals denoting changed variables can be updated.
      Parameters:
      recordedVariable - variable which has changed.
    • registerReplacement

      public boolean registerReplacement(Replaceable<? extends Constraint> replacement)
      It makes it possible to register replacement for a particular constraint type.
      Parameters:
      replacement - that is being registered.
      Returns:
      true if replacement has been added and was not already registered, false otherwise.
    • deregisterReplacement

      public boolean deregisterReplacement(Replaceable<? extends Constraint> replacement)
      It makes it possible to deregister the replacement. The constraint that have been already replaced remained replaced.
      Parameters:
      replacement - that is being deregister from within the constraint store.
      Returns:
      true if replacement was present and was deregistered, false otherwise.
    • registerRemoveLevelListener

      public boolean registerRemoveLevelListener(Stateful stateful)
      Any constraint in general may need information what variables have changed since the last time a consistency was called. This function is called just *before* removeLevel method is executed for variables, mutable variables, and timestamps.
      Parameters:
      stateful - constraint which is interested in listening to remove level events.
      Returns:
      true if constraint stateful was watching remove level events.
    • registerRemoveLevelLateListener

      public boolean registerRemoveLevelLateListener(RemoveLevelLate c)
      Any constraint in general may need information what variables have changed since the last time a consistency was called. This function is called just *after* removeLevel method is executed for variables, mutable variables, and timestamps.
      Parameters:
      c - constraint which is no longer interested in listening to remove level events.
      Returns:
      true if constraint c was watching remove level events.
    • removeLevel

      public void removeLevel(int rLevel)
      This important function removes all changes which has been recorded to any variable at given level. Before backtracking to earlier level all levels after earlier level must be removed. The removal order must be reversed to the creation order.
      Parameters:
      rLevel - Store level to be removed.
    • setDescription

      public void setDescription(String description)
      This function sets the long description of the store.
      Parameters:
      description - description of the store
    • setID

      public void setID(String id)
      This function sets the id of the store. This id is used when saving to XML file.
      Parameters:
      id - store id.
    • setLevel

      public void setLevel(int levelSetTo)
      This function allows to proceed with the search, create new layer at which new values for variables will be recorded. This function is also used during backtracking, after removing current level the store can be set to the previous level.
      Parameters:
      levelSetTo - level number to which store is changing to.
    • setVariableIdPrefix

      public void setVariableIdPrefix(String idPrefix)
      This function sets the prefix of the automatically generated names for noname variables.
      Parameters:
      idPrefix - prefix of all variables with automatically generated names.
    • size

      public int size()
      It returns number of variables in a store.
      Returns:
      number of variables in a store.
    • throwFailException

      public void throwFailException(Var x)
      It throws an exception after printing trace information if tracing is switched on.
      Parameters:
      x - variable causing the failure exception.
      Throws:
      FailException - is always thrown.
    • toString

      public String toString()
      This function returns a string a representation of the store. Whatever seems important may be included here.
      Overrides:
      toString in class Object
    • getConstraints

      public Set<Constraint> getConstraints()
    • setAllConstraints

      public void setAllConstraints()
    • setDecay

      public void setDecay(double d)
    • getDecay

      public double getDecay()
    • afcManagement

      public void afcManagement(boolean m)
    • activityManagement

      public void activityManagement(boolean m)
    • updateActivities

      void updateActivities(Constraint constraint)
    • toStringChangedEl

      public String toStringChangedEl()
      This function returns a string representation of the constraints pending for re-evaluation.
      Returns:
      string description of changed constraints.
    • checkInvariants

      public String checkInvariants()
      It checks invariants to see if the execution went smoothly.
      Returns:
      description of the violated invariant, null otherwise.
    • toStringOrderedVars

      public String toStringOrderedVars()
    • setSeed

      public static void setSeed(long s)
    • getSeed

      public static long getSeed()
    • seedPresent

      public static boolean seedPresent()
    • resetSeed

      public static void resetSeed()