Package eu.bandm.music.entities

Class MCover

java.lang.Object
eu.bandm.music.entities.MCover
public class MCover extends Object
Represents an "Initial Cover" of MTree 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: Usage:
Call static method process(MTree,CheckedParameters_approximate,CheckedParameters_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.

  • Field Details

    • metricTree

      protected final MTree metricTree
      The top-level metric tree (modelling the whole measure) as passed to process(MTree, CheckedParameters_approximate, CheckedParameters_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.CheckedParameters_approximate parameters_approximate
      Parameters for "auto-division mode".

    • parameters_divide

      @Opt protected final @Opt MCover.CheckedParameters_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.

    • 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 Details

    • process

      public static MCover process(MTree metricTree, @Opt @Opt MCover.CheckedParameters_approximate parameters_approximate, @Opt @Opt MCover.CheckedParameters_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. Either parameters_divide or parameters_approximate must be != null. 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.CheckedParameters_divide parameters_divide, List<Rational> limits)
      A standard MStackingPlanner is used.

    • process

      public static MCover process(MTree metricTree, MCover.CheckedParameters_divide parameters_divide, List<Rational> limits, MStackingPlanner stackingPlanner)
      Same functionality as process(MTree,CheckedParameters_divide,List), but a different bracket order stacking planner can be plugged in.

    • addAlternative

      static void addAlternative(MTree base, MTree alt)

    • 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,CheckedParameters_approximate,CheckedParameters_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, @Opt 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.)
      Is only called if no explicit division matches <-- synthetic division is necessary -> only synthetics must be searched.
      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.
  
          |===========|
      !    !   (! 

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

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