eu.bandm.music.entities

Class MetricSplitter

java.lang.Object

eu.bandm.music.entities.MetricSplitter

public class MetricSplitter
extends Object

Executes testing of MetricTree variants, introducing spontanuous n-plets. and merging of note symbols for lighter and more ergonomic writing. Maintains an internal cache, so a new instance must be created for any new combination of MetricTree and parameters.
Usage: Create a new instance with the appropriate parameters.
For every sequence of durations and sound/pause information, call process(List) / #process(List.List). //FIXME Collection?? This returns a MetricSplitter.Result object (possibly from cache). From this, an inner instance of MetricSplitter.Result.WriteOut must be created and the abstract methods overridden to the desired behaviour, then its "process()" method is called.
A MetricSplitter.Parameters_explicitMode must be provided on construction. A MetricSplitter.Parameters_automatedMode may be provided and enables automated synthesis of alternatives for divisions non yet contained. Instead, a MetricSplitter.Parameters_approximationMode may be provided which enables approximation by repeated division.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	MetricSplitter.Coverage Represents one of many ALTERNATIVE SOLUTIONS, which decided locally and concatenated before delivery.
static class	MetricSplitter.MetricNotHitException Thrown iff automated node synthesis is not active.
static class	MetricSplitter.Parameters_approximationMode
static class	MetricSplitter.Parameters_automatedMode
static class	MetricSplitter.Parameters_beams Control the generation of beam information.
static class	MetricSplitter.Parameters_explicitMode
class	MetricSplitter.Result Represents one result of processing a sequence of qualified durations.

Field Summary

Fields

Modifier and Type	Field and Description
protected Map<MetricTree,Integer>	base_flags
protected List<Tuple3<Integer,Integer,Integer>>	beam_conditional_modifiers
protected Map<Integer,Integer>	beam_unconditional_replacements
protected eu.bandm.tools.ramus.ana.Trie<MetricTree.QualifiedRational,MetricSplitter.Result>	cache
protected eu.bandm.tools.ramus.ana.Trie.Evaluator<MetricTree.QualifiedRational,MetricSplitter.Result>	cacheEvaluator
protected Map<MetricTree,StemEnd>	genuine_beams
protected MetricTree	metricTree
protected MetricSplitter.Parameters_approximationMode	parameters_approximation
protected MetricSplitter.Parameters_automatedMode	parameters_automated
protected MetricSplitter.Parameters_beams	parameters_beams
protected MetricSplitter.Parameters_explicitMode	parameters_explicit
protected Map<MetricTree,List<RationalDuration.DottedBaseDuration>>	single_node_display_cache

Constructor Summary

Constructors

Constructor and Description
MetricSplitter(MetricTree metricTree)
MetricSplitter(MetricTree metricTree, MetricSplitter.Parameters_explicitMode parameters_explicit, MetricSplitter.Parameters_automatedMode parameters_automated, MetricSplitter.Parameters_approximationMode parameters_approximation, MetricSplitter.Parameters_beams parameters_beams)

Method Summary

Modifier and Type	Method and Description
protected static void	addAlternative(MetricTree old, MetricTree neu) Aux function for adding a synthesized tree to the originial tree.
protected void	collect_genuine_beams(MetricTree parent)
protected void	collect_genuine_beams(MetricTree parent, StemEnd se_parent)
(package private) List<Integer>	div_plan(int factor) Split factor into a plan, according to GLO IN parameters_automated.
(package private) List<Integer>	div_plan(int divisor, PrimeFactors pf) Split factor into a plan, according to GLO IN parameters_automated.
(package private) List<Integer>	div_plan(PrimeFactors pf) Split factor into a plan, according to GLO IN parameters_automated.
protected void	do_collect_genuine_beams(MetricTree parent, StemEnd se_parent, List<MetricTree> subtrees)
protected void	do1Alt(MetricTree mt, List<Integer> spontPlan, MetricSplitter.Coverage cover, List<Rational> limits, int index) Find coverage for one single alternative, possibly by descending or by synthesizing a new subtree.
(package private) void	do2PF_containing(PrimeFactors containing, PrimeFactors contained, MetricTree newMt, MetricSplitter.Coverage cover, List<Rational> limits, int index) Render the events when there are two divisors, one contains the other as factor.
protected void	doFCs(MetricTree mt, List<Integer> spontPlan, MetricSplitter.Coverage cover, List<Rational> limits, int index) Aux methods for finding the Initial Coverage.
List<List<MetricTree>>	findCoverage_B(MetricTree mt, List<Rational> limits) ADAPT old version to new implementation!
MetricSplitter.Coverage	findCoverages(List<Rational> limits) Finds the lists of all completely covered and maximal nodes for a list of events.
MetricTree	get_metricTree()
protected void	make_initial_beam_plan() Assign a StemEnd to each node in metricTree, which will be used later, possibly modified by neighbours.
(package private) boolean	n_writable(MetricTree mt, int n, int posDots) Whether the conacatenation of "n" times "mt" is dotted-writable with maximally "posDots" (set differently for pause and sound by the caller).
(package private) void	noSplit1PF(MetricTree newMt, MetricSplitter.Coverage cover, List<Rational> limits, int index, PrimeFactors pf) Render the events which fall in the MetricTree mt and which need bracket/s for the PrimeFactors pf by only one(1) proportion.
protected void	parseSiblingsAndDottings(List<MetricTree> irep, boolean isPause, Set<MetricTree> printThem, Map<MetricTree,StemEnd> stemEnds) Delivers all nodes which shall appear in the notation as a symbol, in the Set #result.
MetricSplitter.Result	process(List<MetricTree.QualifiedRational> eventStarts) Main entry method: process the (ascending) list of start time points and deliver a semantically sensible rendering plan.
MetricSplitter.Result	process(List<Rational> eventStarts, List<Boolean> isPause) Main entry method: process the (ascending) list of start time points and deliver a semantically sensible rendering plan.
(package private) void	processSpontanuous_NEW(MetricTree mt, MetricSplitter.Coverage cover, List<Rational> limits, int index, int upto)
(package private) void	processSpontanuous(MetricTree mt, MetricSplitter.Coverage cover, List<Rational> limits, int index, int upto) Spectral analysis: create a new node and memorize it for LATER insertion, add quality values to cover and re-enter rh-generation with a certain PLAN for the necessary divisions.
(package private) List<Integer>	simple_factors(PrimeFactors pf, boolean reverse) Iterate over identic factors seperated, like "2, 2, 3, 5, 5", not "4,3,25".
(package private) void	split1PF(MetricTree newMt, MetricSplitter.Coverage cover, List<Rational> limits, int index, PrimeFactors pf) Render the events which fall in the MetricTree mt and which need bracket/s for the PrimeFactors pf, by one proportion or by splitting into more proportions, according to the style parameters GLO IN parameters_automated.
(package private) void	splitDots_withBeams(List<MetricTree> irep, Set<MetricTree> printThem, Map<MetricTree,StemEnd> stemEnds, int maxDots, int startPos, int endPos, boolean leftNotRight, boolean positiveDotting) Add nodes from Initial Coverage to result, representing a sequence of dotted values not exceeding maxDots.
(package private) void	splitDots(List<MetricTree> irep, Set<MetricTree> printThem, int maxDots, int startPos, int endPos, boolean leftNotRight)
protected boolean	testForSyncopeAndHemiola(List<MetricTree> irep) Returns whether the node list, representing one event, can be replaced by one single symbol, due to syncope or hemiola rules.

Methods inherited from class java.lang.Object

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

Field Detail

metricTree

protected final MetricTree metricTree

parameters_beams

protected final MetricSplitter.Parameters_beams parameters_beams

parameters_explicit

protected final MetricSplitter.Parameters_explicitMode parameters_explicit

parameters_automated

protected final MetricSplitter.Parameters_automatedMode parameters_automated

parameters_approximation

protected final MetricSplitter.Parameters_approximationMode parameters_approximation

cache

protected eu.bandm.tools.ramus.ana.Trie<MetricTree.QualifiedRational,MetricSplitter.Result> cache

cacheEvaluator

protected final eu.bandm.tools.ramus.ana.Trie.Evaluator<MetricTree.QualifiedRational,MetricSplitter.Result> cacheEvaluator

single_node_display_cache

protected Map<MetricTree,List<RationalDuration.DottedBaseDuration>> single_node_display_cache

base_flags

protected Map<MetricTree,Integer> base_flags

genuine_beams

protected Map<MetricTree,StemEnd> genuine_beams

beam_conditional_modifiers

protected final List<Tuple3<Integer,Integer,Integer>> beam_conditional_modifiers

beam_unconditional_replacements

protected Map<Integer,Integer> beam_unconditional_replacements

Constructor Detail

MetricSplitter

public MetricSplitter(MetricTree metricTree)

MetricSplitter

public MetricSplitter(MetricTree metricTree,
                      MetricSplitter.Parameters_explicitMode parameters_explicit,
                      MetricSplitter.Parameters_automatedMode parameters_automated,
                      MetricSplitter.Parameters_approximationMode parameters_approximation,
                      MetricSplitter.Parameters_beams parameters_beams)

Method Detail

get_metricTree

public MetricTree get_metricTree()

make_initial_beam_plan

protected void make_initial_beam_plan()

Assign a StemEnd to each node in metricTree, which will be used later, possibly modified by neighbours. (In any case only DECREASING: in number and/or from long to short beams.) Assume EssentialBrackets are all set. Some style parameters can be considered already here.

collect_genuine_beams

protected void collect_genuine_beams(MetricTree parent)

collect_genuine_beams

protected void collect_genuine_beams(MetricTree parent,
                                     StemEnd se_parent)

do_collect_genuine_beams

protected void do_collect_genuine_beams(MetricTree parent,
                                        StemEnd se_parent,
                                        List<MetricTree> subtrees)

process

public MetricSplitter.Result process(List<Rational> eventStarts,
                                     List<Boolean> isPause)

Main entry method: process the (ascending) list of start time points and deliver a semantically sensible rendering plan.

process

public MetricSplitter.Result process(List<MetricTree.QualifiedRational> eventStarts)

Main entry method: process the (ascending) list of start time points and deliver a semantically sensible rendering plan. Processes a list of QualifiedRational (i.e. positive Rational cross Boolean is_sound_not_pause), and finds the list of nodes of the Metric Tree of "this" MetricSplitter which must be printed to get a minimal representation in note symobles according to some historical standard note writing patterns. These patterns are called "siblings", "dottings", "syncopes" and "hemiolas". The simplification step is called "merging".
Internally, first an "Initial Coverage" is found, which for each event gives the smallest set of nodes which partition the event's duration. Is automatic mode is supported, new alternative nodes will be constructed if the division factors needed are not yet found in the MetricTree.
Output is the set of nodes which shall be printed in the rendering. More precisely: A note symbol shall appear at the start time point of all nodes contained in this set. A note symbol should not appear at the start time point of the nodes which are NOT in the set, but this is not always possible: The algorithm does not check the D-writability of nodes which are not the result of merging. The duration of each symbol is the distance to the follower in this set (or to the end of the measure, resp.).
The nodes which come out of merging correspond to more than one node of the Initial Coverage. For convenience, the calculated duration of the merge result is stored in the result object.
The nodes which come out of mergings (except dotting!) are always "directly D-writeable".
The nodes which come out of dotting may require an additional proportion to be D-writeable.
Any MetricTree contains already all brackets which are required by non-power-of-two denominators. These are considered by the MetricSplit merging process and be the final write-out. Additionally, nodes NOT merged, i.e. surviving from the Initial Coverage, may be not D-writeable due to the ENUMERATOR of their duration. This (in the current implementation) will NOT be fixed by additionally inserted proportions (which could be a feasible alternative), but by writing their child nodes or by writing FreeSectionings. The difference must be found out when generating the symbol sequence by comparing the result set with the original tree.
Some of the merge patterns applied here are "closed", ie. they put a min-and-max condition on the end-point of the event.
Others are "open", put only a min condition on the extent, and their result can further be prolongated by tied notes.
Enscribed into the metric tree, the patterns look as follows:

     syncope = closed pattern.
               The duration which is exactly as long as the parent metric node, but
               the event starts later.
           x     
          /  \   (\   )  toplevel: any division possible
         /    \ 
        p      p2        p and its follower p2 must have identical lengths 
       / \    / \            and div-counts (2 or 3 only!)
          [----[         index of start and follower identical > 0

    (will be applied only if p.duration is D-writable (e.g. for 15/16).

    In case of p.div==2, the pattern may stretch over more than one 
    intermediate levels, limited by max_level_syncope_2

      positive dotting
            pTop     
        /  / \  \
          /   x     identical lengths on all levels
         /   / \    x.div==2  required (but not for pTop.div)
        /       x     maximal dot count is limited by max_dots_positive.
       /       / \    if exceeded, push dots up or down
      [----------[

      negative dotting
             pTop     
            / \  \  \
           x   \     identical lengths on all levels
          / \   \    x.div==2  required (but not for pTop.div)
         x       \     maximal dot count is limited by max_dots_negative
        / \       \    if exceeded, push dots up or down
           [--------]


      sibling fusing (p.div >2)
             p
           / | \
          -  x  x     ident.length, n*x.duration must be D-writeable
             [----]
          x  -  x
          [----]

   

In all patterns: Differences in the duration between siblings (candidates or parents of candiates) are ALWAYS A BARRIER. Differences in their division number, i.e. internal structure, in general are NOT.
Rules for D-writability are complicated (see user documentation and the (German language) article.
Most patterns are NOT APPLIED if the result is not e-writable without proportion,
FIXME LATER: EXCEPT Dottings, which assume such a proportion will be applied when writing out! This requirement is stored in the set #additionalProportions, which must be considered when programming any later write-out procedure.
FIXME hemiole_punct, syncope_punct requires an alternative metric tree, which would be selected automtically when searching for minimal number of symbols:

               P              2*3*(1/4)
            /     \
          P         P
        / | \     / | \
       x  x  X.    Xz  z

               P               | 3*2*(1|4)
            /  |  \
          P    Q    P
        / |   /  \  | \
                 /\  
       x  x  X.    Xz  z

               P               2*2*(1/4)
            /     \
          P         P
        /   \     /   \
       x     X.    X   z
  
               P               | 1/4+(2*1/4)+1/4
            /  |  \
          /    Q    \
        /     / \     \
       x     X.    X   z
  
                              etc.
                              5*2*1/4|1/4+4*2*1/4+1/4
                              5*2*1/4|1/4+2*1/4+1/4+3*2*1/4|1/2+1/4+2*1/4+1/4+2*1/2|
                              etc.
  

data structure is event index 0 1 initialCoverage [a,b] [c, d, e] printed a c d summedDuration a d

findCoverage_B

public List<List<MetricTree>> findCoverage_B(MetricTree mt,
                                             List<Rational> limits)

ADAPT old version to new implementation!

findCoverages

public MetricSplitter.Coverage findCoverages(List<Rational> limits)

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 of the top-level tree. All values must be strongly increasing. If this list does not match the tree, then new subtrees are synthesized. which are linked into the original tree finally, when this variant has really been selected.

addAlternative

protected static void addAlternative(MetricTree old,
                                     MetricTree neu)

Aux function for adding a synthesized tree to the originial tree.

do1Alt

protected void do1Alt(MetricTree mt,
                      List<Integer> spontPlan,
                      MetricSplitter.Coverage cover,
                      List<Rational> limits,
                      int index)

Find coverage for one single alternative, possibly by descending or by synthesizing a new subtree. Index is the event currently to cover, limits[index+1] its end, which is the critical time point. spontPlan is NOT empty iff an analysis has been made by #processSpontanuous(), and this is a re-enter.

processSpontanuous

void processSpontanuous(MetricTree mt,
                        MetricSplitter.Coverage cover,
                        List<Rational> limits,
                        int index,
                        int upto)

Spectral analysis: create a new node and memorize it for LATER insertion, add quality values to cover and re-enter rh-generation with a certain PLAN for the necessary divisions. Index is the event, the END of which can not yet be processed: From index.end=limits[index+1] to upto.start=limits[upto] must all be considered. HEURISTICS! Try to divide in two(2) parts instead of nesting. Strategy of spont sub-tree generation depends on distribution of events and prime factors. Basically, there are the following cases:

   | start             | end
   |  0/1     1/2      | 1/1 
   |          .        | 
   |    1/3   |   2/3  |         a-a  (~a*b - a*b)
   |          .        | 
   |    1/3   |   1/5  |         a-b   (~a*b-c*d)
   |          .        | 
   | 1/3+1/4  |   1/5  |         a+2-b
   |          .        | 
   | 1/3 1/5  |        |         a+b-0
   |          .        | 
   | 1/3 1/5  |  1/2   |         a+b-2
   |          .        | 
   |    1/15  |   1/3  |         a*b-a  (=a*b+a*b)
   |          .        | 
   | 1/3 1/5  |   1/3  |         a+b-a  (=a+b-a+b)
   |          .        | 
   | 1/15     |   1/21 |         a*c + b*c
   |          .        | 
   | 1/3  1/7 | 1/7 1/3|         a - b - b -  a 
   |          .        | 
   | 1/5 2/5  |4/7 4/5 |         a+a - a+b
   |          .        | 
   all other, more irregular distributions -> a>b>c or a

processSpontanuous_NEW

void processSpontanuous_NEW(MetricTree mt,
                            MetricSplitter.Coverage cover,
                            List<Rational> limits,
                            int index,
                            int upto)

do2PF_containing

void do2PF_containing(PrimeFactors containing,
                      PrimeFactors contained,
                      MetricTree newMt,
                      MetricSplitter.Coverage cover,
                      List<Rational> limits,
                      int index)

Render the events when there are two divisors, one contains the other as factor. Test the special cases as enabled in GLO IN parameters_automated. Otherwise put the common divisor on top.

split1PF

void split1PF(MetricTree newMt,
              MetricSplitter.Coverage cover,
              List<Rational> limits,
              int index,
              PrimeFactors pf)

Render the events which fall in the MetricTree mt and which need bracket/s for the PrimeFactors pf, by one proportion or by splitting into more proportions, according to the style parameters GLO IN parameters_automated.

noSplit1PF

void noSplit1PF(MetricTree newMt,
                MetricSplitter.Coverage cover,
                List<Rational> limits,
                int index,
                PrimeFactors pf)

Render the events which fall in the MetricTree mt and which need bracket/s for the PrimeFactors pf by only one(1) proportion.

div_plan

List<Integer> div_plan(int divisor,
                       PrimeFactors pf)

Split factor into a plan, according to GLO IN parameters_automated.

div_plan

List<Integer> div_plan(PrimeFactors pf)

Split factor into a plan, according to GLO IN parameters_automated.

div_plan

List<Integer> div_plan(int factor)

Split factor into a plan, according to GLO IN parameters_automated.

simple_factors

List<Integer> simple_factors(PrimeFactors pf,
                             boolean reverse)

Iterate over identic factors seperated, like "2, 2, 3, 5, 5", not "4,3,25".

doFCs

protected void doFCs(MetricTree mt,
                     List<Integer> spontPlan,
                     MetricSplitter.Coverage cover,
                     List<Rational> limits,
                     int index)

Aux methods for finding the Initial Coverage. limits[index] ... limits[index+1] is the currently tested interval. "mt" is the currently tested node of type MetricTree. It holds that mt.start<=limits[index]. The event data processed is numbered like ...

  t      0/0                 measure.end
        |                   |
  index               len-2  len-1  len=4
  limits [0]   [1]    [2]    [3] 
  events [0]   [1]    [2]
  

testForSyncopeAndHemiola

protected boolean testForSyncopeAndHemiola(List<MetricTree> irep)

Returns whether the node list, representing one event, can be replaced by one single symbol, due to syncope or hemiola rules. Is NOT called with pauses. Syncopes and hemioles are CLOSED patterns, i.e. only applied when start AND end points match certain criteria. So they can be checked once, before all other patterns, and only the FACT WHETHER they are found must be returned: Iff true, the reaction of the caller is to enter only the first node into the printed set.
Any denominator !=2^n can be ignored, because it has to be realized by an n-tuplet-notation anyhow (on some higher level).
Returning true requires that duration of the new note is D-writable.
ASSUME the original final MetricTree has been extended by "get_subs_binary()" when calculating the coverage, so that all relevant nodes already exist reified and un-ambiguously.

Parameters:

irep - the initial representation, which shall be simplified

splitDots_withBeams

void splitDots_withBeams(List<MetricTree> irep,
                         Set<MetricTree> printThem,
                         Map<MetricTree,StemEnd> stemEnds,
                         int maxDots,
                         int startPos,
                         int endPos,
                         boolean leftNotRight,
                         boolean positiveDotting)

Add nodes from Initial Coverage to result, representing a sequence of dotted values not exceeding maxDots. ASSUME that the nodes of the tree are always printable: their denominator is realized by an EssentialBracket anyhow. Their enumerator is two(2). Therefore also all dottings are d-writable.
FIXME STIMMT NICHT: Die Hälfte von 4*(5/16) KANN NICHT PUNKTIERT WERDEN !!!

            negative                   positive 
             N                        N    i=in Initial Coverage
           /   \                            /   \        
          N     Xi                         Xi    N 
         / \                            / \      
        N   Xi                        Xi   N     
       / \                                        / \            
      N   Ni                             Ni  X   
     ---][^^^^^^^^^^^]            [^^^^^^^^^]
      
  

The whole interval of nodes is given by startpos to endpos (INCLUSIVE). LeftNotRight says on which side to begin the comprehensions. LeftNotRight = NegativeDotting XOR parameters.push_dots_down_not_up
BEAMING: pos dots -> nothing necessary. neg dots -> shift last of tie group to first

splitDots

void splitDots(List<MetricTree> irep,
               Set<MetricTree> printThem,
               int maxDots,
               int startPos,
               int endPos,
               boolean leftNotRight)

parseSiblingsAndDottings

protected void parseSiblingsAndDottings(List<MetricTree> irep,
                                        boolean isPause,
                                        Set<MetricTree> printThem,
                                        Map<MetricTree,StemEnd> stemEnds)

Delivers all nodes which shall appear in the notation as a symbol, in the Set #result. Filters out the subsequent nodes which shall not appear with an own symbol. (As a consequence, their durations must be added to the predecessor when writing out, in some later processing step.)
Assumes that the input is an Initial Coverage, i.e. adjacent and maximal nodes. Therefore the possible patterns are rather limited, which is exploited.
Assumes that the CLOSED patterns (syncope, hemiola, etc) have already been tested for, with neg. result.
The patterns to look for are ...

                 ppp
          /   /     \       \      \
             n       n+      pp      pp 
            /  \    /  \    /   \
                            n     p
                           / \   / \
                                n
           [-------------------]          positive dotting
           [----------------------]       double pos. dotting   
           [-------------]                siblings
                   [------------------] 


                 ppp
          /   /     \       \      \
            +pp      n       n 
            /  \    /  \    /  \
          +p    n           
          / \              
         n   n 
            [--------------]              double neg. dotting  
            [-----]                       negative dotting
                   [--------------]       siblings


   jump more than one level => no simplification possible!

                    ppp
          /         /     \       \      \
        pp        N        pp
         \       /  \     /   \
           p             p  
          / \           / \   
             n         n
            [---------]
            [-------------]
 

In a first step for every node (not the very first) the kind of Move is determined:

• up: from a nephew to an uncle, iff nephew.parent.div==2
• down: from an uncle to a nephew, iff nephew.parent.div==2
• horizontal: from sibling to sibling, iff duration identical
• jump: all others (no pattern ever spans a jump)

From parent.div==2 and the maximality of the coverage nodes it follows that

• before "up" there may be no "down" or "horizontal", and
• after "down" there may be no "up" or "horizontal".

So the only relevant sequence is

  up-up-..-hori-hori-.. down-down 

               pp
            /  \  \     \
          /     \  \      \
         p      []  []      p 
        / \    --------     / \
          []  /   hori  \  []
             /up         \
                          down
            i0 i1      i2 i3  .... i0 again
  phase       0   1      3    4=flush

  i1 = last of neg.dot, first of siblings
  i2 = last of siblings, first of pos dot (iff any!)
 

n_writable

boolean n_writable(MetricTree mt,
                   int n,
                   int posDots)

Whether the conacatenation of "n" times "mt" is dotted-writable with maximally "posDots" (set differently for pause and sound by the caller).