Beat Cycle Onset Position Wrap Tool

Description

Floor-divide onset-minus-origin for cycleIndex and return nonnegative modular position and phase fraction.

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.

Floor-divide onset-minus-origin for cycleIndex and return nonnegative modular position and phase fraction.

When to use this tool

Use Beat Cycle Onset Position Wrap when you need an explicit rhythmic or tuning-cycle coordinate calculation.

How to use the tool and how it works

Enter onsetPulses, cyclePulses, originPulses. Use the units and conventions below.
Run the tool. Correct any format, range, or cross-field input error before interpreting the output.
Read cycleIndex, position, phaseFraction. Use the output convention below.

Require positive cyclePulses. Floor-divide onset-minus-origin for cycleIndex and return nonnegative modular position and phase fraction.^[1]

Input field	Meaning and units	Accepted input
onsetPulses	Onset Pulses	Required. Finite number.
cyclePulses	Cycle Pulses	Required. Finite number; strictly above 0.
originPulses	Origin Pulses	Required. Finite number.

Output field	Interpretation	Returned shape
cycleIndex	Cycle Index	Required. Safe integer.
position	Position	Required. Finite number.
phaseFraction	Phase Fraction	Required. Finite number.

json

{
  "input": {
    "onsetPulses": 17,
    "cyclePulses": 8,
    "originPulses": 1
  },
  "output": {
    "cycleIndex": 2,
    "position": 0,
    "phaseFraction": 0
  }
}

Limitations and assumptions

Pulse coordinates may be fractional and cycles need not be integer length. The operation does not detect beats, classify meter or edit a recording.
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/beat-cycle-onset-position-wrap — 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.
Metrical Cycle Phase Gap
Compute exact modular second-minus-first beat gap; choose the nearest signed representative and resolve an exact half-cycle with positiveTie.