## org.opencyc.constraintsolver
Class VariableDomainPopulator

    java.lang.Object
      |
      +--org.opencyc.constraintsolver.VariableDomainPopulator

public class VariableDomainPopulator
extends java.lang.Object

`VariableDomainPopulator` object to contain information about variables and applicable rules, and which determines the best rule to populate each variable. For high cardinality variables, which are those variables having a domain size exceeding a high cardinality threshold, the domain population is typically postponed until the forward checking search has instantiated enough other variables so that the high cardinality variable's domain is more efficiently obtained from the KB.

Author:
  Stephen L. Reed

  Copyright 2001 Cycorp, Inc., license is open source GNU LGPL.

  the license

  www.opencyc.org

  OpenCyc at SourceForge

  THIS SOFTWARE AND KNOWLEDGE BASE CONTENT ARE PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OPENCYC ORGANIZATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE AND KNOWLEDGE BASE CONTENT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

See Also:
  `UnitTest#testConstraintProblem`

Field Summary
`protected java.util.ArrayList` `candidateVariablePopulators` List of `VariablePopulation` objects used to determine the best domain population rule for each variable.
`protected ConstraintProblem` `constraintProblem` Reference to the parent `ConstraintProblem` object.
`protected java.util.ArrayList` `constraintRules` Reference to the parent list of constraint rules.
`static int` `DEFAULT_DOMAIN_SIZE_THRESHOLD` The default value of the variable value domain size beyond which the initial values are not all fetched from the KB.
`protected java.util.ArrayList` `domainPopulationRules` Reference to the parent list of domain populating constraint rules.
`protected int` `domainSizeThreshold` The value of the variable value domain size beyond which the initial values are not all fetched from the KB.
`protected ValueDomains` `valueDomains` Reference to the parent `ValueDomains` object.
`protected java.util.HashMap` `variableDomainPopulators` variable --> VariableDomainPopulator
`protected int` `verbosity` Sets verbosity of the constraint solver output.

Constructor Summary
`VariableDomainPopulator(ConstraintProblem constraintProblem)` Constructs a new `VariableDomainPopulator` object.

Method Summary
`void` `add(VariablePopulationItem variablePopulationItem)` Adds the given `VariablePopulationItem` object to the list of variable populator items.
`int` `getDomainSize(CycVariable cycVariable)` Gets the domain size of the high cardinality variable.
`ConstraintRule` `getPopulatingRule(CycVariable cycVariable)` Gets the domain-populating `ConstraintRule` of the high cardinality variable.
`void` `initializeDomain(VariablePopulationItem variablePopulationItem)` Initializes the value domain for each variable.
`boolean` `isPopulatingRule(ConstraintRule rule, CycVariable cycVariable)` Returns `true` iff the given `ConstraintRule` was used to populate the domain of the given high cardinality variable.
`boolean` `isPostponedHighCardinalityDomain(CycVariable cycVariable)` Returns `true` iff this variable's domain is too large for efficient processing.
`void` `populateDomains()` Determines the best domain population rule to populate each constraint problem variable, and populates those which do not exceed the domain size threshold.
`protected void` `populateDomainViaQuery(ConstraintRule rule, CycVariable cycVariable)` Populates the domain by asking a query.
`protected void` `populatePostponedDomain(CycVariable variable)` Populates the domain of an postponed high cardinality variable, using the previously determined best value domain population rule.
`void` `setDomainSizeThreshold(int domainSizeThreshold)` Sets the domain size threshold, beyond which the population of a variable's domain is typically postponed until the forward checking search.
`void` `setPopulatingRule(CycVariable cycVariable, ConstraintRule rule)` Sets the domain-populating `ConstraintRule` of the high cardinality variable.
`void` `setVerbosity(int verbosity)` Sets verbosity of the constraint solver output.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### constraintProblem

    protected ConstraintProblem constraintProblem

  Reference to the parent `ConstraintProblem` object.

### valueDomains

    protected ValueDomains valueDomains

  Reference to the parent `ValueDomains` object.

### domainPopulationRules

    protected java.util.ArrayList domainPopulationRules

  Reference to the parent list of domain populating constraint rules.

### constraintRules

    protected java.util.ArrayList constraintRules

  Reference to the parent list of constraint rules.

### candidateVariablePopulators

    protected java.util.ArrayList candidateVariablePopulators

  List of `VariablePopulation` objects used to determine the best domain population rule for each variable.

### DEFAULT_DOMAIN_SIZE_THRESHOLD

    public static final int DEFAULT_DOMAIN_SIZE_THRESHOLD

  The default value of the variable value domain size beyond which the initial values are not all fetched from the KB.

### domainSizeThreshold

    protected int domainSizeThreshold

  The value of the variable value domain size beyond which the initial values are not all fetched from the KB.

### variableDomainPopulators

    protected java.util.HashMap variableDomainPopulators

  variable --> VariableDomainPopulator

### verbosity

    protected int verbosity

  Sets verbosity of the constraint solver output. 0 --> quiet ... 9 -> maximum diagnostic input.

Constructor Detail

### VariableDomainPopulator

    public VariableDomainPopulator(ConstraintProblem constraintProblem)

  Constructs a new `VariableDomainPopulator` object.

Method Detail

### add

    public void add(VariablePopulationItem variablePopulationItem)

  Adds the given `VariablePopulationItem` object to the list of variable populator items. Each item contains a variable, an applicable rule, and the number of values that rule would yield if asked in the KB.

### populateDomains

    public void populateDomains()
                         throws java.io.IOException,
                                CycApiException

  Determines the best domain population rule to populate each constraint problem variable, and populates those which do not exceed the domain size threshold.

### isPostponedHighCardinalityDomain

    public boolean isPostponedHighCardinalityDomain(CycVariable cycVariable)

  Returns `true` iff this variable's domain is too large for efficient processing. The constraint solver will employ other rules to populate domain values via OpenCyc KB queries.
  Parameters:
    `cycVariable` - the variable under consideration
  Returns:
    `true` iff this variable's domain is too large for efficient processing

### setVerbosity

    public void setVerbosity(int verbosity)

  Sets verbosity of the constraint solver output. 0 --> quiet ... 9 -> maximum diagnostic input.
  Parameters:
    `verbosity` - 0 --> quiet ... 9 -> maximum diagnostic input

### isPopulatingRule

    public boolean isPopulatingRule(ConstraintRule rule,
                                    CycVariable cycVariable)

  Returns `true` iff the given `ConstraintRule` was used to populate the domain of the given high cardinality variable.
  Parameters:
    `rule` - the rule under consideration
    `cycVariable` - the variable under consideration
  Returns:
    `true` iff the given `ConstraintRule` was used to populate the domain of the given high cardinality variable

### setDomainSizeThreshold

    public void setDomainSizeThreshold(int domainSizeThreshold)

  Sets the domain size threshold, beyond which the population of a variable's domain is typically postponed until the forward checking search.
  Parameters:
    `domainSizeThreshold` - domain size threshold

### getDomainSize

    public int getDomainSize(CycVariable cycVariable)

  Gets the domain size of the high cardinality variable.
  Parameters:
    `cycVariable` - the variable under consideration
  Returns:
    `int` the domain size of the high cardinality variable

### setPopulatingRule

    public void setPopulatingRule(CycVariable cycVariable,
                                  ConstraintRule rule)

  Sets the domain-populating `ConstraintRule` of the high cardinality variable.
  Parameters:
    `cycVariable` - the high-cardinality variable under consideration

### getPopulatingRule

    public ConstraintRule getPopulatingRule(CycVariable cycVariable)

  Gets the domain-populating `ConstraintRule` of the high cardinality variable.
  Parameters:
    `cycVariable` - the variable under consideration
  Returns:
    the domain-populating `ConstraintRule` of the high cardinality variable

### populateDomainViaQuery

    protected void populateDomainViaQuery(ConstraintRule rule,
                                          CycVariable cycVariable)
                                   throws java.io.IOException,
                                          CycApiException

  Populates the domain by asking a query.
  Parameters:
    `rule` - the query to asked in the KB
    `cycVariable` - the variable whose value domain is to be populated by the results of the query

### initializeDomain

    public void initializeDomain(VariablePopulationItem variablePopulationItem)
                          throws java.io.IOException,
                                 CycApiException

  Initializes the value domain for each variable.
  Parameters:
    `variablePopulationItem` - the `VariablePopulationItem` object which contains the variable and its domain populating rule

### populatePostponedDomain

    protected void populatePostponedDomain(CycVariable variable)
                                    throws java.io.IOException,
                                           CycApiException

  Populates the domain of an postponed high cardinality variable, using the previously determined best value domain population rule.
  Parameters:
    `variable` - the variable whose value domain is to be populated