MetricTree (BandM signal & music)

java.lang.Object
- eu.bandm.music.entities.MetricTree

All Implemented Interfaces:

MetrumIndication
```
public class MetricTree
extends Object
implements MetrumIndication
```
Represention of the internal metrical hierarchies of one single measure, used for interpretation of rhythms. This implementation has back-pointers to context and siblings, so sharing of nodes is NOT POSSIBLE! Every node represents an interval of the time of the measure. The sequence of the intervals represented by the childs of a node cover the interval of this parent node, in the same order. As a consequence, every node has a duration, startpoint and endpoint. The children of each node can be of different length and/or structure.
When constructing such a tree structure, finally the method initialize() or #initialize(Reaction) must be called which checks and distributes the missing duration values. The result must be conflict-free and total.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`MetricTree.EssentialBracket` Realizes an n-tuplet-bracket which is necessary for the notation of some continuous sequence of nodes, because a new prime factor is introduced in the denominators of their durations.
`static class`	`MetricTree.Origin`
`static class`	`MetricTree.QualifiedRational` Realizes duration X boolean = sound_notPause.
`class`	`MetricTree.Visitor` User must redefine action(), openProportion(), closeProportion().

Field Summary

Fields
Modifier and Type	Field and Description
`(package private) MetricTree`	`alternative`
`(package private) MetricTree.EssentialBracket`	`bracketStart`
`(package private) Rational`	`duration`
`(package private) Rational`	`end`
`(package private) boolean`	`equidist`
`(package private) boolean`	`explicitDuration`
`(package private) boolean`	`initialized`
`(package private) MetricTree.Origin`	`origin` Kind of origin, either explictly by user, or by different automatic augmentations.
`protected static Function<List<MetricTree>,MetricTree>`	`packAlt`
`protected static Function<List<MetricTree>,MetricTree>`	`packConcat`
`protected static Function3<Integer,Integer,MetricTree,MetricTree>`	`packDivTree`
`protected static Function2<Integer,MetricTree,MetricTree>`	`packMul`
`protected static Function<Integer,MetricTree>`	`packSimple`
`(package private) MetricTree`	`parent`
`protected static Translet.Parser<MetricTree>`	`parser_alt`
`protected static Translet.Parser<MetricTree>`	`parser_concat`
`static Translet.Parser<MetricTree>`	`parser_summand`
`protected static Translet.Recursive<MetricTree>`	`parser_summand_recursive`
`static Translet.Parser<MetricTree>`	`parser_timed`
`(package private) int`	`position` Position in the parents' list, starting from zero(0).
`(package private) Rational`	`start`
`(package private) List<MetricTree>`	`subs`

Constructor Summary

Constructors
Constructor and Description
`MetricTree(int num, int den, MetricTree... args)` Create one node with arg nodes as sub-nodes, and an explicit duration.
`MetricTree(List<MetricTree> args)` Create one node with arg nodes as sub-nodes.
`MetricTree(MetricTree... args)` Create one node with arg nodes as sub-nodes.
`MetricTree(Rational rat, List<MetricTree> args)` Create one node with arg nodes as sub-nodes, and an explicit duration.
`MetricTree(Rational rat, MetricTree... args)` Create one node with arg nodes as sub-nodes, and an explicit duration.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`MetricTree`	`addAlternative(MetricTree alt)`
`static String`	`arrayToString(Object[] array)`
`protected void`	`calcStartEnd(Rational start)` Recursive function for calculating `start`, `end` and `equidist`.
`protected void`	`collectBrackets()` Make potential n-plet-brackets, merge brackets over more than one child into one(1), iff appropriate.
`Rational`	`constantRationalMeasureDuration()` Returns the length of a measure.
`protected MetricTree`	`deepCopy()` Converts into individuum and fills context dependend fields (pos, parent).
`(package private) void`	`divide_by_odd_or_2(int num)` Adds a number of equidistant sub-trees.
`void`	`dump()` Prints an indented visualization to System.err.
`void`	`dump(PrintStream p)` Prints an indented visualization.
`void`	`dump(PrintWriter p)` Prints an indented visualization.
`MetricTree`	`get_alternative()`
`Rational`	`get_duration()`
`Rational`	`get_end()`
`boolean`	`get_explicitDuration()`
`boolean`	`get_initialized()`
`MetricTree.Origin`	`get_origin()` Whether this has been created explicitly, or by implicit division, or ..
`MetricTree`	`get_parent()`
`int`	`get_position()` Position in the parents' list, starting from zero(0).
`int`	`get_size_binary()` Returns the number of children of this node.
`int`	`get_size()`
`Rational`	`get_start()`
`List<MetricTree>`	`get_subs_binary()` Returns the list of children of this node.
`List<MetricTree>`	`get_subs()`
`MetricTree`	`getFollowing()` Returns the highest node which starts at the timepoint when this ends.
`MetricTree`	`getFollowingSibling()` Returns the node which is child of the same parent, and one position further, iff it exists, otherwise null.
`MetricTree`	`getPrecedingSibling()` Returns the node which is child of the same parent, and one position earlier, iff it exists, otherwise null.
`MetricTree`	`initialize()` Calls `#initialize(Reaction)` with `Modifiers.Reaction.silentlyAllow`.
`MetricTree`	`initialize(Modifiers.Reaction redundantDuration)` Delivers an initialized, ready to use NEW COPY of the given MetricTree.
`boolean`	`is_equi_binary()` Returns whether the cild level is divided equidistantly by two.
`boolean`	`isFollowingSiblingOf(MetricTree predec)` Returns whether this node is child of the same parent and one position further.
`static void`	`main(String[] args)` Perform some tests via `test_i(MetricTree)` and `test_p(String)`.
`protected void`	`makeBracket(PrimeFactors factors, int startPos, int endPos)` Make an instance of EssentialBracket and link it to the child node of "this" at the given start position (if !=1).
`static MetricTree`	`parseAndInitialize(String s)` Create one node by parsing.
`static Translet.Parser<MetricTree>`	`parser()` Frontend for constructing a MetricTree, supporting durations at arbitrarily distributed points, as long as a consistent completion is possible, exactly as with the constructor calls.
`String`	`posString()` Return a position indidication, i.e.
`protected void`	`propagateDown_alt(Rational altdur, Modifiers.Reaction redundantDuration)` The duration of some alternative of the node is fixed (explicitly when constructing, or by upward propagation; in altdur != null).
`protected void`	`propagateDown(Modifiers.Reaction redundantDuration)` The duration of the node is fixed (by construction or by downward propagation or by some alternative.) Either all children do not have a duration, then the duration is distributed equally among them, or only one child does not have a duration and gets the rest.
`protected void`	`propagateUp(Modifiers.Reaction redundantDuration)` Visit depth-first and sum-up the durations of children, as long as possible and necessary.
`protected void`	`reduceBrackets(PrimeFactors factors)` Remove a factor from a previously (bottom up) constructed bracket, because it is now realized by a bracket on the next higher level.
`protected MetricTree`	`shallowCopy()` Makes new "empty" node as boilerplate for deep copy and for synthesizing new alternatives.
`protected static void`	`test_i(MetricTree mt)` Test the initialization (ie.
`protected static void`	`test_p(String s)` Test parsing and initialization for the text representation of a MetricTree.
`String`	`toString()` gives one-line rendering.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - origin
```
MetricTree.Origin origin
```
    Kind of origin, either explictly by user, or by different automatic augmentations.
  - position
```
int position
```
    Position in the parents' list, starting from zero(0).
  - subs
```
List<MetricTree> subs
```
  - parent
```
MetricTree parent
```
  - alternative
```
MetricTree alternative
```
  - duration
```
Rational duration
```
  - start
```
Rational start
```
  - end
```
Rational end
```
  - explicitDuration
```
boolean explicitDuration
```
  - initialized
```
boolean initialized
```
  - equidist
```
boolean equidist
```
  - bracketStart
```
MetricTree.EssentialBracket bracketStart
```
  - packConcat
```
protected static Function<List<MetricTree>,MetricTree> packConcat
```
  - packAlt
```
protected static Function<List<MetricTree>,MetricTree> packAlt
```
  - packMul
```
protected static Function2<Integer,MetricTree,MetricTree> packMul
```
  - packSimple
```
protected static Function<Integer,MetricTree> packSimple
```
  - packDivTree
```
protected static Function3<Integer,Integer,MetricTree,MetricTree> packDivTree
```
  - parser_summand_recursive
```
protected static final Translet.Recursive<MetricTree> parser_summand_recursive
```
  - parser_concat
```
protected static final Translet.Parser<MetricTree> parser_concat
```
  - parser_alt
```
protected static final Translet.Parser<MetricTree> parser_alt
```
  - parser_timed
```
public static Translet.Parser<MetricTree> parser_timed
```
  - parser_summand
```
public static Translet.Parser<MetricTree> parser_summand
```
- Constructor Detail
  - MetricTree
```
public MetricTree(List<MetricTree> args)
```
    Create one node with arg nodes as sub-nodes.
  - MetricTree
```
public MetricTree(MetricTree... args)
```
    Create one node with arg nodes as sub-nodes.
  - MetricTree
```
public MetricTree(Rational rat,
                  List<MetricTree> args)
```
    Create one node with arg nodes as sub-nodes, and an explicit duration.
  - MetricTree
```
public MetricTree(int num,
                  int den,
                  MetricTree... args)
```
    Create one node with arg nodes as sub-nodes, and an explicit duration.
  - MetricTree
```
public MetricTree(Rational rat,
                  MetricTree... args)
```
    Create one node with arg nodes as sub-nodes, and an explicit duration.
- Method Detail
  - parseAndInitialize
```
public static MetricTree parseAndInitialize(String s)
```
    Create one node by parsing.
  - addAlternative
```
public MetricTree addAlternative(MetricTree alt)
```
  - constantRationalMeasureDuration
```
public Rational constantRationalMeasureDuration()
```
    Returns the length of a measure. This is defined by the interface MetrumIndication, which MAY throw an UnsupportedOperationException in other implementations.
    
    Specified by:
    
    constantRationalMeasureDuration in interface MetrumIndication
  - posString
```
public String posString()
```
    Return a position indidication, i.e. the hierarchical adress.
  - toString
```
public String toString()
```
    gives one-line rendering. See also dump(PrintStream), which gives a multi-line indented view.
    
    Overrides:
    
    toString in class Object
  - get_position
```
public int get_position()
```
    Position in the parents' list, starting from zero(0).
  - get_size
```
public int get_size()
```
  - get_origin
```
public MetricTree.Origin get_origin()
```
    Whether this has been created explicitly, or by implicit division, or ..
  - get_subs
```
public List<MetricTree> get_subs()
```
  - get_parent
```
public MetricTree get_parent()
```
  - get_alternative
```
public MetricTree get_alternative()
```
  - get_initialized
```
public boolean get_initialized()
```
  - get_start
```
public Rational get_start()
```
  - get_end
```
public Rational get_end()
```
  - get_duration
```
public Rational get_duration()
```
  - get_explicitDuration
```
public boolean get_explicitDuration()
```
  - isFollowingSiblingOf
```
public boolean isFollowingSiblingOf(MetricTree predec)
```
    Returns whether this node is child of the same parent and one position further.
  - getFollowingSibling
```
public MetricTree getFollowingSibling()
```
    Returns the node which is child of the same parent, and one position further, iff it exists, otherwise null.
    ATTENTION: There may be alterrnative nodes, accessible by alternative, which have a different structure, but the same duration.
  - getPrecedingSibling
```
public MetricTree getPrecedingSibling()
```
    Returns the node which is child of the same parent, and one position earlier, iff it exists, otherwise null.
    ATTENTION: There may be alterrnative nodes, accessible by alternative, which have a different structure, but the same duration.
  - getFollowing
```
public MetricTree getFollowing()
```
    Returns the highest node which starts at the timepoint when this ends. It can be the following sibling, or the following sibling of the parent, if the first does not exist, etc.
    ATTENTION: There may be alterrnative nodes, accessible by alternative, which have a different structure, but the same duration.
    ATTENTION: only used locally, in doFC. AND IN makebeams .... FIXME
  - get_subs_binary
```
public List<MetricTree> get_subs_binary()
```
    Returns the list of children of this node. Creates a sub-tree with a division factor of two(2), iff no children currently exist. This mirrors the default division by two(2) implicitly allowed for every node in CWN.
  - divide_by_odd_or_2
```
void divide_by_odd_or_2(int num)
```
    Adds a number of equidistant sub-trees. ONLY used when synthesizing new subnode divisions by MetricSplitter. FIXME ANZAHL der NEUEN BEAMS muss noch berechnet werden !?!?
  - get_size_binary
```
public int get_size_binary()
```
    Returns the number of children of this node. Returns two(2) iff no children currently exist. This mirrors the default division by two(2) implicitly allowed for every node in CWN.
  - is_equi_binary
```
public boolean is_equi_binary()
```
    Returns whether the cild level is divided equidistantly by two.
  - initialize
```
public MetricTree initialize(Modifiers.Reaction redundantDuration)
```
    Delivers an initialized, ready to use NEW COPY of the given MetricTree. Must be called once on the root of a complete tree definition to initialize all derived field values. Assumes that initially only a few duration fields are set. The durations of the children of such a node are calculated by equidistant division. The duration of a node where all childern have a duration is by summing them up. After all durations have been set, the start positions are defined by summing up the preceding siblings. The user is free to define durations at very different positions of a fresh MetricTree, before calling the method. This may result in inconsistencies, which are signalled as exceptions. Esp. when tuplets shall be combined, durations must be inserted explicitly.
```
   new MetricTree(new MetricTree (3,4, new MetricTree(),
                                       new MetricTree(),
                                       new MetricTree()),
                  new MetricTree (2,4, new MetricTree(),
                                       new MetricTree(),
                                       new MetricTree())
                 ):
  
```
    ... defines a measure with three(3) quarter notes (1/4) in its first part, and three(3) quarter triplets(1/6) in its second part.
    The following combinations are possible for any node "x" which does not yet carry a duration:
```
        p=dp              p=dp
      /  \   \           /  \           /
     x=?  =?  =?        x=?  y=py      x=?
                                     / \    \
                                   c=dc d=dd e=de
  
```
    Parameters:
    
    redundantDuration - how to react when the duration of a particular node is defined by more than one(>1) sources to the same value.
  - initialize
```
public MetricTree initialize()
```
    Calls #initialize(Reaction) with Modifiers.Reaction.silentlyAllow.
  - deepCopy
```
protected MetricTree deepCopy()
```
    Converts into individuum and fills context dependend fields (pos, parent). Called (currently only) here by initialize() and by "new MetricSplitter()".
  - shallowCopy
```
protected MetricTree shallowCopy()
```
    Makes new "empty" node as boilerplate for deep copy and for synthesizing new alternatives. Called (currently only) here by deepCopy() and by "MetricSplitter.processSpontanuous()" (followed by #divide_by_odd(int)).
  - calcStartEnd
```
protected void calcStartEnd(Rational start)
```
    Recursive function for calculating start, end and equidist.
  - propagateUp
```
protected void propagateUp(Modifiers.Reaction redundantDuration)
```
    Visit depth-first and sum-up the durations of children, as long as possible and necessary. Whenever an explicit duration is found, switch to #propagateDown(Reaction) for the sub-tree.
  - propagateDown_alt
```
protected void propagateDown_alt(Rational altdur,
                                 Modifiers.Reaction redundantDuration)
```
    The duration of some alternative of the node is fixed (explicitly when constructing, or by upward propagation; in altdur != null). Check for identiy iff there is an explicit duration, and call propagateDown().
  - propagateDown
```
protected void propagateDown(Modifiers.Reaction redundantDuration)
```
    The duration of the node is fixed (by construction or by downward propagation or by some alternative.) Either all children do not have a duration, then the duration is distributed equally among them, or only one child does not have a duration and gets the rest.
  - collectBrackets
```
protected void collectBrackets()
```
    Make potential n-plet-brackets, merge brackets over more than one child into one(1), iff appropriate. To support the liberal construction rules of MetricTree, very different combinations must be supported:
    - Different prime factors for child nodes on the same level, ...
    - ... opposed to brackets spanning all childs of a particular parent, putting same proportion on every of these, called "complete".
    - Sublevels with under- and overflow of duration values, together called non-fitting, ...
    - ... opposed to those adding up to factor one(1), called fitting. (Non-fitting brackets are indeed standard on lower levels, e.g. triplet-eights in a triplet-quarter, but do not survive, being replaced by a fitting one, one level above.)
    - Factors can "disappear" again on a lower level, due to asymmetrical addition, as in
      1/3 // = triplet-half / \ 1/4 1/12 // divided into quarter and triplet eights
    EssentialBrackets are collected bottom-up. but complete and non-fitting are replaced if one level above is a fitting one.
  - makeBracket
```
protected void makeBracket(PrimeFactors factors,
                           int startPos,
                           int endPos)
```
    Make an instance of EssentialBracket and link it to the child node of "this" at the given start position (if !=1). Eliminate the factor of this level from all brackets already constructed on the next lower level by replacing them with the result of #reduceBracket(EssentialBracket,PrimeFactors).
  - reduceBrackets
```
protected void reduceBrackets(PrimeFactors factors)
```
    Remove a factor from a previously (bottom up) constructed bracket, because it is now realized by a bracket on the next higher level. May yield a more simple bracket (eg. 1/15 -> 1/5) or no bracket at all.
  - parser
```
public static Translet.Parser<MetricTree> parser()
```
    Frontend for constructing a MetricTree, supporting durations at arbitrarily distributed points, as long as a consistent completion is possible, exactly as with the constructor calls.
    , Leaves without any duration must be possible, as well as durations attached to non-leaf nodes. Consequently, examples of inputs are ...
```
    3/4(3)
    1/1(3*2)
        2*2*3    //will fail to initialize due to missing duration information
    1/1(2*2*3)
        2*2*3*1/12
    1/8(3)
    1/8(2*3)
    1/1(3*1/8+3)
    (1/8+1/8)+1/2(1+2)
  NEW:
    2*2+(1/4|3*1/12)  // eighth-triplets
    2*(1/2|3*1/6)     // quarter-triplets
    2*2*(1/4|3*1/12|5*1/20)
    2 * 2 * (1/4 | 3*1/12 | 5*1/20)
  
```
  - arrayToString
```
public static String arrayToString(Object[] array)
```
  - dump
```
public void dump()
```
    Prints an indented visualization to System.err.
  - dump
```
public void dump(PrintStream p)
```
    Prints an indented visualization.
  - dump
```
public void dump(PrintWriter p)
```
    Prints an indented visualization.
  - test_i
```
protected static void test_i(MetricTree mt)
```
    Test the initialization (ie. time value distribution etc.) for a MetricTree.
  - test_p
```
protected static void test_p(String s)
```
    Test parsing and initialization for the text representation of a MetricTree.
  - main
```
public static void main(String[] args)
```
    Perform some tests via test_i(MetricTree) and test_p(String).

Class MetricTree

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

origin

position

subs

parent

alternative

duration

start

end

explicitDuration

initialized

equidist

bracketStart

packConcat

packAlt

packMul

packSimple

packDivTree

parser_summand_recursive

parser_concat

parser_alt

parser_timed

parser_summand

Constructor Detail

MetricTree

MetricTree

MetricTree

MetricTree

MetricTree

Method Detail

parseAndInitialize

addAlternative

constantRationalMeasureDuration

posString

toString

get_position

get_size

get_origin

get_subs

get_parent

get_alternative

get_initialized

get_start

get_end

get_duration

get_explicitDuration

isFollowingSiblingOf

getFollowingSibling

getPrecedingSibling

getFollowing

get_subs_binary

divide_by_odd_or_2

get_size_binary

is_equi_binary

initialize

initialize

deepCopy

shallowCopy

calcStartEnd

propagateUp

propagateDown_alt

propagateDown

collectBrackets

makeBracket

reduceBrackets

parser

arrayToString

dump

dump

dump

test_i

test_p

main