hu.birot.OTKit.dataType
Class MapFormExamples

java.lang.Object
  extended by hu.birot.OTKit.dataType.MapFormExamples

public final class MapFormExamples
extends java.lang.Object

Offers a number of static methods returning MapForms.

NB: They may be reconsidered in the future.

See Also:
MapForm

Constructor Summary
MapFormExamples()
           
 
Method Summary
static MapForm composition(MapForm mapform1, MapForm mapform2)
          Composition of two MapForms.
static MapForm equals(java.util.HashMap<Form,FormValuePair[]> hm)
          This static method creates a MapForm based on a HashMap.
static MapForm fromGen(Gen gen)
          Transform a Gen into a MapForm.
static MapForm linearCombination(MapForm mapform1, double factor1, MapForm mapform2, double factor2)
          This static method creates a MapForm by combining two MapForms.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MapFormExamples

public MapFormExamples()
Method Detail

equals

public static final MapForm equals(java.util.HashMap<Form,FormValuePair[]> hm)

This static method creates a MapForm based on a HashMap. The HashMap maps a Form to an array of FormValuePairs. The resulting MapForm will map that Form to the Forms specified in the array, whereas the values in the array specify the weights of the mapping.

The value of hm for key form1 is an array of FormValuePairs. Method MapForm.first(form1) returns the first Form in this array. Method MapForm.next(form1, form2) returns the Form subsequent (successor) to form2 in this array. Method MapForm.random(Form form1, double rnd) returns the "rndth" element, using the values in the FormValuePairs as weights (0 <= rnd <= 1). Method MapForm.all(form1) returns all the forms in the array.

If hm does not contain a mapping from form1, a Form with string value "ERROR: no mapping from "+form1+"." is returned.

Parameters:
hm - HashMap defining the MapForm.
Returns:
A MapForm, as described above.

linearCombination

public static final MapForm linearCombination(MapForm mapform1,
                                              double factor1,
                                              MapForm mapform2,
                                              double factor2)

This static method creates a MapForm by combining two MapForms. The resulting MapForm is the union of mapform1 and mapform2: the new relation maps Form1 to Form2 if and only if at least one of mapform1 and mapform2 does so. The weights in the new relation are the weighted sums of the old relation, with factor1 and factor2 as the weights of the linear combination.

To be more precise, the edges leaving Form1 in mapform1 form a well-ordered set A, and the edges leaving Form1 in mapform2 form the well-ordered set B. The well-formed set of the edges leaving Form1 in the linear combination is factor1 * A + factor2 * B, where multiplication refers to multiplying the weights on each edge by a factor, whereas addition refers to the (non-commutative) addition of well-ordered sets (ordinal numbers).

In particular, the first edge leaving Form1 in the linear combination is the first edge leaving Form1 in mapform1. If no such edge exists, then it is the first edge leaving Form1 in mapform2. If no such edge exists again, then no edge should leave Form1 in the linear combination either.

The subsequent (successor) e' in the combined MapForm to an edge e is defined thus: If edge e comes from mapform1, then e' is the successor of e in mapform2. If no such successor exists in mapform1 (because e is the last edge in mapform1), then e' is the first edge from mapform2. Similarly, if e originates from mapform2, then e' is the successor of e in mapform2; unless e is the last edge in mapform2, in which case e also becomes the last edge of the combined MapForm.

Consequently, the all-forms operation of the combined MapForm for any input form1 yields the union of the all-forms operations of mapform1 and mapform2 applied to input form1.

Finally, the weights on edge e of the combined MapForm is factor1 times the weight of this edge in mapform1, if e comes from mapform1; and it is factor2 times the weight of this edge in mapform1, if it originates in mapform2.

Note that a MapForm can contain more edges between the same Forms. When it comes to probability, their weights are simply summed up. Yet, the edges can play a different role with regard to the first edge, the subsequent (successor) edge and the last edge operations. Note also that the order of the MapForms in a combination is significant with regard to the same operations, but not with regard to the random edgeoperation. If mapform1 maps from form1 to form2 with probability p1, and mapform2 does so with probability p2, then the combined MapForm will do so with probability factor1 * p1 + factor2 * p2.

As the next-method receives form1 and form_last as arguments, it will always return the subsequent of the first edge that brings from form1 to form_last. So multiple edges from form1 to form_last may cause problems. If you would like to loop through all the edges, it is better to employ the all-method, which simply concatenates the outputs of the all-method for the two MapForms, and therefore it can contain repetitions.

It is important that mapform1 and mapform2 be defined canonically, that is, they return the static Forms defined in object MapForm as error messages.

A typical use of this method will be the combination of basic steps.

Parameters:
mapform1 - The first MapForm to be combined.
factor1 - The factor used to combine the first MapForm.
mapform2 - The second MapForm to be combined.
factor2 - The factor used to combine the second MapForm.
Returns:
A MapForm that is the linear combination of the two input MapForms, with the specified weights, as described above.
See Also:
BasicSteps

composition

public static final MapForm composition(MapForm mapform1,
                                        MapForm mapform2)

Composition of two MapForms. First mapform1 is applied to the input, then mapform2 is applied to this intermediate form, to obtain the outcome of the composed MapForm.

The first(Form f) method typically returns mapform2.first(mapform1.first(f)). If mapform2 does not map mapform1.first(f), then a subsequent element of the range of mapform1 is used. An infinite loop can occur, if mapform1 maps f unto an infinite range, but none of it is mapped by mapform2.)

The all(Form f) returns a "concatenation" of the vectors obtained by applying mapform2.all() to each element in mapform1.all(f) respectively. NB: certain forms can appear multiple times. If you need them only once, delete repetitions.

The method random(Form f, double r) uses the lower part of r in mapform1.random and the upper part of r in mapform2.random.

Method next(Form f1, Form last) iterates in a "diagonal". Note that this is not a very efficient way. Note also that if last is not in the range, you run into an infinite loop, instead of being returned MapForm.NotInRange.

Parameters:
mapform1 - First mapform to apply.
mapform2 - Second mapform to apply.
Returns:
A new MapForm, which is the composition of the two arguments.

fromGen

public static final MapForm fromGen(Gen gen)
Transform a Gen into a MapForm. The MapForm maps form1 unto form2 if and only if the Candidate (form1, form2) is generated by gen. The opposite of the constructor of a Gen.

See Also:
Gen