# Meter¶

class `metertools.``Meter`(argument=None, decrease_durations_monotonically=True, preferred_boundary_depth=None)

Meter.

```>>> import abjad
```

Meter models a common practice understanding of beats and other levels of rhythmic organization structured as a tree. Meter structure corresponds to the monotonically increasing sequence of factors in the numerator of a given time signature. Successively deeper levels of the tree divide time by successive factors.

Duple meter:

```>>> meter = abjad.Meter((2, 4))
>>> meter
Meter('(2/4 (1/4 1/4))')
```
```>>> print(meter.pretty_rtm_format)
(2/4 (
1/4
1/4))
```
```>>> graph(meter)
```

2/4 comprises two beats.

Triple meter:

```>>> meter = abjad.Meter((3, 4))
>>> print(meter.pretty_rtm_format)
(3/4 (
1/4
1/4
1/4))
```
```>>> graph(meter)
```

3/4 comprises three beats.

```>>> meter = abjad.Meter((4, 4))
>>> meter
Meter('(4/4 (1/4 1/4 1/4 1/4))')
```
```>>> print(meter.pretty_rtm_format)
(4/4 (
1/4
1/4
1/4
1/4))
```
```>>> graph(meter)
```

4/4 comprises four beats.

Compound triple meter:

```>>> meter = abjad.Meter((6, 8))
>>> print(meter.pretty_rtm_format)
(6/8 (
(3/8 (
1/8
1/8
1/8))
(3/8 (
1/8
1/8
1/8))))
```
```>>> graph(meter)
```

6/8 comprises two beats of three parts each.

Another compound triple meter:

```>>> meter = abjad.Meter((12, 8))
>>> print(meter.pretty_rtm_format)
(12/8 (
(3/8 (
1/8
1/8
1/8))
(3/8 (
1/8
1/8
1/8))
(3/8 (
1/8
1/8
1/8))
(3/8 (
1/8
1/8
1/8))))
```
```>>> graph(meter)
```

12/8 comprises four beats of three parts each.

An asymmetric meter:

```>>> meter = abjad.Meter((5, 4))
>>> print(meter.pretty_rtm_format)
(5/4 (
(3/4 (
1/4
1/4
1/4))
(2/4 (
1/4
1/4))))
```
```>>> graph(meter)
```

5/4 comprises two unequal beats. By default unequal beats are arranged from greatest to least.

Another asymmetric meter:

```>>> meter = abjad.Meter((7, 4))
>>> print(meter.pretty_rtm_format)
(7/4 (
(3/4 (
1/4
1/4
1/4))
(2/4 (
1/4
1/4))
(2/4 (
1/4
1/4))))
```
```>>> graph(meter)
```

7/4 comprises three unequal beats. Beats are arranged from greatest to least by default.

The same asymmetric meter structured differently:

```>>> meter = abjad.Meter(
...     (7, 4),
...     decrease_durations_monotonically=False,
...     )
>>> print(meter.pretty_rtm_format)
(7/4 (
(2/4 (
1/4
1/4))
(2/4 (
1/4
1/4))
(3/4 (
1/4
1/4
1/4))))
```
```>>> graph(meter)
```

7/4 with beats arragned from least to greatest.

Meter interpreted by default as containing two compound beats:

```>>> meter = abjad.Meter((6, 4))
>>> meter
Meter('(6/4 ((3/4 (1/4 1/4 1/4)) (3/4 (1/4 1/4 1/4))))')
```
```>>> print(meter.pretty_rtm_format)
(6/4 (
(3/4 (
1/4
1/4
1/4))
(3/4 (
1/4
1/4
1/4))))
```
```>>> graph(meter)
```

Same meter customized to contain four compound beats:

```>>> parser = abjad.rhythmtreetools.RhythmTreeParser()
>>> meter = abjad.Meter('(6/4 ((3/8 (1/8 1/8 1/8)) (3/8 (1/8 1/8 1/8)) (3/8 (1/8 1/8 1/8)) (3/8 (1/8 1/8 1/8))))')
>>> meter
Meter('(6/4 ((3/8 (1/8 1/8 1/8)) (3/8 (1/8 1/8 1/8)) (3/8 (1/8 1/8 1/8)) (3/8 (1/8 1/8 1/8))))')
```
```>>> print(meter.pretty_rtm_format)
(6/4 (
(3/8 (
1/8
1/8
1/8))
(3/8 (
1/8
1/8
1/8))
(3/8 (
1/8
1/8
1/8))
(3/8 (
1/8
1/8
1/8))))
```
```>>> graph(meter)
```

Prime divisions greater than `3` are converted to sequences of `2` and `3` summing to that prime. Summands are arranged from greatest to least by default. This means that `5` becomes `3+2` and `7` becomes `3+2+2` in the examples above.

## Attribute summary¶

 `decrease_durations_monotonically` Is true when meter divides large primes into collections of `2` and `3` that decrease monotonically. `denominator` Gets denominator of meter. `depthwise_offset_inventory` Gets depthwise offset inventory of meter. `duration` Gets duration of meter. `fit_meters`(argument, meters[, denominator, …]) Finds the best-matching sequence of meters for the offsets contained in argument. `generate_offset_kernel_to_denominator`(…[, …]) Generates a dictionary of all offsets in a meter up to denominator. `implied_time_signature` Gets implied time signature of meter. `is_compound` Is true when meter is compound. `is_simple` Is true when meter is simple. `numerator` Gets numerator of meter. `pair` Gets pair of numerator and denominator of meter. `preferred_boundary_depth` Gets preferred boundary depth of meter. `pretty_rtm_format` Gets pretty RTM format of meter. `root_node` Gets root node of meter. `rtm_format` Gets RTM format of meter. `__copy__`(*arguments) Copies Abjad value object. `__eq__`(argument) Is true when argument is a meter with an rtm format equal to that of this meter. `__format__`([format_specification]) Formats meter. `__graph__`(**keywords) Gets Graphviz format of meter. `__hash__`() Hashes meter. `__iter__`() Iterates meter. `__ne__`(argument) Is true when Abjad object does not equal argument. `__repr__`() Gets interpreter representation of Abjad object. `__str__`() Gets string representation of meter.

`Meter.``decrease_durations_monotonically`

Is true when meter divides large primes into collections of `2` and `3` that decrease monotonically. Otherwise false.

An asymmetric meter with beats arranged greatest to least:

```>>> meter = abjad.Meter(
...     (7, 4),
...     decrease_durations_monotonically=True,
...     )
```
```>>> meter.decrease_durations_monotonically
True
```
```>>> print(meter.pretty_rtm_format)
(7/4 (
(3/4 (
1/4
1/4
1/4))
(2/4 (
1/4
1/4))
(2/4 (
1/4
1/4))))
```

This is default beahvior.

The same asymmetric meter with unequal beats arranged least to greatest:

```>>> meter = abjad.Meter(
...     (7, 4),
...     decrease_durations_monotonically=False,
...     )
```
```>>> meter.decrease_durations_monotonically
False
```
```>>> print(meter.pretty_rtm_format)
(7/4 (
(2/4 (
1/4
1/4))
(2/4 (
1/4
1/4))
(3/4 (
1/4
1/4
1/4))))
```

Returns true or false.

`Meter.``denominator`

Gets denominator of meter.

```>>> meter = abjad.Meter((7, 4))
>>> meter.denominator
4
```

Returns positive integer.

`Meter.``depthwise_offset_inventory`

Gets depthwise offset inventory of meter.

```>>> for depth, offsets in enumerate(
...     meter.depthwise_offset_inventory):
...     print(depth, offsets)
...
0 (Offset(0, 1), Offset(7, 4))
1 (Offset(0, 1), Offset(3, 4), Offset(5, 4), Offset(7, 4))
2 (Offset(0, 1), Offset(1, 4), Offset(1, 2), Offset(3, 4), Offset(1, 1), Offset(5, 4), Offset(3, 2), Offset(7, 4))
```

Returns dictionary.

`Meter.``duration`

Gets duration of meter.

```>>> meter.duration
Duration(7, 4)
```

Returns duration.

`Meter.``implied_time_signature`

Gets implied time signature of meter.

```>>> abjad.Meter((4, 4)).implied_time_signature
TimeSignature((4, 4))
```

Returns time signature.

`Meter.``is_compound`

Is true when meter is compound. Otherwise false.

Compound meters written over `4`:

```>>> for numerator in range(1, 13):
...     string = True if meter.is_compound else ''
...     print(str(meter), string)
...
1/4
2/4
3/4
4/4
5/4
6/4 True
7/4
8/4
9/4 True
10/4
11/4
12/4 True
```

Compound meters written over `8`:

```>>> for numerator in range(1, 13):
...     string = True if meter.is_compound else ''
...     print(str(meter), string)
...
1/8
2/8
3/8
4/8
5/8
6/8 True
7/8
8/8
9/8 True
10/8
11/8
12/8 True
```

Compound meters defined equal to those meters with a numerator divisible by `3` (but not equal to `3`).

Returns true or false.

`Meter.``is_simple`

Is true when meter is simple. Otherwise false.

Simple meters written over `4`:

```>>> for numerator in range(1, 13):
...     string = True if meter.is_simple else ''
...     print(str(meter), string)
...
1/4 True
2/4 True
3/4 True
4/4 True
5/4 True
6/4
7/4 True
8/4 True
9/4
10/4 True
11/4 True
12/4
```

Simple meters written over `8`:

```>>> for numerator in range(1, 13):
...     string = True if meter.is_simple else ''
...     print(str(meter), string)
...
1/8 True
2/8 True
3/8 True
4/8 True
5/8 True
6/8
7/8 True
8/8 True
9/8
10/8 True
11/8 True
12/8
```

Simple meters defined equal to those meters with a numerator not divisible by `3`.

Meters with numerator equal to `3` are also defined as simple.

Returns true or false.

`Meter.``numerator`

Gets numerator of meter.

```>>> meter = abjad.Meter((7, 4))
>>> meter.numerator
7
```

Returns positive integer.

`Meter.``pair`

Gets pair of numerator and denominator of meter.

```>>> meter = abjad.Meter((6, 4))
>>> meter.pair
(6, 4)
```

Returns pair.

`Meter.``preferred_boundary_depth`

Gets preferred boundary depth of meter.

No preferred boundary depth:

```>>> abjad.Meter((6, 8)).preferred_boundary_depth is None
True
```

Customized preferred boundary depth:

```>>> meter = abjad.Meter(
...     (6, 8),
...     preferred_boundary_depth=1,
...     )
>>> meter.preferred_boundary_depth
1
```

Used by `mutate().rewrite_meter()`.

Defaults to none.

Set to integer or none.

Returns integer or none.

`Meter.``pretty_rtm_format`

Gets pretty RTM format of meter.

```>>> meter = abjad.Meter((7, 4))
>>> print(meter.pretty_rtm_format)
(7/4 (
(3/4 (
1/4
1/4
1/4))
(2/4 (
1/4
1/4))
(2/4 (
1/4
1/4))))
```

Returns string.

`Meter.``root_node`

Gets root node of meter.

```>>> meter = abjad.Meter((7, 4))
>>> print(format(meter.root_node))
rhythmtreetools.RhythmTreeContainer(
children=(
rhythmtreetools.RhythmTreeContainer(
children=(
rhythmtreetools.RhythmTreeLeaf(
is_pitched=True,
),
rhythmtreetools.RhythmTreeLeaf(
is_pitched=True,
),
rhythmtreetools.RhythmTreeLeaf(
is_pitched=True,
),
),
),
rhythmtreetools.RhythmTreeContainer(
children=(
rhythmtreetools.RhythmTreeLeaf(
is_pitched=True,
),
rhythmtreetools.RhythmTreeLeaf(
is_pitched=True,
),
),
),
rhythmtreetools.RhythmTreeContainer(
children=(
rhythmtreetools.RhythmTreeLeaf(
is_pitched=True,
),
rhythmtreetools.RhythmTreeLeaf(
is_pitched=True,
),
),
),
),
)
```

Returns rhythm tree node.

`Meter.``rtm_format`

Gets RTM format of meter.

```>>> meter = abjad.Meter((7, 4))
>>> meter.rtm_format
'(7/4 ((3/4 (1/4 1/4 1/4)) (2/4 (1/4 1/4)) (2/4 (1/4 1/4))))'
```

Returns string.

## Methods¶

`Meter.``generate_offset_kernel_to_denominator`(denominator, normalize=True)

Generates a dictionary of all offsets in a meter up to denominator.

Keys are the offsets and the values are the normalized weights of those offsets.

```>>> meter = abjad.Meter((4, 4))
>>> kernel = meter.generate_offset_kernel_to_denominator(8)
>>> for offset, weight in sorted(kernel.kernel.items()):
...     print('{!s}\t{!s}'.format(offset, weight))
...
0	3/16
1/8	1/16
1/4	1/8
3/8	1/16
1/2	1/8
5/8	1/16
3/4	1/8
7/8	1/16
1	3/16
```

This is useful for testing how strongly a collection of offsets responds to a given meter.

Returns dictionary.

## Class & static methods¶

static `Meter.``fit_meters`(argument, meters, denominator=32, discard_final_orphan_downbeat=True, maximum_run_length=None, starting_offset=None)

Finds the best-matching sequence of meters for the offsets contained in argument.

```>>> meters = [(3, 4), (4, 4), (5, 4)]
>>> meters = [abjad.Meter(_) for _ in meters]
```

Matches a series of hypothetical `4/4` measures:

```>>> argument = [(0, 4), (4, 4), (8, 4), (12, 4), (16, 4)]
...     argument, meters):
...     print(x.implied_time_signature)
...
4/4
4/4
4/4
4/4
```

Matches a series of hypothetical `5/4` measures:

```>>> argument = [(0, 4), (3, 4), (5, 4), (10, 4), (15, 4), (20, 4)]
...     argument, meters):
...     print(x.implied_time_signature)
...
3/4
4/4
3/4
5/4
5/4
```

Coerces offsets from argument via MetricAccentKernel.count_offsets().

Coerces Meters from meters via MeterList.

Returns list.

## Special methods¶

`(AbjadValueObject).``__copy__`(*arguments)

`Meter.``__eq__`(argument)

Is true when argument is a meter with an rtm format equal to that of this meter. Otherwise false.

Returns true or false.

`Meter.``__format__`(format_specification='')

Formats meter.

Gets storage format of `7/4`:

```>>> meter = abjad.Meter((7, 4))
>>> print(format(meter))
'(7/4 ((3/4 (1/4 1/4 1/4)) (2/4 (1/4 1/4)) (2/4 (1/4 1/4))))'
)
```

Set format_specification to ‘’ or ‘storage’. Interprets ‘’ equal to ‘storage’.

Returns string.

`Meter.``__graph__`(**keywords)

Gets Graphviz format of meter.

Graphs `7/4`:

```>>> meter = abjad.Meter((7, 4))
>>> meter_graph = meter.__graph__()
>>> graph(meter_graph)
```

Returns Graphviz graph.

`Meter.``__hash__`()

Hashes meter.

Returns integer.

`Meter.``__iter__`()

Iterates meter.

Iterates `5/4`:

```>>> meter = abjad.Meter((5, 4))
>>> for x in meter:
...    x
...
(NonreducedFraction(0, 4), NonreducedFraction(1, 4))
(NonreducedFraction(1, 4), NonreducedFraction(2, 4))
(NonreducedFraction(2, 4), NonreducedFraction(3, 4))
(NonreducedFraction(0, 4), NonreducedFraction(3, 4))
(NonreducedFraction(3, 4), NonreducedFraction(4, 4))
(NonreducedFraction(4, 4), NonreducedFraction(5, 4))
(NonreducedFraction(3, 4), NonreducedFraction(5, 4))
(NonreducedFraction(0, 4), NonreducedFraction(5, 4))
```

Yields pairs.

`(AbjadObject).``__ne__`(argument)

Is true when Abjad object does not equal argument. Otherwise false.

Returns true or false.

`(AbjadObject).``__repr__`()

Gets interpreter representation of Abjad object.

Returns string.

`Meter.``__str__`()

Gets string representation of meter.

Gets string representation of meters over `8`:

```>>> for numerator in range(1, 9):