Package ec.rule

# Class RuleSet

java.lang.Object
ec.rule.RuleSet

All Implemented Interfaces:
  `Prototype`, `Setup`, `Serializable`, `Cloneable`

public class RuleSet extends Object implements Prototype
RuleSet is a set of Rules, implemented straightforwardly as an arbitrary-length array of Rules. A RuleIndividual is simply a list of RuleSets. Most typically, a RuleIndividual contains a single RuleSet, containing a variety of Rules. RuleSets contain many useful subsetting and modification functions which you can use in breeding operators which modify RuleSets and Rules.

Besides the Rules themselves, the only thing else a RuleSet contains is a pointer to a corresponding RuleSetConstraints object, which holds all of its modification parameters. See RuleSetConstraints for a description of these parameters.

In addition to serialization for checkpointing, RuleSets may read and write themselves to streams in three ways.

- writeRuleSet(...,DataOutput)/readRuleSet(...,DataInput) This method transmits or receives a RuleSet in binary. It is the most efficient approach to sending RuleSets over networks, etc. The default versions of writeRuleSet/readRuleSet reads/writes out the number of rules, then calls read/writeRule(...) on each Rule. Override this if you need more functionality.
- printRuleSet(...,PrintWriter)/readRuleSet(...,LineNumberReader) This approach transmits or receives a RuleSet in text encoded such that the RuleSet is largely readable by humans but can be read back in 100% by ECJ as well. To do this, these methods will typically encode numbers using the `ec.util.Code` class. These methods are mostly used to write out populations to files for inspection, slight modification, then reading back in later on. readRuleSet reads in the number of rules, then calls readRule(...) on each new Rule. printRuleSet writes out the number of rules, then calls printrule(...) on each new Rule. Again, override this if you need more functionality.
- printRuleSetForHumans(...,PrintWriter) This approach prints a RuleSet in a fashion intended for human consumption only. printRuleSetForHumans prints out the number of rules, then calles printRuleForHumans on each Rule in turn. You may wish to override this to provide more information instead. You should handle one of these methods properly to ensure RuleSets can be printed by ECJ.

Parameters

base.`constraints` string | (name of the rule set constraints)

Default Base
rule.ruleset

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `byte`
  `constraints`
  An index to a RuleSetConstraints
  `static final String`
  `N_RULES`
  The message to appear when printing the rule set
  `int`
  `numRules`
  How many rules are there used in the rules array
  `static final String`
  `P_CONSTRAINTS`
  The constraint for the rule set
  `static final String`
  `P_RULESET`
  `Rule[]`
  `rules`
  The rules in the rule set

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RuleSet()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addRandomRule(EvolutionState state, int thread)`
  Add a random rule to the rule set
  `void`
  `addRule(Rule rule)`
  Add a rule directly to the rule set.
  `Object`
  `clone()`
  Creates a new individual cloned from a prototype, and suitable to begin use in its own evolutionary context.
  `final RuleSetConstraints`
  `constraints(RuleInitializer initializer)`
  `void`
  `copyNoClone(RuleSet other)`
  Clears out existing rules, and loads the rules from the other ruleset without cloning them.
  `Parameter`
  `defaultBase()`
  Returns the default base for this prototype.
  `boolean`
  `equals(Object _other)`
  `int`
  `hashCode()`
  The hash code for the rule set.
  `void`
  `join(RuleSet other)`
  Makes a copy of the rules in another RuleSet and adds the rule copies.
  `void`
  `mutate(EvolutionState state, int thread)`
  Mutates rules in the RuleSet independently with the given probability.
  `int`
  `numRules()`
  How many rules are there used in the rules array
  `void`
  `postprocessRules(EvolutionState state, int thread)`
  Should be called by pipelines to "fix up" the rulesets after they have been mutated or crossed over.
  `void`
  `preprocessRules(EvolutionState state, int thread)`
  Should be called by pipelines to "fix up" the rulesets before they have been mutated or crossed over.
  `void`
  `printRuleSet(EvolutionState state, int log)`
  Prints the rule set such that the computer can read it later
  `void`
  `printRuleSet(EvolutionState state, int log, int verbosity)`
  Prints the rule set such that the computer can read it later
  `void`
  `printRuleSet(EvolutionState state, PrintWriter writer)`
  Prints the rule set such that the computer can read it later
  `void`
  `printRuleSetForHumans(EvolutionState state, int log)`
  Prints out the rule set in a readable fashion.
  `void`
  `printRuleSetForHumans(EvolutionState state, int log, int verbosity)`
  Prints out the rule set in a readable fashion.
  `void`
  `randomizeRulesOrder(EvolutionState state, int thread)`
  Randomizes the order of the rules in the rule set.
  `void`
  `readRuleSet(EvolutionState state, DataInput dataInput)`
  Reads RuleSets in from a binary stream
  `void`
  `readRuleSet(EvolutionState state, LineNumberReader reader)`
  Reads the rule set
  `Rule`
  `removeRandomRule(EvolutionState state, int thread)`
  Removes a randomly-chosen rule from the rule set and returns it.
  `Rule`
  `removeRule(int index)`
  Removes a rule from the rule set and returns it.
  `void`
  `reset(EvolutionState state, int thread)`
  A reset method for randomly reinitializing the RuleSet
  `void`
  `setup(EvolutionState state, Parameter base)`
  Sets up the object by reading it from the parameters stored in state, built off of the parameter base base.
  `RuleSet[]`
  `split(int[] points, RuleSet[] sets)`
  Splits the rule set into n pieces, according to points, which *must* be sorted.
  `RuleSet[]`
  `split(EvolutionState state, int thread, RuleSet[] sets)`
  Splits the rule set into a number of disjoint rule sets, copying the rules and adding them to the sets as appropriate.
  `RuleSet[]`
  `splitIntoTwo(EvolutionState state, int thread, RuleSet[] sets, double prob)`
  Splits the rule set into a two disjoint rule sets, copying the rules and adding them to the sets as appropriate.
  `void`
  `writeRuleSet(EvolutionState state, DataOutput dataOutput)`
  Writes RuleSets out to a binary stream

  ### Methods inherited from class java.lang.Object

  `finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### N_RULES

    public static final String N_RULES
    The message to appear when printing the rule set
    See Also:
      - Constant Field Values

  - ### P_RULESET

    public static final String P_RULESET
    See Also:
      - Constant Field Values

  - ### P_CONSTRAINTS

    public static final String P_CONSTRAINTS
    The constraint for the rule set
    See Also:
      - Constant Field Values

  - ### constraints

    public byte constraints
    An index to a RuleSetConstraints

  - ### rules

    public Rule[] rules
    The rules in the rule set

  - ### numRules

    public int numRules
    How many rules are there used in the rules array

- ## Constructor Details

  - ### RuleSet

    public RuleSet()

- ## Method Details

  - ### constraints

    public final RuleSetConstraints constraints(RuleInitializer initializer)

  - ### clone

    public Object clone()
    Description copied from interface: `Prototype`
    Creates a new individual cloned from a prototype, and suitable to begin use in its own evolutionary context.

    Typically this should be a full "deep" clone. However, you may share certain elements with other objects rather than clone hem, depending on the situation:

    - If you hold objects which are shared with other instances, don't clone them.
    - If you hold objects which must be unique, clone them.
    - If you hold objects which were given to you as a gesture of kindness, and aren't owned by you, you probably shouldn't clone them.
    - DON'T attempt to clone: Singletons, Cliques, or Populations, or Subpopulation.
    - Arrays are not cloned automatically; you may need to clone an array if you're not sharing it with other instances. Arrays have the nice feature of being copyable by calling clone() on them.

    Implementations.

    - If no ancestor of yours implements clone(), and you have no need to do clone deeply, and you are abstract, then you should not declare clone().
    - If no ancestor of yours implements clone(), and you have no need to do clone deeply, and you are not abstract, then you should implement it as follows:

      ``

           public Object clone()
               {
               try
                   {
                   return super.clone();
                   }
               catch ((CloneNotSupportedException e)
                   { throw new InternalError(); } // never happens
               }

    - If no ancestor of yours implements clone(), but you need to deep-clone some things, then you should implement it as follows:

      ``

           public Object clone()
               {
               try
                   {
                   MyObject myobj = (MyObject) (super.clone());

                   // put your deep-cloning code here...
                   }
               catch ((CloneNotSupportedException e)
                   { throw new InternalError(); } // never happens
               return myobj;
               }

    - If an ancestor has implemented clone(), and you also need to deep clone some things, then you should implement it as follows:

      ``

           public Object clone()
               {
               MyObject myobj = (MyObject) (super.clone());

               // put your deep-cloning code here...

               return myobj;
               }

    Specified by:
      `clone` in interface `Prototype`
    Overrides:
      `clone` in class `Object`

  - ### numRules

    public int numRules()
    How many rules are there used in the rules array

  - ### reset

    public void reset(EvolutionState state, int thread)
    A reset method for randomly reinitializing the RuleSet

  - ### mutate

    public void mutate(EvolutionState state, int thread)
    Mutates rules in the RuleSet independently with the given probability.

  - ### preprocessRules

    public void preprocessRules(EvolutionState state, int thread)
    Should be called by pipelines to "fix up" the rulesets before they have been mutated or crossed over. Override this method to do so.

  - ### postprocessRules

    public void postprocessRules(EvolutionState state, int thread)
    Should be called by pipelines to "fix up" the rulesets after they have been mutated or crossed over. Override this method to do so.

  - ### randomizeRulesOrder

    public void randomizeRulesOrder(EvolutionState state, int thread)
    Randomizes the order of the rules in the rule set. It is helpful when the order of rule is important for the conflict resolution.

  - ### addRandomRule

    public void addRandomRule(EvolutionState state, int thread)
    Add a random rule to the rule set

  - ### addRule

    public void addRule(Rule rule)
    Add a rule directly to the rule set. Does not copy the rule.

  - ### removeRule

    public Rule removeRule(int index)
    Removes a rule from the rule set and returns it. If index is out of bounds, then this method returns null. The rules are shifted down --- thus this is O(n).

  - ### removeRandomRule

    public Rule removeRandomRule(EvolutionState state, int thread)
    Removes a randomly-chosen rule from the rule set and returns it. If there are no rules to remove, this method returns null.

  - ### join

    public void join(RuleSet other)
    Makes a copy of the rules in another RuleSet and adds the rule copies.

  - ### copyNoClone

    public void copyNoClone(RuleSet other)
    Clears out existing rules, and loads the rules from the other ruleset without cloning them. Mostly for use if you create temporary rulesets (see for example RuleCrossoverPipeline)

  - ### split

    public RuleSet[] split(int[] points, RuleSet[] sets)
    Splits the rule set into n pieces, according to points, which *must* be sorted. The rules in each piece are cloned and added to the equivalent set. Sets must be already allocated. sets.length must be 1+ points.length. Comment: This function appends the split rulesets to the existing rulesets already in sets.

  - ### split

    public RuleSet[] split(EvolutionState state, int thread, RuleSet[] sets)
    Splits the rule set into a number of disjoint rule sets, copying the rules and adding them to the sets as appropriate. Each rule independently throws a die to determine which ruleset it will go into. Sets must be already allocated. Comment: This function appends the split rulesets to the existing rulesets already in sets.

  - ### splitIntoTwo

    public RuleSet[] splitIntoTwo(EvolutionState state, int thread, RuleSet[] sets, double prob)
    Splits the rule set into a two disjoint rule sets, copying the rules and adding them to the sets as appropriate. The value prob is the probability that an element will land in the first set. Sets must be already allocated. Comment: This function appends the split rulesets to the existing rulesets already in sets.

  - ### printRuleSetForHumans

    public void printRuleSetForHumans(EvolutionState state, int log)
    Prints out the rule set in a readable fashion.

  - ### printRuleSetForHumans

    public void printRuleSetForHumans(EvolutionState state, int log, int verbosity)
    Prints out the rule set in a readable fashion.

  - ### printRuleSet

    public void printRuleSet(EvolutionState state, int log)
    Prints the rule set such that the computer can read it later

  - ### printRuleSet

    public void printRuleSet(EvolutionState state, int log, int verbosity)
    Prints the rule set such that the computer can read it later

  - ### printRuleSet

    public void printRuleSet(EvolutionState state, PrintWriter writer)
    Prints the rule set such that the computer can read it later

  - ### readRuleSet

    public void readRuleSet(EvolutionState state, LineNumberReader reader) throws IOException
    Reads the rule set
    Throws:
      `IOException`

  - ### writeRuleSet

    public void writeRuleSet(EvolutionState state, DataOutput dataOutput) throws IOException
    Writes RuleSets out to a binary stream
    Throws:
      `IOException`

  - ### readRuleSet

    public void readRuleSet(EvolutionState state, DataInput dataInput) throws IOException
    Reads RuleSets in from a binary stream
    Throws:
      `IOException`

  - ### defaultBase

    public Parameter defaultBase()
    Description copied from interface: `Prototype`
    Returns the default base for this prototype. This should generally be implemented by building off of the static base() method on the DefaultsForm object for the prototype's package. This should be callable during setup(...).
    Specified by:
      `defaultBase` in interface `Prototype`

  - ### setup

    public void setup(EvolutionState state, Parameter base)
    Description copied from interface: `Prototype`
    Sets up the object by reading it from the parameters stored in state, built off of the parameter base base. If an ancestor implements this method, be sure to call super.setup(state,base); before you do anything else.

    For prototypes, setup(...) is typically called once for the prototype instance; cloned instances do not receive the setup(...) call. setup(...) may be called more than once; the only guarantee is that it will get called at least once on an instance or some "parent" object from which it was ultimately cloned.

    Specified by:
      `setup` in interface `Prototype`
    Specified by:
      `setup` in interface `Setup`

  - ### hashCode

    public int hashCode()
    The hash code for the rule set. This isn't a very good hash code, but it has the benefit of not being O(n lg n) -- otherwise, we'd have to do something like sort the rules in the individual first and then do an ordered hash code of some sort, ick.
    Overrides:
      `hashCode` in class `Object`

  - ### equals

    public boolean equals(Object _other)
    Overrides:
      `equals` in class `Object`