eu.bandm.music.entities

Class MSplitter

java.lang.Object

eu.bandm.music.entities.MSplitter

public class MSplitter
extends Object

Delivers a notation for rhythms, interpreted in a particular metric structure and notation style. The rhythm is given as sequence of time points or durations, qualified as sounds or pauses. It is assumed to exactly cover the time interval of one measure. The metric structure is given as an MTreeSpec, and the notation style as a set of parameters, realized as instance of MSplitter.Parameters, MTree.Parameters, MCover.Parameters_approximate and MCover.Parameters_divide.
The result includes a sequence of RationalDuration.DottedBaseDuration, representing the note heads, additional beaming information and tuplet brackets.
The calculation includes (a) finding an initial cover, as executed by MCover, and (b) merging these nodes to "dotted notation" or "sibling merge" etc., for stylistic or ergonomic reasons.
Maintains as an internal cache a Trie.
Usage: (a) construct one new instance for any new combination of one MTreeSpec and the Parameter objects. These are:

• an optional MTree.Parameters, to modify the appearance of beams and brackets.
  
• One optional instance either of MCover.Parameters_divide or
• of MCover.Parameters_approximate. This is passed down to MCover to specify the kind of automated MTree expansion.
• An optional MSplitter.Parameters instance specifies the further processing of the initial coverage by merging, dotting, etc.
  

Then (b) for every sequence of durations and sound/pause information, call process(List) / process(List,List). This returns a MSplitter.Result object (possibly from cache). From this, an inner instance of MSplitter.Result.WriteOut must be constructed and the abstract methods overridden to the desired behaviour; finally its MSplitter.Result.WriteOut.process() method is called.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MSplitter.Parameters The parameters for the post-processing of found covers.
class	MSplitter.Result Represents one result of processing a sequence of qualified durations.

Field Summary

Fields

Modifier and Type	Field and Description
protected Trie<QualifiedRational,MSplitter.Result>	cache Cache which holds the split result for each particualr sequence of qualified Rationals.
protected Trie.Evaluator<QualifiedRational,MSplitter.Result>	cacheEvaluator Operator on cache, needed for entering and retrieving cached keys and values.
protected Map<Integer,List<Integer>>	freeSectionings_int Internal cache.
protected Map<Rational,List<RationalDuration.DottedBaseDuration>>	freeSectionings_rat Internal cache.
protected MTree	metricTree The growing metric tree.
protected MCover.Parameters_approximate	parameters_approximate Parameters for the "binary approximation" mode.
protected MCover.Parameters_divide	parameters_divide Parameters for the "auto-divide" mode.
protected MSplitter.Parameters	parameters_explicit The parameters controling sibling merge, dotting, syncopas and hemiolas.
protected Map<MTree,List<MTree>>	pause_displays FIXME ????
protected Map<MTree,List<MTree>>	sound_displays FIXME ????
protected boolean	topBracketIsVanishing Whether the top-level node has a vanishing brackt.

Constructor Summary

Constructors

Constructor and Description
MSplitter(MTreeSpec metricTreeSpec) Simplified constructor, setting all to default but the metric tree spefication.
MSplitter(MTreeSpec metricTreeSpec, MTree.Parameters parameters_brackets, MCover.Parameters_approximate parameters_approximate, MCover.Parameters_divide parameters_divide, MSplitter.Parameters parameters_explicit) Full constructor, specifying all parameters.

Method Summary

Modifier and Type	Method and Description
(package private) List<MTree>	find_symbol_sequence(MTree node, Rational duration, boolean isSound) Convert a node into one or more notation symbols.
protected List<Integer>	freeSectioning_params(int i) Cuts the numerator of any duration value (the denominator being some power of two) into sums of minimal number of summands which can be written only with basic note symbol and prolongation dots ("e-writable").
protected List<RationalDuration.DottedBaseDuration>	freeSectioning_params(Rational rat) Delivers a list of RationalDuration.DottedBaseDuration which add up to the given duration value.
MTree	get_metricTree() Returns the metric tree in its current state, as modified by all preceding metric splitting tasks.
protected void	parseSiblingsAndDottings(List<MTree> irep, boolean isPause, Set<MTree> printThem, Map<MTree,StemEnd> stemEnds) Delivers all nodes which shall appear in the notation as a symbol, in the set argumente "printThem".
MSplitter.Result	process(List<QualifiedRational> eventStarts) Main entry method: process the (ascending) list of start time points and deliver a semantically sensible rendering plan.
MSplitter.Result	process(List<Rational> eventStarts, List<Boolean> isSound) Main entry method: process the (ascending) list of start time points and deliver a semantically sensible rendering plan.
(package private) void	splitDots_withBeams(List<MTree> irep, Set<MTree> printThem, Map<MTree,StemEnd> stemEnds, int dotCounts, boolean dotCountsIsMax, int startPos, int endPos, boolean leftNotRight, boolean positiveDotting) Add nodes from Initial Coverage to result, representing a sequence of dotted values not exceeding maxDots.
protected boolean	testForSyncopeAndHemiola(List<MTree> 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 MTree metricTree

The growing metric tree. Is initially constructed when this instance is constructed, and is modified whenever new divisions must be synthesized.

topBracketIsVanishing

protected final boolean topBracketIsVanishing

Whether the top-level node has a vanishing brackt.

parameters_explicit

protected final MSplitter.Parameters parameters_explicit

The parameters controling sibling merge, dotting, syncopas and hemiolas.

parameters_divide

@Opt
protected final MCover.Parameters_divide parameters_divide

Parameters for the "auto-divide" mode.

parameters_approximate

@Opt
protected final MCover.Parameters_approximate parameters_approximate

Parameters for the "binary approximation" mode.

cache

protected Trie<QualifiedRational,MSplitter.Result> cache

Cache which holds the split result for each particualr sequence of qualified Rationals. (= rational duration and flag whether sound or pause)

cacheEvaluator

protected final Trie.Evaluator<QualifiedRational,MSplitter.Result> cacheEvaluator

Operator on cache, needed for entering and retrieving cached keys and values.

sound_displays

protected Map<MTree,List<MTree>> sound_displays

FIXME ????

pause_displays

protected Map<MTree,List<MTree>> pause_displays

FIXME ????

freeSectionings_rat

protected final Map<Rational,List<RationalDuration.DottedBaseDuration>> freeSectionings_rat

Internal cache.

freeSectionings_int

protected final Map<Integer,List<Integer>> freeSectionings_int

Internal cache. See senzatempo 2013120500:

    0 0001  A        0 0001  A       0 0001  A         0 0001  A         
    0 0100  B        0 0100  B       0 1100  B         0 0100  B         
 +  1 0000  C     + 10 0000  C    + 10 0000  C      +100 0000  C         
 ---------            ---------       ---------         ---------            
    1 0101 21       10 0101 37      10 1101 45       100 0101 69         
                                                                             
    0 0011           0 0011          0 0011            0 0011            
    0 0100           0 0100          0 1100            0 0100            
 +  0 1110        + 01 1110       +  1 1110         + 11 1110            
 ---------        ---------       ---------         ---------            
    1 0101           1 0101         10 1101          100 0101            
                                                                             
    0 0111  7        0 0111  7       0 1111 15         0 0111  7         
 +  0 1110 14     +  1 1110 30    +  1 1110 30      + 11 1110 62         
 ---------        ---------       ---------         ---------            
    1 0101 21        1 0101 37      10 1101 45       100 0101 69
  

Constructor Detail

MSplitter

public MSplitter(MTreeSpec metricTreeSpec)

Simplified constructor, setting all to default but the metric tree spefication.

MSplitter

public MSplitter(MTreeSpec metricTreeSpec,
                 MTree.Parameters parameters_brackets,
                 @Opt
                 MCover.Parameters_approximate parameters_approximate,
                 @Opt
                 MCover.Parameters_divide parameters_divide,
                 MSplitter.Parameters parameters_explicit)

Full constructor, specifying all parameters.

Parameters:

metricTreeSpec - the specification of the metric tree

parameters_brackets - rules how to insert proportional brackets and beams

parameters_approximate - rules for the "binary approximation" mode

parameters_divide - rules for the "synthesize divisions" mode

parameters_explicit - rules for sibling merge, dotting, syncopes etc.

Method Detail

get_metricTree

public MTree get_metricTree()

Returns the metric tree in its current state, as modified by all preceding metric splitting tasks.

find_symbol_sequence

List<MTree> find_symbol_sequence(MTree node,
                                 Rational duration,
                                 boolean isSound)

Convert a node into one or more notation symbols. Duration is the "graphical visible" duration, before the current effective n-plet factors are applied. If the duration is e-writable, a symbol (RationalDuration.DottedBaseDuration) is already stored with the node, different for sound and silence. Otherwise a free sectioning is constructed and the beams are calculated. The results are cached.

process

public MSplitter.Result process(List<Rational> eventStarts,
                                List<Boolean> isSound)

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

process

public MSplitter.Result process(List<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 MTree "this" MSplitter 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 MTree.
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. FIXME : ALTER MetricSplitter-Text, stimmt das noch ? 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.
FIMXE: ?????? 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.
          pTop     
      / / /  \ \ \..  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 candidates) are ALWAYS A BARRIER. Differences in their division number, i.e. internal structure, in general are NOT.
Rules for E-writability of the results are complicated (see user documentation and this (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 MSplitter.Result.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 automatically 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               | 4*1/4
         /   /   \   \
                 /\
       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.
  

testForSyncopeAndHemiola

protected boolean testForSyncopeAndHemiola(List<MTree> irep)

Returns whether the node list, representing one event, can be replaced by one single symbol, due to syncope or hemiola rules. Is currently 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, etc.
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 the duration of the new note is e-writable (under the current EB-stack, i.e. only w.r.t. the enumerator).

Parameters:

irep - the initial representation, which shall be simplified

splitDots_withBeams

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

Add nodes from Initial Coverage to result, representing a sequence of dotted values not exceeding maxDots. The caller guarantees e-printability for the comprehension of (a) "dotCounts+1" nodes exactly, if "dotCountsIsMax==false"; else for all numbers of nodes <= "dotCount+1"

            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 grouping, i.e. on which side the most dots will be found if splitting them is necessary.
LeftNotRight = PositiveDotting XOR parameters.push_dots_down_not_up
BEAMING:
pos dots -> nothing necessary.
neg dots -> shift beams of the last node of every joined group to the first (=representant) of this groupe.

parseSiblingsAndDottings

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

Delivers all nodes which shall appear in the notation as a symbol, in the set argumente "printThem". 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


   jumps over more than one level => no simplification is 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!)
 

But there may be more of these patterns, if they are partial and separated by jumps in the hierarchy:

  --up--up  ....     up--hori--down hori-down
   
                         /     /   \
                        P     P     P
                      /  \         / \ 
                                  p   p
                                    / | \
                                   q  q  q
                                         /\                     
                                        X
       [---------------------------------]
 

(After a down can never come an up, because this would imply a GAP in the time cover.)

freeSectioning_params

protected List<RationalDuration.DottedBaseDuration> freeSectioning_params(Rational rat)

Delivers a list of RationalDuration.DottedBaseDuration which add up to the given duration value. The calculation of this list is controlled by style parameters, therefore the cache must be maintained specifically, with this MSplitter instanve.

freeSectioning_params

protected List<Integer> freeSectioning_params(int i)

Cuts the numerator of any duration value (the denominator being some power of two) into sums of minimal number of summands which can be written only with basic note symbol and prolongation dots ("e-writable"). The algorithm is based on the fact that the numerators of dotted base values have the form of "Mersenne numbers" (2^n)-1, and that these numbers appear as continuous sequences of the digit One(1) in the binary representation. E.g.

        27     ^   0001 1011    ^   3*8 + 3*1
       ----    =            2   =   ---   ---   = dotted whole plus dotted eighth
        16                           16    16
  

Some exceptions are hard-wired, see the initialization block above. The limits on dot counts and rule for dot grouping is controlled by parameters_explicit, therefore this cache must be local to this MSplitter instance.