Module:Chord edo approximation

Documentation for this module may be created at Module:Chord edo approximation/doc

-- EDO Approximations Module
-- Calculates EDO approximations for just intervals
-- Usage: {{#invoke:EDO_Approximations|main|interval=3/2|tolerance=9|min_edo=5|max_edo=60}}
local u = require("Module:Utils")
local yesno = require("Module:Yesno")
local p = {}

-- ===== CONFIGURATION VARIABLES =====
local DEFAULT_TOLERANCE = 9.0  -- Relative error tolerance in percent
local DEFAULT_MIN_EDO = 5      -- Minimum EDO to check
local DEFAULT_MAX_EDO = 60     -- Maximum EDO to check
-- ====================================

-- Convert a frequency ratio to cents
local function cents(ratio)
    return 1200 * u.log2(ratio)
end

-- Python-compatible rounding function (banker's rounding)
local function round(x)
    local floor_x = math.floor(x)
    local frac = x - floor_x

    if frac < 0.5 then
        return floor_x
    elseif frac > 0.5 then
        return floor_x + 1
    else
        if floor_x % 2 == 0 then
            return floor_x
        else
            return floor_x + 1
        end
    end
end

-- Find the best approximation of an interval in a given EDO
local function find_best_approximation(ratio_cents, edo)
    local edostep = 1200 / edo
    local best_step = round(ratio_cents / edostep)
    local approximation_cents = best_step * edostep
    local absolute_error = approximation_cents - ratio_cents
    local relative_error = (absolute_error / edostep) * 100

    return best_step, absolute_error, relative_error
end

-- Calculate all EDO approximations within tolerance for a given ratio
local function calculate_edo_approximations(ratio, tolerance, min_edo, max_edo)
    local ratio_cents = cents(ratio)
    local results = {}

    for edo = min_edo, max_edo do
        local steps, abs_error, rel_error = find_best_approximation(ratio_cents, edo)

        if math.abs(rel_error) <= tolerance then
            table.insert(results, {
                edo = edo,
                steps = steps,
                abs_error = abs_error,
                rel_error = rel_error
            })
        end
    end

    return results
end

-- Format a number with sign and 2 decimal places
local function format_error(value)
    if value >= 0 then
        return string.format("+%.2f", value)
    else
        return string.format("%.2f", value)
    end
end

-- Main function to generate the wikitable
function p.main(frame)
    local args = frame.args
    local interval_str = args.interval or args[1]
    local interval_name = args.interval_name
    local tolerance = tonumber(args.tolerance) or DEFAULT_TOLERANCE
    local min_edo = tonumber(args.min_edo) or DEFAULT_MIN_EDO
    local max_edo = tonumber(args.max_edo) or DEFAULT_MAX_EDO

    if not interval_str then
        return "Error: No interval specified"
    end

    local ratio = u.eval_num_arg(interval_str)
    if not ratio then
        return "Error: Invalid interval format (use format like '3/2')"
    end

    local results = calculate_edo_approximations(ratio, tolerance, min_edo, max_edo)

    if #results == 0 then
        return "No edos found within tolerance of " .. tolerance .. "%"
    end

    local output = {}
    table.insert(output, '{| class="wikitable center-all mw-collapsible sortable"')

    local ratio_cents = cents(ratio)
    local display_name = (interval_name and interval_name ~= "") and interval_name or interval_str

    table.insert(output, '|+ style="font-size: 105%;" | '
        .. string.format('Edo&nbsp;approximations&nbsp;for&nbsp;%s&nbsp;(%.2f{{c}})<br /><span style="font-size: 0.75em;">\'\'&le;&nbsp;%dedo,&nbsp;relative&nbsp;error&nbsp;&le;&nbsp;%g%%\'\'</span>',
            display_name, ratio_cents, max_edo, tolerance))
    table.insert(output, '|-')
    table.insert(output, '! class="unsortable" | &nbsp;'
                        .. ' !! Edo'
                        .. ' !! class="unsortable" | Step size'
                        .. ' !! Cents ([[cent|¢]])'
                        .. ' !! Absolute error ([[cent|¢]])'
                        .. ' !! [[Relative interval error|Relative error]] ([[relative cent|%]])')

    for _, result in ipairs(results) do
        local edo_link = string.format("[[%dedo|%d]]", result.edo, result.edo)
        local step_size = string.format("%d\\%d", result.steps, result.edo)
        local approximation_cents = result.steps * (1200 / result.edo)
        local approx_str = string.format("%.2f", approximation_cents)
        local abs_err = format_error(result.abs_error)
        local rel_err = format_error(result.rel_error)

        -- Play button: dyad of root (0) + the interval's step in this edo
        local steps_data = "0," .. tostring(result.steps)
        local play_btn = string.format(
            '<span class="edo-chord-play" data-edo="%d" data-steps="%s" title="Play %s in %dedo" role="button" tabindex="0">▶</span>',
            result.edo, steps_data, interval_str, result.edo)

        table.insert(output, '|-')
        table.insert(output, string.format('| %s || %s || %s || %s || %s || %s',
            play_btn, edo_link, step_size, approx_str, abs_err, rel_err))
    end

    table.insert(output, '|}')

    local result = table.concat(output, '\n')
    if yesno(frame.args["debug"]) == true then
        result = '<syntaxhighlight lang="wikitext">' .. result .. '</syntaxhighlight>'
    end

    return frame:preprocess(result)
end

return p