FlowMap

timelines.FlowMap(source=None, *, id='', resolve=None)

Coordinate transformation map for flow control.

A FlowMap enables bidirectional coordinate conversion between a source timeline (with flow control) and a target (linearized) timeline:

• Source -> Target conversion (1:N, since repeats duplicate coordinates)
• Target -> Source lookup (N:1, always unique)

The single positional argument, source, is polymorphic:

• None — an empty map (no sections). Used by internal construction such as :meth:inverse, which fills the section tables afterwards.
• a :class:Flow — sections are derived from the flow’s measure-count ranges (integer MC space); id defaults to the flow’s mode value.
• a single interval-like descriptor or an iterable of them — sections are built directly from the resulting (start, end) ranges with a cumulative target position, so the played spans concatenate in the target axis and any gaps between them map to nothing. id defaults to "default". Accepted descriptors are region names (resolved through resolve), Region objects, (start, end) coordinate pairs, Timeline objects, and interval events — see :func:~timetoalign.timelines.flow.sections._coerce_intervals.

FlowMap stores sections for efficient lookup:

• _sections: List of FlowMapSection objects
• _target_boundaries: Sorted list of target section starts for binary search

Attributes

Name	Type	Description
flow	Flow | None	The computed Flow, or None for interval-built maps.
id	str	Identifier for this FlowMap.

Methods

Name	Description
fold	Map target coordinate back to source coordinate.
from_qb_sections	Create a FlowMap with QB-space source coordinates.
inverse	Create the inverse FlowMap (target -> source becomes source -> target).
unfold_coordinate	Map source coordinate to target coordinates.

fold

timelines.FlowMap.fold(coord)

Map target coordinate back to source coordinate.

The target timeline has unique coordinates, so this always returns a single value.

Parameters

Name	Type	Description	Default
coord	Fraction | float | int	Coordinate in target timeline.	required

Returns

Name	Type	Description
	Fraction	Coordinate in source timeline.

Raises

Name	Type	Description
	ValueError	If coordinate is outside the flow range.

Examples

>>> # Target coord 6 maps back to source coord 3
>>> flow_map.fold(6)
Fraction(3)

from_qb_sections

timelines.FlowMap.from_qb_sections(flow, qb_sections, *, id='')

Create a FlowMap with QB-space source coordinates.

Unlike the default constructor which derives source coordinates from MC numbers (integers), this factory accepts pre-computed quarterbeat boundaries. This is the correct approach for scores with non-uniform measure durations, where MC-number space != QB-coordinate space.

Parameters

Name	Type	Description	Default
flow	Flow	The computed Flow (retained for metadata and inverse ops).	required
qb_sections	list[tuple[Fraction, Fraction]]	List of (qb_start, qb_end) tuples giving the quarterbeat boundaries of each section in the folded source timeline. Must have the same length as flow.sections.	required
id	str	Optional identifier. Defaults to flow.mode.value.	''

Returns

Name	Type	Description
	'FlowMap'	FlowMap with sections in QB-space.

Raises

Name	Type	Description
	ValueError	If len(qb_sections) != len(flow.sections).

See Also

compute_qb_sections: Computes QB boundaries from a Flow and ScoreFlowController.

inverse

timelines.FlowMap.inverse()

Create the inverse FlowMap (target -> source becomes source -> target).

The inverse FlowMap swaps the source and target coordinate systems. This is useful for attaching to a target timeline to enable tracing back to the original source.

Note

The inverse FlowMap’s unfold_coordinate() returns coordinates in the original source space, which may yield multiple results if the source coord is visited multiple times.

Returns

Name	Type	Description
	'FlowMap'	A new FlowMap with inverted sections.

unfold_coordinate

timelines.FlowMap.unfold_coordinate(coord)

Map source coordinate to target coordinates.

Since a source coordinate may be visited multiple times (due to repeats), this returns a list of all corresponding target coordinates.

Parameters

Name	Type	Description	Default
coord	Fraction | float | int	Coordinate in source timeline.	required

Returns

Name	Type	Description
	list[Fraction]	List of coordinates in target timeline. Empty list if coord
	list[Fraction]	is not within any section.

Examples

>>> # Source coord 3 appears twice due to repeat
>>> flow_map.unfold_coordinate(3)
[Fraction(2), Fraction(6)]