Metrical Cycle Phase Gap Tool

Description

Compute exact modular second-minus-first beat gap; choose the nearest signed representative and resolve an exact half-cycle with positiveTie.

Cyclic musical positions need a cycle length, origin and tie policy. Negative positions and half-cycle differences require careful modular conventions, especially when returning both a local phase and a whole-cycle carry.

Compute exact modular second-minus-first beat gap; choose the nearest signed representative and resolve an exact half-cycle with positiveTie.

When to use this tool

Use Metrical Cycle Phase Gap when you need an explicit rhythmic or tuning-cycle coordinate calculation.

How to use the tool and how it works

Enter firstBeat, secondBeat, beatsPerCycle, positiveTie. Use the units and conventions below.
Run the tool. Correct any format, range, or cross-field input error before interpreting the output.
Read signedBeatGap, antipodal. Inspect antipodal before interpreting the associated values.

Require positive integer beatsPerCycle. Compute exact modular second-minus-first beat gap; choose the nearest signed representative and resolve an exact half-cycle with positiveTie.^[1]

Input field	Meaning and units	Accepted input
firstBeat	First Beat	Required. Safe integer.
secondBeat	Second Beat	Required. Safe integer.
beatsPerCycle	Beats Per Cycle	Required. Safe integer; minimum 1.
positiveTie	Positive Tie	Required. Boolean.

Output field	Interpretation	Returned shape
signedBeatGap	Signed Beat Gap	Required. Safe integer.
antipodal	Antipodal	Required. Boolean.

json

{
  "input": {
    "firstBeat": 7,
    "secondBeat": 1,
    "beatsPerCycle": 8,
    "positiveTie": true
  },
  "output": {
    "signedBeatGap": 2,
    "antipodal": false
  }
}

Limitations and assumptions

Antipodal ties exist only for an even cycle. Beat indexes are supplied and no performance pulse, meter or actual rhythmic similarity is determined.
Inputs must satisfy both the field types and the cross-field conditions above. Invalid input causes an error; a successful false flag or documented placeholder is a different result.
Numeric calculations use binary floating point unless exact decimal-integer arithmetic is explicitly stated. No hidden measurement tolerance or decimal rounding is added; nonfinite or out-of-contract results are rejected. Numeric signed-zero results are exported as zero.

Alternative or Complementary methods

Use the intended musical notation and source annotations to establish the cycle and origin. A numerical wrap cannot determine meter, tuning practice or cultural meaning by itself.

References

Calculation and input contract: ethnomusicology/metrical-cycle-phase-gap — tool.io

Similar or alternative tools

Public Rhythm Cycle Phase Shift
Add with exact integer arithmetic, return nonnegative phase modulo length and floor-based cycle carry as safe numeric integers.
Rhythmic Cycle Beat Phase
Wrap a supplied beat position into a caller-defined rhythmic cycle without identifying a musical meter.