hu.birot.OTKit.otBuildingBlocks
Class Topology

java.lang.Object
  hu.birot.OTKit.otBuildingBlocks.Topology

public class Topology
extends java.lang.Object

Realizes the neighborhood structure (a.k.a. topology) on the candidate set. It defines a relation among the candidates originating from the same underlying form.

Candidates Candidate(uf1,sf1) and Candidate(uf2,sf2) can be neighbors of each other only if uf1 and uf2 are the same (are equal, at least for the equals method). In such a case, whether the two candidates are neighbors usually depends on sf1 and sf2 only, even though this restriction needs not be always met. Another frequently met requirement is that neighborhood be a symmetric and irreflexive relation.

To create a Topology, you can either employ a MapForm, or implement the methods yourself. The second is often much more efficient. Additionally, if the topology also depends on the underlying form, you cannot use a MapForm, since the MapForm defines a mapping exclusively on the surface forms.

In both cases you must be aware of which methods you will use. If you use performance.randomWalks.randomWalk, you will only need Topology.rndNeighborOf. If, however, you use performance.randomWalks.gradientWalk or performance.randomWalks.gradientWalkrnd, then you will need Topology.allNeighborsOf. That is, depending on the type of random walk you need the Topology for, it is sufficient to override either method Topology.allNeighborsOf or method Topology.rndNeighborOf. Similarly, if you base your Topology on a MapForm, then it is sufficient to override (implement) the corresponding methods of that MapForm.

A probably frequently asked question will be what the difference between the Topology and the underlying MapForm is. The answer is that although both have the same methods (maybe named differently), they do not realize a map between the same types of objects. A MapForm m is about mapping a (surface) Form to a set of (surface) Forms, whereas the corresponding Topology(m) maps candidates to a set of (neighboring) candidates. (Additionally, a Gen maps an underlying form to a set of candidates.) True, the set of neighboring candidates will share their underlying form with the argument of the topology, whereas looking at the surface forms only will reflect m.

See Also:

MapForm

Field Summary

java.lang.String

name An optional nickname of the topology.

Constructor Summary

Topology()
Construct a new Topology with an empty map.

Topology(MapForm m)
Construct a new Topology employing the MapForm m.

Method Summary

java.util.Vector<Candidate>	allNeighborsOf(Candidate c) Returns a vector of all the neighbors of candidate c.
Candidate	firstNeighborOf(Candidate c) Returns the first candidate among the neighbors of candidate c.
Candidate	nextNeighborOf(Candidate c, Candidate c0) Returns the next neighbor among the neighbors of candidate c, the one following candidate c0.
Candidate	rndNeighborOf(Candidate c, double rnd) Return a random neighbor of c.

Methods inherited from class java.lang.Object

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

Field Detail

name

public java.lang.String name

An optional nickname of the topology.

Constructor Detail

Topology

public Topology()

Construct a new Topology with an empty map. Can be used for instance if you override the methods yourself.

Topology

public Topology(MapForm m)

Construct a new Topology employing the MapForm m.

The set of neighboring candidates of the Candidate c will be the candidates c' such that: c.uf == c'.uf, and c'.sf is in the set to which c.sf is mapped by m.

For instance, Topology.firstNeighborOf(c) is Candidate(c.uf, m.first(c.sf)).

Parameters:

m - MapForm that contains the mapping from underlying forms to surface forms.

See Also:

MapForm

Method Detail

rndNeighborOf

public Candidate rndNeighborOf(Candidate c,
                               double rnd)

Return a random neighbor of c.

If c.sf is not in the domain of Topology.map, then Candidate(c.uf, MapForm.NoMapping) is returned. If rnd is too high (greater than 1), then Candidate(c.uf, MapForm.rndTooHigh) is returned. If rnd is less than 0, then the result is the same as if rnd were equal to 0.

Parameters:

c - Candidate, the neighbor of which is returned by the method.

rnd - A random value defining which neighbor to be returned.

Returns:

A random candidate (determined by rnd) neighboring candidate c.

See Also:

MapForm.random(Form, double), MapForm.NoMapping, MapForm.RndTooHigh

firstNeighborOf

public Candidate firstNeighborOf(Candidate c)

Returns the first candidate among the neighbors of candidate c.

If c.sf is not in the domain of Topology.map, then Candidate(c.uf, MapForm.NoMapping) is returned.

Parameters:

c - Candidate whose first neighbor is returned.

Returns:

The first neighboring candidate of c.

See Also:

MapForm.first(Form), MapForm.NoMapping

nextNeighborOf

public Candidate nextNeighborOf(Candidate c,
                                Candidate c0)

Returns the next neighbor among the neighbors of candidate c, the one following candidate c0.

If c.uf is not equal to c0.uf (as defined by the method Form.equals), then Candidate(Form(), MapForm.NotInRange) is returned.

Otherwise, if c0 is the last candidate among the neighbors of c, then the method returns a Candidate whose surface form contains is MapForm.NoMoreForm ("ERROR: no more forms.").

If c0 is not a neighbor of c (i.e., if c.sf is not mapped to c0.sf by Topology.map), although they share equal underlying forms, then Candidate(c.uf, MapForm.NotInRange) is returned.

Finally, you are returned Candidate(c.uf, MapForm.NoMapping), if c.sf is not in the domain of Topology.map.

Parameters:

c - Candidate among whose neighbors the next one is searched for.

c0 - Previous neighbor of candidate c.

Returns:

The candidate among the neighbors of c that follows candidate c1.

See Also:

MapForm.next(hu.birot.OTKit.dataType.Form, hu.birot.OTKit.dataType.Form), MapForm.NoMoreForm, MapForm.NoMapping, MapForm.NotInRange

allNeighborsOf

public java.util.Vector<Candidate> allNeighborsOf(Candidate c)

Returns a vector of all the neighbors of candidate c. They share the same underlying form: Form c.uf. Their surface forms come from Topology.map.all(c.sf), which is the set of the (surface) forms to which c.sf is mapped by the map realizing the topology.

If this set is infinite, then the vector returned contains the single candidate Candidate(c.uf, MapForm.InfiniteSet). Similarly, a vector with the single Candidate(c.uf, MapForm.NoMapping) is returned, if Topology.map has no mapping for c.

Parameters:

c - Candidates whose neighbors are to be listed.

Returns:

A vector of all candidates neighboring candidate c.

See Also:

MapForm.all(hu.birot.OTKit.dataType.Form), MapForm.InfiniteSet, MapForm.NoMapping