eu.bandm.music.entities

Class MCover

java.lang.Object

eu.bandm.music.entities.MCover

public class MCover
extends Object

Represents an "Initial Cover" of MetricTree nodes = a set of nodes which realizes a given rhythm. Tests all alternatives already contained in the MetricTree, and modifies it by inserting new divisions if necessary.
There are three modes, two of them total:

• MCover.Parameters_divide!=null inserts new proportions, if no single alternative matches;
• MCover.Parameters_approximate!=null makes equidist-bi-divisions until below a threshold;
• both==null fails, if no explicit division matches.
• both!=null is a configuration error.

Usage:
Call static method process(MTree,Parameters_approximate,Parameters_divide,List). The list must be a list of time points, strictly increasing and normalized, i.e. starting with the Rational 0/1 and ending with the duration of the measure.
This will deliver an instance of this class. On this, get_ic() will return a list of list of nodes, giving the initial cover for the events.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MCover.MetricNotHitException Thrown iff neither of both automated synthesis modes is active.
static class	MCover.Parameters_approximate The parameters when MCover works in "binary approximation mode", which divides only by two(2) until the approximation is better than the given thresholds.
static class	MCover.Parameters_divide The parameters when MCover works in "auto-division mode", which inserts new alternatives of child nodes whenever necessary.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) int	eventToProcess Realizes Co-Routine character: index of the currently processed event, switched forth globally.
(package private) List<List<MTree>>	ic The accumulator for the result; maps (via index) events to lists of MTree nodes.
protected List<Rational>	limits The list of time points to analyze.
protected MTree	metricTree The top-level metric tree (modelling the whole measure) as passed to process(MTree, Parameters_approximate, Parameters_divide, List).
(package private) Map<MTree,MTree>	newAlts Synthesized alternatives for nodes.
(package private) int	nodeCount Quality criterium for alternative decision.
protected @Opt MCover.Parameters_approximate	parameters_approximate Parameters for "binary approximation mode".
protected @Opt MCover.Parameters_divide	parameters_divide Parameters for "auto-division mode".
(package private) int	spontNodeCount Quality criterium for alternative decision: Number of nodes FIXME.
protected MStackingPlanner	stackingPlanner The strategy for introducing new brackets/divisions in "auto-division mode".

Method Summary

Modifier and Type	Method and Description
(package private) void	addNode(MTree mt, int compareResult) Store to the result the fact that the given arguments (node and event) are related.
(package private) void	appendNodes(MCover other) Merge the intermediate results (ic-mapping, reached input index, quality criteria, new mtree alternatives) from an alternative finally selected (=OTHER) into THIS.
protected void	do1Alt(MTree mt) Test to split the duration of one alternative (of possibly several), which all are EXPLICIT nodes (=from MTS, not synthetic).
protected void	doAlts(MTree mt) Test the sub-nodes and the alternatives of a node which is not completely in the current event interval, so some sub-nodes must be found to cover that interval.
protected void	doApprox(MTree mt, int index, int upto, boolean endIsHit) One ore more event starts lie truely in the current node's interval, partly with prime factors != 2.
protected void	doFC_bin(MTree mt) Here the bottom of the MTree is reached: only binary divisions are required, all other primes factors have already been realized somewhere above.
protected void	doFC_synt(MTree mt, MStackingPlanner.Plan spontPlan) Is only called if synthesizing is necessary.
protected void	doFC_top(MTree mt) Main method for finding the Initial MCover; called once for the top node from process(MTree,Parameters_approximate parameters_approximate,Parameters_divide,List), and later repeatedly for different alternatives in the middle of do1Alt(MTree).
protected void	doSynthOrImplicit(MTree mt, MStackingPlanner.Plan spontPlan) The current event interval is truely included in that of the MTree node, but there are no child nodes.
void	dump() Auxiliary debugging print-out.
List<List<MTree>>	get_ic() Return the accumulated result, which maps events (by their index) to lists of nodes.
protected MTree	makeSyntheticAlternative(MTree mt, int division) Search if a synthetic alternative with this division already exists, otherwise make one and memorize it for later tree insertion.
static MCover	process(MTree metricTree, @Opt MCover.Parameters_approximate parameters_approximate, @Opt MCover.Parameters_divide parameters_divide, List<Rational> limits) Main entry method: Finds the lists of all completely covered and maximal nodes for a list of events.
static MCover	process(MTree metricTree, MCover.Parameters_approximate parameters_approximate, @Opt MCover.Parameters_divide parameters_divide, List<Rational> limits, @Opt MStackingPlanner stackingPlanner) Same functionality as process(MTree,Parameters_approximate,Parameters_divide,List), but a different bracket order stacking planner can be plugged in.

Methods inherited from class java.lang.Object

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

Field Detail

metricTree

protected final MTree metricTree

The top-level metric tree (modelling the whole measure) as passed to process(MTree, Parameters_approximate, Parameters_divide, List).

stackingPlanner

protected final MStackingPlanner stackingPlanner

The strategy for introducing new brackets/divisions in "auto-division mode".

parameters_approximate

@Opt
protected final @Opt MCover.Parameters_approximate parameters_approximate

Parameters for "binary approximation mode".

parameters_divide

@Opt
protected final @Opt MCover.Parameters_divide parameters_divide

Parameters for "auto-division mode".

limits

protected final List<Rational> limits

The list of time points to analyze. Must start with 0/0 and end with the measure's duration. Must be strictly increasing.

ic

List<List<MTree>> ic

The accumulator for the result; maps (via index) events to lists of MTree nodes. When alternatives are tested, here temporary results are accumulated and merged into the predecessor MCover after THIS has been selected as the best result.

newAlts

Map<MTree,MTree> newAlts

Synthesized alternatives for nodes. Are temporarily stored for hypotheses, merged for selected sub-hypotheses and merged into to the MTree at the very end, when this hypotheses has been selected as result.

spontNodeCount

int spontNodeCount

Quality criterium for alternative decision: Number of nodes FIXME.

nodeCount

int nodeCount

Quality criterium for alternative decision. (Is redundant, is sum of sizes of ranges in range of ic.)

eventToProcess

int eventToProcess

Realizes Co-Routine character: index of the currently processed event, switched forth globally.

Method Detail

process

public static MCover process(MTree metricTree,
                             @Opt
                             @Opt MCover.Parameters_approximate parameters_approximate,
                             @Opt
                             @Opt MCover.Parameters_divide parameters_divide,
                             List<Rational> limits)
                      throws MCover.MetricNotHitException

Main entry method: Finds the lists of all completely covered and maximal nodes for a list of events. The events are given as a list of starting points, the first of which must be 0/1, the last of which must be the end time of the top-level MTree node = the length of the measure. All starting points must be strongly increasing. If this list does not match the tree, then new subtrees are synthesized. These are linked into the original tree in a very last step. not before some variant has really been selected as the result. The result ist stored locally and presented to the caller by the method get_ic() of the returned instance.

Throws:

MCover.MetricNotHitException

process

public static MCover process(MTree metricTree,
                             MCover.Parameters_approximate parameters_approximate,
                             @Opt
                             @Opt MCover.Parameters_divide parameters_divide,
                             List<Rational> limits,
                             @Opt
                             @Opt MStackingPlanner stackingPlanner)
                      throws MCover.MetricNotHitException

Same functionality as process(MTree,Parameters_approximate,Parameters_divide,List), but a different bracket order stacking planner can be plugged in. ("parameters_approximate" is NOT optional, because with ==null you do not need an MStackingPlanner !-)

Throws:

MCover.MetricNotHitException

get_ic

public List<List<MTree>> get_ic()

Return the accumulated result, which maps events (by their index) to lists of nodes.

addNode

void addNode(MTree mt,
             int compareResult)

Store to the result the fact that the given arguments (node and event) are related. The event is given globally by eventToProcess.

Parameters:

mt - the node which relates to the event.

compareResult - of comparing the node's and the event's end time. if identic, than change eventToProcess to the next event. // RAUS ALT : Adjust quality criterion accordingly.

appendNodes

void appendNodes(MCover other)

Merge the intermediate results (ic-mapping, reached input index, quality criteria, new mtree alternatives) from an alternative finally selected (=OTHER) into THIS. Currently only called from doAlts(MTree), could be inlined.

dump

public void dump()

Auxiliary debugging print-out.

doFC_top

protected void doFC_top(MTree mt)

Main method for finding the Initial MCover; called once for the top node from process(MTree,Parameters_approximate parameters_approximate,Parameters_divide,List), and later repeatedly for different alternatives in the middle of do1Alt(MTree).
(ATTENTION: Top-node must not have alternatives !)
"limits[index] ... limits[index+1]" is the currently tested input interval.
"mt" is the currently tested node of type MTree.
It holds that mt.start<=limits[index]. The event data processed is numbered like ...

               t=     0/0                 measure.endTime
                      |                   |
                                   len-2  len-1    limits.length=4
               limits [0]   [1]    [2]    [3] 
               events [0]   [1]    [2]
  eventToProcess ==    0     1      2
  

doAlts

protected void doAlts(MTree mt)

Test the sub-nodes and the alternatives of a node which is not completely in the current event interval, so some sub-nodes must be found to cover that interval.
This routine does NOT follow synthetics. Assume synthetics are LATER than explicits in the ".alternative" chain.

Two aux instances of MCover are created and the node "mt" and its alternative (ic any) are tested by . The two results are compared directly, one is discarded, the other merged into "THIS". This can be done locally/pairwise, because the "better than" relation is transitive.
Only called from doFC_top(MTree) and itself; could be inlined.

do1Alt

protected void do1Alt(MTree mt)

Test to split the duration of one alternative (of possibly several), which all are EXPLICIT nodes (=from MTS, not synthetic). If there are sub-nodes, then test these by calling doFC_top(MTree) recursively. (These are also only non-synthetics, because synthetics are linked as ALTERNATIVES into an MTree!)
Otherwise try the synthesizing routines doSynthOrImplicit(MTree,MStackingPlanner.Plan).
Only called from doAlts(MTree).

doSynthOrImplicit

protected void doSynthOrImplicit(MTree mt,
                                 MStackingPlanner.Plan spontPlan)

The current event interval is truely included in that of the MTree node, but there are no child nodes. Here the explicit tree and its alternatives (or the levels synthesized just now, in this particular run) have ended. We must must perform a spectral analysis of all contained time points for synthesizing further divisions.
This method works in two modes: First with spontPlan==null, for all top-level entries, and later entries without plan prediction. In this case all events under this node are collected and a spontPlan/stacking order is calculated.
If spontPlan!=null and not empty, a stacking plan has been calculated by an earlier instantiation of this same method for some ancestor. Then it is only needed to decide whether the plan must be realized for mt=one particular synthetic sub-node.

makeSyntheticAlternative

protected MTree makeSyntheticAlternative(MTree mt,
                                         int division)

Search if a synthetic alternative with this division already exists, otherwise make one and memorize it for later tree insertion. "division==2" is treated specially, because only the implicit subnodes must be activated and the parent can be re-used. (The parent has had no childs yet, ergo no childs contradict the implicit bisection.) FIXME so auch für REINE zweierpotenzen !?!?! (ZZt wird "4" als NEUE synthetische division angelegt!)

doFC_synt

protected void doFC_synt(MTree mt,
                         MStackingPlanner.Plan spontPlan)

Is only called if synthesizing is necessary.

Parameters:

mt - is a new, synthetic alternative with the correct division. It has the appropriate list of childs (which have no childs, but possibly alternatives)

spontPlan - the plan for further divisions, to be created in necessarily this order.

doFC_bin

protected void doFC_bin(MTree mt)

Here the bottom of the MTree is reached: only binary divisions are required, all other primes factors have already been realized somewhere above.

doApprox

protected void doApprox(MTree mt,
                        int index,
                        int upto,
                        boolean endIsHit)

One ore more event starts lie truely in the current node's interval, partly with prime factors != 2. The prescribed division must be executed, until the difference to the node start is in the allowed limit. Then the node is taken for the event as an approximation.

  If distance eventStart-nodeStart is too high:
     make division.
     continue recursively with that node the event lies in.
  If distance eventStart-nodeStart is NOT too high, but there is a second event in the node:
     If this is allowed: map both events to the same node
     make bi-division and continue with the lower half.
  

    |===========|
      !    !   (! 

    |=====|=====|
      !    !   (! 

    |=====|=====|
      ! !        (!